@amritk/nish-x86_64-linux 0.27.2 → 0.28.0

package/std/net/http-compress.ts

@@ -23,6 +23,30 @@
  * its `minLength`, longer than its `maxLength`, or that gzip would not make
  * smaller, answering -1 so the program sends the bytes as they are.
  *
+ * **Compression that pays for itself.** A body is sent compressed only when
+ * it saves at least `minSaving` bytes and `minSavingPercent` percent of the
+ * body; otherwise the compressed bytes are dropped and the body goes as it
+ * is. With `segmentMode` set, `respondEncoded` also sends it compressed only
+ * when the whole response, head included, takes fewer TCP segments of `mss`
+ * bytes (the connection's `mss` if set, else the compressor's, 1448 by
+ * default): a 1300-byte body that gzips to 700 still fits in one segment
+ * either way. After each call `decision` says why (`HTTP_COMPRESS_SENT`,
+ * `_NOT_ACCEPTED`, `_TOO_SMALL`, `_TOO_LARGE`, `_TOO_LITTLE_SAVED`,
+ * `_NO_FEWER_SEGMENTS`), for a program to count.
+ *
+ * **Two encoders.** Bodies up to `fixedLimit` (16 KB) go through
+ * `GzipFixedCompressor`: one fixed-Huffman block, a 16 KB window, no state
+ * between calls, two to four times faster than `DEFLATE_FAST` on 0.5 to
+ * 16 KB of JSON for output about 1.35 times larger. Larger bodies go through
+ * the `GzipCompressor` at the level given; `encoder` forces either one.
+ *
+ * **`Vary: Accept-Encoding`** (with `vary`, on by default) goes on every
+ * response whose coding depended on the request: one sent compressed, and
+ * one sent as it is because the request did not accept gzip. A body that is
+ * too small, too large or did not pay is sent the same to every client, so
+ * it carries no `Vary`. A request that refuses identity (`identity;q=0`)
+ * and accepts gzip is sent gzip whatever the policy (`compressAnyway`).
+ *
  * **Negotiation** (`httpAcceptEncoding`) follows §12.5.3: each listed coding
  * with its q-value, `x-gzip` as `gzip`, `*` for every coding not listed, and
  * `identity` acceptable unless it is given q=0, directly or through `*`. Of
@@ -35,15 +59,16 @@
  * and identity is refused: a server may answer 406 or send identity anyway.
  * A malformed element is skipped. The parser allocates nothing.
  *
- * **Compressing allocates nothing**: `HttpCompressor` holds a
- * `GzipCompressor`, an output buffer of `compressBound(maxLength)` bytes and
+ * **Compressing allocates nothing** and caches nothing between responses:
+ * `HttpCompressor` holds a `GzipCompressor`, a `GzipFixedCompressor`, an
+ * output buffer of `compressBound(maxLength)` bytes and
  * the field arrays `addFields` fills, all built once.
  * `HTTP_CODING_DEFLATE` (zlib framing) is negotiated but not produced: a
  * client that accepts only `deflate` is sent identity, which every client
  * reads.
  */
 import { DEFLATE_FAST, compressBound } from "nish/compress/deflate"
-import { GzipCompressor } from "nish/compress/gzip"
+import { GzipCompressor, GzipFixedCompressor } from "nish/compress/gzip"
 
 /** No content coding: the body as it is. */
 export const HTTP_CODING_IDENTITY: i32 = 0
@@ -61,6 +86,62 @@ export const HTTP_CODING_NONE: i32 = -1
 export const HTTP_OFFER_GZIP: i32 = 1
 export const HTTP_OFFER_DEFLATE: i32 = 2
 
