@dunx/http 1.2.0 → 1.3.0

package/dist/inspect.d.ts

@@ -0,0 +1,58 @@
+import { type Dependency, type ModuleRef } from '@dunx/core';
+export interface RouteInputs {
+    readonly body?: string;
+    readonly query?: string;
+    readonly params?: string;
+}
+export interface RouteNode {
+    readonly method: string;
+    readonly path: string;
+    readonly controller: string;
+    readonly handler: string;
+    readonly module: string;
+    readonly public: boolean;
+    readonly roles: readonly string[] | null;
+    /** Class-level `@UseGuards` first, then method-level, which is resolution order. */
+    readonly guards: readonly string[];
+    /** `@ApiHidden()`, so a caller can tell "not documented" from "not there". */
+    readonly hidden: boolean;
+    /**
+     * Which inputs the route validates, and by which Standard Schema vendor. The
+     * schemas themselves are not here: turning one into JSON Schema is zod-specific
+     * work that `@dunx/openapi` already does, and `dunx_openapi` is where it lives.
+     * What this answers is "does this route parse a body at all", which is the
+     * question that does not need a schema compiler.
+     */
+    readonly validates: RouteInputs;
+    /** The success status the decorator declared, or null for the default. */
+    readonly status: number | null;
+    /** Status codes the route documents a response schema for. */
+    readonly responses: readonly number[];
+}
+export declare const routesOf: (root: ModuleRef) => readonly RouteNode[];
+/**
+ * Gateways are declared in `@Module({ providers })` like any other injectable and
+ * found by their marker, so they are read the same way routes are: the class's
+ * prototype, never an instance.
+ *
+ * `discoverGateway` does all of it - the path, the marked methods, the event each
+ * message handler claims - and `Object.create(Gateway.prototype)` satisfies its
+ * one argument, exactly as it satisfies `discoverRoutes`. Its sibling
+ * `discoverGateways` is the one that is unusable here: it takes a `resolve`
+ * callback and constructs every gateway, which is the boot this package exists to
+ * avoid. Only the bound `invoke` is dropped, being a function.
+ */
+export interface GatewayHandler {
+    readonly kind: string;
+    /** The envelope event a message handler claims; null is the raw catch-all. */
+    readonly event: string | null;
+    readonly method: string;
+}
+export interface GatewayNode {
+    readonly name: string;
+    readonly path: string;
+    readonly module: string;
+    readonly dependencies: readonly Dependency[];
+    readonly handlers: readonly GatewayHandler[];
+}
+export declare const gatewaysOf: (root: ModuleRef) => readonly GatewayNode[];

package/dist/server/request-logging.d.ts

