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.

1093 lignes · 30819 octetsBrut · Historique
1/// A connection to PostgreSQL: one actor owns the socket and the protocol
2/// state, so a connection is never used by two callers at once (issue
3/// gabla108/louise#145 §3). Parameters travel as `$1`, never inside the SQL text.
4///
5/// The wire is the extended query protocol (`Parse`/`Bind`/`Describe`/
6/// `Execute`/`Sync`); authentication is `trust`, cleartext password (over
7/// TLS or to localhost only) or SCRAM-SHA-256 (scram.lse).
8
9import std/actor.{Continue, Stop}
10import std/base64
11import std/bytes
12import std/dec.{type Dec}
13import std/dict.{type Dict}
14import std/ffi.{type Resource}
15import std/list
16import std/net.{type TcpStream}
17import std/option
18import std/process.{type Pid, type Subject, type proc}
19import std/random.{type random}
20import std/result
21import std/string
22import std/time.{type Timestamp}
23import std/tls.{type TlsStream}
24
25import binary
26import config.{type Config, Disable, Require}
27import numeric
28import protocol
29import scram
30import uuid
31
32/// What a call failed with.
33@derive Debug
34pub type Error
35{ /// The socket or the TLS layer.
36 Io(String)
37 /// The server refused, with its fields (the `"C"` field is the
38 /// SQLSTATE, `"M"` the message).
39, Server(List<(String, String)>)
40 /// The driver itself: the protocol was violated, or authentication
41 /// could not run.
42, Driver(String)
43}
44
45/// A parameter's value; SQL `NULL` is `Null`. A value whose type a binary
46/// codec exists for is declared in the `Parse` and binds in binary
47/// (`Bytea` is the raw bytes, no `\x` form); the rest go in text.
48@derive Eq Debug
49pub type Value
50{ Null
51, Integer(Int)
52, Real(Float)
53, Boolean(Bool)
54, Text(String)
55, Bytea(Bytes)
56, Uuid(uuid.Uuid)
57, Timestamptz(time.Timestamp)
58 /// PostgreSQL `NUMERIC` (OID 1700): a fixed-point decimal (ADR 0070).
59, Decimal(Dec)
60}
61
62/// A row set's columns (the protocol's fields) and rows.
63pub type QueryResult
64{ QueryResult(columns: List<protocol.Field>, rows: List<Row>, tag: String) }
65
66/// A row: its columns and its values in text format (`None` is `NULL`).
67pub type Row { Row(columns: List<protocol.Field>, values: List<Option<Bytes>>) }
68
69/// The SQLSTATE of a server error, if it has one.
70pub fn sqlstate :: e: Error -> Option<String>
71{
72 match e { Server(fields) -> field fields "C", _ -> None }
73}
74
75/// The server's message for a server error, or the text otherwise.
76pub fn message :: e: Error -> String
77{
78 match e
79 { Io(m) -> m
80 , Server(fields) -> option.unwrap_or (field fields "M") (debug_fields fields)
81 , Driver(m) -> m
82 }
83}
84
85fn field :: fields: List<(String, String)> name: String -> Option<String>
86{
87 match fields
88 { [] -> None
89 , [(n, v), ..rest] -> if n == name { Some(v) } else { field rest name }
90 }
91}
92
93fn debug_fields :: fields: List<(String, String)> -> String
94{
95 "{fields:?}"
96}
97
98// ---- connecting -------------------------------------------------------------
99
100/// The socket: plain TCP or TLS.
101type Conn { Tcp(Resource<TcpStream>), Tls(Resource<TlsStream>) }
102
103/// A connection's socket after the handshake: the connection, the read
104/// buffer, the settings, and the backend key data (for `CancelRequest`).
105pub type Socket
106{ Socket(
107 conn: Conn
108 , buffer: Bytes
109 , host: String
110 , port: Int
111 , backend: Option<(Int, Int)>
112 )
113}
114
115/// Connect and authenticate, without the actor: the socket, for the
116/// connection actor (`connect`) or a listener (`listen`).
117pub fn connect_socket :: cfg: Config -> Result<Socket, Error> / <io, random>
118{
119 use tcp <- result.try (net.connect cfg.host cfg.port |> result.map_error Io)
120 use conn <- result.try (maybe_tls tcp cfg)
121 use (buffer, backend) <- result.try (handshake conn cfg)
122 Ok(Socket(conn, buffer, cfg.host, cfg.port, backend))
123}
124
125/// Connect and authenticate. The connection is an actor; stop it with
126/// `close`.
127pub fn connect ::
128 cfg: Config
129 -> Result<Subject<Msg>, Error> / <io, proc, random>
130{
131 use socket <- result.try (connect_socket cfg)
132 Ok(connect_over socket)
133}
134
135/// The connection actor over an already-authenticated socket.
136pub fn connect_over :: socket: Socket -> Subject<Msg> / <proc>
137{
138 actor.start (state_of socket) fn state msg { on_message state msg }
139}
140
141fn state_of :: socket: Socket -> State
142{
143 let Socket(conn, buffer, host, port, backend) = socket
144 State(conn, buffer, 0, host, port, backend, dict.empty (), 1)
145}
146
147/// TLS if the mode wants it: `SslRequest`, then the handshake if the
148/// server agrees. `Require` refuses a plain answer.
149fn maybe_tls ::
150 tcp: Resource<TcpStream>
151 cfg: Config
152 -> Result<Conn, Error> / <io>
153{
154 match cfg.tls
155 { Disable -> Ok(Tcp(tcp))
156 , mode ->
157 {
158 use _ <-
159 result.try
160 ( net.write tcp (protocol.encode protocol.SslRequest)
161 |> result.map_error Io
162 )
163 use answer <- result.try (net.read tcp 1 |> result.map_error Io)
164 match bytes.to_list answer
165 { [byte] -> match protocol.ssl_answer byte
166 { Some(protocol.Upgrade) ->
167 {
168 use tls_config <-
169 result.try
170 (tls.config (tls.defaults ()) |> result.map_error tls_io)
171 use stream <-
172 result.try
173 (tls.connect tcp cfg.host tls_config |> result.map_error tls_io)
174 Ok(Tls(stream))
175 }
176 , Some(protocol.Plain) -> match mode
177 { Require ->
178 Error(Driver("the server does not do TLS (sslmode=require)"))
179 , _ -> Ok(Tcp(tcp))
180 }
181 , None -> Error(Driver("a byte that is not an SSL answer"))
182 }
183 , _ -> Error(Io("the server closed the connection"))
184 }
185 }
186 }
187}
188
189fn tls_io :: e: tls.TlsError -> Error
190{
191 Io("TLS: {e}")
192}
193
194/// The startup message, then authenticate until `ReadyForQuery`. The
195/// buffer's leftover bytes come back (the server sent nothing extra in
196/// practice), with the backend key data if it arrived.
197fn handshake ::
198 conn: Conn
199 cfg: Config
200 -> Result<(Bytes, Option<(Int, Int)>), Error> / <io, random>
201{
202 use _ <-
203 result.try
204 (write_msg conn protocol.Startup(cfg.user, cfg.database, cfg.application))
205 use (buffer, at, backend) <-
206 result.try (auth_loop conn (bytes.empty ()) 0 cfg None)
207 Ok((bytes.slice buffer at (bytes.length buffer), backend))
208}
209
210fn auth_loop ::
211 conn: Conn
212 buffer: Bytes
213 at: Int
214 cfg: Config
215 backend: Option<(Int, Int)>
216 -> Result<(Bytes, Int, Option<(Int, Int)>), Error> / <io, random>
217{
218 use (msg, buffer, at) <- result.try (read_message conn buffer at)
219 match msg
220 { protocol.AuthenticationOk -> auth_loop conn buffer at cfg backend
221 , protocol.AuthenticationCleartext ->
222 {
223 use _ <- result.try (cleartext_password conn cfg)
224 auth_loop conn buffer at cfg backend
225 }
226 , protocol.AuthenticationSasl(mechanisms) ->
227 {
228 use (buffer, at) <-
229 result.try (scram_exchange conn buffer at cfg mechanisms)
230 auth_loop conn buffer at cfg backend
231 }
232 , protocol.ParameterStatus(..) -> auth_loop conn buffer at cfg backend
233 , protocol.BackendKeyData(pid, secret) ->
234 auth_loop conn buffer at cfg Some((pid, secret))
235 , protocol.NoticeResponse(_) -> auth_loop conn buffer at cfg backend
236 , protocol.ReadyForQuery(_) -> Ok((buffer, at, backend))
237 , protocol.ErrorResponse(fields) -> Error(Server(fields))
238 , _ -> Error(Driver("an unexpected message during startup"))
239 }
240}
241
242/// A cleartext password, over TLS or to localhost only.
243fn cleartext_password :: conn: Conn cfg: Config -> Result<(), Error> / <io>
244{
245 let safe = match conn
246 { Tls(_) -> True
247 , Tcp(_) ->
248 cfg.host == "localhost" || cfg.host == "127.0.0.1" || cfg.host == "::1"
249 }
250 if !safe
251 {
252 Error( Driver( "the server wants a cleartext password, which needs TLS or localhost"
253 )
254 )
255 }
256 else
257 {
258 use password <-
259 result.try
260 ( option.to_result
261 cfg.password
262 "the server wants a password; the URL has none"
263 |> result.map_error Driver
264 )
265 write_msg conn protocol.Password(password)
266 }
267}
268
269/// SCRAM-SHA-256, if the server offers it.
270fn scram_exchange ::
271 conn: Conn
272 buffer: Bytes
273 at: Int
274 cfg: Config
275 mechanisms: List<String>
276 -> Result<(Bytes, Int), Error> / <io, random>
277{
278 if !list.any mechanisms fn m { m == "SCRAM-SHA-256" }
279 {
280 Error(Driver("the server offers no SCRAM-SHA-256"))
281 }
282 else
283 {
284 use password <-
285 result.try
286 ( option.to_result
287 cfg.password
288 "the server wants a password; the URL has none"
289 |> result.map_error Driver
290 )
291 let nonce = base64.encode (random.bytes 18)
292 let (state, first) = scram.client_first nonce
293 use _ <-
294 result.try
295 (write_msg conn protocol.SaslInitialResponse("SCRAM-SHA-256", first))
296 use (msg, buffer, at) <- result.try (read_message conn buffer at)
297 use (state, reply) <- result.try (scram_continue msg state password)
298 use _ <-
299 result.try (write_msg conn protocol.SaslResponse(bytes.from_string reply))
300 use (msg, buffer, at) <- result.try (read_message conn buffer at)
301 use _ <- result.try (scram_final msg state)
302 Ok((buffer, at))
303 }
304}
305
306/// The server-first step: the client-final message and the state the
307/// final step verifies with.
308fn scram_continue ::
309 msg: protocol.In
310 state: scram.Scram
311 password: String
312 -> Result<(scram.Scram, String), Error>
313{
314 match msg
315 { protocol.SaslContinue(data) -> match bytes.to_string data
316 { Ok(text) ->
317 scram.client_final state password text |> result.map_error Driver
318 , Error(e) -> Error(Driver("SASL data is not UTF-8: {e}"))
319 }
320 , protocol.ErrorResponse(fields) -> Error(Server(fields))
321 , _ -> Error(Driver("expected a SASL continuation"))
322 }
323}
324
325/// The server-final step: verify the server's signature (it proves the
326/// server knew the password too).
327fn scram_final :: msg: protocol.In state: scram.Scram -> Result<(), Error>
328{
329 match msg
330 { protocol.SaslFinal(data) -> match bytes.to_string data
331 { Ok(text) -> scram.verify_server state text |> result.map_error Driver
332 , Error(e) -> Error(Driver("SASL data is not UTF-8: {e}"))
333 }
334 , protocol.ErrorResponse(fields) -> Error(Server(fields))
335 , _ -> Error(Driver("expected a SASL final"))
336 }
337}
338
339// ---- the query exchange -------------------------------------------------------
340
341/// The actor's state: the socket, the read buffer and the offset parsing
342/// resumes at, the settings, the backend key data (for `CancelRequest`),
343/// and the statements prepared on this connection, by SQL text (issue
344/// gabla108/louise#145 §1).
345type State
346{ State(
347 conn: Conn
348 , buffer: Bytes
349 , at: Int
350 , host: String
351 , port: Int
352 , backend: Option<(Int, Int)>
353 , prepared: Dict<String, Prepared>
354 , next_statement: Int
355 )
356}
357
358/// A statement prepared on this connection: its name, its parameters'
359/// type OIDs, and its result columns.
360type Prepared
361{ Prepared(name: String, param_oids: List<Int>, fields: List<protocol.Field>) }
362
363/// The connection's messages.
364pub type Msg
365{ DoQuery(
366 sql: String
367 , params: List<Value>
368 , reply: Subject<Result<QueryResult, Error>>
369 )
370 /// A liveness check: a bare `Sync`, answered by `ReadyForQuery` — the
371 /// cheapest round trip the protocol has. It fails when the connection
372 /// is not idle (a pooled connection has no transaction open). The actor
373 /// stops after a failed ping: the connection is not to be trusted.
374, Ping(reply: Subject<Result<(), Error>>)
375, Close(reply: Subject<()>)
376}
377
378fn on_message :: state: State msg: Msg -> actor.Next<State> / <io, proc>
379{
380 match msg
381 { DoQuery(sql, params, reply) ->
382 {
383 let (res, state) = run_query state sql params
384 process.send reply res
385 Continue(state)
386 }
387 , Ping(reply) ->
388 {
389 let (res, buffer, at) = ping state.conn state.buffer state.at
390 process.send reply res
391 match res
392 { Ok(()) -> Continue(State(..state, buffer: buffer, at: at))
393 , Error(_) ->
394 {
395 close_conn state.conn
396 Stop
397 }
398 }
399 }
400 , Close(reply) ->
401 {
402 close_conn state.conn
403 process.send reply ()
404 Stop
405 }
406 }
407}
408
409/// A bare `Sync`, then read to `ReadyForQuery`, which must report the
410/// connection idle: a pooled connection has no transaction open.
411fn ping ::
412 conn: Conn
413 buffer: Bytes
414 at: Int
415 -> (Result<(), Error>, Bytes, Int) / <io>
416{
417 match write_msg conn protocol.Sync
418 { Error(e) -> (Error(e), bytes.empty (), 0)
419 , Ok(()) -> ping_read conn buffer at None
420 }
421}
422
423fn ping_read ::
424 conn: Conn
425 buffer: Bytes
426 at: Int
427 error: Option<Error>
428 -> (Result<(), Error>, Bytes, Int) / <io>
429{
430 match read_message conn buffer at
431 { Error(e) -> (Error(e), bytes.empty (), 0)
432 , Ok((msg, buffer, at)) -> match msg
433 { protocol.ReadyForQuery(status) -> match error
434 { Some(e) -> (Error(e), buffer, at)
435 , None -> match status
436 { protocol.Idle -> (Ok(()), buffer, at)
437 , _ -> ( Error(Driver("the connection has a transaction open"))
438 , buffer
439 , at
440 )
441 }
442 }
443 , protocol.ErrorResponse(fields) ->
444 ping_read conn buffer at Some(Server(fields))
445 , _ -> ping_read conn buffer at error
446 }
447 }
448}
449
450/// A query: the statement is prepared once per connection (Parse +
451/// Describe, one exchange), then Bind + Execute. Parameters travel as
452/// `$1`, binary per type where a codec exists (binary.lse).
453fn run_query ::
454 state: State
455 sql: String
456 params: List<Value>
457 -> (Result<QueryResult, Error>, State) / <io>
458{
459 match prepare state sql params
460 { (Error(e), state) -> (Error(e), state)
461 , ( Ok(prep)
462 , state
463 ) -> if list.length params != list.length prep.param_oids
464 {
465 ( Error( Driver( "the statement takes {list.length prep.param_oids} parameters, got {list.length params}"
466 )
467 )
468 , state
469 )
470 }
471 else
472 {
473 let encoded = encode_params params prep.param_oids []
474 let formats =
475 list.map
476 prep.fields
477 fn f
478 {
479 if binary_known f.type_oid
480 {
481 1
482 }
483 else
484 {
485 0
486 }
487 }
488 let out =
489 [ protocol.Bind("", prep.name, encoded, formats)
490 , protocol.DescribePortal("")
491 , protocol.Execute("", 0)
492 , protocol.Sync
493 ]
494 match conn_write
495 state.conn
496 (bytes.concat_all (list.map out protocol.encode))
497 { Error(e) -> (Error(e), state)
498 , Ok(()) ->
499 {
500 let (res, buffer, at) =
501 collect state.conn state.buffer state.at [] [] "" None
502 (res, State(..state, buffer: buffer, at: at))
503 }
504 }
505 }
506 }
507}
508
509/// The statement prepared on this connection: from the cache, or by Parse
510/// + Describe (one exchange). The parameters' types are declared where the
511/// value names one unambiguously (`declared_oid`), so a `Bytea` binds in
512/// binary whatever the SQL context infers.
513fn prepare ::
514 state: State
515 sql: String
516 params: List<Value>
517 -> (Result<Prepared, Error>, State) / <io>
518{
519 match dict.get state.prepared sql
520 { Some(prep) -> (Ok(prep), state)
521 , None ->
522 {
523 let name = "q{state.next_statement}"
524 let out =
525 [ protocol.Parse(name, sql, list.map params declared_oid)
526 , protocol.DescribeStatement(name)
527 , protocol.Sync
528 ]
529 match conn_write
530 state.conn
531 (bytes.concat_all (list.map out protocol.encode))
532 { Error(e) -> (Error(e), state)
533 , Ok
534 ( ()
535 ) -> match read_describe state.conn state.buffer state.at [] [] None
536 { (Error(e), buffer, at) -> ( Error(e)
537 , State(..state, buffer: buffer, at: at)
538 )
539 , (Ok((oids, fields)), buffer, at) ->
540 {
541 let prep = Prepared(name, oids, fields)
542 ( Ok(prep)
543 , State( ..state
544 , buffer: buffer
545 , at: at
546 , prepared: dict.insert state.prepared sql prep
547 , next_statement: state.next_statement + 1
548 )
549 )
550 }
551 }
552 }
553 }
554 }
555}
556
557/// Read the answers to Parse + Describe until `ReadyForQuery`: the
558/// parameters' type OIDs and the result columns.
559fn read_describe ::
560 conn: Conn
561 buffer: Bytes
562 at: Int
563 param_oids: List<Int>
564 fields: List<protocol.Field>
565 error: Option<Error>
566 -> (Result<(List<Int>, List<protocol.Field>), Error>, Bytes, Int) / <io>
567{
568 match read_message conn buffer at
569 { Error(e) -> (Error(e), bytes.empty (), 0)
570 , Ok((msg, buffer, at)) -> match msg
571 { protocol.ParameterDescription(oids) ->
572 read_describe conn buffer at oids fields error
573 , protocol.RowDescription(f) ->
574 read_describe conn buffer at param_oids f error
575 , protocol.NoData -> read_describe conn buffer at param_oids [] error
576 , protocol.ErrorResponse(f) ->
577 read_describe conn buffer at param_oids fields Some(Server(f))
578 , protocol.ReadyForQuery(_) -> match error
579 { Some(e) -> (Error(e), buffer, at)
580 , None -> (Ok((param_oids, fields)), buffer, at)
581 }
582 , _ -> read_describe conn buffer at param_oids fields error
583 }
584 }
585}
586
587fn collect ::
588 conn: Conn
589 buffer: Bytes
590 at: Int
591 columns: List<protocol.Field>
592 rows: List<Row>
593 tag: String
594 error: Option<Error>
595 -> (Result<QueryResult, Error>, Bytes, Int) / <io>
596{
597 match read_message conn buffer at
598 { Error(e) -> (Error(e), bytes.empty (), 0)
599 , Ok((msg, buffer, at)) -> match msg
600 { protocol.RowDescription(fields) ->
601 collect conn buffer at fields rows tag error
602 , protocol.DataRow(values) ->
603 collect conn buffer at columns [Row(columns, values), ..rows] tag error
604 , protocol.CommandComplete(t) -> collect conn buffer at columns rows t error
605 , protocol.ErrorResponse(fields) ->
606 collect conn buffer at columns rows tag Some(Server(fields))
607 , protocol.ReadyForQuery(_) -> match error
608 { Some(e) -> (Error(e), buffer, at)
609 , None -> (Ok(QueryResult(columns, list.reverse rows, tag)), buffer, at)
610 }
611 , _ ->
612 collect
613 conn
614 buffer
615 at
616 columns
617 rows
618 tag
619 error // ParseComplete, BindComplete, NoData, ...
620 }
621 }
622}
623
624// ---- the wire ----------------------------------------------------------------
625
626/// One full message, reading more as needed; the answer is the message,
627/// the buffer and the offset parsing resumes at. A message already whole
628/// in the buffer is parsed in place (nothing is copied); one that
629/// straddles reads pays once for moving its tail into a builder.
630fn read_message ::
631 conn: Conn
632 buffer: Bytes
633 at: Int
634 -> Result<(protocol.In, Bytes, Int), Error> / <io>
635{
636 match protocol.next buffer at
637 { protocol.Message(msg, past) -> if past == bytes.length buffer
638 {
639 Ok((msg, bytes.empty (), 0))
640 }
641 else
642 {
643 Ok((msg, buffer, past))
644 }
645 , protocol.Malformed(e) -> Error(Driver(e))
646 , protocol.Incomplete ->
647 fill conn (bytes.slice buffer at (bytes.length buffer))
648 }
649}
650
651/// The rest of a message that straddles reads: chunks accumulate in a
652/// builder (appending does not copy what was appended before) until the
653/// frame is whole.
654fn fill ::
655 conn: Conn
656 tail: Bytes
657 -> Result<(protocol.In, Bytes, Int), Error> / <io>
658{
659 use tail <- result.try (fill_header conn tail)
660 use total <-
661 result.try (protocol.frame_total tail 0 |> result.map_error Driver)
662 let b =
663 bytes.append (bytes.builder_with_capacity (bytes.length tail + 65536)) tail
664 fill_loop conn b (bytes.length tail) total
665}
666
667/// `tail` grown to a whole frame header (5 bytes).
668fn fill_header :: conn: Conn tail: Bytes -> Result<Bytes, Error> / <io>
669{
670 if bytes.length tail >= 5
671 {
672 Ok(tail)
673 }
674 else
675 {
676 use chunk <- result.try (conn_read conn 65536)
677 if bytes.length chunk == 0
678 {
679 Error(Io("the server closed the connection"))
680 }
681 else
682 {
683 fill_header conn (bytes.concat tail chunk)
684 }
685 }
686}
687
688fn fill_loop ::
689 conn: Conn
690 b: bytes.Builder
691 have: Int
692 total: Int
693 -> Result<(protocol.In, Bytes, Int), Error> / <io>
694{
695 if have >= total
696 {
697 let buffer = bytes.build b
698 match protocol.next buffer 0
699 { protocol.Message(msg, past) -> Ok((msg, buffer, past))
700 , protocol.Malformed(e) -> Error(Driver(e))
701 , protocol.Incomplete ->
702 Error( Driver( "protocol: a whole frame did not parse (a bug in the codec)"
703 )
704 )
705 }
706 }
707 else
708 {
709 use chunk <- result.try (conn_read conn 65536)
710 if bytes.length chunk == 0
711 {
712 Error(Io("the server closed the connection"))
713 }
714 else
715 {
716 fill_loop conn (bytes.append b chunk) (have + bytes.length chunk) total
717 }
718 }
719}
720
721fn write_msg :: conn: Conn msg: protocol.Out -> Result<(), Error> / <io>
722{
723 conn_write conn (protocol.encode msg)
724}
725
726fn conn_read :: conn: Conn max: Int -> Result<Bytes, Error> / <io>
727{
728 match conn
729 { Tcp(c) -> net.read c max |> result.map_error Io
730 , Tls(c) -> tls.read c max |> result.map_error tls_io
731 }
732}
733
734fn conn_write :: conn: Conn data: Bytes -> Result<(), Error> / <io>
735{
736 match conn
737 { Tcp(c) -> net.write c data |> result.map_error Io
738 , Tls(c) -> tls.write c data |> result.map_error tls_io
739 }
740}
741
742fn close_conn :: conn: Conn -> () / <io>
743{
744 let _ = conn_write conn (protocol.encode protocol.Terminate)
745 match conn { Tcp(c) -> net.close c, Tls(c) -> tls.close c }
746}
747
748// ---- LISTEN/NOTIFY (a dedicated connection, outside any pool) -----------------
749
750/// A notification from a `LISTEN`ed channel.
751@derive Debug
752pub type Notification
753{ Notification(channel: String, payload: String, process: Int) }
754
755/// Listen on `channel`; each of its notifications goes to `subscriber`.
756/// The listener is one dedicated connection (outside any pool): an actor
757/// parked on the socket. Stop it with `process.kill` (a supervisor
758/// restarts it: it re-`LISTEN`s). Quoting: the channel is an identifier,
759/// sent as `LISTEN "channel"`.
760pub fn listen ::
761 cfg: Config
762 channel: String
763 subscriber: Subject<Notification>
764 -> Result<Pid, Error> / <io, proc, random>
765{
766 use socket <- result.try (connect_socket cfg)
767 let Socket(conn, buffer, ..) = socket
768 use (buffer, at) <- result.try (listen_command conn buffer 0 channel)
769 Ok(process.spawn fn { listen_serve conn buffer at channel subscriber })
770}
771
772/// `LISTEN "channel"`, answered by `CommandComplete` and `ReadyForQuery`.
773fn listen_command ::
774 conn: Conn
775 buffer: Bytes
776 at: Int
777 channel: String
778 -> Result<(Bytes, Int), Error> / <io>
779{
780 use _ <- result.try (write_msg conn protocol.Query("LISTEN {quoted channel}"))
781 drain_until_ready conn buffer at
782}
783
784/// An identifier in double quotes (inner quotes doubled).
785fn quoted :: name: String -> String
786{
787 "\""
788 <> string.concat
789 ( list.map
790 (string.chars name)
791 fn c
792 {
793 if c == "\""
794 {
795 "\"\""
796 }
797 else
798 {
799 c
800 }
801 }
802 )
803 <> "\""
804}
805
806/// Read until `ReadyForQuery` (the simple query protocol's end).
807fn drain_until_ready ::
808 conn: Conn
809 buffer: Bytes
810 at: Int
811 -> Result<(Bytes, Int), Error> / <io>
812{
813 use (msg, buffer, at) <- result.try (read_message conn buffer at)
814 match msg
815 { protocol.ReadyForQuery(_) -> Ok((buffer, at))
816 , protocol.ErrorResponse(fields) -> Error(Server(fields))
817 , _ -> drain_until_ready conn buffer at
818 }
819}
820
821/// Read forever: notifications for our channel go to the subscriber. A
822/// broken socket stops the listener.
823fn listen_serve ::
824 conn: Conn
825 buffer: Bytes
826 at: Int
827 channel: String
828 subscriber: Subject<Notification>
829 -> () / <io, proc>
830{
831 match read_message conn buffer at
832 { Error(_) -> ()
833 , Ok((msg, buffer, at)) ->
834 {
835 match msg
836 { protocol.NotificationResponse(source, ch, payload) ->
837 {
838 if ch == channel
839 {
840 process.send subscriber Notification(ch, payload, source)
841 }
842 }
843 , _ -> ()
844 }
845 listen_serve conn buffer at channel subscriber
846 }
847 }
848}
849
850// ---- parameters ---------------------------------------------------------------
851
852/// Parameters encoded per their inferred types: binary where a codec
853/// exists for the OID (binary.lse), text otherwise. `Null` has no format.
854fn encode_params ::
855 params: List<Value>
856 oids: List<Int>
857 acc: List<protocol.BindParam>
858 -> List<protocol.BindParam>
859{
860 match (params, oids)
861 { ([], _) -> list.reverse acc
862 , ([param, ..rest], [oid, ..rest_oids]) ->
863 encode_params rest rest_oids [encode_one param oid, ..acc]
864 , (_, []) -> list.reverse acc // the arity check in run_query came first
865 }
866}
867
868fn encode_one :: value: Value oid: Int -> protocol.BindParam
869{
870 match value
871 { Null -> protocol.BindParam(None, 0)
872 , Integer(n) -> match oid
873 { 21 -> binary_param (binary.be16 n) // int2
874 , 23 -> binary_param (binary.be32 n) // int4
875 , 20 -> binary_param (binary.be64 n) // int8
876 , _ -> text_param "{n}"
877 }
878 , Real(f) -> match oid
879 { 700 -> binary_param (binary.f32 f) // float4
880 , 701 -> binary_param (binary.f64 f) // float8
881 , _ -> text_param "{f}"
882 }
883 , Boolean
884 ( b
885 ) -> if oid == 16
886 {
887 binary_param (bytes.from_list [if b { 1 } else { 0 }])
888 }
889 else
890 {
891 text_param (show value)
892 }
893 , Text(s) -> text_param s
894 , Bytea(b) -> if oid == 17
895 {
896 binary_param b // raw, no `\x` form
897 }
898 else
899 {
900 text_param (show value)
901 }
902 , Uuid(id) -> if oid == 2950
903 {
904 binary_param (uuid.to_bytes id)
905 }
906 else
907 {
908 text_param (show value)
909 }
910 , Timestamptz(t) -> if oid == 1184
911 {
912 binary_param (binary.be64 (pg_micros t))
913 }
914 else
915 {
916 text_param (show value)
917 }
918 , Decimal(d) -> if oid == 1700
919 {
920 binary_param (numeric.from_dec d) // NUMERIC, always exact
921 }
922 else
923 {
924 text_param (show value)
925 }
926 }
927}
928
929fn binary_param :: data: Bytes -> protocol.BindParam
930{
931 protocol.BindParam(Some(data), 1)
932}
933
934fn text_param :: text: String -> protocol.BindParam
935{
936 protocol.BindParam(Some(bytes.from_string text), 0)
937}
938
939/// The oid a `Parse` declares for a value whose type is unambiguous, so
940/// its binary codec is used whatever the SQL infers (`0` is "infer it").
941/// `Integer` stays inferred: its width (int2/int4/int8) is the context's
942/// call, and declaring int8 would break resolution of int4 functions
943/// (`pg_terminate_backend($1)`).
944fn declared_oid :: value: Value -> Int
945{
946 match value
947 { Boolean(_) -> 16
948 , Bytea(_) -> 17
949 , Real(_) -> 701
950 , Uuid(_) -> 2950
951 , Timestamptz(_) -> 1184
952 , Decimal(_) -> 1700
953 , _ -> 0
954 }
955}
956
957/// A binary codec exists for the OID (results come back in it).
958fn binary_known :: oid: Int -> Bool
959{
960 list.any [16, 17, 20, 21, 23, 700, 701, 1184, 1700, 2950] fn o { o == oid }
961}
962
963/// Microseconds since PostgreSQL's epoch (2000-01-01 00:00:00 UTC).
964fn pg_micros :: t: Timestamp -> Int
965{
966 time.unix_ns t / 1000 - 946684800000000
967}
968
969/// The text format on the wire (`True`/`False` for booleans: PostgreSQL
970/// reads them; `\x…` for bytea). In a `sql` template (lib.lse), write SQL
971/// `null` literally — `Null` has no text.
972impl Show<Value>
973{
974 fn show :: value
975 {
976 match value
977 { Null -> ""
978 , Integer(n) -> "{n}"
979 , Real(f) -> "{f}"
980 , Boolean(b) -> if b { "True" } else { "False" }
981 , Text(s) -> s
982 , Bytea(b) -> "\\x" <> hex b
983 , Uuid(id) -> uuid.to_rfc id
984 , Timestamptz(t) -> time.format t
985 , Decimal(d) -> "{d}"
986 }
987 }
988}
989
990/// Lowercase hex, built in one pass (a `bytea`'s text form): one buffer,
991/// no per-byte strings — a list of them costs ~77 bytes and 0.55 µs per
992/// byte (issue gabla108/louise#311).
993fn hex :: b: Bytes -> String
994{
995 bytes.build_string
996 (hex_loop b 0 (bytes.builder_with_capacity (bytes.length b * 2)))
997}
998
999fn hex_loop :: b: Bytes at: Int acc: bytes.Builder -> bytes.Builder
1000{
1001 if at >= bytes.length b
1002 {
1003 acc
1004 }
1005 else
1006 {
1007 let byte = bytes.read_u8 b at
1008 let acc = bytes.append_byte acc (hex_digit (byte / 16))
1009 hex_loop b (at + 1) (bytes.append_byte acc (hex_digit (byte % 16)))
1010 }
1011}
1012
1013/// The ASCII code of `d`'s hex digit (`0`–`9`, `a`–`f`).
1014fn hex_digit :: d: Int -> Int
1015{
1016 if d < 10
1017 {
1018 48 + d
1019 }
1020 else
1021 {
1022 87 + d
1023 }
1024}
1025
1026// ---- tests ------------------------------------------------------------------------
1027
1028import std/test.{assert, assert_equal}
1029
1030@test
1031fn hex_is_lowercase_and_single_pass ::
1032{
1033 assert_equal (hex (bytes.empty ())) ""
1034 assert_equal (hex (bytes.from_list [222, 173, 190, 239])) "deadbeef"
1035 assert_equal (hex (bytes.from_list [0, 1, 15, 16, 255])) "00010f10ff"
1036 // A bytea's text form (the `sql` template's encoding of a hole).
1037 assert_equal (show Bytea(bytes.from_list [222, 173])) "\\xdead"
1038 // Large enough that a per-byte-strings build would not fit the test
1039 // budget: one buffer, one pass (issue gabla108/louise#311).
1040 let big =
1041 bytes.build
1042 ( list.fold
1043 (list.range 1 200_000)
1044 (bytes.builder_with_capacity 200_000)
1045 fn b i { bytes.append_byte b (i % 251) }
1046 )
1047 let text = hex big
1048 assert_equal (string.length text) 400_000
1049 assert_equal (string.slice text 0 8) "01020304"
1050}
1051
1052@test
1053fn a_bytea_parameter_is_declared_and_bound_in_binary ::
1054{
1055 // The Parse declares the unambiguous types, so the binary codec is used
1056 // whatever the SQL infers (issue gabla108/louise#311); Integer/Text stay inferred.
1057 assert_equal (declared_oid Bytea(bytes.empty ())) 17
1058 assert_equal (declared_oid Boolean(True)) 16
1059 assert_equal (declared_oid Real(1.5)) 701
1060 assert_equal (declared_oid Integer(42)) 0
1061 assert_equal (declared_oid Text("x")) 0
1062 assert_equal (declared_oid Null) 0
1063 match uuid.from_rfc "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
1064 { Some(id) -> assert_equal (declared_oid Uuid(id)) 2950
1065 , None -> panic "a literal uuid"
1066 }
1067 assert_equal (declared_oid Timestamptz(time.from_unix_ns 0)) 1184
1068 match dec.parse "12345.6789"
1069 { Error(e) -> panic e
1070 , Ok(price) ->
1071 {
1072 // NUMERIC is unambiguous: declared 1700, bound in binary.
1073 assert_equal (declared_oid Decimal(price)) 1700
1074 match encode_one Decimal(price) 1700
1075 { protocol.BindParam(Some(b), 1) ->
1076 assert_equal (numeric.to_dec b) (Ok(price))
1077 , _ -> panic "a numeric binds in binary"
1078 }
1079 // In text (an inferred oid) it is the decimal's text.
1080 match encode_one Decimal(price) 0
1081 { protocol.BindParam(Some(b), 0) ->
1082 assert_equal (bytes.to_string b) (Ok("12345.6789"))
1083 , _ -> panic "a numeric binds in text"
1084 }
1085 }
1086 }
1087 // And with the oid known, the parameter is the raw bytes, format 1.
1088 let data = bytes.from_list [1, 2, 3]
1089 match encode_one Bytea(data) 17
1090 { protocol.BindParam(Some(b), 1) -> assert (b == data) "raw bytes, binary"
1091 , _ -> panic "a bytea binds in binary"
1092 }
1093}