lopata 0.7.0 → 0.8.2

package/src/testing/durable-object.ts

@@ -0,0 +1,325 @@
+import type { InProcessExecutor } from '../bindings/do-executor-inprocess'
+import type { DurableObjectNamespaceImpl, SqliteDurableObjectStorage } from '../bindings/durable-object'
+import type { SqlStorage } from '../bindings/durable-object'
+import type { CFWebSocket } from '../bindings/websocket-pair'
+
+export class TestDurableObjectStorage {
+	private storage: SqliteDurableObjectStorage
+
+	constructor(storage: SqliteDurableObjectStorage) {
+		this.storage = storage
+	}
+
+	async get<T = unknown>(key: string): Promise<T | undefined>
+	async get<T = unknown>(keys: string[]): Promise<Map<string, T>>
+	async get<T = unknown>(keyOrKeys: string | string[]): Promise<T | undefined | Map<string, T>> {
+		return this.storage.get(keyOrKeys as any)
+	}
+
+	async list(
+		options?: { prefix?: string; start?: string; startAfter?: string; end?: string; limit?: number; reverse?: boolean },
+	): Promise<Map<string, unknown>> {
+		return this.storage.list(options)
+	}
+
+	async put(key: string, value: unknown): Promise<void>
+	async put(entries: Record<string, unknown>): Promise<void>
+	async put(keyOrEntries: string | Record<string, unknown>, value?: unknown): Promise<void> {
+		if (typeof keyOrEntries === 'string') {
+			return this.storage.put(keyOrEntries, value)
+		}
+		return this.storage.put(keyOrEntries)
+	}
+
+	async delete(key: string): Promise<boolean>
+	async delete(keys: string[]): Promise<number>
+	async delete(keyOrKeys: string | string[]): Promise<boolean | number> {
+		return this.storage.delete(keyOrKeys as any)
+	}
+
+	async deleteAll(): Promise<void> {
+		return this.storage.deleteAll()
+	}
+
+	async getAlarm(): Promise<number | null> {
+		return this.storage.getAlarm()
+	}
+
+	async setAlarm(scheduledTime: number | Date): Promise<void> {
+		return this.storage.setAlarm(scheduledTime)
+	}
+
+	async deleteAlarm(): Promise<void> {
+		return this.storage.deleteAlarm()
+	}
+}
+
+// --- TestWebSocket ---
+
+export class TestWebSocket {
+	readonly raw: CFWebSocket
+	private _messages: (string | ArrayBuffer)[] = []
+	private _messageWaiters: { resolve: (msg: string | ArrayBuffer) => void; reject: (err: Error) => void }[] = []
+	private _closeWaiters: { resolve: (ev: { code: number; reason: string }) => void; reject: (err: Error) => void }[] = []
+	private _closed = false
+	private _closeData: { code: number; reason: string } | null = null
+
+	constructor(ws: CFWebSocket) {
+		this.raw = ws
+
+		ws.addEventListener('message', (event: Event) => {
+			const data = (event as MessageEvent).data as string | ArrayBuffer
+			const waiter = this._messageWaiters.shift()
+			if (waiter) {
+				waiter.resolve(data)
+			} else {
+				this._messages.push(data)
+			}
+		})
+
+		ws.addEventListener('close', (event: Event) => {
+			this._closed = true
+			const ce = event as CloseEvent
+			const closeData = { code: ce.code, reason: ce.reason }
+			this._closeData = closeData
+			// Reject all pending message waiters
+			for (const w of this._messageWaiters) {
+				w.reject(new Error('WebSocket closed'))
+			}
+			this._messageWaiters = []
+			// Resolve close waiters
+			for (const w of this._closeWaiters) {
+				w.resolve(closeData)
+			}
+			this._closeWaiters = []
+		})
+	}
+
+	get readyState(): number {
+		return this.raw.readyState
+	}
+
+	/** All received messages so far. */
+	get messages(): ReadonlyArray<string | ArrayBuffer> {
+		return this._messages
+	}
+
+	/** Send data to the DO via the WebSocket. */
+	send(data: string | ArrayBuffer | ArrayBufferView): void {
+		this.raw.send(data)
+	}
+
+	/** Wait for the next message from the DO. */
+	waitForMessage(timeout = 5000): Promise<string | ArrayBuffer> {
+		// Check queue first
+		const queued = this._messages.shift()
+		if (queued !== undefined) return Promise.resolve(queued)
+
+		if (this._closed) return Promise.reject(new Error('WebSocket closed'))
+
+		return new Promise<string | ArrayBuffer>((resolve, reject) => {
+			const timer = setTimeout(() => {
+				const idx = this._messageWaiters.findIndex(w => w.resolve === resolve)
+				if (idx !== -1) this._messageWaiters.splice(idx, 1)
+				reject(new Error(`waitForMessage timed out after ${timeout}ms`))
+			}, timeout)
+
+			this._messageWaiters.push({
+				resolve: (msg) => {
+					clearTimeout(timer)
+					resolve(msg)
+				},
+				reject: (err) => {
+					clearTimeout(timer)
+					reject(err)
+				},
+			})
+		})
+	}
+
+	/** Wait for the WebSocket to close. */
+	waitForClose(timeout = 5000): Promise<{ code: number; reason: string }> {
+		if (this._closed) {
+			return Promise.resolve(this._closeData ?? { code: 1000, reason: '' })
+		}
+
+		return new Promise<{ code: number; reason: string }>((resolve, reject) => {
+			const timer = setTimeout(() => {
+				const idx = this._closeWaiters.findIndex(w => w.resolve === resolve)
+				if (idx !== -1) this._closeWaiters.splice(idx, 1)
+				reject(new Error(`waitForClose timed out after ${timeout}ms`))
+			}, timeout)
+
+			this._closeWaiters.push({
+				resolve: (ev) => {
+					clearTimeout(timer)
+					resolve(ev)
+				},
+				reject: (err) => {
+					clearTimeout(timer)
+					reject(err)
+				},
+			})
+		})
+	}
+
+	/** Close the WebSocket from the client side. */
+	close(code?: number, reason?: string): void {
+		this.raw.close(code, reason)
+	}
+
+	/** Read the server-side WebSocket's serialized attachment. */
+	deserializeAttachment(): unknown {
+		const peer = this.raw._peer
+		if (!peer) return null
+		return peer.deserializeAttachment()
+	}
+
+	/** Write to the server-side WebSocket's serialized attachment. */
+	serializeAttachment(value: unknown): void {
+		const peer = this.raw._peer
+		if (!peer) throw new Error('No peer WebSocket')
+		peer.serializeAttachment(value)
+	}
+}
+
+// --- TestDurableObjectHandle ---
+
+export class TestDurableObjectHandle {
+	private namespace: DurableObjectNamespaceImpl
+	private idStr: string
+	private _stub: unknown | null = null
+
+	constructor(namespace: DurableObjectNamespaceImpl, idStr: string) {
+		this.namespace = namespace
+		this.idStr = idStr
+	}
+
+	/** The DO instance ID. */
+	get id(): string {
+		return this.idStr
+	}
+
+	/** RPC proxy stub. Forces executor creation on first access. */
+	get stub(): any {
+		if (!this._stub) {
+			const doId = this.namespace.idFromString(this.idStr)
+			this._stub = this.namespace.get(doId)
+		}
+		return this._stub
+	}
+
+	private getExecutor(): InProcessExecutor {
+		// Ensure executor exists by accessing the stub
+		// eslint-disable-next-line @typescript-eslint/no-unused-expressions
+		this.stub
+		const executor = this.namespace._getExecutor(this.idStr)
+		if (!executor) throw new Error(`Durable Object executor not found for ${this.idStr}`)
+		return executor as InProcessExecutor
+	}
+
+	/** Access KV-style storage for this DO instance. */
+	get storage(): TestDurableObjectStorage {
+		const executor = this.getExecutor()
+		return new TestDurableObjectStorage(executor._rawState.storage)
+	}
+
+	/** Access SQL storage for this DO instance. */
+	get sql(): SqlStorage {
+		const executor = this.getExecutor()
+		return executor._rawState.storage.sql
+	}
+
+	/** Get the scheduled alarm time, or null. */
+	async getAlarm(): Promise<number | null> {
+		const executor = this.getExecutor()
+		return executor._rawState.storage.getAlarm()
+	}
+
+	/** Trigger the alarm handler immediately. */
+	async triggerAlarm(): Promise<void> {
+		return this.namespace.triggerAlarm(this.idStr)
+	}
+
+	/** Cancel a scheduled alarm without firing it. */
+	async cancelAlarm(): Promise<void> {
+		this.namespace.cancelAlarm(this.idStr)
+	}
+
+	/** Delete this DO instance and all its data. */
+	async delete(): Promise<void> {
+		this.namespace.deleteInstance(this.idStr)
+		this._stub = null
+	}
+
+	/** Connect a WebSocket to this DO, simulating the upgrade handshake. */
+	async connectWebSocket(options?: {
+		path?: string
+		headers?: Record<string, string>
+	}): Promise<TestWebSocket> {
+		const executor = this.getExecutor()
+		const path = options?.path ?? '/'
+		const url = `http://localhost${path}`
+		const headers = new Headers(options?.headers)
+		headers.set('upgrade', 'websocket')
+
+		const request = new Request(url, { headers })
+		const response = await executor.executeFetch(request)
+
+		// Extract the server-side WebSocket from the response
+		const serverWs = (response as any).webSocket as CFWebSocket | undefined
+		if (!serverWs) {
+			throw new Error('DO fetch handler did not return a WebSocket upgrade response (no response.webSocket)')
+		}
+
+		// Accept the client side (simulates what Bun.serve does)
+		serverWs.accept()
+
+		return new TestWebSocket(serverWs)
+	}
+
+	/** Get all accepted WebSockets for this DO instance (via DurableObjectState). */
+	getWebSockets(tag?: string): WebSocket[] {
+		const executor = this.getExecutor()
+		return executor._rawState.getWebSockets(tag)
+	}
+
+	/** Get tags for a specific WebSocket. */
+	getTags(ws: WebSocket): string[] {
+		const executor = this.getExecutor()
+		return executor._rawState.getTags(ws)
+	}
+}
+
+export class TestDurableObjectNamespace {
+	private namespace: DurableObjectNamespaceImpl
+	private handles: TestDurableObjectHandle[] = []
+
+	constructor(namespace: DurableObjectNamespaceImpl) {
+		this.namespace = namespace
+	}
+
+	/** Get a DO handle by name (uses idFromName). */
+	get(name: string): TestDurableObjectHandle {
+		const doId = this.namespace.idFromName(name)
+		const handle = new TestDurableObjectHandle(this.namespace, doId.toString())
+		this.handles.push(handle)
+		return handle
+	}
+
+	/** Get a DO handle by raw ID string. */
+	getById(idStr: string): TestDurableObjectHandle {
+		const handle = new TestDurableObjectHandle(this.namespace, idStr)
+		this.handles.push(handle)
+		return handle
+	}
+
+	/** List all instance IDs in this namespace. */
+	listIds(): string[] {
+		return this.namespace._listInstanceIds()
+	}
+
+	dispose(): void {
+		this.handles = []
+	}
+}

