@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
package/std/net/hpack.ts CHANGED
@@ -12,6 +12,9 @@
12
12
  *
13
13
  * import { HpackDecoder, HpackEncoder, HPACK_INDEX_INCREMENTAL, HPACK_OK } from "nish/net/hpack";
14
14
  *
15
+ * const name: u8[] = [58, 112, 97, 116, 104]; // ":path"
16
+ * const value: u8[] = [47]; // "/"
17
+ *
15
18
  * const enc = new HpackEncoder(4096);
16
19
  * const block: u8[] = [];
17
20
  * enc.encodeField(block, name, value, HPACK_INDEX_INCREMENTAL, true);
@@ -32,12 +35,13 @@
32
35
  * end of the tables, Huffman padding longer than seven bits or not all ones,
33
36
  * the EOS symbol inside a string, a table size update above the SETTINGS limit
34
37
  * or after the block's first field, and a block that does not begin with the
35
- * update a lowered limit requires (§4.2). Each of those is HTTP/2's
36
- * COMPRESSION_ERROR, which closes the connection, so the code is sticky: every
37
- * later `decode` answers it again without reading anything. So is
38
- * `HPACK_ERR_COPY_BUDGET`, a block that would make the table copy more than
39
- * `HPACK_COPY_FACTOR` times the larger of its size and the block's length,
40
- * which HTTP/2 answers with ENHANCE_YOUR_CALM.
38
+ * update a lowered limit requires (§4.2).
39
+ *
40
+ * Each of those is HTTP/2's COMPRESSION_ERROR, which closes the connection, so
41
+ * the code is sticky: every later `decode` answers it again without reading
42
+ * anything. So is `HPACK_ERR_COPY_BUDGET`, a block that would make the table
43
+ * copy more than `HPACK_COPY_FACTOR` times the larger of its size and the
44
+ * block's length, which HTTP/2 answers with ENHANCE_YOUR_CALM.
41
45
  *
42
46
  * A header list larger than the caller's limit is not one of them. The block
43
47
  * is still decoded to its end, so that the table stays in step with the
@@ -407,24 +411,44 @@ const hpackCheckWindow = (what: string, buf: u8[], off: i32, len: i32): void =>
407
411
  *
408
412
  * Canonical means that the codes of one length are consecutive integers in
409
413
  * symbol order, and that the first code of a length is one past the last code
410
- * of the length before, shifted left by the difference. So `firstCode[L]` and
411
- * `countAt[L]` say which `L`-bit integers are codes, and `symbols` lists the
412
- * symbols in code order, `baseRank[L]` being where length `L` starts in it.
414
+ * of the length before, shifted left by the difference. So the first code of
415
+ * each length and how many codes it has say which `L`-bit integers are codes,
416
+ * and a list of the symbols in code order, with where each length starts in
417
+ * it, turns such a code into its symbol: decoding needs no tree.
413
418
  */
