@dunx/http 3.8.2 → 3.9.0

package/README.md

@@ -95,6 +95,10 @@ from, and it may change in any release.
   otherwise silently keep one.
 - Handlers may return a `Response`, any JSON-serialisable value, or `undefined`
   for a 204.
+- `Authorize` and `gate()` are the contract an ops surface gates itself with:
+  raw request in, 404 on refusal, and a returned `Response` sent as written for a
+  browser that needs a sign-in page. `@dunx/dashboard` and `@dunx/openapi` both
+  take one, so an app writes the policy once and hands it to both.
 - Schemas, parsers and the status resolve at boot into the same closure the
   middleware chain folds into. A request reads no metadata and does no lookup.
 - Every request adopts W3C Trace Context, so `traceId`, `spanId`, `parentSpanId`

package/dist/client.js

@@ -41,7 +41,7 @@ class FetchTransportError extends AppError {
     this.aborted = aborted;
   }
 }
-Object.defineProperty(FetchTransportError, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "readonly response: { readonly method: string; readonly url: string }" }, { unresolved: "readonly aborted: boolean" }, ErrorOptions] });
+Object.defineProperty(FetchTransportError, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "readonly response: { readonly method: string; readonly url: string }" }, { unresolved: "readonly aborted: boolean" }, typeof ErrorOptions === "undefined" ? { unresolved: "options?: ErrorOptions" } : ErrorOptions] });
 // src/client/options.ts
 class HttpClientOptions {
   baseUrl;

package/dist/health/contracts.d.ts

@@ -54,3 +54,9 @@ export declare abstract class PingProbe {
 export declare abstract class QueryProbe {
     abstract ping(): Promise<void>;
 }
+/** Enough of an object store to answer "can I reach it", which `Storage` from
+ * `@dunx/infra/files` is on either backend. `exists` and not a read or a write:
+ * one `HEAD` against S3, one `stat` locally, and nothing left behind. */
+export declare abstract class StorageProbe {
+    abstract exists(key: string): Promise<boolean>;
+}

package/dist/health/indicators.d.ts

@@ -1,16 +1,47 @@
-import { HealthIndicator, type PingProbe, type ProbeResult, type QueryProbe } from './contracts.js';
+import { HealthIndicator, type PingProbe, type ProbeResult, type QueryProbe, type StorageProbe } from './contracts.js';
+/** Up on a completed round trip, down with the thrown message, detail the
+ * latency. Subclass it with a `name` for anything else answering a `ping()`. */
+export declare abstract class RoundTripIndicator extends HealthIndicator {
+    private readonly probe;
+    constructor(probe: QueryProbe);
+    check(): Promise<ProbeResult>;
+}
 /** Redis is up if it answers `PING`. */
-export declare class RedisIndicator extends HealthIndicator {
-    private readonly redis;
+export declare class RedisIndicator extends RoundTripIndicator {
     readonly name = "redis";
     constructor(redis: PingProbe);
-    check(): Promise<ProbeResult>;
 }
 /** The database is up if a round trip completes. */
-export declare class DatabaseIndicator extends HealthIndicator {
-    private readonly db;
+export declare class DatabaseIndicator extends RoundTripIndicator {
     readonly name = "database";
-    constructor(db: QueryProbe);
+}
+/**
+ * The AMQP broker, up while the connection is established and unblocked, and
+ * satisfied by `AmqpConnection` from `@dunx/infra/amqp`. The first probe on an
+ * unopened connection waits `readyTimeoutMs`, whose 5 s default outruns
+ * `timeoutMs` at 2 s and so reports `unknown`; the rest never wait.
+ */
+export declare class AmqpIndicator extends RoundTripIndicator {
+    readonly name = "amqp";
+}
+export interface StorageProbeOptionsInit {
+    readonly key?: string;
+}
+export declare class StorageProbeOptions {
+    readonly key: string;
+    constructor(init?: StorageProbeOptionsInit);
+}
+/**
+ * The configured object store, which is what `DiskIndicator` stops measuring the
+ * moment an app moves to `S3Storage`. Whether the key exists is no part of the
+ * signal and the answer is discarded: a store that replies is up, one that throws
+ * is down with the message expired credentials and a missing bucket arrive as.
+ */
+export declare class StorageIndicator extends HealthIndicator {
+    private readonly storage;
+    private readonly options;
+    readonly name = "storage";
+    constructor(storage: StorageProbe, options?: StorageProbeOptions);
     check(): Promise<ProbeResult>;
 }
 export interface MemoryOptionsInit {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { Controller, Delete, Get, Patch, Post, Put, } from './route/decorators.j
 export type { HttpMethod, RoutePath } from './route/marker.js';
 export { ApiHidden, HIDDEN, meta, metaKey, metaOf, mergeMeta, Public, PUBLIC, Roles, ROLES, STREAMS, UNMATCHED, UseGuards, type MetaKey, type MetaRecord, } from './route/metadata.js';
 export type { InferOutput, Input, JsonSchema, ResponseMap, Returns, RouteInput, RouteSchemas, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, } from './route/schema.js';
+export { gate, type Authorize, type AuthorizeDecision, } from './server/authorize.js';
 export { ClientAddress } from './server/client-address.js';
 export type { RouteContext } from './server/context.js';
 export type { CorsOptions, CorsOrigin } from './server/cors.js';
@@ -40,9 +41,9 @@ export { PostgresRelayConnectionOptions, RelayConnectionOptions, WsRelayModule,
 export { RelayPublisher, type RelayPublisherInit, } from './ws/relay-publisher.js';
 export { DEFAULT_RELAY_CHANNEL, WsRelay, type PubSubRelay, type RelayOptions, } from './ws/relay.js';
 export type { Socket, SocketData, SocketErrorHandler, SocketOptions, } from './ws/socket.js';
-export { HealthIndicator, PingProbe, QueryProbe, type ProbeResult, type ProbeState, } from './health/contracts.js';
+export { HealthIndicator, PingProbe, QueryProbe, StorageProbe, type ProbeResult, type ProbeState, } from './health/contracts.js';
 export { HealthController } from './health/controller.js';
-export { DatabaseIndicator, DiskIndicator, DiskOptions, MemoryIndicator, MemoryOptions, RedisIndicator, type DiskOptionsInit, type MemoryOptionsInit, } from './health/indicators.js';
+export { AmqpIndicator, DatabaseIndicator, DiskIndicator, DiskOptions, MemoryIndicator, MemoryOptions, RedisIndicator, RoundTripIndicator, StorageIndicator, StorageProbeOptions, type DiskOptionsInit, type MemoryOptionsInit, type StorageProbeOptionsInit, } from './health/indicators.js';
 export { HealthModule } from './health/module.js';
 export { HEALTH_REPORT_SCHEMA } from './health/report-schema.js';
 export { Readiness, ReadinessOptions } from './health/readiness.js';

package/dist/index.js

@@ -62,6 +62,17 @@ var Post = verb("POST");
 var Put = verb("PUT");
 var Patch = verb("PATCH");
 var Delete = verb("DELETE");
+// src/server/authorize.ts
+var gate = async (authorize, req) => {
+  if (authorize === undefined)
+    return;
+  const decision = await authorize(req);
+  if (decision === true)
+    return;
+  if (decision instanceof Response)
+    return decision;
+  return Response.json({ error: "NOT_FOUND", status: 404 }, { status: 404 });
+};
 // src/server/client-address.ts
 import { AppError } from "@dunx/core";
 var trustedHops = (setting) => {
@@ -3010,6 +3021,9 @@ class PingProbe {
 
 class QueryProbe {
 }
+
+class StorageProbe {
+}
 // src/health/controller.ts
 import { inject } from "@dunx/core";
 
@@ -3211,35 +3225,64 @@ let _HiddenHealthController = HiddenHealthController;
 import { statfs } from "fs/promises";
 var ms = (started) => Math.round(performance.now() - started);
 
-class RedisIndicator extends HealthIndicator {
-  redis;
-  name = "redis";
-  constructor(redis) {
+class RoundTripIndicator extends HealthIndicator {
+  probe;
+  constructor(probe) {
     super();
-    this.redis = redis;
+    this.probe = probe;
   }
   async check() {
     const started = performance.now();
-    await this.redis.ping();
+    await this.probe.ping();
     return { state: "up", detail: `${ms(started)} ms` };
   }
 }
-Object.defineProperty(RedisIndicator, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "private readonly redis: PingProbe", typeOnly: "PingProbe" }] });
+Object.defineProperty(RoundTripIndicator, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "private readonly probe: QueryProbe", typeOnly: "QueryProbe" }] });
+
+class RedisIndicator extends RoundTripIndicator {
+  name = "redis";
+  constructor(redis) {
+    super({
+      ping: async () => {
+        await redis.ping();
+      }
+    });
+  }
+}
+Object.defineProperty(RedisIndicator, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "redis: PingProbe", typeOnly: "PingProbe" }] });
 
-class DatabaseIndicator extends HealthIndicator {
-  db;
+class DatabaseIndicator extends RoundTripIndicator {
   name = "database";
-  constructor(db) {
+}
+
+class AmqpIndicator extends RoundTripIndicator {
+  name = "amqp";
+}
+
+class StorageProbeOptions {
+  key;
+  constructor(init = {}) {
+    this.key = init.key ?? ".dunx-health";
+  }
+}
+Object.defineProperty(StorageProbeOptions, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "init: StorageProbeOptionsInit = {}", optional: true }] });
+
+class StorageIndicator extends HealthIndicator {
+  storage;
+  options;
+  name = "storage";
+  constructor(storage, options = new StorageProbeOptions) {
     super();
-    this.db = db;
+    this.storage = storage;
+    this.options = options;
   }
   async check() {
     const started = performance.now();
-    await this.db.ping();
+    await this.storage.exists(this.options.key);
     return { state: "up", detail: `${ms(started)} ms` };
   }
 }
