All files / core/blong-gogo/src gatewayStream.ts

77.74% Statements 276/355
84.61% Branches 55/65
71.42% Functions 20/28
77.74% Lines 276/355

Press n or j to go to the next uncovered block, b, p or k for the previous block.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 3561x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 425x 424x 424x 425x 425x 425x 425x 421x 421x 1x 1x 1x               12x 12x 12x 12x 12x 12x 12x 1x     2x 2x 2x 2x 2x 2x 2x 2x                                                               1x 10x 10x   13x 3x 13x 13x   2x     10x 10x 10x 10x 1x 1x 1x 1x 1x 1x 1x 1x 1x 4x 4x 4x 4x 4x 5x 5x 4x 4x 5x 5x     4x         4x 4x 1x 4x 4x 1x 1x 1x 1x 1x 1x 1x 1x 1x 19x 19x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 13x 13x 13x 13x 13x 13x 13x 13x 13x 13x 13x               11x 11x                   7x 7x 7x 4x 4x 4x 4x 4x 13x 13x 13x   17x 17x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 16x 16x 18x 18x 13x 2x 13x 13x 13x 13x 13x 1x 1x 1x 20x 12x 12x 12x 20x 20x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x                         1x 1x 1x  
/**
 * The frame writer behind a streamed route (`@@D-948` `@@D-949`).
 *
 * A stream is a *sequence* where an ordinary call is one value: a realm handler
 * answers an async iterable, and each value it yields leaves as one frame. Nothing
 * here knows what a frame means — the handler's values are the payload, and the
 * writer's job is only to put them on the wire in a way a reader can follow. That
 * is deliberate: the same writer serves a log tail, a progress feed, a file and
 * anything else a realm wants to send over time.
 *
 * Four obligations, each of which somebody has to be able to read on its own:
 *
 * - **Backpressure.** The sink says when it is full and the loop waits for
 *   `drain` rather than queueing in memory, so a slow reader slows the producer
 *   instead of growing the process. A producer that cannot be slowed has to cope
 *   with a gap itself — one more reason the resume cursor is the *route's*
 *   concept and not this file's.
 * - **Heartbeat.** A frame that carries no value, written as soon as the stream opens and again while
 *   nothing else is being written, keeps an idle proxy or ingress from closing a connection the reader
 *   still wants and lets the reader tell a quiet stream from a dead one. In the text envelope it is an
 *   SSE comment, which a client reading `data:` never sees; in the binary one it is a keepalive frame
 *   @@D-955.
 * - **Abort.** The reader going away is an ordinary event: the signal is aborted
 *   so the producer can stop, and the loop stops pulling.
 * - **Ending.** A thrown producer is one `error` frame — the frames before it stay
 *   readable — and then the response closes, so a reader never waits for a frame
 *   that will not come.
 *
 * Two envelopes carry the same frames, and the caller picks one with `Accept`:
 * server-sent events, which a person can read and `curl` can print, and a binary
 * envelope, which costs no base64 and no escape handling. Sealing is the route's
 * decision rather than the caller's (`@@D-949`), because a caller that could ask
 * for the readable envelope would turn a confidential stream into a readable one.
 */
 
import {
    STREAM_BINARY_TYPE,
    STREAM_FLAG_BINARY,
    STREAM_FLAG_KEEPALIVE,
    STREAM_FLAG_SEALED,
    STREAM_MAX_FRAME_BYTES,
    STREAM_TEXT_TYPE,
    encodeFrame,
    sealFrame,
    toBase64,
} from '@feasibleone/blong-mle';
 
export {STREAM_BINARY_TYPE, STREAM_TEXT_TYPE};
 
/** A frame whose payload was sealed. */
export const FLAG_SEALED = STREAM_FLAG_SEALED;
 
/** A frame whose payload is bytes rather than JSON. */
export const FLAG_BINARY = STREAM_FLAG_BINARY;
 
