@abide/abide 0.104.0 → 0.105.0

package/src/shared/framing.ts

@@ -1,46 +1,26 @@
-// 16.32 — A FRAMED ANSWER, read one JSON value per line: the whole line for jsonl, the `data:` line of
-// each event for sse. A line that does not carry the prefix — an sse `event:` line, a blank line — is
-// skipped. One line reader behind both a body read to the end and one read as it lands.
+// 16.32 — A FRAMED ANSWER, read one JSON value per frame: each line for jsonl, the `data` of each
+// event for sse. One reader, `frameReader`, behind both a body read to the end and one read as it
+// lands — and behind `abide watch`, which reads an event stream's events by name. The writer is the
+// server's (`server/streamEvent.ts`).
 //
 // 16.68 — AND ITS LAST FRAME MAY BE A REFUSAL: one that reached the stream after it had answered, so
-// after its status was sent. An sse `event: refusal` and the Problem Details on its `data:` line, or a
+// after its status was sent. An sse `event: refusal` and the Problem Details as its `data`, or a
 // jsonl line `{"$refusal": <Problem Details>}` — read here as the refusal, thrown where it lands.
 
-import { failedFrom, isProblem, type Problem } from './Failed.ts'
+import { failedFrom, isProblem } from './Failed.ts'
+import { REFUSAL_KEY } from './REFUSAL_KEY.ts'
 
-/** The key a jsonl line carries a refusal under (16.68). */
-const REFUSAL_KEY = '$refusal'
+/** The two framings a streamed JSON answer is read in. 17.6. */
+export type Framed = 'jsonl' | 'sse'
 
