# @smithers-orchestrator/server — src

The Smithers Gateway control plane. `gateway.js` is the core: the `Gateway`
class serves the WS RPC protocol, HTTP `/v1/rpc`, the `/v1/api` REST + SSE
surface, run event windows with backpressure, webhooks, cron/timer sweeps,
approvals/signals, devtools streams, and the extension registry implemented in
`GatewayExtensions.js`. `serve.js` is the single-run server behind
`smithers up --serve`, `light-gateway.js` a slimmer variant, and
`smithersRuntime.js` the shared Effect runtime (`runFork`/`runPromise`).
`index.js` is the package barrel.

Every other `Foo.ts` file here (ConnectRequest, RequestFrame/ResponseFrame/
EventFrame, GatewayOptions, GatewayAuthConfig, ServeOptions/ServerOptions, the
webhook/UI configs, HelloResponse, ...) is a type-only sidecar for the .js
implementations — the repo's .js-with-JSDoc convention. `index.d.ts` is
generated by the build; never hand-edit it.

Subdirectories: `gatewayRoutes/` holds the devtools/node-output/node-diff/
jump-to-frame route handlers the Gateway dispatches into; `gatewayUi/` holds
the browser UI shell (auth, HTML/asset rendering, Bun bundling, the default
operator console).

Gotchas:
- The block between `// @smithers-type-exports-begin/end` at the top of
  gateway.js is tool-managed — preserve it byte-for-byte.
- Security defenses (DNS-rebinding Host gate, auth-mode-aware Origin gate,
  trusted-proxy fail-closed scopes) live in `Gateway.isHostAllowed`,
  `isRequestOriginAllowed`, and `authenticateRequest`; read their comments
  before touching auth.
- Three parallel slow-consumer guards exist (run event streams, devtools
  streams, extension streams), each with matching queue-limit / high-water
  constants (`RUN_EVENT_STREAM_*`, `DEVTOOLS_STREAM_*`, `EXTENSION_*`).
