weft
ir 2.6.0 · warp 1.8.0
generatedwalked out of the package's public entry

@weftjs/warp

The frame protocol: negotiation, frames, and the codec. Also versioned, and for the same reason.

51exports
51with a doc comment on the declaration

Read out of packages/warp/src/index.ts, the package’s public entry, so this page is the surface itself rather than a description of it.

bool function

export function bool(f: AnyFrame, key: string): boolean | undefined { … }

A header read as a boolean. Absent and malformed are both undefined: a header is text.

Specified inspec/warp/warp-1.md

packages/warp/src/frames.ts

codeForKind function

export function codeForKind(kind: FrameKind): number { … }

The binary code for a kind. Retired codes are never reused — see spec/VERSIONING.md.

packages/warp/src/frames.ts

concatBytes function

export function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array { … }

Two buffers as one. A decoder holds a partial frame across chunks and this is how it grows.

Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION

packages/warp/src/codec.ts

createBinaryDecoder function

export function createBinaryDecoder(options: DecoderOptions = {}): Decoder { … }

The length-prefixed binary decoder. What a socket uses.

Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION

packages/warp/src/codec.ts

createTextDecoder function

export function createTextDecoder(options: DecoderOptions = {}): Decoder { … }

The newline-delimited text decoder. What an event stream uses, where a frame is a line.

Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION

packages/warp/src/codec.ts

decodeHeader function

export function decodeHeader(text: string): Header { … }

A header line as names and values, with numbers and booleans parsed back.

Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION

packages/warp/src/codec.ts

decodeTextFrame function

export function decodeTextFrame(line: string): AnyFrame { … }

One line as a frame. An unknown kind comes back as an unknown frame rather than an error.

Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION

packages/warp/src/codec.ts

directionOf function

export function directionOf(kind: FrameKind): Direction { … }

Which way this kind travels.

packages/warp/src/frames.ts

directionOfCode function

export function directionOfCode(code: number): Direction { … }

Which way a code travels, without needing to know the kind it names.

packages/warp/src/frames.ts

encodeBinaryFrame function

export function encodeBinaryFrame(f: Frame): Uint8Array { … }

One frame as length-prefixed bytes: code, header length, body length, then the two.

Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION

packages/warp/src/codec.ts

encodeHeader function

export function encodeHeader(header: Header): string { … }

A header as one line. Keys are sorted, so the same header is always the same bytes.

Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION

packages/warp/src/codec.ts

encodeStream function

export function encodeStream(frames: Frame[], mode: 'binary' | 'text' = 'binary'): Uint8Array { … }

A whole stream, preamble included. What a test and a server both send.

Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION

packages/warp/src/codec.ts

encodeTextFrame function

export function encodeTextFrame(f: Frame): string { … }

Text framing: one frame per line, for dev tooling and traces. Bodies are encoded into the line, so text framing is not byte-transparent and production uses binary.

Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION

packages/warp/src/codec.ts

frame function

export function frame(kind: FrameKind, header: Header = {}, body?: Uint8Array, bodyIsText = false): Frame { … }

A frame, with the direction check the kind implies already done.

Specified inspec/kernel/budgets.md

packages/warp/src/frames.ts

isUnknown function

export function isUnknown(value: AnyFrame): value is UnknownFrame { … }

Whether this frame is one this version does not define.

An unknown frame is skipped intact rather than dropped, which is what makes a minor additive: an older reader passes a newer frame along instead of ending the stream over it.

packages/warp/src/frames.ts

kindForCode function

export function kindForCode(code: number): FrameKind | undefined { … }

The kind a code names, or nothing — in which case the frame is carried as unknown.

packages/warp/src/frames.ts

list function

export function list(f: AnyFrame, key: string): string[] { … }

A comma-separated header as a list. Empty when absent, so a caller needs no guard.

Specified inspec/client/adoption.md·spec/compiler/supported-subset.md·spec/ir/template-ir-2.md·spec/warp/warp-1.md

packages/warp/src/frames.ts

negotiate function

export function negotiate(hello: ClientHello, server: ServerCapabilities): Negotiation { … }

Capability variance, one mechanism: nothing here fails — a missing capability costs a form, a fill, or an animation, never correctness.

Raised in this fileE_WARP_MAJOR

Specified inspec/FINDINGS.md·spec/kernel/transport.md·spec/warp/warp-1.md

packages/warp/src/handshake.ts

num function

export function num(f: AnyFrame, key: string): number | undefined { … }

A header read as a number. Absent and unparseable are both undefined.

Specified inspec/warp/warp-1.md

packages/warp/src/frames.ts

preamble function

export function preamble(major = WARP_MAJOR, minor = WARP_MINOR): Uint8Array { … }

The eight bytes that open a stream: magic and version, so a wrong stream is refused at once.

Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION

