@nextrush/core 3.0.7 → 4.0.0-beta.1

package/dist/index.d.ts

@@ -1,12 +1,14 @@
-import { Middleware, Context, Plugin, Next } from '@nextrush/types';
-export { ContentType, Context, ContextState, HttpMethod, HttpStatus, HttpStatusCode, Middleware, Next, Plugin, PluginWithHooks, QueryParams, RouteHandler, RouteParams } from '@nextrush/types';
-export { BadRequestError, ForbiddenError, HttpError, InternalServerError, NextRushError, NotFoundError, UnauthorizedError, createError as createHttpError } from '@nextrush/errors';
+import { Logger, ProxyTrust, Router, Container, Middleware, RouteEntry, Context, Extension, Next } from '@nextrush/types';
+export { ContentType, Context, ContextState, Extension, ExtensionContext, ExtensionHost, HttpMethod, HttpStatus, HttpStatusCode, Logger, Middleware, Next, QueryParams, RouteEntry, RouteHandler, RouteParams, Router } from '@nextrush/types';
+export { BadRequestError, ForbiddenError, HttpError, InternalServerError, NextRushError, NotFoundError, UnauthorizedError } from '@nextrush/errors';
 
 /**
  * @nextrush/core - Application Class
  *
  * The Application class is the main entry point for NextRush.
- * It manages middleware registration and plugin installation.
+ * It manages middleware registration and the extension lifecycle.
+ *
+ * See docs/RFC/class-runtime/005-plugin-system.md for the extension model.
  *
  * @packageDocumentation
  */