package/src/testing/env-builder.ts

@@ -0,0 +1,126 @@
+import { Database } from 'bun:sqlite'
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { LocalD1Database } from '../bindings/d1'
+import type { DurableObjectNamespaceImpl } from '../bindings/durable-object'
+import { SqliteKVNamespace } from '../bindings/kv'
+import { SqliteQueueProducer } from '../bindings/queue'
+import { FileR2Bucket } from '../bindings/r2'
+import { createServiceBinding } from '../bindings/service-binding'
+import type { SqliteWorkflowBinding } from '../bindings/workflow'
+import type { WranglerConfig } from '../config'
+import { runMigrations } from '../db'
+import type { Clock } from './clock'
+import type { BindingSpec } from './types'
+
+interface ServiceBindingEntry {
+	bindingName: string
+	serviceName: string
+	entrypoint?: string
+	proxy: Record<string, unknown>
+}
+
+export interface TestClassRegistry {
+	durableObjects: { bindingName: string; className: string; namespace: DurableObjectNamespaceImpl }[]
+	workflows: { bindingName: string; className: string; binding: SqliteWorkflowBinding }[]
+	serviceBindings: ServiceBindingEntry[]
+}
+
+export interface BuiltTestEnv {
+	db: Database
+	env: Record<string, unknown>
+	registry: TestClassRegistry
+	tmpDirs: string[]
+}
+
+export function buildTestEnv(
+	bindings: Record<string, BindingSpec> | undefined,
+	vars: Record<string, string> | undefined,
+	clock?: Clock,
+): BuiltTestEnv {
+	const db = new Database(':memory:')
+	runMigrations(db)
+
+	const env: Record<string, unknown> = {}
+	const registry: TestClassRegistry = { durableObjects: [], workflows: [], serviceBindings: [] }
+	const tmpDirs: string[] = []
+
+	if (vars) {
+		for (const [key, value] of Object.entries(vars)) {
+			env[key] = value
+		}
+	}
+
+	if (!bindings) {
+		return { db, env, registry, tmpDirs }
+	}
+
+	for (const [bindingName, spec] of Object.entries(bindings)) {
+		if (spec === 'kv') {
+			env[bindingName] = new SqliteKVNamespace(db, bindingName, undefined, clock)
+		} else if (spec === 'r2') {
+			const tmpDir = mkdtempSync(join(tmpdir(), 'lopata-test-r2-'))
+			tmpDirs.push(tmpDir)
+			env[bindingName] = new FileR2Bucket(db, bindingName, tmpDir)
+		} else if (spec === 'd1') {
+			env[bindingName] = new LocalD1Database(new Database(':memory:'))
+		} else if (spec === 'queue') {
+			env[bindingName] = new SqliteQueueProducer(db, bindingName, 0, undefined, clock)
+		} else if (typeof spec === 'object') {
+			if (spec.type === 'durable-object') {
+				// Lazy import to avoid pulling in the whole DO module at parse time
+				const { DurableObjectNamespaceImpl } = require('../bindings/durable-object')
+				const namespace = new DurableObjectNamespaceImpl(db, spec.className, undefined, { evictionTimeoutMs: 0 }, undefined, clock)
+				env[bindingName] = namespace
+				registry.durableObjects.push({ bindingName, className: spec.className, namespace })
+			} else if (spec.type === 'workflow') {
+				const { SqliteWorkflowBinding } = require('../bindings/workflow')
+				const binding = new SqliteWorkflowBinding(db, bindingName, spec.className, undefined, clock)
+				env[bindingName] = binding
+				registry.workflows.push({ bindingName, className: spec.className, binding })
+			} else if (spec.type === 'service') {
+				const proxy = createServiceBinding(spec.service, spec.entrypoint)
+				env[bindingName] = proxy
+				registry.serviceBindings.push({
+					bindingName,
+					serviceName: spec.service,
+					entrypoint: spec.entrypoint,
+					proxy,
+				})
+			}
+		}
+	}
+
+	return { db, env, registry, tmpDirs }
+}
+
+/** Translate a WranglerConfig into a flat BindingSpec map + vars */
+export function configToBindings(config: WranglerConfig): { bindings: Record<string, BindingSpec>; vars: Record<string, string> } {
+	const bindings: Record<string, BindingSpec> = {}
+	const vars: Record<string, string> = { ...config.vars }
+
+	for (const kv of config.kv_namespaces ?? []) {
+		bindings[kv.binding] = 'kv'
+	}
+	for (const r2 of config.r2_buckets ?? []) {
+		bindings[r2.binding] = 'r2'
+	}
+	for (const d1 of config.d1_databases ?? []) {
+		bindings[d1.binding] = 'd1'
+	}
+	for (const producer of config.queues?.producers ?? []) {
+		bindings[producer.binding] = 'queue'
+	}
+	for (const doBinding of config.durable_objects?.bindings ?? []) {
+		bindings[doBinding.name] = { type: 'durable-object', className: doBinding.class_name }
+	}
+	for (const wf of config.workflows ?? []) {
+		bindings[wf.binding] = { type: 'workflow', className: wf.class_name }
+	}
+	for (const svc of config.services ?? []) {
+		bindings[svc.binding] = { type: 'service', service: svc.service, entrypoint: svc.entrypoint }
+	}
+
+	return { bindings, vars }
+}

