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.

615 lignes · 17298 octetsBrut · Historique
1/// A PostgreSQL client (issue gabla108/louise#145): one actor per connection, SQL
2/// written as text with `$1` parameters — values never reach the SQL
3/// text, so the API has no injection to build.
4///
5/// import postgres as pg
6///
7/// use conn <- result.try(pg.connect(pg.config("postgres://ada:secret@db.internal/orders")))
8/// pg.query(conn, "select version from streams where id = $1", [pg.text(stream)])
9///
10/// The wire protocol (version 3.0, extended query only) is pure Louise
11/// (`protocol`); SCRAM-SHA-256 runs over `std/crypto`; TLS upgrades per
12/// `sslmode` (`std/tls`).
13
14import std/actor.{Timeout}
15import std/dec as decs
16import std/list
17import std/net
18import std/process.{type Pid, type Subject, type proc}
19import std/random.{type random}
20import std/result
21import std/string
22import std/template.{type Hole, type Template, Embed, Template, Text}
23import std/time.{type Timestamp}
24
25import client
26import config.{defaults}
27import pool
28import protocol
29import protocol.{type Field}
30import row
31import uuid
32
33/// A connection's settings; parse a `postgres://` URL, or start from
34/// `postgres.config_defaults()` and update fields.
35pub type Config = config.Config
36
37/// How TLS is wanted (`disable`, `prefer`, `require`).
38pub type TlsMode = config.TlsMode
39
40/// What a call failed with (`Io`, `Server` with its fields, `Driver`).
41pub type Error = client.Error
42
43/// A parameter's value: `Null`, `Integer`, `Real`, `Boolean`, `Text`,
44/// `Bytea`.
45pub type Value = client.Value
46
47/// A row set's columns and rows.
48pub type QueryResult = client.QueryResult
49
50/// A row; read it by column name with `text`, `int`, `bool`, `bytea`.
51pub type Row = client.Row
52
53/// The `sql` effect (issue gabla108/louise#145 §3): queries against the ambient
54/// connection — a transaction's, or one checked out for the statement.
55/// Handled by `with_connection` and `transaction`; domain code can be
56/// tested with an in-memory handler, never touching a database.
57pub effect sql
58{
59 fn query :: sql: String params: List<Value> -> Result<QueryResult, Error>
60 fn execute :: sql: String params: List<Value> -> Result<Int, Error>
61 fn query_statement :: statement: Statement -> Result<QueryResult, Error>
62 fn execute_statement :: statement: Statement -> Result<Int, Error>
63}
64
65/// A live connection (one actor; it owns the socket). It carries the
66/// backend key data from the handshake, so `cancel` needs no round trip
67/// (a busy connection answers nothing until its query ends).
68pub opaque type Connection
69{ Connection(
70 subject: Subject<client.Msg>
71 , host: String
72 , port: Int
73 , backend: Option<(Int, Int)>
74 )
75}
76
77/// A pool of connections.
78pub type Pool = pool.Pool
79
80/// The pool's knobs (`min_idle`, `idle_timeout`, `max_lifetime`,
81/// `check_after`, `tick`): see `pool.PoolSettings`.
82pub type PoolSettings = pool.PoolSettings
83
84/// A pool of `size` connections, made now; dead ones are replaced as
85/// they're needed. The pool runs under no supervisor: supervise the
86/// caller (`std/supervisor`) and start it again on a crash.
87pub fn start_pool ::
88 cfg: Config
89 size: Int
90 -> Result<Pool, Error> / <io, proc, random>
91{
92 pool.start cfg size
93}
94
95/// The default pool settings for `size` connections (no reaping, a
96/// liveness check past 30 s idle), to update field by field:
97/// `PoolSettings(..postgres.pool_settings(10), min_idle: 2)`.
98pub fn pool_settings :: size: Int -> PoolSettings
99{
100 pool.defaults size
101}
102
103/// A pool with explicit settings.
104pub fn start_pool_with ::
105 cfg: Config
106 settings: PoolSettings
107 -> Result<Pool, Error> / <io, proc, random>
108{
109 pool.start_with cfg settings
110}
111/// `postgres://user:password@host:port/database?sslmode=...`. The error
112/// never quotes the URL (it may hold a password).
113pub fn config :: url: String -> Result<Config, String>
114{
115 config.parse url
116}
117
118/// The default settings (localhost, no password, `prefer` TLS), to update
119/// field by field: `Config(..postgres.config_defaults(), user: "ada")`.
120pub fn config_defaults :: -> Config
121{
122 defaults ()
123}
124
125/// Connect and authenticate.
126pub fn connect :: cfg: Config -> Result<Connection, Error> / <io, proc, random>
127{
128 use socket <- result.try (client.connect_socket cfg)
129 Ok( Connection( client.connect_over socket
130 , socket.host
131 , socket.port
132 , socket.backend
133 )
134 )
135}
136
137/// The SQLSTATE of a server error, if it has one.
138pub fn sqlstate :: e: Error -> Option<String>
139{
140 client.sqlstate e
141}
142
143/// A server error's message, or the error's text.
144pub fn error_message :: e: Error -> String
145{
146 client.message e
147}
148
149/// A driver-side error (handlers mapping to their own error types use
150/// it): `pg.driver("...")`.
151pub fn driver :: message: String -> Error
152{
153 client.Driver(message)
154}
155
156/// Rows for the SQL and its parameters (none for `NULL`), on an explicit
157/// connection. The ambient form is the `sql` effect's `query` (see
158/// `with_connection`).
159pub fn query_on ::
160 conn: Connection
161 sql: String
162 params: List<Value>
163 -> Result<QueryResult, Error> / <proc>
164{
165 let Connection(subject, ..) = conn
166 run_on subject sql params
167}
168
169/// A statement that returns no rows; the number of rows it changed (the
170/// command tag's count).
171pub fn execute_on ::
172 conn: Connection
173 sql: String
174 params: List<Value>
175 -> Result<Int, Error> / <proc>
176{
177 use res <- result.try (query_on conn sql params)
178 rows_affected res.tag
179}
180
181/// A query on a connection actor's subject.
182fn run_on ::
183 subject: Subject<client.Msg>
184 text: String
185 params: List<Value>
186 -> Result<QueryResult, Error> / <proc>
187{
188 actor.try_call subject client.DoQuery(text, params, _) 30000
189 |> result.map_error fn (Timeout) { client.Driver("the query timed out") }
190 |> result.flatten
191}
192
193fn run_execute ::
194 subject: Subject<client.Msg>
195 text: String
196 params: List<Value>
197 -> Result<Int, Error> / <proc>
198{
199 use res <- result.try (run_on subject text params)
200 rows_affected res.tag
201}
202
203// ---- the pool's statements ------------------------------------------------------
204
205/// One statement's connection, checked out of the pool and returned
206/// however the action ends: `use <- postgres.with_connection(pool)`.
207///
208/// use <- pg.with_connection(pool)
209/// use rows <- result.try(pg.query("select ...", [pg.text(name)]))
210/// ...
211///
212/// An unwind (a panic, a kill) crashes the borrower: the pool's monitor
213/// then closes the connection rather than reusing it, so no connection
214/// leaks when an actor crashes. A `final ctl` past the block abandons it
215/// without one — don't do that today (the connection is reclaimed when
216/// the borrower stops).
217pub fn with_connection ::
218 p: Pool
219 action: fn() -> a / <sql, proc | e>
220 -> Result<a, Error> / <proc | e>
221{
222 use conn <- result.try (pool.acquire p 5000)
223 let outcome = handle
224 {
225 action ()
226 }
227 with
228 { query text params -> run_on conn text params
229 , execute text params -> run_execute conn text params
230 , query_statement stmt ->
231 {
232 let Statement(text, params) = stmt
233 run_on conn text params
234 }
235 , execute_statement stmt ->
236 {
237 let Statement(text, params) = stmt
238 run_execute conn text params
239 }
240 }
241 pool.release p conn
242 Ok(outcome)
243}
244
245/// `transaction` with retries of serialization failures (SQLSTATE
246/// `40001`) and deadlocks (`40P01`): the action must be safe to rerun.
247/// `retries` is the number of *re*-tries after the first attempt.
248pub fn transaction_retry ::
249 p: Pool
250 retries: Int
251 action: fn() -> Result<a, Error> / <sql, proc | e>
252 -> Result<a, Error> / <proc | e>
253{
254 match transaction p action
255 { Error
256 ( e
257 ) -> if retries > 0 && is_transient e
258 {
259 transaction_retry p (retries - 1) action
260 }
261 else
262 {
263 Error(e)
264 }
265 , ok -> ok
266 }
267}
268
269/// A serialization failure (`40001`) or deadlock (`40P01`) is transient:
270/// the same transaction may go through on a fresh attempt.
271fn is_transient :: e: Error -> Bool
272{
273 sqlstate e == Some("40001") || sqlstate e == Some("40P01")
274}
275
276/// A savepoint: `pg.savepoint(fn() { ... })` inside a `transaction` (or
277/// `with_connection`) block. On an `Error` the block's writes are rolled
278/// back to the savepoint and the error returned; the transaction
279/// continues. Nesting works (names are generated).
280///
281/// PostgreSQL runs `SAVEPOINT` only inside a transaction, so a savepoint
282/// outside one is a server error — use `transaction` for the outer block.
283pub fn savepoint ::
284 action: fn() -> Result<a, Error> / <sql, proc | e>
285 -> Result<a, Error> / <sql, proc, random | e>
286{
287 let name = "sp_" <> random.token 4
288 use _ <- result.try (execute ("savepoint " <> name) [])
289 match action ()
290 { Ok(value) ->
291 {
292 use _ <- result.try (execute ("release savepoint " <> name) [])
293 Ok(value)
294 }
295 , Error(e) ->
296 {
297 let _ = execute ("rollback to savepoint " <> name) []
298 Error(e)
299 }
300 }
301}
302
303/// `use <- postgres.transaction(pool)`: `BEGIN`, run the block, `COMMIT`;
304/// on an `Error`, `ROLLBACK` first. The connection is checked out
305/// exclusively for the block and always relinquished; an uncertain COMMIT
306/// outcome closes it instead of reusing it. On an unwind the borrower
307/// crashes and the pool closes the connection (see
308/// `with_connection`).
309///
310/// Don't nest transactions (no savepoints yet); retry `40001`/`40P01`
311/// yourself for now.
312pub fn transaction ::
313 p: Pool
314 action: fn() -> Result<a, Error> / <sql, proc | e>
315 -> Result<a, Error> / <proc | e>
316{
317 match pool.acquire p 5000
318 { Error(e) -> Error(e)
319 , Ok(conn) ->
320 {
321 match run_on conn "begin" []
322 { Error(e) ->
323 {
324 pool.release p conn
325 Error(e)
326 }
327 , Ok(_) ->
328 {
329 let outcome = handle
330 {
331 action ()
332 }
333 with
334 { query text params -> run_on conn text params
335 , execute text params -> run_execute conn text params
336 , query_statement stmt ->
337 {
338 let Statement(text, params) = stmt
339 run_on conn text params
340 }
341 , execute_statement stmt ->
342 {
343 let Statement(text, params) = stmt
344 run_execute conn text params
345 }
346 }
347 match outcome
348 { Ok(value) -> match run_on conn "commit" []
349 { Ok(_) ->
350 {
351 pool.release p conn
352 Ok(value)
353 }
354 , Error(e) ->
355 {
356 // COMMIT may have completed before the error. Never reuse
357 // the connection, but always relinquish its pool slot.
358 pool.discard p conn
359 Error(e)
360 }
361 }
362 , Error(e) ->
363 {
364 let _ = run_on conn "rollback" []
365 pool.release p conn
366 Error(e)
367 }
368 }
369 }
370 }
371 }
372 }
373}
374
375/// "INSERT 0 1", "UPDATE 3": the count is the tag's last word; DDL tags
376/// ("CREATE TABLE") name no rows and count as 0.
377fn rows_affected :: tag: String -> Result<Int, Error>
378{
379 match list.reverse (string.split tag " ")
380 { [word, ..] -> match string.to_int word { Ok(n) -> Ok(n), Error(_) -> Ok(0) }
381 , [] -> Error(client.Driver("an empty command tag"))
382 }
383}
384
385/// End the connection politely (`Terminate`).
386pub fn close :: conn: Connection -> () / <proc>
387{
388 let Connection(subject, ..) = conn
389 actor.call subject client.Close(_) 5000
390}
391
392/// Cancel the query the connection is running (PostgreSQL's
393/// `CancelRequest`, on a fresh connection). Best effort: the server may
394/// answer the query first.
395pub fn cancel :: conn: Connection -> Result<(), Error> / <io>
396{
397 match conn.backend
398 { None -> Error(client.Driver("no backend key data"))
399 , Some((pid, secret)) ->
400 {
401 use tcp <-
402 result.try
403 (net.connect conn.host conn.port |> result.map_error client.Io)
404 let _ =
405 net.write tcp (protocol.encode protocol.CancelRequest(pid, secret))
406 net.close tcp
407 Ok(())
408 }
409 }
410}
411
412// ---- LISTEN/NOTIFY -------------------------------------------------------------
413
414/// A notification from a `LISTEN`ed channel.
415pub type Notification = client.Notification
416
417/// A channel being listened to (one dedicated connection, outside the
418/// pool). Stop it with `unlisten`.
419pub opaque type Listener { Listener(Pid) }
420
421/// Listen on `channel`; each of its notifications goes to `subscriber`
422/// (a subject of the caller's: `process.subject()`). The listener is a
423/// dedicated connection actor; supervise it and it re-`LISTEN`s after a
424/// restart.
425pub fn listen ::
426 cfg: Config
427 channel: String
428 subscriber: Subject<Notification>
429 -> Result<Listener, Error> / <io, proc, random>
430{
431 client.listen cfg channel subscriber |> result.map Listener
432}
433
434/// Stop listening (the connection closes).
435pub fn unlisten :: listener: Listener -> () / <proc>
436{
437 let Listener(pid) = listener
438 process.kill pid
439}
440
441// ---- parameters ---------------------------------------------------------------
442
443pub fn text :: s: String -> Value
444{
445 client.Text(s)
446}
447pub fn int :: n: Int -> Value
448{
449 client.Integer(n)
450}
451pub fn float :: f: Float -> Value
452{
453 client.Real(f)
454}
455pub fn bool :: b: Bool -> Value
456{
457 client.Boolean(b)
458}
459pub fn bytea :: b: Bytes -> Value
460{
461 client.Bytea(b)
462}
463/// A `NUMERIC` parameter (OID 1700, binary on the wire; ADR 0070).
464pub fn dec :: d: decs.Dec -> Value
465{
466 client.Decimal(d)
467}
468pub fn null :: -> Value
469{
470 client.Null
471}
472
473// ---- rows ---------------------------------------------------------------------
474
475/// The value of column `name` as text (`None` is NULL).
476pub fn row_text :: r: Row name: String -> Result<Option<String>, String>
477{
478 row.text r name
479}
480
481/// The value of column `name` as an `Int`.
482pub fn row_int :: r: Row name: String -> Result<Option<Int>, String>
483{
484 row.int r name
485}
486
487/// The value of column `name` as a `Bool`.
488pub fn row_bool :: r: Row name: String -> Result<Option<Bool>, String>
489{
490 row.bool r name
491}
492
493/// The value of column `name` as bytes.
494pub fn row_bytea :: r: Row name: String -> Result<Option<Bytes>, String>
495{
496 row.bytea r name
497}
498
499/// The value of column `name` as a `uuid.Uuid`.
500pub fn row_uuid :: r: Row name: String -> Result<Option<uuid.Uuid>, String>
501{
502 row.uuid r name
503}
504
505/// The value of column `name` as a `time.Timestamp`.
506pub fn row_timestamptz ::
507 r: Row
508 name: String
509 -> Result<Option<time.Timestamp>, String>
510{
511 row.timestamptz r name
512}
513
514/// The value of column `name` as a `decs.Dec` (`NUMERIC`; rounds
515/// half-even past 18 places, an `Error` on NaN, infinity or out of
516/// range).
517pub fn row_dec :: r: Row name: String -> Result<Option<decs.Dec>, String>
518{
519 row.dec r name
520}
521
522/// The row's columns (names, type OIDs).
523pub fn row_columns :: r: Row -> List<Field>
524{
525 let client.Row(columns, _) = r
526 columns
527}
528
529// ---- the sql template ---------------------------------------------------------
530
531/// A `sql` template's statement: the text with `$1`..`$n` placeholders
532/// and the parameters in order.
533pub type Statement { Statement(text: String, params: List<Value>) }
534
535/// `sql`select version from streams where id = {stream}`` (ADR 0048):
536/// each hole becomes a parameter — `$1`, `$2`, ... — never SQL text, so a
537/// template cannot build an injection. A hole's `Show` text is the
538/// parameter's wire encoding (write `pg.bool`/`pg.bytea` for the types
539/// that need them, and SQL `null` literally). A `pg.bytea` hole travels
540/// as its `\x…` text form; for a large value prefer `query_on`/
541/// `execute_on` with a `pg.bytea` parameter, which binds in binary
542/// (issue gabla108/louise#311).
543///
544/// import postgres as pg
545/// import postgres.{sql}
546///
547/// pg.query_statement(conn, sql`select version from streams where id = {stream}`)
548///
549/// Holes hold values only: a column or table name is SQL text, written in
550/// the template itself.
551pub fn sql :: tpl: Template<msg> -> Statement
552{
553 let Template(parts, holes) = tpl
554 build_statement parts holes [] [] 1
555}
556
557fn build_statement ::
558 parts: List<String>
559 holes: List<Hole<msg>>
560 text_acc: List<String>
561 params_acc: List<Value>
562 n: Int
563 -> Statement
564{
565 match parts
566 { [] ->
567 Statement(string.concat (list.reverse text_acc), list.reverse params_acc)
568 , [part, ..rest] ->
569 {
570 let text_acc = [part, ..text_acc]
571 match holes
572 { [] -> build_statement rest [] text_acc params_acc n
573 , [hole, ..hs] ->
574 {
575 let (marker, param) = hole_param hole n
576 build_statement
577 rest
578 hs
579 [marker, ..text_acc]
580 [param, ..params_acc]
581 (n + 1)
582 }
583 }
584 }
585 }
586}
587
588/// The `$n` marker and the parameter for a hole.
589fn hole_param :: hole: Hole<msg> n: Int -> (String, Value)
590{
591 match hole
592 { Text(s) -> ("${n}", client.Text(s))
593 , Embed(_) -> panic "an element can't be a SQL parameter"
594 }
595}
596
597/// Run a `sql` template's statement on an explicit connection.
598pub fn query_statement_on ::
599 conn: Connection
600 statement: Statement
601 -> Result<QueryResult, Error> / <proc>
602{
603 let Statement(text, params) = statement
604 query_on conn text params
605}
606
607/// `execute_on` for a `sql` template's statement.
608pub fn execute_statement_on ::
609 conn: Connection
610 statement: Statement
611 -> Result<Int, Error> / <proc>
612{
613 let Statement(text, params) = statement
614 execute_on conn text params
615}