# src/workerd/io/

## OVERVIEW

I/O lifecycle, per-request context, worker/isolate management, actor storage, consistency gates, and compatibility flags.

## KEY CLASSES

| Class                                       | File                   | Role                                                                                        |
| ------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------- |
| `IoContext`                                 | `io-context.{h,c++}`   | Per-request god object; thread-local via `IoContext::current()`                             |
| `IoContext::IncomingRequest`                | `io-context.h`         | Tracks one inbound request for metrics/tracing; actors have many per IoContext              |
| `Worker`                                    | `worker.{h,c++}`       | Ref-counted worker instance; owns Script + Isolate refs                                     |
| `Worker::Isolate`                           | `worker.h:337`         | V8 isolate wrapper; shared across workers with same config                                  |
| `Worker::Script`                            | `worker.h:250`         | Compiled script bound to an Isolate                                                         |
| `Worker::Lock`                              | `worker.h:677`         | Synchronous V8 isolate lock (must hold to touch JS heap)                                    |
| `Worker::AsyncLock`                         | `worker.h:799`         | Fair async queue for acquiring `Worker::Lock`                                               |
| `Worker::Actor`                             | `worker.h:819`         | Durable Object instance; owns gates + cache + hibernation state                             |
| `ActorCache`                                | `actor-cache.{h,c++}`  | LRU write-back cache over RPC storage; `ActorCacheOps` base                                 |
| `ActorSqlite`                               | `actor-sqlite.{h,c++}` | SQLite-backed `ActorCacheOps` implementation                                                |
| `InputGate` / `OutputGate`                  | `io-gate.{h,c++}`      | Consistency primitives for DO concurrent request handling                                   |
| `IoOwn<T>` / `IoPtr<T>` / `ReverseIoOwn<T>` | `io-own.{h,c++}`       | Cross-heap smart pointers preventing KJ↔JS ref leaks                                       |

## WHERE TO LOOK

| Task                            | File(s)                                                                           |
| ------------------------------- | --------------------------------------------------------------------------------- |
| Promise bridging KJ↔JS         | `io-context.h` — `awaitIo()`, `awaitJs()`                                         |
| Request lifecycle / subrequests | `io-context.{h,c++}`, `worker-entrypoint.{h,c++}`                                 |
| Actor storage ops               | `actor-cache.h` (`ActorCacheOps`), `actor-sqlite.h`, `actor-storage.capnp`        |
| DO gate semantics               | `io-gate.{h,c++}` — `InputGate::CriticalSection`, `OutputGate::lockWhile()`       |
| Worker/isolate creation         | `worker.{h,c++}`, `worker-modules.{h,c++}`                                        |
| Metrics/logging hooks           | `observer.h` — `RequestObserver`, `IsolateObserver`, `ActorObserver`              |
| Tracing                         | `trace.{h,c++,capnp}`, `trace-stream.{h,c++}`, `tracer.{h,c++}`                   |
| Resource limits                 | `limit-enforcer.h` (abstract interface)                                           |
| Timer scheduling                | `io-timers.{h,c++}`                                                               |
| Hibernatable WebSockets         | `hibernation-manager.{h,c++}`                                                     |
| Cap'n Proto schemas             | `worker-interface.capnp`, `actor-storage.capnp`, `container.capnp`, `trace.capnp` |

## CONVENTIONS

- `IoContext::current()` — ambient thread-local access; only valid inside a request
- `awaitIo(js, kjPromise, func)` bridges KJ→JS; `func` runs under V8 lock. `awaitIo(js, kjPromise)` for identity
- `awaitJs(js, jsPromise)` bridges JS→KJ
- `addObject(kj::Own<T>)` returns `IoOwn<T>` — the **only** safe way to store KJ I/O objects reachable from JS heap
- Two-phase locking: `Worker::AsyncLock` (fair queue) → `Worker::Lock` (V8 isolate lock)
- `ActorCacheOps` methods return `kj::OneOf<Result, kj::Promise<Result>>` — sync when cached, async otherwise
- `OutputGate::lockWhile(promise)` blocks outgoing responses until the promise resolves
- `InputGate::CriticalSection` must succeed or permanently breaks the gate
- Observer classes (`RequestObserver`, `IsolateObserver`, etc.) have no-op defaults; all methods optional

## ANTI-PATTERNS

- **NEVER** use `awaitIoLegacy()` in new code — use `awaitIo()` with continuation
- `awaitIoImpl` parameter ordering (promise by-value, func by-ref) is **critical** for exception safety
- `abortWhen()` promises must **never** enter the V8 isolate
- Cross-request I/O object access throws by design (IoOwn prevents this)