Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/cloudflare-cross-request-scheduler.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"effect": minor
"@effect/platform-cloudflare": minor
---

Add `CloudflareScheduler` and the `Scheduler.preserveAsyncContext` opt-out so shared Worker fibers can resume across requests without request-bound async-context errors.
10 changes: 10 additions & 0 deletions packages/effect/src/Scheduler.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,16 @@ import type * as Fiber from "./Fiber.ts"
*/
export interface Scheduler {
readonly executionMode: "sync" | "async"
/**
* Controls whether fibers preserve native async context across suspension and
* deferred forks. Set to `false` on runtimes with request-bound async resources;
* continuations then run in the context that resumes them. Omission preserves
* the current behavior.
*
* @default true
* @since 4.2.0
*/
readonly preserveAsyncContext?: boolean | undefined
shouldYield(fiber: Fiber.Fiber<unknown, unknown>): boolean
makeDispatcher(): SchedulerDispatcher
}
Expand Down
10 changes: 6 additions & 4 deletions packages/effect/src/internal/effect.ts
Original file line number Diff line number Diff line change
Expand Up @@ -511,8 +511,10 @@
}
})()

const captureAsyncContext = (): AsyncContext | undefined =>
AsyncResource === undefined ? undefined : new AsyncResource("effect/Fiber")
const captureAsyncContext = (scheduler: Scheduler.Scheduler): AsyncContext | undefined =>
AsyncResource === undefined || scheduler.preserveAsyncContext === false
? undefined
: new AsyncResource("effect/Fiber")

Check failure on line 517 in packages/effect/src/internal/effect.ts

View workflow job for this annotation

GitHub Actions / Test (Bun)

error: All fibers interrupted without error

at causeSquash (/home/runner/work/effect/effect/packages/effect/src/internal/effect.ts:517:38) at <anonymous> (/home/runner/work/effect/effect/packages/effect/src/Stream.ts:8125:51) at addObserver (/home/runner/work/effect/effect/packages/effect/src/internal/effect.ts:715:6) at start (/home/runner/work/effect/effect/packages/effect/src/Stream.ts:8121:21) at <anonymous> (/home/runner/work/effect/effect/packages/effect/src/Stream.ts:8111:9) at makeResponse (/home/runner/work/effect/effect/packages/platform/bun/src/BunHttpServer.ts:264:67) at <anonymous> (/home/runner/work/effect/effect/packages/platform/bun/src/BunHttpServer.ts:179:36) at ~effect/Effect/evaluate (/home/runner/work/effect/effect/packages/effect/src/internal/effect.ts:1109:22) at runLoop (/home/runner/work/effect/effect/packages/effect/src/internal/effect.ts:843:116)