@@ -27,6 +27,23 @@ export interface RequestLoggingOptions {
      * is what makes it free. `correlateIgnored` buys the correlation back.
      */
     readonly ignore?: readonly string[];
+    /**
+     * Path **prefixes** to skip, for a whole mount rather than one path.
+     *
+     * `ignore` is an exact-match `Set` because that is one lookup on the hot path
+     * and a health check is one path. A mount is not: `@dunx/dashboard` at
+     * `/_dunx` polls four endpoints every five seconds and bull-board pulls a
+     * dozen assets, and listing them is both tedious and wrong the moment either
+     * grows an endpoint.
+     *
+     * Scanned only when non-empty, so an app that sets none pays nothing - the
+     * same guard `ignore` has. Keep the list short; it is a loop.
+     *
+     * ```ts
+     * requestLogging: { ignorePrefix: ['/_dunx'] }
+     * ```
+     */
+    readonly ignorePrefix?: readonly string[];
     /**
      * Keep the request id and the async scope on an `ignore`d path. Default
      * **`false`**.

package/dist/static/files.d.ts

@@ -0,0 +1,35 @@
+import type { BunRequest } from 'bun';
+import type { Middleware, Next } from '../server/middleware.js';
+import type { RouteContext } from '../server/context.js';
+import { StaticOptions } from './options.js';
+/**
+ * Static files, on `Bun.file`.
+ *
+ * Nest has `ServeStaticModule` over `serve-static`, which is Express middleware
+ * doing its own `stat`, its own range parsing, its own ETag and its own MIME table.
+ * None of that is needed here: `Bun.file(path)` handed to a `Response` already
+ * streams, already sets `content-type` from the extension, already answers a
+ * `Range` request, and does the whole thing with `sendfile(2)` rather than reading
+ * into JavaScript. So this file is a **path check and a cache policy**, and that is
+ * the entire justification for it existing.
+ *
+ * A middleware rather than routes, for the same reason the dashboard is one: the
+ * file set is whatever is on disk at request time, and turning it into a
+ * `Bun.serve` route table would mean walking a directory at boot and being wrong
+ * the moment anything changed.
+ */
+export declare class StaticFiles implements Middleware {
+    #private;
+    constructor(options: StaticOptions);
+    /**
+     * The file for a request path, or `undefined` if it escapes the root.
+     *
+     * **The traversal check is the point of this method.** `..` segments are removed
+     * by `normalize`, but that alone is not enough: a root of `/srv/app` and a
+     * request for `/srv/app-secrets` both start with the same string, so the guard
+     * has to compare against the root **with a separator**. Both halves have to hold
+     * or a caller reads the filesystem.
+     */
+    resolvePath(pathname: string): string | undefined;
+    handle(req: BunRequest, _ctx: RouteContext, next: Next): Promise<Response>;
+}

package/dist/static/module.d.ts

@@ -0,0 +1,27 @@
+import { type Deps, type DynamicModule, type FactoryProvider } from '@dunx/core';
+import { type StaticOptionsInit } from './options.js';
+/**
+ * Serves a directory, the way Nest's `ServeStaticModule` does - and like the
+ * dashboard, **it does not register itself**. The app does:
+ *
+ * ```ts
+ * const app = await HttpFactory.create(AppModule);
+ * app.use(StaticFiles);
+ * ```
+ *
+ * Position in the chain is the decision being left to the app. Static assets
+ * usually want to be *outside* an auth guard and *inside* request logging, and no
+ * default can know which. Anything outside the mount falls through untouched, so
+ * the app's own routes and its 404 behave exactly as before.
+ *
+ * There is no `index.html` fallback and no SPA rewrite. Both are one route in the
+ * app - `@Get('/*')` returning `Bun.file(...)` - and building them in would mean
+ * this middleware deciding what a 404 means for paths it does not own.
+ */
+export declare class StaticModule {
+    static forRoot(init: StaticOptionsInit): DynamicModule;
+    /** `forRoot` with the root read off the container - a config value, usually. */
+    static forRootAsync<const D extends Deps>(config: FactoryProvider<StaticOptionsInit, D> & {
+        readonly imports?: DynamicModule['imports'];
+    }): DynamicModule;
+}

package/dist/static/options.d.ts

@@ -0,0 +1,46 @@
+export interface StaticOptionsInit {
+    /**
+     * The directory served. Resolved once, at construction, and every request is
+     * checked against it - see `StaticFiles.resolvePath`.
+     */
+    readonly root: string;
+    /**
+     * The URL prefix it is served under. `/` serves from the root of the app, which
+     * is the usual case for a `public/` directory.
+     *
+     * @default '/'
+     */
+    readonly path?: string;
+    /**
+     * `max-age` in seconds for anything `immutable` does not claim.
+     *
+     * Deliberately short. A long max-age on a name that can change is a promise the
+     * server cannot keep, and the fix - a content hash in the filename - is the
+     * thing `immutable` is for.
+     *
+     * @default 60
+     */
+    readonly maxAge?: number;
+    /**
+     * Which paths may be cached forever.
+     *
+     * Only honest for a **content-addressed** name, where a change produces a
+     * different URL: `(path) => /\.[0-9a-f]{8}\.(js|css)$/.test(path)`. The default
+     * claims nothing, because guessing wrong here is a stale asset nobody can flush.
+     */
+    readonly immutable?: (pathname: string) => boolean;
+}
+/**
+ * A class, not an interface, so it is a runtime value and can therefore be a
+ * constructor parameter type that `@dunx/transform` records - the same reason
+ * `QueueOptions` and `RedisOptions` are classes.
+ */
+export declare class StaticOptions {
+    readonly root: string;
+    readonly path: string;
+    readonly maxAge: number;
+    readonly immutable: (pathname: string) => boolean;
+    constructor(init: StaticOptionsInit);
+}
+/** A leading slash and no trailing one, so `${path}/x` is never `//x`. */
+export declare const normalizePrefix: (path: string) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/http",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Bun.serve adapter for the dunx framework: controllers, middleware and WebSocket gateways",
   "keywords": [
     "bun",
@@ -58,7 +58,7 @@
     "@dunx/core": "workspace:*"
   },
   "peerDependencies": {
-    "@dunx/core": "^1.2.0",
+    "@dunx/core": "^1.3.0",
     "@types/bun": ">=1.3.0"
   },
   "peerDependenciesMeta": {

package/dist/chunk-x80f562w.js

@@ -1,40 +0,0 @@
-// @bun
-// src/server/status.ts
-var HttpStatusCode = Object.freeze({
-  OK: 200,
-  CREATED: 201,
-  ACCEPTED: 202,
-  NO_CONTENT: 204,
-  MOVED_PERMANENTLY: 301,
-  FOUND: 302,
-  NOT_MODIFIED: 304,
-  TEMPORARY_REDIRECT: 307,
-  PERMANENT_REDIRECT: 308,
-  BAD_REQUEST: 400,
-  UNAUTHORIZED: 401,
-  PAYMENT_REQUIRED: 402,
-  FORBIDDEN: 403,
-  NOT_FOUND: 404,
-  METHOD_NOT_ALLOWED: 405,
-  NOT_ACCEPTABLE: 406,
-  REQUEST_TIMEOUT: 408,
-  CONFLICT: 409,
-  GONE: 410,
-  PRECONDITION_FAILED: 412,
-  PAYLOAD_TOO_LARGE: 413,
-  URI_TOO_LONG: 414,
-  UNSUPPORTED_MEDIA_TYPE: 415,
-  IM_A_TEAPOT: 418,
-  UNPROCESSABLE_ENTITY: 422,
-  TOO_MANY_REQUESTS: 429,
-  INTERNAL_SERVER_ERROR: 500,
-  NOT_IMPLEMENTED: 501,
-  BAD_GATEWAY: 502,
-  SERVICE_UNAVAILABLE: 503,
-  GATEWAY_TIMEOUT: 504
-});
-
-export { HttpStatusCode };
-
-//# debugId=881F02139124CAE264756E2164756E21
-//# sourceMappingURL=chunk-x80f562w.js.map