/** A frame that carries no value, written so a reader can tell quiet from dead @@D-955. */
export const FLAG_KEEPALIVE = STREAM_FLAG_KEEPALIVE;
 
/** The payload a keepalive carries: none at all. */
const NO_PAYLOAD = new Uint8Array(0);
 
/**
 * The most one frame may occupy, and why a writer checks it at all.
 *
 * The length field is what a reader trusts, so a frame above the cap is one no
 * reader will accept: better the producer's route hears it here — as one `error`
 * frame and an end — than that the reader drops the stream after refusing a
 * prefix (`@@D-950`).
 */
export const MAX_FRAME_BYTES = STREAM_MAX_FRAME_BYTES;
 
/** The default idle interval: below the usual proxy timeout, above a poll. */
export const DEFAULT_HEARTBEAT_MS = 15000;
 
/** The two envelopes a stream can be written in. */
export type StreamEnvelope = 'text' | 'binary';
 
/** The smallest writable this needs: everything above that is the caller's. */
export interface IFrameSink {
    /** Write one frame; `false` means the sink is full until `drained` resolves. */
    write(frame: string | Uint8Array): boolean;
    /** Resolve when the sink has room again, or when the reader has gone. */
    drained(signal: AbortSignal): Promise<void>;
    /** Finish the response. */
    end(): void;
}
 
/**
 * The envelope a caller asked for, from its `Accept` header.
 *
 * Stream types are opt-in on purpose: an ordinary call arrives with `*​/*` (curl's
 * default, and a browser's for a request it did not describe), so a stream that
 * answered `*​/*` would answer every call with events. A caller names the envelope
 * it wants, and the text one wins when it names both, because that is the one a
 * person can read.
 */
export function envelopeOf(accept: string | undefined): StreamEnvelope | undefined {
    if (!accept) return undefined;
    // The first envelope the caller named wins, because that is the order it
    // expressed. A browser sends a list; a tool sends the one type it wants.
    for (const type of accept.split(',').map(entry => entry.split(';')[0].trim().toLowerCase())) {
        if (type === STREAM_TEXT_TYPE) return 'text';
        if (type === STREAM_BINARY_TYPE) return 'binary';
    }
    return undefined;
}
 
/** What one value becomes: its bytes, and whether those bytes are JSON. */
export function payloadOf(value: unknown): {bytes: Uint8Array; binary: boolean} {
    if (value instanceof Uint8Array) return {bytes: value, binary: true};
    const json = typeof value === 'string' ? value : JSON.stringify(value ?? null);
    return {bytes: new TextEncoder().encode(json), binary: false};
}

/** One value as one `data:` frame, escaped so a newline cannot end it early. */
export function dataFrame(value: unknown): string {
    const {bytes} = payloadOf(value);
    const text = new TextDecoder().decode(bytes);
    return `${text
        .split('\n')
        .map(line => `data: ${line}`)
        .join('\n')}\n\n`;
}
 
/** The payload a failed producer ends with. */
export function errorPayload(error: unknown): unknown {
    const typed = error as {message?: string; type?: string; statusCode?: number};
    return {
        error: {
            message: typed?.message ?? String(error),
            ...(typed?.type === undefined ? {} : {type: typed.type}),
            ...(typed?.statusCode === undefined ? {} : {statusCode: typed.statusCode}),
        },
    };
}

/**
 * How one value becomes one frame.
 *
 * The writer asks an encoder rather than knowing a format, which is what lets one
 * transport serve every route: what a frame *means* is the route's, and whether it
 * is sealed is a decision the gateway makes once per stream.
 */
export interface IFrameEncoder {
    encode(value: unknown, seq: number): Promise<string | Uint8Array>;
    /** The last frame, written after a producer failed. */
    error(error: unknown, seq: number): Promise<string | Uint8Array>;
    /**
     * A frame that says the stream is still there, carrying no value.
     *
     * The text envelope spells it as an SSE comment and the binary one as a frame flagged keepalive,
     * which every reader skips. It is not sealed even when the route seals: an empty frame has nothing
     * to protect, and spending a sequence number on it would only make the reader do crypto to learn
     * that nothing happened @@D-955.
     */
    keepalive(): string | Uint8Array;
}

