@amritk/nish-aarch64-darwin 0.35.0 → 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 (119) hide show
  1. package/INSTALL.md +6 -1
  2. package/bin/nish +0 -0
  3. package/docs/AI.md +9 -2
  4. package/package.json +1 -1
  5. package/runtime/nish.d.ts +4612 -430
  6. package/runtime/vite.d.ts +30 -0
  7. package/runtime/vite.mjs +150 -0
  8. package/scripts/build.sh +108 -13
  9. package/std/base64.ts +34 -5
  10. package/std/bytes.ts +256 -40
  11. package/std/cli-args.ts +296 -70
  12. package/std/cli-flags.ts +184 -19
  13. package/std/cli.ts +475 -54
  14. package/std/collections.ts +121 -23
  15. package/std/compress/checksum.ts +44 -14
  16. package/std/compress/deflate.ts +224 -111
  17. package/std/compress/gzip.ts +217 -53
  18. package/std/compress/zlib.ts +63 -7
  19. package/std/crypto/aes.ts +80 -9
  20. package/std/crypto/base64url.ts +22 -0
  21. package/std/crypto/bcrypt-batch.ts +88 -21
  22. package/std/crypto/bcrypt.ts +60 -0
  23. package/std/crypto/chacha20poly1305.ts +53 -0
  24. package/std/crypto/ct.ts +32 -13
  25. package/std/crypto/ed25519.ts +47 -0
  26. package/std/crypto/hkdf.ts +198 -13
  27. package/std/crypto/hmac.ts +235 -31
  28. package/std/crypto/jwt.ts +192 -63
  29. package/std/crypto/p256.ts +159 -16
  30. package/std/crypto/p384.ts +28 -3
  31. package/std/crypto/pki-roots.ts +32 -2
  32. package/std/crypto/pki.ts +81 -15
  33. package/std/crypto/rsa.ts +33 -3
  34. package/std/crypto/sha1.ts +3 -0
  35. package/std/crypto/sha256.ts +24 -1
  36. package/std/crypto/sha512.ts +99 -14
  37. package/std/crypto/x25519.ts +152 -14
  38. package/std/crypto/x509-random.ts +10 -0
  39. package/std/crypto/x509.ts +67 -7
  40. package/std/json-equal.ts +19 -0
  41. package/std/json-format.ts +112 -13
  42. package/std/json-number.ts +64 -14
  43. package/std/json-pointer.ts +23 -1
  44. package/std/json-tokenizer.ts +100 -29
  45. package/std/json-typed.ts +713 -66
  46. package/std/json-value.ts +400 -124
  47. package/std/json.ts +138 -10
  48. package/std/map.ts +25 -7
  49. package/std/math.ts +36 -4
  50. package/std/net/buffer-pool.ts +42 -11
  51. package/std/net/dns-config.ts +109 -23
  52. package/std/net/dns-message.ts +62 -7
  53. package/std/net/dns-resolver.ts +247 -53
  54. package/std/net/dns.ts +203 -35
  55. package/std/net/fetch.ts +151 -61
  56. package/std/net/handler.ts +278 -80
  57. package/std/net/hpack.ts +262 -52
  58. package/std/net/http-compress.ts +125 -15
  59. package/std/net/http-fields.ts +85 -9
  60. package/std/net/http1-client-codec.ts +100 -19
  61. package/std/net/http1-codec.ts +235 -27
  62. package/std/net/http1-server.ts +343 -85
  63. package/std/net/http2-frame.ts +272 -35
  64. package/std/net/http2-tls.ts +135 -34
  65. package/std/net/http2.ts +247 -106
  66. package/std/net/http3-frame.ts +154 -17
  67. package/std/net/http3-server.ts +246 -96
  68. package/std/net/http3.ts +307 -115
  69. package/std/net/outbound.ts +37 -3
  70. package/std/net/postgres-carrier.ts +144 -8
  71. package/std/net/postgres.ts +723 -103
  72. package/std/net/prefork.ts +164 -31
  73. package/std/net/qpack.ts +105 -18
  74. package/std/net/quic-conn-ack.ts +59 -12
  75. package/std/net/quic-conn-cid.ts +124 -27
  76. package/std/net/quic-conn-params.ts +70 -10
  77. package/std/net/quic-datagram.ts +43 -3
  78. package/std/net/quic-frame.ts +286 -12
  79. package/std/net/quic-listener.ts +101 -32
  80. package/std/net/quic-packet.ts +302 -21
  81. package/std/net/quic-recovery.ts +228 -44
  82. package/std/net/quic-stream.ts +353 -91
  83. package/std/net/quic.ts +489 -171
  84. package/std/net/router.ts +87 -40
  85. package/std/net/tls/client.ts +166 -51
  86. package/std/net/tls/codec.ts +413 -56
  87. package/std/net/tls/record-client.ts +110 -55
  88. package/std/net/tls/record-server.ts +159 -59
  89. package/std/net/tls/record.ts +109 -12
  90. package/std/net/tls/schedule.ts +235 -26
  91. package/std/net/tls/ticket.ts +159 -40
  92. package/std/net/tls/verify.ts +49 -3
  93. package/std/net/tls-tcp.ts +250 -45
  94. package/std/net/tls.ts +221 -59
  95. package/std/net/upstream.ts +81 -45
  96. package/std/net/url.ts +97 -13
  97. package/std/net/websocket.ts +122 -12
  98. package/std/net/webtransport.ts +220 -89
  99. package/std/pair.ts +10 -2
  100. package/std/random.ts +34 -9
  101. package/std/regex.ts +352 -198
  102. package/std/region.ts +70 -15
  103. package/std/secret.ts +52 -11
  104. package/std/sort.ts +17 -2
  105. package/std/sqlite.ts +256 -35
  106. package/std/sync/ring.ts +205 -35
  107. package/std/sync/shm.ts +194 -16
  108. package/std/term-io.ts +137 -64
  109. package/std/term-pixels.ts +144 -19
  110. package/std/term-probe.ts +66 -25
  111. package/std/term-rate.ts +128 -57
  112. package/std/term.ts +332 -121
  113. package/std/testing.ts +130 -32
  114. package/std/text.ts +73 -7
  115. package/std/threads.ts +229 -41
  116. package/std/yaml-json.ts +94 -82
  117. package/std/yaml-lines.ts +47 -15
  118. package/std/yaml-write.ts +24 -16
  119. package/std/yaml.ts +764 -384