/** @internal */
export const getCurrentFiber = (): Fiber.Fiber<any, any> | undefined => (globalThis as any)[currentFiberTypeId]
Expand Down Expand Up @@ -636,7 +638,7 @@
}
const exit = this.runLoop(effect)
if (exit === Yield) {
this._asyncContext = captureAsyncContext()
this._asyncContext = captureAsyncContext(this.cache.scheduler)
return
}
// the interruptChildren middleware is added in Effect.forkChild, so it can be
Expand Down Expand Up @@ -5631,7 +5633,7 @@
child.evaluate(effect as any)
} else {
// Preserve the fork context rather than the dispatcher's context.
child._asyncContext = captureAsyncContext()
child._asyncContext = captureAsyncContext(child.cache.scheduler)
parentRuntime.currentDispatcher.scheduleTask(() => child.evaluate(effect as any), 0)
}
return child
Expand Down
2 changes: 2 additions & 0 deletions packages/effect/src/testing/TestClock.ts
Original file line number Diff line number Diff line change
Expand Up @@ -493,10 +493,12 @@ class TrackingScheduler implements Scheduler.Scheduler {
readonly clock: TestClockImpl
readonly parent: Scheduler.Scheduler
readonly executionMode: Scheduler.Scheduler["executionMode"]
readonly preserveAsyncContext: Scheduler.Scheduler["preserveAsyncContext"]
constructor(clock: TestClockImpl, parent: Scheduler.Scheduler) {
this.clock = clock
this.parent = parent
this.executionMode = parent.executionMode
this.preserveAsyncContext = parent.preserveAsyncContext
}
shouldYield(fiber: Fiber.Fiber<unknown, unknown>): boolean {
return this.parent.shouldYield(fiber)
Expand Down
53 changes: 53 additions & 0 deletions packages/effect/test/Effect.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5445,6 +5445,59 @@ describe("Effect", () => {
const storage = new AsyncLocalStorage<string>()
const current = () => storage.getStore() ?? "none"

it("TestClock preserves the scheduler async-context opt-out", async () => {
const scheduler = new class extends Scheduler.MixedScheduler {
readonly preserveAsyncContext = false
}("sync")
const deferred = Deferred.makeUnsafe<void>()
const waiter = storage.run("waiter", () =>
Effect.runFork(
Effect.andThen(Deferred.await(deferred), Effect.sync(current)).pipe(Effect.provide(TestClock.layer())),
{ scheduler }
))
await storage.run("waker", () => Effect.runPromise(Deferred.succeed(deferred, undefined), { scheduler }))
assert.deepStrictEqual(waiter.pollUnsafe(), Exit.succeed("waker"))
})

for (const preserveAsyncContext of [false, true, undefined]) {
it(`resumes and forks with preserveAsyncContext=${preserveAsyncContext}`, async () => {
const tasks: Array<() => void> = []
const scheduler = {
executionMode: "sync" as const,
preserveAsyncContext,
shouldYield: () => false,
makeDispatcher: () => ({
scheduleTask: (task: () => void) => {
tasks.push(task)
},
flush: () => {
while (tasks.length > 0) tasks.shift()!()
}
})
}
const deferred = Deferred.makeUnsafe<void>()
const waiter = storage.run(
"waiter",
() => Effect.runFork(Effect.andThen(Deferred.await(deferred), Effect.sync(current)), { scheduler })
)
const parent = storage.run("parent", () =>
Effect.runFork(
Effect.gen(function*() {
const child = yield* Effect.forkChild(Effect.sync(current))
return yield* Fiber.join(child)
}),
{ scheduler }
))
await storage.run("waker", () => Effect.runPromise(Deferred.succeed(deferred, undefined)))
storage.run("dispatcher", () => scheduler.makeDispatcher().flush())
assert.deepStrictEqual(waiter.pollUnsafe(), Exit.succeed(preserveAsyncContext === false ? "waker" : "waiter"))
assert.deepStrictEqual(
parent.pollUnsafe(),
Exit.succeed(preserveAsyncContext === false ? "dispatcher" : "parent")
)
})
}

const runWithStore = <A, E>(store: string | undefined, effect: Effect.Effect<A, E>): Promise<A> =>
store === undefined ? Effect.runPromise(effect) : storage.run(store, () => Effect.runPromise(effect))

Expand Down
3 changes: 2 additions & 1 deletion packages/platform/cloudflare/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@
"alchemy": "2.0.0-beta.87",
"effect": "workspace:^",
"esbuild": "^0.28.2",
"miniflare": "^4.20260730.0"
"miniflare": "^4.20260730.0",
"miniflare-v5": "npm:miniflare@5.20260925.0-alpha"
}
}
51 changes: 51 additions & 0 deletions packages/platform/cloudflare/src/CloudflareScheduler.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
/**
* Fiber scheduling for applications shared across Cloudflare Worker requests.
*
* @stability stable
* @since 4.2.0
*/
import * as Layer from "effect/Layer"
import * as Scheduler from "effect/Scheduler"

/**
* A synchronous scheduler that does not capture request-bound native async contexts.
*
* **When to use**
*
* Use when fibers or services are shared across requests. Pass an instance as
* the `scheduler` option to Effect runners. For a shared runtime, build it with
* `ManagedRuntime.make(AppLayer.pipe(Layer.provideMerge(CloudflareScheduler.layer)))`.
* Also pass `{ scheduler: new CloudflareScheduler() }` to the runtime runners,
* including `runFork` and `runPromise`: the layer alone does not configure callers
* waiting for lazy initialization. To initialize explicitly, run
* `Effect.runPromise(runtime.contextEffect, { scheduler: new CloudflareScheduler() })`
* instead of `runtime.context()`, which does not accept a scheduler.
*
* **Gotchas**
*
* Native AsyncLocalStorage state is not preserved across suspension or deferred
* forks; a continuation uses the context that resumes it. Synchronous execution
* does not yield to the event loop, so CPU-heavy work delays other requests.
* This does not make request-owned I/O or timers such as `Effect.sleep` portable
* across requests.
*
* @stability stable
* @category models
* @since 4.2.0
*/
export class CloudflareScheduler extends Scheduler.MixedScheduler {
readonly preserveAsyncContext = false

constructor() {
super("sync")
}
}

/**
* Layer that installs the Cloudflare scheduler for an application and its fibers.
*
* @stability stable
* @category layers
* @since 4.2.0
*/
export const layer: Layer.Layer<never> = Layer.succeed(Scheduler.Scheduler, new CloudflareScheduler())
6 changes: 6 additions & 0 deletions packages/platform/cloudflare/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,12 @@ export * as CloudflareDurableObjects from "./CloudflareDurableObjects.ts"
*/
export * as CloudflarePersistedQueue from "./CloudflarePersistedQueue.ts"

/**
* @stability stable
* @since 4.2.0
*/
export * as CloudflareScheduler from "./CloudflareScheduler.ts"

/**
* @stability experimental
* @since 4.1.5
Expand Down
43 changes: 43 additions & 0 deletions packages/platform/cloudflare/test/CloudflareScheduler.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
import { assert, it } from "@effect/vitest"
import * as esbuild from "esbuild"
import { Miniflare } from "miniflare-v5"
import * as path from "node:path"

it("resumes a shared fiber from a later Worker request", async () => {
const bundle = await esbuild.build({
entryPoints: [path.join(import.meta.dirname, "fixtures/scheduler-worker.ts")],
bundle: true,
format: "esm",
platform: "neutral",
write: false,
external: ["cloudflare:workers", "node:*"],
alias: {
"@effect/platform-cloudflare": path.join(import.meta.dirname, "../src")
}
})
const miniflare = new Miniflare({
workers: [{
config: {
name: "scheduler",
manifest: {
mainModule: "worker.mjs",
modules: { "worker.mjs": { type: "esm", contents: bundle.outputFiles[0].text } }
},
compatibilityDate: "2026-07-01",
compatibilityFlags: ["nodejs_compat"]
}
}]
})
try {
const start = await miniflare.dispatchFetch("http://localhost/start")
assert.strictEqual(start.status, 200)
assert.strictEqual(await start.json(), "started")
const resume = await miniflare.dispatchFetch("http://localhost/resume")
assert.strictEqual(resume.status, 200, await resume.clone().text())
assert.deepStrictEqual(await resume.json(), { done: true, initialized: true })
const status = await miniflare.dispatchFetch("http://localhost/status")
assert.deepStrictEqual(await status.json(), { done: true, initialized: true })
} finally {
await miniflare.dispose()
}
}, 30_000)
38 changes: 38 additions & 0 deletions packages/platform/cloudflare/test/fixtures/scheduler-worker.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
import { CloudflareScheduler, layer } from "@effect/platform-cloudflare/CloudflareScheduler"
import { Deferred, Effect, Layer, ManagedRuntime } from "effect"

const deferred = Deferred.makeUnsafe<void>()
const scheduler = new CloudflareScheduler()
let done = false
let initialized = false
const runtime = ManagedRuntime.make(
Layer.effectDiscard(Deferred.await(deferred)).pipe(Layer.provideMerge(layer))
)

export default {
async fetch(request: Request) {
switch (new URL(request.url).pathname) {
case "/start": {
runtime.runFork(
Effect.sync(() => {
initialized = true
}),
{ scheduler }
)
Effect.runFork(
Deferred.await(deferred).pipe(Effect.andThen(Effect.sync(() => {
done = true
}))),
{ scheduler }
)
return Response.json("started")
}
case "/resume": {
await Effect.runPromise(Deferred.succeed(deferred, undefined), { scheduler })
return Response.json({ done, initialized })
}
default:
return Response.json({ done, initialized })
}
}
}
3 changes: 3 additions & 0 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading