@fastls/fastls 0.0.0-stage → 0.10.1-dev.0

package/dist/session.js

@@ -0,0 +1,390 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Session = void 0;
+const node_fs_1 = require("node:fs");
+const cookies_js_1 = require("./cookies.js");
+const errors_js_1 = require("./errors.js");
+const native_js_1 = require("./native.js");
+const response_js_1 = require("./response.js");
+const timeout_js_1 = require("./timeout.js");
+const upload_js_1 = require("./upload.js");
+const duplex_js_1 = require("./duplex.js");
+const sse_js_1 = require("./sse.js");
+const notifications_js_1 = require("./notifications.js");
+const request_options_js_1 = require("./request-options.js");
+const websocket_js_1 = require("./websocket.js");
+function decoding(decode, maximum) {
+    if (typeof decode !== "boolean")
+        throw new TypeError("decodeContent must be a boolean");
+    if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 2 ** 40)
+        throw new RangeError("maxDecodedBytes must be 1..1099511627776");
+}
+function proxyValue(value) {
+    if (value !== undefined && value !== null && typeof value !== "string")
+        throw new TypeError("proxy must be a URL string or null");
+    // The native validator owns URL parsing and redacted errors. Do not include
+    // credentials in JavaScript URL parser errors or normalize invalid input.
+    return value;
+}
+function proxyTrust(path) {
+    if (path === null || path === undefined)
+        return undefined;
+    if (typeof path !== "string")
+        throw new TypeError("proxyCaFile must be a path string or null");
+    const pem = (0, node_fs_1.readFileSync)(path, "utf8");
+    if (!pem.trim())
+        throw new TypeError("proxyCaFile is empty");
+    return pem;
+}
+function mergeHeaders(...sources) {
+    const merged = Object.create(null);
+    for (const source of sources) {
+        for (const [key, value] of Object.entries(source ?? {})) {
+            if (typeof value !== "string")
+                throw new TypeError("header values must be strings");
+            merged[key.toLowerCase()] = value;
+        }
+    }
+    return merged;
+}
+class Session {
+    /** Construct and initialize; failed initialization closes the new session. */
+    static async open(options = {}) {
+        const session = new Session(options);
+        try {
+            await session.ready();
+            return session;
+        }
+        catch (error) {
+            await session.closeAsync();
+            throw error;
+        }
+    }
+    notificationMode;
+    cookies;
+    native;
+    handle;
+    profile;
+    proxy;
+    proxyCaPem;
+    headers;
+    timeouts;
+    decodeContent;
+    maxDecodedBytes;
+    caPem;
+    active = new Set();
+    websockets = new Set();
+    producers = new Set();
+    closed = false;
+    notifier;
+    setup;
+    constructor(options = {}) {
+        this.proxy = proxyValue(options.proxy);
+        this.proxyCaPem = proxyTrust(options.proxyCaFile);
+        const notifications = options.notifications === undefined ? "auto" : options.notifications;
+        if (!["auto", "required", "poll"].includes(notifications))
+            throw new TypeError("notifications must be auto, required or poll");
+        this.profile = options.profile ?? "chrome/156/windows";
+        this.timeouts = (0, timeout_js_1.timeoutFields)(options.timeoutMs ?? 30000);
+        this.decodeContent = options.decodeContent ?? true;
+        this.maxDecodedBytes = options.maxDecodedBytes ?? 256 * 1024 * 1024;
+        decoding(this.decodeContent, this.maxDecodedBytes);
+        this.headers = mergeHeaders(options.headers);
+        if (options.cookies !== undefined && typeof options.cookies !== "boolean")
+            throw new TypeError("cookies must be a boolean");
+        this.caPem = options.caFile === undefined ? undefined : (0, node_fs_1.readFileSync)(options.caFile, "utf8");
+        if (this.caPem !== undefined && !this.caPem.trim())
+            throw new TypeError("caFile is empty");
+        this.native = native_js_1.Native.load(options.library);
+        const supported = this.native.notificationsAvailable && this.native.call("features").includes("session_notifications");
+        if (notifications === "required" && !supported)
+            throw new errors_js_1.FastlsError("notifications require a newer Fastls native library");
+        this.notificationMode = notifications !== "poll" && supported ? "async-events" : "poll";
+        this.handle = (0, native_js_1.asHandle)(this.native.call("session_create"));
+        this.cookies = new cookies_js_1.Cookies(input => {
+            this.ensureOpen();
+            const raw = (0, native_js_1.encodeNativeJSON)(input, 16384);
+            return this.native.call("session_cookies", this.handle, raw, raw.length);
+        });
+        try {
+            if (options.cookies === false) {
+                const raw = (0, native_js_1.encodeNativeJSON)({ action: "configure", enabled: false });
+                this.native.call("session_cookies", this.handle, raw, raw.length);
+            }
+        }
+        catch (error) {
+            this.close();
+            throw error;
+        }
+    }
+    ensureOpen() {
+        if (this.closed)
+            throw new errors_js_1.FastlsError("session is closed");
+    }
+    /** Initialize the shared wakeup channel before any HTTP request is allocated. */
+    async ready(signal) {
+        this.ensureOpen();
+        if (signal !== undefined && !(signal instanceof AbortSignal))
+            throw new TypeError("signal must be an AbortSignal");
+        if (signal?.aborted)
+            throw new errors_js_1.AbortError(undefined, { cause: signal.reason });
+        if (this.notificationMode === "poll")
+            return;
+        if (!this.notifier) {
+            const notifier = this.notifier = new notifications_js_1.Notifier(this.native, this.handle);
+            const setup = this.setup = notifier.start().catch(async (error) => {
+                await notifier.closeAsync();
+                if (this.notifier === notifier) {
+                    this.notifier = undefined;
+                    this.setup = undefined;
+                }
+                throw error;
+            });
+            void setup.catch(() => { });
+        }
+        const notifier = this.notifier;
+        notifier.setupWaiters++;
+        try {
+            if (signal)
+                await (0, upload_js_1.abortable)(this.setup, signal);
+            else
+                await this.setup;
+            this.ensureOpen();
+            notifier.check();
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new errors_js_1.AbortError(undefined, { cause: signal.reason });
+            throw error;
+        }
+        finally {
+            if (--notifier.setupWaiters === 0 && !notifier.isReady && this.notifier === notifier) {
+                notifier.close();
+                this.notifier = undefined;
+                this.setup = undefined;
+            }
+        }
+    }
+    begin(method, url, options, manual = false) {
+        this.ensureOpen();
+        if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) {
+            throw new TypeError("signal must be an AbortSignal");
+        }
+        if (options.signal?.aborted)
+            throw new errors_js_1.AbortError(undefined, { cause: options.signal.reason });
+        const headers = mergeHeaders(this.headers, options.headers);
+        for (const name of ["proxy-authorization", "proxy-connection"]) {
+            if (name in headers)
+                throw new errors_js_1.FastlsError("proxy headers must not be sent as target headers; configure proxy URL credentials");
+        }
+        const proxy = proxyValue(options.proxy === undefined ? this.proxy : options.proxy);
+        if (proxy && !this.native.call("features").includes("proxy_tunnels")) {
+            throw new errors_js_1.FastlsError("proxy support requires a newer Fastls native library");
+        }
+        const httpsProxy = proxy?.toLowerCase().startsWith("https://") ?? false;
+        if (httpsProxy && !this.native.call("features").includes("https_proxy_tls")) {
+            throw new errors_js_1.FastlsError("HTTPS proxy support requires a newer Fastls native library");
+        }
+        const proxyCaPem = !httpsProxy ? undefined : options.proxyCaFile === undefined
+            ? this.proxyCaPem : proxyTrust(options.proxyCaFile);
+        if (options.duplex !== undefined && typeof options.duplex !== "boolean")
+            throw new TypeError("duplex must be a boolean");
+        const duplex = options.duplex ?? false;
+        if (duplex && !this.native.call("features").includes("duplex_h2")) {
+            throw new errors_js_1.FastlsError("HTTP/2 duplex requires a newer Fastls native library");
+        }
+        const prepared = (0, request_options_js_1.prepare)(url, options, headers);
+        url = prepared.url;
+        const body = prepared.body === undefined && duplex && !manual ? Buffer.alloc(0) : prepared.body;
+        const streaming = (0, upload_js_1.isStreamingBody)(body) || duplex;
+        const bodyBytes = streaming || body === undefined ? undefined : Buffer.from(body);
+        const timeouts = options.timeoutMs === undefined ? this.timeouts : (0, timeout_js_1.timeoutFields)(options.timeoutMs);
+        const decodeContent = options.decodeContent ?? this.decodeContent;
+        const maxDecodedBytes = options.maxDecodedBytes ?? this.maxDecodedBytes;
+        decoding(decodeContent, maxDecodedBytes);
+        if (options.allowRedirects !== undefined && typeof options.allowRedirects !== "boolean") {
+            throw new TypeError("allowRedirects must be a boolean");
+        }
+        const started = performance.now();
+        let trailers;
+        if (options.trailers !== undefined) {
+            if (!this.native.call("features").includes("request_trailers"))
+                throw new errors_js_1.FastlsError("request trailers require a newer Fastls native library");
+            if (!options.trailers || typeof options.trailers !== "object" || Array.isArray(options.trailers))
+                throw new TypeError("trailers must be a mapping");
+            trailers = {};
+            for (const [name, value] of Object.entries(options.trailers)) {
+                const values = typeof value === "string" ? [value] : value;
+                if (!Array.isArray(values) || values.some(item => typeof item !== "string"))
+                    throw new TypeError("trailer values must be strings");
+                trailers[name] = [...values];
+            }
+        }
+        const handle = this.native.start({
+            session: this.handle, url, method, headers, trailers, proxy: proxy || undefined, proxy_ca_pem: proxyCaPem,
+            profile: options.profile ?? this.profile,
+            ...timeouts, decode_content: decodeContent, max_decoded_bytes: maxDecodedBytes,
+            disable_redirect: duplex || options.allowRedirects === false,
+            ca_pem: this.caPem,
+            body_base64: bodyBytes?.toString("base64"),
+            stream_body: streaming || undefined,
+            duplex: duplex || undefined,
+        });
+        const transfer = new response_js_1.Transfer(this.native, handle, () => { this.active.delete(transfer); this.notifier?.forget(handle); }, options.signal, duplex, this.notifier);
+        this.active.add(transfer);
+        try {
+            this.notifier?.track(handle);
+            transfer.attachSignal(timeouts.timeout_ms, started);
+            return { transfer, body, streaming };
+        }
+        catch (error) {
+            transfer.close();
+            throw error;
+        }
+    }
+    async stream(method, url, options = {}) {
+        await this.ready(options.signal);
+        const { transfer, body, streaming } = this.begin(method, url, options);
+        try {
+            const upload = streaming ? (0, upload_js_1.startUpload)(transfer, body) : undefined;
+            if (upload) {
+                this.producers.add(upload);
+                void upload.cleanup.then(() => this.producers.delete(upload), () => this.producers.delete(upload));
+            }
+            let info;
+            try {
+                info = await transfer.headers();
+                if (!transfer.duplex && upload && info.status < 300 && !info.upload_discarded && !upload.complete()) {
+                    throw new errors_js_1.FastlsError("server responded before upload finished; duplex streaming is not supported");
+                }
+            }
+            finally {
+                if (upload && (!transfer.duplex || !info || info.status >= 300)) {
+                    upload.stop();
+                    await upload.done;
+                }
+            }
+            transfer.ensureOpen();
+            return new response_js_1.StreamResponse(transfer, info, transfer.duplex ? upload : undefined);
+        }
+        catch (error) {
+            transfer.close();
+            throw error;
+        }
+    }
+    async sse(method, url, options = {}) {
+        const { maxEventBytes = 1024 * 1024, lastEventId, ...request } = options;
+        (0, sse_js_1.validateSSEOptions)(maxEventBytes, lastEventId);
+        const headers = mergeHeaders({ accept: "text/event-stream", "cache-control": "no-cache" }, request.headers);
+        if (lastEventId !== undefined)
+            headers["last-event-id"] = lastEventId;
+        const response = await this.stream(method, url, { ...request, headers });
+        try {
+            return new sse_js_1.SSEStream(response, maxEventBytes, lastEventId);
+        }
+        catch (error) {
+            await response.closeAsync();
+            throw error;
+        }
+    }
+    async request(method, url, options = {}) {
+        const stream = await this.stream(method, url, options);
+        try {
+            const content = await stream.read();
+            return new response_js_1.Response(stream.status, stream.headers, stream.match, content, stream.wireHeaders, stream.decoded, stream.httpVersion, stream.url, stream.trailers);
+        }
+        finally {
+            await stream.closeAsync();
+        }
+    }
+    /** Open a manual exchange; send() and response reads can run concurrently. */
+    duplex(method, url, options = {}) {
+        if (["body", "duplex", "json", "form", "files"].some(key => key in options))
+            throw new TypeError("manual duplex uses send() and finishUpload(), not body, json, form, files or duplex options");
+        this.ensureOpen();
+        const cancellation = new AbortController();
+        const signal = options.signal === undefined ? cancellation.signal : AbortSignal.any([options.signal, cancellation.signal]);
+        const transfer = this.ready(signal).then(() => {
+            if (cancellation.signal.aborted)
+                throw new errors_js_1.FastlsError("exchange is closed");
+            return this.begin(method, url, { ...options, signal, duplex: true }, true).transfer;
+        }, error => { if (cancellation.signal.aborted)
+            throw new errors_js_1.FastlsError("exchange is closed"); throw error; });
+        return new duplex_js_1.DuplexExchange(transfer, () => cancellation.abort());
+    }
+    get(url, options) { return this.request("GET", url, options); }
+    post(url, options) { return this.request("POST", url, options); }
+    async websocket(url, options = {}) {
+        await this.ready(options.signal);
+        this.ensureOpen();
+        if (options.signal?.aborted)
+            throw new errors_js_1.AbortError(undefined, { cause: options.signal.reason });
+        if (!this.native.websocketAvailable)
+            throw new errors_js_1.FastlsError("WebSocket requires a newer Fastls native library");
+        const cookieMode = options.cookieMode === undefined ? "session" : options.cookieMode;
+        if (cookieMode !== "session" && cookieMode !== "manual")
+            throw new TypeError("cookieMode must be session or manual");
+        const features = this.native.call("features");
+        const sessionCookies = features.includes("websocket_cookie_control_v1") || features.includes("websocket_cookies");
+        if (cookieMode === "manual" && !sessionCookies && features.includes("websocket_cookies_v1"))
+            throw new errors_js_1.FastlsError("This native library cannot disable automatic WebSocket cookies; a newer library with websocket_cookie_control_v1 is required");
+        if (cookieMode === "session" && !sessionCookies)
+            throw new errors_js_1.FastlsError("WebSocket session cookies require a newer Fastls native library; use cookieMode manual for legacy behavior");
+        const maximum = (options.maxMessageBytes === undefined ? 1048576 : options.maxMessageBytes);
+        if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 16777216)
+            throw new RangeError("maxMessageBytes must be 1..16777216");
+        const close = (0, websocket_js_1.wsBudget)((options.closeTimeoutMs === undefined ? 1000 : options.closeTimeoutMs), "closeTimeoutMs", 60000);
+        const headers = mergeHeaders(this.headers, options.headers), prepared = (0, request_options_js_1.prepare)(url, { params: options.params }, headers);
+        const proxy = proxyValue(options.proxy === undefined ? this.proxy : options.proxy);
+        const proxyCA = proxy?.toLowerCase().startsWith("https://") ? (options.proxyCaFile === undefined ? this.proxyCaPem : proxyTrust(options.proxyCaFile)) : undefined;
+        if (options.subprotocols !== undefined && (!Array.isArray(options.subprotocols) || options.subprotocols.some(p => typeof p !== "string")))
+            throw new TypeError("subprotocols must be an array of strings");
+        const handle = this.native.wsStart({ url: prepared.url, session: this.handle, disable_cookies: sessionCookies && cookieMode === "manual" ? true : undefined, headers, profile: options.profile ?? this.profile, proxy: proxy || undefined, ca_pem: this.caPem, proxy_ca_pem: proxyCA, subprotocols: options.subprotocols ?? [], max_message_bytes: maximum,
+            timeout_ms: (0, websocket_js_1.wsBudget)((options.handshakeTimeoutMs === undefined ? 30000 : options.handshakeTimeoutMs), "handshakeTimeoutMs"), read_timeout_ms: options.readTimeoutMs === null || options.readTimeoutMs === undefined ? 0 : (0, websocket_js_1.wsBudget)(options.readTimeoutMs, "readTimeoutMs"), write_timeout_ms: (0, websocket_js_1.wsBudget)((options.writeTimeoutMs === undefined ? 30000 : options.writeTimeoutMs), "writeTimeoutMs") });
+        const ws = new websocket_js_1.WebSocket(this.native, handle, () => { this.websockets.delete(ws); this.notifier?.forget(handle); }, maximum, close, this.notifier, options.signal);
+        this.websockets.add(ws);
+        try {
+            this.notifier?.track(handle);
+            return await ws.opened();
+        }
+        catch (error) {
+            ws.abort();
+            throw error;
+        }
+    }
+    listProfiles() { this.ensureOpen(); return this.native.call("profiles"); }
+    stats() { this.ensureOpen(); return this.native.call("stats"); }
+    closeIdleConnections() { this.ensureOpen(); this.native.call("session_close_idle", this.handle); }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            for (const transfer of this.active)
+                transfer.close(new errors_js_1.FastlsError("session is closed"));
+            for (const ws of this.websockets)
+                ws.abort(new errors_js_1.FastlsError("session is closed"));
+        }
+        finally {
+            try {
+                this.notifier?.close();
+            }
+            finally {
+                this.native.call("session_close", this.handle);
+            }
+        }
+    }
+    /** Release native resources immediately, then wait for cooperative upload cleanup. */
+    async closeAsync() {
+        const producers = [...this.producers];
+        this.close();
+        await this.notifier?.closeAsync();
+        const results = await Promise.allSettled(producers.map(task => task.cleanup));
+        for (const result of results)
+            if (result.status === "rejected")
+                throw result.reason;
+        for (const task of producers)
+            task.check();
+    }
+}
+exports.Session = Session;