@@ -8,17 +8,24 @@
8
8
  * the caller reuses, its content left where it lies as a window, and a frame
9
9
  * is written into the caller's buffer at an offset.
10
10
  *
11
- * import { Http2Frame, http2ReadHeader, http2ParseFrame, http2WriteData } from "nish/net/http2-frame";
11
+ * import {
12
+ * H2_FLAG_END_STREAM, Http2Frame, http2ReadHeader, http2ParseFrame, http2WriteData,
13
+ * } from "nish/net/http2-frame";
12
14
  *
13
- * const frame = new Http2Frame();
14
- * if (http2ReadHeader(frame, buf, off, len) && len >= 9 + frame.length) {
15
- * const error: i32 = http2ParseFrame(frame, buf, off, maxFrameSize);
16
- * // 0, or the connection error to close with; frame.streamError, the
17
- * // stream error to reset the stream with; then buf[frame.contentStart ..
18
- * // frame.contentStart + frame.contentLength) is the DATA, the header
19
- * // block fragment or the GOAWAY debug data.
20
- * }
21
- * const end: i32 = http2WriteData(out, at, streamId, body, 0, n, H2_FLAG_END_STREAM, -1);
15
+ * // `buf[off, off + len)` is what the peer sent; `maxFrameSize` is this side's SETTINGS_MAX_FRAME_SIZE.
16
+ * const read = (frame: Http2Frame, buf: u8[], off: i32, len: i32, maxFrameSize: i32): void => {
17
+ * if (http2ReadHeader(frame, buf, off, len) && len >= 9 + frame.length) {
18
+ * const error: i32 = http2ParseFrame(frame, buf, off, maxFrameSize);
19
+ * // 0, or the connection error to close with; frame.streamError, the
20
+ * // stream error to reset the stream with; then buf[frame.contentStart ..
21
+ * // frame.contentStart + frame.contentLength) is the DATA, the header
22
+ * // block fragment or the GOAWAY debug data.
23
+ * }
24
+ * };
25
+ * // `body[0, n)` goes into `out` at `at` as the last DATA of `streamId`; `end` is the offset after it.
26
+ * const send = (out: u8[], at: i32, streamId: i32, body: u8[], n: i32): void => {
27
+ * const end: i32 = http2WriteData(out, at, streamId, body, 0, n, H2_FLAG_END_STREAM, -1);
28
+ * };
22
29
  *
23
30
  * **What a parse refuses**, as the error code RFC 9113 names, which closes
24
31
  * the connection: a frame longer than the receiver's SETTINGS_MAX_FRAME_SIZE
@@ -46,8 +53,10 @@
46
53
  * **The writers** answer the offset after the frame, or -1 when it would not
47
54
  * fit in the buffer, which is then unchanged; a window outside its source
48
55
  * buffer, a stream identifier outside 0 to 2^31 − 1 and padding past 255 are
49
- * the program's mistakes and panic. They write any frame the reader accepts
50
- * and none it refuses, so a program cannot send what its peer must close for.
56
+ * the program's mistakes and panic. The writers of a frame type write none
57
+ * the reader refuses, so a program cannot send what its peer must close for,
58
+ * save a payload past the peer's SETTINGS_MAX_FRAME_SIZE, which they cannot
59
+ * know: they stop at 2^24 − 1. `http2WriteHeader` checks no type's rules.
51
60
  *
52
61
  * Private helpers share the importing program's flat symbol namespace
53
62
  * (`docs/wp26-stdlib.md` §3e), which is why each one carries the module's name.
@@ -58,20 +67,30 @@
58
67
  /** The size of a frame header: a 24-bit length, a type, flags and a 31-bit stream identifier (§4.1). */
59
68
  export const H2_FRAME_HEADER_SIZE: i32 = 9
60
69
 
61
- /** The frame types of §6. */
70
+ /** The frame types of §6, the header's type byte. DATA (0x0): a stream's body bytes (§6.1). */
62
71
  export const H2_FRAME_DATA: i32 = 0
72
+ /** HEADERS (0x1): opens a stream with a header block fragment, or carries trailers (§6.2). */
63
73
  export const H2_FRAME_HEADERS: i32 = 1
74
+ /** PRIORITY (0x2): a stream's dependency and weight, a scheme RFC 9113 deprecates (§6.3, §5.3.2). */
64
75
  export const H2_FRAME_PRIORITY: i32 = 2
76
+ /** RST_STREAM (0x3): ends one stream at once with an error code (§6.4). */
65
77
  export const H2_FRAME_RST_STREAM: i32 = 3
78
+ /** SETTINGS (0x4): the sender's settings, or with ACK their acknowledgement (§6.5). */
66
79
  export const H2_FRAME_SETTINGS: i32 = 4