@@ -16,13 +18,21 @@ export { BadRequestError, ForbiddenError, HttpError, InternalServerError, NextRu
  */
 type ErrorHandler = (error: Error, ctx: Context) => void | Promise<void>;
 /**
- * Logger interface for pluggable logging
+ * Options for {@link Application.close}.
+ *
+ * @see RFC-022 (`docs/RFC/class-runtime/022-bounded-teardown-lifecycle.md`) / ADR-0012.
  */
-interface Logger {
-    error(...args: unknown[]): void;
-    warn(...args: unknown[]): void;
-    info(...args: unknown[]): void;
-    debug(...args: unknown[]): void;
+interface CloseOptions {
+    /**
+     * Bound, in milliseconds, on total teardown time. Every teardown unit
+     * (extension `destroy()`) races against this budget independently — a
+     * unit that does not finish in time is reported as a {@link TeardownTimeoutError}
+     * in the returned array, and never blocks `close()` past the budget.
+     *
+     * @remarks Omitted = unbounded, identical to calling `close()` with no
+     * arguments today (`Promise.allSettled`, no timeout).
+     */
+    timeout?: number;
 }
 /**
  * Application options
@@ -34,37 +44,65 @@ interface ApplicationOptions {
      */
     env?: 'development' | 'production' | 'test';
     /**
-     * Whether to use proxy headers (X-Forwarded-For, etc.)
+     * Proxy-trust specification for `ctx.ip` resolution (RFC-030, SEC-01).
+     *
+     * @remarks
+     * `false` trusts nothing (the socket peer is always `ctx.ip`); a `number`
+     * trusts exactly that many reverse-proxy hops; a `string[]` of CIDR
+     * ranges/IPs trusts only a direct peer inside that set. `true` and `0`
+     * throw at construction — see {@link validateProxyTrust}.
+     *
      * @default false
      */
-    proxy?: boolean;
+    proxy?: ProxyTrust;
     /**
      * Custom logger. Defaults to no-op (silent).
      *
      * @remarks
-     * Pass `console` for quick development logging:
-     * ```ts
-     * const app = createApp({ logger: console });
-     * ```
-     *
-     * For production, provide a structured logger (e.g. pino, winston)
-     * that implements the {@link Logger} interface.
-     *
-     * Adapters and internal hooks use `app.logger` — configuring it here
-     * ensures consistent logging across the framework.
+     * Pass `console` for quick development logging. For production, provide a
+     * structured logger (pino, winston, `@nextrush/logger`) implementing {@link Logger}.
      */
     logger?: Logger;
+    /**
+     * A router the app owns. Route methods (`app.get`, `app.post`, …) delegate to
+     * it, and it is mounted last at `ready()`. The `nextrush` meta-package's
+     * `createApp` injects one automatically; pass it explicitly when using
+     * `@nextrush/core` directly.
+     */
+    router?: Router;
+    /**
+     * A per-app DI container. Exposed to extensions via `ExtensionContext.container`
+     * and used by class-based registrars (e.g. `registerControllers`). Injected by
+     * `nextrush/class`; omitted for functional, DI-free apps.
+     */
+    container?: Container;
 }
 /**
  * Listener callback type
  */
 type ListenCallback = () => void;
 /**
- * Routable interface - any object with routes() method
- * This allows mounting Router instances without circular dependency
+ * Routable interface - any object with routes() method.
+ * Allows mounting Router instances without a circular dependency.
  */
 interface Routable {
     routes(): Middleware;
+    /**
+     * Test whether `path` falls under this router's mount prefix, using the
+     * SAME normalization the router itself matches with (case folding per its
+     * `caseSensitive` option, structural normalization) — never a raw
+     * `startsWith` comparison, which would apply a different rule than the
+     * router's own dispatch (RFC-029, SEC-02/SEC-15). Optional so a minimal
+     * `Routable` (e.g. a test double) still mounts; {@link createPrefixMount}
+     * falls back to a literal prefix test when this is absent.
+     *
+     * @param path - The full, still-query-stripped request path being tested.
+     * @param prefix - The normalized mount prefix (leading `/`, no trailing `/`).
+     * @returns The path's remainder past the prefix (e.g. `/users` for
+     *   `/Admin/Users` mounted at `/admin`), or `undefined` if `path` is not
+     *   under `prefix` per this router's own normalization.
+     */
+    matchesMountPrefix?(path: string, prefix: string): string | undefined;
 }
 /**
  * The Application class
@@ -77,195 +115,183 @@ interface Routable {
  *   ctx.json({ message: 'Hello World' });
  * });
  *
- * // Mount with an adapter
- * listen(app, { port: 3000 });
+ * // Extensions (rare — long-lived services) are booted at ready(), which
+ * // adapters call automatically before start().
+ * app.extend(events());
+ *
+ * listen(app, { port: 8080 });
  * ```
  */
 declare class Application {
-    /**
-     * Middleware stack
-     */
     private readonly middlewareStack;
     /**
-     * Installed plugins
+     * Boot-time security audit checks contributed by tagged middleware
+     * (`security-boundaries` capability, task 8.1). Collected as `use()`
+     * registers each middleware; run once by `_boot()`, production-only.
      */
-    private readonly plugins;
+    private readonly securityAudits;
+    /** Registered extensions, in registration order (setup runs at ready()) */
+    private readonly extensions;
+    /** Registered extension names — enforces uniqueness */
+    private readonly extensionNames;
     /**
-     * Custom error handler
+     * Combined teardown-unit registration order: extension `destroy()`s and
+     * {@link onClose} hooks interleaved in the exact order they were registered,
+     * so `_shutdown()` can run the whole set in one reverse-of-registration pass
+     * (RFC-022 §7.3 — "teardown becomes a flat list of independently-isolated,
+     * budget-raced units"). Populated lazily by {@link extend} (for extensions
+     * declaring `destroy()`) and {@link onClose}.
      */
+    private readonly teardownUnits;
+    /** Whether {@link close} has started — {@link onClose} is a pre-shutdown-only registration point (RFC-022 §8.6). */
+    private _closeStarted;
+    /** Names decorated onto the app — enforces collision detection */
+    private readonly decorations;
     private _errorHandler;
-    /**
-     * Pluggable logger
-     */
     readonly logger: Logger;
-    /**
-     * Application options
-     */
     readonly options: ApplicationOptions;
-    /**
-     * Whether the app is running
-     */
+    /** Whether the app is running (server listening) */
     private _isRunning;
+    /** Whether the app has been booted (extensions set up, config frozen) */
+    private _isReady;
+    /** Whether ready() mounted the app-owned router (so close() can undo it) */
+    private _routerMounted;
+    /** In-flight boot promise — memoized so concurrent ready() calls share one boot (H-1) */
+    private _readyPromise;
+    /** In-flight shutdown promise — memoized so concurrent close() calls share one (H-3) */
+    private _closePromise;
+    /** The app-owned router (optional). Route methods delegate to it. */
+    readonly router?: Router;
+    /** The app-owned DI container (optional). Exposed to extensions and registrars. */
+    readonly container?: Container;
     constructor(options?: ApplicationOptions);
-    /**
-     * Check if running in production
-     */
+    /** Check if running in production */
     get isProduction(): boolean;
-    /**
-     * Check if app is running
-     */
+    /** Check if app is running */
     get isRunning(): boolean;
     /**
-     * Get middleware count
+     * Whether a graceful shutdown is currently in progress — `true` from the
+     * moment {@link close} begins tearing down until it completes (F-12:
+     * shutdown observability, RFC-022). A readiness check or operator tooling
+     * can read this to reflect an in-progress drain.
      */
+    get isDraining(): boolean;
+    /** Check if app has been booted via ready() */
+    get isReady(): boolean;
+    /** Get middleware count */
     get middlewareCount(): number;
+    /** Get registered extension count */
+    get extensionCount(): number;
     /**
-     * Throws if the app is already running.
-     * Prevents configuration mutations after start().
+     * Throws if the app configuration is frozen (after ready() or start()).
+     * Prevents unsafe mutations once the app has booted or is serving traffic.
      */
-    private assertNotRunning;
+    private assertConfigurable;
     /**
      * Register middleware function(s)
      *
-     * @param middleware - Middleware function or array of middleware
+     * @param middleware - Middleware function(s)
      * @returns this for chaining
-     *
-     * @example
-     * ```typescript
-     * // Single middleware
-     * app.use(async (ctx) => {
-     *   console.log(ctx.method, ctx.path);
-     *   await ctx.next();
-     * });
-     *
-     * // Multiple middleware
-     * app.use(cors(), helmet(), json());
-     * ```
      */
     use(...middleware: Middleware[]): this;
     /**
-     * Mount a router at a path prefix
-     *
-     * This is the Hono-style API for mounting routers directly on the app.
-     * The router's routes will only match requests that start with the given prefix.
+     * Mount a router at a path prefix.
      *
-     * @param path - Path prefix for the router (e.g., '/api/users')
+     * @param path - Path prefix (e.g. '/api/users')
      * @param router - Router instance to mount
      * @returns this for chaining
-     *
-     * @example
-     * ```typescript
-     * // Create modular routers
-     * const users = createRouter();
-     * users.get('/', listUsers);
-     * users.get('/:id', getUser);
-     * users.post('/', createUser);
-     *
-     * const posts = createRouter();
-     * posts.get('/', listPosts);
-     * posts.get('/:id', getPost);
-     *
-     * // Mount directly on app - clean like Hono!
-     * const app = createApp();
-     * app.route('/api/users', users);
-     * app.route('/api/posts', posts);
-     *
-     * listen(app, 3000);
-     * ```
      */
     route(path: string, router: Routable): this;
+    private requireRouter;
+    /** Register a GET route on the app-owned router. */
+    get(path: string, ...entries: RouteEntry[]): this;
+    /** Register a POST route on the app-owned router. */
+    post(path: string, ...entries: RouteEntry[]): this;
+    /** Register a PUT route on the app-owned router. */
+    put(path: string, ...entries: RouteEntry[]): this;
+    /** Register a PATCH route on the app-owned router. */
+    patch(path: string, ...entries: RouteEntry[]): this;
+    /** Register a DELETE route on the app-owned router. */
+    delete(path: string, ...entries: RouteEntry[]): this;
+    /** Register a HEAD route on the app-owned router. */
+    head(path: string, ...entries: RouteEntry[]): this;
     /**
-     * Set the application error handler.
+     * Register a route for all HTTP methods on the app-owned router.
      *
-     * Replaces any previously set handler. Only one error handler is active
-     * at a time. For additive error handling, compose logic within a single
-     * handler or use the `errorHandler()` middleware from `@nextrush/errors`.
-     *
-     * @param handler - Error handler function
-     * @returns this for chaining
-     *
-     * @example
-     * ```typescript
-     * app.setErrorHandler((error, ctx) => {
-     *   console.error('Request failed:', error);
-     *
-     *   if (error instanceof ValidationError) {
-     *     ctx.status = 400;
-     *     ctx.json({ error: error.message, details: error.details });
-     *     return;
-     *   }
-     *
-     *   ctx.status = 500;
-     *   ctx.json({ error: 'Internal Server Error' });
-     * });
-     * ```
+     * @remarks
+     * There is intentionally no `app.options()` verb method — it would collide
+     * with the `app.options` configuration property. Register OPTIONS routes via
+     * `app.all()`, the router directly, or let CORS middleware handle preflight.
      */
-    setErrorHandler(handler: ErrorHandler): this;
+    all(path: string, ...entries: RouteEntry[]): this;
     /**
-     * Set custom error handler.
+     * Set the application error handler. Replaces any previously set handler.
      *
      * @param handler - Error handler function
      * @returns this for chaining
-     *
-     * @deprecated Use `setErrorHandler()` instead — `onError()` implies
-     * event subscription (additive), but this is a setter (replaces).
      */
-    onError(handler: ErrorHandler): this;
+    setErrorHandler(handler: ErrorHandler): this;
     /**
-     * Install a plugin.
-     *
-     * Handles both sync and async `install()` methods automatically.
-     * Returns `this` for sync plugins and `Promise<this>` for async ones.
+     * Register an extension. Queues it — `setup()` runs later, at `ready()`,
+     * in registration order. Synchronous and chainable.
      *
-     * @param plugin - Plugin to install
-     * @returns this (sync) or Promise<this> (async)
+     * @param extension - Extension to register. If it declares a decorated
+     * shape via `Extension<TDecorated>`, the return type carries that shape —
+     * `app.extend(events<MyEvents>()).events` is statically known, no
+     * `declare module` augmentation required.
+     * @returns this, intersected with the extension's declared decorated shape
      *
      * @example
      * ```typescript
-     * // Sync plugin
-     * app.plugin(loggerPlugin({ level: 'info' }));
-     *
-     * // Async plugin — just await it
-     * await app.plugin(databasePlugin({ uri: '...' }));
+     * const extended = app.extend(events<MyEvents>());
+     * await app.ready(); // adapters call this automatically — runs setup()/decorate()
+     * extended.events.emit('user:created', { id: '1' }); // available only AFTER ready()
      * ```
      */
-    plugin(plugin: Plugin): this | Promise<this>;
+    extend<TDecorated = Record<string, never>>(extension: Extension<TDecorated>): this & TDecorated;
     /**
-     * Install a plugin asynchronously.
-     *
-     * @param plugin - Plugin to install
-     * @returns Promise that resolves when plugin is installed
+     * Boot the application: run every registered extension's `setup()` once, in
+     * registration order, awaiting async setups. Idempotent — safe to call twice.
+     * Adapters call this automatically before `start()`.
      *
-     * @deprecated Use `plugin()` instead — it handles both sync and async
-     * plugins automatically.
+     * After `ready()` resolves, the configuration is frozen (`use`/`route`/`extend`
+     * throw).
      *
-     * @example
-     * ```typescript
-     * await app.plugin(new DatabasePlugin({ connectionString: '...' }));
-     * ```
+     * @returns this
+     * @throws if an extension declares a `needs` dependency not yet registered
      */
-    pluginAsync(plugin: Plugin): Promise<this>;
+    ready(): Promise<this>;
     /**
-     * Get an installed plugin by name
-     *
-     * @param name - Plugin name
-     * @returns Plugin instance or undefined
+     * Run the boot sequence once (extension setup + router mount). Guarded and
+     * memoized by {@link ready}.
      */
-    getPlugin<T extends Plugin>(name: string): T | undefined;
+    private _boot;
     /**
-     * Check if a plugin is installed
+     * Run every registered middleware's boot-time security audit check
+     * (`security-boundaries` capability, task 8.1/8.2). `throw`-level verdicts
+     * fail boot immediately; `warn`-level verdicts log once each via the app
+     * logger and never block boot. Production-only — `_boot()` calls this
+     * conditionally so a dev/test app never pays the cost or sees the noise.
      */
-    hasPlugin(name: string): boolean;
+    private _runSecurityAudits;
     /**
-     * Create the request handler callback
+     * Attach a value to the app under `name`. Extension-author primitive, invoked
+     * through {@link ExtensionContext.decorate} — there is intentionally no public
+     * `app.decorate()` (RFC §6.1). Throws on collision.
      *
-     * This is the function that adapters call to handle each request.
-     * It composes all middleware and returns a function that processes context.
+     * @internal
+     */
+    private decorate;
+    /**
+     * Whether a decoration already occupies `name`.
+     */
+    hasDecorator(name: string): boolean;
+    /**
+     * Create the request handler callback.
      *
-     * **Important:** The middleware stack is snapshot at call time.
-     * Middleware or plugins added after `callback()` will NOT take effect
-     * on the returned handler. Call `callback()` again to get a
-     * handler that includes subsequent registrations.
+     * The middleware stack is snapshot at call time — call `ready()` before
+     * `callback()` so extension-registered middleware is included. Adapters do
+     * this automatically.
      *
      * @returns Request handler function
      */
@@ -275,46 +301,58 @@ declare class Application {
      */
     private handleError;
     /**
-     * Default error handler
-     *
-     * Uses the `expose` flag on errors (set by HttpError/NextRushError)
-     * to decide whether to include the error message in the response.
-     * 4xx errors expose messages by default; 5xx errors never do.
-     * This prevents leaking internal details (paths, SQL, stack info)
-     * regardless of environment.
+     * Default error handler — delegates to the shared error serializer so the
+     * default response matches `@nextrush/errors`' `errorHandler()` (audit C-1).
      */
     private defaultErrorHandler;
     /**
      * Mark app as running and freeze configuration.
      *
-     * Called by adapters when the server starts listening. After this call,
-     * `use()`, `route()`, `plugin()`, and `pluginAsync()` will throw.
-     * This prevents unsafe middleware mutations while requests are in flight.
-     *
-     * To re-enable registration (e.g. for testing), call `close()` first.
+     * Called by adapters when the server starts listening (after `ready()`).
      */
     start(): void;
     /**
-     * Graceful shutdown
-     * Destroys all plugins that have a destroy method.
-     * Uses Promise.allSettled to ensure all plugins are destroyed
-     * even if some throw errors.
+     * Register a teardown hook for a resource outside the extension system
+     * (stateful middleware, a manually-attached service, …). Run during
+     * {@link close} under the SAME bounded/isolated guarantee as extension
+     * `destroy()` — one throwing/hanging hook never strands the others — in one
+     * combined reverse-of-registration order together with every `extend()`ed
+     * extension's `destroy()` (RFC-022 §8.1/§8.2).
+     *
+     * @param hook - Teardown callback. May be sync or async; a thrown/rejected
+     * hook is isolated and its error collected in {@link close}'s returned array.
      *
-     * @returns Array of errors from plugins that failed to destroy (empty on success)
+     * @remarks Registration is pre-shutdown only: a hook registered after
+     * `close()` has already started is not run in that shutdown (RFC-022 §8.6).
+     *
+     * @example
+     * ```typescript
+     * const store = new MemoryStore(options);
+     * app.onClose(() => store.shutdown());
+     * ```
      */
-    close(): Promise<Error[]>;
+    onClose(hook: () => void | Promise<void>): void;
+    /**
+     * Graceful shutdown. Destroys extensions in reverse registration order,
+     * each isolated from the others' failures — one failing/hanging `destroy()`
+     * never strands the rest (RFC-022 / ADR-0012).
+     *
+     * @param options - Optional teardown budget. Omitted = unbounded, byte-identical
+     * to today's behavior (`Promise.allSettled`, no timeout). When `timeout` is
+     * given, every teardown unit races against it independently; a unit that
+     * does not finish in time is reported as a {@link TeardownTimeoutError} in
+     * the returned array instead of blocking `close()` past the budget.
+     * @returns Array of errors from units that failed or timed out (empty on success)
+     */
+    close(options?: CloseOptions): Promise<Error[]>;
+    /** Run the shutdown sequence once. Guarded and memoized by {@link close}. */
+    private _shutdown;
 }
 /**
  * Create a new Application instance
  *
  * @param options - Application options
  * @returns New Application instance
- *
- * @example
- * ```typescript
- * const app = createApp();
- * const app = createApp({ env: 'production' });
- * ```
  */
 declare function createApp(options?: ApplicationOptions): Application;
 
@@ -337,8 +375,14 @@ type ComposedMiddleware = (ctx: Context, next?: Next) => Promise<void>;
 interface ComposeOptions {
     /**
      * Warn when a middleware sends a response AND calls next().
-     * Enabled by default in non-production environments.
-     * @default process.env.NODE_ENV !== 'production'
+     *
+     * @remarks
+     * Opt-in and defaults to `false` — `@nextrush/core` is a runtime-agnostic
+     * package and must not read `process.env` (global-rules §2, audit C-4). The
+     * `Application` enables this in non-production by passing the flag from its
+     * own `env` option.
+     *
+     * @default false
      */
     warnDoubleResponse?: boolean;
 }
@@ -385,4 +429,4 @@ declare function isMiddleware(fn: unknown): fn is Middleware;
  */
 declare function flattenMiddleware(arr: (Middleware | Middleware[])[]): Middleware[];
 
-export { Application, type ApplicationOptions, type ComposeOptions, type ComposedMiddleware, type ErrorHandler, type ListenCallback, type Logger, type Routable, compose, createApp, flattenMiddleware, isMiddleware };
+export { Application, type ApplicationOptions, type ComposeOptions, type ComposedMiddleware, type ErrorHandler, type ListenCallback, type Routable, compose, createApp, flattenMiddleware, isMiddleware };