@kavo/sse 0.7.2

package/README.md

@@ -0,0 +1,131 @@
+# @kavo/sse
+
+The first `RealtimeTransport` implementation (`@kavo/core`, ADR-0023):
+plain HTTP `text/event-stream`, no client or server library required —
+SSE is one-directional, so there is no socket to open and nothing to
+depend on beyond Node's own `http` types.
+
+**May depend on:** `@kavo/core` only, no peer. **Never on:** `@kavo/nest`
+or any other framework — same rule `packages/orms/*` follows.
+
+## Usage
+
+```ts
+import { createTransport } from "@kavo/sse";
+import { createKavo } from "@kavo/core";
+
+// Filled in below, after `createCrud` — the callback only runs once a
+// subscribe request actually arrives, so the forward reference is fine.
+let bookService: ReturnType<typeof kavo.createCrud<Book>>;
+
+const sse = createTransport({
+  subscribableFields: (entityName) => (entityName === "Book" ? ["title", "status", "price"] : undefined),
+  // Enables subscribe-time filtering (issue #160) for an entity — omit an
+  // entry and a `filter[...]` query param on that entity is rejected with
+  // 400 rather than silently ignored. Typically `service.engine.metadata`/
+  // `service.engine.config` off the `createCrud` service already returned.
+  filterableEntities: (entityName) =>
+    entityName === "Book" ? { metadata: bookService.engine.metadata, config: bookService.engine.config } : undefined,
+});
+
+const kavo = createKavo({
+  infrastructure,
+  realtimeTransports: [sse],
+  defaults: {
+    realtime: { enabled: true, events: { created: true, updated: true, patched: true, deleted: true } },
+  },
+});
+
+bookService = kavo.createCrud(Book);
+```
+
+`@kavo/sse` has **no authentication of its own** — `handleRequest` accepts
+any subscribe request that otherwise validates. A deployment that needs to
+gate who may open a stream does so in front of it: a reverse proxy, or the
+host framework's own guard/middleware on the mounted route, since
+`handleRequest` is just an ordinary `(req, res)` handler.
+
+Mount `sse.handleRequest` on a plain Node HTTP route (or any host
+framework's request/response — Express, Nest, Fastify's raw
+req/res, … — since `IncomingMessage`/`ServerResponse` is what all of
+them extend or wrap):
+
+```ts
+http.createServer((req, res) => {
+  if (req.url?.startsWith("/realtime")) {
+    void sse.handleRequest(req, res);
+    return;
+  }
+  // ... the rest of the app's routing
+});
+```
+
+A client subscribes to one entity/id, or to the whole entity, with
+`EventSource` (or any HTTP client that reads a chunked `text/event-stream`
+body):
+
+```js
+// Item channel: every event for Book id 42.
+const one = new EventSource("/realtime?channel=Book.42");
+
+// Collection channel: every event for every Book (issue #160).
+const all = new EventSource("/realtime?channel=Book");
+
+// Collection channel, scoped with the same filter grammar REST uses.
+const published = new EventSource("/realtime?channel=Book&filter[status][eq]=published");
+
+all.addEventListener("updated", (message) => {
+  const event = JSON.parse(message.data); // RealtimeEventDto
+});
+```
+
+`channel` is required: `<entity>.<id>` for an item-level subscription, or
+the bare `<entity>` for a collection-level one (every event for that
+entity). A collection-channel subscribe request may add a `filter` query
+string in the exact `filter[field][operator]=value` grammar REST list
+requests use (doc 18) — evaluated in memory per event, no DB round trip.
+Filtering is opt-in per entity via `filterableEntities`; an entity with no
+entry there rejects any `filter[...]` param with `400` rather than
+silently ignoring it. See doc 18 §4.3 for what a filtered subscriber
+receives when a write moves a row across the filter boundary, and for the
+unconditional `"deleted"`-event bypass.
+
+Once `subscribableFields` is configured for an entity, it bounds every
+outgoing `item` **unconditionally** — not only when a subscriber names
+`fields` — the same way `allowlists.selectable`
+bounds a REST response whether or not the caller asked for a subset. An
+optional `fields` query param (comma-separated) narrows further within
+that bound; a field outside it (or outside `subscribableFields`, when no
+`fields` param is given) gets a `400` the same way `allowlists.selectable`
+rejects an unlisted field over REST.
+
+A connection that cannot keep up with its publish rate (the writable
+buffer on its response exceeds `bufferLimitBytes`, default 64 KiB) is
+closed rather than left to block delivery to every other subscriber.
+
+## Known limitations
+
+- **No resume-on-reconnect.** Every SSE frame carries an `id:`, but
+  nothing reads `Last-Event-ID` yet — a dropped connection means missed
+  events, not replayed ones. This matters more for SSE than it will for
+  `@kavo/websocket`: browsers' native `EventSource` **auto-reconnects by
+  default** on a dropped connection, with no application code asking for
+  it, so a client silently starts receiving only new events after a gap it
+  never signaled. Building resume via the `since` cursor is a future issue.
+- **No multi-node fan-out.** The channel registry is one process's
+  in-memory `Map` — a subscriber connected to one instance of a
+  horizontally-scaled app never sees a write handled by another instance.
+- **No "leave" event on an ordinary write.** A write that makes a row stop
+  matching a filtered subscriber's filter is not delivered at all — only a
+  genuine `"deleted"` reliably tells that subscriber a row is gone. See
+  doc 18 §4.3.
+- **No filtering by which fields changed** — a subscribe-time filter
+  matches row data (`RealtimeEventDto.item`), not the write's diff
+  (`RealtimeEventDto.changed`).
+- **No authentication or authorization.** `@kavo/sse` accepts any subscribe
+  request that otherwise validates — gating who may open a stream is the
+  host app's job (a reverse proxy, or a guard on the mounted route), and
+  row/tenant-level subscriber scoping is a future issue (`authorize`, out
+  of scope here — see `RealtimeTransport`'s own doc). A `filter` narrows
+  _which_ events a subscriber receives, not _whether_ they were authorized
+  to receive them.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createTransport, type FilterableEntity, type SseTransport, type SseTransportOptions, } from "./sse-transport.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createTransport, } from "./sse-transport.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,GAIhB,MAAM,oBAAoB,CAAC"}