/**
 * A frame that is sent as it is.
 *
 * Used by a route that opted out of sealing — because its frames carry something
 * that is not secret, a cursor or a status — and by the text envelope a reader
 * inspects by hand.
 */
export function plainEncoder(envelope: StreamEnvelope): IFrameEncoder {
    return {
        // An unsealed frame needs no sequence: nothing about it is a nonce.
        encode: async (value: unknown) => {
            if (envelope === 'text') return dataFrame(value);
            const {bytes, binary} = payloadOf(value);
            return binaryFrame(binary ? FLAG_BINARY : 0, bytes);
        },
        error: async (error: unknown) => {
            if (envelope === 'text') return dataFrame(errorPayload(error));
            return binaryFrame(0, payloadOf(errorPayload(error)).bytes);
        },
        keepalive: () =>
            envelope === 'text' ? ': ping\n\n' : binaryFrame(FLAG_KEEPALIVE, NO_PAYLOAD),
    };
}
 
/**
 * A frame sealed under the stream's own key (`@@D-949`).
 *
 * The key belongs to one stream, so the sequence number is the whole nonce and no
 * frame needs a random IV. `info` binds a frame to the route it was asked for, so a
 * frame captured from one method does not open under another.
 */
export function sealedEncoder(
    envelope: StreamEnvelope,
    key: CryptoKey,
    info: string,
): IFrameEncoder {
    const seal = async (value: unknown, seq: number): Promise<{sealed: Uint8Array}> => ({
        sealed: await sealFrame(key, seq, payloadOf(value).bytes, info),
    });
    return {
        encode: async (value: unknown, seq: number) => {
            const {sealed} = await seal(value, seq);
            if (envelope === 'binary') return binaryFrame(FLAG_SEALED, sealed);
            return `data: ${toBase64(sealed)}\n\n`;
        },
        error: async (error: unknown, seq: number) => {
            const {sealed} = await seal(errorPayload(error), seq);
            if (envelope === 'binary') return binaryFrame(FLAG_SEALED, sealed);
            return `data: ${toBase64(sealed)}\n\n`;
        },
        // Unsealed on purpose, and carrying nothing: see the interface @@D-955.
        keepalive: () =>
            envelope === 'text' ? ': ping\n\n' : binaryFrame(FLAG_KEEPALIVE, NO_PAYLOAD),
    };
}
 
/**
 * A binary frame: its length, then the flag byte, then the payload.
 *
 * The length is what makes the envelope self-delimiting — a reader that receives a
 * chunk of any size can find the frames in it, which the newline does for the text
 * envelope.
 */
export function binaryFrame(flags: number, payload: Uint8Array): Uint8Array {
    return encodeFrame(flags, payload);
}
 
export interface IEventStreamOptions {
    sink: IFrameSink;
    /** The values to send, in order. Each becomes one frame. */
    iterate: AsyncIterable<unknown>;
    /** Aborts when the reader closes the connection. */
    signal: AbortSignal;
    /** How a value becomes a frame. */
    encoder: IFrameEncoder;
    /** How often an idle stream says it is alive, and how long after it opens it first says so. */
    heartbeatMs?: number;
    /** Whether the stream says it is alive at all. */
    heartbeat?: boolean;
    /** The most one frame may occupy. A producer above it ends the stream. */
    maxFrameBytes?: number;
}
 
/**
 * Write the iterable as a stream, and resolve once the response ends.
 *
 * Resolves rather than throws: the caller is a route handler that has already
 * taken over the response, so a producer's failure has nowhere to go but a frame —
 * and one frame is what a reader can still report.
 */