+/**
+ * What `HttpCompressor.compress` (and `respondEncoded`'s segment check) last
+ * decided, in `HttpCompressor.decision`, for a program to count: the body
+ * went out compressed; the client did not take gzip; it was shorter than
+ * `minLength`; longer than `maxLength`; gzip did not save `minSaving` bytes
+ * and `minSavingPercent` percent; or the compressed response would not have
+ * taken fewer TCP segments (`segmentMode`).
+ */
+export const HTTP_COMPRESS_SENT: i32 = 0
+export const HTTP_COMPRESS_NOT_ACCEPTED: i32 = 1
+export const HTTP_COMPRESS_TOO_SMALL: i32 = 2
+export const HTTP_COMPRESS_TOO_LARGE: i32 = 3
+export const HTTP_COMPRESS_TOO_LITTLE_SAVED: i32 = 4
+export const HTTP_COMPRESS_NO_FEWER_SEGMENTS: i32 = 5
+
+/**
+ * `HttpCompressor.encoder`: by the body's length (the fixed-Huffman encoder up
+ * to `fixedLimit` bytes, the constructor's level above), the fixed-Huffman
+ * encoder always, or the constructor's level always.
+ */
+export const HTTP_ENCODER_AUTO: i32 = 0
+export const HTTP_ENCODER_FIXED: i32 = 1
+export const HTTP_ENCODER_LEVEL: i32 = 2
+
+/**
+ * The maximum segment size `segmentMode` counts with unless told the
+ * connection's: a 1500-byte Ethernet MTU less 20 bytes of IPv4 header, 20 of
+ * TCP header and 12 of the timestamp option.
+ */
+export const HTTP_DEFAULT_MSS: i32 = 1448
+
+/** The bytes `content-encoding: gzip` adds to an HTTP/1.1 head: name, value, ": " and CRLF. */
+export const HTTP1_GZIP_FIELD_BYTES: i32 = 24
+
+/** The number of TCP segments `bytes` bytes take at `mss` bytes a segment. */
+export const httpSegments = (bytes: i32, mss: i32): i32 => {
+  if (mss <= 0) {
+    panic("httpSegments: a segment size of zero or less")
+  }
+  if (bytes <= 0) {
+    return 0
+  }
+  return (bytes - 1) / mss + 1
+}
+
+/** The digits of `n` in decimal, `n` 0 or more. */
+const httpDecimalDigits = (n: i32): i32 => {
+  let digits: i32 = 1
+  let rest: i32 = n
+  while (rest >= 10) {
+    rest = rest / 10
+    digits += 1
+  }
+  return digits
+}
+
 /** A q-value of 1, in thousandths. */
 const HTTP_Q_ONE: i32 = 1000
 
@@ -255,6 +336,15 @@ export const httpAcceptEncoding = (buf: u8[], start: i32, end: i32, offered: i32
   return HTTP_CODING_NONE
 }
 
