@amritk/nish-aarch64-darwin 0.35.0 → 0.37.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 (128) hide show
  1. package/INSTALL.md +73 -59
  2. package/bin/nish +0 -0
  3. package/docs/AI.md +50 -4
  4. package/package.json +1 -1
  5. package/runtime/async.d.mts +2 -0
  6. package/runtime/async.mjs +7 -0
  7. package/runtime/nish.d.ts +4849 -430
  8. package/runtime/nish.h +25 -0
  9. package/runtime/page.d.ts +53 -0
  10. package/runtime/page.mjs +146 -0
  11. package/runtime/runtime-async.c +557 -0
  12. package/runtime/runtime-wasm.c +63 -7
  13. package/runtime/vite.d.ts +30 -0
  14. package/runtime/vite.mjs +150 -0
  15. package/scripts/build.sh +252 -15
  16. package/std/README.md +107 -82
  17. package/std/base64.ts +34 -5
  18. package/std/bytes.ts +279 -59
  19. package/std/cli-args.ts +296 -70
  20. package/std/cli-flags.ts +184 -19
  21. package/std/cli.ts +475 -54
  22. package/std/collections.ts +121 -23
  23. package/std/compress/checksum.ts +44 -14
  24. package/std/compress/deflate.ts +224 -111
  25. package/std/compress/gzip.ts +217 -53
  26. package/std/compress/zlib.ts +63 -7
  27. package/std/crypto/aes.ts +128 -52
  28. package/std/crypto/base64url.ts +29 -5
  29. package/std/crypto/bcrypt-batch.ts +101 -34
  30. package/std/crypto/bcrypt.ts +93 -27
  31. package/std/crypto/chacha20poly1305.ts +69 -14
  32. package/std/crypto/ct.ts +32 -13
  33. package/std/crypto/ed25519.ts +66 -16
  34. package/std/crypto/hkdf.ts +198 -13
  35. package/std/crypto/hmac.ts +242 -37
  36. package/std/crypto/jwt.ts +204 -72
  37. package/std/crypto/p256.ts +222 -72
  38. package/std/crypto/p384.ts +51 -23
  39. package/std/crypto/pki-roots.ts +32 -2
  40. package/std/crypto/pki.ts +99 -30
  41. package/std/crypto/rsa.ts +56 -22
  42. package/std/crypto/sha1.ts +3 -0
  43. package/std/crypto/sha256.ts +24 -1
  44. package/std/crypto/sha512.ts +99 -14
  45. package/std/crypto/x25519.ts +163 -24
  46. package/std/crypto/x509-random.ts +10 -0
  47. package/std/crypto/x509.ts +133 -66
  48. package/std/host/ring.ts +124 -0
  49. package/std/json-equal.ts +31 -11
  50. package/std/json-format.ts +112 -13
  51. package/std/json-number.ts +76 -26
  52. package/std/json-pointer.ts +23 -1
  53. package/std/json-tokenizer.ts +126 -51
  54. package/std/json-typed.ts +757 -96
  55. package/std/json-value.ts +438 -157
  56. package/std/json.ts +170 -38
  57. package/std/map.ts +25 -7
  58. package/std/math.ts +36 -4
  59. package/std/net/buffer-pool.ts +42 -11
  60. package/std/net/dns-config.ts +109 -23
  61. package/std/net/dns-message.ts +62 -7
  62. package/std/net/dns-resolver.ts +247 -53
  63. package/std/net/dns.ts +203 -35
  64. package/std/net/fetch.ts +1267 -290
  65. package/std/net/handler.ts +296 -80
  66. package/std/net/hpack.ts +290 -77
  67. package/std/net/http-compress.ts +152 -36
  68. package/std/net/http-fields.ts +85 -9
  69. package/std/net/http1-client-codec.ts +129 -44
  70. package/std/net/http1-codec.ts +279 -114
  71. package/std/net/http1-server.ts +409 -139
  72. package/std/net/http2-frame.ts +289 -51
  73. package/std/net/http2-tls.ts +152 -49
  74. package/std/net/http2.ts +314 -160
  75. package/std/net/http3-frame.ts +165 -27
  76. package/std/net/http3-server.ts +282 -131
  77. package/std/net/http3.ts +377 -173
  78. package/std/net/outbound.ts +37 -3
  79. package/std/net/postgres-carrier.ts +144 -8
  80. package/std/net/postgres.ts +898 -260
  81. package/std/net/prefork.ts +202 -65
  82. package/std/net/qpack.ts +120 -32
  83. package/std/net/quic-conn-ack.ts +60 -12
  84. package/std/net/quic-conn-cid.ts +135 -27
  85. package/std/net/quic-conn-params.ts +109 -22
  86. package/std/net/quic-datagram.ts +50 -3
  87. package/std/net/quic-frame.ts +333 -23
  88. package/std/net/quic-listener.ts +161 -75
  89. package/std/net/quic-packet.ts +373 -73
  90. package/std/net/quic-recovery.ts +287 -65
  91. package/std/net/quic-stream.ts +436 -146
  92. package/std/net/quic.ts +693 -323
  93. package/std/net/router.ts +87 -40
  94. package/std/net/tls/client.ts +167 -51
  95. package/std/net/tls/codec.ts +494 -68
  96. package/std/net/tls/record-client.ts +140 -73
  97. package/std/net/tls/record-server.ts +233 -105
  98. package/std/net/tls/record.ts +142 -36
  99. package/std/net/tls/schedule.ts +235 -26
  100. package/std/net/tls/ticket.ts +161 -40
  101. package/std/net/tls/verify.ts +57 -10
  102. package/std/net/tls-tcp.ts +308 -95
  103. package/std/net/tls.ts +276 -102
  104. package/std/net/upstream.ts +81 -45
  105. package/std/net/url.ts +109 -22
  106. package/std/net/websocket.ts +140 -26
  107. package/std/net/webtransport.ts +243 -106
  108. package/std/pair.ts +10 -2
  109. package/std/random.ts +42 -15
  110. package/std/regex.ts +422 -257
  111. package/std/region.ts +70 -15
  112. package/std/secret.ts +52 -11
  113. package/std/sort.ts +17 -2
  114. package/std/sqlite.ts +256 -35
  115. package/std/sync/ring.ts +229 -56
  116. package/std/sync/shm.ts +203 -23
  117. package/std/term-io.ts +154 -78
  118. package/std/term-pixels.ts +144 -19
  119. package/std/term-probe.ts +77 -35
  120. package/std/term-rate.ts +199 -118
  121. package/std/term.ts +400 -175
  122. package/std/testing.ts +130 -32
  123. package/std/text.ts +84 -17
  124. package/std/threads.ts +248 -56
  125. package/std/yaml-json.ts +111 -97
  126. package/std/yaml-lines.ts +47 -15
  127. package/std/yaml-write.ts +45 -30
  128. package/std/yaml.ts +764 -384