packages/warp/src/codec.ts

readResident function

export function readResident(f: Frame): ClientHello { … }

A client hello back out of a RESIDENT frame.

Raised in this fileE_WARP_MAJOR

packages/warp/src/handshake.ts

reservedHeader function

export function reservedHeader(key: string): boolean { … }

True for a header key the frame reserved for itself rather than for a slot.

Specified inspec/VERSIONING.md

packages/warp/src/frames.ts

residentFrame function

export function residentFrame(hello: ClientHello): Frame { … }

A RESIDENT frame from a client hello.

Raised in this fileE_WARP_MAJOR

packages/warp/src/handshake.ts

resumeFrame function

export function resumeFrame(input: { epoch: string; tpl?: string; since?: number }): Frame { … }

A frozen and evicted webview reconnects with the last epoch it committed and the templates it still holds, and the server continues from there rather than restarting.

Raised in this fileE_WARP_MAJOR

packages/warp/src/handshake.ts

str function

export function str(f: AnyFrame, key: string): string | undefined { … }

A header read as text.

packages/warp/src/frames.ts

warpFrame function

export function warpFrame(n: Negotiation): Frame { … }

The first frame the server sends: versions and strategy, and — since ok/fatal were added — whether anything was settled at all. See spec/kernel/transport.md.

Raised in this fileE_WARP_MAJOR

packages/warp/src/handshake.ts

ClientHello interface

export interface ClientHello {
  warp: string
  ir: string
  /** Coarse, bucketed digest of held template versions. Never a precise set. */
  tpl?: string
  forms?: WireForm[]
  transport?: Transport
  /** Incremental declarative-shadow-DOM parsing, not merely DSD support. */
  dsd?: boolean
  /** Same-document View Transitions, for committing an epoch without a flash. */
  vt?: boolean
  /** Service workers. Unavailable in generic WKWebView and suppressed by many in-app browsers. */
  sw?: boolean
  /** Persistent storage the resident-template set can live in when there is no service worker. */
  idb?: boolean
  rtt?: number
  ect?: string
  cpu?: number
  engine?: string
  caps?: string[]
}

What a client announces: its versions, the forms it accepts, and the templates it holds.

Raised in this fileE_WARP_MAJOR

packages/warp/src/handshake.ts

Decoder interface

export interface Decoder {
  push(chunk: Uint8Array): AnyFrame[]
  end(): void
  peer: { major: number; minor: number } | null
}

A streaming decoder: push bytes, take whole frames, and read back what the peer announced.

Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION

packages/warp/src/codec.ts

DecoderOptions interface

export interface DecoderOptions {
  /** Reject frames travelling the wrong way, which is a protocol violation, not a version gap. */
  expect?: 'up' | 'down'
  /** Refuse a stream whose preamble announces a different major. */
  major?: number
}

What a decoder refuses, as opposed to what it cannot read.

Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION

packages/warp/src/codec.ts

Frame interface

export interface Frame {
  kind: FrameKind
  header: Header
  body?: Uint8Array
  /** Set when the body is UTF-8 text rather than opaque bytes. */
  bodyIsText?: boolean
}

One frame: a kind, a header of names, and an optional body.

packages/warp/src/frames.ts

Negotiation interface

export interface Negotiation {
  ok: boolean
  spec: string
  warp: string
  ir: string
  forms: WireForm[]
  /** How this response will be delivered, after the client's transport is taken into account. */
  strategy: 'stream' | 'collapse' | 'socket'
  /** Who fills an out-of-order hole: the parser, or the ~1 KB filler script. */
  fill: 'dsd' | 'script'
  commit: 'view-transition' | 'instant'
  /** Where a returning client may keep resident templates. */
  residency: 'service-worker' | 'indexeddb' | 'http-cache'
  /** Whether a severed channel may continue instead of restarting. Webviews get frozen often. */
  resumable: boolean
  downgrades: string[]
  fatal?: string
}

What was settled: the versions, the forms, and the strategy both ends agreed on.

Raised in this fileE_WARP_MAJOR

Specified inspec/VERSIONING.md

packages/warp/src/handshake.ts

ServerCapabilities interface

export interface ServerCapabilities {
  warp: string
  ir: string
  forms: WireForm[]
}

What this server can offer, so the intersection is a fact rather than an assumption.

Raised in this fileE_WARP_MAJOR

packages/warp/src/handshake.ts

UnknownFrame interface

export interface UnknownFrame {
  kind: 'UNKNOWN'
  code: number
  header: Header
  body?: Uint8Array
  bodyIsText?: boolean
}

A frame kind this build does not know. Skippable, which is the whole point of length prefixes.

packages/warp/src/frames.ts

AnyFrame type

export type AnyFrame = Frame | UnknownFrame

A frame this version understands, or one it does not. Both are carried; only one is read.