package/dist/sse-transport.d.ts

@@ -0,0 +1,99 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { EntityMetadata, RealtimeFieldSelector, RealtimeTransport, ResolvedEntityConfig } from "@kavo/core";
+/**
+ * What a subscribe request needs to parse and validate a `filter` query
+ * string for one entity — the same two pieces `DefaultFilterParser` and
+ * `Filter.parse` already need for REST: `metadata` for column-kind-aware
+ * value coercion, `config` for the `filterable` allowlist and the
+ * `query.maxFilterDepth`/`maxInValues` limits. `@kavo/sse` has no config
+ * resolution of its own (same reason `subscribableFields` is a callback,
+ * not a lookup this package performs itself), so the host app supplies
+ * both — typically `service.engine.metadata`/`service.engine.config` off
+ * the `DefaultKavoService` `createCrud` already returned for that entity.
+ * That property is concretely typed per entity (`ResolvedEntityConfig<
+ * Book>`), while this interface — serving every entity through one
+ * callback — is not; assigning the former to the latter needs the same
+ * erasure cast `kavo.ts`'s own `catalog.register` already uses internally
+ * (`config as unknown as ResolvedEntityConfig`), not a sign of a type
+ * mismatch.
+ */
+export interface FilterableEntity {
+    readonly metadata: EntityMetadata;
+    readonly config: ResolvedEntityConfig;
+}
+/**
+ * What `handleRequest` needs to scope one subscription. `@kavo/sse` has no
+ * authentication of its own — every subscribe request that otherwise
+ * validates is accepted. A deployment that needs to gate who may open a
+ * stream does so in front of `handleRequest` (a reverse proxy, a host
+ * framework's own guard/middleware on the mounted route, …) — see
+ * `RealtimeTransport`'s doc comment on why subscriber-level access control
+ * is out of this seam entirely.
+ */
+export interface SseTransportOptions {
+    /**
+     * Per-entity `RealtimeSettings.subscribableFields`, the same allowlist an
+     * app already configured via `createCrud` — this package has no config
+     * resolution of its own, so the caller supplies the lookup. A request
+     * naming a `fields` query param outside the allowlist is rejected with
+     * `400` before the stream opens, the same way `allowlists.selectable`
+     * rejects an unlisted field over REST. Returning `undefined` (including
+     * when the callback itself is omitted) means no allowlist is configured
+     * for that entity, so any requested field is accepted.
+     *
+     * Once configured, this allowlist is also enforced **unconditionally** on
+     * every outgoing `item` for that entity — not only when a subscriber
+     * names `fields` — the same way `allowlists.selectable` bounds a REST
+     * response whether or not the caller asked for a subset. A `fields`
+     * query param narrows further *within* that bound; it can never widen
+     * past it.
+     */
+    subscribableFields?(entityName: string): RealtimeFieldSelector | undefined;
+    /**
+     * Enables subscribe-time filtering (`filter[field][operator]=value`,
+     * issue #160) for one entity. Returning `undefined` (including when the
+     * callback itself is omitted) means that entity does not support
+     * subscribe-time filtering — a request naming any `filter[...]`/`filter`
+     * query param for it is rejected with `400` before the stream opens,
+     * rather than silently ignoring the filter and delivering everything.
+     */
+    filterableEntities?(entityName: string): FilterableEntity | undefined;
+    /** See `DEFAULT_BUFFER_LIMIT_BYTES`. */
+    bufferLimitBytes?: number;
+}
+/** A `RealtimeTransport` plus the HTTP entry point a host wires a route to. */
+export interface SseTransport extends RealtimeTransport {
+    /**
+     * Handles one incoming SSE subscribe request:
+     * `GET ?channel=<entity>.<id>` (item channel) or `GET ?channel=<entity>`
+     * (collection channel, issue #160) with `Accept: text/event-stream`.
+     * Host-framework-agnostic — takes Node's own
+     * `IncomingMessage`/`ServerResponse`, which every Node HTTP framework's
+     * request/response either extends or wraps directly. Resolves once the
+     * response is settled (an error status was written, or the stream was
+     * opened) — the connection itself then lives for as long as the client
+     * keeps it open, torn down by the request's own `close`.
+     */
+    handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /** Number of currently open subscriptions, across every channel. */
+    readonly connectionCount: number;
+    /** Ends every open connection and forgets them. For graceful shutdown and tests. */
+    close(): void;
+}
+/**
+ * The first real `RealtimeTransport` implementation (issue #155, over the
+ * seam #154 added; issue #160 / ADR-0024 added collection and filtered subscriptions):
+ * plain HTTP `text/event-stream`, no client or server library required.
+ * The channel a connection opens is either the item-level `<entity>.<id>`
+ * string `RealtimeEventDto.channel` carries, or the bare `<entity>` name
+ * (`RealtimeEventDto.entity`) for every event on that entity — `publish`
+ * fans an event out to every connection registered under either string, so
+ * one write reaches both an item-level and a collection-level subscriber
+ * from the same call.
+ *
+ * One process, one in-memory channel registry: a subscriber connected to
+ * this instance never sees a write handled by another instance of a
+ * horizontally-scaled app (see the package README's "Known limitations").
+ */
+export declare function createTransport(options: SseTransportOptions): SseTransport;
+//# sourceMappingURL=sse-transport.d.ts.map