-/** A framed stream's last frame, as the server writes it for a refusal (16.68). */
-export function refusalFrame(problem: Problem, prefix: string): string {
-    return prefix === ''
-        ? `${JSON.stringify({ [REFUSAL_KEY]: problem })}\n`
-        : `event: refusal\n${prefix}${JSON.stringify(problem)}\n\n`
-}
-
-// What a read of one framed body carries from one line to the next: whether an sse event named the
-// data line after it a refusal.
-type Reading = { refusal: boolean }
-
-// A refusal's frame, read: thrown where it lands among the chunks.
-class Refused {
-    problem: Problem
-    constructor(problem: Problem) {
-        this.problem = problem
-    }
-}
-
-/**
- * What precedes a chunk's JSON on its line: nothing for jsonl, `data: ` for sse, and `null` where
- * the answer is not framed at all.
- */
-export function framingPrefix(type: string | null | undefined): string | null {
+/** How an answer at `type` is framed, or `null` where it is not framed at all. */
+export function framingOf(type: string | null | undefined): Framed | null {
     if (
         type?.startsWith('application/jsonl') ||
         type?.startsWith('application/x-ndjson')
     )
-        return ''
-    if (type?.startsWith('text/event-stream')) return 'data: '
+        return 'jsonl'
+    if (type?.startsWith('text/event-stream')) return 'sse'
     return null
 }
 
@@ -52,24 +32,102 @@ export function framingPrefix(type: string | null | undefined): string | null {
  */
 export function carriesBytes(type: string | null | undefined): boolean {
     if (type === null || type === undefined || type === '') return false
-    if (framingPrefix(type) !== null) return false
+    if (framingOf(type) !== null) return false
     const semicolon = type.indexOf(';')
     const essence = semicolon === -1 ? type : type.slice(0, semicolon)
     return essence !== 'application/json' && !essence.endsWith('+json')
 }
 
+/** One frame: an sse event's name — `message` where it named none — `id` and `data`, or a jsonl line. */
+export type Frame = { name: string; id: string | undefined; data: string }
+
+/**
+ * A framed body's reader, fed its text as it arrives: pushes each frame the text completes onto
+ * `frames` — and, where `ended`, the last one too.
+ *
+ * An event stream is read as the format says (18.27) — fields by name, a comment skipped, `data`
+ * lines joined, the event ending at a blank line. A jsonl line is a frame with nothing but its data.
+ * A closure over the read's own state, which is all it captures.
+ */
+function frameReader(
+    lines: boolean,
+): (text: string, ended: boolean, frames: Frame[]) => void {
+    // The text after the last newline read, held until its line completes.
+    let rest = ''
+    let name = 'message'
+    let id: string | undefined
+    let data: string | undefined
+    return (text, ended, frames) => {
+        // A long line across many reads is held unscanned until its newline lands, or each read
+        // rescans everything before it.
+        if (!ended && !text.includes('\n')) {
+            rest += text
+            return
+        }
+        const read = (rest + text).split('\n')
+        // The unfinished last line waits for the next read; at the end, a blank line ends it.
+        rest = ended ? '' : (read.pop() as string)
+        if (ended) read.push('')
+        for (const line of read) {
+            // A blank line ends an event; a jsonl line is one.
+            if (lines || line === '') {
+                const complete = lines ? line || undefined : data
+                if (complete !== undefined)
+                    frames.push({ name, id, data: complete })
+                name = 'message'
+                id = data = undefined
+                continue
+            }
+            // A field and its value, the one space after the colon dropped and a CRLF's `\r` with
+            // it; a line with no colon is a field with no value. A comment — an event stream's
+            // opener — names the field ``, which is none.
+            const colon = line.indexOf(':')
+            const field = colon === -1 ? line : line.slice(0, colon)
+            if (field !== 'data' && field !== 'event' && field !== 'id')
+                continue
+            let start = colon === -1 ? line.length : colon + 1
+            if (line.charCodeAt(start) === 32) start += 1
+            const value = line.slice(
+                start,
+                line.charCodeAt(line.length - 1) === 13
+                    ? line.length - 1
+                    : line.length,
+            )
+            if (field === 'data')
+                data = data === undefined ? value : `${data}\n${value}`
+            else if (field === 'event') name = value
+            else id = value
+        }
+    }
+}
+
+/**
+ * The chunk a frame carried, or — where it is a refusal (16.68) — that refusal, thrown.
+ *
+ * Per chunk: the reserved key is tested before any key list is built.
+ */
+function chunkOf(frame: Frame, lines: boolean): unknown {
+    const value = JSON.parse(frame.data)
+    const problem = !lines
+        ? frame.name === 'refusal' && value
+        : typeof value === 'object' &&
+          Object.hasOwn(Object(value), REFUSAL_KEY) &&
+          Object.keys(value).length === 1 &&
+          value[REFUSAL_KEY]
+    if (isProblem(problem)) throw failedFrom(problem)
+    return value
+}
+
 /**
- * A streamed answer's chunks: each JSON value its framing carried, or, for bytes (16.46), each
- * `Uint8Array` as it was read — bytes have no framing to split them back into the chunks the
- * handler yielded.
+ * A streamed answer's chunks: each JSON value its `framing` carried, or, for bytes (16.46) — an
+ * unread body with no framing — each `Uint8Array` as it was read: bytes have no framing to split
+ * them back into the chunks the handler yielded.
  */
 export function answerChunks(
     body: ReadableStream<Uint8Array>,
-    type: string | null | undefined,
+    framing: Framed | null,
 ): AsyncIterable<unknown> {
-    return carriesBytes(type)
-        ? bytesStream(body)
-        : framedStream(body, framingPrefix(type) ?? '')
+    return framing === null ? bytesStream(body) : framedStream(body, framing)
 }
 
 /**
@@ -92,113 +150,54 @@ async function* bytesStream(
     }
 }
 
-/** The chunks a framed text carried, every line of it complete. */
-export function framedChunks(text: string, prefix: string): unknown[] {
-    const chunks: unknown[] = []
-    readLines(text, prefix, true, chunks, { refusal: false })
-    for (const chunk of chunks)
-        if (chunk instanceof Refused) throw failedFrom(chunk.problem)
-    return chunks
+/** The chunks a framed text carried, every frame of it complete. */
+export function framedChunks(text: string, framing: Framed): unknown[] {
+    const lines = framing === 'jsonl'
+    const frames: Frame[] = []
+    frameReader(lines)(text, true, frames)
+    return frames.map((frame) => chunkOf(frame, lines))
+}
+
+/** An event stream's events, yielded as each completes. */
+export function eventsOf(
+    body: ReadableStream<Uint8Array>,
+): AsyncGenerator<Frame> {
+    return framedStream(body, 'sse', true) as AsyncGenerator<Frame>
 }
 
 /**
- * A framed body's chunks, yielded as each line completes.
+ * A framed body's chunks — or, where `events`, its frames as they are — yielded as each frame
+ * completes.
  *
  * Canceled when the reader stops reading — a refresh starts a new run and the old one's reader has
  * nothing left to hand anything.
  */
 export async function* framedStream(
     body: ReadableStream<Uint8Array>,
-    prefix: string,
+    framing: Framed,
+    events?: true,
 ): AsyncGenerator<unknown> {
+    const lines = framing === 'jsonl'
     const reader = body.getReader()
     const decoder = new TextDecoder()
-    const chunks: unknown[] = []
-    const reading: Reading = { refusal: false }
-    let buffered = ''
+    const framed = frameReader(lines)
+    const frames: Frame[] = []
     try {
         for (;;) {
             const { done, value } = await reader.read()
-            const decoded = done
-                ? decoder.decode()
-                : decoder.decode(value, { stream: true })
-            // A long line across many reads is held unscanned until its newline lands, or each read
-            // rescans everything before it.
-            if (!done && !decoded.includes('\n')) {
-                buffered += decoded
-                continue
-            }
-            buffered = readLines(
-                buffered + decoded,
-                prefix,
+            framed(
+                done
+                    ? decoder.decode()
+                    : decoder.decode(value, { stream: true }),
                 done,
-                chunks,
-                reading,
+                frames,
             )
-            for (const chunk of chunks) {
-                if (chunk instanceof Refused) throw failedFrom(chunk.problem)
-                yield chunk
-            }
-            chunks.length = 0
+            for (const frame of frames)
+                yield events ? frame : chunkOf(frame, lines)
+            frames.length = 0
             if (done) return
         }
     } finally {
         void reader.cancel().catch(() => {})
     }
 }
-
-/**
- * Parses each complete line of `text` into `chunks`, and the unfinished last one too where `ended`.
- *
- * Answers what is left of `text` after the last newline.
- */
-function readLines(
-    text: string,
-    prefix: string,
-    ended: boolean,
-    chunks: unknown[],
-    reading: Reading,
-): string {
-    let start = 0
-    for (;;) {
-        const newline = text.indexOf('\n', start)
-        if (newline === -1 && !ended) return text.slice(start)
-        const end = newline === -1 ? text.length : newline
-        if (prefix !== '' && text.startsWith('event: refusal', start))
-            reading.refusal = true
-        else if (end > start && text.startsWith(prefix, start)) {
-            const value: unknown = JSON.parse(
-                text.slice(start + prefix.length, end),
-            )
-            chunks.push(refusalIn(value, prefix, reading) ?? value)
-            reading.refusal = false
-        }
-        if (newline === -1) return ''
-        start = newline + 1
-    }
-}
-
-// The refusal a value carries as its frame: the data line an sse event named one, or a jsonl line
-// holding the one reserved key and Problem Details under it.
-function refusalIn(
-    value: unknown,
-    prefix: string,
-    reading: Reading,
-): Refused | undefined {
-    if (prefix !== '')
-        return reading.refusal && isProblem(value)
-            ? new Refused(value)
-            : undefined
-    // Per chunk: the reserved key is tested before any key list is built.
-    if (
-        value === null ||
-        typeof value !== 'object' ||
-        !Object.hasOwn(value, REFUSAL_KEY)
-    )
-        return undefined
-    const keys = Object.keys(value)
-    const problem = (value as Record<string, unknown>)[REFUSAL_KEY]
-    return keys.length === 1 && isProblem(problem)
-        ? new Refused(problem)
-        : undefined
-}

package/src/shared/queryText.ts

@@ -1,18 +1,26 @@
 /**
  * A record of members as a query string.
  *
- * ONE QUERY-STRING RULE for `rpcRequest`'s args (16.18) and `url`'s `Query` (30.6): a member left
+ * 30.28 — ONE QUERY-STRING RULE for `rpcRequest`'s args (16.18) and `url`'s `Query`: a member left
  * `undefined` is omitted, a list is its member repeated, and anything else is its text — `null`
- * included, which 19.7 reads back as `null` where the schema declares it. An empty list writes
- * nothing here; `rpcRequest` spells it as a bare name.
+ * included, which 19.7 reads back as `null` where the schema declares it. AN EMPTY LIST IS ITS NAME
+ * WITH NO `=`, last, which no text value spells — `tags=` is the one-member list `['']` — so 19.7
+ * reads it back as `[]` rather than losing the member.
  */
 export function queryText(members: Record<string, unknown>): string {
     const query = new URLSearchParams()
+    let bare = ''
     for (const [name, value] of Object.entries(members)) {
         if (value === undefined) continue
-        if (Array.isArray(value))
-            for (const each of value) query.append(name, String(each))
-        else query.append(name, String(value))
+        if (!Array.isArray(value)) query.append(name, String(value))
+        else if (value.length === 0) bare += `&${bareName(name)}`
+        else for (const each of value) query.append(name, String(each))
     }
-    return query.toString()
+    const text = query.toString()
+    return text === '' ? bare.slice(1) : text + bare
+}
+
+/** A query member's name in the encoding `URLSearchParams` gives it, without its `=`. */
+export function bareName(name: string): string {
+    return new URLSearchParams([[name, '']]).toString().slice(0, -1)
 }

package/src/shared/reactive/Cursor.ts

@@ -1,7 +1,7 @@
 // THE CURSOR. RULEBOOK 2.6: a streaming producer's chunks, read from the chunk buffer by ordinal,
 // so two chunks between two `await`s are two turns of the loop, and a patch or a write over the
 // stream moves no place (5.7, 9.12). Where the run ENDS is the caller's settling, handed to
-// `closeOn`: `for await` over a `Reactive` is `Reactive.ts`'s `producedRun`.
+// `closeOn`: one run's reader is `Reactive.ts`'s `runChunks`.
 //
 // A NARROW FACE rather than the `Cell`, the same way `tracking.ts` takes a `Tracked`: what a
 // cursor reads is a handful of fields, and naming them keeps the cell's internals out of a
@@ -15,7 +15,7 @@ import {
 } from './tracking.ts'
 
 /**
- * What a cursor reads, and all of a cell the server is handed (`servedCellOf`).
+ * What a cursor reads of a cell.
  *
  * `ring[index]` carries ordinal `ringBase + index + 1`, so a cursor holding an ordinal finds its
  * place in a stream's chunk buffer without the buffer having to hold one.
@@ -92,6 +92,8 @@ export class Cursor {
         this.reader = newSubscriber([source], null)
         this.reader.notify = (): void => this.woken()
         source.readers.push(this.reader)
+        // ONE PLACED PAST EVERY CHUNK is a wake and never behind, so no patch has a place to keep.
+        if (from === Number.POSITIVE_INFINITY) return
         let cursors = CURSORS.get(source)
         if (cursors === undefined) {
             cursors = new Set()