packages/warp/src/frames.ts

Direction type

export type Direction = 'up' | 'down'

Which way a frame kind travels. Declared per kind, so a frame sent the wrong way is refused.

packages/warp/src/frames.ts

FrameKind type

export type FrameKind = keyof typeof FRAMES

Every frame this version defines. An unknown code is carried rather than refused.

packages/warp/src/frames.ts

Header type

export type Header = Record<string, HeaderValue>

A frame's header: names, never content. Whatever is large belongs in the body.

packages/warp/src/frames.ts

HeaderValue type

export type HeaderValue = string | number | boolean

What a header value can be. Everything is text on the wire; these are what it parses back to.

packages/warp/src/frames.ts

Transport type

export type Transport = 'stream' | 'buffered' | 'socket' | 'turn'

How the document itself reached the client. See spec/warp/warp-1.md: buffered and turn.

Raised in this fileE_WARP_MAJOR

packages/warp/src/handshake.ts

WireForm type

export type WireForm = 'html' | 'bundle' | 'split' | 'patch' | 'delta' | 'remote'

The forms a client may accept. Mirrors the IR's own list, because the wire is the contract.

Raised in this fileE_WARP_MAJOR

packages/warp/src/handshake.ts

FRAME_HEADER_BYTES const

export const FRAME_HEADER_BYTES = 8

The fixed part of a binary frame: code, flags, and the two lengths.

packages/warp/src/version.ts

FRAMES const

export const FRAMES = {
  RESIDENT: { code: 0x01, dir: 'up' },
  HELD: { code: 0x02, dir: 'up' },
  REFRESH: { code: 0x03, dir: 'up' },
  /** Stage data for a route, do not paint — at three grains: `tpl`, `at`, `plan`. See `spec/warp/warp-1.md`. */
  WARM: { code: 0x04, dir: 'up' },
  INTENT: { code: 0x05, dir: 'up' },
  RESUME: { code: 0x07, dir: 'up' },

  WARP: { code: 0x10, dir: 'down' },
  SHELL: { code: 0x11, dir: 'down' },
  SLOT: { code: 0x12, dir: 'down' },
  HTML: { code: 0x13, dir: 'down' },
  TPL: { code: 0x14, dir: 'down' },
  DATA: { code: 0x15, dir: 'down' },
  DELTA: { code: 0x16, dir: 'down' },
  PATCH: { code: 0x17, dir: 'down' },
  SIGNAL: { code: 0x18, dir: 'down' },
  COMMIT: { code: 0x19, dir: 'down' },
  MOD: { code: 0x1a, dir: 'down' },
  CSS: { code: 0x1b, dir: 'down' },
  STALE: { code: 0x1c, dir: 'down' },
  /** The answer to `WARM at=`: what the r
  …

Codes below 0x10 travel client to server, codes from 0x10 up travel server to client. See spec/warp/warp-1.md.

packages/warp/src/frames.ts

HELD_ONLY const

export const HELD_ONLY = '$only'

$ is reserved because a HELD frame's headers are slot names. $only means the whole of what the client holds. See spec/warp/warp-1.md.

packages/warp/src/frames.ts

PREAMBLE_BYTES const

export const PREAMBLE_BYTES = 8

How many bytes open a stream, so a decoder knows when it can start reading.

packages/warp/src/version.ts

RETIRED const

export const RETIRED: readonly { code: number; was: string; until: string }[] = [
  { code: 0x06, was: 'ACK, in the up direction', until: 'warp 1.2.0' },
]

Codes that meant something once and are not to be reused — the one version mistake a length prefix can't catch.

Specified inspec/FINDINGS.md·spec/VERSIONING.md

packages/warp/src/frames.ts

WARP_FORMS const

export const WARP_FORMS: WireForm[] = ['html', 'bundle', 'split', 'patch', 'delta']

No default: this package owns the Warp version, not the IR version. See spec/FINDINGS.md for the bug that happened when it tried to.

Raised in this fileE_WARP_MAJOR

packages/warp/src/handshake.ts

WARP_MAGIC const

export const WARP_MAGIC = 'WRP1'

Binary stream preamble: magic, then the major and minor the sender is speaking.

packages/warp/src/version.ts

WARP_MAJOR const

export const WARP_MAJOR = 1

The major. A different one is refused rather than negotiated: majors are wire breaks.

packages/warp/src/version.ts

WARP_MINOR const

export const WARP_MINOR = 8

The minor. Additive, so a peer on a lower one skips what it does not know.

packages/warp/src/version.ts

WARP_SPEC const

export const WARP_SPEC = 'weft.warp/1'

The protocol name, in every preamble. A different name is a different protocol.

packages/warp/src/version.ts

WARP_VERSION const

export const WARP_VERSION = '1.8.0'

The version this build speaks.

packages/warp/src/version.ts