Skip to content
Runtime APIs / Fetch events

Runtime APIs

Fetch events

Your Worker's fetch() handler runs unchanged on OpenOrange, with a new execution context for each request for waitUntil(), props, and exports.

Drop-in

Runs on Node.js runtime with workerd-shaped globals, cloudflare:* and node:* modules

Works
fetch(request, env, ctx), ctx.waitUntil(), ctx.props, ctx.exports, WorkerEntrypoint, and env and exports from cloudflare:workers
Differs
passThroughOnException() does nothing, ctx.abort() cannot stop running code, and request.cf holds placeholder values
Missing
ctx.cache, ctx.access, and real trace spans in ctx.tracing
Migration
Not needed A Worker holds no data. Deploy its code to Orange.
Scales by
Runner count

Your Worker’s fetch(request, env, ctx) handler runs unchanged on OpenOrange. Orange calls it once for each request, with a new ctx each time, as Cloudflare does.

Quickstart

  1. Configure the Worker

    Point main at the file that exports the handler.

    {
      "name": "hello",
      "main": "src/index.ts",
      "compatibility_date": "2026-09-03"
    }
  2. Write the handler

    Export fetch on the default object, as on Cloudflare.

    export default {
      async fetch(request, env, ctx): Promise<Response> {
        // Runs after the response is sent.
        ctx.waitUntil(fetch("https://example.com/log", { method: "POST", body: request.url }));
        return new Response(`Hello from ${new URL(request.url).pathname}`);
      },
    } satisfies ExportedHandler<Env>;
  3. Run it

    orange dev

    Call it on port 8787:

    curl localhost:8787/hello
    Hello from /hello

How it works

  • ctx.waitUntil(promise) keeps work running after the response. orange dev prints each promise that rejects.
  • ctx.props and ctx.exports work as on Cloudflare. A default class that extends WorkerEntrypoint gets a new instance for each request.
  • request.url is the URL the client used, built from its Host header.
AI context Compatibility, limits and details

Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.

Compatibility

FeatureStatusNotes
The fetch eventPartialThe handler runs unchanged. The context members below that are Partial or Not supported make the event Partial.
ctx.waitUntil(promise)SupportedOrange waits for every registered promise, including work registered while an earlier promise is settling, and keeps both fulfilled and rejected outcomes.
ctx.propsSupportedThe props of the service binding that called this entrypoint. See Multiple Workers. An empty object when the caller passes no props, as in workerd.
ctx.exportsSupportedThis Worker’s named WorkerEntrypoint classes and handler objects become service stubs. Durable Object classes appear as their namespaces.
ctx.passThroughOnException()PartialA no-op. See Deviations.
ctx.abort(reason)PartialReleases the context’s I/O objects, then throws. See Deviations.
ctx.tracingPartialNo-op spans. See Deviations.
ctx.cache and ctx.accessNot supportedundefined, as in local workerd.
env and exports from cloudflare:workersSupportedFollow workerd. See cloudflare:workers.
withEnv(), withExports(), and withEnvAndExports()SupportedOverride the importable env and exports for a callback.
waitUntil() from cloudflare:workersSupportedRegisters the promise on the running event. At module scope it throws workerd’s Disallowed operation called within global scope error.
WorkerEntrypointSupportedA base class that stores ctx and env.
The disallow_importable_env flagNot supportedOrange does not read it.

Copying every ctx property, as Sentry does, works: ctx.cache reads as undefined instead of throwing.

Limits

Orange does not copy Cloudflare’s per-request limits, such as CPU time or how long waitUntil() work runs after the response. Nothing in the runtime times out a handler or its waitUntil() promises. For the limits of the machine and of Rivet, see Limits.

Handlers

  • The default export’s fetch handles each request. A default class that extends WorkerEntrypoint handles each request with a new instance.
  • A Worker that also exports scheduled, queue, or other handlers still serves fetch. Each other handler has its own dispatch.
  • A Worker without a fetch handler loads, and each request fails with Handler does not export a fetch() function., as in workerd.
  • A module without a default export serves only its named entrypoints.
  • A default export that is not an object or a WorkerEntrypoint class fails with Worker entrypoint must have a default object export.

Responses

The handler must return an OpenOrange Response. The request fails when:

What the handler returnsError
Something that is not a ResponseTypeError: Worker fetch handler must return a Response
Response.error()TypeError: Return value from serve handler must not be an error response (like Response.error())
A Response whose body was already readTypeError: Body has already been used. It can only be used once. Use tee() first if you need to read it twice.

A handler that throws fails the request with a 500 response. Its waitUntil() work still settles first.

Through a service binding or a Durable Object stub, the caller’s fetch() rejects with workerd’s remote error instead. A missing handler gives Handler does not export a fetch() function., a result that is not a Response gives TypeError: Incorrect type for Promise: the Promise did not resolve to 'Response'., and a thrown error keeps its name, message, and own properties, such as code.

Requests

  • request.url uses the request’s Host header. Under orange serve, its scheme is https: when the cluster’s gateway sends X-Forwarded-Proto: https, so a Worker sees the URL its client used, as on Cloudflare. orange dev takes requests directly and ignores that header.
  • request.cf is the placeholder object that Miniflare uses when it cannot download the real one, such as colo: "DFW" and city: "Austin", with httpProtocol set from the request. It is the same under orange dev and orange serve.
  • Orange sets CF-Connecting-IP to the client’s address, unless the request already has one, as Miniflare does.

cloudflare:workers

  • The env, exports, withEnv(), withExports(), and withEnvAndExports() exports follow workerd.
  • env is readable while the Worker module evaluates.
  • Both proxies follow the current async-context override.
  • Changes through env change the environment object passed to handlers.
  • exports is the same object as ctx.exports.

How Orange runs the handler

  • The controlled loader builds an extensible environment from the configured bindings, installs the Cloudflare global manifest, imports the Worker, and keeps its named exports.
  • Dispatch calls the default module Worker’s fetch handler inside the request’s execution context.
  • The dispatch result holds the response and a promise for every waitUntil() outcome.
  • In development, a dedicated Node.js child process owns the HTTP listener and the runtime lifecycle. It streams request and response bodies and runs each request inside the child.
  • The child reports readiness, startup failures, request failures, background failures, signals, and a clean shutdown to the parent CLI over IPC.
  • The child returns background outcomes to the runtime, which reports each rejected one to the CLI for local diagnostics. orange dev prints it as an error with its stack.

Deviations

  • passThroughOnException() is a no-op, because Orange has no origin to fall back to. An exception after the call still fails the request with a 500 response.
  • abort() releases the context’s I/O objects, such as RPC stubs, and then throws the reason, because Node.js cannot stop running JavaScript. Without a reason it throws Worker execution was aborted due to call to ctx.abort().
  • ctx.cache and ctx.access are undefined, as in local workerd.
  • ctx.tracing runs every span callback with a no-op span whose isTraced is false, because Orange has no trace collector.
  • request.cf holds placeholder values, not the client’s location.

Conformance

  • The conformance check compiles a module Worker against the pinned ExportedHandler<Env> fetch signature, and proves that an invalid response type is rejected.
  • The generated event registry check verifies that the context has exactly the Cloudflare ExecutionContext keys, and that it is assignable to its generic contract.
  • Runtime tests cover entrypoint ordering, named exports, environment injection, response validation, waitUntil() draining, each unsupported API, and the dedicated process lifecycle over a real HTTP socket.
  • tests/events/execution-context.test.ts runs Workers under orange dev and checks a missing, throwing, or non-Response handler, passThroughOnException(), ctx.props with and without props, and copying every ctx property.

Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.

Workers
Check Status Results