lopata 0.18.3 → 0.19.0

package/src/bindings/scheduled.ts

@@ -1,4 +1,3 @@
-import { ExecutionContext } from '../execution-context'
 import { persistError, startSpan } from '../tracing/span'
 
 export interface ScheduledController {
@@ -269,39 +268,47 @@ export function createScheduledController(cron: string, scheduledTime: number):
 	}
 }
 
-type ScheduledHandler = (controller: ScheduledController, env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>
-
-export function startCronScheduler(
+/**
+ * Generic cron timer. `invoke` is called with the matched expression and the
+ * tick time; the caller decides how to dispatch (in-process handler vs RPC).
+ */
+export function startCronTimer(
 	crons: string[],
-	handler: ScheduledHandler,
-	env: Record<string, unknown>,
+	invoke: (cronExpr: string, now: Date) => Promise<unknown>,
 	workerName?: string,
+	/**
+	 * Per-cron last-fired-minute dedup state, keyed by cron expression. Pass a map
+	 * OWNED BY THE GENERATION MANAGER (not per-generation) so it survives reloads:
+	 * a fresh per-generation map would start empty and re-fire a cron for a minute
+	 * the previous generation already handled — for `* * * * *` that's nearly every
+	 * save. Defaults to a local map for standalone callers/tests.
+	 */
+	lastFiredMinute: Map<string, number> = new Map(),
 ): NodeJS.Timer {
 	const parsed = crons.map(parseCron)
 
-	// Check every 60 seconds, aligned to the start of each minute
-	const interval = setInterval(() => {
+	// Poll a few times per minute and fire each cron at most once per matching
+	// wall-clock minute. `setInterval` is NOT minute-aligned (it fires relative
+	// to creation, and HMR reload resets that phase), so a once-per-60s check
+	// could drift past a matching minute or land on it twice. Polling at 15s +
+	// per-minute dedup makes firing robust to that drift.
+	return setInterval(() => {
 		const now = new Date()
-		for (const cron of parsed) {
-			if (cronMatchesDate(cron, now)) {
-				const controller = createScheduledController(cron.expression, now.getTime())
-				const ctx = new ExecutionContext()
-				console.log(`[lopata] Cron triggered: ${cron.expression}`)
-				startSpan({
-					name: 'scheduled',
-					kind: 'server',
-					attributes: { cron: cron.expression },
-					workerName,
-				}, async () => {
-					await handler(controller, env, ctx)
-					await ctx._awaitAll()
-				}).catch((err) => {
-					console.error(`[lopata] Scheduled handler error (${cron.expression}):`, err)
-					persistError(err, 'scheduled', workerName)
-				})
-			}
-		}
-	}, 60_000)
-
-	return interval
+		const minuteKey = Math.floor(now.getTime() / 60_000)
+		parsed.forEach((cron) => {
+			if (!cronMatchesDate(cron, now)) return
+			if (lastFiredMinute.get(cron.expression) === minuteKey) return
+			lastFiredMinute.set(cron.expression, minuteKey)
+			console.log(`[lopata] Cron triggered: ${cron.expression}`)
+			startSpan({
+				name: 'scheduled',
+				kind: 'server',
+				attributes: { cron: cron.expression },
+				workerName,
+			}, () => invoke(cron.expression, now)).catch((err) => {
+				console.error(`[lopata] Scheduled handler error (${cron.expression}):`, err)
+				persistError(err, 'scheduled', workerName)
+			})
+		})
+	}, 15_000)
 }

package/src/bindings/service-binding.ts

@@ -11,6 +11,7 @@
 import { ExecutionContext } from '../execution-context'
 import { warnInvalidRpcArgs } from '../rpc-validate'
 import { getActiveContext, runWithContext } from '../tracing/context'
+import type { ResolvedTarget } from '../worker-registry'
 import { createRpcFunctionStub, NON_RPC_PROPS, wrapRpcReturnValue } from './rpc-stub'
 
 type WorkerModule = Record<string, unknown>
@@ -30,8 +31,41 @@ const SERVICE_BINDING_DEFAULTS: Required<ServiceBindingLimits> = {
 // Internal properties that should be forwarded to the ServiceBinding instance
 const INTERNAL_PROPS = new Set(['_wire', 'isWired', '_subrequestCount'])
 
+/** Error thrown by `connect()` (both in-process and worker-thread paths). */
+export function serviceBindingConnectError(name: string): Error {
+	return new Error(`Service binding "${name}": connect() (TCP sockets) is not supported in local dev mode`)
+}
+
+/**
+ * Resolve the call target for a service binding RPC (`fetch` or method):
+ * a named entrypoint class, an unnamed default class, or the default object.
+ *
+ * Used by `ServiceBinding._getTarget` (in-process) and the worker-thread's
+ * `invokeEntrypointRpc`. Single source of truth so the in-process and
+ * thread-mode paths can't drift.
+ */
+export function resolveEntrypointTarget(
+	workerModule: Record<string, unknown>,
+	entrypoint: string | undefined,
+	ctx: unknown,
+	env: unknown,
+): Record<string, unknown> {
+	if (entrypoint) {
+		const cls = workerModule[entrypoint]
+		if (typeof cls !== 'function') {
+			throw new Error(`Entrypoint "${entrypoint}" not exported from worker module`)
+		}
+		return new (cls as new(ctx: unknown, env: unknown) => Record<string, unknown>)(ctx, env)
+	}
+	const def = workerModule.default
+	if (typeof def === 'function' && def.prototype) {
+		return new (def as new(ctx: unknown, env: unknown) => Record<string, unknown>)(ctx, env)
+	}
+	return def as Record<string, unknown>
+}
+
 export class ServiceBinding {
-	private _resolver: (() => { workerModule: Record<string, unknown>; env: Record<string, unknown> }) | null = null
+	private _resolver: (() => ResolvedTarget) | null = null
 	private _entrypoint: string | undefined
 	private _serviceName: string
 	private _limits: Required<ServiceBindingLimits>
@@ -47,17 +81,17 @@ export class ServiceBinding {
 	}
 
 	_wire(
-		resolverOrModule: (() => { workerModule: Record<string, unknown>; env: Record<string, unknown> }) | Record<string, unknown>,
+		resolverOrModule: (() => ResolvedTarget) | Record<string, unknown>,
 		env?: Record<string, unknown>,
 	): void {
 		if (typeof resolverOrModule === 'function' && env === undefined) {
 			// New API: resolver function
-			this._resolver = resolverOrModule as () => { workerModule: Record<string, unknown>; env: Record<string, unknown> }
+			this._resolver = resolverOrModule as () => ResolvedTarget
 		} else {
 			// Legacy API: _wire(workerModule, env)
 			const workerModule = resolverOrModule as Record<string, unknown>
 			const capturedEnv = env!
-			this._resolver = () => ({ workerModule, env: capturedEnv })
+			this._resolver = () => ({ kind: 'in-process', workerModule, env: capturedEnv })
 		}
 	}
 
@@ -65,7 +99,7 @@ export class ServiceBinding {
 		return this._resolver !== null
 	}
 
-	private _resolve(): { workerModule: Record<string, unknown>; env: Record<string, unknown> } {
+	private _resolve(): ResolvedTarget {
 		if (!this._resolver) {
 			throw new Error(`Service binding "${this._serviceName}" is not wired — target worker not loaded`)
 		}
@@ -73,8 +107,15 @@ export class ServiceBinding {
 	}
 
 	private _checkSubrequestLimit(): void {
-		this._subrequestCount++
-		if (this._subrequestCount > this._limits.maxSubrequests) {
+		// Prefer the per-top-level-request counter on the active span context so
+		// the budget resets each incoming request (Cloudflare semantics). Fall
+		// back to the per-binding counter only when there is no request context
+		// (direct or programmatic use, e.g. tests) — otherwise the count would
+		// leak across the whole dev-server lifetime and eventually 500 every
+		// asset request that goes through a service binding.
+		const requestCounter = getActiveContext()?.subrequests
+		const count = requestCounter ? ++requestCounter.count : ++this._subrequestCount
+		if (count > this._limits.maxSubrequests) {
 			throw new Error(
 				`Service binding "${this._serviceName}": subrequest limit exceeded (max ${this._limits.maxSubrequests})`,
 			)
@@ -82,39 +123,37 @@ export class ServiceBinding {
 	}
 
 	private _getTarget(ctx?: ExecutionContext): Record<string, unknown> {
-		const { workerModule, env } = this._resolve()
-		const execCtx = ctx ?? new ExecutionContext(this._props)
-		if (this._entrypoint) {
-			const cls = workerModule[this._entrypoint] as (new(...args: unknown[]) => Record<string, unknown>) | undefined
-			if (!cls) {
-				throw new Error(`Entrypoint "${this._entrypoint}" not exported from worker module`)
-			}
-			return new cls(execCtx, env)
-		}
-		// Default export: could be class-based or object-based
-		const def = workerModule.default
-		if (typeof def === 'function' && def.prototype && typeof def.prototype.fetch === 'function') {
-			return new (def as new(ctx: ExecutionContext, env: unknown) => Record<string, unknown>)(execCtx, env)
+		const resolved = this._resolve()
+		if (resolved.kind !== 'in-process') {
+			throw new Error(
+				`Service binding "${this._serviceName}": in-process resolve attempted but the target worker runs in thread isolation — calls must route through the thread executor`,
+			)
 		}
-		return def as Record<string, unknown>
+		const execCtx = ctx ?? new ExecutionContext(this._props)
+		return resolveEntrypointTarget(resolved.workerModule, this._entrypoint, execCtx, resolved.env)
 	}
 
 	async fetch(input: Request | string | URL, init?: RequestInit): Promise<Response> {
+		const url = input instanceof URL ? input.toString() : input
+		const request = typeof url === 'string' ? new Request(url, init) : url
+
+		// Resolve first so a missing target throws the real error instead of
+		// burning a slot in the per-request subrequest budget on every failed call.
+		const resolved = this._resolve()
 		this._checkSubrequestLimit()
+		if (resolved.kind === 'thread') {
+			return resolved.executor.executeFetch(request, this._props)
+		}
+
 		const execCtx = new ExecutionContext(this._props)
 		const target = this._getTarget(execCtx)
 		if (!target?.fetch || typeof target.fetch !== 'function') {
 			throw new Error(`Service binding "${this._serviceName}" target has no fetch() handler`)
 		}
-		const url = input instanceof URL ? input.toString() : input
-		const request = typeof url === 'string' ? new Request(url, init) : url
-		// Class-based entrypoints receive (request) — env/ctx via constructor
-		// Object-based entrypoints receive (request, env, ctx)
-		const { workerModule, env } = this._resolve()
+		const { workerModule, env } = resolved
 		const def = workerModule.default
 		const isClass = this._entrypoint || (typeof def === 'function' && def.prototype?.fetch)
 
-		// Propagate trace context to target worker so child spans link correctly
 		const parentCtx = getActiveContext()
 		const doCall = async () => {
 			const response = isClass
@@ -131,9 +170,7 @@ export class ServiceBinding {
 	}
 
 	connect(_address: string | { hostname: string; port: number }): never {
-		throw new Error(
-			`Service binding "${this._serviceName}": connect() (TCP sockets) is not supported in local dev mode`,
-		)
+		throw serviceBindingConnectError(this._serviceName)
 	}
 
 	toProxy(): Record<string, unknown> {
@@ -166,8 +203,15 @@ export class ServiceBinding {
 				// If called as a function → RPC method call (always returns Promise)
 				// If awaited → RPC property read (returns Promise of the property value)
 				const rpcCallable = (...args: unknown[]) => {
-					self._checkSubrequestLimit()
 					warnInvalidRpcArgs(args, prop)
+					// Resolve first so a missing target throws the real error before
+					// the budget moves.
+					const resolved = self._resolve()
+					self._checkSubrequestLimit()
+					if (resolved.kind === 'thread') {
+						return resolved.executor.executeEntrypointRpc(self._entrypoint, prop, args, self._props)
+							.then((r) => wrapRpcReturnValue(r, prop))
+					}
 					const target = self._getTarget()
 					const member = target[prop]
 					if (typeof member !== 'function') {
@@ -188,18 +232,35 @@ export class ServiceBinding {
 					onFulfilled?: ((value: unknown) => unknown) | null,
 					onRejected?: ((reason: unknown) => unknown) | null,
 				) => {
+					// Resolve before incrementing so a missing target doesn't burn budget.
+					const resolved = self._resolve()
 					self._checkSubrequestLimit()
-					const promise = new Promise<unknown>((resolve, reject) => {
+					if (resolved.kind === 'thread') {
+						const executor = resolved.executor
+						const entrypoint = self._entrypoint
+						const props = self._props
+						const promise = executor.executeEntrypointPropertyGet(entrypoint, prop, props).then((result) => {
+							if (result.kind === 'function') {
+								// Property is a function on the entrypoint — hand back a function-stub
+								// that RPCs through to the worker thread on each call.
+								const remoteFn = (...callArgs: unknown[]) => executor.executeEntrypointRpc(entrypoint, prop, callArgs, props)
+								return createRpcFunctionStub(remoteFn, undefined)
+							}
+							return wrapRpcReturnValue(result.value, prop)
+						})
+						return promise.then(onFulfilled, onRejected)
+					}
+					const promise = new Promise<unknown>((resolveP, rejectP) => {
 						try {
 							const target = self._getTarget()
 							const member = target[prop]
 							if (typeof member === 'function') {
-								resolve(createRpcFunctionStub(member as Function, target))
+								resolveP(createRpcFunctionStub(member as Function, target))
 							} else {
-								resolve(wrapRpcReturnValue(member, prop))
+								resolveP(wrapRpcReturnValue(member, prop))
 							}
 						} catch (e) {
-							reject(e)
+							rejectP(e)
 						}
 					})
 					return promise.then(onFulfilled, onRejected)

package/src/bindings/static-assets.ts

@@ -58,8 +58,9 @@ export class StaticAssets {
 		this.limits = { ...STATIC_ASSETS_LIMITS_DEFAULTS, ...limits }
 	}
 
-	async fetch(request: Request): Promise<Response> {
-		const url = new URL(request.url)
+	async fetch(input: Request | string | URL): Promise<Response> {
+		const url = input instanceof Request ? new URL(input.url) : new URL(input)
+		const request = input instanceof Request ? input : undefined
 		let pathname = decodeURIComponent(url.pathname)
 
 		// Check _redirects rules first (highest precedence)

package/src/bindings/websocket-pair.ts

@@ -6,9 +6,9 @@
  * Events are buffered until accept() is called.
  */
 
-type WSEventType = 'message' | 'close' | 'error' | 'open'
+export type WSEventType = 'message' | 'close' | 'error' | 'open'
 
-interface WSEvent {
+export interface WSEvent {
 	type: WSEventType
 	data?: string | ArrayBuffer
 	code?: number
@@ -16,6 +16,9 @@ interface WSEvent {
 	wasClean?: boolean
 }
 
+/** Response with optional CF `webSocket` property — used by upgrade flows. */
+export type ResponseWithWebSocket = Response & { webSocket?: CFWebSocket }
+
 const CONNECTING = 0
 const OPEN = 1
 const CLOSING = 2
@@ -68,7 +71,10 @@ export class CFWebSocket extends EventTarget {
 	accept(): void {
 		if (this._accepted) return
 		this._accepted = true
-		this.readyState = OPEN
+		// Don't re-open a socket that was already closed before accept() (e.g. a
+		// bridged peer whose close was buffered ahead of registration). The queued
+		// close event below still dispatches to listeners.
+		if (this.readyState !== CLOSED) this.readyState = OPEN
 
 		// Flush queued events
 		const queue = this._eventQueue
@@ -134,6 +140,16 @@ export class CFWebSocket extends EventTarget {
 		}
 	}
 
+	/**
+	 * Deliver `evt` to local listeners if the peer is already `accept()`ed;
+	 * otherwise queue it for replay. Centralises the "dispatch or queue" branch
+	 * that every bridge implementation otherwise inlines.
+	 */
+	dispatchOrQueue(evt: WSEvent): void {
+		if (this._accepted) this._dispatchWSEvent(evt)
+		else this._eventQueue.push(evt)
+	}
+
 	/** @internal */
 	_dispatchWSEvent(evt: WSEvent): void {
 		switch (evt.type) {

package/src/bindings/workflow.ts

@@ -3,6 +3,7 @@ import type { Clock } from '../testing/clock'
 import { realClock } from '../testing/clock'
 import { getActiveContext } from '../tracing/context'
 import { addSpanEvent, persistError, startSpan } from '../tracing/span'
+import type { WorkflowControlOp, WorkflowControlResult } from '../worker-thread/protocol'
 
 // --- Limits ---
 
@@ -720,6 +721,27 @@ export function parseDuration(duration: string | number): number {
 
 // --- Base class ---
 
+/**
+ * Wire a workflow class from the user module onto a `SqliteWorkflowBinding`.
+ * Both the in-process `wireClassRefs` and the worker-thread entry use this
+ * — keeps the lookup-throw-setClass-resumeInterrupted contract in one place.
+ */
+export function wireWorkflowClass(
+	binding: SqliteWorkflowBinding,
+	className: string,
+	workerModule: Record<string, unknown>,
+	env: Record<string, unknown>,
+): void {
+	const cls = workerModule[className]
+	if (!cls) throw new Error(`Workflow class "${className}" not exported from worker module`)
+	binding._setClass(cls as new(ctx: unknown, env: unknown) => WorkflowEntrypointBase, env)
+	// NOTE: resumeInterrupted() is deliberately NOT called here. Resuming during
+	// worker init would re-execute running/waiting instances while the previous
+	// generation's worker (terminated only after drain) is still running them —
+	// duplicate side effects. Main drives resume via a `resumeInterrupted` control
+	// op once the old generation's worker is disposed (see GenerationManager).
+}
+
 export class WorkflowEntrypointBase {
 	ctx: { env: unknown; waitUntil(p: Promise<unknown>): void }
 	env: unknown
@@ -880,6 +902,13 @@ export class SqliteWorkflowBinding {
 	private counter = 0
 	private limits: Required<WorkflowLimits>
 	private clock: Clock
+	/**
+	 * Thread-mode router for dashboard control ops. The real state machine lives
+	 * in the worker thread, so when this is set `executeControl` forwards there
+	 * instead of running against this (hollow) main-side binding. `null`/unset =
+	 * in-process: run locally. Installed by `GenerationManager` on each reload.
+	 */
+	private _threadRouter?: (op: WorkflowControlOp) => Promise<WorkflowControlResult>
 
 	constructor(db: Database, workflowName: string, className: string, limits?: WorkflowLimits, clock?: Clock) {
 		this.db = db
@@ -1071,6 +1100,68 @@ export class SqliteWorkflowBinding {
 		return new SqliteWorkflowInstance(this.db, id, this)
 	}
 
+	/**
+	 * Install the thread-mode router (see {@link _threadRouter}). Called by
+	 * `GenerationManager` on each reload so the dashboard's control ops reach the
+	 * live worker-side binding. Mirrors the DO namespace's `_setExternalClass`.
+	 */
+	_setThreadRouter(router: (op: WorkflowControlOp) => Promise<WorkflowControlResult>): void {
+		this._threadRouter = router
+	}
+
+	/**
+	 * Execute a dashboard control operation. In thread mode the real state
+	 * machine (abort controllers, event waiters, sleep resolvers, the wired
+	 * class) lives in the worker, so when a thread router is installed this
+	 * forwards there; otherwise (in-process / worker-side binding) it runs
+	 * locally. Mutating ops resolve to `{ kind: 'ok' }`; `create` reports the new
+	 * id; the introspection reads report their value.
+	 */
+	async executeControl(op: WorkflowControlOp): Promise<WorkflowControlResult> {
+		if (this._threadRouter) return this._threadRouter(op)
+		switch (op.kind) {
+			case 'create': {
+				const instance = await this.create({ id: op.id, params: op.params })
+				return { kind: 'create', id: instance.id }
+			}
+			case 'status': {
+				return { kind: 'status', value: await (await this.get(op.instanceId)).status() }
+			}
+			case 'resumeInterrupted': {
+				this.resumeInterrupted()
+				return { kind: 'ok' }
+			}
+			case 'terminate': {
+				await (await this.get(op.instanceId)).terminate()
+				return { kind: 'ok' }
+			}
+			case 'pause': {
+				await (await this.get(op.instanceId)).pause()
+				return { kind: 'ok' }
+			}
+			case 'resume': {
+				await (await this.get(op.instanceId)).resume()
+				return { kind: 'ok' }
+			}
+			case 'restart': {
+				await (await this.get(op.instanceId)).restart(op.fromStep ? { fromStep: op.fromStep } : undefined)
+				return { kind: 'ok' }
+			}
+			case 'skipSleep': {
+				await (await this.get(op.instanceId)).skipSleep()
+				return { kind: 'ok' }
+			}
+			case 'sendEvent': {
+				await (await this.get(op.instanceId)).sendEvent({ type: op.eventType, payload: op.payload })
+				return { kind: 'ok' }
+			}
+			case 'isSleeping':
+				return { kind: 'isSleeping', value: isInstanceSleeping(op.instanceId) }
+			case 'waitingEventTypes':
+				return { kind: 'waitingEventTypes', value: getWaitingEventTypes(op.instanceId) }
+		}
+	}
+
 	/** Resume any workflow instances that were running/waiting when the process last exited. */
 	resumeInterrupted(): void {
 		if (!this._class) return