feat: add Node fiber context bridge for framework request scope

also refactor repo into workspace and add Hono example

Author: utopyin

.changeset/swift-bikes-doubt.md

@@ -0,0 +1,7 @@
+---
+"effect-orpc": minor
+---
+
+Add `withFiberContext` helper at `effect-orpc/node` to
+propagate Effect `FiberRef` state across framework async boundaries, and add a
+workspace Hono example showing request-scoped log and trace propagation.

README.md

@@ -23,6 +23,8 @@ pnpm add effect-orpc
 bun add effect-orpc
 ```
 
+Runnable demos live in the repository's `examples/` directory.
+
 ## Demo
 
 ```ts
@@ -87,6 +89,46 @@ export const router = {
 export type Router = typeof router;
 ```
 
+## Request-Scoped Fiber Context
+
+If you run `effect-orpc` inside a framework such as Hono, the handler executes
+through the runtime boundary and will not automatically inherit request-local
+`FiberRef` state from outer middleware. Import `makeEffectORPC` from the main
+package, and wrap the framework continuation with `withFiberContext` from
+`effect-orpc/node` to preserve request-scoped logs, tracing annotations, and
+other fiber-local state.
+
+```ts
+import { Hono } from "hono";
+import { Effect, ManagedRuntime } from "effect";
+import { makeEffectORPC } from "effect-orpc";
+import { withFiberContext } from "effect-orpc/node";
+
+const runtime = ManagedRuntime.make(AppLive);
+const effectOs = makeEffectORPC(runtime);
+const app = new Hono();
+
+app.use("*", async (c, next) => {
+  await Effect.runPromise(
+    Effect.gen(function* () {
+      yield* Effect.annotateLogsScoped({
+        requestId: c.get("requestId"),
+      });
+
+      yield* withFiberContext(() => next());
+    }),
+  );
+});
+```
+
+The reason for the separate `/node` entrypoint is that `withFiberContext` relies
+on Node/Bun's `AsyncLocalStorage` from `node:async_hooks` to carry Effect
+`FiberRef` state across framework async boundaries. The main package stays
+runtime-agnostic.
+
+If you do not need framework-to-handler fiber propagation, you do not need the
+`/node` entrypoint at all.
+
 ## Type Safety
 
 The wrapper enforces that Effect procedures only use services provided by the `ManagedRuntime`. If you try to use a service that isn't in the runtime, you'll get a compile-time error:

bun.lock

@@ -0,0 +1,12 @@
+# Examples
+
+Runnable examples for `effect-orpc`.
+
+Install dependencies from the repository root with `bun install`, then run an
+example from its own folder. Examples depend on the local library through Bun
+workspaces.
+
+## Available Examples
+
+- `hono-request-context`: Hono + oRPC + Effect with request-scoped `FiberRef`
+  propagation using `withFiberContext` from `effect-orpc/node`.

examples/README.md

@@ -0,0 +1,35 @@
+# Hono Request Context
+
+This example mirrors the flow from Rezrazi's `effect-orpc-hono` demo, adapted to
+the split import API in this repository.
+
+It demonstrates:
+
+- Hono request middleware annotating logs with a request ID
+- `makeEffectORPC` imported from `effect-orpc`
+- `withFiberContext(() => next())` imported from `effect-orpc/node`
+- nested Effect services preserving the same request-scoped annotations
+
+## Run
+
+```bash
+cd /path/to/effect-orpc
+bun install
+cd examples/hono-request-context
+bun start
+```
+
+The API is served on `http://localhost:3000/api` by default.
+
+To override the port:
+
+```bash
+cd /path/to/effect-orpc/examples/hono-request-context
+PORT=43123 bun start
+```
+
+## Optional Telemetry Stack
+
+```bash
+docker compose up
+```

examples/hono-request-context/README.md

@@ -0,0 +1,7 @@
+services:
+  otel:
+    image: grafana/otel-lgtm:latest
+    ports:
+      - "3001:3000"
+      - "4317:4317"
+      - "4318:4318"

examples/hono-request-context/docker-compose.yml

@@ -0,0 +1,93 @@
+import { OpenAPIHandler } from "@orpc/openapi/fetch";
+import { OpenAPIReferencePlugin } from "@orpc/openapi/plugins";
+import { onError, os } from "@orpc/server";
+import { CORSPlugin } from "@orpc/server/plugins";
+import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
+import { serve } from "bun";
+import { type Effect as EffectType, Effect, pipe } from "effect";
+import { makeEffectORPC } from "effect-orpc";
+import { withFiberContext } from "effect-orpc/node";
+import { Hono } from "hono";
+import { requestId } from "hono/request-id";
+
+import { runtime } from "./runtime";
+import { OrderService } from "./services/order";
+
+const port = Number(process.env.PORT ?? "3000");
+
+const app = new Hono();
+app.use("*", requestId());
+
+app.use("/*", async (c, next) => {
+  const { method, path } = c.req;
+  const currentRequestId = c.get("requestId");
+
+  const requestEffect = Effect.gen(function* () {
+    yield* Effect.annotateLogsScoped({
+      requestId: currentRequestId,
+      service: "backend-service",
+    });
+    yield* Effect.logInfo(`[Request] ${method} ${path}`);
+    yield* withFiberContext(() => next());
+    yield* Effect.logInfo(`[Response] ${method} ${path} (${c.res.status})`);
+  }).pipe(Effect.scoped, Effect.withSpan(`${method} ${path}`));
+
+  await runtime.runPromise(
+    requestEffect as EffectType.Effect<void, unknown, never>,
+  );
+});
+
+const o = makeEffectORPC(runtime, os);
+
+const router = {
+  orders: o.route({ path: "/orders", method: "GET" }).effect(function* () {
+    yield* Effect.logInfo("Handler: GET /orders - listing all orders");
+    return yield* OrderService.listOrders();
+  }),
+  test: o.route({ path: "/test", method: "GET" }).effect(function* () {
+    return "ok";
+  }),
+};
+
+const openAPIHandler = new OpenAPIHandler(router, {
+  plugins: [
+    new CORSPlugin(),
+    new OpenAPIReferencePlugin({
+      schemaConverters: [new ZodToJsonSchemaConverter()],
+    }),
+  ],
+  interceptors: [
+    onError(async (error) => {
+      await runtime.runPromise(pipe(Effect.logError("oRPC Error", error)));
+    }),
+  ],
+});
+
+app.use("/*", async (c, next) => {
+  const { matched, response } = await openAPIHandler.handle(c.req.raw, {
+    prefix: "/api",
+  });
+
+  if (matched) {
+    return c.newResponse(response.body, response);
+  }
+
+  await next();
+});
+
+const server = serve({
+  fetch: app.fetch,
+  port,
+});
+
+await runtime.runPromise(
+  pipe(
+    Effect.logInfo(`Server started on http://localhost:${port}`),
+    Effect.annotateLogs("service", "backend-service"),
+  ),
+);
+
+process.on("SIGINT", () => {
+  server.stop();
+  process.exit(0);
+});

examples/hono-request-context/index.ts

@@ -0,0 +1,25 @@
+{
+  "name": "effect-orpc-example-hono-request-context",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "bun --watch index.ts"
+  },
+  "dependencies": {
+    "@effect/opentelemetry": "^0.60.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.210.0",
+    "@opentelemetry/sdk-metrics": "^2.4.0",
+    "@opentelemetry/sdk-trace-base": "^2.4.0",
+    "@opentelemetry/sdk-trace-node": "^2.4.0",
+    "@opentelemetry/sdk-trace-web": "^2.4.0",
+    "@orpc/openapi": "^1.13.4",
+    "@orpc/server": "^1.13.4",
+    "@orpc/zod": "^1.13.4",
+    "@types/bun": "latest",
+    "effect": "^3.19.14",
+    "effect-orpc": "workspace:*",
+    "hono": "^4.11.4",
+    "typescript": "^5.9.3",
+    "zod": "^4.3.5"
+  }
+}