@@ -29,36 +29,40 @@
29
29
  * stops asking to be written. An event with the hang-up bit (4) goes to
30
30
  * `readable`, which is where a closed or failed socket is noticed.
31
31
  *
32
- * **Slots, built on first use; record buffers, borrowed.** The pool's size
33
- * is a cap: the constructor builds no slot, and the first `accept` into a
34
- * slot builds its handshake state and keys (TLS-3) and keeps them, so a pool
35
- * sized for its peak costs at start-up only what does not depend on the
36
- * size. `accept` hands the next connection the slot closed last, or failing
37
- * that the next never used, and reuses it once the program `close`s it
38
- * (WP34 N9). The record buffers — the bytes to send, the plaintext waiting
39
- * for the program, the record being opened and the record being read — are
40
- * borrowed from pools this server owns while a connection uses the slot, and
41
- * given back zeroed (`BufferPool.giveSecret`) when it ends, so a free slot
42
- * holds none of them ("What moves between connections" in
43
- * `docs/security/tls.md`). When every slot is busy a new connection is
44
- * accepted and closed at once, so the listener does not stay readable; the
45
- * program sees `TLS_TCP_POOL_FULL`. Each slot keeps its own `TlsServer`, which `accept` restarts for the connection, so neither the
46
- * handshake nor application data allocates anything that outlives a call:
47
- * a thousand connections through one slot leave `Arena.mark()` where the
48
- * first left it, under every suite (TLS-3 in `docs/security/tls.md`,
49
- * `tests/link/net_tls_memory`).
32
+ * **Slots, built on first use; record buffers, borrowed.** The pool's size is a
33
+ * cap: the constructor builds no slot, and the first `accept` into a slot
34
+ * builds its handshake state and keys (TLS-3) and keeps them, so a pool sized
35
+ * for its peak costs at start-up only what does not depend on the size.
36
+ * `accept` hands the next connection the slot closed last, or failing that the
37
+ * next never used, and reuses it once the program `close`s it (WP34 N9).
38
+ *
39
+ * The record buffers — the bytes to send, the plaintext waiting for the
40
+ * program, the record being opened and the record being read — are borrowed
41
+ * from pools this server owns while a connection uses the slot, and given back
42
+ * zeroed (`BufferPool.giveSecret`) when it ends, so a free slot holds none of
43
+ * them ("What moves between connections" in `docs/security/tls.md`). When every
44
+ * slot is busy a new connection is accepted and closed at once, so the listener
45
+ * does not stay readable; the program sees `TLS_TCP_POOL_FULL`.
46
+ *
47
+ * Each slot keeps its own `TlsServer`, which `accept` restarts for the
48
+ * connection, so neither the handshake nor application data allocates anything
49
+ * that outlives a call: a thousand connections through one slot leave
50
+ * `Arena.mark()` where the first left it, under every suite (TLS-3 in
51
+ * `docs/security/tls.md`, `tests/link/net_tls_memory`).
50
52
  *
51
53
  * **Randomness is the caller's.** `accept` takes the 32-byte server random and
52
54
  * the 32-byte x25519 private key the handshake uses, as `TlsServer` does, so a
53
55
  * test replays RFC 8448's trace and a server draws them with
54
56
  * `crypto.getRandomValues`. `accept` copies both into the slot and wipes the
55
57
  * caller's key array, so one buffer of each refilled for every `accept` is
56
- * safe, and refuses either when it is not 32 bytes before taking a
57
- * connection; the slot's copy of the key is wiped once the ServerHello is
58
- * written, when the handshake fails, or when the slot is closed. **Signing is the caller's**, as `TlsServer`'s is: `signP256` signs
59
- * the CertificateVerify with a P-256 key the caller holds as a `Secret` and
60
- * borrows for the call, and `signatureInput` / `sign` hand the input out and
61
- * take any signature back.
58
+ * safe, and refuses either when it is not 32 bytes before taking a connection;
59
+ * the slot's copy of the key is wiped once the ServerHello is written, when the
60
+ * handshake fails, or when the slot is closed.
61
+ *
62
+ * **Signing is the caller's**, as `TlsServer`'s is: `signP256` signs the
63
+ * CertificateVerify with a P-256 key the caller holds as a `Secret` and borrows
64
+ * for the call, and `signatureInput` / `sign` hand the input out and take any
65
+ * signature back.
62
66
  *
63
67
  * **Resumption is opt-in, and its keys are the caller's.** After
64
68
  * `enableTickets`, a slot whose interest says `TLS_RECORD_TICKET` waits on
@@ -75,23 +79,25 @@
75
79
  * `close` frees the slot at once; `shutdown` sends the `close_notify` as the
76
80
  * socket takes it, and the slot is done when its interest says so.
77
81
  *
78
- * **A closed connection lingers until the client hangs up.** Once a
79
- * connection the server closed has sent everything, the slot shuts the
80
- * socket's write side — the client reads the response, the `close_notify`
81
- * and then the end of the stream — and reads and throws away what the
82
- * client still sends, until its own end of stream, before its interest says
83
- * `TLS_RECORD_DONE` (RFC 9112 §9.6's staged close). A socket closed with
84
- * the client's bytes unread, or that the client writes to after the close,
85
- * answers with a TCP reset, and a client may report that reset instead of
86
- * the response it was sent: Chromium's `ERR_CONNECTION_RESET` after an HTTP/2
87
- * `GOAWAY`, when its SETTINGS acknowledgement crossed the server's close. A
88
- * lingering slot holds no key and no record buffer, asks only to be read,
89
- * and gives up past `TLS_TCP_LINGER_LIMIT` bytes. A connection that failed,
90
- * whose client sent its own `close_notify` (it writes nothing after it,
91
- * RFC 8446 §6.1) or whose client's stream had already ended, is done at
92
- * once. A client that never hangs up keeps its slot, as one that never sends
93
- * does: how long a slot may wait is the program's (`docs/security/tls.md`,
94
- * TLS-6 and TLS-4).
82
+ * **A closed connection lingers until the client hangs up.** Once a connection
83
+ * the server closed has sent everything, the slot shuts the socket's write side
84
+ * — the client reads the response, the `close_notify` and then the end of the
85
+ * stream — and reads and throws away what the client still sends, until its own
86
+ * end of stream, before its interest says `TLS_RECORD_DONE` (RFC 9112 §9.6's
87
+ * staged close).
88
+ *
89
+ * A socket closed with the client's bytes unread, or that the client writes to
90
+ * after the close, answers with a TCP reset, and a client may report that reset
91
+ * instead of the response it was sent: Chromium's `ERR_CONNECTION_RESET` after
92
+ * an HTTP/2 `GOAWAY`, when its SETTINGS acknowledgement crossed the server's
93
+ * close. A lingering slot holds no key and no record buffer, asks only to be
94
+ * read, and gives up past `TLS_TCP_LINGER_LIMIT` bytes.
95
+ *
96
+ * A connection that failed, whose client sent its own `close_notify` (it writes
97
+ * nothing after it, RFC 8446 §6.1) or whose client's stream had already ended,
98
+ * is done at once. A client that never hangs up keeps its slot, as one that
99
+ * never sends does: how long a slot may wait is the program's
100
+ * (`docs/security/tls.md`, TLS-6 and TLS-4).
95
101
  *