80
+ /** PUSH_PROMISE (0x5): reserves a stream for a server push, with its request's header block (§6.6). */
67
81
  export const H2_FRAME_PUSH_PROMISE: i32 = 5
82
+ /** PING (0x6): eight opaque bytes the peer echoes back with ACK (§6.7). */
68
83
  export const H2_FRAME_PING: i32 = 6
84
+ /** GOAWAY (0x7): the sender is going away; names the last stream it may have processed (§6.8). */
69
85
  export const H2_FRAME_GOAWAY: i32 = 7
86
+ /** WINDOW_UPDATE (0x8): widens a stream's or the connection's flow-control window (§6.9). */
70
87
  export const H2_FRAME_WINDOW_UPDATE: i32 = 8
88
+ /** CONTINUATION (0x9): the next fragment of a header block a HEADERS or PUSH_PROMISE began (§6.10). */
71
89
  export const H2_FRAME_CONTINUATION: i32 = 9
72
90
 
73
- /** END_STREAM on DATA and HEADERS; ACK on SETTINGS and PING, the same bit. */
91
+ /** END_STREAM (0x1) on DATA and HEADERS: the sender's last frame on the stream. */
74
92
  export const H2_FLAG_END_STREAM: i32 = 1
93
+ /** ACK (0x1) on SETTINGS and PING, the same bit as END_STREAM: the frame acknowledges the peer's. */
75
94
  export const H2_FLAG_ACK: i32 = 1
76
95
  /** END_HEADERS on HEADERS, PUSH_PROMISE and CONTINUATION. */
77
96
  export const H2_FLAG_END_HEADERS: i32 = 4
@@ -80,37 +99,61 @@ export const H2_FLAG_PADDED: i32 = 8
80
99
  /** PRIORITY on HEADERS. */
81
100
  export const H2_FLAG_PRIORITY: i32 = 32
82
101
 
83
- /** The error codes of §7. */
102
+ /** The error codes of §7. NO_ERROR (0x0): not an error, as in a graceful GOAWAY; the parsers' "accepted". */
84
103
  export const H2_NO_ERROR: i32 = 0
104
+ /** PROTOCOL_ERROR (0x1): a generic protocol violation (§7). */
85
105
  export const H2_PROTOCOL_ERROR: i32 = 1
106
+ /** INTERNAL_ERROR (0x2): the sender hit an unexpected internal error (§7). */
86
107
  export const H2_INTERNAL_ERROR: i32 = 2
108
+ /** FLOW_CONTROL_ERROR (0x3): the peer broke flow control (§7). */
87
109
  export const H2_FLOW_CONTROL_ERROR: i32 = 3
110
+ /** SETTINGS_TIMEOUT (0x4): a SETTINGS was not acknowledged in time (§7). */
88
111
  export const H2_SETTINGS_TIMEOUT: i32 = 4
112
+ /** STREAM_CLOSED (0x5): a frame arrived on a stream that was half-closed for it (§7). */
89
113
  export const H2_STREAM_CLOSED: i32 = 5
114
+ /** FRAME_SIZE_ERROR (0x6): a frame had an invalid size (§7). */
90
115
  export const H2_FRAME_SIZE_ERROR: i32 = 6
116
+ /** REFUSED_STREAM (0x7): the stream was refused before any of it was processed; it may be retried (§7). */
91
117
  export const H2_REFUSED_STREAM: i32 = 7
118
+ /** CANCEL (0x8): the stream is no longer needed (§7). */
92
119
  export const H2_CANCEL: i32 = 8
120
+ /** COMPRESSION_ERROR (0x9): the field-compression context cannot be kept (§7). */
93
121
  export const H2_COMPRESSION_ERROR: i32 = 9
122
+ /** CONNECT_ERROR (0xa): the connection a CONNECT request made was reset or closed (§7). */
94
123
  export const H2_CONNECT_ERROR: i32 = 10
124
+ /** ENHANCE_YOUR_CALM (0xb): the peer is generating excessive load (§7). */
95
125
  export const H2_ENHANCE_YOUR_CALM: i32 = 11
126
+ /** INADEQUATE_SECURITY (0xc): the transport does not meet the minimum security requirements (§7). */
96
127
  export const H2_INADEQUATE_SECURITY: i32 = 12
128
+ /** HTTP_1_1_REQUIRED (0xd): the endpoint requires HTTP/1.1 instead of HTTP/2 (§7). */
97
129
  export const H2_HTTP_1_1_REQUIRED: i32 = 13
98
130
 
99
- /** The settings of §6.5.2, and RFC 8441's. */
131
+ /**
132
+ * The settings of §6.5.2, and RFC 8441's, by identifier. SETTINGS_HEADER_TABLE_SIZE (0x1): the most
133
+ * bytes of HPACK dynamic table the sender lets its peer's encoder use.
134
+ */
100
135
  export const H2_SETTINGS_HEADER_TABLE_SIZE: i32 = 1
136
+ /** SETTINGS_ENABLE_PUSH (0x2): 0 or 1, whether the sender allows server push. */
101
137
  export const H2_SETTINGS_ENABLE_PUSH: i32 = 2
138
+ /** SETTINGS_MAX_CONCURRENT_STREAMS (0x3): the most streams the sender lets its peer open at once. */
102
139
  export const H2_SETTINGS_MAX_CONCURRENT_STREAMS: i32 = 3
140
+ /** SETTINGS_INITIAL_WINDOW_SIZE (0x4): every stream's initial send window, in bytes, 0 to 2^31 − 1. */
103
141
  export const H2_SETTINGS_INITIAL_WINDOW_SIZE: i32 = 4