package/dist/sse-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-transport.d.ts","sourceRoot":"","sources":["../src/sse-transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EACV,cAAc,EAId,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAcpB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;;;OAgBG;IACH,kBAAkB,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAC;IAC3E;;;;;;;OAOG;IACH,kBAAkB,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACtE,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAa,SAAQ,iBAAiB;IACrD;;;;;;;;;;OAUG;IACH,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,oEAAoE;IACpE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,oFAAoF;IACpF,KAAK,IAAI,IAAI,CAAC;CACf;AA0HD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAiM1E"}

package/dist/sse-transport.js

@@ -0,0 +1,315 @@
+import { DefaultFilterParser, QueryValidationException, evaluateFilter } from "@kavo/core";
+/**
+ * Bytes buffered in a connection's underlying socket before it is dropped
+ * rather than blocking `publish` for every other subscriber. `res.
+ * writableLength` (Node's `http.ServerResponse` is a `stream.Writable`) is
+ * the amount queued but not yet flushed to the OS — a slow reader grows
+ * this, a healthy one keeps it near zero. 64 KiB is generous for
+ * `RealtimeEventDto`-sized JSON frames while still catching a genuinely
+ * stuck client quickly.
+ */
+const DEFAULT_BUFFER_LIMIT_BYTES = 64 * 1024;
+/**
+ * Same array-or-`exclude` semantics `resolveFieldSelector` (core,
+ * internal) applies for REST's `selectable`/`filterable`/`sortable` — but
+ * with no "base" field list to fall back on, because `RealtimeFieldSelector`
+ * carries none (`settings.ts`'s own doc on why: this schema has no `Entity`
+ * type parameter to check a field name against). An explicit array is a
+ * positive allowlist; `{ exclude }` is checked negatively instead — "not
+ * excluded" rather than "in some base set minus excluded" — since there is
+ * no base set here to subtract from.
+ */
+function isFieldAllowed(selector, field) {
+    if (selector === undefined)
+        return true;
+    // `"exclude" in selector`, not `Array.isArray` — `Array.isArray`'s guard is
+    // `arg is any[]`, and a `readonly string[]` is not assignable to `any[]`,
+    // so it fails to narrow the union in the negative branch. Same reason
+    // core's own `resolveFieldSelector` (resolve-entity-config.ts) checks it
+    // this way.
+    if ("exclude" in selector)
+        return !selector.exclude.includes(field);
+    return selector.includes(field);
+}
+/**
+ * Bounds an outgoing `item` to `selector` (unconditional, once configured)
+ * and then further to `fields` (a subscriber-requested subset, already
+ * validated ⊆ the allowlist at subscribe time). `undefined` for both means
+ * no narrowing — the item is delivered whole, today's behavior for an
+ * entity that never configured `subscribableFields`.
+ */
+function narrowItem(item, selector, fields) {
+    if (item === null || typeof item !== "object")
+        return item;
+    const record = item;
+    let allowed;
+    if (fields !== undefined) {
+        allowed = fields;
+    }
+    else if (selector !== undefined) {
+        const keys = Object.keys(record);
+        allowed = "exclude" in selector ? keys.filter((key) => !selector.exclude.includes(key)) : selector;
+    }
+    else {
+        return item;
+    }
+    const narrowed = {};
+    for (const key of allowed)
+        if (key in record)
+            narrowed[key] = record[key];
+    return narrowed;
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(payload) });
+    res.end(payload);
+}
+/**
+ * `id:` set even though nothing consumes it yet (resume-on-reconnect is a
+ * future issue) — a monotonically increasing counter, shared across every
+ * channel on this transport instance, so it stays meaningful the day resume
+ * is built instead of forcing a wire-format change then. Allocated once per
+ * `publish` call (not once per connection/frame) so every subscriber of one
+ * logical write sees the same `id:`, even though the `data:` they receive
+ * may differ once field-narrowing is applied.
+ */
+function frame(id, event) {
+    return `id: ${id}\nevent: ${event.event}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+/**
+ * Every `filter[...]`/`filter` query param, flattened the way
+ * `DefaultFilterParser` expects: one entry per literal key, repeated keys
+ * (the `filter[status][in][]=a&filter[status][in][]=b` form) collapsed
+ * into one array value under that key. Every other query param
+ * (`channel`, `fields`, …) rides along harmlessly — the parser only ever
+ * reads keys starting with `filter[` or the bare `filter` key.
+ */
+function collectRawParams(searchParams) {
+    const raw = {};
+    for (const key of new Set(searchParams.keys())) {
+        const values = searchParams.getAll(key);
+        raw[key] = values.length > 1 ? values : values[0];
+    }
+    return raw;
+}
+function hasFilterParams(searchParams) {
+    for (const key of searchParams.keys()) {
+        if (key === "filter" || key.startsWith("filter["))
+            return true;
+    }
+    return false;
+}
+/** Every field name a condition in `expression` compares against, deduplicated. */
+function collectConditionFields(expression) {
+    const fields = new Set();
+    const visit = (node) => {
+        if (node.kind === "condition") {
+            fields.add(node.field);
+            return;
+        }
+        for (const child of node.children)
+            visit(child);
+    };
+    visit(expression);
+    return [...fields];
+}
+/**
+ * The first real `RealtimeTransport` implementation (issue #155, over the
+ * seam #154 added; issue #160 / ADR-0024 added collection and filtered subscriptions):
+ * plain HTTP `text/event-stream`, no client or server library required.
+ * The channel a connection opens is either the item-level `<entity>.<id>`
+ * string `RealtimeEventDto.channel` carries, or the bare `<entity>` name
+ * (`RealtimeEventDto.entity`) for every event on that entity — `publish`
+ * fans an event out to every connection registered under either string, so
+ * one write reaches both an item-level and a collection-level subscriber
+ * from the same call.
+ *
+ * One process, one in-memory channel registry: a subscriber connected to
+ * this instance never sees a write handled by another instance of a
+ * horizontally-scaled app (see the package README's "Known limitations").
+ */
+export function createTransport(options) {
+    const bufferLimitBytes = options.bufferLimitBytes ?? DEFAULT_BUFFER_LIMIT_BYTES;
+    const channels = new Map();
+    let nextEventId = 1;
+    function subscribe(connection) {
+        let subscribers = channels.get(connection.channel);
+        if (!subscribers) {
+            subscribers = new Set();
+            channels.set(connection.channel, subscribers);
+        }
+        subscribers.add(connection);
+    }
+    function unsubscribe(connection) {
+        const subscribers = channels.get(connection.channel);
+        if (!subscribers)
+            return;
+        subscribers.delete(connection);
+        if (subscribers.size === 0)
+            channels.delete(connection.channel);
+    }
+    /**
+     * `"deleted"` bypasses the filter unconditionally — `event.item` is
+     * `null`, so there is nothing to evaluate, and the alternative (silently
+     * excluding it) leaves a filtered subscriber with a row in its view that
+     * is permanently gone. See `RealtimeTransport`'s doc for the
+     * confidentiality tradeoff this implies. Every other event id evaluates
+     * normally: a write that makes a row start matching a filter is
+     * delivered as whatever its real event id is (`"entering" a filtered
+     * view reuses the ordinary event, not a synthesized `"created"`); a
+     * write that makes it stop matching simply is not delivered — there is
+     * no before-image available to detect that transition without an extra
+     * read the engine does not already do, so it is a documented limitation
+     * rather than a silently-wrong "leave" event.
+     */
+    function matches(connection, event) {
+        if (event.event === "deleted")
+            return true;
+        return evaluateFilter(connection.filter, (event.item ?? {}));
+    }
+    function deliverTo(subscribers, event, id) {
+        if (!subscribers || subscribers.size === 0)
+            return;
+        // Direct `for...of` over the live `Set`, not a snapshot copy: deleting
+        // the current entry mid-iteration (the `unsubscribe` below, for a
+        // connection that can't keep up) is well-defined under the Set
+        // iteration protocol — already-visited and about-to-be-visited
+        // entries are unaffected.
+        for (const connection of subscribers) {
+            if (!matches(connection, event))
+                continue;
+            if (connection.res.writableLength > bufferLimitBytes) {
+                // Can't keep up: dropped rather than left to block publish to
+                // every other subscriber of this channel.
+                unsubscribe(connection);
+                connection.res.end();
+                continue;
+            }
+            const outgoing = {
+                ...event,
+                item: (narrowItem(event.item, connection.selector, connection.fields) ?? null),
+            };
+            connection.res.write(frame(id, outgoing));
+        }
+    }
+    return {
+        name: "sse",
+        get connectionCount() {
+            let total = 0;
+            for (const subscribers of channels.values())
+                total += subscribers.size;
+            return total;
+        },
+        async publish(event) {
+            const itemSubscribers = channels.get(event.channel);
+            const collectionSubscribers = channels.get(event.entity);
+            if ((!itemSubscribers || itemSubscribers.size === 0) &&
+                (!collectionSubscribers || collectionSubscribers.size === 0)) {
+                return;
+            }
+            // Allocated once per publish, not once per connection — every
+            // subscriber of one logical write shares the same `id:` even though
+            // the `data:` they receive may differ (field narrowing).
+            const id = nextEventId++;
+            deliverTo(itemSubscribers, event, id);
+            deliverTo(collectionSubscribers, event, id);
+        },
+        async handleRequest(req, res) {
+            if (req.method !== "GET") {
+                sendJson(res, 400, { error: "SSE subscription requires GET" });
+                return;
+            }
+            const accept = req.headers.accept;
+            if (typeof accept !== "string" || !accept.includes("text/event-stream")) {
+                sendJson(res, 400, { error: "requires 'Accept: text/event-stream'" });
+                return;
+            }
+            const url = new URL(req.url ?? "", "http://kavo.invalid");
+            const channel = url.searchParams.get("channel");
+            if (!channel) {
+                sendJson(res, 400, {
+                    error: "a 'channel' query parameter of the form '<entity>' or '<entity>.<id>' is required",
+                });
+                return;
+            }
+            const dot = channel.indexOf(".");
+            if (dot === 0 || dot === channel.length - 1) {
+                sendJson(res, 400, {
+                    error: "a 'channel' query parameter of the form '<entity>' or '<entity>.<id>' is required",
+                });
+                return;
+            }
+            const entityName = dot === -1 ? channel : channel.slice(0, dot);
+            const selector = options.subscribableFields?.(entityName);
+            const fieldsParam = url.searchParams.get("fields");
+            let fields;
+            if (fieldsParam !== null) {
+                const requested = fieldsParam
+                    .split(",")
+                    .map((field) => field.trim())
+                    .filter((field) => field.length > 0);
+                const disallowed = requested.filter((field) => !isFieldAllowed(selector, field));
+                if (disallowed.length > 0) {
+                    sendJson(res, 400, { error: `field(s) not subscribable: ${disallowed.join(", ")}` });
+                    return;
+                }
+                fields = requested;
+            }
+            let filter = null;
+            if (hasFilterParams(url.searchParams)) {
+                const filterable = options.filterableEntities?.(entityName);
+                if (filterable === undefined) {
+                    sendJson(res, 400, { error: `entity '${entityName}' does not support subscribe-time filtering` });
+                    return;
+                }
+                const parser = new DefaultFilterParser(filterable.metadata);
+                let parsed;
+                try {
+                    parsed = parser.parse(collectRawParams(url.searchParams), filterable.config);
+                }
+                catch (error) {
+                    if (error instanceof QueryValidationException) {
+                        sendJson(res, 400, { error: "invalid filter", issues: error.issues });
+                        return;
+                    }
+                    throw error;
+                }
+                filter = parsed.root;
+                if (filter !== null) {
+                    const knownFields = new Set(filterable.metadata.fields.map((field) => field.name));
+                    const conditionFields = collectConditionFields(filter);
+                    const unevaluable = conditionFields.find((field) => !knownFields.has(field));
+                    if (unevaluable !== undefined) {
+                        sendJson(res, 400, {
+                            error: `filter field '${unevaluable}' cannot be evaluated for a realtime subscription (relation and computed fields are not supported — only the entity's own columns)`,
+                        });
+                        return;
+                    }
+                    const disallowed = conditionFields.filter((field) => !isFieldAllowed(selector, field));
+                    if (disallowed.length > 0) {
+                        sendJson(res, 400, { error: `filter field(s) not subscribable: ${disallowed.join(", ")}` });
+                        return;
+                    }
+                }
+            }
+            res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+            });
+            res.flushHeaders();
+            const connection = { res, channel, entityName, filter, fields, selector };
+            subscribe(connection);
+            req.on("close", () => unsubscribe(connection));
+            res.on("error", () => unsubscribe(connection));
+        },
+        close() {
+            for (const subscribers of channels.values()) {
+                for (const connection of subscribers)
+                    connection.res.end();
+            }
+            channels.clear();
+        },
+    };
+}
+//# sourceMappingURL=sse-transport.js.map

package/dist/sse-transport.js.map

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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@kavo/sse",
+  "version": "0.7.2",
+  "description": "Kavo SSE realtime transport — implements @kavo/core's RealtimeTransport over Server-Sent Events, plain HTTP with no required peer library.",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kavo-labs/kavo.git",
+    "directory": "packages/realtime/sse"
+  },
+  "homepage": "https://github.com/kavo-labs/kavo/tree/main/packages/realtime/sse#readme",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@kavo/core": "workspace:^"
+  }
+}