+/**
+ * Whether the `Accept-Encoding` value in `buf[start .. end)` refuses the
+ * body as it is: `identity;q=0`, or `*;q=0` with no `identity` listed. A
+ * server should then send a coding the client takes even where it would not
+ * bother (`HttpCompressor.compressAnyway`).
+ */
+export const httpIdentityRefused = (buf: u8[], start: i32, end: i32): boolean =>
+  httpAcceptEncoding(buf, start, end, 0) === HTTP_CODING_NONE
+
 /** The bytes of an ASCII string. */
 const httpCompressBytes = (text: string): u8[] => {
   const out: u8[] = new Array<u8>(toI32(text.length))
@@ -270,6 +360,8 @@ const httpCompressBytes = (text: string): u8[] => {
  */
 export class HttpCompressor {
   readonly gzip: GzipCompressor
+  /** The small-body encoder: one fixed-Huffman block, nothing kept between calls. */
+  readonly fixed: GzipFixedCompressor
   /** Where `compress` writes; valid until the next call. */
   readonly output: u8[]
   /** The fields `addFields` built: the program's, then `Content-Encoding` and `Vary`. */
@@ -288,6 +380,27 @@ export class HttpCompressor {
    * default; turn it off when the program sets its own `Vary`.
    */
   vary: boolean
+  /**
+   * The least a compressed body must save to be sent: `minSaving` bytes and
+   * `minSavingPercent` percent of the body, whichever is more. 1 and 0 by
+   * default (any saving at all); a value below those counts as them.
+   */
+  minSaving: i32
+  minSavingPercent: i32
+  /**
+   * Whether `respondEncoded` also sends the compressed response only when,
+   * head included, it takes fewer TCP segments of `mss` bytes than the body
+   * as it is; off by default. `mss` is `HTTP_DEFAULT_MSS` unless the program
+   * sets it, or a connection's own `mss` overrides it.
+   */
+  segmentMode: boolean
+  mss: i32
+  /** `HTTP_ENCODER_AUTO` (the default), `HTTP_ENCODER_FIXED` or `HTTP_ENCODER_LEVEL`. */
+  encoder: i32
+  /** The longest body `HTTP_ENCODER_AUTO` gives the fixed-Huffman encoder: 16384 by default. */
+  fixedLimit: i32
+  /** The last decision, an `HTTP_COMPRESS_*`; `HTTP_COMPRESS_NOT_ACCEPTED` before any. */
+  decision: i32
 
   /**
    * A compressor at `level` (`DEFLATE_FAST` suits a server) for bodies of
@@ -299,6 +412,7 @@ export class HttpCompressor {
       panic("HttpCompressor: the lengths are out of order")
     }
     this.gzip = new GzipCompressor(level)
+    this.fixed = new GzipFixedCompressor()
     this.output = new Array<u8>(compressBound(maxLength))
     this.names = []
     this.values = []
@@ -309,28 +423,151 @@ export class HttpCompressor {
     this.minLength = minLength
     this.maxLength = maxLength
     this.vary = true
+    this.minSaving = 1
+    this.minSavingPercent = 0
+    this.segmentMode = false
+    this.mss = HTTP_DEFAULT_MSS
+    this.encoder = HTTP_ENCODER_AUTO
+    this.fixedLimit = 16384
+    this.decision = HTTP_COMPRESS_NOT_ACCEPTED
   }
 
   /**
-   * Compresses `body[off .. off + len)` into `output` when `coding` is
-   * `HTTP_CODING_GZIP`, the length is in `[minLength, maxLength]` and gzip
-   * makes it smaller; answers the compressed length, or -1 to send the body
-   * as it is. A window outside `body` panics.
+   * Compresses `body[off .. off + len)` into `output` when the length is in
+   * `[minLength, maxLength]`, `coding` is `HTTP_CODING_GZIP` and gzip saves
+   * what `minSaving` and `minSavingPercent` ask; answers the compressed
+   * length, or -1 to send the body as it is, and sets `decision` either way.
+   * `encoder` picks the encoder; the fixed-Huffman one stops as soon as its
+   * output passes what would be kept. A window outside `body` panics.
    */
   compress(coding: i32, body: u8[], off: i32, len: i32): i32 {
     if (off < 0 || len < 0 || off > toI32(body.length) - len) {
       panic("HttpCompressor.compress: the window lies outside its body")
     }
-    if (coding !== HTTP_CODING_GZIP || len < this.minLength || len > this.maxLength) {
+    if (len < this.minLength) {
+      this.decision = HTTP_COMPRESS_TOO_SMALL
+      return -1
+    }
+    if (len > this.maxLength) {
+      this.decision = HTTP_COMPRESS_TOO_LARGE
+      return -1
+    }
+    if (coding !== HTTP_CODING_GZIP) {
+      this.decision = HTTP_COMPRESS_NOT_ACCEPTED
+      return -1
+    }
+    // The longest output kept; `output` holds `compressBound(maxLength)`, more.
+    const keep: i32 = len - this.leastSaving(len)
+    let n: i32 = -1
+    if (keep > 0) {
+      const fixed: boolean =
+        this.encoder === HTTP_ENCODER_FIXED || (this.encoder !== HTTP_ENCODER_LEVEL && len <= this.fixedLimit)
+      n = fixed
+        ? this.fixed.compress(body, off, len, this.output, toI32(0), keep)
+        : this.gzip.compress(body, off, len, this.output, toI32(0))
+    }
+    if (n < 0 || n > keep) {
+      this.decision = HTTP_COMPRESS_TOO_LITTLE_SAVED
+      return -1
+    }
+    this.decision = HTTP_COMPRESS_SENT
+    return n
+  }
+
+  /**
+   * `compress` for a client that refuses identity (`httpIdentityRefused`):
+   * gzip whatever the body's length, the saving or the
+   * segments, so long as it is no longer than `maxLength`. Answers the
+   * compressed length, or -1 when `coding` is not gzip or the body is too
+   * long (sent as it is, which RFC 9110 §12.5.3 allows).
+   */
+  compressAnyway(coding: i32, body: u8[], off: i32, len: i32): i32 {
+    if (off < 0 || len < 0 || off > toI32(body.length) - len) {
+      panic("HttpCompressor.compressAnyway: the window lies outside its body")
+    }
+    if (len > this.maxLength) {
+      this.decision = HTTP_COMPRESS_TOO_LARGE
       return -1
     }
-    const n: i32 = this.gzip.compress(body, off, len, this.output, toI32(0))
-    if (n < 0 || n >= len) {
+    if (coding !== HTTP_CODING_GZIP) {
+      this.decision = HTTP_COMPRESS_NOT_ACCEPTED
       return -1
     }
+    let n: i32 = -1
+    if (
+      this.encoder === HTTP_ENCODER_FIXED ||
+      (this.encoder !== HTTP_ENCODER_LEVEL && len <= this.fixedLimit)
+    ) {
+      n = this.fixed.compress(body, off, len, this.output, toI32(0), toI32(this.output.length))
+    }
+    if (n < 0) {
+      n = this.gzip.compress(body, off, len, this.output, toI32(0))
+    }
+    this.decision = HTTP_COMPRESS_SENT
     return n
   }
 
+  /** The bytes a compressed `len`-byte body must save: `minSaving` and `minSavingPercent`, at least 1. */
+  leastSaving(len: i32): i32 {
+    let least: i32 = this.minSaving > 1 ? this.minSaving : 1
+    let pct: i32 = this.minSavingPercent
+    if (pct < 0) {
+      pct = 0
+    } else if (pct > 100) {
+      pct = 100
+    }
+    const share: i32 = toI32((toI64(len) * toI64(pct) + toI64(99)) / toI64(100))
+    if (share > least) {
+      least = share
+    }
+    return least
+  }
+
+  /**
+   * `segmentMode`'s rule, for a response of `identityBytes` bytes sent as it
+   * is or `encodedBytes` compressed, heads included, at `mss` bytes a segment
+   * (`this.mss` when 0 or less): whether the compressed one takes fewer
+   * segments. When it does not, `decision` becomes
+   * `HTTP_COMPRESS_NO_FEWER_SEGMENTS`. `respondEncoded` calls it; a program
+   * driving HTTP/2 or HTTP/3 by hand may with its own head sizes.
+   */
+  fewerSegments(identityBytes: i32, encodedBytes: i32, mss: i32): boolean {
+    let size: i32 = mss
+    if (size <= 0) {
+      size = this.mss > 0 ? this.mss : HTTP_DEFAULT_MSS
+    }
+    if (httpSegments(encodedBytes, size) < httpSegments(identityBytes, size)) {
+      return true
+    }
+    this.decision = HTTP_COMPRESS_NO_FEWER_SEGMENTS
+    return false
+  }
+
+  /**
+   * The bytes of the HTTP/1.1 head a `length`-byte body sent as it is would
+   * get, from `encodedHead`, that of the same response sent compressed as
+   * `encodedLength` bytes with the fields `addFields` built: less
+   * `Content-Encoding: gzip`, less `Vary` (a body the segment count kept as
+   * it is would go out so to any client), and the other `Content-Length`.
+   */
+  http1IdentityHead(encodedHead: i32, encodedLength: i32, length: i32): i32 {
+    let head: i32 = encodedHead - HTTP1_GZIP_FIELD_BYTES
+    if (this.vary) {
+      head -= toI32(this.varyName.length) + toI32(this.acceptEncodingValue.length) + 4
+    }
+    return head - httpDecimalDigits(encodedLength) + httpDecimalDigits(length)
+  }
+
+  /**
+   * Whether the last decision depended on the request's `Accept-Encoding`, so
+   * the response needs `Vary: Accept-Encoding`: a body sent compressed, or
+   * one sent as it is because the client did not take gzip. A body the
+   * lengths or the saving kept as it is would go out the same to any client.
+   */
+  varies(): boolean {
+    return this.decision === HTTP_COMPRESS_SENT || this.decision === HTTP_COMPRESS_NOT_ACCEPTED
+  }
+
   /**
    * Sets `names` / `values` to the program's fields followed by
    * `Content-Encoding: gzip` and, when `vary`, `Vary: Accept-Encoding`. The
@@ -354,21 +591,27 @@ export class HttpCompressor {
     }
     this.names.push(this.contentEncodingName)
     this.values.push(this.gzipValue)
-    this.addVary()
+    if (this.vary) {
+      this.names.push(this.varyName)
+      this.values.push(this.acceptEncodingValue)
+    }
   }
 
-  /** Appends `Vary: Accept-Encoding` to the arrays `addFields` built when `vary` is set. */
+  /**
+   * Appends `Vary: Accept-Encoding` to the arrays `identityFields` built when
+   * `vary` is set and the last decision `varies`.
+   */
   addVary(): void {
-    if (this.vary) {
+    if (this.vary && this.varies()) {
       this.names.push(this.varyName)
       this.values.push(this.acceptEncodingValue)
     }
   }
 
   /**
-   * Sets `names` / `values` to the program's fields and, when `vary`,
-   * `Vary: Accept-Encoding`: the fields of a body sent as it is from a
-   * resource that is sometimes compressed.
+   * Sets `names` / `values` to the program's fields and, when `vary` and the
+   * last decision `varies`, `Vary: Accept-Encoding`: the fields of a body
+   * sent as it is from a resource that is sometimes compressed.
    */
   identityFields(names: u8[][], values: u8[][]): void {
     while (this.names.length > 0) {

package/std/net/http1-client.ts

@@ -10,7 +10,10 @@
  * with nothing allocated. A chunked body is written with `http1Chunk` and
  * `http1LastChunk` from `nish/net/http1`. The writer refuses anything that
  * would let a caller's string end a line early or frame the body itself — the
- * request-splitting and request-smuggling shapes.
+ * request-splitting and request-smuggling shapes. `http1UpgradeRequestHead`
+ * is the one way to ask the server to switch protocols: it writes `Upgrade`
+ * and `Connection: Upgrade` itself, and every other writer refuses a
+ * `Connection` that lists `upgrade`.
  *
  * **The parser** is a push-pull machine, like the server's. A caller tells it
  * what it asked (`expect`), `feed`s whatever slice the socket gave it, cut
@@ -34,10 +37,11 @@
  * final one follows), `HTTP1_HEAD` (the final response's status line and
  * header section are in), `HTTP1_BODY` (some body bytes, de-chunked),
  * `HTTP1_END` (the response is complete; with `keepAlive()` the next one
- * follows), `HTTP1_UPGRADE` (a CONNECT was answered with 2xx and the
- * connection is a tunnel now: `tunnelBytes()` answers what was fed past the
- * head), `HTTP1_CLOSED` (the connection is done: the server closed it
- * between responses, or the last response was not kept alive) and
+ * follows), `HTTP1_UPGRADE` (a CONNECT was answered with 2xx, or a request
+ * that `expectUpgrade` named was answered with 101, and the connection is a
+ * tunnel now: `tunnelBytes()` answers what was fed past the head),
+ * `HTTP1_CLOSED` (the connection is done: the server closed it between
+ * responses, or the last response was not kept alive) and
  * `HTTP1_ERROR`. The last three repeat on every later call. Only complete
  * lines are acted on, body bytes are counted, never guessed, and every
  * refusal is decided by the same byte wherever the input was cut, so the
@@ -55,7 +59,7 @@
  * **What it refuses**, each with its own code in `error`: a malformed status
  * line, an HTTP major version other than 1, a bare LF, a malformed field line
  * (an obs-fold, whitespace before the colon, a control byte in a value), a 101
- * (this client never asks to switch protocols), `Transfer-Encoding` together
+ * to a request that did not ask to switch protocols, `Transfer-Encoding` together
  * with `Content-Length`, a transfer coding other than one `chunked` or one in
  * an HTTP/1.0 response, a `Content-Length` that is not a decimal or whose
  * repeats disagree, a malformed chunk, a status line, header section, field
@@ -112,7 +116,7 @@ export const HTTP1_E_VERSION: i32 = 2
 export const HTTP1_E_BARE_LF: i32 = 3
 /** `error`: a malformed field line: an obs-fold, a bad name, whitespace before the colon, a control byte. */
 export const HTTP1_E_FIELD: i32 = 4
-/** `error`: a 101, which this client never asks for. */
+/** `error`: a 101 to a request that did not ask to switch protocols (see `expectUpgrade`). */
 export const HTTP1_E_SWITCH: i32 = 5
 /** `error`: both `Transfer-Encoding` and `Content-Length` (RFC 9112 §6.1). */
 export const HTTP1_E_FRAMING: i32 = 6
@@ -290,11 +294,16 @@ const http1ClientRequestNeed = (
   target: string,
   names: string[],
   values: string[],
-  bodyLength: i64
+  bodyLength: i64,
+  upgrade: string
 ): i64 => {
   if (!http1IsToken(method) || !http1ClientTargetOk(method, target)) {
     return toI64(-1)
   }
+  const upgrading: boolean = toI32(upgrade.length) > 0
+  if (upgrading && (!http1IsToken(upgrade) || bodyLength !== toI64(-2))) {
+    return toI64(-1)
+  }
   if (bodyLength < toI64(-2)) {
     return toI64(-1)
   }
@@ -319,7 +328,13 @@ const http1ClientRequestNeed = (
     ) {
       return toI64(-1)
     }
-    if (http1SameWord(name, 0, nameLength, "connection") && http1ClientListHas(value, "upgrade")) {
+    if (
+      http1SameWord(name, 0, nameLength, "connection") &&
+      (upgrading || http1ClientListHas(value, "upgrade"))
+    ) {
+      return toI64(-1)
+    }
+    if (upgrading && http1SameWord(name, 0, nameLength, "upgrade")) {
       return toI64(-1)
     }
     if (http1SameWord(name, 0, nameLength, "host")) {
@@ -335,6 +350,10 @@ const http1ClientRequestNeed = (
   } else if (bodyLength === toI64(-1)) {
     need = need + toI64(28)
   }
+  if (upgrading) {
+    // "Upgrade: " value CRLF "Connection: Upgrade" CRLF
+    need = need + toI64(upgrade.length) + toI64(32)
+  }
   return need
 }
 
@@ -364,9 +383,9 @@ const http1ClientPutField = (out: u8[], at: i32, names: string[], values: string
  * early and let the rest be read as a field or a second request); `names` and
  * `values` of different lengths; not exactly one `Host`; a `Content-Length` or
  * `Transfer-Encoding` among the caller's fields, since the framing is decided
- * here; a `Connection` that lists `upgrade`, which the parser refuses the
- * answer to; and a `bodyLength` below -2. Answers `HTTP1_NO_ROOM` when it is
- * well formed but does not fit. Either way `out` is untouched.
+ * here; a `Connection` that lists `upgrade`, which only
+ * `http1UpgradeRequestHead` may write; and a `bodyLength` below -2. Answers
+ * `HTTP1_NO_ROOM` when it is well formed but does not fit. Either way `out` is untouched.
  */
 export const http1WriteRequestHead = (
   out: u8[],
@@ -377,14 +396,14 @@ export const http1WriteRequestHead = (
   values: string[],
   bodyLength: i64
 ): i32 => {
-  const need: i64 = http1ClientRequestNeed(method, target, names, values, bodyLength)
+  const need: i64 = http1ClientRequestNeed(method, target, names, values, bodyLength, "")
   if (need < toI64(0)) {
     return HTTP1_REFUSED
   }
   if (at < 0 || need > toI64(toI32(out.length) - at)) {
     return HTTP1_NO_ROOM
   }
-  return http1ClientPutHead(out, at, method, target, names, values, bodyLength)
+  return http1ClientPutHead(out, at, method, target, names, values, bodyLength, "")
 }
 
 /** Writes a head `http1ClientRequestNeed` accepted into room it counted; answers the end. */
@@ -395,7 +414,8 @@ const http1ClientPutHead = (
   target: string,
   names: string[],
   values: string[],
-  bodyLength: i64
+  bodyLength: i64,
+  upgrade: string
 ): i32 => {
   let end: i32 = http1PutText(out, at, method)
   end = http1PutText(out, end, " ")
@@ -419,6 +439,11 @@ const http1ClientPutHead = (
   } else if (bodyLength === toI64(-1)) {
     end = http1PutText(out, end, "Transfer-Encoding: chunked\r\n")
   }
+  if (toI32(upgrade.length) > 0) {
+    end = http1PutText(out, end, "Upgrade: ")
+    end = http1PutText(out, end, upgrade)
+    end = http1PutText(out, end, "\r\nConnection: Upgrade\r\n")
+  }
   return http1PutText(out, end, "\r\n")
 }
 
@@ -432,13 +457,46 @@ export const http1RequestHead = (
   names: string[],
   values: string[],
   bodyLength: i64
+): u8[] | null => http1ClientHeadArray(method, target, names, values, bodyLength, "")
+
+/**
+ * A request that asks the server to switch the connection to `upgrade` (RFC
+ * 9110 §7.8), such as a WebSocket opening handshake: `http1RequestHead`'s head
+ * with no body, and `Upgrade: <upgrade>` and `Connection: Upgrade` written
+ * after the caller's fields. Answers `null` for everything `http1RequestHead`
+ * refuses, an `upgrade` that is not one token, and an `Upgrade` or
+ * `Connection` among the caller's fields, which would contradict the two this
+ * writes. A response to it is read after `expect(false, false)` and then
+ * `expectUpgrade()`, so that its 101 answers `HTTP1_UPGRADE`.
+ */
+export const http1UpgradeRequestHead = (
+  method: string,
+  target: string,
+  names: string[],
+  values: string[],
+  upgrade: string
 ): u8[] | null => {
-  const need: i64 = http1ClientRequestNeed(method, target, names, values, bodyLength)
+  if (toI32(upgrade.length) === 0) {
+    return null
+  }
+  return http1ClientHeadArray(method, target, names, values, toI64(-2), upgrade)
+}
+
+/** The head `http1ClientRequestNeed` accepts in an array of its own, or `null`. */
+const http1ClientHeadArray = (
+  method: string,
+  target: string,
+  names: string[],
+  values: string[],
+  bodyLength: i64,
+  upgrade: string
+): u8[] | null => {
+  const need: i64 = http1ClientRequestNeed(method, target, names, values, bodyLength, upgrade)
   if (need < toI64(0) || need > toI64(1073741824)) {
     return null
   }
   const out: u8[] = new Array<u8>(toI32(need))
-  http1ClientPutHead(out, 0, method, target, names, values, bodyLength)
+  http1ClientPutHead(out, 0, method, target, names, values, bodyLength, upgrade)
   return out
 }
 
@@ -533,6 +591,8 @@ export class Http1ResponseParser {
   /** What `expect` said of the request this response answers. */
   wasHead: boolean = false
   wasConnect: boolean = false
+  /** Whether `expectUpgrade` said the request asked to switch protocols. */
+  wasUpgrade: boolean = false
   /** Whether `finish()` said the server closed the connection. */
   closed: boolean = false
 
@@ -567,6 +627,24 @@ export class Http1ResponseParser {
     if (this.state === HTTP1_CLIENT_S_STATUS_LINE && this.informational === 0) {
       this.wasHead = methodWasHead
       this.wasConnect = wasConnect
+      this.wasUpgrade = false
+    }
+  }
+
+  /**
+   * Says the request this response answers asked to switch protocols (it was
+   * written by `http1UpgradeRequestHead`), so a 101 is that switch: the parser
+   * answers `HTTP1_HEAD` with its status and fields readable, `HTTP1_END`, and
+   * then `HTTP1_UPGRADE`, and `tunnelBytes()` answers what was fed past the
+   * head. Any other status is read as it would be without it. It is said after
+   * `expect`, which clears it, and like `expect` it takes effect only while the
+   * parser waits for a response's first status line. Without it a 101 is
+   * refused with `HTTP1_E_SWITCH`: a server may not switch a connection whose
+   * client never asked.
+   */
+  expectUpgrade(): void {
+    if (this.state === HTTP1_CLIENT_S_STATUS_LINE && this.informational === 0) {
+      this.wasUpgrade = true
     }
   }
 
@@ -949,7 +1027,13 @@ const http1ClientConnectionHas = (p: Http1ResponseParser, word: string): boolean
 const http1ClientEndOfHead = (p: Http1ResponseParser): i32 => {
   const status: i32 = p.status
   if (status === 101) {
-    return http1ClientFail(p, HTTP1_E_SWITCH, "a 101 Switching Protocols this client never asks for")
+    if (!p.wasUpgrade) {
+      return http1ClientFail(p, HTTP1_E_SWITCH, "a 101 Switching Protocols the request did not ask for")
+    }
+    // RFC 9110 §15.2.2: the connection switches right after the 101's empty
+    // line, so what follows the head is the new protocol's.
+    p.state = HTTP1_CLIENT_S_MESSAGE_END
+    return HTTP1_HEAD
   }
   if (status < 200) {
     if (p.informational >= HTTP1_MAX_INFORMATIONAL) {
@@ -1203,7 +1287,7 @@ const http1ClientNext = (p: Http1ResponseParser): i32 => {
         break
       }
       case HTTP1_CLIENT_S_MESSAGE_END: {
-        if (p.wasConnect && p.status < 300) {
+        if ((p.wasConnect && p.status < 300) || (p.wasUpgrade && p.status === 101)) {
           p.state = HTTP1_CLIENT_S_TUNNEL
         } else if (!p.persistent) {
           p.state = HTTP1_CLIENT_S_CLOSED
@@ -1213,6 +1297,7 @@ const http1ClientNext = (p: Http1ResponseParser): i32 => {
           p.informational = 0
           p.wasHead = false
           p.wasConnect = false
+          p.wasUpgrade = false
         }
         return HTTP1_END
       }