-Object.defineProperty(DatabaseIndicator, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "private readonly db: QueryProbe", typeOnly: "QueryProbe" }] });
+Object.defineProperty(StorageIndicator, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "private readonly storage: StorageProbe", typeOnly: "StorageProbe" }, StorageProbeOptions] });
 
 class MemoryOptions {
   maxRssBytes;
@@ -3393,6 +3436,7 @@ __runInitializers(_init, 1, HealthModule);
 __decoratorMetadata(_init, HealthModule);
 let _HealthModule = HealthModule;
 export {
+  AmqpIndicator,
   ApiHidden2 as ApiHidden,
   ClientAddress,
   Compression,
@@ -3452,6 +3496,7 @@ export {
   RequestLoggingMiddleware,
   RequestMetrics,
   Roles2 as Roles,
+  RoundTripIndicator,
   SKIP_THROTTLE,
   STREAMS2 as STREAMS,
   SkipThrottle,
@@ -3462,6 +3507,9 @@ export {
   StaticFiles2 as StaticFiles,
   StaticModule,
   StaticOptions2 as StaticOptions,
+  StorageIndicator,
+  StorageProbe,
+  StorageProbeOptions,
   THROTTLE,
   TRACEPARENT_HEADER2 as TRACEPARENT_HEADER,
   TRACERESPONSE_HEADER2 as TRACERESPONSE_HEADER,
@@ -3480,6 +3528,7 @@ export {
   WsRelayModule,
   defaultErrorMapper,
   errorMapper,
+  gate,
   mergeMeta2 as mergeMeta,
   meta2 as meta,
   metaKey2 as metaKey,

package/dist/server/authorize.d.ts

@@ -0,0 +1,18 @@
+import type { BunRequest } from 'bun';
+/**
+ * What an {@link Authorize} answers. `true` passes and `false` refuses with a
+ * 404; a `Response` refuses with itself, which is what a browser needs.
+ */
+export type AuthorizeDecision = boolean | Response;
+/**
+ * Decides whether a request may see an ops surface at all - the dashboard page,
+ * the OpenAPI explorer. Both sit outside the app's session guard, so this gets
+ * the raw `BunRequest` and asks the auth library. Refusal is 404, not 403.
+ */
+export type Authorize = (req: BunRequest) => AuthorizeDecision | Promise<AuthorizeDecision>;
+/**
+ * Runs the gate: `undefined` to carry on, or the response to answer with. Only
+ * `true` admits and only a `Response` replaces the refusal, so an `authorize`
+ * that falls off the end of a branch closes rather than opens.
+ */
+export declare const gate: (authorize: Authorize | undefined, req: BunRequest) => Promise<Response | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/http",
-  "version": "3.8.2",
+  "version": "3.9.0",
   "description": "Bun.serve adapter for the dunx framework: controllers, middleware and WebSocket gateways",
   "keywords": [
     "bun",
@@ -76,7 +76,7 @@
   "peerDependencies": {
     "@bufbuild/protobuf": "^2.15.0",
     "@connectrpc/connect": "^2.2.0",
-    "@dunx/core": "^3.8.2",
+    "@dunx/core": "^3.9.0",
     "@types/bun": ">=1.4.1"
   },
   "peerDependenciesMeta": {