package/dist/sse.d.ts

@@ -0,0 +1,52 @@
+import type { StreamResponse } from "./response.js";
+import type { RequestOptions } from "./session.js";
+export interface SSEOptions extends RequestOptions {
+    /** Separate limits for a raw line and accumulated UTF-8 data; defaults to 1 MiB. */
+    maxEventBytes?: number;
+    /** Sets Last-Event-ID and the parser's initial ID. Reconnection is manual. */
+    lastEventId?: string;
+}
+export declare class ServerSentEvent {
+    readonly data: string;
+    readonly event: string;
+    readonly id: string;
+    readonly retry?: number | undefined;
+    constructor(data: string, event?: string, id?: string, retry?: number | undefined);
+    json<T = unknown>(): T;
+}
+export declare function validateSSEOptions(maximum: number, initialId?: string): void;
+/** Internal pull parser. feed() pauses at each event, including within one chunk. */
+export declare class SSEDecoder {
+    private readonly maximum;
+    lastEventId: string;
+    retry?: number;
+    private id;
+    private blockRetry?;
+    private line;
+    private length;
+    private data;
+    private size;
+    private event;
+    private first;
+    private skipLF;
+    constructor(maximum: number, initialId?: string);
+    private append;
+    private processLine;
+    feed(chunk: Uint8Array): Generator<ServerSentEvent>;
+    finish(): void;
+}
+export declare class SSEStream implements AsyncIterable<ServerSentEvent> {
+    readonly response: StreamResponse;
+    private readonly decoder;
+    private started;
+    private closed;
+    constructor(response: StreamResponse, maximum?: number, initialId?: string);
+    get lastEventId(): string;
+    get retry(): number | undefined;
+    private checkOpen;
+    [Symbol.asyncIterator](): AsyncGenerator<ServerSentEvent>;
+    private events;
+    cancel(): void;
+    close(): void;
+    closeAsync(): Promise<void>;
+}

