@amritk/nish-aarch64-darwin 0.34.1 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. package/INSTALL.md +22 -13
  2. package/bin/nish +0 -0
  3. package/docs/AI.md +86 -16
  4. package/package.json +1 -1
  5. package/runtime/async.d.mts +49 -0
  6. package/runtime/async.mjs +27 -0
  7. package/runtime/nish.d.ts +4681 -427
  8. package/runtime/nish.h +6 -2
  9. package/runtime/nish.mjs +4 -0
  10. package/runtime/runtime-net.c +22 -0
  11. package/runtime/runtime-shm.c +93 -2
  12. package/runtime/vite.d.ts +30 -0
  13. package/runtime/vite.mjs +150 -0
  14. package/scripts/build.sh +108 -13
  15. package/std/README.md +131 -131
  16. package/std/base64.ts +34 -5
  17. package/std/bytes.ts +258 -42
  18. package/std/cli-args.ts +296 -70
  19. package/std/cli-flags.ts +184 -19
  20. package/std/cli.ts +475 -54
  21. package/std/collections.ts +121 -23
  22. package/std/compress/checksum.ts +44 -14
  23. package/std/compress/deflate.ts +224 -111
  24. package/std/compress/gzip.ts +217 -53
  25. package/std/compress/zlib.ts +63 -7
  26. package/std/crypto/aes.ts +80 -9
  27. package/std/crypto/base64url.ts +22 -0
  28. package/std/crypto/bcrypt-batch.ts +88 -21
  29. package/std/crypto/bcrypt.ts +60 -0
  30. package/std/crypto/chacha20poly1305.ts +53 -0
  31. package/std/crypto/ct.ts +32 -13
  32. package/std/crypto/ed25519.ts +47 -0
  33. package/std/crypto/hkdf.ts +198 -13
  34. package/std/crypto/hmac.ts +235 -31
  35. package/std/crypto/jwt.ts +192 -63
  36. package/std/crypto/p256.ts +159 -16
  37. package/std/crypto/p384.ts +28 -3
  38. package/std/crypto/pki-roots.ts +32 -2
  39. package/std/crypto/pki.ts +81 -15
  40. package/std/crypto/rsa.ts +33 -3
  41. package/std/crypto/sha1.ts +3 -0
  42. package/std/crypto/sha256.ts +24 -1
  43. package/std/crypto/sha512.ts +99 -14
  44. package/std/crypto/x25519.ts +152 -14
  45. package/std/crypto/x509-random.ts +10 -0
  46. package/std/crypto/x509.ts +67 -7
  47. package/std/json-equal.ts +19 -0
  48. package/std/json-format.ts +112 -13
  49. package/std/json-number.ts +64 -14
  50. package/std/json-pointer.ts +23 -1
  51. package/std/json-tokenizer.ts +100 -29
  52. package/std/json-typed.ts +713 -66
  53. package/std/json-value.ts +400 -124
  54. package/std/json.ts +138 -10
  55. package/std/map.ts +25 -7
  56. package/std/math.ts +36 -4
  57. package/std/net/buffer-pool.ts +42 -11
  58. package/std/net/dns-config.ts +109 -23
  59. package/std/net/dns-message.ts +62 -7
  60. package/std/net/dns-resolver.ts +247 -53
  61. package/std/net/dns.ts +203 -35
  62. package/std/net/fetch.ts +151 -61
  63. package/std/net/handler.ts +278 -80
  64. package/std/net/hpack.ts +262 -52
  65. package/std/net/http-compress.ts +125 -15
  66. package/std/net/http-fields.ts +85 -9
  67. package/std/net/http1-client-codec.ts +100 -19
  68. package/std/net/http1-codec.ts +297 -77
  69. package/std/net/http1-server.ts +430 -94
  70. package/std/net/http2-frame.ts +272 -35
  71. package/std/net/http2-tls.ts +135 -34
  72. package/std/net/http2.ts +247 -106
  73. package/std/net/http3-frame.ts +154 -17
  74. package/std/net/http3-server.ts +275 -101
  75. package/std/net/http3.ts +307 -115
  76. package/std/net/outbound.ts +37 -3
  77. package/std/net/postgres-carrier.ts +144 -8
  78. package/std/net/postgres.ts +801 -112
  79. package/std/net/prefork.ts +164 -31
  80. package/std/net/qpack.ts +105 -18
  81. package/std/net/quic-conn-ack.ts +59 -12
  82. package/std/net/quic-conn-cid.ts +124 -27
  83. package/std/net/quic-conn-params.ts +70 -10
  84. package/std/net/quic-datagram.ts +43 -3
  85. package/std/net/quic-frame.ts +286 -12
  86. package/std/net/quic-listener.ts +101 -32
  87. package/std/net/quic-packet.ts +302 -21
  88. package/std/net/quic-recovery.ts +264 -52
  89. package/std/net/quic-stream.ts +353 -91
  90. package/std/net/quic.ts +1124 -201
  91. package/std/net/router.ts +87 -40
  92. package/std/net/tls/client.ts +166 -51
  93. package/std/net/tls/codec.ts +413 -56
  94. package/std/net/tls/record-client.ts +110 -55
  95. package/std/net/tls/record-server.ts +159 -59
  96. package/std/net/tls/record.ts +109 -12
  97. package/std/net/tls/schedule.ts +235 -26
  98. package/std/net/tls/ticket.ts +159 -40
  99. package/std/net/tls/verify.ts +49 -3
  100. package/std/net/tls-tcp.ts +250 -45
  101. package/std/net/tls.ts +221 -59
  102. package/std/net/upstream.ts +81 -45
  103. package/std/net/url.ts +97 -13
  104. package/std/net/websocket.ts +122 -12
  105. package/std/net/webtransport.ts +220 -89
  106. package/std/pair.ts +10 -2
  107. package/std/random.ts +34 -9
  108. package/std/regex.ts +352 -198
  109. package/std/region.ts +70 -15
  110. package/std/secret.ts +52 -11
  111. package/std/sort.ts +17 -2
  112. package/std/sqlite.ts +256 -35
  113. package/std/sync/ring.ts +430 -40
  114. package/std/sync/shm.ts +222 -15
  115. package/std/term-io.ts +137 -64
  116. package/std/term-pixels.ts +144 -19
  117. package/std/term-probe.ts +66 -25
  118. package/std/term-rate.ts +128 -57
  119. package/std/term.ts +332 -121
  120. package/std/testing.ts +130 -32
  121. package/std/text.ts +73 -7
  122. package/std/threads.ts +229 -41
  123. package/std/yaml-json.ts +94 -82
  124. package/std/yaml-lines.ts +47 -15
  125. package/std/yaml-write.ts +24 -16
  126. package/std/yaml.ts +764 -384