package/src/testing/fetch-mock.ts

@@ -0,0 +1,145 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+export interface FetchCall {
+	request: Request
+	url: string
+	method: string
+	response: Response | null
+	mocked: boolean
+	timestamp: number
+}
+
+type MatchFn = (req: Request) => boolean
+type HandlerFn = (req: Request) => Response | Promise<Response>
+
+interface MockRoute {
+	match: MatchFn
+	handler: HandlerFn
+	method?: string
+}
+
+const fetchMockStorage = new AsyncLocalStorage<FetchMock>()
+
+export function getActiveFetchMock(): FetchMock | undefined {
+	return fetchMockStorage.getStore()
+}
+
+export function runWithFetchMock<T>(mock: FetchMock, fn: () => T): T {
+	return fetchMockStorage.run(mock, fn)
+}
+
+function toHandlerFn(handler: Response | HandlerFn): HandlerFn {
+	if (typeof handler === 'function') return handler
+	return () => (handler as any).clone()
+}
+
+export class FetchMock {
+	private routes: MockRoute[] = []
+	private _calls: FetchCall[] = []
+	private _passthrough = true
+
+	/** Add a mock route. Unmatched requests will throw unless passthrough() is called. */
+	on(match: string | RegExp | ((req: Request) => boolean), handler: Response | HandlerFn): this {
+		const matchFn = this.toMatchFn(match)
+		this.routes.push({ match: matchFn, handler: toHandlerFn(handler) })
+		this._passthrough = false
+		return this
+	}
+
+	/** Add a mock route for GET requests only. */
+	onGet(match: string | RegExp | ((req: Request) => boolean), handler: Response | HandlerFn): this {
+		const matchFn = this.toMatchFn(match)
+		this.routes.push({ match: matchFn, handler: toHandlerFn(handler), method: 'GET' })
+		this._passthrough = false
+		return this
+	}
+
+	/** Add a mock route for POST requests only. */
+	onPost(match: string | RegExp | ((req: Request) => boolean), handler: Response | HandlerFn): this {
+		const matchFn = this.toMatchFn(match)
+		this.routes.push({ match: matchFn, handler: toHandlerFn(handler), method: 'POST' })
+		this._passthrough = false
+		return this
+	}
+
+	/** Allow unmatched requests to pass through to the real network. */
+	passthrough(): this {
+		this._passthrough = true
+		return this
+	}
+
+	/** All recorded fetch calls. */
+	get calls(): readonly FetchCall[] {
+		return this._calls
+	}
+
+	/** Get recorded calls, optionally filtered by URL match. */
+	getCalls(match?: string | RegExp | ((req: Request) => boolean)): FetchCall[] {
+		if (!match) return [...this._calls]
+		const matchFn = this.toMatchFn(match)
+		return this._calls.filter(c => matchFn(c.request))
+	}
+
+	/** Reset all routes and recorded calls. */
+	reset(): void {
+		this.routes = []
+		this._calls = []
+		this._passthrough = true
+	}
+
+	/** @internal Handle a fetch request from the intercepted globalThis.fetch */
+	async _handle(request: Request): Promise<{ response: Response; mocked: boolean } | null> {
+		for (const route of this.routes) {
+			if (route.method && request.method !== route.method) continue
+			if (route.match(request)) {
+				const response = await route.handler(request)
+				const call: FetchCall = {
+					request,
+					url: request.url,
+					method: request.method,
+					response,
+					mocked: true,
+					timestamp: Date.now(),
+				}
+				this._calls.push(call)
+				return { response, mocked: true }
+			}
+		}
+
+		// No route matched
+		if (this._passthrough) {
+			return null // let the original fetch handle it
+		}
+
+		// Strict mode — no route matched and passthrough is disabled
+		const call: FetchCall = {
+			request,
+			url: request.url,
+			method: request.method,
+			response: null,
+			mocked: false,
+			timestamp: Date.now(),
+		}
+		this._calls.push(call)
+		throw new Error(`FetchMock: no route matched for ${request.method} ${request.url} (passthrough disabled)`)
+	}
+
+	/** @internal Record a passthrough call */
+	_recordPassthrough(request: Request, response: Response): void {
+		this._calls.push({
+			request,
+			url: request.url,
+			method: request.method,
+			response,
+			mocked: false,
+			timestamp: Date.now(),
+		})
+	}
+
+	private toMatchFn(match: string | RegExp | ((req: Request) => boolean)): MatchFn {
+		if (typeof match === 'function') return match
+		if (match instanceof RegExp) return (req) => match.test(req.url)
+		// String: prefix match
+		return (req) => req.url.startsWith(match)
+	}
+}