examples/hono-request-context/package.json

@@ -0,0 +1,21 @@
+import { NodeSdk } from "@effect/opentelemetry";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { Layer, Logger, ManagedRuntime } from "effect";
+
+import { OrderService } from "./services/order";
+
+const NodeSdkLive = NodeSdk.layer(() => ({
+  resource: { serviceName: "effect-orpc-hono-request-context" },
+  spanProcessor: new BatchSpanProcessor(
+    new OTLPTraceExporter({
+      url: "http://localhost:4318/v1/traces",
+    }),
+  ),
+}));
+
+export const AppLive = Layer.mergeAll(Logger.pretty, OrderService.Default).pipe(
+  Layer.provideMerge(NodeSdkLive),
+);
+
+export const runtime = ManagedRuntime.make(AppLive);

examples/hono-request-context/runtime.ts

@@ -0,0 +1,47 @@
+import { Effect } from "effect";
+
+import { DatabaseService } from "./database";
+
+export class CacheService extends Effect.Service<CacheService>()(
+  "CacheService",
+  {
+    accessors: true,
+    dependencies: [DatabaseService.Default],
+    effect: Effect.gen(function* () {
+      const db = yield* DatabaseService;
+      const cache = new Map<string, unknown>();
+
+      return {
+        get: (key: string) =>
+          Effect.gen(function* () {
+            yield* Effect.logInfo(`Cache lookup: ${key}`);
+
+            if (cache.has(key)) {
+              yield* Effect.logInfo(`Cache HIT: ${key}`);
+              return cache.get(key);
+            }
+
+            yield* Effect.logInfo(`Cache MISS: ${key}, fetching from DB`);
+            const result = yield* db.query(
+              `SELECT * FROM cache WHERE key = '${key}'`,
+            );
+            cache.set(key, result);
+            return result;
+          }).pipe(
+            Effect.annotateLogs("service", "CacheService"),
+            Effect.withSpan("CacheService.get"),
+          ),
+        set: (key: string, value: unknown) =>
+          Effect.gen(function* () {
+            yield* Effect.logInfo(`Cache set: ${key}`);
+            cache.set(key, value);
+            yield* db.insert("cache", { key, value });
+            return true;
+          }).pipe(
+            Effect.annotateLogs("service", "CacheService"),
+            Effect.withSpan("CacheService.set"),
+          ),
+      };
+    }),
+  },
+) {}