@@ -61,7 +61,7 @@ const OUTBOUND_V4_AT: i32 = 12
61
61
  */
62
62
  export class OutboundPolicy {
63
63
  // Declared widest first, so no byte of a policy is padding.
64
- /** The names a URL may carry, lower-cased; empty for any. See `allowHost`. */
64
+ /** The names a URL may carry, lower-cased; empty for any. See `allowHost`. @internal */
65
65
  allowHosts: string[]
66
66
  /** `OUTBOUND_PERMIT_BYTES` per prefix `permit` let through. */
67
67
  permitted: u8[]
@@ -72,6 +72,10 @@ export class OutboundPolicy {
72
72
  /** At most this many redirects, or the client's own limit if lower. */
73
73
  maxRedirects: i32 = 5
74
74
 
75
+ /**
76
+ * Makes the default policy the class describes: public addresses only, any
77
+ * host name, and the default limits.
78
+ */
75
79
  constructor() {
76
80
  this.allowHosts = []
77
81
  this.permitted = []
@@ -83,6 +87,7 @@ export class OutboundPolicy {
83
87
  * trailing dot do not matter. A leading dot (`.example.com`) allows the
84
88
  * name and every name under it. An address literal matches only itself,
85
89
  * as the URL writes it (`::1` or `[::1]`, `127.0.0.1`), never as a suffix.
90
+ * @param name The host name, `.`-led for a whole domain, or an address literal.
86
91
  */
87
92
  allowHost(name: string): void {
88
93
  let entry: string = outboundLower(name)
@@ -96,6 +101,8 @@ export class OutboundPolicy {
96
101
  * Lets the addresses in `cidr` through though they are not public:
97
102
  * `10.1.2.0/24`, `fd00:1::/64`, or one address alone. False, with nothing
98
103
  * added, when `cidr` is not an address and a prefix length that fits it.
104
+ * @param cidr The address, or the address and its prefix length after a `/`.
105
+ * @returns Whether the prefix was added.
99
106
  */
100
107
  permit(cidr: string): boolean {
101
108
  const n: i32 = toI32(cidr.length)
@@ -134,6 +141,10 @@ export class OutboundPolicy {
134
141
  /**
135
142
  * Whether the sixteen address bytes at `addr[off]` are public, as the module
136
143
  * comment defines it. Panics when sixteen bytes do not fit there.
144
+ *
145
+ * @param addr The array holding the address; an IPv4 one in its `::ffff:` form, as nish:net writes it.
146
+ * @param off Where the address's sixteen bytes start in `addr`.
147
+ * @returns True for a public address. An IPv4 one carried by NAT64 or 6to4 is judged as that IPv4 address.
137
148
  */
138
149
  export const outboundAddressPublic = (addr: u8[], off: i32): boolean => {
139
150
  if (off < 0 || off > toI32(addr.length) - 16) {
@@ -163,7 +174,15 @@ export const outboundAddressPublic = (addr: u8[], off: i32): boolean => {
163
174
  return !(b0 === 0x3f && b1 === 0xff && (b2 & 0xf0) === 0)
164
175
  }
165
176
 
166
- /** Whether `policy` lets a connection go to the sixteen address bytes at `addr[off]`. */
177
+ /**
178
+ * Whether `policy` lets a connection go to the sixteen address bytes at
179
+ * `addr[off]`: a prefix it `permit`s, or else a public address.
180
+ *
181
+ * @param policy The policy whose permits are checked first.
182
+ * @param addr The array holding the address; an IPv4 one in its `::ffff:` form, as nish:net writes it.
183
+ * @param off Where the address's sixteen bytes start in `addr`.
184
+ * @returns True when a connection may go there. An IPv4 address carried by NAT64 or 6to4 is judged as that address, by a permit too.
185
+ */
167
186
  export const outboundAddressAllowed = (policy: OutboundPolicy, addr: u8[], off: i32): boolean => {
168
187
  if (outboundPermitted(policy, addr, off)) {
169
188
  return true
@@ -189,6 +208,11 @@ export const outboundAddressAllowed = (policy: OutboundPolicy, addr: u8[], off:
189
208
  * Keeps the addresses of `count` `DNS_ADDRESS_BYTES` records in `addresses`
190
209
  * that `policy` allows, moved to the front in their order, and answers how
191
210
  * many. Refused records are left behind them, so the caller can name one.
211
+ *
212
+ * @param policy The policy each address is checked against, as `outboundAddressAllowed` checks it.
213
+ * @param addresses The records, each sixteen address bytes and a two-byte port, reordered in place.
214
+ * @param count How many records `addresses` holds from its start; one that does not fit panics.
215
+ * @returns How many records were kept, now `addresses`' first ones; 0 when every one was refused.
192
216
  */
193
217
  export const outboundFilter = (policy: OutboundPolicy, addresses: u8[], count: i32): i32 => {
194
218
  if (count < 0 || count * DNS_ADDRESS_BYTES > toI32(addresses.length)) {
@@ -216,6 +240,10 @@ export const outboundFilter = (policy: OutboundPolicy, addresses: u8[], count: i
216
240
  * Whether `policy` lets a URL name `host`, as the URL parser gives it
217
241
  * (lower-cased, an IPv6 literal without its brackets). Any host when the
218
242
  * policy names none.
243
+ *
244
+ * @param policy The policy whose `allowHost` names are checked.
245
+ * @param host The URL's host; its case and one trailing dot do not matter.
246
+ * @returns True when the host is one the policy names, or under a `.`-led name it allows, or the policy names none.
219
247
  */
220
248
  export const outboundHostAllowed = (policy: OutboundPolicy, host: string): boolean => {
221
249
  if (policy.allowHosts.length === 0) {
@@ -239,7 +267,13 @@ export const outboundHostAllowed = (policy: OutboundPolicy, host: string): boole
239
267
  return false
240
268
  }
241
269
 
242
- /** The sixteen address bytes at `addr[off]` as text: dotted for an IPv4 address, eight hex groups otherwise. */
270
+ /**
271
+ * The sixteen address bytes at `addr[off]` as text, for an error to name.
272
+ *
273
+ * @param addr The array holding the address.
274
+ * @param off Where the address's sixteen bytes start in `addr`.
275
+ * @returns Dotted decimal for an IPv4 address in its `::ffff:` form, otherwise all eight lower-case hex groups with no `::` shortening.
276
+ */
243
277
  export const outboundAddressText = (addr: u8[], off: i32): string => {
244
278
  if (outboundMapped(addr, off)) {
245
279
  const at: i32 = off + OUTBOUND_V4_AT
@@ -1,9 +1,53 @@
1
1
  /**
2
- * nish/net/postgres-carrier: `PgCarrier`, a `PgPool`'s queries on an
2
+ * `nish/net/postgres-carrier` — `PgCarrier`, a `PgPool`'s queries on an
3
3
  * `HttpHandler`'s loop, so a route handler queries PostgreSQL without
4
4
  * blocking its worker.
5
5
  *
6
- * `nish/net/postgres` reads no socket, clock or entropy source; this module is
6
+ * import { HttpRequest } from "nish/net/handler"
7
+ * import { PgConnection, pgTarget } from "nish/net/postgres"
8
+ * import {
9
+ * PG_CARRIER_BUILD, PG_CARRIER_DONE, PG_CARRIER_FAILED, PG_CARRIER_FULL,
10
+ * PG_CARRIER_MISSING, PG_CARRIER_NONE, PG_CARRIER_ROW, PgCarrier, PgCarrierLimits,
11
+ * } from "nish/net/postgres-carrier"
12
+ *
13
+ * // A sketch: `pool` registered "article"; `handler` serves the routes;
14
+ * // `ARTICLE` is the route's tag, `running` the server's loop condition,
15
+ * // and `text` and `none` the program's content-type and empty body.
16
+ * const carrier = new PgCarrier(new PgCarrierLimits(), pool, pgTarget("127.0.0.1", 5432), handler)
17
+ * const answered: boolean[] = new Array<boolean>(256) // one per query number
18
+ * while (running) {
19
+ * handler.wait(50) // a timeout, so the connect timeout is checked
20
+ * while (handler.ready()) {
21
+ * const req: HttpRequest = handler.take()
22
+ * if (carrier.run(req, ARTICLE) === PG_CARRIER_FULL) {
23
+ * handler.send(req, 503, text, none, 0, 0)
24
+ * }
25
+ * }
26
+ * let event: i32 = carrier.next()
27
+ * while (event !== PG_CARRIER_NONE) {
28
+ * if (event === PG_CARRIER_BUILD) {
29
+ * const conn: PgConnection = carrier.connection()
30
+ * conn.bindStart("article")
31
+ * conn.paramInt(toI64(carrier.request().paramDecimal(0)))
32
+ * conn.bindEnd()
33
+ * carrier.send()
34
+ * } else if (event === PG_CARRIER_ROW && !answered[carrier.query]) {
35
+ * const conn: PgConnection = carrier.connection()
36
+ * handler.send(carrier.request(), 200, text, conn.inputBuffer(), conn.colStart(0), conn.colLength(0))
37
+ * answered[carrier.query] = true
38
+ * } else if (event === PG_CARRIER_DONE || event === PG_CARRIER_MISSING || event === PG_CARRIER_FAILED) {
39
+ * if (!answered[carrier.query]) {
40
+ * handler.send(carrier.request(), event === PG_CARRIER_FAILED ? 503 : 404, text, none, 0, 0)
41
+ * }
42
+ * answered[carrier.query] = false
43
+ * }
44
+ * event = carrier.next()
45
+ * }
46
+ * }
47
+ * carrier.close()
48
+ * pool.dispose()
49
+ *
50
+ * **Why a module of its own.** `nish/net/postgres` reads no socket, clock or entropy source; this module is
7
51
  * the one that does, and it is kept apart so that one stays sans-IO. The
8
52
  * carrier's sockets sit in an epoll set the handler watches (`HttpHandler.watch`), a
9
53
  * route handler hands a request to `run` (or to `runInt` and `runText` for an
@@ -14,6 +58,28 @@
14
58
  * itself, gives up on one that has not answered in `connectTimeoutMs`, and
15
59
  * sizes every table from `PgCarrierLimits` at construction.
16
60
  *
61
+ * **Lifetime.** A query number from `run`, `runInt` or `runText`, with its
62
+ * `tag` and `request()`, holds until the `next()` after its final event,
63
+ * which frees the number for reuse; a row's bytes on `connection()` hold
64
+ * only until the next call. The carrier never answers a request itself: the
65
+ * program answers each one once, on its first row or on its final event.
66
+ *
67
+ * **Limits.** Every cap is fixed at construction (`PgCarrierLimits`), so a
68
+ * full carrier answers `PG_CARRIER_FULL` rather than grow, and once the
69
+ * connections are up nothing is allocated per query. There is no deadline on
70
+ * a query once its connection is up; bound a slow statement with the
71
+ * server's `statement_timeout`.
72
+ *
73
+ * **Errors.** A connection that is refused, reset, closed or past its connect
74
+ * timeout fails every query on it with `PG_CARRIER_FAILED`, `failure` the
75
+ * connection's `PG_ERR_*` and `socketError` the socket's negative errno
76
+ * (`-110` for the timeout, 0 when the server closed cleanly). A plain query
77
+ * the server refuses answers `PG_CARRIER_ERROR`, then `PG_CARRIER_FAILED`
78
+ * with `failure` `PG_ERR_NONE`; a batched query the server refuses answers
79
+ * only `PG_CARRIER_FAILED` with `failure` `PG_ERR_NONE`.
80
+ * Programming errors (a cap out of range, an unknown batcher id, `send()`
81
+ * with no build open) panic.
82
+ *
17
83
  * `tests/link/std_postgres_carrier` runs one against a loopback backend;
18
84
  * `tests/postgres/carrier.ts` against a live server. Caps and findings:
19
85
  * `docs/security/postgres.md`.
@@ -216,7 +282,16 @@ export class PgCarrier {
216
282
  /**
217
283
  * A carrier for `pool`'s connections to `target`, its descriptor watched on
218
284
  * `handler` as `limits.watch`. Panics on a cap or watch id out of range,
219
- * or a target that failed or is not a numeric address.
285
+ * a target that failed or is not a numeric address, or a poll set the
286
+ * system will not create. It allocates every table here and opens its poll
287
+ * set, but connects nothing until the first `next()`.
288
+ *
289
+ * @param limits The caps, read once; changing them later changes nothing.
290
+ * @param pool The pool whose slots the carrier connects and drives. It
291
+ * stays the program's, to `dispose()` after `close()`.
292
+ * @param target Where to connect: a Unix socket, or a numeric address and
293
+ * port, as `pgTarget` parsed it; a host name panics.
294
+ * @param handler The handler whose `wait` watches the carrier's sockets.
220
295
  */
221
296
  constructor(limits: PgCarrierLimits, pool: PgPool, target: PgTarget, handler: HttpHandler) {
222
297
  const queries: i32 = limits.queries
@@ -296,7 +371,11 @@ export class PgCarrier {
296
371
  * Registers `batcher`'s statement on the pool and answers its id for
297
372
  * `runInt` and `runText`. Panics past 8 batchers, and wherever
298
373
  * `PgPool.register` refuses: once the pool has connected, on a NUL in the
299
- * batcher's name or SQL, or past 256 statements.
374
+ * batcher's name or SQL, or past 256 statements. Attach every batcher
375
+ * before the first `next()`, which starts connecting.
376
+ *
377
+ * @param batcher The batcher to route keys to; the carrier keeps it.
378
+ * @returns The batcher's id, 0 for the first attached and counting up.
300
379
  */
301
380
  attach(batcher: PgBatcher): i32 {
302
381
  const id: i32 = toI32(this.batchers.length)
@@ -315,6 +394,13 @@ export class PgCarrier {
315
394
  * answers its number; `PG_CARRIER_BUILD` comes for it once a connection
316
395
  * has room. `PG_CARRIER_FULL` when `queries` are waiting, the pool's
317
396
  * queue is full or the carrier is closed. Returns at once.
397
+ *
398
+ * @param req The request the query answers, handed back by `request()`;
399
+ * null for a query of the program's own.
400
+ * @param tag The program's own number for what was asked, handed back as
401
+ * `tag` on every event of the query.
402
+ * @returns The query's number, 0 up to `queries - 1` and reused once its
403
+ * final event has passed, or `PG_CARRIER_FULL`.
318
404
  */
319
405
  run(req: HttpRequest | null, tag: i32): i32 {
320
406
  const q: i32 = this.take(req, tag)
@@ -331,7 +417,19 @@ export class PgCarrier {
331
417
  return q
332
418
  }
333
419
 
334
- /** Queues `req`'s int8 `key` on batcher `batcher`, as `run` does a plain query; `PG_CARRIER_FULL` also when the batcher's queue is. */
420
+ /**
421
+ * Queues `req`'s int8 `key` on batcher `batcher`, as `run` does a plain
422
+ * query: the carrier sends it with the other keys waiting on that batcher
423
+ * in one execution, and answers its rows to this query alone. Panics on an
424
+ * id `attach` never gave, or a batcher whose key is text.
425
+ *
426
+ * @param req The request the key answers; null for the program's own.
427
+ * @param batcher The id `attach` answered.
428
+ * @param key The key to look up.
429
+ * @param tag The program's own number, handed back as `tag`.
430
+ * @returns The query's number, or `PG_CARRIER_FULL` when `queries` are
431
+ * waiting, the batcher's queue is full or the carrier is closed.
432
+ */
335
433
  runInt(req: HttpRequest | null, batcher: i32, key: i64, tag: i32): i32 {
336
434
  const b: PgBatcher = this.batcher(batcher)
337
435
  const q: i32 = this.take(req, tag)
@@ -345,7 +443,24 @@ export class PgCarrier {
345
443
  return q
346
444
  }
347
445
 
348
- /** Queues `req`'s text key `bytes[start, start + length)` on batcher `batcher`, as `runInt` does; also `PG_CARRIER_FULL` when `PgBatcher.addText` refuses the key. */
446
+ /**
447
+ * Queues `req`'s text key `bytes[start, start + length)` on batcher
448
+ * `batcher`, as `runInt` does an int8 key. The key is copied into the
449
+ * batcher's own store, so `bytes` may change once this returns. Panics on
450
+ * an id `attach` never gave, a batcher whose key is int8, or a window
451
+ * outside `bytes`.
452
+ *
453
+ * @param req The request the key answers; null for the program's own.
454
+ * @param batcher The id `attach` answered.
455
+ * @param bytes The buffer holding the key, such as the request's own bytes.
456
+ * @param start Where the key starts in `bytes`, in bytes.
457
+ * @param length The key's length in bytes.
458
+ * @param tag The program's own number, handed back as `tag`.
459
+ * @returns The query's number, or `PG_CARRIER_FULL` when `queries` are
460
+ * waiting, the carrier is closed, or `PgBatcher.addText` refuses the key:
461
+ * one that is not UTF-8 or holds a NUL, a full queue or key store, or a
462
+ * key too long for one execution.
463
+ */
349
464
  runText(req: HttpRequest | null, batcher: i32, bytes: u8[], start: i32, length: i32, tag: i32): i32 {
350
465
  const b: PgBatcher = this.batcher(batcher)
351
466
  const q: i32 = this.take(req, tag)
@@ -359,7 +474,13 @@ export class PgCarrier {
359
474
  return q
360
475
  }
361
476
 
362
- /** The request `query` was run for. Panics when it was run with none, or no event named a query. */
477
+ /**
478
+ * The request `query` was run for. Panics when it was run with none, or no
479
+ * event named a query.
480
+ *
481
+ * @returns The request handed to `run`, `runInt` or `runText`, valid until
482
+ * the `next()` after the query's final event.
483
+ */
363
484
  request(): HttpRequest {
364
485
  const q: i32 = this.query
365
486
  const req: HttpRequest | null = q >= 0 && q < toI32(this.qRequests.length) ? this.qRequests[q] : null
@@ -369,7 +490,14 @@ export class PgCarrier {
369
490
  return req
370
491
  }
371
492
 
372
- /** The connection the last `PG_CARRIER_BUILD` or row is on. Panics before any. */
493
+ /**
494
+ * The connection the last `PG_CARRIER_BUILD` or row is on. Panics before
495
+ * any.
496
+ *
497
+ * @returns The pool's connection, to bind a query on after
498
+ * `PG_CARRIER_BUILD` or read a row from after `PG_CARRIER_ROW`; its row
499
+ * holds only until the next call to `next()`.
500
+ */
373
501
  connection(): PgConnection {
374
502
  const conn: PgConnection | null = this.conn
375
503
  if (conn === null) {
@@ -383,6 +511,10 @@ export class PgCarrier {
383
511
  * and answers whether it went. A bind left open is dropped, and the query
384
512
  * fails; one with nothing written fails at once, on the next `next()`.
385
513
  * Panics when no build is open.
514
+ *
515
+ * @returns True when bytes for the group go to the server, even when the
516
+ * query itself was dropped and will end `PG_CARRIER_FAILED`; false when
517
+ * nothing was written and the query fails.
386
518
  */
387
519
  send(): boolean {
388
520
  const q: i32 = this.building
@@ -418,6 +550,10 @@ export class PgCarrier {
418
550
  * connect timeout is checked here, so the program's `wait` timeout bounds
419
551
  * how late it fires. Panics while a `PG_CARRIER_BUILD` is unsent.
420
552
  * `PG_CARRIER_NONE` once the carrier is closed, which connects nothing.
553
+ * The call first frees the query whose final event it answered last.
554
+ *
555
+ * @returns One of the `PG_CARRIER_*` events, `PG_CARRIER_NONE` to stop
556
+ * calling until the handler's next turn.
421
557
  */
422
558
  next(): i32 {
423
559
  if (this.closed) {