@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
@@ -5,14 +5,20 @@
5
5
  * unknown. Sans-IO: every reader takes a byte window `(buf, off, len)` and
6
6
  * reads it in place, and every writer writes into the caller's buffer at an
7
7
  * offset, before an end, and answers the offset past what it wrote, or -1
8
- * with nothing written. Nothing here allocates.
8
+ * when it does not fit (the frame writers may have written their header by
9
+ * then). Nothing here allocates.
9
10
  *
10
- * import { Http3FrameHeader, h3ReadFrameHeader, h3PutFrameHeader, H3_FRAME_DATA } from "nish/net/http3-frame";
11
+ * import {
12
+ * Http3FrameHeader, h3ReadFrameHeader, h3PutFrameHeader, H3_FRAME_DATA, H3_FRAME_HEADER_MAX,
13
+ * } from "nish/net/http3-frame";
11
14
  *
15
+ * const buf: u8[] = [0x00, 0x03, 0x61, 0x62, 0x63]; // bytes a stream delivered: DATA, 3 bytes
12
16
  * const h = new Http3FrameHeader();
13
- * const size: i32 = h3ReadFrameHeader(h, buf, off, len); // 0: the window ends inside the header
17
+ * const size: i32 = h3ReadFrameHeader(h, buf, 0, toI32(buf.length)); // 2; 0 if the header is cut off
14
18
  * // h.type, h.length; the payload is the next h.length bytes of the stream
15
- * const at: i32 = h3PutFrameHeader(out, 0, toI32(out.length), H3_FRAME_DATA, toI64(n));
19
+ * const out: u8[] = new Array<u8>(H3_FRAME_HEADER_MAX);
20
+ * const n: i32 = 3;
21
+ * const at: i32 = h3PutFrameHeader(out, 0, toI32(out.length), H3_FRAME_DATA, toI64(n)); // 2
16
22
  *
17
23
  * **Frames** (§7.1) are a type and a length, each a QUIC variable-length
18
24
  * integer, and then that many bytes of payload. On a QUIC stream a frame may
@@ -32,16 +38,17 @@
32
38
  * **SETTINGS** (§7.2.4). `h3ReadSettings` reads a whole payload into an
33
39
  * `Http3Settings`: the three identifiers this endpoint understands, and the
34
40
  * first `H3_SETTINGS_KEEP` it does not, kept rather than dropped so that an
35
- * extension can read them. The four that extended CONNECT and WebTransport
36
- * read (RFC 9220's, RFC 9297's and the two of the WebTransport drafts) are
37
- * also recorded in fields of their own, refused when repeated, so a peer
38
- * cannot push them out of reach behind eight others. A payload that ends
39
- * inside a pair is H3_FRAME_ERROR (§7.1); an identifier HTTP/2 defined with
40
- * no HTTP/3 counterpart (0x00, 0x02 to 0x05), or one that appears twice, is
41
- * H3_SETTINGS_ERROR (§7.2.4, §7.2.4.1). A repeat among the unknown ones is
42
- * caught while they are kept, and past `H3_SETTINGS_KEEP` they are counted,
43
- * not compared, so a peer cannot make the read cost more than a fixed number
44
- * of compares per setting.
41
+ * extension can read them. The four that extended CONNECT and WebTransport read
42
+ * (RFC 9220's, RFC 9297's and the two of the WebTransport drafts) are also
43
+ * recorded in fields of their own, refused when repeated, so a peer cannot push
44
+ * them out of reach behind eight others.
45
+ *
46
+ * A payload that ends inside a pair is H3_FRAME_ERROR (§7.1); an identifier
47
+ * HTTP/2 defined with no HTTP/3 counterpart (0x00, 0x02 to 0x05), or one that
48
+ * appears twice, is H3_SETTINGS_ERROR (§7.2.4, §7.2.4.1). A repeat among the
49
+ * unknown ones is caught while they are kept, and past `H3_SETTINGS_KEEP` they
50
+ * are counted, not compared, so a peer cannot make the read cost more than a
51
+ * fixed number of compares per setting.
45
52
  *