export async function writeEventStream({
    sink,
    iterate,
    signal,
    encoder,
    heartbeatMs = DEFAULT_HEARTBEAT_MS,
    heartbeat = true,
    maxFrameBytes = MAX_FRAME_BYTES,
}: IEventStreamOptions): Promise<void> {
    let idle: ReturnType<typeof setInterval> | undefined;
    let wroteSomething = false;
    const write = async (frame: string | Uint8Array): Promise<void> => {
        wroteSomething = true;
        if (sink.write(frame)) return;
        await sink.drained(signal);
    };
    // A keepalive is not a value, so it does not count as writing something: the next idle tick still
    // owes the reader one @@D-955.
    const keepalive = async (): Promise<void> => {
        if (signal.aborted) return;
        if (sink.write(encoder.keepalive())) return;
        await sink.drained(signal);
    };
    if (heartbeat && heartbeatMs > 0) {
        // The first one leaves at once, with the headers. A reader that has just subscribed learns that
        // the stream is open without waiting for the producer's first value — and an intermediary that
        // holds a response back until its first byte now has one, so the headers reach the reader in
        // this request rather than at the first record or never @@D-955.
        await keepalive();
        idle = setInterval(() => {
            const silent = !wroteSomething;
            wroteSomething = false;
            if (silent) keepalive().catch(() => {});
        }, heartbeatMs);
        // An unref'd timer is what keeps a served process able to exit: the
        // heartbeat is a convenience for the reader, not a reason to stay alive.
        idle.unref?.();
    }
    let seq = 0;
    try {
        for await (const value of iterate) {
            if (signal.aborted) break;
            const frame = await encoder.encode(value, seq);
            if (frameByteLength(frame) > maxFrameBytes) {
                // A reader would refuse this frame's prefix, so sending it would
                // end the stream at the far end with nothing to explain it. The
                // producer's own failure is reported here and the stream closes.
                throw Object.assign(
                    new Error(
                        `a stream frame of ${frameByteLength(frame)} bytes exceeds the ` +
                            `${maxFrameBytes}-byte limit: the route must split what it sends`,
                    ),
                    {type: 'stream.frameTooLarge', statusCode: 413},
                );
            }
            await write(frame);
            seq += 1;
            if (signal.aborted) break;
        }
    } catch (error) {
        if (!signal.aborted) await write(await encoder.error(error, seq));
    } finally {
        if (idle) clearInterval(idle);
        sink.end();
    }
}
 
/** How many bytes a frame occupies on the wire, whichever envelope carried it. */
export function frameByteLength(frame: string | Uint8Array): number {
    if (frame instanceof Uint8Array) return frame.length;
    // A text frame is what the reader parses back into one; the payload is the
    // base64 or JSON between the markers, and it is the payload that has a limit.
    const match = /^data: (.*)\n\n$/s.exec(frame);
    return match ? match[1].length : frame.length;
}
 
/**
 * A `ServerResponse` as the sink this module writes to.
 *
 * `drained` races the socket's `drain` against the abort signal, because a reader
 * that left while the loop was waiting for room would otherwise hold the producer
 * until the socket's own timeout — the one wait here with no other way out.
 */
export function nodeSink(raw: {
    write(chunk: string | Uint8Array): boolean;
    end(): void;
    once(event: 'drain' | 'close', listener: () => void): unknown;
    off(event: 'drain' | 'close', listener: () => void): unknown;
}): IFrameSink {
    return {
        write: frame => raw.write(frame),
        drained: signal =>
            new Promise<void>(resolve => {
                if (signal.aborted) return resolve();
                const done = (): void => {
                    raw.off('drain', done);
                    raw.off('close', done);
                    signal.removeEventListener('abort', done);
                    resolve();
                };
                raw.once('drain', done);
                raw.once('close', done);
                signal.addEventListener('abort', done, {once: true});
            }),
        end: () => raw.end(),
    };
}