96
102
  * Written from RFC 8446 and docs/LANGUAGE.md's `nish:net`, not ported from
97
103
  * another implementation.
@@ -183,11 +189,11 @@ const TLS_TCP_NANOS_PER_MS: i64 = 1000000
183
189
  * `fd(slot)`.
184
190
  */
185
191
  export class TlsTcpServer {
186
- config: TlsServerConfig
192
+ private config: TlsServerConfig
187
193
  /**
188
194
  * The connections built so far, slot `k`'s at `k`: one per slot ever
189
195
  * accepted into. `connection` never adds to it; a slot never built reads
190
- * `vacant` instead.
196
+ * one shared vacant connection instead.
191
197
  */
192
198
  connections: TlsRecordServer[]
193
199
  /**
@@ -201,7 +207,7 @@ export class TlsTcpServer {
201
207
  * over, then how many bytes it has thrown away while it waits for the
202
208
  * client's end of stream, then `TLS_TCP_LINGERED` once it is done.
203
209
  */
204
- lingered: i32[]
210
+ private lingered: i32[]
205
211
  /**
206
212
  * The slots closed since they were used, a stack whose top `accept` takes
207
213
  * before it builds a slot past the high-water mark, so finding one costs
@@ -209,11 +215,11 @@ export class TlsTcpServer {
209
215
  */
210
216
  free: i32[]
211
217
  /** Where the socket is read into before a connection takes the bytes: the largest record. */
212
- scratch: u8[]
218
+ private scratch: u8[]
213
219
  /** The last accepted peer's address, in `nish:net`'s 18-byte form. */
214
220
  peer: u8[]
215
221
  /** Signs every slot's CertificateVerify in `signP256`, one for the pool, keeping nothing per signature. */
216
- signer: TlsP256Signer
222
+ private signer: TlsP256Signer
217
223
  /**
218
224
  * Each slot's own copy of its connection's server random: `TlsServer`
219
225
  * keeps the array it is given and writes it into the ServerHello only once
@@ -224,9 +230,9 @@ export class TlsTcpServer {
224
230
  */
225
231
  randoms: u8[][]
226
232
  /** How many slots the pool may hold, which `size` answers. */
227
- slots: i32 = 1
233
+ private slots: i32 = 1
228
234
  /** Whether `enableTickets` has run, so a slot built after it resumes too. */
229
- tickets: boolean = false
235
+ private tickets: boolean = false
230
236
  /**
231
237
  * What `connection` answers for every slot never built: one failed
232
238
  * connection no slot holds and every such slot shares, so the slot reads
@@ -234,7 +240,7 @@ export class TlsTcpServer {
234
240
  * session. Its first read allocates it, once per server; it has no
235
241
  * tickets, and a caller must not change it.
236
242
  */
237
- vacant: TlsRecordServer | null = null
243
+ private vacant: TlsRecordServer | null = null
238
244
  /**
239
245
  * The pools every slot borrows its record buffers from, each with a
240
246
  * ceiling of one per slot: `lent()` is 0 once every connection has ended,
@@ -242,7 +248,7 @@ export class TlsTcpServer {
242
248
  */
243
249
  pools: TlsRecordPools
244
250
  /** The listening socket, which the program made with `tcpListen` and still owns. */
245
- listener: i32 = -1
251
+ private listener: i32 = -1
246
252
 
247
253
  /**
248
254
  * A pool of `size` slots, at least one, serving `config` on `listener`, a
@@ -251,6 +257,10 @@ export class TlsTcpServer {
251
257
  * kept, and its record buffers are borrowed from `pools` while a
252
258
  * connection uses them, so a pool sized for a peak costs at start-up only
253
259
  * the read scratch, the signer and the empty pools.
260
+ *
261
+ * @param config What every slot serves: certificate chain, ALPN and the rest; every slot shares it.
262
+ * @param listener The listening socket from `tcpListen`; the program still owns it and closes it.
263
+ * @param size How many connections may be open at once; anything below 1 is taken as 1.
254
264
  */
255
265
  constructor(config: TlsServerConfig, listener: i32, size: i32) {
256
266
  this.config = config
@@ -273,6 +283,8 @@ export class TlsTcpServer {
273
283
  * entry must sit at index `k` of `connections` and `randoms`. Its handshake
274
284
  * is never given a ClientHello: `accept` restarts it for a connection with
275
285
  * real randomness, and every later connection reuses its state.
286
+ *
287
+ * @returns The new slot's connection, failed until `accept` restarts it, already pushed onto `connections`.
276
288
  */
277
289
  build(): TlsRecordServer {
278
290
  const random: u8[] = new Array<u8>(TLS_TCP_KEY_SIZE)
@@ -290,7 +302,7 @@ export class TlsTcpServer {
290
302
  * alert, so a stray call on it fails closed, and that borrows no buffer
291
303
  * until a connection moves bytes through it.
292
304
  */
293
- make(random: u8[]): TlsRecordServer {
305
+ private make(random: u8[]): TlsRecordServer {
294
306
  // A placeholder key for a first handshake, which never runs.
295
307
  const zeros: u8[] = new Array<u8>(TLS_TCP_KEY_SIZE)
296
308
  const conn: TlsRecordServer = new TlsRecordServer(new TlsServer(this.config, random, zeros))
@@ -299,12 +311,20 @@ export class TlsTcpServer {
299
311
  return conn
300
312
  }
301
313
 
302
- /** How many slots the pool has, built or not. */
314
+ /**
315
+ * How many slots the pool has, built or not.
316
+ *
317
+ * @returns The slot count the constructor settled on, at least 1.
318
+ */
303
319
  size(): i32 {
304
320
  return this.slots
305
321
  }
306
322
 
307
- /** How many slots hold a connection. */
323
+ /**
324
+ * How many slots hold a connection.
325
+ *
326
+ * @returns The number of slots with an open descriptor, lingering ones included; 0 to `size()`.
327
+ */
308
328
  busy(): i32 {
309
329
  let n: i32 = 0
310
330
  for (const fd of this.fds) {
@@ -315,12 +335,23 @@ export class TlsTcpServer {
315
335
  return n
316
336
  }
317
337
 
318
- /** Whether `slot` is a slot of this pool that holds a connection. */
338
+ /**
339
+ * Whether `slot` is a slot of this pool that holds a connection.
340
+ *
341
+ * @param slot A slot number, as `accept` answered it; any value is safe to ask about.
342
+ * @returns True when `slot` is in range and holds a descriptor, lingering or live.
343
+ */
319
344
  holds(slot: i32): boolean {
320
345
  return slot >= 0 && slot < toI32(this.fds.length) && this.fds[slot] >= 0
321
346
  }
322
347
 
323
- /** The descriptor of `slot`, for `pollAdd`; -1 for a free or unknown slot. */
348
+ /**
349
+ * The descriptor of `slot`, for `pollAdd`; -1 for a free or unknown slot.
350
+ *
351
+ * @param slot A slot number, as `accept` answered it.
352
+ * @returns The socket descriptor, which the pool still owns and closes in `close`; -1 when `slot`
353
+ * holds none.
354
+ */
324
355
  fd(slot: i32): i32 {
325
356
  return this.holds(slot) ? this.fds[slot] : -1
326
357
  }
@@ -328,9 +359,13 @@ export class TlsTcpServer {
328
359
  /**
329
360
  * The connection in `slot`: its state, its handshake (`tls`: suite, ALPN,
330
361
  * server name) and the alerts sent and received. A free slot answers the
331
- * last connection it held. A slot never accepted into answers `vacant`,
332
- * failed, as a free slot does, and builds no slot; a slot out of range
362
+ * last connection it held. A slot never accepted into answers one shared
363
+ * vacant connection, failed, as a free slot does, and builds no slot; a slot out of range
333
364
  * names slot 0's.
365
+ *
366
+ * @param slot A slot number, as `accept` answered it.
367
+ * @returns The slot's connection, for reading; the pool keeps it and reuses it for the slot's next
368
+ * connection.
334
369
  */
335
370
  connection(slot: i32): TlsRecordServer {
336
371
  const index: i32 = slot >= 0 && slot < this.slots ? slot : 0
@@ -357,6 +392,11 @@ export class TlsTcpServer {
357
392
  * closed), or `tcpAccept`'s own failure; and `TLS_RECORD_INVALID` (-22),
358
393
  * before any connection is taken, for a random or key that is not 32
359
394
  * bytes. On any answer but a slot both arrays are left as they were.
395
+ *
396
+ * @param serverRandom 32 fresh random bytes for the ServerHello's random; copied, not kept.
397
+ * @param ephemeralPrivate 32 fresh random bytes for this handshake's key share; when a slot is answered it
398
+ * has been copied into the slot's own `Secret` and this array wiped.
399
+ * @returns The slot, 0 or more, that now holds the connection; or one of the negative failures above.
360
400
  */
361
401
  accept(serverRandom: u8[], ephemeralPrivate: u8[]): i32 {
362
402
  if (
@@ -407,7 +447,11 @@ export class TlsTcpServer {
407
447
  * The socket of `slot` is readable: reads it until it would block or the
408
448
  * connection has no room, handing each read to the connection, then sends
409
449
  * what that produced. Answers the connection's `interest`, or, while the
410
- * slot lingers, what `drain` answers; a free slot answers `TLS_RECORD_DONE`.
450
+ * slot lingers (`lingering`), `TLS_RECORD_WANT_READ` until its linger is
451
+ * over and then `TLS_RECORD_DONE`; a free slot answers `TLS_RECORD_DONE`.
452
+ *
453
+ * @param slot The slot whose socket `pollWait` reported readable.
454
+ * @returns The slot's interest: `TLS_RECORD_*` bits saying what to wait for next.
411
455
  */
412
456
  readable(slot: i32): i32 {
413
457
  if (!this.holds(slot)) {
@@ -438,7 +482,12 @@ export class TlsTcpServer {
438
482
  return this.flush(slot)
439
483
  }
440
484
 
441
- /** The socket of `slot` is writable: sends what the connection holds. Answers its `interest`. */
485
+ /**
486
+ * The socket of `slot` is writable: sends what the connection holds. Answers its `interest`.
487
+ *
488
+ * @param slot The slot whose socket `pollWait` reported writable.
489
+ * @returns The slot's interest; `TLS_RECORD_DONE` for a free slot.
490
+ */
442
491
  writable(slot: i32): i32 {
443
492
  if (!this.holds(slot)) {
444
493
  return TLS_RECORD_DONE
@@ -449,8 +498,12 @@ export class TlsTcpServer {
449
498
  /**
450
499
  * Writes the connection's output until the socket would block or it is all
451
500
  * sent, and answers its `interest`; once the connection is over and the
452
- * program has read what the client sent, the slot lingers (`linger`). A
501
+ * program has read what the client sent, the slot lingers (`lingering`). A
453
502
  * free slot answers `TLS_RECORD_DONE`.
503
+ *
504
+ * @param slot The slot whose output to send.
505
+ * @returns The slot's interest; once the connection is over, `TLS_RECORD_WANT_READ` while the slot
506
+ * lingers and `TLS_RECORD_DONE` after.
454
507
  */
455
508
  flush(slot: i32): i32 {
456
509
  if (!this.holds(slot)) {
@@ -466,7 +519,7 @@ export class TlsTcpServer {
466
519
  }
467
520
 
468
521
  /** Writes `slot`'s output until the socket would block or it is all sent; answers the connection's `interest`. */
469
- send(slot: i32): i32 {
522
+ private send(slot: i32): i32 {
470
523
  const fd: i32 = this.fds[slot]
471
524
  const conn: TlsRecordServer = this.connections[slot]
472
525
  while (conn.outputEnd > conn.outputStart) {
@@ -489,7 +542,7 @@ export class TlsTcpServer {
489
542
  * every record buffer given back, and what the client sends is drained
490
543
  * (`drain`). Any other is done.
491
544
  */
492
- linger(slot: i32): i32 {
545
+ private linger(slot: i32): i32 {
493
546
  const conn: TlsRecordServer = this.connections[slot]
494
547
  if (
495
548
  conn.state !== TLS_RECORD_STATE_CLOSED ||
@@ -512,7 +565,7 @@ export class TlsTcpServer {
512
565
  * socket fails or more than `TLS_TCP_LINGER_LIMIT` bytes came
513
566
  * (`TLS_RECORD_DONE`).
514
567
  */
515
- drain(slot: i32): i32 {
568
+ private drain(slot: i32): i32 {
516
569
  while (this.lingered[slot] >= 0) {
517
570
  const n: i32 = netRead(this.fds[slot], this.scratch, TLS_TCP_FROM, toI32(this.scratch.length))
518
571
  if (n === TLS_RECORD_AGAIN) {
@@ -528,17 +581,25 @@ export class TlsTcpServer {
528
581
  * Whether `slot` lingers: its connection is over and it waits for the
529
582
  * client to hang up. A carrier's idle clock does not move for what a
530
583
  * lingering slot drains, so its idle timeout bounds the wait.
584
+ *
585
+ * @param slot A slot number, as `accept` answered it.
586
+ * @returns True while the slot holds a connection that is draining its client before `close`.
531
587
  */
532
588
  lingering(slot: i32): boolean {
533
589
  return this.holds(slot) && this.lingered[slot] >= 0
534
590
  }
535
591
 
536
592
  /** A lingering `slot`'s interest: to be read, or `TLS_RECORD_DONE` once its linger is over. */
537
- lingerInterest(slot: i32): i32 {
593
+ private lingerInterest(slot: i32): i32 {
538
594
  return this.lingered[slot] >= 0 ? TLS_RECORD_WANT_READ : TLS_RECORD_DONE
539
595
  }
540
596
 
541
- /** What `slot`'s connection wants now, without touching the socket; `TLS_RECORD_DONE` for a free slot. */
597
+ /**
598
+ * What `slot`'s connection wants now, without touching the socket; `TLS_RECORD_DONE` for a free slot.
599
+ *
600
+ * @param slot A slot number, as `accept` answered it.
601
+ * @returns The slot's `TLS_RECORD_*` interest bits; the low two are the events for `pollModify`.
602
+ */
542
603
  interest(slot: i32): i32 {
543
604
  if (!this.holds(slot)) {
544
605
  return TLS_RECORD_DONE
@@ -548,12 +609,25 @@ export class TlsTcpServer {
548
609
  : this.connections[slot].interest()
549
610
  }
550
611
 
551
- /** What `slot`'s CertificateVerify signs, while its `interest` says `TLS_RECORD_SIGN`; `null` otherwise. */
612
+ /**
613
+ * What `slot`'s CertificateVerify signs, while its `interest` says `TLS_RECORD_SIGN`; `null` otherwise.
614
+ *
615
+ * @param slot A slot number, as `accept` answered it.
616
+ * @returns The bytes to sign with the certificate's private key, or `null` for a free slot or one not
617
+ * waiting for a signature.
618
+ */
552
619
  signatureInput(slot: i32): u8[] | null {
553
620
  return this.holds(slot) ? this.connections[slot].signatureInput() : null
554
621
  }
555
622
 
556
- /** Hands `slot` the signature over `signatureInput(slot)`, seals the rest of its flight and sends it. Answers its `interest`. */
623
+ /**
624
+ * Hands `slot` the signature over `signatureInput(slot)`, seals the rest of its flight and sends it.
625
+ * Answers its `interest`.
626
+ *
627
+ * @param slot The slot whose interest says `TLS_RECORD_SIGN`.
628
+ * @param signature The signature the certificate's private key made over `signatureInput(slot)`.
629
+ * @returns The slot's interest after sending; `TLS_RECORD_DONE` for a free slot.
630
+ */
557
631
  sign(slot: i32, signature: u8[]): i32 {
558
632
  if (!this.holds(slot)) {
559
633
  return TLS_RECORD_DONE
@@ -568,6 +642,10 @@ export class TlsTcpServer {
568
642
  * handshake's signature keeps nothing. The key is borrowed: the caller made
569
643
  * the `Secret`, and wipes it. A malformed key fails the connection with
570
644
  * `internal_error`.
645
+ *
646
+ * @param slot The slot whose interest says `TLS_RECORD_SIGN`.
647
+ * @param key The certificate's P-256 private key; borrowed, still the caller's to wipe.
648
+ * @returns The slot's interest after sending; the current interest when the slot wants no signature.
571
649
  */
572
650
  signP256(slot: i32, key: Secret<u8[]>): i32 {
573
651
  const input: u8[] | null = this.signatureInput(slot)
@@ -602,6 +680,15 @@ export class TlsTcpServer {
602
680
  * the flight that answers the hello, resumed or in full
603
681
  * (`TlsRecordServer.resume`). The keys and the register are borrowed for
604
682
  * the call. Answers the slot's interest.
683
+ *
684
+ * @param slot The slot whose interest says `TLS_RECORD_TICKET` during its handshake.
685
+ * @param current The ticket key that seals new tickets; borrowed, still the caller's to wipe.
686
+ * @param currentInfo The public record of `current`: its id, when it was drawn and how much it has sealed.
687
+ * @param previous The key before `current`, so tickets sealed under it still resume; borrowed.
688
+ * @param previousInfo The public record of `previous`.
689
+ * @param strikes The register of tickets already resumed, so a ticket resumes at most once.
690
+ * @param now The time now, in `monotonicNanos()`, which key windows and ticket ages are judged against.
691
+ * @returns The slot's interest after sending; `TLS_RECORD_DONE` for a free slot.
605
692
  */
606
693
  resume(
607
694
  slot: i32,
@@ -623,6 +710,12 @@ export class TlsTcpServer {
623
710
  * While `slot`'s interest says `TLS_RECORD_TICKET` on an open connection:
624
711
  * seals one ticket under the borrowed `key` and sends its
625
712
  * NewSessionTicket (`TlsRecordServer.issue`). Answers the slot's interest.
713
+ *
714
+ * @param slot The slot whose interest says `TLS_RECORD_TICKET` on an open connection.
715
+ * @param key The ticket key to seal under; borrowed, still the caller's to wipe.
716
+ * @param info The public record of `key`, whose sealed count the ticket adds to.
717
+ * @param now The time now, in `monotonicNanos()`, sealed into the ticket as its issue time.
718
+ * @returns The slot's interest after sending; `TLS_RECORD_DONE` for a free slot.
626
719
  */
627
720
  issue(slot: i32, key: Secret<u8[]>, info: TlsTicketKeyInfo, now: i64): i32 {
628
721
  if (!this.holds(slot)) {
@@ -639,6 +732,12 @@ export class TlsTcpServer {
639
732
  * room, and the records that were waiting for it may be handled and
640
733
  * answered (a KeyUpdate), which is sent here; the connection may then want
641
734
  * the socket read again, so re-arm it with `interest(slot)`.
735
+ *
736
+ * @param slot The slot to read from.
737
+ * @param buf The program's buffer the plaintext is copied into.
738
+ * @param off Where in `buf` the first byte goes.
739
+ * @param len The most bytes to take.
740
+ * @returns The bytes copied, or 0, -11 or -104 as above; `TLS_RECORD_INVALID` (-22) for a free slot.
642
741
  */
643
742
  read(slot: i32, buf: u8[], off: i32, len: i32): i32 {
644
743
  if (!this.holds(slot)) {
@@ -654,6 +753,13 @@ export class TlsTcpServer {
654
753
  * much as fits and sends what the socket takes, and answers how much was
655
754
  * taken, -11 when nothing fits yet or the handshake is under way, -32 once
656
755
  * the server has closed, as `TlsRecordServer.write` says.
756
+ *
757
+ * @param slot The slot to write to.
758
+ * @param data The program's plaintext; it is sealed into the connection's own buffer, not kept.
759
+ * @param off Where in `data` the bytes to send start.
760
+ * @param len How many bytes, from `off`, to send.
761
+ * @returns The bytes taken, fewer than `len` when the rest does not fit yet, or -11 or -32 as above;
762
+ * `TLS_RECORD_INVALID` (-22) for a free slot.
657
763
  */
658
764
  write(slot: i32, data: u8[], off: i32, len: i32): i32 {
659
765
  if (!this.holds(slot)) {
@@ -664,7 +770,15 @@ export class TlsTcpServer {
664
770
  return n
665
771
  }
666
772
 
667
- /** Sends a KeyUpdate on `slot`, asking the client for one too when `requestPeer`; answers as `TlsRecordServer.keyUpdate`. */
773
+ /**
774
+ * Sends a KeyUpdate on `slot`, asking the client for one too when `requestPeer`; answers as
775
+ * `TlsRecordServer.keyUpdate`.
776
+ *
777
+ * @param slot The slot whose sending keys to update.
778
+ * @param requestPeer True to ask the client to update its sending keys as well (§4.6.3).
779
+ * @returns 0 once the KeyUpdate is sealed, or a negative `TLS_RECORD_*` failure as
780
+ * `TlsRecordServer.keyUpdate` says; `TLS_RECORD_INVALID` (-22) for a free slot.
781
+ */
668
782
  keyUpdate(slot: i32, requestPeer: boolean): i32 {
669
783
  if (!this.holds(slot)) {
670
784
  return TLS_RECORD_INVALID
@@ -678,9 +792,13 @@ export class TlsTcpServer {
678
792
  * Closes the server's side of `slot`'s connection (§6.1): a `close_notify`
679
793
  * after whatever is already written, sent as the socket takes it. The slot
680
794
  * stays the program's until its interest says `TLS_RECORD_DONE` — every
681
- * byte is sent and, once the slot lingers (`linger`), the client has hung
795
+ * byte is sent and, once the slot lingers (`lingering`), the client has hung
682
796
  * up — and the program calls `close`. Meanwhile the interest asks for the
683
797
  * socket to be read. Answers the interest.
798
+ *
799
+ * @param slot The slot whose connection to close.
800
+ * @returns The slot's interest; `TLS_RECORD_DONE` for a free slot, or once there is nothing left to
801
+ * wait for.
684
802
  */
685
803
  shutdown(slot: i32): i32 {
686
804
  if (!this.holds(slot)) {
@@ -697,6 +815,8 @@ export class TlsTcpServer {
697
815
  * out of every loop. A program that must know every byte and the
698
816
  * `close_notify` arrived calls `shutdown` instead, and `close` once the
699
817
  * slot's interest says `TLS_RECORD_DONE`.
818
+ *
819
+ * @param slot The slot to free; a free or unknown slot is left alone.
700
820
  */
701
821
  close(slot: i32): void {
702
822
  if (!this.holds(slot)) {
@@ -746,29 +866,38 @@ export class TlsTcpServer {
746
866
  * The socket is still connecting when the constructor returns, so the first
747
867
  * interest is writable alone; the first event on it, writable or a hang-up,
748
868
  * says how the connection went (`connectResult`), and a socket that did not
749
- * connect leaves the client done, its failure in `connectError`.
869
+ * connect leaves the client done, its failure in `failure()`.
750
870
  */
751
871
  export class TlsTcpClient {
872
+ /** The TLS record layer over the socket: its `tls` is the handshake, read for the negotiated suite and `alpnChosen`. */
752
873
  conn: TlsRecordClient
753
- trust: TlsClientTrust
874
+ private trust: TlsClientTrust
754
875
  /** The socket, -1 once `close` has run or when `tcpConnect` refused at once. */
755
- socket: i32 = -1
876
+ private socket: i32 = -1
756
877
  /** Whether the socket has yet to say how its connection went. */
757
- connecting: boolean = true
878
+ private connecting: boolean = true
758
879
  /**
759
880
  * Why the connection failed below TLS, or 0: `tcpConnect`'s or
760
881
  * `connectResult`'s failure, or what ended `tlsConnect`'s wait — its
761
882
  * timeout (`TLS_TCP_TIMED_OUT`) or its loop's failure.
883
+ *
884
+ * @internal Read by the free functions of this module.
762
885
  */
763
886
  connectError: i32 = 0
764
887
  /** Where the socket is read into before the connection takes the bytes: the largest record. */
765
- scratch: u8[]
888
+ private scratch: u8[]
766
889
 
767
890
  /**
768
891
  * A connection to the server at `addr` (`nish:net`'s 18-byte form, which
769
892
  * `netAddress` writes) under `config`, authenticated against `trust`. The
770
893
  * name the certificate must carry is `config.serverName`, never one taken
771
894
  * from `addr`. The ClientHello is sealed here and waits for the socket.
895
+ *
896
+ * @param addr The server's address and port in `nish:net`'s 18-byte form; a shorter array fails the
897
+ * client with `failure()` -22 and nothing dialled.
898
+ * @param config The server name, ALPN protocols and the rest of the ClientHello; a config `TlsClient`
899
+ * refuses leaves the client failed before any socket is made.
900
+ * @param trust The roots and policy the server's certificate chain is checked against.
772
901
  */
773
902
  constructor(addr: u8[], config: TlsClientConfig, trust: TlsClientTrust) {
774
903
  const random: u8[] = new Array<u8>(TLS_TCP_KEY_SIZE)
@@ -797,22 +926,41 @@ export class TlsTcpClient {
797
926
  this.socket = fd
798
927
  }
799
928
 
800
- /** The socket, for `pollAdd`; -1 when there is none. */
929
+ /**
930
+ * The socket, for `pollAdd`; -1 when there is none.
931
+ *
932
+ * @returns The socket descriptor, which the client still owns and closes in `close`; -1 when there is none.
933
+ */
801
934
  fd(): i32 {
802
935
  return this.socket
803
936
  }
804
937
 
805
- /** Whether the handshake is done and the server authenticated, so application data flows. */
938
+ /**
939
+ * Whether the handshake is done and the server authenticated, so application data flows.
940
+ *
941
+ * @returns True from the server's Finished until the connection fails or `shutdown` or `close` closes it.
942
+ */
806
943
  open(): boolean {
807
944
  return this.conn.state === TLS_RECORD_STATE_OPEN
808
945
  }
809
946
 
810
- /** Why a failed connection failed: `connectError` when TCP did not connect, else the alert (`TlsRecordClient.failure`). */
947
+ /**
948
+ * Why a failed connection failed: the TCP failure when TCP did not connect, else the alert
949
+ * (`TlsRecordClient.failure`).
950
+ *
951
+ * @returns A negative `nish:net` failure or `TLS_TCP_TIMED_OUT` when the trouble was below TLS,
952
+ * otherwise what `TlsRecordClient.failure` answers.
953
+ */
811
954
  failure(): i32 {
812
955
  return this.connectError !== 0 ? this.connectError : this.conn.failure()
813
956
  }
814
957
 
815
- /** What the connection wants now, as `TLS_RECORD_*` bits, without touching the socket. */
958
+ /**
959
+ * What the connection wants now, as `TLS_RECORD_*` bits, without touching the socket.
960
+ *
961
+ * @returns The interest bits; the low two are the events for `pollModify`, and `TLS_RECORD_DONE` once
962
+ * there is no socket.
963
+ */
816
964
  interest(): i32 {
817
965
  if (this.socket < 0) {
818
966
  return TLS_RECORD_DONE
@@ -825,7 +973,7 @@ export class TlsTcpClient {
825
973
  * did not leaves the client failed with nothing sent, its reason in
826
974
  * `connectError`.
827
975
  */
828
- connected(): boolean {
976
+ private connected(): boolean {
829
977
  this.connecting = false
830
978
  const result: i32 = connectResult(this.socket)
831
979
  if (result !== 0) {
@@ -840,6 +988,9 @@ export class TlsTcpClient {
840
988
  * The socket is readable, or hung up: reads it until it would block or the
841
989
  * connection has no room, handing each read to the connection, then sends
842
990
  * what that produced. Answers the `interest`.
991
+ *
992
+ * @returns The interest after reading and sending; `TLS_RECORD_DONE` when there is no socket or it
993
+ * did not connect.
843
994
  */
844
995
  readable(): i32 {
845
996
  if (this.socket < 0) {
@@ -869,7 +1020,12 @@ export class TlsTcpClient {
869
1020
  return this.flush()
870
1021
  }
871
1022
 
872
- /** The socket is writable: on the first event, how the connection went; then sends what the connection holds. Answers the `interest`. */
1023
+ /**
1024
+ * The socket is writable: on the first event, how the connection went; then sends what the
1025
+ * connection holds. Answers the `interest`.
1026
+ *
1027
+ * @returns The interest after sending; `TLS_RECORD_DONE` when there is no socket or it did not connect.
1028
+ */
873
1029
  writable(): i32 {
874
1030
  if (this.socket < 0) {
875
1031
  return TLS_RECORD_DONE
@@ -885,7 +1041,7 @@ export class TlsTcpClient {
885
1041
  * connection's output until the socket would block or it is all sent, and
886
1042
  * answers the `interest`.
887
1043
  */
888
- flush(): i32 {
1044
+ private flush(): i32 {
889
1045
  if (this.socket < 0) {
890
1046
  return TLS_RECORD_DONE
891
1047
  }
@@ -915,6 +1071,11 @@ export class TlsTcpClient {
915
1071
  * connection has failed, as `TlsRecordClient.read` says, and -32 once
916
1072
  * `close` has run. What reading makes room for is answered and sent here;
917
1073
  * re-arm with `interest()`.
1074
+ *
1075
+ * @param buf The program's buffer the plaintext is copied into.
1076
+ * @param off Where in `buf` the first byte goes.
1077
+ * @param len The most bytes to take.
1078
+ * @returns The bytes copied, or 0, -11, -104 or -32 as above.
918
1079
  */
919
1080
  read(buf: u8[], off: i32, len: i32): i32 {
920
1081
  if (this.socket < 0) {
@@ -926,7 +1087,7 @@ export class TlsTcpClient {
926
1087
  }
927
1088
 
928
1089
  /** What a call on a client that is done answers: -104 when it failed, else -32. */
929
- ended(): i32 {
1090
+ private ended(): i32 {
930
1091
  return this.conn.state === TLS_RECORD_STATE_FAILED ? TLS_RECORD_RESET : TLS_RECORD_PIPE
931
1092
  }
932
1093
 
@@ -937,6 +1098,12 @@ export class TlsTcpClient {
937
1098
  * nothing came in time (the connection stays usable), -104 once it has
938
1099
  * failed, -32 once it is done otherwise, or the loop's failure. It drives
939
1100
  * the handshake too, so it may follow `new TlsTcpClient` directly.
1101
+ *
1102
+ * @param buf The program's buffer the plaintext is copied into.
1103
+ * @param off Where in `buf` the first byte goes.
1104
+ * @param len The most bytes to take.
1105
+ * @param timeoutMs How long to wait, in milliseconds on the monotonic clock, from the call.
1106
+ * @returns The bytes copied, or 0, `TLS_TCP_TIMED_OUT`, -104, -32 or the loop's failure as above.
940
1107
  */
941
1108
  readWait(buf: u8[], off: i32, len: i32, timeoutMs: i32): i32 {
942
1109
  const end: i64 = tlsTcpDeadline(timeoutMs)
@@ -978,6 +1145,12 @@ export class TlsTcpClient {
978
1145
  * sent, and the same bytes written again would reach the server twice:
979
1146
  * once the handshake is done, a timeout leaves the stream unusable, and
980
1147
  * the client is for `close`.
1148
+ *
1149
+ * @param data The program's plaintext; it is sealed into the connection's own buffer, not kept.
1150
+ * @param off Where in `data` the bytes to send start.
1151
+ * @param len How many bytes, from `off`, to send.
1152
+ * @param timeoutMs How long to wait for all of it, in milliseconds on the monotonic clock, from the call.
1153
+ * @returns `len` once the socket has taken every byte, or one of the negative failures above.
981
1154
  */
982
1155
  writeAll(data: u8[], off: i32, len: i32, timeoutMs: i32): i32 {
983
1156
  const end: i64 = tlsTcpDeadline(timeoutMs)
@@ -1020,12 +1193,20 @@ export class TlsTcpClient {
1020
1193
  return result < 0 ? result : done
1021
1194
  }
1022
1195
 
1023
- /** Whether sealed bytes are still waiting for the socket. */
1196
+ /**
1197
+ * Whether sealed bytes are still waiting for the socket.
1198
+ *
1199
+ * @returns True while the connection's output holds bytes the socket has not taken yet.
1200
+ */
1024
1201
  sending(): boolean {
1025
1202
  return this.conn.outputEnd > this.conn.outputStart
1026
1203
  }
1027
1204
 
1028
- /** A readiness loop of the client's own holding its socket, for the waiting calls, or the loop's failure. */
1205
+ /**
1206
+ * A readiness loop of the client's own holding its socket, for the waiting calls, or the loop's failure.
1207
+ *
1208
+ * @internal Read by the free functions of this module.
1209
+ */
1029
1210
  ownLoop(): i32 {
1030
1211
  const loop: i32 = pollCreate()
1031
1212
  if (loop >= 0) {
@@ -1039,6 +1220,8 @@ export class TlsTcpClient {
1039
1220
  * until `end` on the monotonic clock, and handles what came. Answers 0,
1040
1221
  * `TLS_RECORD_DONE` once the connection wants nothing more,
1041
1222
  * `TLS_TCP_TIMED_OUT`, or the loop's failure.
1223
+ *
1224
+ * @internal Read by the free functions of this module.
1042
1225
  */
1043
1226
  turn(loop: i32, end: i64): i32 {
1044
1227
  const wants: i32 = this.interest()
@@ -1074,6 +1257,12 @@ export class TlsTcpClient {
1074
1257
  * as fits and sends what the socket takes, and answers how much was taken,
1075
1258
  * -11 when nothing fits yet or the handshake is under way, -32 once the
1076
1259
  * client has closed, as `TlsRecordClient.write` says.
1260
+ *
1261
+ * @param data The program's plaintext; it is sealed into the connection's own buffer, not kept.
1262
+ * @param off Where in `data` the bytes to send start.
1263
+ * @param len How many bytes, from `off`, to send.
1264
+ * @returns The bytes taken, fewer than `len` when the rest does not fit yet, or a negative failure as
1265
+ * `TlsRecordClient.write` says.
1077
1266
  */
1078
1267
  write(data: u8[], off: i32, len: i32): i32 {
1079
1268
  const n: i32 = this.conn.write(data, off, len)
@@ -1081,7 +1270,13 @@ export class TlsTcpClient {
1081
1270
  return n
1082
1271
  }
1083
1272
 
1084
- /** Sends a KeyUpdate, asking the server for one too when `requestPeer`; answers as `TlsRecordClient.keyUpdate`. */
1273
+ /**
1274
+ * Sends a KeyUpdate, asking the server for one too when `requestPeer`; answers as
1275
+ * `TlsRecordClient.keyUpdate`.
1276
+ *
1277
+ * @param requestPeer True to ask the server to update its sending keys as well (§4.6.3).
1278
+ * @returns 0 once the KeyUpdate is sealed, or a negative failure as `TlsRecordClient.keyUpdate` says.
1279
+ */
1085
1280
  keyUpdate(requestPeer: boolean): i32 {
1086
1281
  const r: i32 = this.conn.keyUpdate(requestPeer)
1087
1282
  this.flush()
@@ -1095,6 +1290,8 @@ export class TlsTcpClient {
1095
1290
  * still reads, and once the `close_notify` is sent the interest says
1096
1291
  * `TLS_RECORD_DONE` and `readWait` answers -32; call `close` then.
1097
1292
  * Answers the interest.
1293
+ *
1294
+ * @returns The interest after sending what the socket takes; `TLS_RECORD_DONE` once nothing is left.
1098
1295
  */
1099
1296
  shutdown(): i32 {
1100
1297
  this.conn.close()
@@ -1126,25 +1323,41 @@ const tlsTcpDeadline = (timeoutMs: i32): i64 => monotonicNanos() + toI64(timeout
1126
1323
 
1127
1324
  /**
1128
1325
  * Opens a TLS 1.3 connection to the server at `addr` (`nish:net`'s 18-byte
1129
- * form) for `serverName`, offering `alpn`, authenticated against the
1130
- * system's roots, and waits in a loop of its own until the handshake is done
1131
- * and the client's last flight sent, or it fails, or `timeoutMs` milliseconds
1132
- * pass, reading the roots included. Answers the client either way:
1133
- * `open()` says whether it opened; otherwise `failure()` says why — the TCP
1134
- * failure, the alert, or `TLS_TCP_TIMED_OUT`, the client closed. Nothing is
1135
- * looked up: to reach a name, resolve it first with `nish/net/dns`'s
1326
+ * form) for `serverName`, offering `alpn`, authenticated against the system's
1327
+ * roots, and waits in a loop of its own until the handshake is done and the
1328
+ * client's last flight sent, or it fails, or `timeoutMs` milliseconds pass,
1329
+ * reading the roots included. Answers the client either way: `open()` says
1330
+ * whether it opened; otherwise `failure()` says why — the TCP failure, the
1331
+ * alert, or `TLS_TCP_TIMED_OUT`, the client closed.
1332
+ *
1333
+ * Nothing is looked up: to reach a name, resolve it first with `nish/net/dns`'s
1136
1334
  * `resolveHost`; the name the certificate must carry is always `serverName`,
1137
1335
  * never one taken from `addr`. The open client's socket is in no loop: the
1138
- * program adds it to its own, or uses `writeAll` and `readWait`. The roots
1139
- * are read on every call; a program that connects often reads them once with
1336
+ * program adds it to its own, or uses `writeAll` and `readWait`. The roots are
1337
+ * read on every call; a program that connects often reads them once with
1140
1338
  * `tlsClientSystemTrust` and passes them to `tlsConnectWith`.
1339
+ *
1340
+ * @param addr The server's address and port in `nish:net`'s 18-byte form.
1341
+ * @param serverName The name the server's certificate must carry, sent as `server_name` unless it is an
1342
+ * IP literal.
1343
+ * @param alpn The ALPN protocols to offer, most preferred first, each 1 to 255 bytes; empty offers none.
1344
+ * @param timeoutMs How long the whole connect may take, in milliseconds on the monotonic clock.
1345
+ * @returns The client, open or failed; the caller owns it and calls `close` when done with it.
1141
1346
  */
1142
1347
  export const tlsConnect = (addr: u8[], serverName: string, alpn: string[], timeoutMs: i32): TlsTcpClient => {
1143
1348
  const end: i64 = tlsTcpDeadline(timeoutMs)
1144
1349
  return tlsConnectBy(addr, new TlsClientConfig(serverName, alpn), tlsClientSystemTrust(), end)
1145
1350
  }
1146
1351
 
1147
- /** `tlsConnect` under a `config` and `trust` of the caller's. */
1352
+ /**
1353
+ * `tlsConnect` under a `config` and `trust` of the caller's.
1354
+ *
1355
+ * @param addr The server's address and port in `nish:net`'s 18-byte form.
1356
+ * @param config The server name, ALPN protocols and the rest of the ClientHello.
1357
+ * @param trust The roots the server's chain is checked against, such as one `tlsClientSystemTrust` read.
1358
+ * @param timeoutMs How long the whole connect may take, in milliseconds on the monotonic clock.
1359
+ * @returns The client, open or failed; the caller owns it and calls `close` when done with it.
1360
+ */
1148
1361
  export const tlsConnectWith = (
1149
1362
  addr: u8[],
1150
1363
  config: TlsClientConfig,