142
+ /** SETTINGS_MAX_FRAME_SIZE (0x5): the longest frame payload the sender takes, 2^14 to 2^24 − 1 bytes. */
104
143
  export const H2_SETTINGS_MAX_FRAME_SIZE: i32 = 5
144
+ /** SETTINGS_MAX_HEADER_LIST_SIZE (0x6): advisory, the largest field section the sender takes (§6.5.2). */
105
145
  export const H2_SETTINGS_MAX_HEADER_LIST_SIZE: i32 = 6
146
+ /** SETTINGS_ENABLE_CONNECT_PROTOCOL (0x8): 0 or 1, whether the sender takes extended CONNECT (RFC 8441). */
106
147
  export const H2_SETTINGS_ENABLE_CONNECT_PROTOCOL: i32 = 8
107
148
 
108
- /** A window's initial size, and the largest a window may reach (§6.9.1, §6.9.2). */
149
+ /** A window's initial size, 65,535 bytes, on the connection and on every stream (§6.9.2). */
109
150
  export const H2_DEFAULT_WINDOW: i32 = 65535
151
+ /** The largest a window may reach, and the largest INITIAL_WINDOW_SIZE: 2^31 − 1 bytes (§6.9.1). */
110
152
  export const H2_MAX_WINDOW: i32 = 2147483647
111
153
 
112
- /** SETTINGS_MAX_FRAME_SIZE's initial value, which is also its least, and its greatest (§6.5.2). */
154
+ /** SETTINGS_MAX_FRAME_SIZE's initial value, which is also its least: 2^14 bytes (§6.5.2). */
113
155
  export const H2_DEFAULT_MAX_FRAME: i32 = 16384
156
+ /** SETTINGS_MAX_FRAME_SIZE's greatest value, 2^24 − 1 bytes; a writer panics past it (§6.5.2). */
114
157
  export const H2_MAX_FRAME_LIMIT: i32 = 16777215
115
158
 
116
159
  /** The size of one setting: a 16-bit identifier and a 32-bit value. */
@@ -132,17 +175,28 @@ const H2_FRAME_EXCLUSIVE: i64 = 2147483648
132
175
  const H2_FRAME_U32_MAX: i64 = 4294967295
133
176
 
134
177
  /**
135
- * One frame, as `http2ReadHeader` and `http2ParseFrame` read it. Every field
136
- * is overwritten by the next read, so one frame serves a whole connection.
178
+ * One frame, as `http2ReadHeader` and `http2ParseFrame` read it. The next
179
+ * header read overwrites the header's fields; the next parse overwrites the
180
+ * content window, the padding and priority fields and `streamError`, and a
181
+ * type's own fields when it parses that type. A field only another type
182
+ * carries (`errorCode`, `lastStreamId`, `increment`, `promisedId`) keeps its
183
+ * last value, so a reader reads the fields of the type it parsed. One frame
184
+ * serves a whole connection.
137
185
  */