46
53
  * **Stream types** (§6.2): control 0x00, push 0x01, RFC 9204's QPACK
47
54
  * encoder 0x02 and decoder 0x03, and WebTransport's 0x54, whose bidirectional
@@ -128,22 +135,39 @@ export const H3_SETTINGS_KEEP: i32 = 8
128
135
 
129
136
  /** What `h3ReadSettings` answers for a payload it read whole. */
130
137
  export const H3_SETTINGS_OK: i64 = 0
138
+ /** H3_NO_ERROR (0x0100): no error, for closing a connection or stream with nothing to signal (§8.1). */
131
139
  export const H3_NO_ERROR: i64 = 0x0100
140
+ /** H3_GENERAL_PROTOCOL_ERROR (0x0101): a protocol violation no more specific code names (§8.1). */
132
141
  export const H3_GENERAL_PROTOCOL_ERROR: i64 = 0x0101
142
+ /** H3_INTERNAL_ERROR (0x0102): an internal error in the HTTP stack (§8.1). */
133
143
  export const H3_INTERNAL_ERROR: i64 = 0x0102
144
+ /** H3_STREAM_CREATION_ERROR (0x0103): the peer created a stream this endpoint will not accept (§8.1). */
134
145
  export const H3_STREAM_CREATION_ERROR: i64 = 0x0103
146
+ /** H3_CLOSED_CRITICAL_STREAM (0x0104): a stream the connection needs was closed or reset (§8.1). */
135
147
  export const H3_CLOSED_CRITICAL_STREAM: i64 = 0x0104
148
+ /** H3_FRAME_UNEXPECTED (0x0105): a frame not allowed in the current state or on its stream (§8.1). */
136
149
  export const H3_FRAME_UNEXPECTED: i64 = 0x0105
150
+ /** H3_FRAME_ERROR (0x0106): a frame whose layout or size is wrong (§8.1). */
137
151
  export const H3_FRAME_ERROR: i64 = 0x0106
152
+ /** H3_EXCESSIVE_LOAD (0x0107): the peer behaves in a way that may cause excessive load (§8.1). */
138
153
  export const H3_EXCESSIVE_LOAD: i64 = 0x0107
154
+ /** H3_ID_ERROR (0x0108): a stream ID or push ID used wrongly, such as past a limit or reused (§8.1). */
139
155
  export const H3_ID_ERROR: i64 = 0x0108
156
+ /** H3_SETTINGS_ERROR (0x0109): an error in a SETTINGS payload (§8.1, §7.2.4). */
140
157
  export const H3_SETTINGS_ERROR: i64 = 0x0109
158
+ /** H3_MISSING_SETTINGS (0x010a): the control stream did not start with SETTINGS (§8.1, §6.2.1). */
141
159
  export const H3_MISSING_SETTINGS: i64 = 0x010a
160
+ /** H3_REQUEST_REJECTED (0x010b): the server refused a request before any processing of it (§8.1). */
142
161
  export const H3_REQUEST_REJECTED: i64 = 0x010b
162
+ /** H3_REQUEST_CANCELLED (0x010c): a request or its response is cancelled (§8.1). */
143
163
  export const H3_REQUEST_CANCELLED: i64 = 0x010c
164
+ /** H3_REQUEST_INCOMPLETE (0x010d): the client's stream ended without a whole request (§8.1). */
144
165
  export const H3_REQUEST_INCOMPLETE: i64 = 0x010d
166
+ /** H3_MESSAGE_ERROR (0x010e): a malformed HTTP message (§8.1, §4.1.2). */
145
167
  export const H3_MESSAGE_ERROR: i64 = 0x010e
168
+ /** H3_CONNECT_ERROR (0x010f): a CONNECT request's TCP connection was reset or closed abnormally (§8.1). */
146
169
  export const H3_CONNECT_ERROR: i64 = 0x010f