package/dist/sse.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSEStream = exports.SSEDecoder = exports.ServerSentEvent = void 0;
+exports.validateSSEOptions = validateSSEOptions;
+const promises_1 = require("node:timers/promises");
+const errors_js_1 = require("./errors.js");
+class ServerSentEvent {
+    data;
+    event;
+    id;
+    retry;
+    constructor(data, event = "message", id = "", retry) {
+        this.data = data;
+        this.event = event;
+        this.id = id;
+        this.retry = retry;
+        Object.freeze(this);
+    }
+    json() { return JSON.parse(this.data); }
+}
+exports.ServerSentEvent = ServerSentEvent;
+function validateSSEOptions(maximum, initialId) {
+    if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 64 * 1024 * 1024) {
+        throw new RangeError("maxEventBytes must be 1..67108864");
+    }
+    if (initialId !== undefined) {
+        if (typeof initialId !== "string")
+            throw new TypeError("lastEventId must be a string");
+        if (/[\0\r\n]/.test(initialId))
+            throw new TypeError("lastEventId must not contain NUL, CR or LF");
+        if (Buffer.byteLength(initialId) > maximum)
+            throw new RangeError("lastEventId exceeds maxEventBytes");
+    }
+}
+/** Internal pull parser. feed() pauses at each event, including within one chunk. */
+class SSEDecoder {
+    maximum;
+    lastEventId;
+    retry;
+    id;
+    blockRetry;
+    line = Buffer.alloc(0);
+    length = 0;
+    data = [];
+    size = 0;
+    event = "";
+    first = true;
+    skipLF = false;
+    constructor(maximum, initialId = "") {
+        this.maximum = maximum;
+        this.id = this.lastEventId = initialId;
+    }
+    append(part) {
+        const required = this.length + part.length;
+        if (required > this.maximum)
+            throw new errors_js_1.FastlsError("SSE line exceeds maxEventBytes");
+        if (required > this.line.length) {
+            const grown = Buffer.allocUnsafe(Math.min(this.maximum, Math.max(required, this.line.length * 2, 256)));
+            this.line.copy(grown, 0, 0, this.length);
+            this.line = grown;
+        }
+        this.line.set(part, this.length);
+        this.length = required;
+    }
+    processLine() {
+        let line = this.line.toString("utf8", 0, this.length);
+        this.length = 0;
+        if (this.first) {
+            if (line.startsWith("\ufeff"))
+                line = line.slice(1);
+            this.first = false;
+        }
+        if (line === "") {
+            this.lastEventId = this.id;
+            const event = this.data.length ? new ServerSentEvent(this.data.join("\n"), this.event || "message", this.id, this.blockRetry) : undefined;
+            this.data = [];
+            this.size = 0;
+            this.event = "";
+            this.blockRetry = undefined;
+            return event;
+        }
+        if (line.startsWith(":"))
+            return;
+        const colon = line.indexOf(":"), field = colon < 0 ? line : line.slice(0, colon);
+        let value = colon < 0 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "data") {
+            const size = this.size + Buffer.byteLength(value) + (this.data.length ? 1 : 0);
+            if (size > this.maximum)
+                throw new errors_js_1.FastlsError("SSE event exceeds maxEventBytes");
+            this.size = size;
+            this.data.push(value);
+        }
+        else if (field === "event")
+            this.event = value;
+        else if (field === "id" && !value.includes("\0"))
+            this.id = value;
+        else if (field === "retry" && /^[0-9]+$/.test(value)) {
+            const digits = value.replace(/^0+/, "") || "0", ceiling = "2147483647";
+            this.retry = this.blockRetry = digits.length > ceiling.length || (digits.length === ceiling.length && digits > ceiling) ? 2147483647 : Number(digits);
+        }
+    }
+    *feed(chunk) {
+        if (!chunk.length)
+            return;
+        let start = 0;
+        if (this.skipLF) {
+            if (chunk[0] === 10)
+                start = 1;
+            this.skipLF = false;
+        }
+        for (let i = start; i < chunk.length; i++) {
+            if (chunk[i] !== 10 && chunk[i] !== 13)
+                continue;
+            this.append(chunk.subarray(start, i));
+            const event = this.processLine();
+            if (chunk[i] === 13) {
+                if (chunk[i + 1] === 10)
+                    i++;
+                else if (i + 1 === chunk.length)
+                    this.skipLF = true;
+            }
+            start = i + 1;
+            if (event)
+                yield event;
+        }
+        this.append(chunk.subarray(start));
+    }
+    finish() {
+        this.line = Buffer.alloc(0);
+        this.length = 0;
+        this.data = [];
+        this.size = 0;
+        this.event = "";
+        this.id = this.lastEventId;
+    }
+}
+exports.SSEDecoder = SSEDecoder;
+class SSEStream {
+    response;
+    decoder;
+    started = false;
+    closed = false;
+    constructor(response, maximum = 1024 * 1024, initialId) {
+        this.response = response;
+        validateSSEOptions(maximum, initialId);
+        this.decoder = new SSEDecoder(maximum, initialId);
+        if (response.status === 204)
+            return;
+        if (response.status !== 200)
+            throw new errors_js_1.FastlsError(`SSE requires HTTP 200, received ${response.status}`);
+        const types = response.headers.getAll("content-type");
+        if (types.length !== 1 || types[0].split(";", 1)[0].replace(/^[ \t]+|[ \t]+$/g, "").toLowerCase() !== "text/event-stream") {
+            throw new errors_js_1.FastlsError("SSE requires Content-Type text/event-stream");
+        }
+        const encodings = response.wireHeaders.getAll("content-encoding").flatMap(value => value.split(",")).map(value => value.trim().toLowerCase());
+        if (!response.decoded && encodings.some(value => value !== "" && value !== "identity")) {
+            throw new errors_js_1.FastlsError("SSE requires decoded content; enable decodeContent");
+        }
+    }
+    get lastEventId() { return this.decoder.lastEventId; }
+    get retry() { return this.decoder.retry; }
+    checkOpen() {
+        if (this.closed)
+            throw new errors_js_1.FastlsError("SSE stream is closed or cancelled");
+        this.response.ensureOpen();
+    }
+    [Symbol.asyncIterator]() {
+        this.checkOpen();
+        if (this.started)
+            throw new errors_js_1.FastlsError("SSE stream permits only one consumer");
+        this.started = true;
+        return this.events();
+    }
+    async *events() {
+        try {
+            if (this.response.status === 204)
+                return;
+            for await (const chunk of this.response.body) {
+                for (const event of this.decoder.feed(chunk)) {
+                    this.checkOpen();
+                    yield event;
+                    // Even many events in one native read must let timers and cancellation run.
+                    await (0, promises_1.setImmediate)();
+                }
+            }
+        }
+        finally {
+            await this.closeAsync();
+        }
+    }
+    cancel() { this.closed = true; this.decoder.finish(); this.response.cancel(); }
+    close() { this.closed = true; this.decoder.finish(); this.response.close(); }
+    async closeAsync() { this.close(); await this.response.closeAsync(); }
+}
+exports.SSEStream = SSEStream;

package/dist/text.d.ts

@@ -0,0 +1,3 @@
+export declare function responseEncoding(contentType: string | undefined): string;
+export declare function decodeText(bytes: Uint8Array, encoding: string): string;
+export declare function decodeJSON(bytes: Buffer): string;