| @@ -0,0 +1,407 @@ |
| 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 | +/// #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 | + |
| 9 | +import std/actor.{Continue, Stop} |
| 10 | +import std/base64 |
| 11 | +import std/bytes |
| 12 | +import std/ffi.{type Resource} |
| 13 | +import std/int |
| 14 | +import std/list |
| 15 | +import std/net.{type TcpStream} |
| 16 | +import std/option |
| 17 | +import std/process.{type Subject, type proc} |
| 18 | +import std/random.{type random} |
| 19 | +import std/result |
| 20 | +import std/string |
| 21 | +import std/tls.{type TlsStream} |
| 22 | + |
| 23 | +import config.{type Config, Disable, Require} |
| 24 | +import protocol |
| 25 | +import scram |
| 26 | + |
| 27 | +/// What a call failed with. |
| 28 | +@derive(Debug) |
| 29 | +pub type Error { |
| 30 | + /// The socket or the TLS layer. |
| 31 | + Io(String) |
| 32 | + /// The server refused, with its fields (the `"C"` field is the |
| 33 | + /// SQLSTATE, `"M"` the message). |
| 34 | + Server(List<(String, String)>) |
| 35 | + /// The driver itself: the protocol was violated, or authentication |
| 36 | + /// could not run. |
| 37 | + Driver(String) |
| 38 | +} |
| 39 | + |
| 40 | +/// A parameter's value, sent in text format; SQL `NULL` is `Null`. |
| 41 | +@derive(Eq, Debug) |
| 42 | +pub type Value { |
| 43 | + Null |
| 44 | + Integer(Int) |
| 45 | + Real(Float) |
| 46 | + Boolean(Bool) |
| 47 | + Text(String) |
| 48 | + Bytea(Bytes) |
| 49 | +} |
| 50 | + |
| 51 | +/// A row set's columns (the protocol's fields) and rows. |
| 52 | +pub type QueryResult { |
| 53 | + QueryResult(columns: List<protocol.Field>, rows: List<Row>, tag: String) |
| 54 | +} |
| 55 | + |
| 56 | +/// A row: its columns and its values in text format (`None` is `NULL`). |
| 57 | +pub type Row { |
| 58 | + Row(columns: List<protocol.Field>, values: List<Option<Bytes>>) |
| 59 | +} |
| 60 | + |
| 61 | +/// The SQLSTATE of a server error, if it has one. |
| 62 | +pub fn sqlstate(e: Error) -> Option<String> { |
| 63 | + match e { |
| 64 | + Server(fields) -> field(fields, "C"), |
| 65 | + _ -> None, |
| 66 | + } |
| 67 | +} |
| 68 | + |
| 69 | +/// The server's message for a server error, or the text otherwise. |
| 70 | +pub fn message(e: Error) -> String { |
| 71 | + match e { |
| 72 | + Io(m) -> m, |
| 73 | + Server(fields) -> option.unwrap_or(field(fields, "M"), debug_fields(fields)), |
| 74 | + Driver(m) -> m, |
| 75 | + } |
| 76 | +} |
| 77 | + |
| 78 | +fn field(fields: List<(String, String)>, name: String) -> Option<String> { |
| 79 | + match fields { |
| 80 | + [] -> None, |
| 81 | + [(n, v), ..rest] -> if n == name { Some(v) } else { field(rest, name) }, |
| 82 | + } |
| 83 | +} |
| 84 | + |
| 85 | +fn debug_fields(fields: List<(String, String)>) -> String { |
| 86 | + "{fields:?}" |
| 87 | +} |
| 88 | + |
| 89 | +// ---- connecting ------------------------------------------------------------- |
| 90 | + |
| 91 | +/// The socket: plain TCP or TLS. |
| 92 | +type Conn { |
| 93 | + Tcp(Resource<TcpStream>) |
| 94 | + Tls(Resource<TlsStream>) |
| 95 | +} |
| 96 | + |
| 97 | +/// Connect and authenticate. The connection is an actor; stop it with |
| 98 | +/// `close`. |
| 99 | +pub fn connect(config: Config) -> Result<Subject<Msg>, Error> / <io, proc, random> { |
| 100 | + use tcp <- result.try(net.connect(config.host, config.port) |> result.map_error(Io)) |
| 101 | + use conn <- result.try(maybe_tls(tcp, config)) |
| 102 | + use buffer <- result.try(handshake(conn, config)) |
| 103 | + Ok(actor.start(State(conn, buffer), fn(state, msg) { on_message(state, msg) })) |
| 104 | +} |
| 105 | + |
| 106 | +/// TLS if the mode wants it: `SslRequest`, then the handshake if the |
| 107 | +/// server agrees. `Require` refuses a plain answer. |
| 108 | +fn maybe_tls(tcp: Resource<TcpStream>, config: Config) -> Result<Conn, Error> / <io> { |
| 109 | + match config.tls { |
| 110 | + Disable -> Ok(Tcp(tcp)), |
| 111 | + mode -> { |
| 112 | + use _ <- result.try(net.write(tcp, protocol.encode(protocol.SslRequest)) |> result.map_error(Io)) |
| 113 | + use answer <- result.try(net.read(tcp, 1) |> result.map_error(Io)) |
| 114 | + match bytes.to_list(answer) { |
| 115 | + [byte] -> |
| 116 | + match protocol.ssl_answer(byte) { |
| 117 | + Some(protocol.Upgrade) -> { |
| 118 | + use tls_config <- result.try(tls.config(tls.defaults()) |> result.map_error(tls_io)) |
| 119 | + use stream <- result.try(tls.connect(tcp, config.host, tls_config) |> result.map_error(tls_io)) |
| 120 | + Ok(Tls(stream)) |
| 121 | + }, |
| 122 | + Some(protocol.Plain) -> |
| 123 | + match mode { |
| 124 | + Require -> Error(Driver("the server does not do TLS (sslmode=require)")), |
| 125 | + _ -> Ok(Tcp(tcp)), |
| 126 | + }, |
| 127 | + None -> Error(Driver("a byte that is not an SSL answer")), |
| 128 | + }, |
| 129 | + _ -> Error(Io("the server closed the connection")), |
| 130 | + } |
| 131 | + } |
| 132 | + } |
| 133 | +} |
| 134 | + |
| 135 | +fn tls_io(e: tls.TlsError) -> Error { |
| 136 | + Io("TLS: {e}") |
| 137 | +} |
| 138 | + |
| 139 | +/// The startup message, then authenticate until `ReadyForQuery`. The |
| 140 | +/// buffer's leftover bytes come back (the server sent nothing extra in |
| 141 | +/// practice). |
| 142 | +fn handshake(conn: Conn, config: Config) -> Result<Bytes, Error> / <io, random> { |
| 143 | + use _ <- result.try(write_msg(conn, protocol.Startup(config.user, config.database, config.application))) |
| 144 | + auth_loop(conn, bytes.empty(), config) |
| 145 | +} |
| 146 | + |
| 147 | +fn auth_loop(conn: Conn, buffer: Bytes, config: Config) -> Result<Bytes, Error> / <io, random> { |
| 148 | + use (msg, buffer) <- result.try(read_message(conn, buffer)) |
| 149 | + match msg { |
| 150 | + protocol.AuthenticationOk -> auth_loop(conn, buffer, config), |
| 151 | + protocol.AuthenticationCleartext -> { |
| 152 | + use _ <- result.try(cleartext_password(conn, config)) |
| 153 | + auth_loop(conn, buffer, config) |
| 154 | + }, |
| 155 | + protocol.AuthenticationSasl(mechanisms) -> scram_exchange(conn, buffer, config, mechanisms), |
| 156 | + protocol.ParameterStatus(..) -> auth_loop(conn, buffer, config), |
| 157 | + protocol.BackendKeyData(..) -> auth_loop(conn, buffer, config), // v0: no CancelRequest |
| 158 | + protocol.NoticeResponse(_) -> auth_loop(conn, buffer, config), |
| 159 | + protocol.ReadyForQuery(_) -> Ok(buffer), |
| 160 | + protocol.ErrorResponse(fields) -> Error(Server(fields)), |
| 161 | + _ -> Error(Driver("an unexpected message during startup")), |
| 162 | + } |
| 163 | +} |
| 164 | + |
| 165 | +/// A cleartext password, over TLS or to localhost only. |
| 166 | +fn cleartext_password(conn: Conn, config: Config) -> Result<(), Error> / <io> { |
| 167 | + let safe = |
| 168 | + match conn { |
| 169 | + Tls(_) -> True, |
| 170 | + Tcp(_) -> |
| 171 | + config.host == "localhost" || config.host == "127.0.0.1" || config.host == "::1", |
| 172 | + } |
| 173 | + if !safe { |
| 174 | + Error(Driver("the server wants a cleartext password, which needs TLS or localhost")) |
| 175 | + } else { |
| 176 | + use password <- result.try( |
| 177 | + option.to_result(config.password, "the server wants a password; the URL has none") |
| 178 | + |> result.map_error(Driver), |
| 179 | + ) |
| 180 | + write_msg(conn, protocol.Password(password)) |
| 181 | + } |
| 182 | +} |
| 183 | + |
| 184 | +/// SCRAM-SHA-256, if the server offers it. |
| 185 | +fn scram_exchange( |
| 186 | + conn: Conn, |
| 187 | + buffer: Bytes, |
| 188 | + config: Config, |
| 189 | + mechanisms: List<String>, |
| 190 | +) -> Result<Bytes, Error> / <io, random> { |
| 191 | + if !list.any(mechanisms, fn(m) { m == "SCRAM-SHA-256" }) { |
| 192 | + Error(Driver("the server offers no SCRAM-SHA-256")) |
| 193 | + } else { |
| 194 | + use password <- result.try( |
| 195 | + option.to_result(config.password, "the server wants a password; the URL has none") |
| 196 | + |> result.map_error(Driver), |
| 197 | + ) |
| 198 | + let nonce = base64.encode(random.bytes(18)) |
| 199 | + let (state, first) = scram.client_first(nonce) |
| 200 | + use _ <- result.try(write_msg(conn, protocol.SaslInitialResponse("SCRAM-SHA-256", first))) |
| 201 | + use (msg, buffer) <- result.try(read_message(conn, buffer)) |
| 202 | + use (state, reply) <- result.try(scram_continue(msg, state, password)) |
| 203 | + use _ <- result.try(write_msg(conn, protocol.SaslResponse(bytes.from_string(reply)))) |
| 204 | + use (msg, buffer) <- result.try(read_message(conn, buffer)) |
| 205 | + use _ <- result.try(scram_final(msg, state)) |
| 206 | + auth_loop(conn, buffer, config) |
| 207 | + } |
| 208 | +} |
| 209 | + |
| 210 | +/// The server-first step: the client-final message and the state the |
| 211 | +/// final step verifies with. |
| 212 | +fn scram_continue( |
| 213 | + msg: protocol.In, |
| 214 | + state: scram.Scram, |
| 215 | + password: String, |
| 216 | +) -> Result<(scram.Scram, String), Error> { |
| 217 | + match msg { |
| 218 | + protocol.SaslContinue(data) -> |
| 219 | + match bytes.to_string(data) { |
| 220 | + Ok(text) -> scram.client_final(state, password, text) |> result.map_error(Driver), |
| 221 | + Error(e) -> Error(Driver("SASL data is not UTF-8: {e}")), |
| 222 | + }, |
| 223 | + protocol.ErrorResponse(fields) -> Error(Server(fields)), |
| 224 | + _ -> Error(Driver("expected a SASL continuation")), |
| 225 | + } |
| 226 | +} |
| 227 | + |
| 228 | +/// The server-final step: verify the server's signature (it proves the |
| 229 | +/// server knew the password too). |
| 230 | +fn scram_final(msg: protocol.In, state: scram.Scram) -> Result<(), Error> { |
| 231 | + match msg { |
| 232 | + protocol.SaslFinal(data) -> |
| 233 | + match bytes.to_string(data) { |
| 234 | + Ok(text) -> scram.verify_server(state, text) |> result.map_error(Driver), |
| 235 | + Error(e) -> Error(Driver("SASL data is not UTF-8: {e}")), |
| 236 | + }, |
| 237 | + protocol.ErrorResponse(fields) -> Error(Server(fields)), |
| 238 | + _ -> Error(Driver("expected a SASL final")), |
| 239 | + } |
| 240 | +} |
| 241 | + |
| 242 | +// ---- the query exchange ------------------------------------------------------- |
| 243 | + |
| 244 | +/// The actor's state: the socket and the read buffer. |
| 245 | +type State { |
| 246 | + State(conn: Conn, buffer: Bytes) |
| 247 | +} |
| 248 | + |
| 249 | +/// The connection's messages. |
| 250 | +pub type Msg { |
| 251 | + DoQuery(sql: String, params: List<Value>, reply: Subject<Result<QueryResult, Error>>) |
| 252 | + Close(reply: Subject<()>) |
| 253 | +} |
| 254 | + |
| 255 | +fn on_message(state: State, msg: Msg) -> actor.Next<State> / <io, proc> { |
| 256 | + match msg { |
| 257 | + DoQuery(sql, params, reply) -> { |
| 258 | + let (result, buffer) = run_query(state.conn, state.buffer, sql, params) |
| 259 | + process.send(reply, result) |
| 260 | + Continue(State(..state, buffer: buffer)) |
| 261 | + }, |
| 262 | + Close(reply) -> { |
| 263 | + close_conn(state.conn) |
| 264 | + process.send(reply, ()) |
| 265 | + Stop |
| 266 | + }, |
| 267 | + } |
| 268 | +} |
| 269 | + |
| 270 | +/// The exchange: Parse, Bind, Describe the portal, Execute, Sync — one |
| 271 | +/// write — then collect until `ReadyForQuery`. |
| 272 | +fn run_query( |
| 273 | + conn: Conn, |
| 274 | + buffer: Bytes, |
| 275 | + sql: String, |
| 276 | + params: List<Value>, |
| 277 | +) -> (Result<QueryResult, Error>, Bytes) / <io> { |
| 278 | + let encoded = list.map(params, encode_param) |
| 279 | + let out = [ |
| 280 | + protocol.Parse("", sql), |
| 281 | + protocol.Bind("", "", encoded), |
| 282 | + protocol.DescribePortal(""), |
| 283 | + protocol.Execute("", 0), |
| 284 | + protocol.Sync, |
| 285 | + ] |
| 286 | + match conn_write(conn, bytes.concat_all(list.map(out, protocol.encode))) { |
| 287 | + Error(e) -> (Error(e), buffer), |
| 288 | + Ok(()) -> collect(conn, buffer, [], [], "", None), |
| 289 | + } |
| 290 | +} |
| 291 | + |
| 292 | +fn collect( |
| 293 | + conn: Conn, |
| 294 | + buffer: Bytes, |
| 295 | + columns: List<protocol.Field>, |
| 296 | + rows: List<Row>, |
| 297 | + tag: String, |
| 298 | + error: Option<Error>, |
| 299 | +) -> (Result<QueryResult, Error>, Bytes) / <io> { |
| 300 | + match read_message(conn, buffer) { |
| 301 | + Error(e) -> (Error(e), bytes.empty()), |
| 302 | + Ok((msg, buffer)) -> |
| 303 | + match msg { |
| 304 | + protocol.RowDescription(fields) -> collect(conn, buffer, fields, rows, tag, error), |
| 305 | + protocol.DataRow(values) -> collect(conn, buffer, columns, [Row(columns, values), ..rows], tag, error), |
| 306 | + protocol.CommandComplete(t) -> collect(conn, buffer, columns, rows, t, error), |
| 307 | + protocol.ErrorResponse(fields) -> collect(conn, buffer, columns, rows, tag, Some(Server(fields))), |
| 308 | + protocol.ReadyForQuery(_) -> |
| 309 | + match error { |
| 310 | + Some(e) -> (Error(e), buffer), |
| 311 | + None -> (Ok(QueryResult(columns, list.reverse(rows), tag)), buffer), |
| 312 | + }, |
| 313 | + _ -> collect(conn, buffer, columns, rows, tag, error), // ParseComplete, BindComplete, NoData, ... |
| 314 | + } |
| 315 | + } |
| 316 | +} |
| 317 | + |
| 318 | +// ---- the wire ---------------------------------------------------------------- |
| 319 | + |
| 320 | +/// One full message, reading more as needed. |
| 321 | +fn read_message(conn: Conn, buffer: Bytes) -> Result<(protocol.In, Bytes), Error> / <io> { |
| 322 | + match protocol.next(buffer) { |
| 323 | + protocol.Message(msg, rest) -> Ok((msg, rest)), |
| 324 | + protocol.Malformed(e) -> Error(Driver(e)), |
| 325 | + protocol.Incomplete -> { |
| 326 | + use chunk <- result.try(conn_read(conn, 65536)) |
| 327 | + if bytes.length(chunk) == 0 { |
| 328 | + Error(Io("the server closed the connection")) |
| 329 | + } else { |
| 330 | + read_message(conn, bytes.concat(buffer, chunk)) |
| 331 | + } |
| 332 | + } |
| 333 | + } |
| 334 | +} |
| 335 | + |
| 336 | +fn write_msg(conn: Conn, msg: protocol.Out) -> Result<(), Error> / <io> { |
| 337 | + conn_write(conn, protocol.encode(msg)) |
| 338 | +} |
| 339 | + |
| 340 | +fn conn_read(conn: Conn, max: Int) -> Result<Bytes, Error> / <io> { |
| 341 | + match conn { |
| 342 | + Tcp(c) -> net.read(c, max) |> result.map_error(Io), |
| 343 | + Tls(c) -> tls.read(c, max) |> result.map_error(tls_io), |
| 344 | + } |
| 345 | +} |
| 346 | + |
| 347 | +fn conn_write(conn: Conn, data: Bytes) -> Result<(), Error> / <io> { |
| 348 | + match conn { |
| 349 | + Tcp(c) -> net.write(c, data) |> result.map_error(Io), |
| 350 | + Tls(c) -> tls.write(c, data) |> result.map_error(tls_io), |
| 351 | + } |
| 352 | +} |
| 353 | + |
| 354 | +fn close_conn(conn: Conn) -> () / <io> { |
| 355 | + let _ = conn_write(conn, protocol.encode(protocol.Terminate)) |
| 356 | + match conn { |
| 357 | + Tcp(c) -> net.close(c), |
| 358 | + Tls(c) -> tls.close(c), |
| 359 | + } |
| 360 | +} |
| 361 | + |
| 362 | +// ---- parameters --------------------------------------------------------------- |
| 363 | + |
| 364 | +/// A parameter in text format; `Null` is SQL `NULL`. |
| 365 | +fn encode_param(param: Value) -> Option<Bytes> { |
| 366 | + match param { |
| 367 | + Null -> None, |
| 368 | + value -> Some(bytes.from_string(show(value))), |
| 369 | + } |
| 370 | +} |
| 371 | + |
| 372 | +/// The text format on the wire (`True`/`False` for booleans: PostgreSQL |
| 373 | +/// reads them; `\x…` for bytea). In a `sql` template (lib.lse), write SQL |
| 374 | +/// `null` literally — `Null` has no text. |
| 375 | +impl Show<Value> { |
| 376 | + fn show(value) { |
| 377 | + match value { |
| 378 | + Null -> "", |
| 379 | + Integer(n) -> "{n}", |
| 380 | + Real(f) -> "{f}", |
| 381 | + Boolean(b) -> if b { "True" } else { "False" }, |
| 382 | + Text(s) -> s, |
| 383 | + Bytea(b) -> "\\x" <> hex(b), |
| 384 | + } |
| 385 | + } |
| 386 | +} |
| 387 | + |
| 388 | +/// Lowercase hex. |
| 389 | +fn hex(b: Bytes) -> String { |
| 390 | + string.concat(list.map(bytes.to_list(b), hex_byte)) |
| 391 | +} |
| 392 | + |
| 393 | +fn hex_byte(b: Int) -> String { |
| 394 | + "{hex_digit(b / 16)}{hex_digit(b % 16)}" |
| 395 | +} |
| 396 | + |
| 397 | +fn hex_digit(d: Int) -> String { |
| 398 | + match d { |
| 399 | + 10 -> "a", |
| 400 | + 11 -> "b", |
| 401 | + 12 -> "c", |
| 402 | + 13 -> "d", |
| 403 | + 14 -> "e", |
| 404 | + 15 -> "f", |
| 405 | + _ -> "{d}", |
| 406 | + } |
| 407 | +} |