tobogganSe connecter

packages

The Louise packages, each released on its own

Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.

701 lignes · 19090 octetsBrut · Historique
1/// PostgreSQL's wire protocol, version 3.0 (issue gabla108/louise#145): pure encoding
2/// and decoding of messages — no IO here, so every exchange is testable
3/// against recorded byte transcripts.
4///
5/// Frames on the wire: a type byte, a big-endian 32-bit length that
6/// counts itself, then the payload. (`Startup` and `SslRequest` have no
7/// type byte; the answer to `SslRequest` is one byte, not a frame.)
8
9import std/bytes
10import std/int
11import std/list
12import std/result
13
14// ---- outgoing (frontend) ---------------------------------------------------
15
16/// A message the client sends.
17pub type Out
18{ /// Ask whether the server upgrades this connection to TLS.
19 SslRequest
20 /// Protocol 3.0, with the user, the database and the application name.
21, Startup(user: String, database: String, application: String)
22 /// The (cleartext, or hashed) password.
23, Password(String)
24 /// One step of a SCRAM exchange.
25, SaslResponse(Bytes)
26 /// The first SCRAM message names the mechanism: `SASLInitialResponse`.
27, SaslInitialResponse(mechanism: String, data: Bytes)
28 /// The simple query protocol (used for `BEGIN`/`COMMIT`/`ROLLBACK` only).
29, Query(String)
30 /// Name a statement for the SQL. `param_oids` declares parameter types
31 /// (`0` leaves one to the server's inference): a `bytea` parameter is
32 /// declared `17` so its binary form is taken however the SQL reads.
33, Parse(name: String, sql: String, param_oids: List<Int>)
34 /// A portal for a statement with its parameters and the result columns'
35 /// formats wanted (`0` text, `1` binary; empty is all text).
36, Bind(
37 portal: String
38 , statement: String
39 , params: List<BindParam>
40 , result_formats: List<Int>
41 )
42 /// Ask for a statement's description (`RowDescription`).
43, DescribeStatement(String)
44 /// Ask for a portal's description.
45, DescribePortal(String)
46 /// Run a portal (`max_rows` 0 = all rows).
47, Execute(portal: String, max_rows: Int)
48 /// End the extended-protocol exchange.
49, Sync
50 /// Ask for the pending responses now.
51, Flush
52 /// End the connection politely.
53, Terminate
54 /// `CancelRequest` (no type byte): ask the server to stop the query the
55 /// connection with this process id and secret key is running.
56, CancelRequest(process: Int, secret: Int)
57}
58
59/// A `Bind` parameter: its value (`None` is SQL `NULL`) and its format
60/// (`0` text, `1` binary).
61pub type BindParam { BindParam(value: Option<Bytes>, format: Int) }
62
63/// A message as bytes on the wire.
64pub fn encode :: msg: Out -> Bytes
65{
66 match msg
67 { SslRequest ->
68 {
69 let b = be32 (bytes.builder ()) 8
70 bytes.build (be32 b 80877103)
71 }
72 , Startup(user, database, application) ->
73 {
74 let p = bytes.builder ()
75 let p = be32 p 196608 // 3.0
76 let p = cstr p "user"
77 let p = cstr p user
78 let p = cstr p "database"
79 let p = cstr p database
80 let p = cstr p "application_name"
81 let p = cstr p application
82 let p = bytes.append_byte p 0
83 let payload = bytes.build p
84 let b = be32 (bytes.builder ()) (bytes.length payload + 4)
85 bytes.build (bytes.append b payload)
86 }
87 , Password(password) ->
88 frame 112 (bytes.build (cstr (bytes.builder ()) password))
89 , SaslResponse(data) -> frame 112 data
90 , SaslInitialResponse(mechanism, data) ->
91 {
92 let p = cstr (bytes.builder ()) mechanism
93 let p = be32 p (bytes.length data)
94 frame 112 (bytes.build (bytes.append p data))
95 }
96 , Query(sql) -> frame 81 (bytes.build (cstr (bytes.builder ()) sql))
97 , Parse(name, sql, param_oids) ->
98 {
99 let p = cstr (bytes.builder ()) name
100 let p = cstr p sql
101 let p = be16 p (list.length param_oids)
102 frame 80 (bytes.build (list.fold param_oids p parse_param_oid))
103 }
104 , Bind(portal, statement, params, result_formats) ->
105 {
106 let p = cstr (bytes.builder ()) portal
107 let p = cstr p statement
108 let p = be16 p (list.length params)
109 let p = list.fold params p bind_param_format
110 let p = be16 p (list.length params)
111 let p = list.fold params p bind_param
112 let p = be16 p (list.length result_formats)
113 frame 66 (bytes.build (list.fold result_formats p bind_result_format))
114 }
115 , DescribeStatement(name) -> describe 83 name
116 , DescribePortal(name) -> describe 80 name
117 , Execute(portal, max_rows) ->
118 {
119 let p = cstr (bytes.builder ()) portal
120 frame 69 (bytes.build (be32 p max_rows))
121 }
122 , Sync -> frame 83 (bytes.empty ())
123 , Flush -> frame 72 (bytes.empty ())
124 , Terminate -> frame 88 (bytes.empty ())
125 , CancelRequest(process, secret) ->
126 {
127 // No type byte: length 16, the cancel code 80877102, then the key.
128 let b = be32 (bytes.builder ()) 16
129 let b = be32 b 80877102
130 let b = be32 b process
131 bytes.build (be32 b secret)
132 }
133 }
134}
135
136fn bind_param :: p: bytes.Builder param: BindParam -> bytes.Builder
137{
138 match param.value
139 { None -> be32 p (-1)
140 , Some(data) ->
141 {
142 let p = be32 p (bytes.length data)
143 bytes.append p data
144 }
145 }
146}
147
148/// The parameter's format code, before the parameters.
149fn bind_param_format :: p: bytes.Builder param: BindParam -> bytes.Builder
150{
151 be16 p param.format
152}
153
154/// A result column's format code.
155fn bind_result_format :: p: bytes.Builder format: Int -> bytes.Builder
156{
157 be16 p format
158}
159
160/// A parameter's declared type oid in a `Parse` (`0` is "infer it").
161fn parse_param_oid :: p: bytes.Builder oid: Int -> bytes.Builder
162{
163 be32 p oid
164}
165
166/// A Describe frame: the tag, then 'S' or 'P' and the name.
167fn describe :: what: Int name: String -> Bytes
168{
169 let p = bytes.append_byte (bytes.builder ()) what
170 frame 68 (bytes.build (cstr p name))
171}
172
173/// A frame: the tag byte, then the big-endian length (counting itself)
174/// and the payload.
175fn frame :: tag: Int payload: Bytes -> Bytes
176{
177 let b = bytes.append_byte (bytes.builder ()) tag
178 let b = be32 b (bytes.length payload + 4)
179 bytes.build (bytes.append b payload)
180}
181
182/// `n` as 4 big-endian bytes (its low 32 bits).
183fn be32 :: b: bytes.Builder n: Int -> bytes.Builder
184{
185 let n = int.low_bits n 32
186 let b = bytes.append_byte b (int.and (int.shift_right n 24) 255)
187 let b = bytes.append_byte b (int.and (int.shift_right n 16) 255)
188 let b = bytes.append_byte b (int.and (int.shift_right n 8) 255)
189 bytes.append_byte b (int.and n 255)
190}
191
192/// `n` as 2 big-endian bytes.
193fn be16 :: b: bytes.Builder n: Int -> bytes.Builder
194{
195 let b = bytes.append_byte b (int.and (int.shift_right n 8) 255)
196 bytes.append_byte b (int.and n 255)
197}
198
199/// `s` as UTF-8, then a zero byte.
200fn cstr :: b: bytes.Builder s: String -> bytes.Builder
201{
202 bytes.append_byte (bytes.append_string b s) 0
203}
204
205// ---- the TLS negotiation answer ---------------------------------------------
206
207/// What the server answered to `SslRequest`.
208pub type SslAnswer
209{ /// 'S': send the TLS handshake now.
210 Upgrade
211 /// 'N': the server does not do TLS.
212, Plain
213}
214
215/// The one byte that answers `SslRequest` (it is not a frame).
216pub fn ssl_answer :: byte: Int -> Option<SslAnswer>
217{
218 match byte { 83 -> Some(Upgrade), 78 -> Some(Plain), _ -> None }
219}
220
221// ---- incoming (backend) -----------------------------------------------------
222
223/// A message the server sent.
224@derive Eq Debug
225pub type In
226{ /// Authentication succeeded.
227 AuthenticationOk
228 /// The server wants a cleartext password (only over TLS, documented).
229, AuthenticationCleartext
230 /// The server wants SASL, offering these mechanisms.
231, AuthenticationSasl(List<String>)
232 /// A SCRAM step's data (`AuthenticationSASLContinue`).
233, SaslContinue(Bytes)
234 /// The last SCRAM step's data (`AuthenticationSASLFinal`).
235, SaslFinal(Bytes)
236 /// A run-time parameter the server reports (`server_version`, ...).
237, ParameterStatus(name: String, value: String)
238 /// The connection's process id and secret key (for `CancelRequest`).
239, BackendKeyData(process: Int, secret: Int)
240 /// The server is ready for a query, in this transaction state.
241, ReadyForQuery(TxStatus)
242 /// An error, as (field code, text) pairs (`"C"` is the SQLSTATE).
243, ErrorResponse(List<(String, String)>)
244 /// A notice, with the same fields.
245, NoticeResponse(List<(String, String)>)
246, ParseComplete
247, BindComplete
248 /// A row set's columns.
249, RowDescription(List<Field>)
250 /// A statement's parameters' type OIDs (the `Describe` of a statement).
251, ParameterDescription(List<Int>)
252 /// A row (`None` is SQL `NULL`).
253, DataRow(List<Option<Bytes>>)
254 /// The command's tag (`"SELECT 2"`, ...).
255, CommandComplete(String)
256 /// A `NOTIFY`: process id, channel, payload.
257, NotificationResponse(process: Int, channel: String, payload: String)
258 /// A `Query` that returned nothing.
259, EmptyQueryResponse
260 /// A portal with no rows (Describe's answer).
261, NoData
262}
263
264/// A `RowDescription` field.
265@derive Eq Debug
266pub type Field
267{ Field(
268 name: String
269 , table: Int
270 , column: Int
271 , type_oid: Int
272 , size: Int
273 , modifier: Int
274 , format: Int
275 )
276}
277
278/// The transaction state a `ReadyForQuery` reports.
279@derive Eq Debug
280pub type TxStatus
281{ /// 'I': not in a transaction.
282 Idle
283 /// 'T': in a transaction.
284, InTx
285 /// 'E': in a failed transaction (rolled back on `COMMIT`).
286, Failed
287}
288
289/// What [`next`] found in the buffer.
290pub type Next
291{ /// Not all of the message's bytes are there yet.
292 Incomplete
293 /// A message, and the offset just past it.
294, Message(In, Int)
295 /// A frame that cannot be one: the connection is broken.
296, Malformed(String)
297}
298
299/// The most payload a message may declare (1 GiB). A bigger length marks
300/// a broken connection: nothing allocates before the check.
301pub fn max_message :: -> Int
302{
303 1073741824
304}
305
306/// The whole frame's size in bytes (tag, length and payload), read from
307/// a buffer holding at least its first 5 bytes from `at`; `Error` when
308/// the declared length cannot be a frame's.
309pub fn frame_total :: buffer: Bytes at: Int -> Result<Int, String>
310{
311 let length = bytes.read_u32be buffer (at + 1)
312 if length < 4 || length > max_message () + 4
313 {
314 Error("invalid frame length {length}")
315 }
316 else
317 {
318 Ok(length + 1)
319 }
320}
321
322/// The first message in `buffer` at `at`, if its bytes are all there,
323/// and the offset just past it. Nothing is copied: the message's fields
324/// are read in place (a column's value is one fresh `Bytes` each).
325pub fn next :: buffer: Bytes at: Int -> Next
326{
327 if bytes.length buffer - at < 5
328 {
329 Incomplete
330 }
331 else
332 {
333 match frame_total buffer at
334 { Error(e) -> Malformed(e)
335 , Ok
336 ( total
337 ) -> if bytes.length buffer - at < total
338 {
339 Incomplete
340 }
341 else
342 {
343 match parse (bytes.read_u8 buffer at) Cursor(buffer, at + 5, at + total)
344 { Ok(msg) -> Message(msg, at + total), Error(e) -> Malformed(e) }
345 }
346 }
347 }
348}
349
350/// A cursor over a message's payload: `end` is one past its last byte
351/// in `bytes`.
352type Cursor { Cursor(bytes: Bytes, at: Int, end: Int) }
353
354fn parse :: tag: Int cur: Cursor -> Result<In, String>
355{
356 match tag
357 { 82 -> authentication cur // 'R'
358 , 83 -> parameter_status cur // 'S'
359 , 75 -> backend_key_data cur // 'K'
360 , 90 -> ready_for_query cur // 'Z'
361 , 69 -> error_fields cur ErrorResponse_of // 'E'
362 , 78 -> error_fields cur NoticeResponse_of // 'N'
363 , 84 -> row_description cur // 'T'
364 , 116 -> parameter_description cur // 't'
365 , 68 -> data_row cur // 'D'
366 , 67 -> command_complete cur // 'C'
367 , 65 -> notification cur // 'A'
368 , 49 -> plain cur ParseComplete // '1'
369 , 50 -> plain cur BindComplete // '2'
370 , 73 -> plain cur EmptyQueryResponse // 'I'
371 , 110 -> plain cur NoData // 'n'
372 , _ -> Error("a message type the driver does not know: tag {tag}")
373 }
374}
375
376// The constructors as values (for the error fields' two shapes).
377fn ErrorResponse_of :: fields: List<(String, String)> -> In
378{
379 ErrorResponse(fields)
380}
381fn NoticeResponse_of :: fields: List<(String, String)> -> In
382{
383 NoticeResponse(fields)
384}
385
386/// A message with an empty payload.
387fn plain :: cur: Cursor msg: In -> Result<In, String>
388{
389 if cur.at == cur.end
390 {
391 Ok(msg)
392 }
393 else
394 {
395 Error("the message has bytes left over")
396 }
397}
398
399fn authentication :: cur: Cursor -> Result<In, String>
400{
401 use (kind, cur) <- result.try (read_be32 cur)
402 match kind
403 { 0 -> Ok(AuthenticationOk)
404 , 3 -> Ok(AuthenticationCleartext)
405 , 10 -> mechanism_list cur []
406 , 11 -> read_rest cur SaslContinue_of
407 , 12 -> read_rest cur SaslFinal_of
408 , _ -> Error("an authentication method the driver does not know: {kind}")
409 }
410}
411
412fn SaslContinue_of :: data: Bytes -> In
413{
414 SaslContinue(data)
415}
416fn SaslFinal_of :: data: Bytes -> In
417{
418 SaslFinal(data)
419}
420
421/// The list of mechanism names, ended by an empty string.
422fn mechanism_list :: cur: Cursor acc: List<String> -> Result<In, String>
423{
424 use (name, cur) <- result.try (read_cstr cur)
425 if name == ""
426 {
427 Ok(AuthenticationSasl(list.reverse acc))
428 }
429 else
430 {
431 mechanism_list cur [name, ..acc]
432 }
433}
434
435/// The rest of the payload as bytes.
436fn read_rest :: cur: Cursor of: fn(Bytes) -> In -> Result<In, String>
437{
438 Ok(of (bytes.slice cur.bytes cur.at cur.end))
439}
440
441fn parameter_status :: cur: Cursor -> Result<In, String>
442{
443 use (name, cur) <- result.try (read_cstr cur)
444 use (value, _) <- result.try (read_cstr cur)
445 Ok(ParameterStatus(name, value))
446}
447
448fn backend_key_data :: cur: Cursor -> Result<In, String>
449{
450 use (process, cur) <- result.try (read_be32 cur)
451 use (secret, _) <- result.try (read_be32 cur)
452 Ok(BackendKeyData(process, secret))
453}
454
455fn ready_for_query :: cur: Cursor -> Result<In, String>
456{
457 use (status, _) <- result.try (read_u8 cur)
458 match status
459 { 73 -> Ok(ReadyForQuery(Idle))
460 , 84 -> Ok(ReadyForQuery(InTx))
461 , 69 -> Ok(ReadyForQuery(Failed))
462 , _ -> Error("a transaction status the driver does not know: {status}")
463 }
464}
465
466/// The `(code, text)` fields of an error or a notice, ended by a zero
467/// byte.
468fn error_fields ::
469 cur: Cursor
470 of: fn(List<(String, String)>) -> In
471 -> Result<In, String>
472{
473 use (code, cur) <- result.try (read_u8 cur)
474 if code == 0
475 {
476 Ok(of [])
477 }
478 else
479 {
480 error_fields_loop cur of code []
481 }
482}
483
484fn error_fields_loop ::
485 cur: Cursor
486 of: fn(List<(String, String)>) -> In
487 code: Int
488 acc: List<(String, String)>
489 -> Result<In, String>
490{
491 use (text, cur) <- result.try (read_cstr cur)
492 let field = (code_string code, text)
493 use (next_code, cur) <- result.try (read_u8 cur)
494 if next_code == 0
495 {
496 Ok(of (list.reverse [field, ..acc]))
497 }
498 else
499 {
500 error_fields_loop cur of next_code [field, ..acc]
501 }
502}
503
504fn row_description :: cur: Cursor -> Result<In, String>
505{
506 use (count, cur) <- result.try (read_be16 cur)
507 field_list cur count []
508}
509
510/// The parameters' type OIDs: an i16 count, then a be32 each.
511fn parameter_description :: cur: Cursor -> Result<In, String>
512{
513 use (count, cur) <- result.try (read_be16 cur)
514 oid_list cur count []
515}
516
517fn oid_list :: cur: Cursor count: Int acc: List<Int> -> Result<In, String>
518{
519 if count <= 0
520 {
521 Ok(ParameterDescription(list.reverse acc))
522 }
523 else
524 {
525 use (oid, cur) <- result.try (read_be32 cur)
526 oid_list cur (count - 1) [oid, ..acc]
527 }
528}
529
530fn field_list :: cur: Cursor count: Int acc: List<Field> -> Result<In, String>
531{
532 if count <= 0
533 {
534 Ok(RowDescription(list.reverse acc))
535 }
536 else
537 {
538 use (name, cur) <- result.try (read_cstr cur)
539 use (table, cur) <- result.try (read_be32 cur)
540 use (column, cur) <- result.try (read_be16 cur)
541 use (type_oid, cur) <- result.try (read_be32 cur)
542 use (size, cur) <- result.try (read_be16 cur)
543 use (modifier, cur) <- result.try (read_be32 cur)
544 use (format, cur) <- result.try (read_be16 cur)
545 let field = Field(name, table, column, type_oid, size, modifier, format)
546 field_list cur (count - 1) [field, ..acc]
547 }
548}
549
550fn data_row :: cur: Cursor -> Result<In, String>
551{
552 use (count, cur) <- result.try (read_be16 cur)
553 value_list cur count []
554}
555
556fn value_list ::
557 cur: Cursor
558 count: Int
559 acc: List<Option<Bytes>>
560 -> Result<In, String>
561{
562 if count <= 0
563 {
564 Ok(DataRow(list.reverse acc))
565 }
566 else
567 {
568 use (value, cur) <- result.try (read_value cur)
569 value_list cur (count - 1) [value, ..acc]
570 }
571}
572
573/// A column's value: its big-endian length, then its bytes (`-1` is SQL
574/// `NULL`). Fused, so a field is one read, not two.
575fn read_value :: cur: Cursor -> Result<(Option<Bytes>, Cursor), String>
576{
577 if cur.at + 4 > cur.end
578 {
579 Error("the message ends early")
580 }
581 else
582 {
583 let n = bytes.read_u32be cur.bytes cur.at
584 let length = if n >= 2147483648 { n - 4294967296 } else { n }
585 if length == -1
586 {
587 Ok((None, Cursor(..cur, at: cur.at + 4)))
588 }
589 else if length < 0
590 {
591 Error("a column length of {length}")
592 }
593 else if cur.at + 4 + length > cur.end
594 {
595 Error("the message ends early")
596 }
597 else
598 {
599 let value = bytes.slice cur.bytes (cur.at + 4) (cur.at + 4 + length)
600 Ok((Some(value), Cursor(..cur, at: cur.at + 4 + length)))
601 }
602 }
603}
604
605fn command_complete :: cur: Cursor -> Result<In, String>
606{
607 use (tag, _) <- result.try (read_cstr cur)
608 Ok(CommandComplete(tag))
609}
610
611fn notification :: cur: Cursor -> Result<In, String>
612{
613 use (process, cur) <- result.try (read_be32 cur)
614 use (channel, cur) <- result.try (read_cstr cur)
615 use (payload, _) <- result.try (read_cstr cur)
616 Ok(NotificationResponse(process, channel, payload))
617}
618
619// ---- the cursor's reads -----------------------------------------------------
620
621// Every read checks its bounds against the payload's end first, then
622// reads in place: no slice, no list, no allocation.
623
624fn read_u8 :: cur: Cursor -> Result<(Int, Cursor), String>
625{
626 if cur.at >= cur.end
627 {
628 Error("the message ends early")
629 }
630 else
631 {
632 Ok((bytes.read_u8 cur.bytes cur.at, Cursor(..cur, at: cur.at + 1)))
633 }
634}
635
636fn read_be16 :: cur: Cursor -> Result<(Int, Cursor), String>
637{
638 if cur.at + 2 > cur.end
639 {
640 Error("the message ends early")
641 }
642 else
643 {
644 Ok((bytes.read_u16be cur.bytes cur.at, Cursor(..cur, at: cur.at + 2)))
645 }
646}
647
648/// The big-endian 32-bit integer, signed.
649fn read_be32 :: cur: Cursor -> Result<(Int, Cursor), String>
650{
651 if cur.at + 4 > cur.end
652 {
653 Error("the message ends early")
654 }
655 else
656 {
657 let n = bytes.read_u32be cur.bytes cur.at
658 let n = if n >= 2147483648 { n - 4294967296 } else { n }
659 Ok((n, Cursor(..cur, at: cur.at + 4)))
660 }
661}
662
663/// The next zero-terminated string.
664fn read_cstr :: cur: Cursor -> Result<(String, Cursor), String>
665{
666 match find_zero cur.bytes cur.at cur.end
667 { None -> Error("the string is not terminated")
668 , Some(end) ->
669 {
670 match bytes.to_string_range cur.bytes cur.at (end - cur.at)
671 { Ok(s) -> Ok((s, Cursor(..cur, at: end + 1)))
672 , Error(e) -> Error("the string is not UTF-8: {e}")
673 }
674 }
675 }
676}
677
678fn find_zero :: b: Bytes at: Int end: Int -> Option<Int>
679{
680 if at >= end
681 {
682 None
683 }
684 else
685 {
686 let byte = bytes.read_u8 b at
687 if byte == 0
688 {
689 Some(at)
690 }
691 else
692 {
693 find_zero b (at + 1) end
694 }
695 }
696}
697
698fn code_string :: code: Int -> String
699{
700 match bytes.to_string (bytes.from_list [code]) { Ok(s) -> s, Error(_) -> "?" }
701}