138
186
  export class Http2Frame {
139
187
  /** The payload's length, from the header. */
140
188
  length: i32 = 0
189
+ /** The frame type from the header, 0 to 255: an `H2_FRAME_*`, or a type this module does not know. */
141
190
  type: i32 = 0
191
+ /** The flags byte from the header, as sent, bits a type does not define included; `has` tests one. */
142
192
  flags: i32 = 0
143
193
  /** The stream identifier, the reserved bit dropped. */
144
194
  streamId: i32 = 0
145
- /** Where the payload starts in the buffer read. */
195
+ /**
196
+ * Where the payload starts in the buffer read.
197
+ *
198
+ * @internal Read by this module's parse and setting readers; a caller reads `contentStart`.
199
+ */
146
200
  payload: i32 = 0
147
201
  /**
148
202
  * The frame's content, `[contentStart, contentStart + contentLength)` of the
@@ -150,12 +204,18 @@ export class Http2Frame {
150
204
  * debug data, SETTINGS' settings; padding and fixed fields left out.
151
205
  */
152
206
  contentStart: i32 = 0
207
+ /**
208
+ * The content's length in bytes, from `contentStart`. For every type but DATA, HEADERS,
209
+ * PUSH_PROMISE and GOAWAY, the window is the whole payload.
210
+ */
153
211
  contentLength: i32 = 0
154
212
  /** The Pad Length field, or -1 without PADDED. */
155
213
  padLength: i32 = -1
156
214
  /** Whether a HEADERS frame carried the PRIORITY fields, as a PRIORITY frame always does. */
157
215
  hasPriority: boolean = false
216
+ /** Whether the stream dependency is exclusive (§5.3.1); false without priority fields. */
158
217
  exclusive: boolean = false
218
+ /** The stream this one depends on, the exclusive bit dropped; 0 without priority fields. */
159
219
  dependency: i32 = 0
160
220
  /** The weight, 1 to 256. */
161
221
  weight: i32 = 0
@@ -170,7 +230,12 @@ export class Http2Frame {
170
230
  /** A stream error the frame is, or 0: the stream is reset and the connection lives. */
171
231
  streamError: i32 = 0
172
232
 
173
- /** Whether the flag `bit` is set. */
233
+ /**
234
+ * Whether the flag `bit` is set.
235
+ *
236
+ * @param bit A flag mask, an `H2_FLAG_*`.
237
+ * @returns True when `flags` has any bit of `bit` set.
238
+ */
174
239
  has(bit: i32): boolean {
175
240
  return (this.flags & bit) !== 0
176
241
  }
@@ -213,6 +278,14 @@ const http2FramePut32 = (out: u8[], at: i32, value: i64): void => {
213
278
  * `off` hold one, and answers whether they did. The payload need not be there
214
279
  * yet: a reader checks `frame.length` against its limit before it waits for
215
280
  * the rest, which is what keeps a peer from making it buffer more.
281
+ *
282
+ * @param frame The frame its length, type, flags and stream identifier are written into; left as it was
283
+ * when the header is not all there.
284
+ * @param buf The bytes received, read and not kept.
285
+ * @param off Where the header starts in `buf`.
286
+ * @param len How many bytes from `off` have arrived; `[off, off + len)` outside `buf` panics.
287
+ * @returns True when nine bytes were there and the header was read; false when fewer were, with `frame`
288
+ * untouched, so the reader waits for more.
216
289
  */
217
290
  export const http2ReadHeader = (frame: Http2Frame, buf: u8[], off: i32, len: i32): boolean => {
218
291
  http2FrameCheckWindow("http2ReadHeader", buf, off, len)
@@ -266,6 +339,16 @@ const http2FramePriority = (frame: Http2Frame, buf: u8[], at: i32): void => {
266
339
  * SETTINGS_MAX_FRAME_SIZE. Answers 0, with the type's fields set and any
267
340
  * stream error in `streamError`, or the connection error the module comment
268
341
  * lists.
342
+ *
343
+ * @param frame The frame `http2ReadHeader` filled from the same `buf` and `off`; its content window,
344
+ * padding, priority fields, `streamError` and the parsed type's own fields are set.
345
+ * @param buf The bytes received; the content window points into it, so it must stay as it is while the
346
+ * content is read. `[off, off + 9 + frame.length)` outside `buf` panics.
347
+ * @param off Where the frame's header starts in `buf`.
348
+ * @param maxFrameSize This side's SETTINGS_MAX_FRAME_SIZE in bytes; a longer payload is refused.
349
+ * @returns 0 (`H2_NO_ERROR`) when the frame is accepted, `streamError` then holding 0 or the stream error
350
+ * to reset with (`H2_FRAME_SIZE_ERROR` or `H2_PROTOCOL_ERROR`); otherwise the connection error to close
351
+ * with, `H2_FRAME_SIZE_ERROR` or `H2_PROTOCOL_ERROR`.
269
352
  */
270
353
  export const http2ParseFrame = (frame: Http2Frame, buf: u8[], off: i32, maxFrameSize: i32): i32 => {
271
354
  http2FrameCheckWindow("http2ParseFrame", buf, off, H2_FRAME_HEADER_SIZE + frame.length)
@@ -370,16 +453,35 @@ export const http2ParseFrame = (frame: Http2Frame, buf: u8[], off: i32, maxFrame
370
453
  }
371
454
  }
372
455
 
373
- /** How many settings a SETTINGS frame `http2ParseFrame` accepted carries. */
456
+ /**
457
+ * How many settings a SETTINGS frame `http2ParseFrame` accepted carries.
458
+ *
459
+ * @param frame The SETTINGS frame just parsed.
460
+ * @returns The payload's length over six: 0 for an ACK or an empty SETTINGS.
461
+ */
374
462
  export const http2SettingCount = (frame: Http2Frame): i32 => frame.length / H2_SETTING_SIZE
375
463
 
376
- /** The identifier of setting `k` of the SETTINGS frame in `buf`. */
464
+ /**
465
+ * The identifier of setting `k` of the SETTINGS frame in `buf`.
466
+ *
467
+ * @param frame The SETTINGS frame `http2ParseFrame` accepted.
468
+ * @param buf The buffer that frame was read from, unchanged since.
469
+ * @param k Which setting, 0 to `http2SettingCount(frame)` − 1; nothing here checks the bound.
470
+ * @returns The 16-bit identifier, 0 to 65,535: an `H2_SETTINGS_*`, or one this module does not know.
471
+ */
377
472
  export const http2SettingId = (frame: Http2Frame, buf: u8[], k: i32): i32 => {
378
473
  const at: i32 = frame.payload + k * H2_SETTING_SIZE
379
474
  return (toI32(buf[at]) << 8) | toI32(buf[at + 1])
380
475
  }
381
476
 
382
- /** The value of setting `k` of the SETTINGS frame in `buf`, a 32-bit value. */
477
+ /**
478
+ * The value of setting `k` of the SETTINGS frame in `buf`.
479
+ *
480
+ * @param frame The SETTINGS frame `http2ParseFrame` accepted.
481
+ * @param buf The buffer that frame was read from, unchanged since.
482
+ * @param k Which setting, 0 to `http2SettingCount(frame)` − 1; nothing here checks the bound.
483
+ * @returns The value as sent, 0 to 2^32 − 1, not yet checked: `http2SettingError` checks it.
484
+ */
383
485
  export const http2SettingValue = (frame: Http2Frame, buf: u8[], k: i32): i64 =>
384
486
  http2FrameU32(buf, frame.payload + k * H2_SETTING_SIZE + 2)
385
487
 
@@ -387,6 +489,12 @@ export const http2SettingValue = (frame: Http2Frame, buf: u8[], k: i32): i64 =>
387
489
  * The connection error a setting's value is, or 0 (§6.5.2, RFC 8441 §3). A
388
490
  * setting this module does not know is not an error: §6.5.2 says it is
389
491
  * ignored.
492
+ *
493
+ * @param id The setting's identifier, as `http2SettingId` reads it.
494
+ * @param value The setting's value, as `http2SettingValue` reads it, 0 to 2^32 − 1.
495
+ * @returns `H2_PROTOCOL_ERROR` for an ENABLE_PUSH or ENABLE_CONNECT_PROTOCOL above 1 or a MAX_FRAME_SIZE
496
+ * outside 2^14 to 2^24 − 1; `H2_FLOW_CONTROL_ERROR` for an INITIAL_WINDOW_SIZE above 2^31 − 1;
497
+ * otherwise 0, every other identifier included.
390
498
  */
391
499
  export const http2SettingError = (id: i32, value: i64): i32 => {
392
500
  switch (id) {
@@ -407,7 +515,16 @@ export const http2SettingError = (id: i32, value: i64): i32 => {
407
515
  /**
408
516
  * Writes a frame header at `out[at]` for a payload of `length` bytes, and
409
517
  * answers where the payload goes, or -1 when the header and the payload would
410
- * not both fit.
518
+ * not both fit. It checks no type's rules: the payload is the caller's to write.
519
+ *
520
+ * @param out The buffer the frame is written into.
521
+ * @param at Where the frame starts in `out`; a negative offset panics.
522
+ * @param length The payload's length in bytes, 0 to 2^24 − 1; outside that panics.
523
+ * @param type The frame type byte, an `H2_FRAME_*` or another 0 to 255; only its low 8 bits are written.
524
+ * @param flags The flags byte, unchecked; only its low 8 bits are written.
525
+ * @param streamId The stream identifier, 0 for the connection, to 2^31 − 1; a negative one panics.
526
+ * @returns `at + 9`, where the payload goes, or -1 when `out` has no room for the header and `length`
527
+ * bytes after it, `out` then unchanged.
411
528
  */
412
529
  export const http2WriteHeader = (
413
530
  out: u8[],
@@ -443,7 +560,7 @@ const http2FrameCopy = (out: u8[], at: i32, src: u8[], off: i32, len: i32): void
443
560
  /**
444
561
  * The shared shape of DATA, HEADERS, PUSH_PROMISE and CONTINUATION: the
445
562
  * header, the Pad Length when `pad` is 0 to 255 (-1 for none), `fixed` bytes
446
- * the caller fills at the answer's offset minus `fixed`, the content and
563
+ * the caller fills just before the content, the content and
447
564
  * the padding. Answers the offset after the frame, or -1.
448
565
  */
449
566
  const http2FrameWritePadded = (
@@ -485,7 +602,22 @@ const http2FrameWritePadded = (
485
602
  return body + len + tail
486
603
  }
487
604
 
488
- /** Writes a DATA frame of `src[off, off + len)` on `streamId`, with `flags` (END_STREAM) and `pad` bytes of padding, -1 for none (§6.1). */
605
+ /**
606
+ * Writes a DATA frame of `src[off, off + len)` on `streamId`, with `flags` (END_STREAM) and `pad` bytes of
607
+ * padding, -1 for none (§6.1).
608
+ *
609
+ * @param out The buffer the frame is written into.
610
+ * @param at Where the frame starts in `out`; a negative offset panics.
611
+ * @param streamId The stream the data belongs to, 1 to 2^31 − 1; 0 or a negative identifier panics.
612
+ * @param src The buffer holding the data; copied, not kept.
613
+ * @param off Where the data starts in `src`.
614
+ * @param len The data's length in bytes; `[off, off + len)` outside `src` panics, and so does a
615
+ * payload past 2^24 − 1 bytes. Keeping it within the peer's SETTINGS_MAX_FRAME_SIZE is the caller's.
616
+ * @param flags `H2_FLAG_END_STREAM` or 0; any other bit is dropped.
617
+ * @param pad Bytes of zero padding, 0 to 255, or -1 (any negative) for none; past 255 panics. PADDED is
618
+ * set from it, never from `flags`.
619
+ * @returns The offset just past the frame in `out`, or -1 when it would not fit, `out` then unchanged.
620
+ */
489
621
  export const http2WriteData = (
490
622
  out: u8[],
491
623
  at: i32,
@@ -518,6 +650,20 @@ export const http2WriteData = (
518
650
  * len)` on `streamId`, with `flags` (END_STREAM, END_HEADERS) and `pad`
519
651
  * bytes of padding, -1 for none (§6.2). It never sets PRIORITY, which RFC
520
652
  * 9113 deprecates.
653
+ *
654
+ * @param out The buffer the frame is written into.
655
+ * @param at Where the frame starts in `out`; a negative offset panics.
656
+ * @param streamId The stream the headers open or belong to, 1 to 2^31 − 1; 0 or a negative identifier
657
+ * panics.
658
+ * @param src The buffer holding the fragment; copied, not kept.
659
+ * @param off Where the fragment starts in `src`.
660
+ * @param len The fragment's length in bytes; `[off, off + len)` outside `src` panics, and so does a
661
+ * payload past 2^24 − 1 bytes. Keeping it within the peer's SETTINGS_MAX_FRAME_SIZE is the caller's.
662
+ * @param flags `H2_FLAG_END_STREAM` and `H2_FLAG_END_HEADERS`, either or both or neither; any other bit
663
+ * is dropped.
664
+ * @param pad Bytes of zero padding, 0 to 255, or -1 (any negative) for none; past 255 panics. PADDED is
665
+ * set from it, never from `flags`.
666
+ * @returns The offset just past the frame in `out`, or -1 when it would not fit, `out` then unchanged.
521
667
  */
522
668
  export const http2WriteHeaders = (
523
669
  out: u8[],
@@ -547,7 +693,18 @@ export const http2WriteHeaders = (
547
693
  )
548
694
  }
549
695
 
550
- /** Writes a PRIORITY frame: `streamId` depends on `dependency`, exclusively or not, with `weight` 1 to 256 (§6.3). */
696
+ /**
697
+ * Writes a PRIORITY frame: `streamId` depends on `dependency`, exclusively or not, with `weight` 1 to 256
698
+ * (§6.3).
699
+ *
700
+ * @param out The buffer the frame is written into.
701
+ * @param at Where the frame starts in `out`; a negative offset panics.
702
+ * @param streamId The stream whose priority this sets, 1 to 2^31 − 1; 0 or a negative identifier panics.
703
+ * @param dependency The stream it depends on, 0 to 2^31 − 1; negative, or `streamId` itself, panics.
704
+ * @param exclusive Whether the dependency is exclusive (§5.3.1).
705
+ * @param weight The weight, 1 to 256, sent as one less; outside that panics.
706
+ * @returns The offset just past the frame in `out`, or -1 when it would not fit, `out` then unchanged.
707
+ */
551
708
  export const http2WritePriority = (
552
709
  out: u8[],
553
710
  at: i32,
@@ -569,7 +726,15 @@ export const http2WritePriority = (
569
726
  return body + 5
570
727
  }
571
728
 
572
- /** Writes a RST_STREAM frame closing `streamId` with `code` (§6.4). */
729
+ /**
730
+ * Writes a RST_STREAM frame closing `streamId` with `code` (§6.4).
731
+ *
732
+ * @param out The buffer the frame is written into.
733
+ * @param at Where the frame starts in `out`; a negative offset panics.
734
+ * @param streamId The stream to close, 1 to 2^31 − 1; 0 or a negative identifier panics.
735
+ * @param code The error code, an `H2_*` of §7 or another 32-bit value; only its low 32 bits are sent.
736
+ * @returns The offset just past the frame in `out`, or -1 when it would not fit, `out` then unchanged.
737
+ */
573
738
  export const http2WriteRstStream = (out: u8[], at: i32, streamId: i32, code: i64): i32 => {
574
739
  if (streamId === 0) {
575
740
  panic("http2WriteRstStream: RST_STREAM on stream 0")
@@ -586,6 +751,12 @@ export const http2WriteRstStream = (out: u8[], at: i32, streamId: i32, code: i64
586
751
  * Writes a SETTINGS frame of the settings `ids[k]` = `values[k]` (§6.5).
587
752
  * A value `http2SettingError` refuses panics, as two lists of different
588
753
  * lengths do.
754
+ *
755
+ * @param out The buffer the frame is written into.
756
+ * @param at Where the frame starts in `out`; a negative offset panics.
757
+ * @param ids The settings' identifiers, each 0 to 65,535, in the order sent; read, not kept.
758
+ * @param values The settings' values, `values[k]` for `ids[k]`, each 0 to 2^32 − 1; read, not kept.
759
+ * @returns The offset just past the frame in `out`, or -1 when it would not fit, `out` then unchanged.
589
760
  */
590
761
  export const http2WriteSettings = (out: u8[], at: i32, ids: i32[], values: i64[]): i32 => {
591
762
  const n: i32 = toI32(ids.length)
@@ -625,7 +796,13 @@ export const http2WriteSettings = (out: u8[], at: i32, ids: i32[], values: i64[]
625
796
  return body + n * H2_SETTING_SIZE
626
797
  }
627
798
 
628
- /** Writes the empty SETTINGS frame with ACK that acknowledges the peer's (§6.5.3). */
799
+ /**
800
+ * Writes the empty SETTINGS frame with ACK that acknowledges the peer's (§6.5.3).
801
+ *
802
+ * @param out The buffer the frame is written into.
803
+ * @param at Where the frame starts in `out`; a negative offset panics.
804
+ * @returns The offset just past the frame in `out`, or -1 when it would not fit, `out` then unchanged.
805
+ */
629
806
  export const http2WriteSettingsAck = (out: u8[], at: i32): i32 =>
630
807
  http2WriteHeader(out, at, H2_FRAME_ZERO, H2_FRAME_SETTINGS, H2_FLAG_ACK, H2_FRAME_ZERO)
631
808
 
@@ -633,6 +810,20 @@ export const http2WriteSettingsAck = (out: u8[], at: i32): i32 =>
633
810
  * Writes a PUSH_PROMISE frame on `streamId` reserving `promisedId`, carrying
634
811
  * the header block fragment `src[off, off + len)`, with `flags`
635
812
  * (END_HEADERS) and `pad` bytes of padding, -1 for none (§6.6).
813
+ *
814
+ * @param out The buffer the frame is written into.
815
+ * @param at Where the frame starts in `out`; a negative offset panics.
816
+ * @param streamId The stream of the request the promise answers, 1 to 2^31 − 1; 0 or a negative
817
+ * identifier panics.
818
+ * @param promisedId The stream reserved for the push, 1 to 2^31 − 1; 0 or a negative identifier panics.
819
+ * @param src The buffer holding the fragment; copied, not kept.
820
+ * @param off Where the fragment starts in `src`.
821
+ * @param len The fragment's length in bytes; `[off, off + len)` outside `src` panics, and so does a
822
+ * payload past 2^24 − 1 bytes. Keeping it within the peer's SETTINGS_MAX_FRAME_SIZE is the caller's.
823
+ * @param flags `H2_FLAG_END_HEADERS` or 0; any other bit is dropped.
824
+ * @param pad Bytes of zero padding, 0 to 255, or -1 (any negative) for none; past 255 panics. PADDED is
825
+ * set from it, never from `flags`.
826
+ * @returns The offset just past the frame in `out`, or -1 when it would not fit, `out` then unchanged.
636
827
  */
637
828
  export const http2WritePushPromise = (
638
829
  out: u8[],
@@ -671,7 +862,16 @@ export const http2WritePushPromise = (
671
862
  return end
672
863
  }
673
864
 
674
- /** Writes a PING frame of the eight bytes `opaque[off, off + 8)`, an ACK when `ack` (§6.7). */
865
+ /**
866
+ * Writes a PING frame of the eight bytes `opaque[off, off + 8)`, an ACK when `ack` (§6.7).
867
+ *
868
+ * @param out The buffer the frame is written into.
869
+ * @param at Where the frame starts in `out`; a negative offset panics.
870
+ * @param opaque The buffer holding the eight bytes; copied, not kept.
871
+ * @param off Where the eight bytes start in `opaque`; `[off, off + 8)` outside it panics.
872
+ * @param ack Whether this answers the peer's PING, its bytes echoed, rather than asking.
873
+ * @returns The offset just past the frame in `out`, or -1 when it would not fit, `out` then unchanged.
874
+ */
675
875
  export const http2WritePing = (out: u8[], at: i32, opaque: u8[], off: i32, ack: boolean): i32 => {
676
876
  http2FrameCheckWindow("http2WritePing", opaque, off, 8)
677
877
  const body: i32 = http2WriteHeader(out, at, 8, H2_FRAME_PING, ack ? H2_FLAG_ACK : 0, H2_FRAME_ZERO)
@@ -682,7 +882,21 @@ export const http2WritePing = (out: u8[], at: i32, opaque: u8[], off: i32, ack:
682
882
  return body + 8
683
883
  }
684
884
 
685
- /** Writes a GOAWAY frame naming `lastStreamId` and `code`, with the debug data `debug[off, off + len)` (§6.8). */
885
+ /**
886
+ * Writes a GOAWAY frame naming `lastStreamId` and `code`, with the debug data `debug[off, off + len)`
887
+ * (§6.8).
888
+ *
889
+ * @param out The buffer the frame is written into.
890
+ * @param at Where the frame starts in `out`; a negative offset panics.
891
+ * @param lastStreamId The highest peer-opened stream this side may have processed, 0 to 2^31 − 1; a
892
+ * negative one panics.
893
+ * @param code The error code, an `H2_*` of §7 or another 32-bit value; only its low 32 bits are sent.
894
+ * @param debug The buffer holding the debug data; copied, not kept.
895
+ * @param off Where the debug data starts in `debug`.
896
+ * @param len The debug data's length in bytes, 0 for none; `[off, off + len)` outside `debug` panics,
897
+ * and so does a payload past 2^24 − 1 bytes.
898
+ * @returns The offset just past the frame in `out`, or -1 when it would not fit, `out` then unchanged.
899
+ */
686
900
  export const http2WriteGoaway = (
687
901
  out: u8[],
688
902
  at: i32,
@@ -704,7 +918,16 @@ export const http2WriteGoaway = (
704
918
  return body + 8 + len
705
919
  }
706
920
 
707
- /** Writes a WINDOW_UPDATE frame adding `increment`, 1 to 2^31 − 1, to `streamId`'s window, or the connection's for 0 (§6.9). */
921
+ /**
922
+ * Writes a WINDOW_UPDATE frame adding `increment`, 1 to 2^31 − 1, to `streamId`'s window, or the
923
+ * connection's for 0 (§6.9).
924
+ *
925
+ * @param out The buffer the frame is written into.
926
+ * @param at Where the frame starts in `out`; a negative offset panics.
927
+ * @param streamId The stream whose window widens, or 0 for the connection's; a negative one panics.
928
+ * @param increment The bytes added to the window, 1 to 2^31 − 1; below 1 panics.
929
+ * @returns The offset just past the frame in `out`, or -1 when it would not fit, `out` then unchanged.
930
+ */
708
931
  export const http2WriteWindowUpdate = (out: u8[], at: i32, streamId: i32, increment: i32): i32 => {
709
932
  if (increment < 1) {
710
933
  panic(`http2WriteWindowUpdate: an increment of ${increment}`)
@@ -717,7 +940,21 @@ export const http2WriteWindowUpdate = (out: u8[], at: i32, streamId: i32, increm
717
940
  return body + 4
718
941
  }
719
942
 
720
- /** Writes a CONTINUATION frame of the header block fragment `src[off, off + len)`, with `flags` (END_HEADERS) (§6.10). */
943
+ /**
944
+ * Writes a CONTINUATION frame of the header block fragment `src[off, off + len)`, with `flags`
945
+ * (END_HEADERS) (§6.10). It is never padded.
946
+ *
947
+ * @param out The buffer the frame is written into.
948
+ * @param at Where the frame starts in `out`; a negative offset panics.
949
+ * @param streamId The stream whose header block this continues, 1 to 2^31 − 1; 0 or a negative
950
+ * identifier panics.
951
+ * @param src The buffer holding the fragment; copied, not kept.
952
+ * @param off Where the fragment starts in `src`.
953
+ * @param len The fragment's length in bytes; `[off, off + len)` outside `src` panics, and so does a
954
+ * payload past 2^24 − 1 bytes. Keeping it within the peer's SETTINGS_MAX_FRAME_SIZE is the caller's.
955
+ * @param flags `H2_FLAG_END_HEADERS` or 0; any other bit is dropped.
956
+ * @returns The offset just past the frame in `out`, or -1 when it would not fit, `out` then unchanged.
957
+ */
721
958
  export const http2WriteContinuation = (
722
959
  out: u8[],
723
960
  at: i32,