@elysiumjs/core 0.8.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,232 @@
 # @elysiumjs/core
 
+## 0.11.0
+
+### Minor Changes
+
+- [#8](https://github.com/na2axl/elysiumjs/pull/8) [`6bc48fe`](https://github.com/na2axl/elysiumjs/commit/6bc48febd51f7090c582e73f349eaeff7261241c) Thanks [@na2axl](https://github.com/na2axl)! - `Application.build()` builds the root Elysia app without listening, for hosts that own the server (Cloudflare Workers) and for ahead-of-time compilation with `elysia/plugin/aot`. Modules are registered but boot on the first request (once, shared by concurrent requests), so building runs no `onInit` work. A boot failure fails the requests.
+
+  HTTP and websocket controllers in the server scope, and middlewares, are now built on their first request instead of when the app is built. `serve` still boots every module before listening.
+
+  `@elysiumjs/runtime-workers` gets a `check:aot` script, run in CI: it compiles a sample app with the AOT plugin for workerd, checks that the bundle holds no `new Function` or `eval`, and serves a validated route and the OpenAPI document under Node.js with code generation from strings disallowed.
+
+- [#7](https://github.com/na2axl/elysiumjs/pull/7) [`e9c3d98`](https://github.com/na2axl/elysiumjs/commit/e9c3d98dd2714b69100215f7c8a80046da463148) Thanks [@na2axl](https://github.com/na2axl)! - Elysium runs on Elysia 2 (`elysia@^2.0.0-rc.1`), with TypeBox 1 (`typebox`), `@elysia/openapi` and `@elysia/opentelemetry`.
+
+  Breaking:
+
+  - `TSchema` and `Static` are re-exported from `typebox` instead of `@sinclair/typebox`; `Value` comes from `typebox/value` and `Value.Errors()` returns an array.
+  - `Application.onError()` receives a `ServerError` (exported from core). Elysia now names its errors in kebab case; the default error response keeps the upper snake case names (`VALIDATION`, `NOT_FOUND`, `UNKNOWN` for other errors).
+  - `AppHttpContext` is a plain interface with `decorator`, `store` and `derive` records (Elysia 2 renamed `resolve` to `derive`).
+  - Websocket controllers install Elysia's `websocket()` capability themselves.
+
+  A module or controller `onRequest` middleware that answers now stops the request: Elysia 2 ignores values returned from a transform hook, so the response is thrown as a status and sent as is, without going through `onError`.
+
+  `mnemosyne` builds date columns with `t.Codec` (TypeBox 1 dropped `Transform`). `argus` traces every route of the app it is installed on and ends each span once, keeping the error status when the request failed.
+
+- [#5](https://github.com/na2axl/elysiumjs/pull/5) [`557a3ca`](https://github.com/na2axl/elysiumjs/commit/557a3cab7af8053a8bab9944e492e5022d91aa82) Thanks [@na2axl](https://github.com/na2axl)! - Core runs outside Bun. Environment variables, timers, the HTTP server, process exit and shutdown signals now come from a `Runtime` set with the new `runtime` option of `@Application.register()` or with `Runtime.use()`. Runtimes ship as packages, each exporting `runtime`: `@elysiumjs/runtime-bun`, `@elysiumjs/runtime-node` and `@elysiumjs/runtime-workers` (which also exports `createRuntime({ env })`).
+
+  Breaking: an application needs a runtime (add `runtime` from `@elysiumjs/runtime-bun`), and `Redis` and `RedisModule` moved from core to the new `@elysiumjs/redis` package, which also accepts a `client` factory for runtimes without `Bun.RedisClient`.
+
+  Console colours are plain ANSI codes instead of `Bun.color`, `node:readline` is loaded only when a prompt runs, and core's dist is built for the `node` target so `node:` imports keep their prefix. `check:runtime` scripts in core and runtime-workers fail when their bundles touch the `Bun` global.
+
+  `create-elysium` gets a runtime step: it installs the chosen runtime package and sets it in the generated app. Bun is selectable today; Node.js and Cloudflare Workers are listed as coming later.
+
+- [#24](https://github.com/na2axl/elysiumjs/pull/24) [`ccc3f5b`](https://github.com/na2axl/elysiumjs/commit/ccc3f5bb904d1bf52d8c72ebf7ea8d10f617a8c4) Thanks [@na2axl](https://github.com/na2axl)! - `Service.ownersOf(service)` lists the modules that declare a service in their own scope, and `ModuleContext.outside(fn)` runs code outside of any module, so that lookups only see the global scope.
+
+- [#19](https://github.com/na2axl/elysiumjs/pull/19) [`6789879`](https://github.com/na2axl/elysiumjs/commit/678987976ecfd46b534b65276e0de3f448977562) Thanks [@na2axl](https://github.com/na2axl)! - Domain errors as classes with a code, returned as values.
+
+  - `DomainError` is an Elysia `HTTPError`. Each error is a class made with `DomainError.for(code, status)`, which keeps its code and status as literal types, with `errors`, `retryAfterSeconds` (served as `retryAfter` and the Retry-After header) and extensions.
+  - Ready-made errors: `BadRequestError`, `ValidationFailedError`, `UnauthenticatedError`, `ForbiddenError`, `NotFoundError` and `ConflictError`.
+  - `ProblemCatalogue`, extended through declaration merging, lists the codes of an application; once it has keys, `DomainError.for()` takes only those and `ELYSIUM_PROBLEM_CODES`.
+  - Every problem carries `code`, `requestId` (from `problems.requestId`, a valid `x-request-id` header, or a random UUID) and `instance`. Its `type` is the kebab-case slug of the code, under `problems.typeBase`.
+  - Errors as values: a handler, a flow step, `UnitOfWork.run()` or a `@Transactional()` method that returns a DomainError rolls back and sends or returns it like a thrown one. `Commands.execute()` and `Queries.ask()` return the DomainError that refused the call, and a returned error joins the route's response type for typed clients.
+
+- [#20](https://github.com/na2axl/elysiumjs/pull/20) [`87299fd`](https://github.com/na2axl/elysiumjs/commit/87299fd9da82d1a408ced1891c0c3d42991444e5) Thanks [@na2axl](https://github.com/na2axl)! - The framework event bus is `Lifecycle`: `Lifecycle.on`, `Lifecycle.once`, `Lifecycle.emit`, `Lifecycle.off`, `@Lifecycle.on()` and `@Lifecycle.once()`, with the `LifecycleEvent` and `LifecycleHandler` types. It carries the framework's own signals (`elysium:error`, app and server lifecycle, heracles queue events) and in-process listeners.
+
+- [#22](https://github.com/na2axl/elysiumjs/pull/22) [`bee66bd`](https://github.com/na2axl/elysiumjs/commit/bee66bdc874b8f23fea356f7d3adf7555a48ca64) Thanks [@na2axl](https://github.com/na2axl)! - Decorators take their main identifier first and their options second.
+
+  - `@Http.controller(path, options)` and the route decorators `@Http.get(path, options)`, `post`, `put`, `patch`, `del`, `head`, `options`, `trace` and `sse`. The path defaults to `/`. `@Http.custom(method, path, options)` takes its method first. The options are `HttpControllerOptions` and `HttpRouteOptions`.
+  - `@Websocket.controller(path, options)`, where the options are those of the websocket server.
+  - `@Flow.controller(name, options)`, and `@Flow.step(name, options)` or `@Flow.step(options)` for a step named after its method.
+  - `@Lifecycle.on(event, options)` and `@Lifecycle.once(event, options)`, like their function forms `Lifecycle.on(event, handler)`.
+  - The styx controller stubs generate the same forms.
+
+- [#10](https://github.com/na2axl/elysiumjs/pull/10) [`0057b67`](https://github.com/na2axl/elysiumjs/commit/0057b67df0e3abecab8a9accff6b55a6a64c21df) Thanks [@na2axl](https://github.com/na2axl)! - `styx routes:generate` writes the route types of an app to `src/routes.gen.ts`: an `AppRoutes` type for Eden (`treaty<AppRoutes>(url)`), built from the controllers of every module. Request types come from the method parameters decorated with `@Http.param`, `@Http.query` and `@Http.body`, and response types from the method return types. The file holds types only; requests are served by the decorated controllers. New projects run the command in their `typecheck` script and keep the file out of git.
+
+  `Http.describe(controller)` reports the routes of an HTTP controller, and `Application.moduleGraph()` builds the module graph of an app class without booting it.
+
+- [#11](https://github.com/na2axl/elysiumjs/pull/11) [`632d77b`](https://github.com/na2axl/elysiumjs/commit/632d77b561fc43ade605fb69b06ac1b9b9a2ffc4) Thanks [@na2axl](https://github.com/na2axl)! - Services are identified by their class, or by the name given to `@Service.register({ name })`. Class names are never used as identifiers, so services resolve the same way in minified builds; `bun run check:minified` in core bundles a minified app and checks that every service resolves. `@Service.inject()` without an argument injects the class of the parameter type, and throws when the type is unknown. Factory services in a module's `services` take a class or a name in `name`.
+
+  `ServiceScope.REQUEST` gives one instance per HTTP request, shared by the request's middlewares, controller and handler. `Service.runInRequestScope(fn)` opens a request scope outside a route. Resolving a request-scoped service outside a request throws `OutsideRequestScopeError`, and a singleton (or a server-scoped controller) depending on one throws `ScopeMismatchError`.
+
+  `HermesModule` registers the logger by the `HermesLogger` class and as `logger`.
+
+- [#13](https://github.com/na2axl/elysiumjs/pull/13) [`1ea417e`](https://github.com/na2axl/elysiumjs/commit/1ea417e3583250bc2f975d795f398b7ff736115d) Thanks [@na2axl](https://github.com/na2axl)! - Hardening of the runtimes, the container and the CLI, checked by a conformance suite that runs on Bun, Node.js and workerd.
+
+  Breaking changes:
+
+  - `Runtime` gains the required `argv()`, `write(stream, text)` and `terminal()` members: core reaches the host's arguments, output streams and terminal only through the runtime. Custom runtimes must implement them.
+  - The third parameter of `InteractsWithConsole.write` is now `'stdout' | 'stderr'`.
+  - The WebSocket options are narrowed to `idleTimeout`, `maxPayloadLength` and `perMessageDeflate`, and the `bun` WebSocket types are replaced by `ElysiumWebSocket`.
+  - Redis connections are `RedisConnection`s, a port any Redis client can implement, instead of `Bun.RedisClient`.
+  - `styx create @scope/name` creates the project in `name/`, and refuses project and module names with upper-case letters.
+  - Queue handlers no longer reject the batch: after the handlers ran, each message is acked or retried on its own. `@Workers.queue(name, { each: true })` receives one message at a time, so a failure retries only that message.
+
+  Fixes:
+
+  - Request-scoped services are destroyed when the request ends, also on failure, and an async `onInit` is awaited. A second dispose of a request scope waits for the one in progress, so a Worker's `waitUntil` covers an async `onDestroy`.
+  - A failed module or service `onInit` no longer breaks later requests: the boot is retried, and the module's event listeners are unwired.
+  - `@elysiumjs/runtime-node` serves through `node:http`, keeping the Host header authoritative.
+  - `styx create` validates names before creating files, ships `.gitignore`, declares the dependencies of created projects and imports their default controllers.
+
+- [#14](https://github.com/na2axl/elysiumjs/pull/14) [`0956186`](https://github.com/na2axl/elysiumjs/commit/0956186db0ca5a83c0a6636aeb2a4c81a0033de4) Thanks [@na2axl](https://github.com/na2axl)! - The request pipeline: problem details, exception filters, interceptors, typed configuration, HTTP security options and an HTTP test client, checked on Bun, Node.js, workerd and AOT-compiled Workers.
+
+  Breaking changes:
+
+  - Error responses are RFC 9457 problem details (`application/problem+json`). Request validation errors answer 422 with an `errors` list of JSON pointers (`problems.validationStatus: 400` keeps 400). Server errors only show their message and stack in development. Thrown statuses (`c.status(...)`) are sent as they are.
+  - Client errors (4xx) are no longer reported to `onError`, the `elysium:error` event or the trace.
+  - `Runtime.serve` may return a handle with `close()`, which the application calls on shutdown.
+  - Request bodies are limited to 1 MiB by default (`http.bodyLimit`), also when chunked.
+  - The environment schema is validated when the app is built or run, with every error reported at once, instead of in the constructor.
+
+  Features:
+
+  - `DomainError`, with `status`, `type`, `title`, `detail` and extensions, and shortcuts such as `DomainError.notFound()`.
+  - Exception filters (`@Catch()`, `filters` on routes, controllers, modules and the app) and interceptors (`interceptors` on the same levels), with `TimingInterceptor`, `TransformInterceptor` and mnemosyne's `CacheInterceptor`.
+  - Typed configuration: `Secret` values, module `envSchema`s merged into the app's, `InvalidEnvironmentError`.
+  - `http` options: CORS, security headers, body limits and trusted proxies (`ctx.ip`). Runtimes report the client address through `clientAddress`.
+  - `createTestingHttpApp` and `createHttpClient` send requests to an app in memory, with `expectStatus()`.
+
+  Fixes:
+
+  - App-level `onRequest` middlewares run in the request scope.
+  - On Workers, the request scope of a streamed response is disposed when the body ends, not when `fetch` returns.
+  - `KeyvWorkersKV.clear()` stays within an operation budget (`maxOperations`).
+  - The Node.js bridge treats a destroyed socket as a client abort.
+  - Heracles performance metrics report through the Redis port (`connection` or `client`), not a Bun client.
+  - `styx routes:generate` names anonymous default controllers after their file; `styx create` pins `@elysiumjs/*` packages to the versions it was released with; invalid names are reported as Elysium errors.
+
+- [#15](https://github.com/na2axl/elysiumjs/pull/15) [`fbcc7da`](https://github.com/na2axl/elysiumjs/commit/fbcc7dad127db29da42e7a4a5c2124966731cd88) Thanks [@na2axl](https://github.com/na2axl)! - Resources, queries, units of work and rate limits.
+
+  Breaking:
+
+  - A route with a `response` schema serializes its handler result through it: fields the schema does not declare are dropped, a `Date` becomes an ISO string (`YYYY-MM-DD` for `format: 'date'`), and an object with `toJSON()` becomes what it returns. Set `serialize: false` on a route to send the result as it is.
+
+  Added:
+
+  - `Resource.hidden(schema)` marks a field that never reaches responses nor the OpenAPI document. `Resource.serialize()` and `Resource.project()` are exported for use outside routes.
+  - Sparse fieldsets: `?fields=id,title` keeps only those fields of an object, of each item of an array, or of each item of a `data` array. An unknown or hidden field answers a 400 problem.
+  - Rate limits with `@RateLimit({ window, max, key?, store?, name? })` on routes and controllers (`@RateLimit(false)` turns one off), and a default limit and store in the app's `rateLimit` option, with fixed windows. Responses carry `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy`; a client over the limit gets a 429 problem with `Retry-After`. Counts are kept by a `RateLimitStore`: `MemoryRateLimitStore` (core), `RedisRateLimitStore` (`@elysiumjs/redis`) or `WorkersRateLimitStore` over a Cloudflare rate limiting binding (`@elysiumjs/runtime-workers`), which only decides whether a hit is over the limit, so its responses carry no `RateLimit-Reset`.
+  - `ModelResource(model, { hidden, pick, omit, extend })` (`@elysiumjs/mnemosyne`) builds a response schema from a model.
+  - `Query.define(model, spec)` declares the filters (`filter[field][op]=value`), sorts, page size and cursor a list accepts; `Query.schema()` gives its query schema, `Query.parse()` turns a request query into a `ParsedQuery` and answers a 400 problem with a pointer per mistake, and `Query.page()` / `Query.pageSchema()` build cursor pages (`{ data, nextCursor }`).
+  - `DrizzleRepository.list(query)` and `count(query)` run a `ParsedQuery` with keyset pagination (`@elysiumjs/mnemosyne-drizzle`), and `compileQuery()` gives its `where` and `orderBy`.
+  - Units of work: `UnitOfWork.run()` and the `@Transactional()` method decorator run work in one transaction, and `UnitOfWork.afterCommit()` / `afterRollback()` defer work, such as sending a message, until the outermost transaction has ended. `transactional` routes open a unit of work too.
+
+- [#16](https://github.com/na2axl/elysiumjs/pull/16) [`ac96e55`](https://github.com/na2axl/elysiumjs/commit/ac96e55874b0ffe350b287c4278cd85afecb7576) Thanks [@na2axl](https://github.com/na2axl)! - Redis, databases, logs, jobs and builds on Bun, Node.js and Cloudflare Workers.
+
+  Breaking:
+
+  - The level shortcuts of `InteractsWithConsole` (`info`, `success`, `warning`, `error` and `debug`) write a tag (`[I]`, `[S]`, `[W]`, `[E]` and `[D]`, in color) before the message, which `InteractsWithConsole.useTags()` changes. `trace()` writes to stderr.
+  - Outside Bun, a Drizzle connection needs a `driver`. Without one, the `connection` and `client` props are a Bun SQL connection, which is only available on Bun; elsewhere the connection throws `MissingDriverError`, which names the drivers.
+
+  Added:
+
+  - Redis adapters (`@elysiumjs/redis`): `ioredis(create)` plugs an ioredis client into the Redis port on Node.js, and `upstash({ token, url?, fetch? })` talks to Upstash over its REST API, for Workers (no pub/sub). `bunRedis` explains which adapter to use when it runs outside Bun.
+  - Drizzle drivers (`@elysiumjs/mnemosyne-drizzle`): a `DrizzleDriver` port set with the `driver` prop of a connection, and drivers on subpaths so that only the chosen database client is imported: `/bun-sql` (`bunSql()`), `/postgres-js` (`postgresJs()`), `/node-postgres` (`nodePostgres()`) and `/hyperdrive` (`hyperdrive({ binding, driver })`, a client per Worker invocation over a Cloudflare Hyperdrive binding). `DrizzleModule` closes connections through their driver, and `migration:run` runs on any driver.
+  - `InteractsWithConsole.write()` and `Runtime.write()` take the level of the line (`OutputLevel`), which the level shortcuts pass. On Cloudflare Workers, a line is written with the console method of its level, so Workers Logs keep it.
+  - `JsonConsoleLogger` (`@elysiumjs/hermes`): JSON lines through the console of the runtime (warnings and errors on stderr), with levels, error serialization and `child()`. `HermesModule.with({ transport: 'console' | 'pino' })` picks it, and it is the default on Workers. `RequestLogInterceptor` writes one structured line per request: method, route, status, duration, client address and request id.
+  - Scheduled jobs (`@elysiumjs/heracles`): `@Schedule(cron, { timezone, args })` on a job class, a five-field cron parser (`Cron`, with lists, ranges, steps and names), and a `Scheduler` that dispatches the jobs on time on Bun and Node.js, taking a Redis lock per tick when a Redis connection is set. The `heracles:schedule` command runs it.
+  - `@elysiumjs/heracles-workers`: `CloudflareQueueTransport` sends jobs to a Cloudflare Queue (dispatch delays become `delaySeconds`), and `HeraclesWorkersModule` consumes them in the Worker's `queue` handler (ack on success, retry with a delay up to the job's retries) and dispatches the `@Schedule()` jobs whose expression is the cron of a trigger.
+  - Queue handlers (`@elysiumjs/runtime-workers`) can settle a message themselves with `ack()` or `retry({ delaySeconds })`; the messages they leave are acked when no handler failed on them.
+  - `styx build --target node` (`@elysiumjs/hephaestus`) bundles the app into one ES module for Node.js, with decorator metadata emitted at build time, run with `node dist/server.js serve`. `styx build --target workers` runs from the CLI, resolves packages to their browser entry, and leaves Node.js modules imported by bare names to workerd (`nodejs_compat`).
+  - `styx create` (`@elysiumjs/styx`) takes `--runtime bun|node|workers`, `--database`, `--cache` and `--package-manager bun|npm|pnpm`. Each runtime gets its entry, tsconfig types, scripts and drivers: postgres.js and ioredis on Node.js; Hyperdrive, Upstash, console logs and a `wrangler.jsonc` on Workers.
+
+- [#12](https://github.com/na2axl/elysiumjs/pull/12) [`98a16aa`](https://github.com/na2axl/elysiumjs/commit/98a16aae889d46f7a9fb5573188f4cbe3629dd3b) Thanks [@na2axl](https://github.com/na2axl)! - `createWorker(app)` from `@elysiumjs/runtime-workers` builds an application and returns the handlers a Cloudflare Worker exports: `fetch` serves the routes, `queue` hands each batch to the service methods marked `@Workers.queue(name)`, and `scheduled` calls the methods marked `@Workers.cron(expression)`. Each invocation runs with its own env and execution context: `Workers.env()`, `Workers.context()` and `Workers.binding(name)` read them, and `WorkersModule` provides them, and the bindings it lists, as request-scoped services injected with `@Workers.inject(name)`. `KeyvWorkersKV` stores mnemosyne caches in a KV namespace. `bun run check:wrangler` runs a sample Worker in `wrangler dev`.
+
+  `MnemosyneModule` takes other Keyv stores in `cache.stores`, read with `Cache.store(name)`.
+
+  `styx build --target workers` (Hephaestus `hephaestus:build --target workers`, `WorkersBuilder`) bundles a Worker with its routes compiled ahead of time and refuses a bundle that generates code at runtime.
+
+  In core, `Application.boot()` initialises the modules once, for hosts that handle more than requests; `Kernel.serviceClasses(node)` lists the service classes of a module; console output falls back to `console` where the host has no output streams; and a singleton depending on a request-scoped service throws `ScopeMismatchError` even when it is built outside a request.
+
+## 0.10.0
+
+### Minor Changes
+
+- [`68a0cdd`](https://github.com/na2axl/elysiumjs/commit/68a0cdd8b2e4a003d6e0af2d78985623cae40428) Thanks [@na2axl](https://github.com/na2axl)! - Route the framework's own diagnostics through the logger service.
+
+  Breaking changes:
+
+  - `@Event.listen()` with a mode other than `on` or `once` now throws an `ElysiumError` when the class is defined, instead of logging to the console and ignoring the listener.
+
+  Fixes and additions:
+
+  - `getLogger(context?)` and `LOGGER_SERVICE` (`'logger'`) are exported by `@elysiumjs/core`. `getLogger()` returns the `logger` service when one is registered (such as the one `HermesModule` provides), and a `ConsoleLogger` otherwise or when the service cannot be built or fails to create a child logger. It is resolved at call time from the global scope only, so a module's own `logger` service does not replace it, and returns a child logger bound to `context` when one is given.
+  - `Middleware.logger` (used by `RequestLoggerMiddleware`) falls back to a `ConsoleLogger` when no `logger` service is registered. It threw before.
+  - Core diagnostics go through the logger with structured context instead of `console.*`: the debug-mode request log (`debug`, with `method` and `url`), `onDestroy` failures on shutdown (`error`, with `target` and `error`), WAMP connection attempts (`warn` while retrying, `error` when giving up, with `connection`, `attempt`/`attempts`, `maxRetries` and `error`), and WAMP registrations and subscriptions (`info`, with `connection`, `topic` and the registration or subscription id).
+  - In debug mode, incoming requests are logged through the logger at `debug` level instead of printed with `console.log`. With `HermesModule`, they show only when its `level` is `debug` or `trace`.
+  - A failed WAMP registration or subscription is logged at `error` level and emitted as `elysium:error` with an error naming the topic and the connection, instead of becoming an unhandled rejection.
+  - The `elysium:error` emitted for a WAMP client error names the connection and its URL and includes the client's message (or the value it reported, when it is not an `Error`), with that value as `cause` when there is one.
+  - `HermesLogger` serialises an `error` field of the log context like pino's `err` (type, message and stack), so logged errors keep their stack trace. Elysium logs errors under `error`.
+  - `@Logged` resolves its fallback logger with `getLogger()`, and logs a thrown error whole under `error` (it logged only its message), so its stack trace is kept.
+  - The `elysium:error` emitted when a WAMP connection gives up states the number of attempts actually made (the first one plus the retries), as the logged `attempts` does. It stated `maxRetries` before.
+
+- [`76ba0ff`](https://github.com/na2axl/elysiumjs/commit/76ba0ff18f3c196cebc2189426328f67cb699f46) Thanks [@na2axl](https://github.com/na2axl)! - `onRequest` middlewares registered on a module or a controller now run only for its routes. Elysia runs `onRequest` hooks on every request of the app, so such a middleware could reject requests meant for other modules.
+
+  They now run in the transform step of their own routes, so after routing and body parsing, and each one runs right before its own `onTransform`: module `onRequest`, module `onTransform`, then controller `onRequest`, controller `onTransform`. Any value they return still stops the request and is sent as the response. Application middlewares still run `onRequest` before routing, for every request.
+
+- [`bacce71`](https://github.com/na2axl/elysiumjs/commit/bacce7146f667a1a46bf474dc0344fb0111ae12a) Thanks [@na2axl](https://github.com/na2axl)! - WebSocket controllers now run the middlewares registered on them with `@Middleware.register()`, on the upgrade request. `onRequest`, `onTransform` and `onBeforeHandle` can refuse the connection by returning a response. `onAfterHandle` and `onAfterResponse` run after the upgrade, with no response to read.
+
+### Patch Changes
+
+- [`2c49acd`](https://github.com/na2axl/elysiumjs/commit/2c49acd3b552aa43765d70339fa216961499e1b5) Thanks [@na2axl](https://github.com/na2axl)! - The tenant set by a middleware, such as a `TenantMiddleware` reading its own header, is no longer replaced by the `x-tenant-id` header (or `public`) before the handler runs.
+
+- [`4ebf029`](https://github.com/na2axl/elysiumjs/commit/4ebf029611e6d753a4f1bfdbe247a75d954d9ded) Thanks [@na2axl](https://github.com/na2axl)! - WAMP clients use Bun's own `WebSocket` again. The subclass that faked the `protocol` field is gone, since Bun now fills it (oven-sh/bun#18744).
+
+## 0.9.0
+
+### Minor Changes
+
+- [`5fef4a7`](https://github.com/na2axl/elysiumjs/commit/5fef4a7199f502fc4fe035299e7670739459a108) Thanks [@na2axl](https://github.com/na2axl)! - Fix tenant isolation, transactions and query caching in the database layer.
+
+  Breaking changes:
+
+  - `TenantMiddleware.validateTenant()` now rejects every tenant unless you override it, and tenant identifiers must match `TENANT_ID_PATTERN` (1 to 63 ASCII letters, digits, `_` or `-`, not starting with `pg_` and other than `information_schema`, in any case) before it is called. Requests that send any other tenant now fail with `Invalid tenant`. Requests without a tenant still resolve to `public` on `SimpleTenantMiddleware`. To migrate, check the tenant against your own data:
+
+    ```ts
+    class OrganizationMiddleware extends SimpleTenantMiddleware {
+    	protected async validateTenant(tenant: string): Promise<boolean> {
+    		return Organization.exists(tenant);
+    	}
+    }
+    ```
+
+  - `getTenantSchema()`, `registerTenantSchema()` and `wrapTenantSchema()` throw on tenant identifiers that do not match `TENANT_ID_PATTERN`.
+  - `setConnectionTenant()` is removed. It set the tenant on a pooled connection for the whole session, so the tenant leaked to other requests. Use `withRLS()`, or `Database.transaction()` in RLS mode, which scope the tenant to a transaction.
+  - `RepositoryInterface.update()` and `delete()`, and the `DrizzleRepository` implementations, return `null` when no row has the id. They returned `undefined` while typed as a row. `DrizzleRepository` also requires a model whose table has an `id` column.
+  - `@transactional` handlers run through the `db.transaction` service that `DrizzleModule` provides (its name is exported by `@elysiumjs/core` as `DATABASE_TRANSACTION_SERVICE`, and still re-exported by `@elysiumjs/mnemosyne`). A transactional handler without a database module now fails with an error naming the service.
+  - `@transactional` generator handlers commit only when the whole stream was sent. A stream closed early, or whose client disconnects (even while the handler is waiting), rolls back.
+  - In RLS mode, a transaction is bound to one tenant for its whole life: the tenant set (with a transaction-local `set_config`) when `Database.transaction()`, a `@transactional` handler, `withRLS()` or `withIsolation()` opens it, from the explicit tenant or the current one (`public` when there is none). Work that finds a transaction open on its connection (`withRLS()`, `withIsolation()`, `Database.transaction()`, repository calls) joins it only when its tenant is the transaction's tenant, and throws `TenantMismatchError` otherwise, without running anything: the tenant of an open transaction never changes. Inside a transaction, `Database.getConnection()` only returns it to work for its tenant (the current tenant, or `public`), and throws `TenantMismatchError` otherwise, so raw queries never run for another tenant; queries on the `tx` handle a callback received run as the transaction's tenant. Work for several tenants, such as an admin fan-out, must use one `withRLS()` per tenant outside any transaction, not nested in one.
+  - In RLS mode, each repository call made outside a transaction runs in its own transaction bound to the current tenant: `BEGIN`, `set_config` of the tenant, the query, `COMMIT`. These calls do not use the query cache, since the cache is bypassed inside transactions. Group calls in `Database.transaction()` or `withRLS()` to share one transaction.
+  - In RLS mode, code running without a tenant in context (background jobs, CLI commands, scripts) is scoped to the `public` tenant. Set the tenant with `withTenant(tenant, () => ...)` around the work (repository calls and `Database.transaction()` then use it), or with `withRLS(tenant, (tx) => ...)`.
+  - `migration:run` validates `--tenant` against `TENANT_ID_PATTERN`. Without a terminal it no longer creates a missing schema: pass `--create-schema` (which also skips the question in a terminal), or it fails.
+  - Query cache keys start with the connection name, and each connection has its own cache transaction scope. When several applications or environments share one cache store and use the same connection names for different databases, set `cache: { prefix }` on each connection: the prefix comes before the connection name in every key (empty by default).
+  - `DrizzleDatabaseCache` keys and values changed: entries written by earlier versions are ignored. The default TTL of cached queries (including with `cache: true`) is now 60 seconds instead of 1 second, and is set with `cache: { ttl }` in seconds.
+  - `Cache.memory` keeps a separate LRU per tag namespace, so `lruSize` applies to each namespace.
+
+  Fixes and additions:
+
+  - In RLS mode, repository operations outside a transaction run in one bound to the current tenant, through the strategy's `withIsolation()`. Transactions opened with `Database.transaction()` or by `@transactional` handlers set the tenant variable when they open. `withIsolation()` and `withRLS()` expose their transaction to repositories and `Database.getConnection()`. `TenantMismatchError` is exported.
+  - `Database.transaction(callback, connection?)` opens a transaction and registers it for the callback. When a transaction is already open on the same connection, the callback joins it (no savepoint: an error rolls back the whole transaction); in RLS mode only if the current tenant is the transaction's tenant (see above). Transactions are tracked by connection, so every name of a connection (`default` and the name it aliases) sees them, and named connections take part in transactions. `Database.getBaseConnection()`, `Database.inTransaction()` and `Database.runInTransaction()` are added. The `db:tx` context entry is still set for the default connection.
+  - `@transactional` generator handlers keep their transaction open until the stream ends, then commit (or roll back if the handler throws). They previously committed before running and failed with `generator.next is not a function`. Generator handlers also see the request context (`tenant`, `http:context`).
+  - The query cache is scoped to the connection and the current tenant, is shared correctly by several app instances (table versions stored in the cache), is not read or written inside transactions, and invalidates the tables a transaction changed once it commits. A result is only stored when no mutation happened since its query started, including when concurrent queries of the same key finish out of order. Cached queries honour Drizzle's `ex`, `px`, `exat`, `pxat` and `keepTtl` options.
+  - Cache namespaces (`Cache.redis.tags(...)`, `Cache.memory.tags(...)`) no longer overwrite each other: reads, deletes and `clear()` stay within their namespace.
+  - `getSessionTenant()` reads the Bun SQL result correctly, and `getCurrentTenant()` works without an application instance (for example under `Application.testing`).
+  - `migration:run` takes an advisory lock per tenant, adds a unique index on `elysium_migrations.name` (also to existing tables), finds the migrations from the project root (`.elysiumrc`), sets the `search_path` for the transaction only, asks before opening the transaction whether to create a missing schema, and always closes its client. Existing duplicate migration names must be removed before the unique index can be created.
+  - `migration:generate` only removes `"public".` qualifiers from the migration it generates, and leaves string literals, comments and dollar-quoted bodies (`DO` blocks, functions) untouched.
+  - `DatabaseDriver.createConnection()` receives the connection name as an optional second argument.
+  - `KeyvRedis` deletes with a single `UNLINK` (or `DEL`) per call or batch and reports failed deletes in `clear()` as `error` events.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -19,7 +19,7 @@ bun install @elysiumjs/core
 - WebSocket support
 - WAMP protocol integration
 - Command-line interface (`@elysiumjs/styx`), with support for custom commands
-- Event system
+- Lifecycle events
 - Caching (memory and Redis)
 - PostgreSQL database support with Drizzle ORM
 - Model classes and repositories for database interactions
@@ -33,9 +33,9 @@ Create a controller class:
 ```typescript
 import { Http } from '@elysiumjs/core';
 
-@Http.controller({ path: '/users' })
+@Http.controller('/users')
 export class UserController {
-	@Http.get({ path: '/:id' })
+	@Http.get('/:id')
 	public getUser(id: string) {
 		return { id };
 	}
@@ -103,6 +103,40 @@ Or, if using `styx`, run:
 bun styx serve
 ```
 
+## Services
+
+A service is identified by its class. Give it a name with `@Service.register({ name })` to look it up by that string instead. Class names are never used as identifiers, so services resolve the same way after a bundler renames classes (`bun run check:minified` builds a minified app and checks it).
+
+```typescript
+import { Service, ServiceScope } from '@elysiumjs/core';
+
+@Service.register()
+export class UserRepository {}
+
+@Service.register({ name: 'mailer' })
+export class MailerService {}
+
+@Service.register()
+export class UserService {
+	constructor(
+		@Service.inject(UserRepository) private readonly users: UserRepository,
+		@Service.inject('mailer') private readonly mailer: MailerService
+	) {}
+}
+```
+
+`@Service.inject()` without an argument injects the class of the parameter type, read from `emitDecoratorMetadata`. Pass the class or the name when the type is an interface or is missing; Elysium throws at declaration time when it cannot tell which service to inject.
+
+A service has one of three scopes:
+
+| Scope                    | Instances                                                   |
+| ------------------------ | ----------------------------------------------------------- |
+| `ServiceScope.SINGLETON` | One for the app (the default)                               |
+| `ServiceScope.FACTORY`   | A new one each time the service is resolved                 |
+| `ServiceScope.REQUEST`   | One per HTTP request, shared by its middlewares and handler |
+
+A request-scoped service resolves only inside a request: resolving it elsewhere throws `OutsideRequestScopeError`. Code outside a route, such as a job or a test, opens a scope with `Service.runInRequestScope(fn)`; every request-scoped service resolved inside `fn`, including after an `await`, is shared for that run. A singleton, or a controller with the default server scope, cannot depend on a request-scoped service, since it would keep the first request's instance: Elysium throws `ScopeMismatchError`. Use a request-scoped controller (`scope: HttpControllerScope.REQUEST`), or inject the service in the route handler's parameters.
+
 ## Lazy boot
 
 A CLI command boots lazily: running `app:cmd` initialises the command's own module and the modules it imports, not the whole graph. `help <cmd>` is always lazy, even for commands with `static boot = true`.
@@ -112,9 +146,33 @@ A CLI command boots lazily: running `app:cmd` initialises the command's own modu
 - **Use `static boot = true`** on a command that needs every module initialised before it runs (workers, servers). It initialises every module and builds every service first.
 - Service factories receive a synchronous `get`; it may only read services whose owning modules initialise synchronously, otherwise it throws `ServiceNotReadyError`.
 
+## Runtimes
+
+Core never calls a host API directly. Environment variables, timers, the HTTP server, process exit and shutdown signals come from a runtime, which ships as its own package:
+
+| Package                      | Exports                             | Notes                                                                                                     |
+| ---------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `@elysiumjs/runtime-bun`     | `runtime`                           | `Bun.env`, `Bun.sleep`, `listen`, process exit and signals                                                |
+| `@elysiumjs/runtime-node`    | `runtime`                           | Same on Node.js; set `server: { adapter: node() }` from `@elysiajs/node`                                  |
+| `@elysiumjs/runtime-workers` | `runtime`, `createRuntime({ env })` | Env from `process.env` (`nodejs_compat`) or `env`; no `serve` (export the app's `fetch`), exit or signals |
+
+Each package exports `runtime` (rename it at import if you like). Pass it to the application, or call `Runtime.use()` before anything needs it:
+
+```ts
+import { Application } from '@elysiumjs/core';
+import { runtime } from '@elysiumjs/runtime-bun';
+
+@Application.register({ runtime, modules: [] })
+class App extends Application {}
+```
+
+Without a runtime, `Runtime.get()` throws `RuntimeNotConfiguredError`; only the environment name falls back to `development`. `bun run check:runtime` bundles core, fails if it touches the `Bun` global, and boots an application from the bundle under Node.js.
+
 ## Migrating from the pre-module API
 
 - The `database`, `redis`, `wamp` and `elysium:hermes` keys of `@Application.register()` are gone. Add `DrizzleModule.with()`, `RedisModule.with()`, `WampModule.with()` and `HermesModule.with()` to `modules` instead.
+- `Redis` and `RedisModule` moved to `@elysiumjs/redis`.
+- An application needs a runtime: add `runtime` from `@elysiumjs/runtime-bun` to `@Application.register()`.
 - `plugins` no longer takes package plugins. Add the package's module (for example `SentryModule`) to `modules`.
 - Importing a file no longer registers its commands or services. List commands in a module's `commands`, services in `services`, and jobs in `jobs`.
 - `new App()` is replaced by `await App.start()`. `Application.testing()` boots a module graph for tests.
@@ -133,4 +191,4 @@ Feel free to open issues for any bugs or questions you may have. Pull requests a
 
 ## License
 
-This project is licensed under the Apache License, Version 2.0. See the [LICENSE](https://github.com/workbud/elysium/blob/main/LICENSE) file for more information.
+This project is licensed under the Apache License, Version 2.0. See the [LICENSE](https://github.com/na2axl/elysiumjs/blob/main/LICENSE) file for more information.

package/dist/app.d.ts

@@ -1,8 +1,16 @@
-import type { ElysiaOpenAPIConfig } from '@elysiajs/openapi';
-import type { AnyElysia, ElysiaConfig, ErrorContext, TSchema } from 'elysia';
+import type { ElysiaOpenAPIConfig } from '@elysia/openapi';
+import type { AnyElysia, ErrorContext } from 'elysia';
+import type { TSchema } from 'typebox';
+import type { FilterClass } from './filter';
 import type { Route } from './http';
+import type { InterceptorClass } from './interceptor';
 import type { ConfiguredModule, ModuleClass } from './module';
-import type { TestingApp, TestingOptions } from './testing';
+import type { ModuleGraph } from './module-graph';
+import type { ProblemOptions } from './problem';
+import type { AppRateLimitOptions } from './rate-limit';
+import type { Runtime as RuntimePort } from './runtime';
+import type { HttpOptions } from './security';
+import type { TestingApp, TestingAppOptions, TestingHttpApp, TestingOptions } from './testing';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { Elysia } from 'elysia';
 import { InteractsWithConsole } from './console';
@@ -24,12 +32,18 @@ export type AppProps = {
     /**
      * The Elysia server configuration.
      */
-    server?: ElysiaConfig<Route> & {
+    server?: ElysiaConfig & {
         /**
          * The port to listen on.
          */
         port?: number;
     };
+    /**
+     * The runtime the application runs on, from `@elysiumjs/runtime-bun`, `@elysiumjs/runtime-node`
+     * or `@elysiumjs/runtime-workers`. Can be omitted when `Runtime.use()` was called before.
+     * The runtime is process-wide: when several applications are constructed, the last one wins.
+     */
+    runtime?: RuntimePort;
     /**
      * The modules the application is made of. They act as the imports of the root module.
      */
@@ -39,7 +53,7 @@ export type AppProps = {
      *
      * Set it to `false` to disable OpenAPI documentation.
      */
-    openapi?: ElysiaOpenAPIConfig | false;
+    openapi?: ElysiaOpenAPIConfig<boolean, string> | false;
     /**
      * The validation schema for the application environment.
      */
@@ -48,12 +62,53 @@ export type AppProps = {
      * The list of plugins to load.
      */
     plugins?: ElysiumPlugin[];
+    /**
+     * How errors are rendered as RFC 9457 problem details: the base of relative problem types, and
+     * the status of validation errors.
+     */
+    problems?: ProblemOptions;
+    /**
+     * Exception filters for every request, run after the filters of the route, the controller and
+     * the module, and before the default problem details rendering.
+     */
+    filters?: FilterClass[];
+    /** Interceptors around every request handler, outside those of the modules. */
+    interceptors?: InterceptorClass[];
+    /**
+     * HTTP security: CORS, security headers, the request body limit (1 MiB by default) and the
+     * trusted proxies that give `ctx.ip`.
+     */
+    http?: HttpOptions;
+    /**
+     * Rate limiting: the store of every limit (in memory by default), and a limit for every route
+     * whose controller and route set none, when `window` and `max` are given.
+     */
+    rateLimit?: AppRateLimitOptions;
+};
+/** The options of the root Elysia app. */
+type ElysiaConfig = NonNullable<ConstructorParameters<typeof Elysia>[0]>;
+/**
+ * An error raised while handling a request, as given to the Elysia error hook. `code` is set for
+ * the errors Elysia raises ('validation', 'not-found', ...).
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ServerError = ErrorContext & {
+    code?: string;
+    error: any;
 };
 /**
  * Type for the application context.
+ *
+ * - `tenant`: the current tenant.
+ * - `http:context`: the context of the HTTP request being handled.
+ * - `db:transactions`: the open database transactions, keyed by the connection they run on.
+ * - `db:tx`: the transaction open on the default database connection. Kept for existing callers;
+ *   prefer `db:transactions`.
+ * - `uow:frame`: the outermost unit of work, which collects the hooks run after it commits or
+ *   rolls back (`@elysiumjs/mnemosyne`).
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export type AppContext = AsyncLocalStorage<Map<'tenant' | 'http:context' | 'db:tx', unknown>>;
+export type AppContext = AsyncLocalStorage<Map<'tenant' | 'http:context' | 'db:transactions' | 'db:tx' | 'uow:frame', unknown>>;
 /**
  * Base class for the application main entry.
  * @author Axel Nana <axel.nana@workbud.com>
@@ -85,10 +140,13 @@ export declare abstract class Application extends InteractsWithConsole {
      */
     static start<T extends Application>(this: new () => T): Promise<void>;
     /**
-     * Boots a module graph without a CLI or an HTTP server, for tests.
-     * @param options The modules to boot, service overrides, environment and boot mode.
+     * Sets up code under test. Given `app`, builds that application and returns an HTTP client that
+     * drives it in memory (`http.get('/x').send()`). Given `modules`, boots a module graph without a
+     * CLI or an HTTP server.
+     * @param options The application or the modules, service overrides, environment and boot mode.
      * @author Axel Nana <axel.nana@workbud.com>
      */
+    static testing(options: TestingAppOptions): Promise<TestingHttpApp>;
     static testing(options: TestingOptions): Promise<TestingApp>;
     /**
      * The kernel running this application's module graph. Available once `run()` has started.
@@ -112,7 +170,7 @@ export declare abstract class Application extends InteractsWithConsole {
      * @param _error The error context.
      * @returns Whether to continue the error propagation.
      */
-    protected onError(_error: ErrorContext): Promise<boolean>;
+    protected onError(_error: ServerError): Promise<boolean>;
     /**
      * Hook that is executed when the application starts.
      * @param _elysia The Elysia instance.
@@ -129,8 +187,15 @@ export declare abstract class Application extends InteractsWithConsole {
      * @param argv The command line arguments, without the executable and script.
      * @author Axel Nana <axel.nana@workbud.com>
      */
-    run(argv?: string[]): Promise<void>;
+    run(argv?: readonly string[]): Promise<void>;
     private props;
+    /**
+     * Builds the module graph of an application class without creating or booting anything.
+     * Used by tools that read the app's structure, such as the route type generator.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param environment The environment to build the graph for. Defaults to the current one.
+     */
+    static moduleGraph(environment?: string): ModuleGraph;
     private dispatch;
     /** Prints an error, shuts down what was started and exits with code 1. */
     private fail;
@@ -160,18 +225,65 @@ export declare abstract class Application extends InteractsWithConsole {
      */
     private commandExec;
     /**
-     * Starts the server: boots the kernel, builds the root Elysia app, lets modules hook into it,
-     * mounts their controllers and listens.
+     * Builds the root Elysia app without listening, for hosts that own the server (Cloudflare
+     * Workers) and for ahead-of-time compilation with `elysia/plugin/aot`, which evaluates the
+     * entry at build time.
+     *
+     * Modules are registered but not initialised: they boot on the first request, so building the
+     * app runs no `onInit` work and builds no service.
+     *
+     * @example
+     * ```ts
+     * export const app = await new App().build();
+     * export default { fetch: (request: Request) => app.fetch(request) };
+     * ```
+     * @returns The root Elysia app.
+     * @throws When the module graph is invalid or a module config is missing.
+     */
+    build(): Promise<Elysia<Route>>;
+    /**
+     * Validates the environment against the schemas of the app and its active modules, then makes
+     * the validated values available through `Env.get()`.
+     * @throws {InvalidEnvironmentError} Listing every missing or invalid variable.
+     */
+    private configureEnvironment;
+    /**
+     * Initialises every module and builds every singleton service, once. An app from
+     * {@link build} calls it on its first request; hosts call it before other work, such as a
+     * queue batch or a scheduled event.
+     * @throws When a module or a singleton fails to initialise. Later calls retry the failed ones,
+     * so that a transient failure does not break every later request. A permanent failure is
+     * retried, and fails, on every request.
      */
+    boot(): Promise<void>;
+    /** Starts the server: boots the kernel, builds the root Elysia app and listens. */
     private commandServe;
+    /**
+     * Builds the root Elysia app: lets modules hook into it and mounts their controllers.
+     * @param bootOnFirstRequest Whether the first request boots the modules, when they were only
+     * registered.
+     */
+    private buildServer;
+    /** Maps each route of the built server to the filter levels of its handler. */
+    private indexRouteFilters;
     /** Lets every module hook into the root app, then mounts the controllers of each module. */
     private serveModules;
     /** Builds the Elysia plugin of a module: its middlewares and the plugins of its controllers. */
     private mountModule;
     /** Registers the error handler and the start and stop hooks of the root app. */
     private setupServerHooks;
-    /** Turns an error raised while handling a request into the response sent to the client. */
+    /**
+     * Turns an error raised while handling a request into the response sent to the client: a
+     * thrown status as is, anything else as problem details. Only server errors are reported
+     * (`onError`, the `elysium:error` event and the trace); client errors are part of normal
+     * operation.
+     */
     private handleServerError;
+    /**
+     * Reports a server error: calls `onError`, emits `elysium:error` and traces it.
+     * @returns `false` when `onError` handled the error itself.
+     */
+    private reportError;
     /**
      * Describes the CLI and available commands.
      */
@@ -179,3 +291,4 @@ export declare abstract class Application extends InteractsWithConsole {
     private commandList;
     private commandDescription;
 }
+export {};