414
419
  export class HpackHuffman {
415
- /** The code of each symbol, aligned on its least significant bit. */
420
+ /**
421
+ * The code of each symbol, aligned on its least significant bit.
422
+ * @internal Read by `hpackHuffmanEncode`; not for callers.
423
+ */
416
424
  codes: i32[]
417
- /** The length of each symbol's code, in bits. */
425
+ /**
426
+ * The length of each symbol's code, in bits.
427
+ * @internal Read by `hpackHuffmanLength` and `hpackHuffmanEncode`; not for callers.
428
+ */
418
429
  lengths: i32[]
419
- /** The symbols in code order. */
430
+ /**
431
+ * The symbols in code order.
432
+ * @internal Read by `hpackHuffmanDecode`; not for callers.
433
+ */
420
434
  symbols: i32[]
421
- /** The first code of each length, by length (0 to 30). */
435
+ /**
436
+ * The first code of each length, by length (0 to 30).
437
+ * @internal Read by `hpackHuffmanDecode` and by `qpack.ts`'s Huffman decoder; not for callers.
438
+ */
422
439
  firstCode: i32[]
423
- /** How many codes each length has, by length. */
440
+ /**
441
+ * How many codes each length has, by length.
442
+ * @internal Read by `hpackHuffmanDecode` and by `qpack.ts`'s Huffman decoder; not for callers.
443
+ */
424
444
  countAt: i32[]
425
- /** Where each length's symbols start in `symbols`, by length. */
445
+ /**
446
+ * Where each length's symbols start in `symbols`, by length.
447
+ * @internal Read by `hpackHuffmanDecode`; not for callers.
448
+ */
426
449
  baseRank: i32[]
427
450
 
451
+ /** Rebuilds the code from Appendix B's 257 code lengths. Build one and reuse it: each build allocates. */
428
452
  constructor() {
429
453
  this.codes = new Array<i32>(257)
430
454
  this.lengths = new Array<i32>(257)
@@ -454,7 +478,15 @@ export class HpackHuffman {
454
478
  }
455
479
  }
456
480
 
457
- /** The length of `src[off, off + len)` once Huffman-coded, in bytes. */
481
+ /**
482
+ * The length of `src[off, off + len)` once Huffman-coded, in bytes, padding included. A window outside
483
+ * `src` panics, as does a coded length past 2^31 - 1 bytes.
484
+ * @param h The code to measure with.
485
+ * @param src The octets to measure; only read.
486
+ * @param off Where the window starts, an index into `src`.
487
+ * @param len How many octets from `off` on to measure.
488
+ * @returns The number of bytes `hpackHuffmanEncode` would append for the same window, 0 for an empty one.
489
+ */
458
490
  export const hpackHuffmanLength = (h: HpackHuffman, src: u8[], off: i32, len: i32): i32 => {
459
491
  hpackCheckWindow("hpackHuffmanLength", src, off, len)
460
492
  let bits: i64 = 0
@@ -478,6 +510,12 @@ export const hpackHuffmanLength = (h: HpackHuffman, src: u8[], off: i32, len: i3
478
510
  *
479
511
  * The accumulator holds fewer than eight waiting bits between symbols, and a
480
512
  * code is at most 30, so it never needs more than 37 bits.
513
+ * A window outside `src` panics.
514
+ * @param h The code to encode with.
515
+ * @param src The octets to encode; only read.
516
+ * @param off Where the window starts, an index into `src`.
517
+ * @param len How many octets from `off` on to encode.
518
+ * @param out Where the coded bytes go: appended after what it holds, `hpackHuffmanLength` of them.
481
519
  */
482
520
  export const hpackHuffmanEncode = (h: HpackHuffman, src: u8[], off: i32, len: i32, out: u8[]): void => {
483
521
  hpackCheckWindow("hpackHuffmanEncode", src, off, len)
@@ -510,6 +548,16 @@ export const hpackHuffmanEncode = (h: HpackHuffman, src: u8[], off: i32, len: i3
510
548
  * thirty bits always are. What is left when the input ends is padding, which
511
549
  * §5.2 requires to be a prefix of EOS — all ones — and shorter than a byte.
512
550
  * `out` keeps what was decoded before an error; a caller discards it.
551
+ * A window outside `src` panics.
552
+ * @param h The code to decode with.
553
+ * @param src The coded bytes, the peer's; only read.
554
+ * @param off Where the window starts, an index into `src`.
555
+ * @param len How many bytes from `off` on to decode; every one is read unless an EOS comes first.
556
+ * @param out Where the decoded octets go, appended after what it holds: at most `len * 8 / 5` of them,
557
+ * since every code is at least five bits long.
558
+ * @returns `HPACK_OK` when the window decoded whole and ended in valid padding; `HPACK_ERR_HUFFMAN_EOS` when
559
+ * a complete code was the EOS symbol, at the point it was read; `HPACK_ERR_HUFFMAN_PADDING` when the bits
560
+ * left after the last symbol are more than seven or not all ones.
513
561
  */
514
562
  export const hpackHuffmanDecode = (h: HpackHuffman, src: u8[], off: i32, len: i32, out: u8[]): i32 => {
515
563
  hpackCheckWindow("hpackHuffmanDecode", src, off, len)
@@ -546,11 +594,26 @@ export const hpackHuffmanDecode = (h: HpackHuffman, src: u8[], off: i32, len: i3
546
594
  * and where the block ends. The primitives below advance `pos`.
547
595
  */
548
596
  export class HpackCursor {
597
+ /** @internal The block being read; read by this module's decoders, not for callers. */
549
598
  buf: u8[]
599
+ /**
600
+ * Where the next read starts, as an index into the cursor's buffer. `hpackDecodeInteger` and
601
+ * `hpackDecodeString` move it past what they read; after a negative answer it is wherever the read
602
+ * stopped, which a caller should not rely on.
603
+ */
550
604
  pos: i32
605
+ /**
606
+ * One past the last byte the cursor may read.
607
+ * @internal Read by this module's decoders; not for callers.
608
+ */
551
609
  end: i32
552
610
 
553
- /** A cursor over `buf[off, off + len)`, which must lie inside `buf`. */
611
+ /**
612
+ * A cursor over `buf[off, off + len)`, which must lie inside `buf`: a window outside it panics.
613
+ * @param buf The block to read; kept by reference, not copied, so it must not change while it is read.
614
+ * @param off Where the first read starts, an index into `buf`.
615
+ * @param len How many bytes from `off` on the cursor may read.
616
+ */
554
617
  constructor(buf: u8[], off: i32, len: i32) {
555
618
  hpackCheckWindow("HpackCursor", buf, off, len)
556
619
  this.buf = buf
@@ -558,7 +621,10 @@ export class HpackCursor {
558
621
  this.end = off + len
559
622
  }
560
623
 
561
- /** Points the cursor at `buf[off, off + len)` instead, which must lie inside `buf`. */
624
+ /**
625
+ * Points the cursor at `buf[off, off + len)` instead, which must lie inside `buf`.
626
+ * @internal Called by `HpackDecoder.decode` for each block; not for callers.
627
+ */
562
628
  reset(buf: u8[], off: i32, len: i32): void {
563
629
  hpackCheckWindow("HpackCursor", buf, off, len)
564
630
  this.buf = buf
@@ -572,6 +638,12 @@ export class HpackCursor {
572
638
  * first byte's high bits being `flags` (the representation's pattern).
573
639
  * A negative value, or a prefix outside 1 to 8 bits, panics: both are the
574
640
  * program's choice.
641
+ * @param out Where the integer's bytes go, appended after what it holds: one byte when `value` fits the
642
+ * prefix, else the prefix byte and one to five continuation bytes.
643
+ * @param flags The first byte's bits above the prefix; it must leave the low `prefixBits` bits clear, since
644
+ * they are or-ed with it.
645
+ * @param prefixBits How many low bits of the first byte the integer starts in, 1 to 8.
646
+ * @param value The integer, 0 to 2^31 - 1.
575
647
  */
576
648
  export const hpackEncodeInteger = (out: u8[], flags: i32, prefixBits: i32, value: i32): void => {
577
649
  if (prefixBits < 1 || prefixBits > 8 || value < 0) {
@@ -600,6 +672,11 @@ export const hpackEncodeInteger = (out: u8[], flags: i32, prefixBits: i32, value
600
672
  * An `i32` needs at most five continuation bytes after a full prefix, so a
601
673
  * sixth is refused even when its bits are zero; otherwise a run of `0x80`
602
674
  * bytes would be read for as long as the peer cared to send it.
675
+ * @param c Where to read; its position moves past every byte read, also when the answer is an error.
676
+ * @param prefixBits How many low bits of the first byte hold the prefix, 1 to 8; the bits above are not read.
677
+ * @returns The integer, 0 to 2^31 - 1; `HPACK_ERR_TRUNCATED` when the cursor has no byte left before the
678
+ * integer ends, at the first byte or at a continuation byte; `HPACK_ERR_INTEGER_OVERFLOW` when the value
679
+ * passes 2^31 - 1, or when the fifth continuation byte still has its continuation bit set.
603
680
  */
604
681
  export const hpackDecodeInteger = (c: HpackCursor, prefixBits: i32): i32 => {
605
682
  if (prefixBits < 1 || prefixBits > 8) {
@@ -636,6 +713,11 @@ export const hpackDecodeInteger = (c: HpackCursor, prefixBits: i32): i32 => {
636
713
  * Appends `data` as a §5.2 string literal: Huffman-coded when `huffman` is
637
714
  * true, else raw. A caller who wants the shorter of the two compares
638
715
  * `hpackHuffmanLength` with the raw length.
716
+ * @param h The code to encode with when `huffman` is true.
717
+ * @param out Where the literal goes, appended after what it holds: its length with a 7-bit prefix and the
718
+ * H bit, then the octets.
719
+ * @param data The octets to write, all of them; only read.
720
+ * @param huffman Whether to Huffman-code them, even when that is longer than raw.
639
721
  */
640
722
  export const hpackEncodeString = (h: HpackHuffman, out: u8[], data: u8[], huffman: boolean): void => {
641
723
  const n: i32 = toI32(data.length)
@@ -654,6 +736,16 @@ export const hpackEncodeString = (h: HpackHuffman, out: u8[], data: u8[], huffma
654
736
  * Reads a §5.2 string literal at the cursor and appends its octets to `out`,
655
737
  * answering `HPACK_OK` or a negative `HPACK_ERR_*` code. The length is checked
656
738
  * against what the block has left before anything is read.
739
+ * @param h The code to decode a Huffman-coded literal with.
740
+ * @param c Where to read; on `HPACK_OK` its position is just past the literal. On an error it is wherever
741
+ * the read stopped.
742
+ * @param out Where the string's octets go, appended after what it holds; on an error it keeps whatever was
743
+ * appended before the error, which a caller discards. The literal's length is bounded only by what the
744
+ * block has left, and a Huffman-coded one decodes to at most 8/5 of its coded length.
745
+ * @returns `HPACK_OK` when the literal was read whole; `HPACK_ERR_TRUNCATED` when the cursor has no byte
746
+ * left, the length integer ends early, or the length is more than the block has left after it;
747
+ * `HPACK_ERR_INTEGER_OVERFLOW` when the length passes 2^31 - 1 or is padded past five continuation bytes;
748
+ * `HPACK_ERR_HUFFMAN_EOS` or `HPACK_ERR_HUFFMAN_PADDING` from `hpackHuffmanDecode` for a Huffman-coded one.
657
749
  */
658
750
  export const hpackDecodeString = (h: HpackHuffman, c: HpackCursor, out: u8[]): i32 => {
659
751
  if (c.pos >= c.end) {
@@ -683,25 +775,42 @@ export const hpackDecodeString = (h: HpackHuffman, c: HpackCursor, out: u8[]): i
683
775
  * whose size — every entry's name and value plus 32 — never passes `maxSize`.
684
776
  *
685
777
  * Every entry's octets live in one store, `bytes`: its name, then its value,
686
- * oldest entry first. `entries` says where each entry sits, two numbers to an
778
+ * oldest entry first. An index says where each entry sits, two numbers to an
687
779
  * entry — where it starts in `bytes` and how long its name is; its value runs
688
780
  * to where the next one starts — oldest first from entry `first` on, so that
689
- * adding one is two `push`es and evicting one moves `first`. The evicted
690
- * prefix of `entries`, and of `bytes`, is shifted out in place once it is half
691
- * of either, which keeps both amortised constant time without a ring's index
692
- * arithmetic. Shifting and popping keep an array's storage, and `bytes` never
693
- * holds more than three times `maxSize`, so a table the peer fills and empties
694
- * for as long as it likes stops allocating once its arrays have grown that far
695
- * (`docs/security/http2.md`, H2-1). Dynamic index 1, the newest entry, is the
696
- * last.
781
+ * adding one is two `push`es and evicting one moves `first`.
782
+ *
783
+ * The evicted prefix of the index, and of `bytes`, is shifted out in place once
784
+ * it is half of either, which keeps both amortised constant time without a
785
+ * ring's index arithmetic. Shifting and popping keep an array's storage, and
786
+ * `bytes` never holds more than three times `maxSize`, so a table the peer
787
+ * fills and empties for as long as it likes stops allocating once its arrays
788
+ * have grown that far (`docs/security/http2.md`, H2-1). Dynamic index 1, the
789
+ * newest entry, is the last.
697
790
  */
698
791
  export class HpackTable {
792
+ /**
793
+ * Every entry's octets, its name then its value, oldest first, after any evicted entries' octets not yet
794
+ * shifted out. Any change to the table may move what it holds.
795
+ */
699
796
  bytes: u8[]
700
- entries: i32[]
797
+ private entries: i32[]
798
+ /**
799
+ * How many evicted entries the table still records before its oldest live one: eviction moves it up,
800
+ * and shifting the evicted ones out returns it to 0.
801
+ */
701
802
  first: i32
803
+ /**
804
+ * The table's size as §4.1 counts it, in octets: every entry's name and value plus 32; at most `maxSize`.
805
+ */
702
806
  size: i32
807
+ /** The most `size` may be, in octets (§4.2); set by the constructor and `resize`. */
703
808
  maxSize: i32
704
809
 
810
+ /**
811
+ * An empty table.
812
+ * @param maxSize The most its size may be, in octets as §4.1 counts them; a negative one panics.
813
+ */
705
814
  constructor(maxSize: i32) {
706
815
  if (maxSize < 0) {
707
816
  panic(`HpackTable: a maximum size of ${maxSize}`)
@@ -714,75 +823,105 @@ export class HpackTable {
714
823
  }
715
824
 
716
825
  /** How many entries `entries` describes, evicted ones included. */
717
- slots(): i32 {
826
+ private slots(): i32 {
718
827
  return toI32(this.entries.length) >> 1
719
828
  }
720
829
 
721
- /** How many entries the table holds. */
830
+ /**
831
+ * How many entries the table holds.
832
+ * @returns The live entry count: dynamic indexes 1 to it are in range; 0 when the table is empty.
833
+ */
722
834
  count(): i32 {
723
835
  return this.slots() - this.first
724
836
  }
725
837
 
726
838
  /** Where dynamic entry `i`, 1 being the newest, sits in `entries`; `i` must be in range. */
727
- slot(i: i32): i32 {
839
+ private slot(i: i32): i32 {
728
840
  return this.slots() - i
729
841
  }
730
842
 
731
843
  /** Where entry `k` of `entries` starts in `bytes`. */
732
- startOf(k: i32): i32 {
844
+ private startOf(k: i32): i32 {
733
845
  return this.entries[k * 2]
734
846
  }
735
847
 
736
848
  /** Where entry `k` of `entries` ends in `bytes`: where the next starts, or the end of `bytes`. */
737
- endOf(k: i32): i32 {
849
+ private endOf(k: i32): i32 {
738
850
  return k + 1 < this.slots() ? this.entries[k * 2 + 2] : toI32(this.bytes.length)
739
851
  }
740
852
 
741
853
  /** What entry `k` of `entries` costs (§4.1); it fits an `i32` because the table holds it. */
742
- costOf(k: i32): i32 {
854
+ private costOf(k: i32): i32 {
743
855
  return this.endOf(k) - this.startOf(k) + HPACK_ENTRY_OVERHEAD
744
856
  }
745
857
 
746
- /** Where the name of dynamic entry `i` starts in `bytes`. */
858
+ /**
859
+ * Where the name of dynamic entry `i` starts in `bytes`.
860
+ * @param i The dynamic index, 1 being the newest; it must be from 1 to `count()` and is not checked.
861
+ * @returns The offset in `bytes`, valid until the table next changes.
862
+ */
747
863
  nameStart(i: i32): i32 {
748
864
  return this.startOf(this.slot(i))
749
865
  }
750
866
 
751
- /** How many octets the name of dynamic entry `i` has. */
867
+ /**
868
+ * How many octets the name of dynamic entry `i` has.
869
+ * @internal Read by this module's decoder and encoder; not for callers.
870
+ */
752
871
  nameLength(i: i32): i32 {
753
872
  return this.entries[this.slot(i) * 2 + 1]
754
873
  }
755
874
 
756
- /** Where the value of dynamic entry `i` starts in `bytes`, straight after its name. */
875
+ /**
876
+ * Where the value of dynamic entry `i` starts in `bytes`, straight after its name.
877
+ * @internal Read by this module's decoder and encoder; not for callers.
878
+ */
757
879
  valueStart(i: i32): i32 {
758
880
  return this.nameStart(i) + this.nameLength(i)
759
881
  }
760
882
 
761
- /** How many octets the value of dynamic entry `i` has. */
883
+ /**
884
+ * How many octets the value of dynamic entry `i` has.
885
+ * @internal Read by this module's decoder and encoder; not for callers.
886
+ */
762
887
  valueLength(i: i32): i32 {
763
888
  return this.endOf(this.slot(i)) - this.valueStart(i)
764
889
  }
765
890
 
766
- /** What dynamic entry `i` costs (§4.1). */
891
+ /**
892
+ * What dynamic entry `i` costs (§4.1).
893
+ * @internal Read by `HpackDecoder`; not for callers.
894
+ */
767
895
  entrySize(i: i32): i32 {
768
896
  return this.costOf(this.slot(i))
769
897
  }
770
898
 
771
- /** A fresh copy of the name of dynamic entry `i`. It allocates; the codec reads the window instead. */
899
+ /**
900
+ * A fresh copy of the name of dynamic entry `i`. It allocates; the codec reads the window instead.
901
+ * @param i The dynamic index, 1 being the newest; it must be from 1 to `count()` and is not checked.
902
+ * @returns A new array, the caller's to keep.
903
+ */
772
904
  name(i: i32): u8[] {
773
905
  const out: u8[] = []
774
906
  hpackAppend(out, this.bytes, this.nameStart(i), this.nameLength(i))
775
907
  return out
776
908
  }
777
909
 
778
- /** A fresh copy of the value of dynamic entry `i`, as `name` makes the name. */
910
+ /**
911
+ * A fresh copy of the value of dynamic entry `i`, as `name` makes the name.
912
+ * @param i The dynamic index, 1 being the newest; it must be from 1 to `count()` and is not checked.
913
+ * @returns A new array, the caller's to keep.
914
+ */
779
915
  value(i: i32): u8[] {
780
916
  const out: u8[] = []
781
917
  hpackAppend(out, this.bytes, this.valueStart(i), this.valueLength(i))
782
918
  return out
783
919
  }
784
920
 
785
- /** Evicts the oldest entries until the size is at most `limit` (§4.4). */
921
+ /**
922
+ * Evicts the oldest entries until the size is at most `limit` (§4.4).
923
+ * @internal Called by `add`, `resize` and `HpackDecoder`; not for callers.
924
+ */
786
925
  evictTo(limit: i32): void {
787
926
  while (toI64(this.size) > toI64(limit) && this.count() > 0) {
788
927
  this.size -= this.costOf(this.first)
@@ -792,7 +931,7 @@ export class HpackTable {
792
931
  }
793
932
 
794
933
  /** Shifts the evicted prefix out of `entries`, and out of `bytes`, once it is half of either. */
795
- compact(): void {
934
+ private compact(): void {
796
935
  const end: i32 = toI32(this.bytes.length)
797
936
  const start: i32 = this.count() > 0 ? this.startOf(this.first) : end
798
937
  const n: i32 = this.slots()
@@ -826,6 +965,11 @@ export class HpackTable {
826
965
  * added (§4.4): that is not an error. Neither array may be `bytes` itself,
827
966
  * since eviction may move what it holds. Returns the octets it pushed into
828
967
  * `bytes`: none for an entry it did not add.
968
+ * @param name The entry's name; copied in, not kept.
969
+ * @param value The entry's value; copied in, not kept.
970
+ * @returns How many octets it pushed into `bytes`, the name's and the value's together: 0 when the entry
971
+ * was larger than `maxSize` and the table was emptied instead, and also for an added entry whose name
972
+ * and value are both empty.
829
973
  */
830
974
  add(name: u8[], value: u8[]): i32 {
831
975
  const cost: i64 = hpackEntrySize(name, value)
@@ -850,7 +994,10 @@ export class HpackTable {
850
994
  return pushed
851
995
  }
852
996
 
853
- /** Sets the maximum size, evicting what no longer fits (§4.3). */
997
+ /**
998
+ * Sets the maximum size, evicting what no longer fits (§4.3).
999
+ * @param maxSize The new maximum, in octets as §4.1 counts them; a negative one panics.
1000
+ */
854
1001
  resize(maxSize: i32): void {
855
1002
  if (maxSize < 0) {
856
1003
  panic(`HpackTable.resize: a maximum size of ${maxSize}`)
@@ -898,11 +1045,15 @@ const HPACK_FIELD_CLASSES: i32 = 24
898
1045
  * class, each class made when first needed.
899
1046
  */
900
1047
  export class HpackWork {
1048
+ /** @internal The read position, reset for each block by `HpackDecoder.decode`; not for callers. */
901
1049
  cursor: HpackCursor
1050
+ /** @internal A literal's new name as it is read, by `HpackDecoder`; not for callers. */
902
1051
  nameScratch: u8[]
1052
+ /** @internal A literal's value as it is read, by `HpackDecoder`; not for callers. */
903
1053
  valueScratch: u8[]
904
- pools: u8[][][]
1054
+ private pools: u8[][][]
905
1055
 
1056
+ /** Empty scratch arrays, a cursor over nothing, and no pools until a field needs one. */
906
1057
  constructor() {
907
1058
  this.nameScratch = []
908
1059
  this.valueScratch = []
@@ -911,7 +1062,10 @@ export class HpackWork {
911
1062
  this.pools = []
912
1063
  }
913
1064
 
914
- /** The smallest size class with room for `length` octets: the first `j` with 2^j past it, at most the last. */
1065
+ /**
1066
+ * The smallest size class with room for `length` octets: the first `j` with 2^j past it, at most the last.
1067
+ * @internal Called by `HpackDecoder` as it gives fields back; not for callers.
1068
+ */
915
1069
  classOf(length: i32): i32 {
916
1070
  let j: i32 = 0
917
1071
  while (j < HPACK_FIELD_CLASSES - 1 && 1 << j <= length) {
@@ -920,7 +1074,10 @@ export class HpackWork {
920
1074
  return j
921
1075
  }
922
1076
 
923
- /** The pool of class `j`, made the first time a field needs it. */
1077
+ /**
1078
+ * The pool of class `j`, made the first time a field needs it.
1079
+ * @internal Called by `HpackDecoder` as it gives fields back; not for callers.
1080
+ */
924
1081
  pool(j: i32): u8[][] {
925
1082
  while (toI32(this.pools.length) <= j) {
926
1083
  const fresh: u8[][] = []
@@ -933,6 +1090,7 @@ export class HpackWork {
933
1090
  * An empty array with room for `length` octets: one an earlier block gave
934
1091
  * back, emptied, to its class's pool, or, once the pool is empty, a new one made with
935
1092
  * the class's room.
1093
+ * @internal Called by `HpackDecoder` for each field it answers; not for callers.
936
1094
  */
937
1095
  take(length: i32): u8[] {
938
1096
  const j: i32 = this.classOf(length)
@@ -953,46 +1111,76 @@ export class HpackWork {
953
1111
  * One HTTP/2 connection's receiving side: its dynamic table, the SETTINGS
954
1112
  * limit the table may grow to, and the header-list limit.
955
1113
  *
956
- * `decode` answers the block's fields in `names`, `values` and
957
- * `neverIndexed`, which it empties and refills on every call. Each name and
958
- * value is an array the decoder owns, taken from its working storage's pools
959
- * by its length and given back, emptied, at the next block, so **a field is
960
- * valid until the next `decode`**: a caller that keeps one past it copies it,
961
- * since the next block may refill the same array with another field. That is
962
- * what keeps the storage a peer can make a connection hold bounded by the
963
- * header-list limit, however many blocks it sends and whatever becomes of
1114
+ * `decode` answers the block's fields in `names`, `values` and `neverIndexed`,
1115
+ * which it empties and refills on every call. Each name and value is an array
1116
+ * the decoder owns, taken from its working storage's pools by its length and
1117
+ * given back, emptied, at the next block, so **a field is valid until the next
1118
+ * `decode`**: a caller that keeps one past it copies it, since the next block
1119
+ * may refill the same array with another field.
1120
+ *
1121
+ * That is what keeps the storage a peer can make a connection hold bounded by
1122
+ * the header-list limit, however many blocks it sends and whatever becomes of
964
1123
  * their streams (`docs/security/http2.md`, H2-1): a class `j` array holds a
965
1124
  * field of at least 2^(j-1) octets, so no class ever holds more than about
966
- * twice the limit, and only the classes up to log2 of the limit, plus one,
967
- * hold any. `settingsLimit` is the SETTINGS_HEADER_TABLE_SIZE this endpoint
1125
+ * twice the limit, and only the classes up to log2 of the limit, plus one, hold
1126
+ * any. `settingsLimit` is the SETTINGS_HEADER_TABLE_SIZE this endpoint
968
1127
  * advertised and the peer acknowledged; the table starts at it.
969
- * `maxHeaderListSize` counts each field as its name, its value and 32 bytes,
970
- * as SETTINGS_MAX_HEADER_LIST_SIZE does (RFC 9113 §6.5.2).
1128
+ * `maxHeaderListSize` counts each field as its name, its value and 32 bytes, as
1129
+ * SETTINGS_MAX_HEADER_LIST_SIZE does (RFC 9113 §6.5.2).
971
1130
  */
972
1131
  export class HpackDecoder {
1132
+ /** The dynamic table, as the blocks decoded so far have left it. */
973
1133
  table: HpackTable
974
- huffman: HpackHuffman
1134
+ private huffman: HpackHuffman
1135
+ /**
1136
+ * The SETTINGS_HEADER_TABLE_SIZE in force, in octets: a size update above it is refused. Set by the
1137
+ * constructor and `setSettingsLimit`, and put back to 4096 by `http2.ts`'s `restart`.
1138
+ */
975
1139
  settingsLimit: i32
1140
+ /**
1141
+ * The header-list limit, in octets counted as RFC 9113 §6.5.2 counts them: the field that takes the
1142
+ * block's running total past it, and every one after, is dropped and `decode` answers
1143
+ * `HPACK_LIST_TOO_LARGE`.
1144
+ */
976
1145
  maxHeaderListSize: i32
977
- /** The smallest limit set since the last size update, or -1 when none is owed. */
1146
+ /**
1147
+ * The smallest limit set since the last size update, or -1 when none is owed.
1148
+ * @internal Cleared by `http2.ts` when a connection restarts; not for callers.
1149
+ */
978
1150
  owedUpdate: i32
979
- /** The fatal error a decode met, which every later decode answers; 0 until then. */
1151
+ /**
1152
+ * The fatal error a decode met, which every later decode answers; 0 until then.
1153
+ * @internal Cleared by `http2.ts` when a connection restarts; not for callers.
1154
+ */
980
1155
  failed: i32
1156
+ /**
1157
+ * The names of the last block's fields, in order: the fields before the list passed its limit, and none
1158
+ * after a negative answer. Each array is the decoder's, valid until the next `decode`.
1159
+ */
981
1160
  names: u8[][]
1161
+ /** The values of the last block's fields, by the same position as `names`, and valid as long. */
982
1162
  values: u8[][]
1163
+ /** Whether each field of the last block came never indexed (§6.2.3), by the same position as `names`. */
983
1164
  neverIndexed: boolean[]
984
1165
  /** The storage a block is decoded with, made by the first `decode`, so an idle connection holds none. */
985
- work: HpackWork | null = null
1166
+ private work: HpackWork | null = null
986
1167
  /**
987
1168
  * The octets the decoder has moved through its dynamic table, counted where
988
- * they move: each name or value `appendNameAt` and `appendValueAt` copy out
989
- * of the table, and each octet `table.add` pushes in. The budget
1169
+ * they move: each name or value it copies out of the dynamic table (a static
1170
+ * entry's do not count), and each octet `table.add` pushes in. The budget
990
1171
  * (`HPACK_COPY_FACTOR`) is charged before a literal's copies, from the
991
1172
  * sizes it will copy; this counts what was copied, so that tests can hold
992
1173
  * the two equal. It is public so that tests can read it.
993
1174
  */
994
1175
  tableCopied: i64 = 0
995
1176
 
1177
+ /**
1178
+ * A decoder with an empty table, holding no working storage until the first `decode`.
1179
+ * @param settingsLimit The SETTINGS_HEADER_TABLE_SIZE in force, in octets; the table starts at it, and a
1180
+ * negative one panics.
1181
+ * @param maxHeaderListSize The header-list limit, in octets as RFC 9113 §6.5.2 counts them; a negative one
1182
+ * panics.
1183
+ */
996
1184
  constructor(settingsLimit: i32, maxHeaderListSize: i32) {
997
1185
  if (maxHeaderListSize < 0) {
998
1186
  panic(`HpackDecoder: a header-list limit of ${maxHeaderListSize}`)
@@ -1009,7 +1197,7 @@ export class HpackDecoder {
1009
1197
  }
1010
1198
 
1011
1199
  /** The decoder's working storage, made the first time it is asked for. */
1012
- working(): HpackWork {
1200
+ private working(): HpackWork {
1013
1201
  const work: HpackWork | null = this.work
1014
1202
  if (work !== null) {
1015
1203
  return work
@@ -1024,6 +1212,8 @@ export class HpackDecoder {
1024
1212
  * A limit below the table's current maximum obliges the peer's encoder to
1025
1213
  * begin its next block with an update to at most the smallest limit set
1026
1214
  * since its last one (§4.2); the decoder holds it to that.
1215
+ * @param limit The acknowledged limit, in octets; a negative one panics. The table's own maximum does not
1216
+ * change until the peer's size update.
1027
1217
  */
1028
1218
  setSettingsLimit(limit: i32): void {
1029
1219
  if (limit < 0) {
@@ -1036,7 +1226,7 @@ export class HpackDecoder {
1036
1226
  }
1037
1227
 
1038
1228
  /** Appends the name at static or dynamic index `index`, which must be in range, to `out`. */
1039
- appendNameAt(index: i32, out: u8[]): void {
1229
+ private appendNameAt(index: i32, out: u8[]): void {
1040
1230
  if (index <= HPACK_STATIC_LENGTH) {
1041
1231
  hpackAppendText(out, hpackStaticName(index))
1042
1232
  return
@@ -1047,7 +1237,7 @@ export class HpackDecoder {
1047
1237
  }
1048
1238
 
1049
1239
  /** Appends the value at `index` to `out`, as `appendNameAt` does the name. */
1050
- appendValueAt(index: i32, out: u8[]): void {
1240
+ private appendValueAt(index: i32, out: u8[]): void {
1051
1241
  if (index <= HPACK_STATIC_LENGTH) {
1052
1242
  hpackAppendText(out, hpackStaticValue(index))
1053
1243
  return
@@ -1058,7 +1248,7 @@ export class HpackDecoder {
1058
1248
  }
1059
1249
 
1060
1250
  /** How many octets the name at `index` has. */
1061
- nameLengthAt(index: i32): i32 {
1251
+ private nameLengthAt(index: i32): i32 {
1062
1252
  if (index <= HPACK_STATIC_LENGTH) {
1063
1253
  return toI32(hpackStaticName(index).length)
1064
1254
  }
@@ -1066,7 +1256,7 @@ export class HpackDecoder {
1066
1256
  }
1067
1257
 
1068
1258
  /** What the entry at `index` counts towards a header list, without building it. */
1069
- sizeAt(index: i32): i64 {
1259
+ private sizeAt(index: i32): i64 {
1070
1260
  if (index <= HPACK_STATIC_LENGTH) {
1071
1261
  return (
1072
1262
  toI64(hpackStaticName(index).length) +
@@ -1078,12 +1268,12 @@ export class HpackDecoder {
1078
1268
  }
1079
1269
 
1080
1270
  /** Whether `index` names an entry of either table. */
1081
- hasIndex(index: i32): boolean {
1271
+ private hasIndex(index: i32): boolean {
1082
1272
  return index >= 1 && index <= HPACK_STATIC_LENGTH + this.table.count()
1083
1273
  }
1084
1274
 
1085
1275
  /** Empties the fields and gives each one's array back, emptied, to its class's pool, for the next block. */
1086
- clear(): void {
1276
+ private clear(): void {
1087
1277
  while (toI32(this.names.length) > 0) {
1088
1278
  const work: HpackWork = this.working()
1089
1279
  const last: i32 = toI32(this.names.length) - 1
@@ -1105,6 +1295,13 @@ export class HpackDecoder {
1105
1295
  * `HPACK_OK`, `HPACK_LIST_TOO_LARGE` or a negative `HPACK_ERR_*` code; the
1106
1296
  * module comment lists what each means. After a negative answer the fields
1107
1297
  * are empty and the decoder is spent.
1298
+ * @param block The bytes holding the block; only read during the call, since every field is copied out.
1299
+ * @param off Where the block starts in `block`.
1300
+ * @param len How many bytes the block has. A window outside `block` panics, unless the decoder has failed.
1301
+ * @returns `HPACK_OK`; `HPACK_LIST_TOO_LARGE` when the list passed `maxHeaderListSize`; or one of
1302
+ * `HPACK_ERR_TRUNCATED`, `HPACK_ERR_INTEGER_OVERFLOW`, `HPACK_ERR_INDEX`, `HPACK_ERR_HUFFMAN_PADDING`,
1303
+ * `HPACK_ERR_HUFFMAN_EOS`, `HPACK_ERR_TABLE_SIZE`, `HPACK_ERR_SIZE_UPDATE_POSITION`,
1304
+ * `HPACK_ERR_SIZE_UPDATE_MISSING` or `HPACK_ERR_COPY_BUDGET`, which every later call answers again.
1108
1305
  */
1109
1306
  decode(block: u8[], off: i32, len: i32): i32 {
1110
1307
  this.clear()
@@ -1141,7 +1338,7 @@ export class HpackDecoder {
1141
1338
  * copied into the pools, which the limit bounds; nothing is allocated once
1142
1339
  * those have grown to the largest block and list seen.
1143
1340
  */
1144
- decodeFields(c: HpackCursor): i32 {
1341
+ private decodeFields(c: HpackCursor): i32 {
1145
1342
  let listSize: i64 = 0
1146
1343
  let tooLarge: boolean = false
1147
1344
  let sawField: boolean = false
@@ -1270,7 +1467,7 @@ export class HpackDecoder {
1270
1467
  }
1271
1468
 
1272
1469
  /** A pooled copy of `bytes`, for the caller. */
1273
- copyOf(bytes: u8[]): u8[] {
1470
+ private copyOf(bytes: u8[]): u8[] {
1274
1471
  const out: u8[] = this.working().take(toI32(bytes.length))
1275
1472
  for (const b of bytes) {
1276
1473
  out.push(b)
@@ -1287,11 +1484,21 @@ export class HpackDecoder {
1287
1484
  * HTTP/2's 4096 until SETTINGS say otherwise — so no update is sent for it.
1288
1485
  */
1289
1486
  export class HpackEncoder {
1487
+ /** The dynamic table, which `encodeField` adds to and `setMaxTableSize` resizes. */
1290
1488
  table: HpackTable
1489
+ /** @internal Read by `http2.ts` to size a field's strings with `hpackHuffmanLength`; not for callers. */
1291
1490
  huffman: HpackHuffman
1292
- /** The smallest size set since the last block, or -1 when no update is owed. */
1491
+ /**
1492
+ * The smallest size set since the last block, or -1 when no update is owed.
1493
+ * @internal Cleared by `http2.ts` when a connection restarts; not for callers.
1494
+ */
1293
1495
  owedMinimum: i32
1294
1496
 
1497
+ /**
1498
+ * An encoder with an empty table, owing no size update.
1499
+ * @param maxSize The table's maximum size, in octets, which both ends already agree on; a negative one
1500
+ * panics.
1501
+ */
1295
1502
  constructor(maxSize: i32) {
1296
1503
  this.table = new HpackTable(maxSize)
1297
1504
  this.huffman = new HpackHuffman()
@@ -1304,6 +1511,7 @@ export class HpackEncoder {
1304
1511
  * the caller's to keep. Call it between blocks: the next `encodeField`
1305
1512
  * begins with the update, or with two when the size went down and then up
1306
1513
  * again, the smallest first (§4.2).
1514
+ * @param maxSize The new maximum, in octets; a negative one panics.
1307
1515
  */
1308
1516
  setMaxTableSize(maxSize: i32): void {
1309
1517
  if (this.owedMinimum < 0 || maxSize < this.owedMinimum) {
@@ -1317,7 +1525,7 @@ export class HpackEncoder {
1317
1525
  * table has one. The static table is searched first, then the dynamic one
1318
1526
  * from the newest entry.
1319
1527
  */
1320
- findField(name: u8[], value: u8[]): i32 {
1528
+ private findField(name: u8[], value: u8[]): i32 {
1321
1529
  for (let i: i32 = 1; i <= HPACK_STATIC_LENGTH; i += 1) {
1322
1530
  if (hpackSameAsText(name, hpackStaticName(i)) && hpackSameAsText(value, hpackStaticValue(i))) {
1323
1531
  return i
@@ -1337,7 +1545,7 @@ export class HpackEncoder {
1337
1545
  }
1338
1546
 
1339
1547
  /** The lowest index whose entry has `name`, or 0 when neither table has one. */
1340
- findName(name: u8[]): i32 {
1548
+ private findName(name: u8[]): i32 {
1341
1549
  for (let i: i32 = 1; i <= HPACK_STATIC_LENGTH; i += 1) {
1342
1550
  if (hpackSameAsText(name, hpackStaticName(i))) {
1343
1551
  return i
@@ -1357,6 +1565,11 @@ export class HpackEncoder {
1357
1565
  * and `indexing` is not `HPACK_INDEX_NEVER`, else as a literal of the kind
1358
1566
  * `indexing` names, its name by index when a table has it and its strings
1359
1567
  * Huffman-coded when `huffman` is true. Any other `indexing` panics.
1568
+ * @param out The block being built; the field, after any size update owed, is appended to it.
1569
+ * @param name The field's name; read, and copied into the table under incremental indexing, not kept.
1570
+ * @param value The field's value, treated as `name` is.
1571
+ * @param indexing `HPACK_INDEX_INCREMENTAL`, `HPACK_INDEX_WITHOUT` or `HPACK_INDEX_NEVER`.
1572
+ * @param huffman Whether a literal's strings are Huffman-coded; a field sent by index ignores it.
1360
1573
  */
1361
1574
  encodeField(out: u8[], name: u8[], value: u8[], indexing: i32, huffman: boolean): void {
1362
1575
  if (indexing < HPACK_INDEX_INCREMENTAL || indexing > HPACK_INDEX_NEVER) {