@durable-streams/server 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,167 @@
+# @durable-streams/server
+
+Node.js reference server implementation for the Durable Streams protocol.
+
+## Installation
+
+```bash
+npm install @durable-streams/server
+```
+
+## Overview
+
+This package provides a reference implementation of the Durable Streams protocol for Node.js. It supports both in-memory and file-backed storage modes, making it suitable for development, testing, and production workloads.
+
+For a standalone binary option, see the [Caddy-based server](https://github.com/durable-streams/durable-streams/releases).
+
+## Quick Start
+
+```typescript
+import { DurableStreamTestServer } from "@durable-streams/server"
+
+const server = new DurableStreamTestServer({
+  port: 4437,
+  host: "127.0.0.1",
+})
+
+await server.start()
+console.log("Server running on http://127.0.0.1:4437")
+```
+
+## Storage Modes
+
+### In-Memory (Default)
+
+Fast, ephemeral storage for development and testing:
+
+```typescript
+import { DurableStreamTestServer, StreamStore } from "@durable-streams/server"
+
+const store = new StreamStore()
+const server = new DurableStreamTestServer({
+  port: 4437,
+  store,
+})
+```
+
+### File-Backed
+
+Persistent storage with streams stored as log files and LMDB for metadata:
+
+```typescript
+import {
+  DurableStreamTestServer,
+  FileBackedStreamStore,
+} from "@durable-streams/server"
+
+const store = new FileBackedStreamStore({
+  path: "./data/streams",
+})
+const server = new DurableStreamTestServer({
+  port: 4437,
+  store,
+})
+```
+
+## Registry Hooks
+
+Track stream lifecycle events (creation, deletion):
+
+```typescript
+import {
+  DurableStreamTestServer,
+  createRegistryHooks,
+} from "@durable-streams/server"
+
+const server = new DurableStreamTestServer({
+  port: 4437,
+  hooks: createRegistryHooks({
+    registryPath: "__registry__",
+  }),
+})
+```
+
+The registry maintains a system stream that tracks all stream creates and deletes, useful for building admin UIs or monitoring.
+
+## API
+
+### DurableStreamTestServer
+
+```typescript
+interface TestServerOptions {
+  port?: number
+  host?: string
+  store?: StreamStore | FileBackedStreamStore
+  hooks?: StreamLifecycleHook[]
+  cors?: boolean
+  cursorOptions?: CursorOptions
+}
+
+class DurableStreamTestServer {
+  constructor(options?: TestServerOptions)
+  start(): Promise<void>
+  stop(): Promise<void>
+  readonly port: number
+  readonly baseUrl: string
+}
+```
+
+### StreamStore
+
+In-memory stream storage:
+
+```typescript
+class StreamStore {
+  create(path: string, contentType: string, options?: CreateOptions): Stream
+  get(path: string): Stream | undefined
+  delete(path: string): boolean
+  append(path: string, data: Uint8Array, seq?: string): void
+  read(path: string, offset: string): ReadResult
+}
+```
+
+### FileBackedStreamStore
+
+File-backed persistent storage (log files for streams, LMDB for metadata) with the same interface as `StreamStore`.
+
+## Exports
+
+```typescript
+export { DurableStreamTestServer } from "./server"
+export { StreamStore } from "./store"
+export { FileBackedStreamStore } from "./file-store"
+export { encodeStreamPath, decodeStreamPath } from "./path-encoding"
+export { createRegistryHooks } from "./registry-hook"
+export {
+  calculateCursor,
+  handleCursorCollision,
+  generateResponseCursor,
+  DEFAULT_CURSOR_EPOCH,
+  DEFAULT_CURSOR_INTERVAL_SECONDS,
+  type CursorOptions,
+} from "./cursor"
+export type {
+  Stream,
+  StreamMessage,
+  TestServerOptions,
+  PendingLongPoll,
+  StreamLifecycleEvent,
+  StreamLifecycleHook,
+} from "./types"
+```
+
+## Testing Your Implementation
+
+Use the conformance test suite to validate protocol compliance:
+
+```typescript
+import { runConformanceTests } from "@durable-streams/server-conformance-tests"
+
+runConformanceTests({
+  baseUrl: "http://localhost:4437",
+})
+```
+
+## License
+
+Apache-2.0

package/dist/index.cjs

@@ -88,12 +88,40 @@ var StreamStore = class {
 	streams = new Map();
 	pendingLongPolls = [];
 	/**
+	* Check if a stream is expired based on TTL or Expires-At.
+	*/
+	isExpired(stream) {
+		const now = Date.now();
+		if (stream.expiresAt) {
+			const expiryTime = new Date(stream.expiresAt).getTime();
+			if (!Number.isFinite(expiryTime) || now >= expiryTime) return true;
+		}
+		if (stream.ttlSeconds !== void 0) {
+			const expiryTime = stream.createdAt + stream.ttlSeconds * 1e3;
+			if (now >= expiryTime) return true;
+		}
+		return false;
+	}
+	/**
+	* Get a stream, deleting it if expired.
+	* Returns undefined if stream doesn't exist or is expired.
+	*/
+	getIfNotExpired(path) {
+		const stream = this.streams.get(path);
+		if (!stream) return void 0;
+		if (this.isExpired(stream)) {
+			this.delete(path);
+			return void 0;
+		}
+		return stream;
+	}
+	/**
 	* Create a new stream.
 	* @throws Error if stream already exists with different config
 	* @returns existing stream if config matches (idempotent)
 	*/
 	create(path, options = {}) {
-		const existing = this.streams.get(path);
+		const existing = this.getIfNotExpired(path);
 		if (existing) {
 			const contentTypeMatches = (normalizeContentType(options.contentType) || `application/octet-stream`) === (normalizeContentType(existing.contentType) || `application/octet-stream`);
 			const ttlMatches = options.ttlSeconds === existing.ttlSeconds;
@@ -116,15 +144,16 @@ var StreamStore = class {
 	}
 	/**
 	* Get a stream by path.
+	* Returns undefined if stream doesn't exist or is expired.
 	*/
 	get(path) {
-		return this.streams.get(path);
+		return this.getIfNotExpired(path);
 	}
 	/**
-	* Check if a stream exists.
+	* Check if a stream exists (and is not expired).
 	*/
 	has(path) {
-		return this.streams.has(path);
+		return this.getIfNotExpired(path) !== void 0;
 	}
 	/**
 	* Delete a stream.
@@ -135,12 +164,12 @@ var StreamStore = class {
 	}
 	/**
 	* Append data to a stream.
-	* @throws Error if stream doesn't exist
+	* @throws Error if stream doesn't exist or is expired
 	* @throws Error if seq is lower than lastSeq
 	* @throws Error if JSON mode and array is empty
 	*/
 	append(path, data, options = {}) {
-		const stream = this.streams.get(path);
+		const stream = this.getIfNotExpired(path);
 		if (!stream) throw new Error(`Stream not found: ${path}`);
 		if (options.contentType && stream.contentType) {
 			const providedType = normalizeContentType(options.contentType);
@@ -157,9 +186,10 @@ var StreamStore = class {
 	}
 	/**
 	* Read messages from a stream starting at the given offset.
+	* @throws Error if stream doesn't exist or is expired
 	*/
 	read(path, offset) {
-		const stream = this.streams.get(path);
+		const stream = this.getIfNotExpired(path);
 		if (!stream) throw new Error(`Stream not found: ${path}`);
 		if (!offset || offset === `-1`) return {
 			messages: [...stream.messages],
@@ -178,9 +208,10 @@ var StreamStore = class {
 	/**
 	* Format messages for response.
 	* For JSON mode, wraps concatenated data in array brackets.
+	* @throws Error if stream doesn't exist or is expired
 	*/
 	formatResponse(path, messages) {
-		const stream = this.streams.get(path);
+		const stream = this.getIfNotExpired(path);
 		if (!stream) throw new Error(`Stream not found: ${path}`);
 		const totalSize = messages.reduce((sum, m) => sum + m.data.length, 0);
 		const concatenated = new Uint8Array(totalSize);
@@ -194,9 +225,10 @@ var StreamStore = class {
 	}
 	/**
 	* Wait for new messages (long-poll).
+	* @throws Error if stream doesn't exist or is expired
 	*/
 	async waitForMessages(path, offset, timeoutMs) {
-		const stream = this.streams.get(path);
+		const stream = this.getIfNotExpired(path);
 		if (!stream) throw new Error(`Stream not found: ${path}`);
 		const { messages } = this.read(path, offset);
 		if (messages.length > 0) return {
@@ -229,9 +261,10 @@ var StreamStore = class {
 	}
 	/**
 	* Get the current offset for a stream.
+	* Returns undefined if stream doesn't exist or is expired.
 	*/
 	getCurrentOffset(path) {
-		return this.streams.get(path)?.currentOffset;
+		return this.getIfNotExpired(path)?.currentOffset;
 	}
 	/**
 	* Clear all streams.
@@ -605,6 +638,35 @@ var FileBackedStreamStore = class {
 		};
 	}
 	/**
+	* Check if a stream is expired based on TTL or Expires-At.
+	*/
+	isExpired(meta) {
+		const now = Date.now();
+		if (meta.expiresAt) {
+			const expiryTime = new Date(meta.expiresAt).getTime();
+			if (!Number.isFinite(expiryTime) || now >= expiryTime) return true;
+		}
+		if (meta.ttlSeconds !== void 0) {
+			const expiryTime = meta.createdAt + meta.ttlSeconds * 1e3;
+			if (now >= expiryTime) return true;
+		}
+		return false;
+	}
+	/**
+	* Get stream metadata, deleting it if expired.
+	* Returns undefined if stream doesn't exist or is expired.
+	*/
+	getMetaIfNotExpired(streamPath) {
+		const key = `stream:${streamPath}`;
+		const meta = this.db.get(key);
+		if (!meta) return void 0;
+		if (this.isExpired(meta)) {
+			this.delete(streamPath);
+			return void 0;
+		}
+		return meta;
+	}
+	/**
 	* Close the store, closing all file handles and database.
 	* All data is already fsynced on each append, so no final flush needed.
 	*/
@@ -613,8 +675,7 @@ var FileBackedStreamStore = class {
 		await this.db.close();
 	}
 	async create(streamPath, options = {}) {
-		const key = `stream:${streamPath}`;
-		const existing = this.db.get(key);
+		const existing = this.getMetaIfNotExpired(streamPath);
 		if (existing) {
 			const normalizeMimeType = (ct) => (ct ?? `application/octet-stream`).toLowerCase();
 			const contentTypeMatches = normalizeMimeType(options.contentType) === normalizeMimeType(existing.contentType);
@@ -623,6 +684,7 @@ var FileBackedStreamStore = class {
 			if (contentTypeMatches && ttlMatches && expiresMatches) return this.streamMetaToStream(existing);
 			else throw new Error(`Stream already exists with different configuration: ${streamPath}`);
 		}
+		const key = `stream:${streamPath}`;
 		const streamMeta = {
 			path: streamPath,
 			contentType: options.contentType,
@@ -656,13 +718,11 @@ var FileBackedStreamStore = class {
 		return this.streamMetaToStream(streamMeta);
 	}
 	get(streamPath) {
-		const key = `stream:${streamPath}`;
-		const meta = this.db.get(key);
+		const meta = this.getMetaIfNotExpired(streamPath);
 		return meta ? this.streamMetaToStream(meta) : void 0;
 	}
 	has(streamPath) {
-		const key = `stream:${streamPath}`;
-		return this.db.get(key) !== void 0;
+		return this.getMetaIfNotExpired(streamPath) !== void 0;
 	}
 	delete(streamPath) {
 		const key = `stream:${streamPath}`;
@@ -680,8 +740,7 @@ var FileBackedStreamStore = class {
 		return true;
 	}
 	async append(streamPath, data, options = {}) {
-		const key = `stream:${streamPath}`;
-		const streamMeta = this.db.get(key);
+		const streamMeta = this.getMetaIfNotExpired(streamPath);
 		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
 		if (options.contentType && streamMeta.contentType) {
 			const providedType = normalizeContentType(options.contentType);
@@ -729,13 +788,13 @@ var FileBackedStreamStore = class {
 			lastSeq: options.seq ?? streamMeta.lastSeq,
 			totalBytes: streamMeta.totalBytes + processedData.length + 5
 		};
+		const key = `stream:${streamPath}`;
 		this.db.putSync(key, updatedMeta);
 		this.notifyLongPolls(streamPath);
 		return message;
 	}
 	read(streamPath, offset) {
-		const key = `stream:${streamPath}`;
-		const streamMeta = this.db.get(key);
+		const streamMeta = this.getMetaIfNotExpired(streamPath);
 		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
 		const startOffset = offset ?? `0000000000000000_0000000000000000`;
 		const startParts = startOffset.split(`_`).map(Number);
@@ -787,8 +846,7 @@ var FileBackedStreamStore = class {
 		};
 	}
 	async waitForMessages(streamPath, offset, timeoutMs) {
-		const key = `stream:${streamPath}`;
-		const streamMeta = this.db.get(key);
+		const streamMeta = this.getMetaIfNotExpired(streamPath);
 		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
 		const { messages } = this.read(streamPath, offset);
 		if (messages.length > 0) return {
@@ -822,10 +880,10 @@ var FileBackedStreamStore = class {
 	/**
 	* Format messages for response.
 	* For JSON mode, wraps concatenated data in array brackets.
+	* @throws Error if stream doesn't exist or is expired
 	*/
 	formatResponse(streamPath, messages) {
-		const key = `stream:${streamPath}`;
-		const streamMeta = this.db.get(key);
+		const streamMeta = this.getMetaIfNotExpired(streamPath);
 		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
 		const totalSize = messages.reduce((sum, m) => sum + m.data.length, 0);
 		const concatenated = new Uint8Array(totalSize);
@@ -838,8 +896,7 @@ var FileBackedStreamStore = class {
 		return concatenated;
 	}
 	getCurrentOffset(streamPath) {
-		const key = `stream:${streamPath}`;
-		const streamMeta = this.db.get(key);
+		const streamMeta = this.getMetaIfNotExpired(streamPath);
 		return streamMeta?.currentOffset;
 	}
 	clear() {
@@ -1018,10 +1075,12 @@ const CURSOR_QUERY_PARAM = `cursor`;
 /**
 * Encode data for SSE format.
 * Per SSE spec, each line in the payload needs its own "data:" prefix.
-* Newlines in the payload become separate data: lines.
+* Line terminators in the payload (CR, LF, or CRLF) become separate data: lines.
+* This prevents CRLF injection attacks where malicious payloads could inject
+* fake SSE events using CR-only line terminators.
 */
 function encodeSSEData(payload) {
-	const lines = payload.split(`\n`);
+	const lines = payload.split(/\r\n|\r|\n/);
 	return lines.map((line) => `data: ${line}`).join(`\n`) + `\n\n`;
 }
 /**
@@ -1060,8 +1119,8 @@ var DurableStreamTestServer = class {
 	_url = null;
 	activeSSEResponses = new Set();
 	isShuttingDown = false;
-	/** Injected errors for testing retry/resilience */
-	injectedErrors = new Map();
+	/** Injected faults for testing retry/resilience */
+	injectedFaults = new Map();
 	constructor(options = {}) {
 		if (options.dataDir) this.store = new FileBackedStreamStore({ dataDir: options.dataDir });
 		else this.store = new StreamStore();
@@ -1146,30 +1205,71 @@ var DurableStreamTestServer = class {
 	/**
 	* Inject an error to be returned on the next N requests to a path.
 	* Used for testing retry/resilience behavior.
+	* @deprecated Use injectFault for full fault injection capabilities
 	*/
 	injectError(path, status, count = 1, retryAfter) {
-		this.injectedErrors.set(path, {
+		this.injectedFaults.set(path, {
 			status,
 			count,
 			retryAfter
 		});
 	}
 	/**
-	* Clear all injected errors.
+	* Inject a fault to be triggered on the next N requests to a path.
+	* Supports various fault types: delays, connection drops, body corruption, etc.
 	*/
-	clearInjectedErrors() {
-		this.injectedErrors.clear();
+	injectFault(path, fault) {
+		this.injectedFaults.set(path, {
+			count: 1,
+			...fault
+		});
+	}
+	/**
+	* Clear all injected faults.
+	*/
+	clearInjectedFaults() {
+		this.injectedFaults.clear();
 	}
 	/**
-	* Check if there's an injected error for this path and consume it.
-	* Returns the error config if one should be returned, null otherwise.
+	* Check if there's an injected fault for this path/method and consume it.
+	* Returns the fault config if one should be triggered, null otherwise.
 	*/
-	consumeInjectedError(path) {
-		const error = this.injectedErrors.get(path);
-		if (!error) return null;
-		error.count--;
-		if (error.count <= 0) this.injectedErrors.delete(path);
-		return error;
+	consumeInjectedFault(path, method) {
+		const fault = this.injectedFaults.get(path);
+		if (!fault) return null;
+		if (fault.method && fault.method.toUpperCase() !== method.toUpperCase()) return null;
+		if (fault.probability !== void 0 && Math.random() > fault.probability) return null;
+		fault.count--;
+		if (fault.count <= 0) this.injectedFaults.delete(path);
+		return fault;
+	}
+	/**
+	* Apply delay from fault config (including jitter).
+	*/
+	async applyFaultDelay(fault) {
+		if (fault.delayMs !== void 0 && fault.delayMs > 0) {
+			const jitter = fault.jitterMs ? Math.random() * fault.jitterMs : 0;
+			await new Promise((resolve) => setTimeout(resolve, fault.delayMs + jitter));
+		}
+	}
+	/**
+	* Apply body modifications from stored fault (truncation, corruption).
+	* Returns modified body, or original if no modifications needed.
+	*/
+	applyFaultBodyModification(res, body) {
+		const fault = res._injectedFault;
+		if (!fault) return body;
+		let modified = body;
+		if (fault.truncateBodyBytes !== void 0 && modified.length > fault.truncateBodyBytes) modified = modified.slice(0, fault.truncateBodyBytes);
+		if (fault.corruptBody && modified.length > 0) {
+			modified = new Uint8Array(modified);
+			const numCorrupt = Math.max(1, Math.floor(modified.length * .03));
+			for (let i = 0; i < numCorrupt; i++) {
+				const pos = Math.floor(Math.random() * modified.length);
+				modified[pos] = modified[pos] ^ 1 << Math.floor(Math.random() * 8);
+			}
+		}
+		return modified;
 	}
 	async handleRequest(req, res) {
 		const url = new URL(req.url ?? `/`, `http://${req.headers.host}`);
@@ -1179,6 +1279,8 @@ var DurableStreamTestServer = class {
 		res.setHeader(`access-control-allow-methods`, `GET, POST, PUT, DELETE, HEAD, OPTIONS`);
 		res.setHeader(`access-control-allow-headers`, `content-type, authorization, Stream-Seq, Stream-TTL, Stream-Expires-At`);
 		res.setHeader(`access-control-expose-headers`, `Stream-Next-Offset, Stream-Cursor, Stream-Up-To-Date, etag, content-type, content-encoding, vary`);
+		res.setHeader(`x-content-type-options`, `nosniff`);
+		res.setHeader(`cross-origin-resource-policy`, `cross-origin`);
 		if (method === `OPTIONS`) {
 			res.writeHead(204);
 			res.end();
@@ -1188,13 +1290,21 @@ var DurableStreamTestServer = class {
 			await this.handleTestInjectError(method, req, res);
 			return;
 		}
-		const injectedError = this.consumeInjectedError(path);
-		if (injectedError) {
-			const headers = { "content-type": `text/plain` };
-			if (injectedError.retryAfter !== void 0) headers[`retry-after`] = injectedError.retryAfter.toString();
-			res.writeHead(injectedError.status, headers);
-			res.end(`Injected error for testing`);
-			return;
+		const fault = this.consumeInjectedFault(path, method ?? `GET`);
+		if (fault) {
+			await this.applyFaultDelay(fault);
+			if (fault.dropConnection) {
+				res.socket?.destroy();
+				return;
+			}
+			if (fault.status !== void 0) {
+				const headers = { "content-type": `text/plain` };
+				if (fault.retryAfter !== void 0) headers[`retry-after`] = fault.retryAfter.toString();
+				res.writeHead(fault.status, headers);
+				res.end(`Injected error for testing`);
+				return;
+			}
+			if (fault.truncateBodyBytes !== void 0 || fault.corruptBody) res._injectedFault = fault;
 		}
 		try {
 			switch (method) {
@@ -1309,7 +1419,10 @@ var DurableStreamTestServer = class {
 			res.end();
 			return;
 		}
-		const headers = { [STREAM_OFFSET_HEADER]: stream.currentOffset };
+		const headers = {
+			[STREAM_OFFSET_HEADER]: stream.currentOffset,
+			"cache-control": `no-store`
+		};
 		if (stream.contentType) headers[`content-type`] = stream.contentType;
 		headers[`etag`] = `"${Buffer.from(path).toString(`base64`)}:-1:${stream.currentOffset}"`;
 		res.writeHead(200, headers);
@@ -1400,6 +1513,7 @@ var DurableStreamTestServer = class {
 				headers[`vary`] = `accept-encoding`;
 			}
 		}
+		finalData = this.applyFaultBodyModification(res, finalData);
 		res.writeHead(200, headers);
 		res.end(Buffer.from(finalData));
 	}
@@ -1412,7 +1526,9 @@ var DurableStreamTestServer = class {
 			"content-type": `text/event-stream`,
 			"cache-control": `no-cache`,
 			connection: `keep-alive`,
-			"access-control-allow-origin": `*`
+			"access-control-allow-origin": `*`,
+			"x-content-type-options": `nosniff`,
+			"cross-origin-resource-policy": `cross-origin`
 		});
 		let currentOffset = initialOffset;
 		let isConnected = true;
@@ -1483,7 +1599,7 @@ var DurableStreamTestServer = class {
 			seq,
 			contentType
 		}));
-		res.writeHead(200, { [STREAM_OFFSET_HEADER]: message.offset });
+		res.writeHead(204, { [STREAM_OFFSET_HEADER]: message.offset });
 		res.end();
 	}
 	/**
@@ -1514,12 +1630,29 @@ var DurableStreamTestServer = class {
 			const body = await this.readBody(req);
 			try {
 				const config = JSON.parse(new TextDecoder().decode(body));
-				if (!config.path || !config.status) {
+				if (!config.path) {
 					res.writeHead(400, { "content-type": `text/plain` });
-					res.end(`Missing required fields: path, status`);
+					res.end(`Missing required field: path`);
 					return;
 				}
-				this.injectError(config.path, config.status, config.count ?? 1, config.retryAfter);
+				const hasFaultType = config.status !== void 0 || config.delayMs !== void 0 || config.dropConnection || config.truncateBodyBytes !== void 0 || config.corruptBody;
+				if (!hasFaultType) {
+					res.writeHead(400, { "content-type": `text/plain` });
+					res.end(`Must specify at least one fault type: status, delayMs, dropConnection, truncateBodyBytes, or corruptBody`);
+					return;
+				}
+				this.injectFault(config.path, {
+					status: config.status,
+					count: config.count ?? 1,
+					retryAfter: config.retryAfter,
+					delayMs: config.delayMs,
+					dropConnection: config.dropConnection,
+					truncateBodyBytes: config.truncateBodyBytes,
+					probability: config.probability,
+					method: config.method,
+					corruptBody: config.corruptBody,
+					jitterMs: config.jitterMs
+				});
 				res.writeHead(200, { "content-type": `application/json` });
 				res.end(JSON.stringify({ ok: true }));
 			} catch {
@@ -1527,7 +1660,7 @@ var DurableStreamTestServer = class {
 				res.end(`Invalid JSON body`);
 			}
 		} else if (method === `DELETE`) {
-			this.clearInjectedErrors();
+			this.clearInjectedFaults();
 			res.writeHead(200, { "content-type": `application/json` });
 			res.end(JSON.stringify({ ok: true }));
 		} else {