@durable-streams/server 0.1.2 → 0.1.3

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() {

package/dist/index.d.cts

@@ -159,6 +159,15 @@ declare class StreamStore {
   private streams;
   private pendingLongPolls;
   /**
+  * Check if a stream is expired based on TTL or Expires-At.
+  */
+  private isExpired;
+  /**
+  * Get a stream, deleting it if expired.
+  * Returns undefined if stream doesn't exist or is expired.
+  */
+  private getIfNotExpired;
+  /**
   * Create a new stream.
   * @throws Error if stream already exists with different config
   * @returns existing stream if config matches (idempotent)
@@ -171,10 +180,11 @@ declare class StreamStore {
   }): Stream;
   /**
   * Get a stream by path.
+  * Returns undefined if stream doesn't exist or is expired.
   */
   get(path: string): Stream | undefined;
   /**
-  * Check if a stream exists.
+  * Check if a stream exists (and is not expired).
   */
   has(path: string): boolean;
   /**
@@ -183,7 +193,7 @@ declare class StreamStore {
   delete(path: string): boolean;
   /**
   * 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
   */
@@ -193,6 +203,7 @@ declare class StreamStore {
   }): StreamMessage;
   /**
   * Read messages from a stream starting at the given offset.
+  * @throws Error if stream doesn't exist or is expired
   */
   read(path: string, offset?: string): {
     messages: Array<StreamMessage>;
@@ -201,10 +212,12 @@ declare class StreamStore {
   /**
   * 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: string, messages: Array<StreamMessage>): Uint8Array;
   /**
   * Wait for new messages (long-poll).
+  * @throws Error if stream doesn't exist or is expired
   */
   waitForMessages(path: string, offset: string, timeoutMs: number): Promise<{
     messages: Array<StreamMessage>;
@@ -212,6 +225,7 @@ declare class StreamStore {
   }>;
   /**
   * Get the current offset for a stream.
+  * Returns undefined if stream doesn't exist or is expired.
   */
   getCurrentOffset(path: string): string | undefined;
   /**
@@ -263,6 +277,15 @@ declare class FileBackedStreamStore {
   */
   private streamMetaToStream;
   /**
+  * Check if a stream is expired based on TTL or Expires-At.
+  */
+  private isExpired;
+  /**
+  * Get stream metadata, deleting it if expired.
+  * Returns undefined if stream doesn't exist or is expired.
+  */
+  private getMetaIfNotExpired;
+  /**
   * Close the store, closing all file handles and database.
   * All data is already fsynced on each append, so no final flush needed.
   */
@@ -292,6 +315,7 @@ declare class FileBackedStreamStore {
   /**
   * 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: string, messages: Array<StreamMessage>): Uint8Array;
   getCurrentOffset(streamPath: string): string | undefined;

package/dist/index.d.ts

@@ -159,6 +159,15 @@ declare class StreamStore {
   private streams;
   private pendingLongPolls;
   /**
+  * Check if a stream is expired based on TTL or Expires-At.
+  */
+  private isExpired;
+  /**
+  * Get a stream, deleting it if expired.
+  * Returns undefined if stream doesn't exist or is expired.
+  */
+  private getIfNotExpired;
+  /**
   * Create a new stream.
   * @throws Error if stream already exists with different config
   * @returns existing stream if config matches (idempotent)
@@ -171,10 +180,11 @@ declare class StreamStore {
   }): Stream;
   /**
   * Get a stream by path.
+  * Returns undefined if stream doesn't exist or is expired.
   */
   get(path: string): Stream | undefined;
   /**
-  * Check if a stream exists.
+  * Check if a stream exists (and is not expired).
   */
   has(path: string): boolean;
   /**
@@ -183,7 +193,7 @@ declare class StreamStore {
   delete(path: string): boolean;
   /**
   * 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
   */
@@ -193,6 +203,7 @@ declare class StreamStore {
   }): StreamMessage;
   /**
   * Read messages from a stream starting at the given offset.
+  * @throws Error if stream doesn't exist or is expired
   */
   read(path: string, offset?: string): {
     messages: Array<StreamMessage>;
@@ -201,10 +212,12 @@ declare class StreamStore {
   /**
   * 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: string, messages: Array<StreamMessage>): Uint8Array;
   /**
   * Wait for new messages (long-poll).
+  * @throws Error if stream doesn't exist or is expired
   */
   waitForMessages(path: string, offset: string, timeoutMs: number): Promise<{
     messages: Array<StreamMessage>;
@@ -212,6 +225,7 @@ declare class StreamStore {
   }>;
   /**
   * Get the current offset for a stream.
+  * Returns undefined if stream doesn't exist or is expired.
   */
   getCurrentOffset(path: string): string | undefined;
   /**
@@ -263,6 +277,15 @@ declare class FileBackedStreamStore {
   */
   private streamMetaToStream;
   /**
+  * Check if a stream is expired based on TTL or Expires-At.
+  */
+  private isExpired;
+  /**
+  * Get stream metadata, deleting it if expired.
+  * Returns undefined if stream doesn't exist or is expired.
+  */
+  private getMetaIfNotExpired;
+  /**
   * Close the store, closing all file handles and database.
   * All data is already fsynced on each append, so no final flush needed.
   */
@@ -292,6 +315,7 @@ declare class FileBackedStreamStore {
   /**
   * 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: string, messages: Array<StreamMessage>): Uint8Array;
   getCurrentOffset(streamPath: string): string | undefined;

package/dist/index.js

@@ -65,12 +65,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$2) {
+		const stream = this.streams.get(path$2);
+		if (!stream) return void 0;
+		if (this.isExpired(stream)) {
+			this.delete(path$2);
+			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$2, options = {}) {
-		const existing = this.streams.get(path$2);
+		const existing = this.getIfNotExpired(path$2);
 		if (existing) {
 			const contentTypeMatches = (normalizeContentType(options.contentType) || `application/octet-stream`) === (normalizeContentType(existing.contentType) || `application/octet-stream`);
 			const ttlMatches = options.ttlSeconds === existing.ttlSeconds;
@@ -93,15 +121,16 @@ var StreamStore = class {
 	}
 	/**
 	* Get a stream by path.
+	* Returns undefined if stream doesn't exist or is expired.
 	*/
 	get(path$2) {
-		return this.streams.get(path$2);
+		return this.getIfNotExpired(path$2);
 	}
 	/**
-	* Check if a stream exists.
+	* Check if a stream exists (and is not expired).
 	*/
 	has(path$2) {
-		return this.streams.has(path$2);
+		return this.getIfNotExpired(path$2) !== void 0;
 	}
 	/**
 	* Delete a stream.
@@ -112,12 +141,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$2, data, options = {}) {
-		const stream = this.streams.get(path$2);
+		const stream = this.getIfNotExpired(path$2);
 		if (!stream) throw new Error(`Stream not found: ${path$2}`);
 		if (options.contentType && stream.contentType) {
 			const providedType = normalizeContentType(options.contentType);
@@ -134,9 +163,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$2, offset) {
-		const stream = this.streams.get(path$2);
+		const stream = this.getIfNotExpired(path$2);
 		if (!stream) throw new Error(`Stream not found: ${path$2}`);
 		if (!offset || offset === `-1`) return {
 			messages: [...stream.messages],
@@ -155,9 +185,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$2, messages) {
-		const stream = this.streams.get(path$2);
+		const stream = this.getIfNotExpired(path$2);
 		if (!stream) throw new Error(`Stream not found: ${path$2}`);
 		const totalSize = messages.reduce((sum, m) => sum + m.data.length, 0);
 		const concatenated = new Uint8Array(totalSize);
@@ -171,9 +202,10 @@ var StreamStore = class {
 	}
 	/**
 	* Wait for new messages (long-poll).
+	* @throws Error if stream doesn't exist or is expired
 	*/
 	async waitForMessages(path$2, offset, timeoutMs) {
-		const stream = this.streams.get(path$2);
+		const stream = this.getIfNotExpired(path$2);
 		if (!stream) throw new Error(`Stream not found: ${path$2}`);
 		const { messages } = this.read(path$2, offset);
 		if (messages.length > 0) return {
@@ -206,9 +238,10 @@ var StreamStore = class {
 	}
 	/**
 	* Get the current offset for a stream.
+	* Returns undefined if stream doesn't exist or is expired.
 	*/
 	getCurrentOffset(path$2) {
-		return this.streams.get(path$2)?.currentOffset;
+		return this.getIfNotExpired(path$2)?.currentOffset;
 	}
 	/**
 	* Clear all streams.
@@ -582,6 +615,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.
 	*/
@@ -590,8 +652,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);
@@ -600,6 +661,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,
@@ -633,13 +695,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}`;
@@ -657,8 +717,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);
@@ -706,13 +765,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);
@@ -764,8 +823,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 {
@@ -799,10 +857,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);
@@ -815,8 +873,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() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@durable-streams/server",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Node.js reference server implementation for Durable Streams",
   "author": "Durable Stream contributors",
   "license": "Apache-2.0",
@@ -47,7 +47,7 @@
     "tsdown": "^0.9.0",
     "typescript": "^5.0.0",
     "vitest": "^3.2.4",
-    "@durable-streams/server-conformance-tests": "0.1.2"
+    "@durable-streams/server-conformance-tests": "0.1.3"
   },
   "files": [
     "dist",

package/src/file-store.ts

@@ -332,6 +332,50 @@ export class FileBackedStreamStore {
     }
   }
 
+  /**
+   * Check if a stream is expired based on TTL or Expires-At.
+   */
+  private isExpired(meta: StreamMetadata): boolean {
+    const now = Date.now()
+
+    // Check absolute expiry time
+    if (meta.expiresAt) {
+      const expiryTime = new Date(meta.expiresAt).getTime()
+      // Treat invalid dates (NaN) as expired (fail closed)
+      if (!Number.isFinite(expiryTime) || now >= expiryTime) {
+        return true
+      }
+    }
+
+    // Check TTL (relative to creation time)
+    if (meta.ttlSeconds !== undefined) {
+      const expiryTime = meta.createdAt + meta.ttlSeconds * 1000
+      if (now >= expiryTime) {
+        return true
+      }
+    }
+
+    return false
+  }
+
+  /**
+   * Get stream metadata, deleting it if expired.
+   * Returns undefined if stream doesn't exist or is expired.
+   */
+  private getMetaIfNotExpired(streamPath: string): StreamMetadata | undefined {
+    const key = `stream:${streamPath}`
+    const meta = this.db.get(key) as StreamMetadata | undefined
+    if (!meta) {
+      return undefined
+    }
+    if (this.isExpired(meta)) {
+      // Delete expired stream
+      this.delete(streamPath)
+      return undefined
+    }
+    return meta
+  }
+
   /**
    * Close the store, closing all file handles and database.
    * All data is already fsynced on each append, so no final flush needed.
@@ -354,8 +398,8 @@ export class FileBackedStreamStore {
       initialData?: Uint8Array
     } = {}
   ): Promise<Stream> {
-    const key = `stream:${streamPath}`
-    const existing = this.db.get(key) as StreamMetadata | undefined
+    // Use getMetaIfNotExpired to treat expired streams as non-existent
+    const existing = this.getMetaIfNotExpired(streamPath)
 
     if (existing) {
       // Check if config matches (idempotent create)
@@ -379,6 +423,9 @@ export class FileBackedStreamStore {
       }
     }
 
+    // Define key for LMDB operations
+    const key = `stream:${streamPath}`
+
     // Initialize metadata
     const streamMeta: StreamMetadata = {
       path: streamPath,
@@ -430,14 +477,12 @@ export class FileBackedStreamStore {
   }
 
   get(streamPath: string): Stream | undefined {
-    const key = `stream:${streamPath}`
-    const meta = this.db.get(key) as StreamMetadata | undefined
+    const meta = this.getMetaIfNotExpired(streamPath)
     return meta ? this.streamMetaToStream(meta) : undefined
   }
 
   has(streamPath: string): boolean {
-    const key = `stream:${streamPath}`
-    return this.db.get(key) !== undefined
+    return this.getMetaIfNotExpired(streamPath) !== undefined
   }
 
   delete(streamPath: string): boolean {
@@ -489,8 +534,7 @@ export class FileBackedStreamStore {
       isInitialCreate?: boolean
     } = {}
   ): Promise<StreamMessage | null> {
-    const key = `stream:${streamPath}`
-    const streamMeta = this.db.get(key) as StreamMetadata | undefined
+    const streamMeta = this.getMetaIfNotExpired(streamPath)
 
     if (!streamMeta) {
       throw new Error(`Stream not found: ${streamPath}`)
@@ -583,6 +627,7 @@ export class FileBackedStreamStore {
       lastSeq: options.seq ?? streamMeta.lastSeq,
       totalBytes: streamMeta.totalBytes + processedData.length + 5, // +4 for length, +1 for newline
     }
+    const key = `stream:${streamPath}`
     this.db.putSync(key, updatedMeta)
 
     // 5. Notify long-polls (data is now readable from disk)
@@ -596,8 +641,7 @@ export class FileBackedStreamStore {
     streamPath: string,
     offset?: string
   ): { messages: Array<StreamMessage>; upToDate: boolean } {
-    const key = `stream:${streamPath}`
-    const streamMeta = this.db.get(key) as StreamMetadata | undefined
+    const streamMeta = this.getMetaIfNotExpired(streamPath)
 
     if (!streamMeta) {
       throw new Error(`Stream not found: ${streamPath}`)
@@ -690,8 +734,7 @@ export class FileBackedStreamStore {
     offset: string,
     timeoutMs: number
   ): Promise<{ messages: Array<StreamMessage>; timedOut: boolean }> {
-    const key = `stream:${streamPath}`
-    const streamMeta = this.db.get(key) as StreamMetadata | undefined
+    const streamMeta = this.getMetaIfNotExpired(streamPath)
 
     if (!streamMeta) {
       throw new Error(`Stream not found: ${streamPath}`)
@@ -729,13 +772,13 @@ export class FileBackedStreamStore {
   /**
    * 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: string,
     messages: Array<StreamMessage>
   ): Uint8Array {
-    const key = `stream:${streamPath}`
-    const streamMeta = this.db.get(key) as StreamMetadata | undefined
+    const streamMeta = this.getMetaIfNotExpired(streamPath)
 
     if (!streamMeta) {
       throw new Error(`Stream not found: ${streamPath}`)
@@ -759,8 +802,7 @@ export class FileBackedStreamStore {
   }
 
   getCurrentOffset(streamPath: string): string | undefined {
-    const key = `stream:${streamPath}`
-    const streamMeta = this.db.get(key) as StreamMetadata | undefined
+    const streamMeta = this.getMetaIfNotExpired(streamPath)
     return streamMeta?.currentOffset
   }
 

package/src/store.ts

@@ -83,6 +83,49 @@ export class StreamStore {
   private streams = new Map<string, Stream>()
   private pendingLongPolls: Array<PendingLongPoll> = []
 
+  /**
+   * Check if a stream is expired based on TTL or Expires-At.
+   */
+  private isExpired(stream: Stream): boolean {
+    const now = Date.now()
+
+    // Check absolute expiry time
+    if (stream.expiresAt) {
+      const expiryTime = new Date(stream.expiresAt).getTime()
+      // Treat invalid dates (NaN) as expired (fail closed)
+      if (!Number.isFinite(expiryTime) || now >= expiryTime) {
+        return true
+      }
+    }
+
+    // Check TTL (relative to creation time)
+    if (stream.ttlSeconds !== undefined) {
+      const expiryTime = stream.createdAt + stream.ttlSeconds * 1000
+      if (now >= expiryTime) {
+        return true
+      }
+    }
+
+    return false
+  }
+
+  /**
+   * Get a stream, deleting it if expired.
+   * Returns undefined if stream doesn't exist or is expired.
+   */
+  private getIfNotExpired(path: string): Stream | undefined {
+    const stream = this.streams.get(path)
+    if (!stream) {
+      return undefined
+    }
+    if (this.isExpired(stream)) {
+      // Delete expired stream
+      this.delete(path)
+      return undefined
+    }
+    return stream
+  }
+
   /**
    * Create a new stream.
    * @throws Error if stream already exists with different config
@@ -97,7 +140,8 @@ export class StreamStore {
       initialData?: Uint8Array
     } = {}
   ): Stream {
-    const existing = this.streams.get(path)
+    // Use getIfNotExpired to treat expired streams as non-existent
+    const existing = this.getIfNotExpired(path)
     if (existing) {
       // Check if config matches (idempotent create)
       const contentTypeMatches =
@@ -140,16 +184,17 @@ export class StreamStore {
 
   /**
    * Get a stream by path.
+   * Returns undefined if stream doesn't exist or is expired.
    */
   get(path: string): Stream | undefined {
-    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: string): boolean {
-    return this.streams.has(path)
+    return this.getIfNotExpired(path) !== undefined
   }
 
   /**
@@ -163,7 +208,7 @@ export class StreamStore {
 
   /**
    * 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
    */
@@ -172,7 +217,7 @@ export class StreamStore {
     data: Uint8Array,
     options: { seq?: string; contentType?: string } = {}
   ): StreamMessage {
-    const stream = this.streams.get(path)
+    const stream = this.getIfNotExpired(path)
     if (!stream) {
       throw new Error(`Stream not found: ${path}`)
     }
@@ -210,12 +255,13 @@ export class StreamStore {
 
   /**
    * Read messages from a stream starting at the given offset.
+   * @throws Error if stream doesn't exist or is expired
    */
   read(
     path: string,
     offset?: string
   ): { messages: Array<StreamMessage>; upToDate: boolean } {
-    const stream = this.streams.get(path)
+    const stream = this.getIfNotExpired(path)
     if (!stream) {
       throw new Error(`Stream not found: ${path}`)
     }
@@ -247,9 +293,10 @@ export class StreamStore {
   /**
    * 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: string, messages: Array<StreamMessage>): Uint8Array {
-    const stream = this.streams.get(path)
+    const stream = this.getIfNotExpired(path)
     if (!stream) {
       throw new Error(`Stream not found: ${path}`)
     }
@@ -273,13 +320,14 @@ export class StreamStore {
 
   /**
    * Wait for new messages (long-poll).
+   * @throws Error if stream doesn't exist or is expired
    */
   async waitForMessages(
     path: string,
     offset: string,
     timeoutMs: number
   ): Promise<{ messages: Array<StreamMessage>; timedOut: boolean }> {
-    const stream = this.streams.get(path)
+    const stream = this.getIfNotExpired(path)
     if (!stream) {
       throw new Error(`Stream not found: ${path}`)
     }
@@ -315,9 +363,10 @@ export class StreamStore {
 
   /**
    * Get the current offset for a stream.
+   * Returns undefined if stream doesn't exist or is expired.
    */
   getCurrentOffset(path: string): string | undefined {
-    return this.streams.get(path)?.currentOffset
+    return this.getIfNotExpired(path)?.currentOffset
   }
 
   /**