/// A connection to PostgreSQL: one actor owns the socket and the protocol /// state, so a connection is never used by two callers at once (issue /// gabla108/louise#145 §3). Parameters travel as `$1`, never inside the SQL text. /// /// The wire is the extended query protocol (`Parse`/`Bind`/`Describe`/ /// `Execute`/`Sync`); authentication is `trust`, cleartext password (over /// TLS or to localhost only) or SCRAM-SHA-256 (scram.lse). import std/actor.{Continue, Stop} import std/base64 import std/bytes import std/dec.{type Dec} import std/dict.{type Dict} import std/ffi.{type Resource} import std/list import std/net.{type TcpStream} import std/option import std/process.{type Pid, type Subject, type proc} import std/random.{type random} import std/result import std/string import std/time.{type Timestamp} import std/tls.{type TlsStream} import binary import config.{type Config, Disable, Require} import numeric import protocol import scram import uuid /// What a call failed with. @derive Debug pub type Error { /// The socket or the TLS layer. Io(String) /// The server refused, with its fields (the `"C"` field is the /// SQLSTATE, `"M"` the message). , Server(List<(String, String)>) /// The driver itself: the protocol was violated, or authentication /// could not run. , Driver(String) } /// A parameter's value; SQL `NULL` is `Null`. A value whose type a binary /// codec exists for is declared in the `Parse` and binds in binary /// (`Bytea` is the raw bytes, no `\x` form); the rest go in text. @derive Eq Debug pub type Value { Null , Integer(Int) , Real(Float) , Boolean(Bool) , Text(String) , Bytea(Bytes) , Uuid(uuid.Uuid) , Timestamptz(time.Timestamp) /// PostgreSQL `NUMERIC` (OID 1700): a fixed-point decimal (ADR 0070). , Decimal(Dec) } /// A row set's columns (the protocol's fields) and rows. pub type QueryResult { QueryResult(columns: List, rows: List, tag: String) } /// A row: its columns and its values in text format (`None` is `NULL`). pub type Row { Row(columns: List, values: List>) } /// The SQLSTATE of a server error, if it has one. pub fn sqlstate :: e: Error -> Option { match e { Server(fields) -> field fields "C", _ -> None } } /// The server's message for a server error, or the text otherwise. pub fn message :: e: Error -> String { match e { Io(m) -> m , Server(fields) -> option.unwrap_or (field fields "M") (debug_fields fields) , Driver(m) -> m } } fn field :: fields: List<(String, String)> name: String -> Option { match fields { [] -> None , [(n, v), ..rest] -> if n == name { Some(v) } else { field rest name } } } fn debug_fields :: fields: List<(String, String)> -> String { "{fields:?}" } // ---- connecting ------------------------------------------------------------- /// The socket: plain TCP or TLS. type Conn { Tcp(Resource), Tls(Resource) } /// A connection's socket after the handshake: the connection, the read /// buffer, the settings, and the backend key data (for `CancelRequest`). pub type Socket { Socket( conn: Conn , buffer: Bytes , host: String , port: Int , backend: Option<(Int, Int)> ) } /// Connect and authenticate, without the actor: the socket, for the /// connection actor (`connect`) or a listener (`listen`). pub fn connect_socket :: cfg: Config -> Result / { use tcp <- result.try (net.connect cfg.host cfg.port |> result.map_error Io) use conn <- result.try (maybe_tls tcp cfg) use (buffer, backend) <- result.try (handshake conn cfg) Ok(Socket(conn, buffer, cfg.host, cfg.port, backend)) } /// Connect and authenticate. The connection is an actor; stop it with /// `close`. pub fn connect :: cfg: Config -> Result, Error> / { use socket <- result.try (connect_socket cfg) Ok(connect_over socket) } /// The connection actor over an already-authenticated socket. pub fn connect_over :: socket: Socket -> Subject / { actor.start (state_of socket) fn state msg { on_message state msg } } fn state_of :: socket: Socket -> State { let Socket(conn, buffer, host, port, backend) = socket State(conn, buffer, 0, host, port, backend, dict.empty (), 1) } /// TLS if the mode wants it: `SslRequest`, then the handshake if the /// server agrees. `Require` refuses a plain answer. fn maybe_tls :: tcp: Resource cfg: Config -> Result / { match cfg.tls { Disable -> Ok(Tcp(tcp)) , mode -> { use _ <- result.try ( net.write tcp (protocol.encode protocol.SslRequest) |> result.map_error Io ) use answer <- result.try (net.read tcp 1 |> result.map_error Io) match bytes.to_list answer { [byte] -> match protocol.ssl_answer byte { Some(protocol.Upgrade) -> { use tls_config <- result.try (tls.config (tls.defaults ()) |> result.map_error tls_io) use stream <- result.try (tls.connect tcp cfg.host tls_config |> result.map_error tls_io) Ok(Tls(stream)) } , Some(protocol.Plain) -> match mode { Require -> Error(Driver("the server does not do TLS (sslmode=require)")) , _ -> Ok(Tcp(tcp)) } , None -> Error(Driver("a byte that is not an SSL answer")) } , _ -> Error(Io("the server closed the connection")) } } } } fn tls_io :: e: tls.TlsError -> Error { Io("TLS: {e}") } /// The startup message, then authenticate until `ReadyForQuery`. The /// buffer's leftover bytes come back (the server sent nothing extra in /// practice), with the backend key data if it arrived. fn handshake :: conn: Conn cfg: Config -> Result<(Bytes, Option<(Int, Int)>), Error> / { use _ <- result.try (write_msg conn protocol.Startup(cfg.user, cfg.database, cfg.application)) use (buffer, at, backend) <- result.try (auth_loop conn (bytes.empty ()) 0 cfg None) Ok((bytes.slice buffer at (bytes.length buffer), backend)) } fn auth_loop :: conn: Conn buffer: Bytes at: Int cfg: Config backend: Option<(Int, Int)> -> Result<(Bytes, Int, Option<(Int, Int)>), Error> / { use (msg, buffer, at) <- result.try (read_message conn buffer at) match msg { protocol.AuthenticationOk -> auth_loop conn buffer at cfg backend , protocol.AuthenticationCleartext -> { use _ <- result.try (cleartext_password conn cfg) auth_loop conn buffer at cfg backend } , protocol.AuthenticationSasl(mechanisms) -> { use (buffer, at) <- result.try (scram_exchange conn buffer at cfg mechanisms) auth_loop conn buffer at cfg backend } , protocol.ParameterStatus(..) -> auth_loop conn buffer at cfg backend , protocol.BackendKeyData(pid, secret) -> auth_loop conn buffer at cfg Some((pid, secret)) , protocol.NoticeResponse(_) -> auth_loop conn buffer at cfg backend , protocol.ReadyForQuery(_) -> Ok((buffer, at, backend)) , protocol.ErrorResponse(fields) -> Error(Server(fields)) , _ -> Error(Driver("an unexpected message during startup")) } } /// A cleartext password, over TLS or to localhost only. fn cleartext_password :: conn: Conn cfg: Config -> Result<(), Error> / { let safe = match conn { Tls(_) -> True , Tcp(_) -> cfg.host == "localhost" || cfg.host == "127.0.0.1" || cfg.host == "::1" } if !safe { Error( Driver( "the server wants a cleartext password, which needs TLS or localhost" ) ) } else { use password <- result.try ( option.to_result cfg.password "the server wants a password; the URL has none" |> result.map_error Driver ) write_msg conn protocol.Password(password) } } /// SCRAM-SHA-256, if the server offers it. fn scram_exchange :: conn: Conn buffer: Bytes at: Int cfg: Config mechanisms: List -> Result<(Bytes, Int), Error> / { if !list.any mechanisms fn m { m == "SCRAM-SHA-256" } { Error(Driver("the server offers no SCRAM-SHA-256")) } else { use password <- result.try ( option.to_result cfg.password "the server wants a password; the URL has none" |> result.map_error Driver ) let nonce = base64.encode (random.bytes 18) let (state, first) = scram.client_first nonce use _ <- result.try (write_msg conn protocol.SaslInitialResponse("SCRAM-SHA-256", first)) use (msg, buffer, at) <- result.try (read_message conn buffer at) use (state, reply) <- result.try (scram_continue msg state password) use _ <- result.try (write_msg conn protocol.SaslResponse(bytes.from_string reply)) use (msg, buffer, at) <- result.try (read_message conn buffer at) use _ <- result.try (scram_final msg state) Ok((buffer, at)) } } /// The server-first step: the client-final message and the state the /// final step verifies with. fn scram_continue :: msg: protocol.In state: scram.Scram password: String -> Result<(scram.Scram, String), Error> { match msg { protocol.SaslContinue(data) -> match bytes.to_string data { Ok(text) -> scram.client_final state password text |> result.map_error Driver , Error(e) -> Error(Driver("SASL data is not UTF-8: {e}")) } , protocol.ErrorResponse(fields) -> Error(Server(fields)) , _ -> Error(Driver("expected a SASL continuation")) } } /// The server-final step: verify the server's signature (it proves the /// server knew the password too). fn scram_final :: msg: protocol.In state: scram.Scram -> Result<(), Error> { match msg { protocol.SaslFinal(data) -> match bytes.to_string data { Ok(text) -> scram.verify_server state text |> result.map_error Driver , Error(e) -> Error(Driver("SASL data is not UTF-8: {e}")) } , protocol.ErrorResponse(fields) -> Error(Server(fields)) , _ -> Error(Driver("expected a SASL final")) } } // ---- the query exchange ------------------------------------------------------- /// The actor's state: the socket, the read buffer and the offset parsing /// resumes at, the settings, the backend key data (for `CancelRequest`), /// and the statements prepared on this connection, by SQL text (issue /// gabla108/louise#145 §1). type State { State( conn: Conn , buffer: Bytes , at: Int , host: String , port: Int , backend: Option<(Int, Int)> , prepared: Dict , next_statement: Int ) } /// A statement prepared on this connection: its name, its parameters' /// type OIDs, and its result columns. type Prepared { Prepared(name: String, param_oids: List, fields: List) } /// The connection's messages. pub type Msg { DoQuery( sql: String , params: List , reply: Subject> ) /// A liveness check: a bare `Sync`, answered by `ReadyForQuery` — the /// cheapest round trip the protocol has. It fails when the connection /// is not idle (a pooled connection has no transaction open). The actor /// stops after a failed ping: the connection is not to be trusted. , Ping(reply: Subject>) , Close(reply: Subject<()>) } fn on_message :: state: State msg: Msg -> actor.Next / { match msg { DoQuery(sql, params, reply) -> { let (res, state) = run_query state sql params process.send reply res Continue(state) } , Ping(reply) -> { let (res, buffer, at) = ping state.conn state.buffer state.at process.send reply res match res { Ok(()) -> Continue(State(..state, buffer: buffer, at: at)) , Error(_) -> { close_conn state.conn Stop } } } , Close(reply) -> { close_conn state.conn process.send reply () Stop } } } /// A bare `Sync`, then read to `ReadyForQuery`, which must report the /// connection idle: a pooled connection has no transaction open. fn ping :: conn: Conn buffer: Bytes at: Int -> (Result<(), Error>, Bytes, Int) / { match write_msg conn protocol.Sync { Error(e) -> (Error(e), bytes.empty (), 0) , Ok(()) -> ping_read conn buffer at None } } fn ping_read :: conn: Conn buffer: Bytes at: Int error: Option -> (Result<(), Error>, Bytes, Int) / { match read_message conn buffer at { Error(e) -> (Error(e), bytes.empty (), 0) , Ok((msg, buffer, at)) -> match msg { protocol.ReadyForQuery(status) -> match error { Some(e) -> (Error(e), buffer, at) , None -> match status { protocol.Idle -> (Ok(()), buffer, at) , _ -> ( Error(Driver("the connection has a transaction open")) , buffer , at ) } } , protocol.ErrorResponse(fields) -> ping_read conn buffer at Some(Server(fields)) , _ -> ping_read conn buffer at error } } } /// A query: the statement is prepared once per connection (Parse + /// Describe, one exchange), then Bind + Execute. Parameters travel as /// `$1`, binary per type where a codec exists (binary.lse). fn run_query :: state: State sql: String params: List -> (Result, State) / { match prepare state sql params { (Error(e), state) -> (Error(e), state) , ( Ok(prep) , state ) -> if list.length params != list.length prep.param_oids { ( Error( Driver( "the statement takes {list.length prep.param_oids} parameters, got {list.length params}" ) ) , state ) } else { let encoded = encode_params params prep.param_oids [] let formats = list.map prep.fields fn f { if binary_known f.type_oid { 1 } else { 0 } } let out = [ protocol.Bind("", prep.name, encoded, formats) , protocol.DescribePortal("") , protocol.Execute("", 0) , protocol.Sync ] match conn_write state.conn (bytes.concat_all (list.map out protocol.encode)) { Error(e) -> (Error(e), state) , Ok(()) -> { let (res, buffer, at) = collect state.conn state.buffer state.at [] [] "" None (res, State(..state, buffer: buffer, at: at)) } } } } } /// The statement prepared on this connection: from the cache, or by Parse /// + Describe (one exchange). The parameters' types are declared where the /// value names one unambiguously (`declared_oid`), so a `Bytea` binds in /// binary whatever the SQL context infers. fn prepare :: state: State sql: String params: List -> (Result, State) / { match dict.get state.prepared sql { Some(prep) -> (Ok(prep), state) , None -> { let name = "q{state.next_statement}" let out = [ protocol.Parse(name, sql, list.map params declared_oid) , protocol.DescribeStatement(name) , protocol.Sync ] match conn_write state.conn (bytes.concat_all (list.map out protocol.encode)) { Error(e) -> (Error(e), state) , Ok ( () ) -> match read_describe state.conn state.buffer state.at [] [] None { (Error(e), buffer, at) -> ( Error(e) , State(..state, buffer: buffer, at: at) ) , (Ok((oids, fields)), buffer, at) -> { let prep = Prepared(name, oids, fields) ( Ok(prep) , State( ..state , buffer: buffer , at: at , prepared: dict.insert state.prepared sql prep , next_statement: state.next_statement + 1 ) ) } } } } } } /// Read the answers to Parse + Describe until `ReadyForQuery`: the /// parameters' type OIDs and the result columns. fn read_describe :: conn: Conn buffer: Bytes at: Int param_oids: List fields: List error: Option -> (Result<(List, List), Error>, Bytes, Int) / { match read_message conn buffer at { Error(e) -> (Error(e), bytes.empty (), 0) , Ok((msg, buffer, at)) -> match msg { protocol.ParameterDescription(oids) -> read_describe conn buffer at oids fields error , protocol.RowDescription(f) -> read_describe conn buffer at param_oids f error , protocol.NoData -> read_describe conn buffer at param_oids [] error , protocol.ErrorResponse(f) -> read_describe conn buffer at param_oids fields Some(Server(f)) , protocol.ReadyForQuery(_) -> match error { Some(e) -> (Error(e), buffer, at) , None -> (Ok((param_oids, fields)), buffer, at) } , _ -> read_describe conn buffer at param_oids fields error } } } fn collect :: conn: Conn buffer: Bytes at: Int columns: List rows: List tag: String error: Option -> (Result, Bytes, Int) / { match read_message conn buffer at { Error(e) -> (Error(e), bytes.empty (), 0) , Ok((msg, buffer, at)) -> match msg { protocol.RowDescription(fields) -> collect conn buffer at fields rows tag error , protocol.DataRow(values) -> collect conn buffer at columns [Row(columns, values), ..rows] tag error , protocol.CommandComplete(t) -> collect conn buffer at columns rows t error , protocol.ErrorResponse(fields) -> collect conn buffer at columns rows tag Some(Server(fields)) , protocol.ReadyForQuery(_) -> match error { Some(e) -> (Error(e), buffer, at) , None -> (Ok(QueryResult(columns, list.reverse rows, tag)), buffer, at) } , _ -> collect conn buffer at columns rows tag error // ParseComplete, BindComplete, NoData, ... } } } // ---- the wire ---------------------------------------------------------------- /// One full message, reading more as needed; the answer is the message, /// the buffer and the offset parsing resumes at. A message already whole /// in the buffer is parsed in place (nothing is copied); one that /// straddles reads pays once for moving its tail into a builder. fn read_message :: conn: Conn buffer: Bytes at: Int -> Result<(protocol.In, Bytes, Int), Error> / { match protocol.next buffer at { protocol.Message(msg, past) -> if past == bytes.length buffer { Ok((msg, bytes.empty (), 0)) } else { Ok((msg, buffer, past)) } , protocol.Malformed(e) -> Error(Driver(e)) , protocol.Incomplete -> fill conn (bytes.slice buffer at (bytes.length buffer)) } } /// The rest of a message that straddles reads: chunks accumulate in a /// builder (appending does not copy what was appended before) until the /// frame is whole. fn fill :: conn: Conn tail: Bytes -> Result<(protocol.In, Bytes, Int), Error> / { use tail <- result.try (fill_header conn tail) use total <- result.try (protocol.frame_total tail 0 |> result.map_error Driver) let b = bytes.append (bytes.builder_with_capacity (bytes.length tail + 65536)) tail fill_loop conn b (bytes.length tail) total } /// `tail` grown to a whole frame header (5 bytes). fn fill_header :: conn: Conn tail: Bytes -> Result / { if bytes.length tail >= 5 { Ok(tail) } else { use chunk <- result.try (conn_read conn 65536) if bytes.length chunk == 0 { Error(Io("the server closed the connection")) } else { fill_header conn (bytes.concat tail chunk) } } } fn fill_loop :: conn: Conn b: bytes.Builder have: Int total: Int -> Result<(protocol.In, Bytes, Int), Error> / { if have >= total { let buffer = bytes.build b match protocol.next buffer 0 { protocol.Message(msg, past) -> Ok((msg, buffer, past)) , protocol.Malformed(e) -> Error(Driver(e)) , protocol.Incomplete -> Error( Driver( "protocol: a whole frame did not parse (a bug in the codec)" ) ) } } else { use chunk <- result.try (conn_read conn 65536) if bytes.length chunk == 0 { Error(Io("the server closed the connection")) } else { fill_loop conn (bytes.append b chunk) (have + bytes.length chunk) total } } } fn write_msg :: conn: Conn msg: protocol.Out -> Result<(), Error> / { conn_write conn (protocol.encode msg) } fn conn_read :: conn: Conn max: Int -> Result / { match conn { Tcp(c) -> net.read c max |> result.map_error Io , Tls(c) -> tls.read c max |> result.map_error tls_io } } fn conn_write :: conn: Conn data: Bytes -> Result<(), Error> / { match conn { Tcp(c) -> net.write c data |> result.map_error Io , Tls(c) -> tls.write c data |> result.map_error tls_io } } fn close_conn :: conn: Conn -> () / { let _ = conn_write conn (protocol.encode protocol.Terminate) match conn { Tcp(c) -> net.close c, Tls(c) -> tls.close c } } // ---- LISTEN/NOTIFY (a dedicated connection, outside any pool) ----------------- /// A notification from a `LISTEN`ed channel. @derive Debug pub type Notification { Notification(channel: String, payload: String, process: Int) } /// Listen on `channel`; each of its notifications goes to `subscriber`. /// The listener is one dedicated connection (outside any pool): an actor /// parked on the socket. Stop it with `process.kill` (a supervisor /// restarts it: it re-`LISTEN`s). Quoting: the channel is an identifier, /// sent as `LISTEN "channel"`. pub fn listen :: cfg: Config channel: String subscriber: Subject -> Result / { use socket <- result.try (connect_socket cfg) let Socket(conn, buffer, ..) = socket use (buffer, at) <- result.try (listen_command conn buffer 0 channel) Ok(process.spawn fn { listen_serve conn buffer at channel subscriber }) } /// `LISTEN "channel"`, answered by `CommandComplete` and `ReadyForQuery`. fn listen_command :: conn: Conn buffer: Bytes at: Int channel: String -> Result<(Bytes, Int), Error> / { use _ <- result.try (write_msg conn protocol.Query("LISTEN {quoted channel}")) drain_until_ready conn buffer at } /// An identifier in double quotes (inner quotes doubled). fn quoted :: name: String -> String { "\"" <> string.concat ( list.map (string.chars name) fn c { if c == "\"" { "\"\"" } else { c } } ) <> "\"" } /// Read until `ReadyForQuery` (the simple query protocol's end). fn drain_until_ready :: conn: Conn buffer: Bytes at: Int -> Result<(Bytes, Int), Error> / { use (msg, buffer, at) <- result.try (read_message conn buffer at) match msg { protocol.ReadyForQuery(_) -> Ok((buffer, at)) , protocol.ErrorResponse(fields) -> Error(Server(fields)) , _ -> drain_until_ready conn buffer at } } /// Read forever: notifications for our channel go to the subscriber. A /// broken socket stops the listener. fn listen_serve :: conn: Conn buffer: Bytes at: Int channel: String subscriber: Subject -> () / { match read_message conn buffer at { Error(_) -> () , Ok((msg, buffer, at)) -> { match msg { protocol.NotificationResponse(source, ch, payload) -> { if ch == channel { process.send subscriber Notification(ch, payload, source) } } , _ -> () } listen_serve conn buffer at channel subscriber } } } // ---- parameters --------------------------------------------------------------- /// Parameters encoded per their inferred types: binary where a codec /// exists for the OID (binary.lse), text otherwise. `Null` has no format. fn encode_params :: params: List oids: List acc: List -> List { match (params, oids) { ([], _) -> list.reverse acc , ([param, ..rest], [oid, ..rest_oids]) -> encode_params rest rest_oids [encode_one param oid, ..acc] , (_, []) -> list.reverse acc // the arity check in run_query came first } } fn encode_one :: value: Value oid: Int -> protocol.BindParam { match value { Null -> protocol.BindParam(None, 0) , Integer(n) -> match oid { 21 -> binary_param (binary.be16 n) // int2 , 23 -> binary_param (binary.be32 n) // int4 , 20 -> binary_param (binary.be64 n) // int8 , _ -> text_param "{n}" } , Real(f) -> match oid { 700 -> binary_param (binary.f32 f) // float4 , 701 -> binary_param (binary.f64 f) // float8 , _ -> text_param "{f}" } , Boolean ( b ) -> if oid == 16 { binary_param (bytes.from_list [if b { 1 } else { 0 }]) } else { text_param (show value) } , Text(s) -> text_param s , Bytea(b) -> if oid == 17 { binary_param b // raw, no `\x` form } else { text_param (show value) } , Uuid(id) -> if oid == 2950 { binary_param (uuid.to_bytes id) } else { text_param (show value) } , Timestamptz(t) -> if oid == 1184 { binary_param (binary.be64 (pg_micros t)) } else { text_param (show value) } , Decimal(d) -> if oid == 1700 { binary_param (numeric.from_dec d) // NUMERIC, always exact } else { text_param (show value) } } } fn binary_param :: data: Bytes -> protocol.BindParam { protocol.BindParam(Some(data), 1) } fn text_param :: text: String -> protocol.BindParam { protocol.BindParam(Some(bytes.from_string text), 0) } /// The oid a `Parse` declares for a value whose type is unambiguous, so /// its binary codec is used whatever the SQL infers (`0` is "infer it"). /// `Integer` stays inferred: its width (int2/int4/int8) is the context's /// call, and declaring int8 would break resolution of int4 functions /// (`pg_terminate_backend($1)`). fn declared_oid :: value: Value -> Int { match value { Boolean(_) -> 16 , Bytea(_) -> 17 , Real(_) -> 701 , Uuid(_) -> 2950 , Timestamptz(_) -> 1184 , Decimal(_) -> 1700 , _ -> 0 } } /// A binary codec exists for the OID (results come back in it). fn binary_known :: oid: Int -> Bool { list.any [16, 17, 20, 21, 23, 700, 701, 1184, 1700, 2950] fn o { o == oid } } /// Microseconds since PostgreSQL's epoch (2000-01-01 00:00:00 UTC). fn pg_micros :: t: Timestamp -> Int { time.unix_ns t / 1000 - 946684800000000 } /// The text format on the wire (`True`/`False` for booleans: PostgreSQL /// reads them; `\x…` for bytea). In a `sql` template (lib.lse), write SQL /// `null` literally — `Null` has no text. impl Show { fn show :: value { match value { Null -> "" , Integer(n) -> "{n}" , Real(f) -> "{f}" , Boolean(b) -> if b { "True" } else { "False" } , Text(s) -> s , Bytea(b) -> "\\x" <> hex b , Uuid(id) -> uuid.to_rfc id , Timestamptz(t) -> time.format t , Decimal(d) -> "{d}" } } } /// Lowercase hex, built in one pass (a `bytea`'s text form): one buffer, /// no per-byte strings — a list of them costs ~77 bytes and 0.55 µs per /// byte (issue gabla108/louise#311). fn hex :: b: Bytes -> String { bytes.build_string (hex_loop b 0 (bytes.builder_with_capacity (bytes.length b * 2))) } fn hex_loop :: b: Bytes at: Int acc: bytes.Builder -> bytes.Builder { if at >= bytes.length b { acc } else { let byte = bytes.read_u8 b at let acc = bytes.append_byte acc (hex_digit (byte / 16)) hex_loop b (at + 1) (bytes.append_byte acc (hex_digit (byte % 16))) } } /// The ASCII code of `d`'s hex digit (`0`–`9`, `a`–`f`). fn hex_digit :: d: Int -> Int { if d < 10 { 48 + d } else { 87 + d } } // ---- tests ------------------------------------------------------------------------ import std/test.{assert, assert_equal} @test fn hex_is_lowercase_and_single_pass :: { assert_equal (hex (bytes.empty ())) "" assert_equal (hex (bytes.from_list [222, 173, 190, 239])) "deadbeef" assert_equal (hex (bytes.from_list [0, 1, 15, 16, 255])) "00010f10ff" // A bytea's text form (the `sql` template's encoding of a hole). assert_equal (show Bytea(bytes.from_list [222, 173])) "\\xdead" // Large enough that a per-byte-strings build would not fit the test // budget: one buffer, one pass (issue gabla108/louise#311). let big = bytes.build ( list.fold (list.range 1 200_000) (bytes.builder_with_capacity 200_000) fn b i { bytes.append_byte b (i % 251) } ) let text = hex big assert_equal (string.length text) 400_000 assert_equal (string.slice text 0 8) "01020304" } @test fn a_bytea_parameter_is_declared_and_bound_in_binary :: { // The Parse declares the unambiguous types, so the binary codec is used // whatever the SQL infers (issue gabla108/louise#311); Integer/Text stay inferred. assert_equal (declared_oid Bytea(bytes.empty ())) 17 assert_equal (declared_oid Boolean(True)) 16 assert_equal (declared_oid Real(1.5)) 701 assert_equal (declared_oid Integer(42)) 0 assert_equal (declared_oid Text("x")) 0 assert_equal (declared_oid Null) 0 match uuid.from_rfc "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11" { Some(id) -> assert_equal (declared_oid Uuid(id)) 2950 , None -> panic "a literal uuid" } assert_equal (declared_oid Timestamptz(time.from_unix_ns 0)) 1184 match dec.parse "12345.6789" { Error(e) -> panic e , Ok(price) -> { // NUMERIC is unambiguous: declared 1700, bound in binary. assert_equal (declared_oid Decimal(price)) 1700 match encode_one Decimal(price) 1700 { protocol.BindParam(Some(b), 1) -> assert_equal (numeric.to_dec b) (Ok(price)) , _ -> panic "a numeric binds in binary" } // In text (an inferred oid) it is the decimal's text. match encode_one Decimal(price) 0 { protocol.BindParam(Some(b), 0) -> assert_equal (bytes.to_string b) (Ok("12345.6789")) , _ -> panic "a numeric binds in text" } } } // And with the oid known, the parameter is the raw bytes, format 1. let data = bytes.from_list [1, 2, 3] match encode_one Bytea(data) 17 { protocol.BindParam(Some(b), 1) -> assert (b == data) "raw bytes, binary" , _ -> panic "a bytea binds in binary" } }