@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.5

package/dist/core/http/sse.d.ts

@@ -0,0 +1,284 @@
+/**
+ * A fetch-based Server-Sent Events client.
+ *
+ * Issue #127, epic #109.
+ *
+ * =============================================================================
+ * WHY THIS FILE EXISTS AT ALL — `EventSource` CANNOT SEND AN AUTHORIZATION HEADER
+ * =============================================================================
+ *
+ * `GET /api/notifications/stream` is guarded by the ordinary bearer `@Auth()`,
+ * exactly like every other endpoint. The native `EventSource` constructor takes
+ * a URL and `withCredentials`, and NOTHING ELSE — there is no headers argument
+ * and no way to add one. So the browser's built-in SSE client cannot
+ * authenticate against that route.
+ *
+ * The two ways out, and why this is the one taken:
+ *
+ *   1. REJECTED — `?token=…` on the stream URL. The API refused this
+ *      deliberately (see the long note on `NotificationsController.stream`), and
+ *      the refusal is right: a URL query string is written verbatim into the
+ *      nginx access log, kept in browser history, and forwarded in `Referer` to
+ *      any third party the page later touches. That turns a live bearer
+ *      credential into something replayable out of a log file retained for
+ *      months and readable by people who are not supposed to hold sessions.
+ *      Cheap transport is not worth credentials in logs.
+ *
+ *   2. CHOSEN — `fetch()` with a real `Authorization` header, reading
+ *      `response.body` as a `ReadableStream` and parsing the SSE framing here.
+ *      `fetch` takes arbitrary headers; the cost is that everything
+ *      `EventSource` does for free — framing, reconnection, backoff — has to be
+ *      written, which is what the rest of this file is.
+ *
+ * WHY HAND-ROLLED RATHER THAN A DEPENDENCY (`@microsoft/fetch-event-source`).
+ * This worktree cannot take a new dependency, and on inspection it does not
+ * need one: the whole client is the parser below plus a retry loop, both of
+ * which are small, fully testable without a network, and — unlike a
+ * dependency — able to reuse the `PlatformHttpClient` token and refresh
+ * machinery directly rather than through a callback shim. A library would also
+ * bring its own opinions about 401 handling, which is precisely the part that
+ * has to match `core/http/client.ts` exactly.
+ *
+ * =============================================================================
+ * WHAT THIS CLIENT DOES NOT DO, AND MUST NOT BE MADE TO DO
+ * =============================================================================
+ *
+ * IT DOES NOT GUARANTEE DELIVERY. Anything the server publishes while this
+ * connection is down is GONE: the API holds no buffer, honours no
+ * `Last-Event-ID`, and has no replay log (`NotificationStreamService`'s header
+ * says so in as many words). This client therefore reports every (re)connection
+ * through `onOpen`, and ITS CALLER IS REQUIRED TO REFETCH on that signal. Do
+ * not add replay here; the `notifications` table is the source of truth and one
+ * indexed query after a gap is strictly more reliable than any cursor built on
+ * top of a stream.
+ *
+ * `lastEventId` is parsed and tracked because the SSE grammar has the field and
+ * a parser that silently dropped it would be wrong — but it is NOT sent back as
+ * `Last-Event-ID` on reconnect, because the server does not implement it and a
+ * header that looks like resumption but resumes nothing is worse than no header
+ * at all.
+ */
+/**
+ * One dispatched SSE event.
+ *
+ * @stability experimental
+ */
+export interface SseFrame {
+    /**
+     * The `event:` name, or `'message'` when the frame declared none.
+     *
+     * Defaulted here rather than left `undefined` so a consumer switching on the
+     * name never has to spell the default itself. The API always names its
+     * frames (`notification`), so a `'message'` arriving is a signal that
+     * something upstream changed.
+     */
+    event: string;
+    /**
+     * The `data:` payload, with multiple `data:` lines joined by `\n` and the
+     * trailing newline removed, per the SSE grammar.
+     */
+    data: string;
+    /** The `id:` field of this frame, or `null`. Tracked, never sent back. */
+    id: string | null;
+}
+/**
+ * An incremental SSE stream parser.
+ *
+ * Fed decoded text in arbitrary chunks — a network read boundary can land
+ * anywhere, including in the middle of a UTF-8 sequence, in the middle of a
+ * field name, or between the CR and LF of one line terminator — and emits whole
+ * frames only. Every one of those splits is a real thing that happens under
+ * load and each has its own comment below.
+ *
+ * Deliberately a plain class with no I/O so the framing rules can be tested by
+ * calling a method with a string.
+ *
+ * @stability experimental
+ */
+export declare class SseParser {
+    /** Bytes seen but not yet terminated by a line ending. */
+    private buffer;
+    /** The event-type buffer, per spec: reset to '' after every dispatch. */
+    private eventType;
+    /** The data buffer, per spec: accumulated across `data:` lines. */
+    private data;
+    /** This frame's `id:`, distinct from `lastEventId` below. */
+    private frameId;
+    /**
+     * The last non-null `id:` seen on the stream.
+     *
+     * Public because it is genuinely part of the stream's state, and read by
+     * nothing today — see the header on why it is not sent back.
+     */
+    lastEventId: string | null;
+    /**
+     * The server's most recent `retry:` directive, in milliseconds, or `null`.
+     *
+     * A STREAM-LEVEL directive, not a per-frame one: it sets the reconnection
+     * delay for every subsequent reconnect until the server says otherwise, which
+     * is why it lives on the parser rather than on `SseFrame`. This API never
+     * sends one; it is honoured anyway because ignoring a server that asks to be
+     * reconnected to more slowly is how a client turns a struggling backend into
+     * a hammered one.
+     */
+    retryMs: number | null;
+    /**
+     * Feed one decoded chunk; get back every frame it completed.
+     *
+     * @param chunk - decoded text. MUST come from a streaming decoder — see
+     *        `TextDecoder({ stream: true })` at the call site. Decoding each
+     *        network chunk independently corrupts any multi-byte character that
+     *        straddles a chunk boundary, which for this API means a notification
+     *        body with an accent or an emoji in it arrives mangled roughly
+     *        whenever it is unlucky about packet size.
+     */
+    push(chunk: string): SseFrame[];
+    private handleLine;
+    private dispatch;
+}
+/**
+ * What the connection is doing right now, for the UI to render honestly.
+ *
+ * `'reconnecting'` is deliberately distinct from `'connecting'`: the first
+ * connection attempt and a recovery after a drop look identical to the network
+ * stack but not to a user, who has already seen the feature working once.
+ *
+ * @stability experimental
+ */
+export type SseState = 'connecting' | 'open' | 'reconnecting' | 'closed';
+/**
+ * Options for {@link connectSse}.
+ *
+ * @stability experimental
+ */
+export interface SseOptions {
+    /** Absolute or root-relative URL of the event stream. */
+    url: string;
+    /**
+     * The `Authorization` header value for the NEXT attempt, or `null` for none.
+     *
+     * A FUNCTION, called fresh on every attempt, not a captured string. Access
+     * tokens are 15 minutes and this connection is meant to outlive many of them;
+     * a value read once at setup would be stale on exactly the reconnect that
+     * follows a long sleep — the moment reconnection matters most.
+     */
+    authorization: () => string | null;
+    /**
+     * The stream returned 401. Renew credentials and return whether it worked.
+     *
+     * Returning `false` STOPS the loop permanently — the session is gone, and a
+     * client that kept retrying would spend the rest of the tab's life issuing
+     * 401s at a logged-out backend.
+     */
+    reauthenticate: () => Promise<boolean>;
+    /**
+     * The stream is open and its headers have arrived.
+     *
+     * ⚠️ FIRES ON EVERY CONNECTION, INCLUDING EVERY RECONNECT, AND THE CALLER MUST
+     * REFETCH ON IT. See this file's header: nothing published during the gap is
+     * replayed, so this callback is the only thing standing between a dropped
+     * connection and a permanently stale unread count.
+     */
+    onOpen: () => void;
+    /** One dispatched frame. Heartbeat comments never reach here. */
+    onFrame: (frame: SseFrame) => void;
+    /** Connection state transitions, for rendering. Optional. */
+    onStateChange?: (state: SseState) => void;
+}
+/**
+ * A live connection. Idempotent `close()`.
+ *
+ * @stability experimental
+ */
+export interface SseConnection {
+    /** Close the connection for good; safe to call more than once. */
+    close: () => void;
+}
+/**
+ * Open an SSE connection and keep it open, reconnecting with backoff until
+ * `close()` is called.
+ *
+ * Returns synchronously; the connection is established in the background. The
+ * returned `close()` aborts an in-flight request, cancels a pending retry, and
+ * detaches every listener — it is what an effect cleanup calls, and it must
+ * remain safe to call at any point in the lifecycle, including before the first
+ * fetch has resolved.
+ *
+ * @stability experimental
+ */
+export declare function connectSse(options: SseOptions): SseConnection;
+/**
+ * Options for {@link postSse}.
+ *
+ * @stability experimental
+ */
+export interface PostSseOptions<T> {
+    /** Absolute or base-relative URL — resolve it against `API_BASE_URL`. */
+    url: string;
+    /** JSON-serialised as the request body. */
+    body: unknown;
+    /** The full `Authorization` header value (`Bearer …`), or null for none. */
+    authorization: () => string | null;
+    /** Renew the access token after a 401. Called at most once per request. */
+    reauthenticate: () => Promise<unknown>;
+    /**
+     * One parsed frame: its `event:` name and its `data:` parsed as JSON (the raw
+     * string when it is not JSON). Comment lines (`: ping`) never arrive here.
+     */
+    onFrame: (event: string, data: T) => void;
+    /** Aborting resolves the promise quietly — cancelling is not an error. */
+    signal?: AbortSignal;
+    /**
+     * Called with every non-2xx response's status and parsed JSON error body,
+     * before the {@link ApiError} is thrown (the error is thrown either way). The
+     * same side channel as `PlatformHttpClientOptions.onErrorResponse`: the
+     * reference app notices a maintenance window here.
+     */
+    onErrorResponse?: (status: number, body: PostSseErrorBody) => void;
+}
+/**
+ * The JSON error envelope `postSse` parses off a non-2xx response.
+ *
+ * @stability experimental
+ */
+export interface PostSseErrorBody {
+    /** The API's message. */
+    message?: string;
+    /** The API's machine-readable error code. */
+    code?: string;
+    /** The error envelope's `details`. */
+    details?: unknown;
+}
+/**
+ * POST a JSON body and stream the `text/event-stream` answer, frame by frame.
+ *
+ * `connectSse` above is the wrong tool for a request/response stream and is
+ * deliberately left alone: it is GET-only, and it RECONNECTS — right for a
+ * notification feed that should live as long as the tab, exactly wrong for
+ * "generate one answer to this prompt", where a reconnect would re-submit the
+ * prompt and bill the user twice. So this is the other shape:
+ *
+ * - ONE request. No reconnect, ever. The promise resolves when the server ends
+ *   the stream.
+ * - ONE 401 retry, through `reauthenticate` — the same single refresh-and-retry
+ *   `PlatformHttpClient.request` does, so an access token that expired just before the
+ *   click does not surface as an error. A second 401 rejects.
+ * - A NON-2xx REJECTS WITH `ApiError`, the error every other call site already
+ *   catches, with `code`/`details` parsed from the JSON error body. The server
+ *   runs every gate (AI disabled, no key, model not enabled) BEFORE the first
+ *   byte precisely so those failures arrive here as ordinary JSON errors; a
+ *   failure AFTER streaming began arrives as a frame (`event: error`) instead,
+ *   and is the caller's to handle. Every non-2xx is handed to `onErrorResponse` on the
+ *   way past (the app's maintenance recogniser), exactly as the HTTP
+ *   client's `toError` does.
+ * - ABORT RESOLVES. A caller that aborts (a Stop button, an unmount) asked for
+ *   the stream to end; rejecting would make every such caller write a catch
+ *   that ignores `AbortError`.
+ *
+ * Same parser as `connectSse` (`SseParser`), same credential posture (a real
+ * `Authorization` header, never a token in the URL — see this file's header).
+ *
+ * @stability experimental
+ */
+export declare function postSse<T>(options: PostSseOptions<T>): Promise<void>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/core/http/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../src/core/http/sse.ts"],"names":[],"mappings":"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"}