void 0.7.3 → 0.7.4

package/dist/runtime/sse.mjs

@@ -0,0 +1,172 @@
+//#region src/runtime/sse.ts
+const DEFAULT_KEEP_ALIVE_INTERVAL_MS = 15e3;
+const DEFAULT_KEEP_ALIVE_COMMENT = "keep-alive";
+var SseStreamClosedError = class extends Error {
+	constructor(message = "sse: stream is closed.") {
+		super(message);
+		this.name = "SseStreamClosedError";
+	}
+};
+function formatSse(message) {
+	const textMessage = {
+		event: message.event,
+		id: message.id,
+		retry: message.retry
+	};
+	if ("data" in message) textMessage.data = serializeData(message.data);
+	return formatSseText(textMessage);
+}
+function formatSseText(message) {
+	const lines = [];
+	if (message.id != null) {
+		assertControlField("id", message.id);
+		lines.push(`id: ${message.id}`);
+	}
+	if (message.event != null) {
+		assertControlField("event", message.event);
+		lines.push(`event: ${message.event}`);
+	}
+	if (message.retry != null) {
+		assertRetry(message.retry);
+		lines.push(`retry: ${message.retry}`);
+	}
+	if ("data" in message) {
+		if (typeof message.data !== "string") throw new Error("sse: data must be a string.");
+		for (const line of splitLines(message.data)) lines.push(`data: ${line}`);
+	}
+	return `${lines.join("\n")}\n\n`;
+}
+function getLastEventId(request) {
+	return request.headers.get("Last-Event-ID");
+}
+function eventStream(start, options = {}) {
+	const encoder = new TextEncoder();
+	const { readable, writable } = new TransformStream();
+	const writer = writable.getWriter();
+	const signalController = new AbortController();
+	const headers = buildSseHeaders(options.headers);
+	const keepAlive = normalizeKeepAlive(options.keepAlive);
+	let keepAliveTimer;
+	let closedOnce = false;
+	let closeResolve;
+	const closed = new Promise((resolve) => {
+		closeResolve = resolve;
+	});
+	const markClosed = () => {
+		if (closedOnce) return;
+		closedOnce = true;
+		if (!signalController.signal.aborted) signalController.abort();
+		if (keepAliveTimer != null) {
+			clearInterval(keepAliveTimer);
+			keepAliveTimer = void 0;
+		}
+		closeResolve();
+	};
+	async function close() {
+		if (closedOnce) return;
+		markClosed();
+		await writer.close().catch(() => {});
+	}
+	async function fail(error) {
+		if (closedOnce) return;
+		markClosed();
+		await writer.abort(error).catch(() => {});
+	}
+	async function write(text) {
+		if (closedOnce) throw new SseStreamClosedError();
+		try {
+			await writer.write(encoder.encode(text));
+		} catch {
+			await close();
+			throw new SseStreamClosedError();
+		}
+	}
+	const stream = {
+		signal: signalController.signal,
+		closed,
+		send(message) {
+			return write(formatSse(message));
+		},
+		comment(text = "") {
+			return write(formatComment(text));
+		},
+		close
+	};
+	writer.closed.catch(() => {
+		close();
+	});
+	if (options.signal?.aborted) close();
+	else options.signal?.addEventListener("abort", () => void close(), { once: true });
+	if (keepAlive) keepAliveTimer = setInterval(() => {
+		stream.comment(keepAlive.comment).catch(() => close());
+	}, keepAlive.intervalMs);
+	queueMicrotask(() => {
+		(async () => {
+			try {
+				await start(stream);
+				await close();
+			} catch (error) {
+				await fail(error);
+			}
+		})();
+	});
+	return new Response(readable, { headers });
+}
+function buildSseHeaders(headers) {
+	const result = new Headers(headers);
+	if (!result.has("Content-Type")) result.set("Content-Type", "text/event-stream; charset=utf-8");
+	if (!result.has("Cache-Control")) result.set("Cache-Control", "no-cache, no-transform");
+	if (!result.has("X-Accel-Buffering")) result.set("X-Accel-Buffering", "no");
+	return result;
+}
+function normalizeKeepAlive(keepAlive) {
+	if (keepAlive === false) return null;
+	if (keepAlive === true || keepAlive == null) return {
+		intervalMs: DEFAULT_KEEP_ALIVE_INTERVAL_MS,
+		comment: DEFAULT_KEEP_ALIVE_COMMENT
+	};
+	const intervalMs = keepAlive.intervalMs ?? DEFAULT_KEEP_ALIVE_INTERVAL_MS;
+	if (!Number.isFinite(intervalMs) || intervalMs <= 0) throw new Error("sse: keepAlive.intervalMs must be a positive finite number.");
+	return {
+		intervalMs,
+		comment: keepAlive.comment ?? DEFAULT_KEEP_ALIVE_COMMENT
+	};
+}
+function formatComment(text) {
+	if (typeof text !== "string") throw new Error("sse: comment text must be a string.");
+	return `${splitLines(text).map((line) => `: ${line}`).join("\n")}\n\n`;
+}
+function assertControlField(name, value) {
+	if (typeof value !== "string") throw new Error(`sse: ${name} must be a string.`);
+	if (hasControlFieldSeparator(value)) throw new Error(`sse: ${name} must not contain CR, LF, or NUL characters.`);
+}
+function hasControlFieldSeparator(value) {
+	return value.includes("\r") || value.includes("\n") || value.includes("\0");
+}
+function assertRetry(value) {
+	if (!Number.isInteger(value) || value < 0) throw new Error("sse: retry must be a non-negative integer.");
+}
+function isBinaryData(data) {
+	return data instanceof ArrayBuffer || ArrayBuffer.isView(data) || typeof Blob !== "undefined" && data instanceof Blob || typeof File !== "undefined" && data instanceof File;
+}
+function serializeData(data) {
+	if (typeof data === "string") return data;
+	if (data == null) return data === null ? "null" : throwDataSerializationError(data);
+	if (typeof data === "function" || typeof data === "symbol") return throwDataSerializationError(data);
+	if (isBinaryData(data)) throw new Error("sse: binary data is not supported.");
+	try {
+		const serialized = JSON.stringify(data);
+		if (typeof serialized !== "string") return throwDataSerializationError(data);
+		return serialized;
+	} catch (error) {
+		throw new Error(`sse: data must be JSON-serializable. ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function throwDataSerializationError(data) {
+	throw new Error(`sse: unsupported data value ${String(data)}.`);
+}
+function splitLines(value) {
+	return value.split(/\r\n|\r|\n/);
+}
+//#endregion
+export { SseStreamClosedError, eventStream, formatSse, formatSseText, getLastEventId };

package/dist/{scan-C6HMEIdW.mjs → scan-QtRTdh94.mjs}

@@ -1,6 +1,6 @@
 import { a as join, t as basename } from "./pathe.M-eThtNZ-D-kmWkCS.mjs";
 import { n as globSync, t as glob } from "./dist-DUyXJLkq.mjs";
-import { d as isIdentifier, f as isLiteral, m as isObjectExpression, u as isCallExpression } from "./plugin-inference-oZ6Ybu2_.mjs";
+import { d as isCallExpression, f as isIdentifier, h as isObjectExpression, p as isLiteral } from "./plugin-inference-CCtRkt9O.mjs";
 import { o as parseRouteFilename, s as parseWebSocketFilename, t as scanPages } from "./scan-Ba4hFwlH.mjs";
 import { readFileSync } from "node:fs";
 import { parseSync } from "vite";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "void",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/voidzero-dev/void.git",
@@ -31,6 +31,11 @@
     "#self/remote/binding-handler": "./dist/runtime/remote/binding-handler.mjs",
     "#self/response": "./dist/runtime/response.mjs",
     "#self/sandbox": "./dist/runtime/sandbox.mjs",
+    "#self/sse": "./dist/runtime/sse.mjs",
+    "#self/sse/client": "./dist/runtime/sse-client.mjs",
+    "#self/live": "./dist/runtime/live.mjs",
+    "#self/live/client": "./dist/runtime/live-client.mjs",
+    "#self/runtime/live-server": "./dist/runtime/live-server.mjs",
     "#self/runtime/fetch": "./dist/runtime/fetch.mjs",
     "#self/runtime/fetch-stream": "./dist/runtime/fetch-stream.mjs",
     "#self/runtime/migration-handler": "./dist/runtime/migration-handler.mjs",
@@ -86,6 +91,26 @@
       "import": "./dist/runtime/fetch-stream.mjs",
       "require": "./dist/runtime/fetch-stream.mjs"
     },
+    "./sse": {
+      "types": "./dist/runtime/sse.d.mts",
+      "import": "./dist/runtime/sse.mjs",
+      "require": "./dist/runtime/sse.mjs"
+    },
+    "./sse/client": {
+      "types": "./dist/runtime/sse-client.d.mts",
+      "import": "./dist/runtime/sse-client.mjs",
+      "require": "./dist/runtime/sse-client.mjs"
+    },
+    "./live": {
+      "types": "./dist/runtime/live.d.mts",
+      "import": "./dist/runtime/live.mjs",
+      "require": "./dist/runtime/live.mjs"
+    },
+    "./live/client": {
+      "types": "./dist/runtime/live-client.d.mts",
+      "import": "./dist/runtime/live-client.mjs",
+      "require": "./dist/runtime/live-client.mjs"
+    },
     "./ws": {
       "types": "./dist/runtime/ws.d.mts",
       "import": "./dist/runtime/ws.mjs",
@@ -307,7 +332,7 @@
     "valibot": ">=1.0.0-beta.7",
     "vite": "^8.0.0",
     "zod": "^3.25.0 || ^4.0.0",
-    "@void/md": "0.7.3"
+    "@void/md": "0.7.4"
   },
   "peerDependenciesMeta": {
     "@void/md": {

package/skills/void/docs/guide/live.md

@@ -0,0 +1,230 @@
+---
+outline: deep
+---
+
+# Live Event Streams
+
+`void/live` provides Durable Object-backed fanout over Server-Sent Events. Use it
+when one browser tab needs a single SSE connection that can subscribe and
+unsubscribe from many application topics over time.
+
+Use `void/sse` for request-owned streams where the producer lives inside the same
+route handler. Use `void/live` when later requests, mutations, scheduled jobs, or
+queue consumers need to publish to clients that are already connected.
+
+## Define A Stream
+
+Create a server-only live stream descriptor:
+
+```ts
+// src/live.ts
+import { defineLiveStream } from 'void/live';
+
+export const live = defineLiveStream({
+  id: 'app',
+  allowAnonymousControl: true,
+});
+```
+
+Expose it from a normal route:
+
+```ts
+// routes/live.ts
+import { defineHandler } from 'void';
+import { live } from '../src/live';
+
+export const GET = defineHandler((c) => live.connect(c));
+export const POST = defineHandler((c) => live.control(c));
+```
+
+`GET` opens the SSE connection. `POST` accepts subscribe and unsubscribe control
+operations for that connection.
+
+## Subscribe From The Browser
+
+Use the browser helper from `void/live/client`:
+
+```ts
+import { connectLiveStream } from 'void/live/client';
+
+const stream = connectLiveStream('/live', {
+  withCredentials: true,
+  retryDelay: 1_000,
+  onError(error) {
+    console.error(error);
+  },
+});
+
+const unsubscribePost = await stream.subscribe({
+  id: 'post-card',
+  topic: 'post:12',
+  onEvent(event) {
+    if (event.type === 'updated') {
+      console.log(event.data);
+    }
+  },
+});
+
+const unsubscribeComments = await stream.subscribe({
+  id: 'comments',
+  topic: 'comment:2323',
+});
+
+await unsubscribeComments();
+await unsubscribePost();
+stream.close();
+```
+
+The helper opens one native `EventSource`, waits for it to open, then sends
+batched `POST` control operations. Subscription ids are scoped to the
+connection. Reusing an id replaces the previous subscription with that id. If
+the transport drops, the helper reconnects and resubmits active subscriptions
+with their latest `eventId` as `lastEventId`.
+
+## Publish
+
+Publish from any server-side code that has a Void runtime env:
+
+```ts
+import { live } from '../src/live';
+
+await live.publish(
+  'post:12',
+  { title: 'Updated title' },
+  { type: 'updated', eventId: 'post-12-v8' },
+);
+```
+
+Topics are opaque strings. Payloads are application-owned JSON. `type` and
+`eventId` are copied into the JSON envelope; `void/live` does not interpret
+them, persist them, or use native SSE `id` fields.
+
+If you are outside an active request/runtime context, pass env explicitly:
+
+```ts
+await live.withEnv(env).publish('post:12', { title: 'Updated title' });
+```
+
+## Authorization
+
+Every live connection has an owner. The owner is the identity allowed to send
+control operations for that SSE connection. `connect()` resolves and stores the
+owner; `control()` resolves the owner again and rejects the request if it does
+not match.
+
+The quickstart uses an anonymous stream:
+
+```ts
+export const live = defineLiveStream({
+  id: 'app',
+  allowAnonymousControl: true,
+});
+```
+
+For authenticated streams, pass the same owner key to `connect()` and
+`control()`:
+
+```ts
+return live.connect(c, { owner: `user:${session.userId}` });
+return live.control(c, { owner: `user:${session.userId}` });
+```
+
+If every route should derive ownership the same way, define it once with
+`identifyConnection`:
+
+```ts
+export const live = defineLiveStream({
+  id: 'app',
+  async identifyConnection(ctx) {
+    const session = await getSession(ctx.request);
+    return session ? `user:${session.userId}` : null;
+  },
+});
+```
+
+Then the route handlers can stay thin:
+
+```ts
+export const GET = defineHandler((c) => live.connect(c));
+export const POST = defineHandler((c) => live.control(c));
+```
+
+When `identifyConnection` returns `null` or `undefined`, Void falls back to the
+current authenticated user and uses `user:${user.id}` when the user has a string
+`id`. If neither path produces an owner and `allowAnonymousControl` is not set,
+the request is rejected with `403`.
+
+For stream-local subscription rules, use `onSubscribe`:
+
+```ts
+export const live = defineLiveStream({
+  id: 'app',
+  async onSubscribe(ctx) {
+    const match = /^post:(.+)$/.exec(ctx.topic);
+    if (match && !(await canReadPost(ctx.env, ctx.user, match[1]))) {
+      return new Response('Forbidden', { status: 403 });
+    }
+  },
+});
+```
+
+## Limits
+
+`void/live` is designed for small and medium fanout. By default, a stream allows:
+
+- `256` active subscriptions per browser connection
+- `256` active subscriptions per topic
+- `100` subscribe or unsubscribe operations per control request
+- `100` queued events per connection
+- `64 KiB` per encoded event envelope
+
+A topic is the unit of fanout. For example, if each blog post uses a topic like
+`post:${postId}`, then each post can have up to `256` active live subscribers at
+one time. Other posts use separate topics and have separate limits.
+
+Streams can have many possible topics. Topics are created on demand when clients
+subscribe or publishers send events, so an app with thousands of posts, rooms, or
+documents can use one topic per entity without provisioning them ahead of time.
+The limit applies to each active topic, not to the total number of topic names
+your app might use.
+
+For example, a blog with `10,000` posts can model its live capacity as
+`10,000 posts × up to 256 active subscribers per post topic`.
+
+That shape works because each post topic is independent. A single post with more
+than `256` active live subscribers would need a larger broadcast design.
+
+These limits apply to live subscriptions, not total users or total page views.
+One user with two open tabs may count twice. Disconnected subscriptions are
+pruned, but they can count until the runtime observes that they are stale.
+
+You can lower limits per stream:
+
+```ts
+export const live = defineLiveStream({
+  id: 'app',
+  limits: {
+    maxSubscriptionsPerTopic: 64,
+  },
+});
+```
+
+`maxSubscriptionsPerTopic` cannot be raised above `256`. For larger broadcast
+workloads, shard topics in userland or use a dedicated realtime system.
+
+## Delivery Semantics
+
+`void/live` is an at-most-once live fanout primitive:
+
+- one SSE connection can hold many topic subscriptions
+- publish cost is proportional to subscribers of the topic
+- events are ordered within one topic
+- clients using the raw HTTP protocol must resubscribe after reconnect
+- deploys, rollbacks, Worker restarts, browser reconnects, and network changes
+  can drop live state
+- durable replay, cache invalidation, live queries, and client state management
+  belong in userland
+
+Use an application database, queue, or custom Durable Object for replay. Use
+`eventId` and caller-provided `lastEventId` values as application protocol
+fields when you build that layer.

package/skills/void/docs/guide/sse.md

@@ -0,0 +1,187 @@
+---
+outline: deep
+---
+
+# Server-Sent Events
+
+Void provides `void/sse` for producing and consuming Server-Sent Events from ordinary route handlers. It handles event formatting, response headers, keepalives, stream closure, request aborts, and browser `EventSource` parsing.
+
+Use SSE when one HTTP request owns the producer: AI token streaming, progress updates, command output, deployment logs, or incremental status messages. Use `void/live` or an application-level Durable Object when multiple requests need shared fanout, replay, or subscription state.
+
+## Server streams
+
+Return `eventStream()` from a route handler:
+
+```ts
+// routes/api/events.ts
+import { defineHandler } from 'void';
+import { eventStream } from 'void/sse';
+
+export const GET = defineHandler((c) => {
+  return eventStream(
+    async (stream) => {
+      await stream.comment('connected');
+      await stream.send({
+        event: 'ready',
+        data: { now: Date.now() },
+      });
+
+      const timer = setInterval(() => {
+        void stream.send({ event: 'tick', data: { now: Date.now() } }).catch(() => stream.close());
+      }, 1000);
+
+      await stream.closed;
+      clearInterval(timer);
+    },
+    {
+      signal: c.req.raw.signal,
+    },
+  );
+});
+```
+
+`eventStream()` returns a `Response` immediately with these default headers:
+
+```http
+Content-Type: text/event-stream; charset=utf-8
+Cache-Control: no-cache, no-transform
+X-Accel-Buffering: no
+```
+
+When the `start` callback returns, the stream closes. Long-lived streams should wait on `stream.closed`, a producer promise, or an application cancellation signal before returning.
+
+## Sending events
+
+Use `send()` for SSE messages and `comment()` for comments:
+
+```ts
+await stream.send({
+  id: 'evt_1',
+  event: 'post.update',
+  retry: 1000,
+  data: { id: 'post_123', likes: 10 },
+});
+
+await stream.comment('still connected');
+```
+
+`data` may be a string or JSON-serializable value. Strings are sent as-is; other values are serialized with `JSON.stringify()`. Multi-line strings are split into multiple `data:` lines. Binary data is rejected because SSE is text-only.
+
+`event`, `id`, and `retry` are validated before writing so accidental frame injection is rejected. Writes after close reject with `SseStreamClosedError`.
+
+If you already serialized the payload, use `formatSseText()` for lower-level formatting while keeping the same `id`, `event`, and `retry` validation:
+
+```ts
+import { formatSseText } from 'void/sse';
+
+const frame = formatSseText({
+  event: 'post.update',
+  data: JSON.stringify({ id: 'post_123', likes: 10 }),
+});
+```
+
+## Keepalives
+
+Keepalives are enabled by default every 15 seconds:
+
+```ts
+return eventStream(start);
+```
+
+Disable them or customize the interval and comment text:
+
+```ts
+return eventStream(start, { keepAlive: false });
+
+return eventStream(start, {
+  keepAlive: { intervalMs: 5000, comment: 'ping' },
+});
+```
+
+The interval must be a positive finite number.
+
+## Last Event ID
+
+Browsers send `Last-Event-ID` when reconnecting after an event with an `id` field. Use `getLastEventId()` to resume from your own storage:
+
+```ts
+import { getLastEventId } from 'void/sse';
+
+export const GET = defineHandler((c) => {
+  const lastId = getLastEventId(c.req.raw);
+  return eventStream(async (stream) => {
+    await stream.send({ id: nextId(lastId), data: await loadNextItem(lastId) });
+  });
+});
+```
+
+`void/sse` does not store or replay events. Persist event offsets in your own database, queue, or Durable Object when replay matters.
+
+## Client
+
+Use `connectEventStream()` from the browser-only `void/sse/client` subpath:
+
+```ts
+import { connectEventStream } from 'void/sse/client';
+
+const stream = connectEventStream<{
+  ready: { now: number };
+  tick: { now: number };
+}>('/api/events', {
+  withCredentials: true,
+});
+
+const offReady = stream.on('ready', (event) => {
+  console.log(event.data.now);
+});
+
+stream.on('tick', (event) => {
+  console.log(event.data.now);
+});
+
+offReady();
+stream.close();
+```
+
+The client wraps native `EventSource`. It supports cookie credentials and typed event handlers, but it does not support request bodies or arbitrary headers. Use cookie auth, signed URLs, or a fetch-based streaming route when you need custom headers.
+
+JSON parsing is the default. Set `parse: 'text'` or pass a custom parser for non-JSON payloads:
+
+```ts
+const logs = connectEventStream('/api/logs', { parse: 'text' });
+
+logs.on('line', (event) => {
+  console.log(event.data);
+});
+```
+
+## Auth
+
+SSE routes are ordinary route handlers, so use the same auth checks you use for JSON routes:
+
+```ts
+import { requireAuth } from 'void/auth';
+
+export const GET = defineHandler(async (c) => {
+  const user = await requireAuth(c);
+
+  return eventStream(async (stream) => {
+    await stream.send({ event: 'ready', data: { userId: user.id } });
+    await stream.closed;
+  });
+});
+```
+
+Native `EventSource` can send cookies with `withCredentials: true`. For non-cookie auth, generate a short-lived signed URL and validate it in the route handler.
+
+## When to use SSE
+
+Plain SSE is enough when the producer belongs to the same request that opened the stream:
+
+- AI token streaming
+- One-off progress updates
+- Command output
+- Per-request deployment or build logs
+- Incremental status for a long-running action
+
+Use a higher-level realtime primitive when you need cross-request fanout, rooms, replay buffers, subscriptions, database change streams, or multi-region coordination.