170
+ /** H3_VERSION_FALLBACK (0x0110): the request cannot be served over HTTP/3; retry it over HTTP/1.1 (§8.1). */
147
171
  export const H3_VERSION_FALLBACK: i64 = 0x0110
148
172
  /** WT_SESSION_GONE (draft-ietf-webtrans-http3-02 §4.5): a WebTransport stream of a session that is gone, or can never come. */
149
173
  export const H3_WT_SESSION_GONE: i64 = 0x170d7b68
@@ -164,7 +188,9 @@ const H3_FRAME_ZERO: i32 = 0
164
188
 
165
189
  /** One frame header as `h3ReadFrameHeader` read it: the type and the payload's length. */
166
190
  export class Http3FrameHeader {
191
+ /** The frame type, 0 to 2^62 - 1, any value: set by each `h3ReadFrameHeader` that answers above 0. */
167
192
  type: i64 = 0
193
+ /** The payload's length in bytes, 0 to 2^62 - 1, set with `type`; the payload itself is not read here. */
168
194
  length: i64 = 0
169
195
  }
170
196
 
@@ -176,10 +202,16 @@ export class Http3FrameHeader {
176
202
  * values, in order, and the rest counted in `dropped`.
177
203
  */
178
204
  export class Http3Settings {
179
- unknownIds: i64[]
180
- unknownValues: i64[]
205
+ private unknownIds: i64[]
206
+ private unknownValues: i64[]
207
+ /** SETTINGS_QPACK_MAX_TABLE_CAPACITY in bytes as the peer sent it, unchecked; 0 by default. */
181
208
  maxTableCapacity: i64 = 0
209
+ /**
210
+ * SETTINGS_MAX_FIELD_SECTION_SIZE as the peer sent it: the largest field section it takes, as §4.2.2
211
+ * counts it; -1, unlimited, by default.
212
+ */
182
213
  maxFieldSectionSize: i64 = -1
214
+ /** SETTINGS_QPACK_BLOCKED_STREAMS, a count of streams, as the peer sent it, unchecked; 0 by default. */
183
215
  blockedStreams: i64 = 0
184
216
  /**
185
217
  * The extension settings WebTransport reads, -1 when the frame did not
@@ -189,8 +221,11 @@ export class Http3Settings {
189
221
  * as an unknown identifier while there is room, so `unknown` still finds it.
190
222
  */
191
223
  enableConnectProtocol: i64 = -1
224
+ /** SETTINGS_H3_DATAGRAM's value as the peer sent it, or -1 when the frame did not carry it. */
192
225
  h3Datagram: i64 = -1
226
+ /** SETTINGS_ENABLE_WEBTRANSPORT's value as the peer sent it, or -1 when the frame did not carry it. */
193
227
  enableWebtransport: i64 = -1
228
+ /** SETTINGS_WEBTRANSPORT_MAX_SESSIONS's value as the peer sent it, or -1 when the frame lacked it. */
194
229
  webtransportMaxSessions: i64 = -1
195
230
  /** The bits of the identifiers understood that the frame set. */
196
231
  seen: i32 = 0
@@ -199,12 +234,17 @@ export class Http3Settings {
199
234
  /** How many more there were, saturating at 2^31 - 1. */
200
235
  dropped: i32 = 0
201
236
 
237
+ /** Settings at their defaults, with room for `H3_SETTINGS_KEEP` unknown identifiers made once. */
202
238
  constructor() {
203
239
  this.unknownIds = new Array<i64>(H3_SETTINGS_KEEP)
204
240
  this.unknownValues = new Array<i64>(H3_SETTINGS_KEEP)
205
241
  }
206
242
 
207
- /** Back to the defaults, for the next connection. */
243
+ /**
244
+ * Back to the defaults, for the next connection.
245
+ * @internal Called by `h3ReadSettings` before it reads and by `http3.ts`'s connection restart; not for
246
+ * callers.
247
+ */
208
248
  reset(): void {
209
249
  this.maxTableCapacity = 0
210
250
  this.maxFieldSectionSize = -1
@@ -218,7 +258,12 @@ export class Http3Settings {
218
258
  this.dropped = 0
219
259
  }
220
260
 
221
- /** The value of an identifier this module does not understand, or -1 when the frame did not carry it (or carried it past the kept ones). */
261
+ /**
262
+ * The value of an identifier this module does not understand.
263
+ * @param id The setting identifier to look up among the kept ones.
264
+ * @returns Its value as the peer sent it, 0 to 2^62 - 1, or -1 when it is not kept; -1 also for the three
265
+ * identifiers this module understands, which are never kept.
266
+ */
222
267
  unknown(id: i64): i64 {
223
268
  for (let k: i32 = 0; k < this.unknownCount && k < H3_SETTINGS_KEEP; k++) {
224
269
  if (this.unknownIds[k] === id) {
@@ -228,7 +273,10 @@ export class Http3Settings {
228
273
  return H3_FRAME_NONE
229
274
  }
230
275
 
231
- /** Records one pair; answers `H3_SETTINGS_OK` or H3_SETTINGS_ERROR for a reserved or repeated identifier. */
276
+ /**
277
+ * Records one pair; answers `H3_SETTINGS_OK` or H3_SETTINGS_ERROR for a reserved or repeated identifier.
278
+ * @internal Called once per pair by `h3ReadSettings`, which resets first; not for callers.
279
+ */
232
280
  take(id: i64, value: i64): i64 {
233
281
  if (id === 0x00 || (id >= 0x02 && id <= 0x05)) {
234
282
  return H3_SETTINGS_ERROR
@@ -288,14 +336,24 @@ export class Http3Settings {
288
336
  }
289
337
  }
290
338
 
291
- /** Panics unless `[off, off + len)` lies inside `buf`: a window outside its buffer is the program's mistake. */
339
+ /**
340
+ * Panics unless `[off, off + len)` lies inside `buf`: a window outside its buffer is the program's mistake.
341
+ * @param what The caller's name, which starts the panic message.
342
+ * @param buf The buffer the window is meant to lie in.
343
+ * @param off The window's first byte offset; negative panics.
344
+ * @param len The window's length in bytes; negative panics, and so does an end past `buf.length`.
345
+ */
292
346
  export const h3CheckWindow = (what: string, buf: u8[], off: i32, len: i32): void => {
293
347
  if (off < 0 || len < 0 || toI64(off) + toI64(len) > toI64(buf.length)) {
294
348
  panic(`${what}: the window [${off}, ${off} + ${len}) is outside a buffer of ${buf.length} bytes`)
295
349
  }
296
350
  }
297
351
 
298
- /** `count` plus one, saturating at 2^31 - 1: every counter a peer drives. */
352
+ /**
353
+ * `count` plus one, saturating at 2^31 - 1: every counter a peer drives.
354
+ * @param count The counter's current value.
355
+ * @returns `count + 1`, or `count` unchanged once it is 2^31 - 1.
356
+ */
299
357
  export const h3Count = (count: i32): i32 => (count < 2147483647 ? count + 1 : count)
300
358
 
301
359
  /** Whether `[at, end)` is a usable place to write in `buf`. */
@@ -305,16 +363,34 @@ const h3FrameRoom = (buf: u8[], at: i32, end: i32): boolean =>
305
363
  /**
306
364
  * The varint at `buf[at]`, read only from `buf[at .. end)`, or -1 when it
307
365
  * does not fit there. Advance past it by `h3VarintLength(buf, at)`.
366
+ * @param buf The bytes holding the integer.
367
+ * @param at The byte offset of the integer's first byte.
368
+ * @param end The offset the integer must end at or before; past `buf.length` reads nothing.
369
+ * @returns The value, 0 to 2^62 - 1, or -1 when `at` is outside `buf`, `end` is past `buf.length`, or the
370
+ * integer's bytes run past `end`.
308
371
  */
309
372
  export const h3ReadVarint = (buf: u8[], at: i32, end: i32): i64 => quicVarintRead(buf, at, end)
310
373
 
311
- /** The length of the varint whose first byte is `buf[at]`: 1, 2, 4 or 8, or 0 outside `buf`. */
374
+ /**
375
+ * The length of the varint whose first byte is `buf[at]`.
376
+ * @param buf The bytes holding the integer.
377
+ * @param at The byte offset of the integer's first byte.
378
+ * @returns 1, 2, 4 or 8 bytes, read from the first byte's two-bit prefix alone (the rest need not be in
379
+ * `buf`), or 0 when `at` is outside `buf`.
380
+ */
312
381
  export const h3VarintLength = (buf: u8[], at: i32): i32 => quicVarintLength(buf, at)
313
382
 
314
383
  /**
315
384
  * Writes `value` as a varint in the fewest bytes at `buf[at]`, before `end`,
316
385
  * and answers the offset past it, or -1 when it does not fit or no varint
317
386
  * holds the value.
387
+ * @param buf The buffer to write into.
388
+ * @param at The byte offset to write the first byte at.
389
+ * @param end The offset the integer must end at or before; at most `buf.length`.
390
+ * @param value The value to encode, 0 to 2^62 - 1.
391
+ * @returns The offset past the 1, 2, 4 or 8 bytes written, or -1 with nothing written when `value` is
392
+ * negative or above 2^62 - 1, `[at, end)` is not a window inside `buf`, or the integer does not fit before
393
+ * `end`.
318
394
  */
319
395
  export const h3PutVarint = (buf: u8[], at: i32, end: i32, value: i64): i32 => {
320
396
  const size: i32 = quicVarintSize(value)
@@ -324,7 +400,12 @@ export const h3PutVarint = (buf: u8[], at: i32, end: i32, value: i64): i32 => {
324
400
  return quicVarintPut(buf, at, value, size)
325
401
  }
326
402
 
327
- /** How many bytes a frame header of `type` and `length` takes, or 0 when either is no varint. */
403
+ /**
404
+ * How many bytes a frame header of `type` and `length` takes.
405
+ * @param type The frame type.
406
+ * @param length The payload's length in bytes.
407
+ * @returns 2 to 16 bytes, or 0 when `type` or `length` is negative or above 2^62 - 1.
408
+ */
328
409
  export const h3FrameHeaderSize = (type: i64, length: i64): i32 => {
329
410
  const a: i32 = quicVarintSize(type)
330
411
  const b: i32 = quicVarintSize(length)
@@ -336,6 +417,11 @@ export const h3FrameHeaderSize = (type: i64, length: i64): i32 => {
336
417
  * many bytes it took, or 0 when the window ends inside it (and `h` is not
337
418
  * touched). Any type and any length up to 2^62 - 1 is a header; whether the
338
419
  * type is allowed where it arrived is the stream's question.
420
+ * @param h The header to fill; set only when the answer is above 0.
421
+ * @param buf The bytes the stream delivered.
422
+ * @param off The window's first byte offset, where the header starts.
423
+ * @param len The window's length in bytes; the window must lie inside `buf`, or this panics.
424
+ * @returns The header's size, 2 to 16 bytes, or 0 when the window ends before both varints are whole.
339
425
  */
340
426
  export const h3ReadFrameHeader = (h: Http3FrameHeader, buf: u8[], off: i32, len: i32): i32 => {
341
427
  h3CheckWindow("h3ReadFrameHeader", buf, off, len)
@@ -354,7 +440,16 @@ export const h3ReadFrameHeader = (h: Http3FrameHeader, buf: u8[], off: i32, len:
354
440
  return at + quicVarintLength(buf, at) - off
355
441
  }
356
442
 
357
- /** Writes a frame header of `type` and `length` at `buf[at]`, before `end`; answers the offset past it, or -1. */
443
+ /**
444
+ * Writes a frame header of `type` and `length` at `buf[at]`, before `end`.
445
+ * @param buf The buffer to write into.
446
+ * @param at The byte offset to write the header at.
447
+ * @param end The offset the header must end at or before; at most `buf.length`.
448
+ * @param type The frame type, 0 to 2^62 - 1, written as given.
449
+ * @param length The payload's length in bytes, 0 to 2^62 - 1; the payload is the caller's to write.
450
+ * @returns The offset past the 2 to 16 bytes written, or -1 with nothing written when `type` or `length` is
451
+ * no varint, `[at, end)` is not a window inside `buf`, or the header does not fit before `end`.
452
+ */
358
453
  export const h3PutFrameHeader = (buf: u8[], at: i32, end: i32, type: i64, length: i64): i32 => {
359
454
  const size: i32 = h3FrameHeaderSize(type, length)
360
455
  if (size === 0 || !h3FrameRoom(buf, at, end) || at > end - size) {
@@ -363,11 +458,21 @@ export const h3PutFrameHeader = (buf: u8[], at: i32, end: i32, type: i64, length
363
458
  return h3PutVarint(buf, h3PutVarint(buf, at, end, type), end, length)
364
459
  }
365
460
 
366
- /** Whether `type` is one HTTP/2 used that HTTP/3 reserves, whose receipt is H3_FRAME_UNEXPECTED (§7.2.8). */
461
+ /**
462
+ * Whether `type` is one HTTP/2 used that HTTP/3 reserves, whose receipt is H3_FRAME_UNEXPECTED (§7.2.8).
463
+ * @param type A frame type as read.
464
+ * @returns True for 0x02, 0x06, 0x08 and 0x09; false for every other type.
465
+ */
367
466
  export const h3ReservedHttp2Frame = (type: i64): boolean =>
368
467
  type === 0x02 || type === 0x06 || type === 0x08 || type === 0x09
369
468
 
370
- /** Whether `value` is one of the `0x1f * N + 0x21` values reserved to exercise the rule that unknowns are ignored (§7.2.8, §7.2.4.1, §6.2.3). */
469
+ /**
470
+ * Whether `value` is one of the `0x1f * N + 0x21` values reserved to exercise the rule that unknowns are
471
+ * ignored (§7.2.8, §7.2.4.1, §6.2.3).
472
+ * @param value A frame type, setting identifier or stream type.
473
+ * @returns True when `value` is 0x21 or above and 0x21 more than a multiple of 0x1f; false otherwise,
474
+ * negatives included.
475
+ */
371
476
  export const h3Greased = (value: i64): boolean => value >= 0x21 && (value - 0x21) % 0x1f === 0
372
477
 
373
478
  /**
@@ -375,6 +480,15 @@ export const h3Greased = (value: i64): boolean => value >= 0x21 && (value - 0x21
375
480
  * resets first). Answers `H3_SETTINGS_OK`, H3_FRAME_ERROR for a payload that
376
481
  * ends inside a pair (§7.1), or H3_SETTINGS_ERROR for a reserved or repeated
377
482
  * identifier (§7.2.4).
483
+ * @param s The settings to fill; reset first, and after an error answer its contents are not meaningful.
484
+ * @param buf The bytes holding the payload.
485
+ * @param off The payload's first byte offset.
486
+ * @param len The payload's length in bytes, the frame header's `length`; the window must lie inside `buf`,
487
+ * or this panics. An empty payload is read as the defaults.
488
+ * @returns `H3_SETTINGS_OK` when every pair was read; H3_FRAME_ERROR when the payload ends inside an
489
+ * identifier or a value; H3_SETTINGS_ERROR for an identifier HTTP/2 defined (0x00, 0x02 to 0x05) or a
490
+ * repeat of an identifier understood, of an extension one, or of a kept unknown one. It stops at the first
491
+ * error.
378
492
  */
379
493
  export const h3ReadSettings = (s: Http3Settings, buf: u8[], off: i32, len: i32): i64 => {
380
494
  h3CheckWindow("h3ReadSettings", buf, off, len)
@@ -403,8 +517,17 @@ export const h3ReadSettings = (s: Http3Settings, buf: u8[], off: i32, len: i32):
403
517
  /**
404
518
  * Writes a whole SETTINGS frame of the pairs `ids[k]`, `values[k]` at
405
519
  * `buf[at]`, before `end`, and answers the offset past it, or -1 when it does
406
- * not fit, the lists differ in length, or a value is no varint. It writes
520
+ * not fit, the lists differ in length, or an identifier or a value is no varint. It writes
407
521
  * what it is given: refusing a reserved identifier is the reader's job.
522
+ * @param buf The buffer to write into.
523
+ * @param at The byte offset to write the frame at.
524
+ * @param end The offset the frame must end at or before; at most `buf.length`.
525
+ * @param ids The setting identifiers, in the order they are written; read, not kept.
526
+ * @param values The values, one per identifier at the same index; read, not kept.
527
+ * @returns The offset past the frame written, header and payload, or -1 when the lists differ in length,
528
+ * an identifier or a value is negative or above 2^62 - 1, `[at, end)` is not a window inside `buf`, or
529
+ * the frame does not fit before `end`. Nothing is written for the first three; when only the payload
530
+ * does not fit, the header may already be in `buf[at ..]`.
408
531
  */
409
532
  export const h3PutSettings = (buf: u8[], at: i32, end: i32, ids: i64[], values: i64[]): i32 => {
410
533
  const n: i32 = toI32(ids.length)
@@ -435,6 +558,15 @@ export const h3PutSettings = (buf: u8[], at: i32, end: i32, ids: i64[], values:
435
558
  * Writes a frame whose payload is one identifier — GOAWAY, MAX_PUSH_ID or
436
559
  * CANCEL_PUSH (§7.2.6, §7.2.7, §7.2.3) — at `buf[at]`, before `end`; answers
437
560
  * the offset past it, or -1.
561
+ * @param buf The buffer to write into.
562
+ * @param at The byte offset to write the frame at.
563
+ * @param end The offset the frame must end at or before; at most `buf.length`.
564
+ * @param type The frame type, written as given: `H3_FRAME_GOAWAY`, `H3_FRAME_MAX_PUSH_ID` or
565
+ * `H3_FRAME_CANCEL_PUSH`, which this does not check.
566
+ * @param id The stream ID or push ID the payload carries, 0 to 2^62 - 1.
567
+ * @returns The offset past the frame written, or -1 when `type` or `id` is no varint, `[at, end)` is not a
568
+ * window inside `buf`, or the frame does not fit before `end`; when only the identifier does not fit, the
569
+ * header may already be in `buf[at ..]`.
438
570
  */
439
571
  export const h3PutIdFrame = (buf: u8[], at: i32, end: i32, type: i64, id: i64): i32 => {
440
572
  const size: i32 = quicVarintSize(id)
@@ -449,6 +581,12 @@ export const h3PutIdFrame = (buf: u8[], at: i32, end: i32, type: i64, id: i64):
449
581
  * The identifier a GOAWAY, MAX_PUSH_ID or CANCEL_PUSH payload
450
582
  * `buf[off, off + len)` carries, or -1 when the payload is not exactly one
451
583
  * varint, which is H3_FRAME_ERROR (§7.1).
584
+ * @param buf The bytes holding the payload.
585
+ * @param off The payload's first byte offset.
586
+ * @param len The payload's length in bytes, the frame header's `length`; the window must lie inside `buf`,
587
+ * or this panics.
588
+ * @returns The identifier, 0 to 2^62 - 1, or -1 when the payload is empty, ends inside the varint, or has
589
+ * bytes after it.
452
590
  */
453
591
  export const h3ReadIdPayload = (buf: u8[], off: i32, len: i32): i64 => {
454
592
  h3CheckWindow("h3ReadIdPayload", buf, off, len)