bazis 0.98.31 → 0.98.33

package/core/background/BackgroundService.ts

@@ -1,4 +1,4 @@
-import type { HostedService, HostedServiceDiagnostics } from "../di";
+import type { HostedService, HostedServiceDiagnostics, HostedServiceHealth } from "../di";
 import { backgroundOptionsOf } from "./decorator";
 import { delay } from "./delay";
 import { redactSensitive } from "../../library/redaction";
@@ -56,6 +56,8 @@ export abstract class BackgroundService implements HostedService {
 
   /** The application logger, passed by the kernel; console until then. */
   private diagnostics?: HostedServiceDiagnostics;
+  /** Set when the service stopped for good after a crash: `/health` reports it. */
+  private terminated?: string;
 
   public constructor(options?: BackgroundServiceOptions) {
     // Explicit `super(...)` options win over `@Background({...})` metadata.
@@ -68,6 +70,15 @@ export abstract class BackgroundService implements HostedService {
   /** The background workload. Must observe `signal` for cooperative shutdown. */
   protected abstract execute(signal: AbortSignal): void | Promise<void>;
 
+  /**
+   * Unhealthy once the service stopped for good: it crashed without a restart
+   * policy, or used up its restarts. A pause before a restart, a tick failure
+   * of a periodic service and a normal end of `execute` stay healthy.
+   */
+  public checkHealth(): HostedServiceHealth {
+    return this.terminated === undefined ? { healthy: true } : { healthy: false, details: this.terminated };
+  }
+
   public useDiagnostics(diagnostics: HostedServiceDiagnostics): void {
     this.diagnostics = diagnostics;
   }
@@ -119,9 +130,11 @@ export abstract class BackgroundService implements HostedService {
         this.reportError(error, restarts);
         if (restarts >= maxRestarts) {
           // Without this line the service would just go quiet.
-          report(this.diagnostics, "error", this.constructor.name, maxRestarts === 0
+          const stopped = maxRestarts === 0
             ? "stopped after a crash and will not run again (no restart policy)"
-            : `stopped after ${maxRestarts} restart${maxRestarts === 1 ? "" : "s"} and will not run again`, { restarts });
+            : `stopped after ${maxRestarts} restart${maxRestarts === 1 ? "" : "s"} and will not run again`;
+          report(this.diagnostics, "error", this.constructor.name, stopped, { restarts });
+          this.terminated = `${stopped}: ${error instanceof Error ? error.message : String(error)}`;
           return;
         }
         restarts += 1;

package/core/background/decorator.ts

@@ -26,7 +26,8 @@ interface BackgroundMetadataCarrier {
  * ```
  *
  * Options passed explicitly to `super(...)` take precedence over the decorator.
- * Registration stays explicit — list the class in `backgroundModule({ services })`.
+ * Registration stays explicit — list the class in `background` of its module:
+ * `@Module({ background: [Heartbeat] })`.
  */
 export function Background(options: BackgroundDecoratorOptions = {}) {
   return (_value: abstract new (...args: never[]) => unknown, context: ClassDecoratorContext): void => {

package/core/background/index.ts

@@ -10,6 +10,5 @@ export {
   type BackgroundServiceOptions,
   type PeriodicBackgroundServiceOptions,
 } from "./BackgroundService";
-export { backgroundModule, type BackgroundModuleConfig } from "./backgroundModule";
 export { Background, backgroundOptionsOf, type BackgroundDecoratorOptions } from "./decorator";
 export { delay } from "./delay";

package/core/di/extensions/hosted-service.ts

@@ -22,7 +22,18 @@ export interface HostedServiceDiagnostics {
   warn(message: string, fields?: Readonly<Record<string, unknown>>): void;
 }
 
+/** What a hosted service reports to `/health`. */
+export interface HostedServiceHealth {
+  readonly healthy: boolean;
+  readonly details?: string;
+}
+
 export interface HostedService {
+  /**
+   * The service's own state for `/health`. A `background` service of a module
+   * is reported as `background:<Class>`; without this method it is healthy.
+   */
+  checkHealth?(): HostedServiceHealth;
   /** Shared validators see real service identities, including inside supervised wrappers. */
   readonly planValidator?: HostedServicePlanValidator;
   /** Receives the application logger before start, when one is registered. */
@@ -39,6 +50,15 @@ export interface HostedService {
 
 export const HOSTED_SERVICE = createToken<HostedService>("IHostedService");
 
+/** A health check contributed by a hosted service; the kernel reports it next to its own checks. */
+export interface HostedServiceHealthCheck {
+  readonly name: string;
+  check(): HostedServiceHealth;
+}
+
+/** Enumerable: one entry per `background` service of the module graph. */
+export const HOSTED_SERVICE_HEALTH = createToken<HostedServiceHealthCheck>("BazisHostedServiceHealth");
+
 interface HostedServiceResolver {
   resolveAll(token: typeof HOSTED_SERVICE): readonly HostedService[];
 }

package/core/di/extensions/index.ts

@@ -1,6 +1,6 @@
 export { createInstance, type ActivatorDependency } from "./activator";
 export { Application, runApplication, type RunApplicationOptions } from "./application";
-export { addHostedService, HOSTED_SERVICE, startHostedServices, stopHostedServices, type HostedService, type HostedServiceDiagnostics, type HostedServicePlanValidator } from "./hosted-service";
+export { addHostedService, HOSTED_SERVICE, HOSTED_SERVICE_HEALTH, startHostedServices, stopHostedServices, type HostedService, type HostedServiceDiagnostics, type HostedServiceHealth, type HostedServiceHealthCheck, type HostedServicePlanValidator } from "./hosted-service";
 export { SERVICE_PROVIDER } from "./service-provider-token";
 export {
   addOptions,

package/core/di/module/collectModuleControllers.ts

@@ -8,11 +8,7 @@ type ClassListKey = "controllers" | "gateways";
  * the module tree (the module itself plus `imports`, recursively). Duplicates by
  * class reference are dropped.
  */
-function collectModuleClasses(
-  roots: readonly BazisModuleRef[],
-  key: ClassListKey,
-  extra?: readonly Class<object>[],
-): Class<object>[] {
+function collectModuleClasses(roots: readonly BazisModuleRef[], key: ClassListKey): Class<object>[] {
   const seen = new Set<Class<object>>();
   const result: Class<object>[] = [];
   const add = (list: readonly Class<object>[] | undefined): void => {
@@ -44,16 +40,12 @@ function collectModuleClasses(
   for (let index = 0; index < roots.length; index += 1) {
     visit(roots[index] as BazisModuleRef, new Set());
   }
-  add(extra);
   return result;
 }
 
-/** Controller classes of the module tree; `extraControllers` are appended once. */
-export function collectModuleControllers(
-  roots: readonly BazisModuleRef[],
-  extraControllers?: readonly Class<object>[],
-): Class<object>[] {
-  return collectModuleClasses(roots, "controllers", extraControllers);
+/** Controller classes (`controllers` of `@Module`) of the module tree. */
+export function collectModuleControllers(roots: readonly BazisModuleRef[]): Class<object>[] {
+  return collectModuleClasses(roots, "controllers");
 }
 
 /** WebSocket gateway classes (`gateways` of `@Module`) of the module tree. */

package/core/di/module/createContainer.ts

@@ -1,6 +1,6 @@
 import { DiContainer } from "../container";
 import { ServiceCollection } from "../ServiceCollection";
-import { HOSTED_SERVICE, type HostedService } from "../extensions/hosted-service";
+import { HOSTED_SERVICE, HOSTED_SERVICE_HEALTH, type HostedService } from "../extensions/hosted-service";
 import { SERVICE_PROVIDER, SERVICE_PROVIDER_BY_TYPE } from "../extensions/service-provider-token";
 import { isClassProvider, ProviderDefinition, type Provider } from "../provider";
 import { getClassDeps } from "../internal/classDeps";
@@ -162,6 +162,13 @@ export function createContainer(rootModule: BazisModuleRef, options?: CreateCont
         collection.add(
           DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => resolver.resolve(ServiceClass))),
         );
+        // `/health` sees a service that stopped for good, not only the process.
+        collection.add(
+          DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE_HEALTH, [], (resolver) => {
+            const service = resolver.resolve(ServiceClass);
+            return { name: `background:${ServiceClass.name}`, check: () => service.checkHealth?.() ?? { healthy: true } };
+          })),
+        );
       }
     }
 

package/core/grpc/Grpc.module.ts

@@ -5,10 +5,9 @@ import { collectGrpcControllers, GRPC_CONTROLLERS } from "./moduleControllers";
 
 /** gRPC counterpart of httpModule: controllers belong to their feature modules. */
 export function grpcModule(options: GrpcModuleOptions = {}): BazisModule {
-  const selected = collectGrpcControllers(options.imports ?? [], options.controllers);
+  const selected = collectGrpcControllers(options.imports ?? []);
   @Module({
     imports: options.imports,
-    grpcControllers: options.controllers,
     providers: [DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => {
       const container = resolver.resolve(SERVICE_PROVIDER);
       if (!(container instanceof DiContainer)) throw new TypeError("gRPC requires a module DI container.");

package/core/grpc/GrpcCall.ts

@@ -1,5 +1,11 @@
 import type { ModuleOwnedProviderActivation, ServiceProvider } from "../di";
 import type { GrpcContext } from "./contracts";
+import { GrpcError } from "./GrpcError";
+import type { AuthorizeCheck } from "../http/Authorization/metadata";
+import { ForbiddenError, UnauthorizedError } from "../http/Errors/HttpError";
+import { JwtError } from "../../library/jwt/errors";
+import { redactSensitive } from "../../library/redaction";
+import type { Logger } from "../kernel/logging/Logger";
 import type { MethodDefinition } from "./serviceDefinition";
 import { GrpcTransport } from "./GrpcTransport";
 import { GrpcStatus } from "./GrpcStatus";
@@ -14,13 +20,25 @@ export class GrpcCall {
     private readonly activation: ModuleOwnedProviderActivation<object>,
     private readonly provider: ServiceProvider,
     private readonly binding?: GrpcRequestBinding,
+    /** `@Authorize` checks of the controller and the method, in order. */
+    private readonly checks: readonly AuthorizeCheck[] = [],
+    private readonly logger?: Logger,
   ) {}
 
   cancel(): void { this.transport.cancel(GrpcStatus.UNAVAILABLE, "Server stopped."); }
 
   async run(): Promise<void> {
     const scope = this.provider.createScope();
-    const context = this.transport.context;
+    const info = this.transport.context;
+    const context: GrpcContext = Object.freeze({
+      ...info,
+      services: scope,
+      state: new Map<string, unknown>(),
+      header: (name: string) => {
+        const value = info.metadata.get(name)[0];
+        return typeof value === "string" ? value : undefined;
+      },
+    });
     let result: unknown;
     let failure: unknown;
     let failed = false;
@@ -35,6 +53,9 @@ export class GrpcCall {
       for await (const value of requests) yield bind(value);
     }
     try {
+      context.signal.throwIfAborted();
+      // Like HTTP: access is decided before the request is read.
+      await authorize(this.checks, context);
       context.signal.throwIfAborted();
       const input = this.definition.requestStream
         ? (this.binding ? validatedRequests() : requests)
@@ -62,7 +83,14 @@ export class GrpcCall {
       // Do not dispose dependencies while non-cooperative handler code is running.
       try { await scope.dispose(); } catch (error) { failure = error; failed = true; }
     }
-    if (failed) this.transport.fail(failure);
+    if (failed) {
+      // An intentional GrpcError and a cancelled call are not server failures;
+      // anything else is a bug and belongs in the log, like an HTTP 500.
+      if (!(failure instanceof GrpcError) && !context.signal.aborted) {
+        this.logger?.error("gRPC handler failed", { path: this.definition.path, error: redactSensitive(failure) });
+      }
+      this.transport.fail(failure);
+    }
     else {
       try {
         if (!this.definition.responseStream) await this.transport.write(result);
@@ -71,3 +99,24 @@ export class GrpcCall {
     }
   }
 }
+
+/**
+ * Runs the `@Authorize` checks: `false` and `ForbiddenError` are
+ * PERMISSION_DENIED, `UnauthorizedError` and `JwtError` (missing, malformed,
+ * expired token) are UNAUTHENTICATED. Any other error propagates as a bug.
+ */
+async function authorize(checks: readonly AuthorizeCheck[], context: GrpcContext): Promise<void> {
+  for (const check of checks) {
+    let allowed: boolean;
+    try {
+      allowed = await check(context);
+    } catch (error) {
+      if (error instanceof UnauthorizedError || error instanceof JwtError) {
+        throw new GrpcError(GrpcStatus.UNAUTHENTICATED, "Unauthenticated.");
+      }
+      if (error instanceof ForbiddenError) throw new GrpcError(GrpcStatus.PERMISSION_DENIED, "Permission denied.");
+      throw error;
+    }
+    if (!allowed) throw new GrpcError(GrpcStatus.PERMISSION_DENIED, "Permission denied.");
+  }
+}

package/core/grpc/GrpcClient.ts

@@ -2,6 +2,7 @@ import { connect, type ClientHttp2Session, type SecureClientSessionOptions } fro
 import type { GrpcCallOptions, GrpcClientOptions, GrpcResponse, GrpcResponseStream } from "./clientContracts";
 import { GrpcClientCall } from "./GrpcClientCall";
 import { GrpcError } from "./GrpcError";
+import { markUpstreamFailure } from "../http/Errors/upstreamFailure";
 import { GrpcStatus } from "./GrpcStatus";
 import { Metadata } from "./Metadata";
 import type { MethodDefinition, ServiceDefinition } from "./serviceDefinition";
@@ -114,10 +115,10 @@ export class GrpcClient {
       deadline = Math.min(deadline, explicit);
     }
     if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) throw new TypeError("Invalid gRPC signal.");
-    if (options.signal?.aborted) throw new GrpcError(GrpcStatus.CANCELLED, "RPC cancelled.");
-    if (deadline <= Date.now()) throw new GrpcError(GrpcStatus.DEADLINE_EXCEEDED, "Deadline exceeded.");
-    if (this.closed) throw new GrpcError(GrpcStatus.CANCELLED, "gRPC client is closed.");
-    if (this.calls.size >= this.callLimit) throw new GrpcError(GrpcStatus.RESOURCE_EXHAUSTED, "Too many concurrent gRPC calls.");
+    if (options.signal?.aborted) throw upstream(new GrpcError(GrpcStatus.CANCELLED, "RPC cancelled."));
+    if (deadline <= Date.now()) throw upstream(new GrpcError(GrpcStatus.DEADLINE_EXCEEDED, "Deadline exceeded."));
+    if (this.closed) throw upstream(new GrpcError(GrpcStatus.CANCELLED, "gRPC client is closed."));
+    if (this.calls.size >= this.callLimit) throw upstream(new GrpcError(GrpcStatus.RESOURCE_EXHAUSTED, "Too many concurrent gRPC calls."));
     let session: ClientHttp2Session, stream: ReturnType<ClientHttp2Session["request"]>;
     try {
       session = this.session();
@@ -125,7 +126,7 @@ export class GrpcClient {
       const wireTimeout = remaining <= 99_999_999 ? `${remaining}m` : `${Math.ceil(remaining / 1000)}S`;
       stream = session.request({ ...metadata.toHttp2Headers(), ":method": "POST", ":path": method.path,
         "content-type": "application/grpc+proto", te: "trailers", "grpc-accept-encoding": "identity", "grpc-timeout": wireTimeout }, { endStream: false });
-    } catch { throw new GrpcError(GrpcStatus.UNAVAILABLE, "Unable to open gRPC connection."); }
+    } catch { throw upstream(new GrpcError(GrpcStatus.UNAVAILABLE, "Unable to open gRPC connection.")); }
     const call = new GrpcClientCall<T>(stream, method, { deadline, signal: options.signal, sendLimit: this.sendLimit, receiveLimit: this.receiveLimit }, () => {
       this.calls.delete(call);
       this.sessions.get(session)?.delete(call);
@@ -170,3 +171,8 @@ function metadataCopy(value: Metadata | undefined): Metadata {
   if (!(value instanceof Metadata)) throw new TypeError("Expected Bazis Metadata.");
   return value.clone();
 }
+
+/** A failed call of this client is a failure of another service for an HTTP request: 504 or 502. */
+function upstream(error: GrpcError): GrpcError {
+  return markUpstreamFailure(error, error.code === GrpcStatus.DEADLINE_EXCEEDED ? "timeout" : "failure");
+}

package/core/grpc/GrpcClientCall.ts

@@ -1,4 +1,5 @@
 import { constants, type Http2Session, type ClientHttp2Stream, type IncomingHttpHeaders } from "node:http2";
+import { markUpstreamFailure } from "../http/Errors/upstreamFailure";
 import type { GrpcResponseStream } from "./clientContracts";
 import { GrpcError } from "./GrpcError";
 import { GrpcStatus } from "./GrpcStatus";
@@ -83,6 +84,9 @@ export class GrpcClientCall<T> implements GrpcResponseStream<T> {
     if (!this.terminalHeaders) this.fail(new GrpcError(GrpcStatus.UNAVAILABLE, "gRPC connection closed before completion."));
   }
   fail(error: GrpcError): void {
+    // In an HTTP request this is a failure of another service: 504 or 502.
+    // Marked even after finish: the same error is rethrown to the caller.
+    markUpstreamFailure(error, error.code === GrpcStatus.DEADLINE_EXCEEDED ? "timeout" : "failure");
     if (this.finished) return;
     this.failure = error;
     this.abort.abort(error);

package/core/grpc/GrpcServer.ts

@@ -11,6 +11,8 @@ import type { MethodDefinition } from "./serviceDefinition";
 import { modelValidatorAdapter } from "../../library/validation";
 import { getGrpcRequestBinding } from "./GrpcBinding.contract";
 import { GrpcRequestBinding } from "./GrpcRequest.binding";
+import { resolveAuthorizeMeta, type AuthorizeCheck } from "../http/Authorization/metadata";
+import { LOGGER, type Logger } from "../kernel/logging/Logger";
 
 type Contribution = ModuleOwnedProviderContribution<GrpcControllerDefinition, object>;
 
@@ -24,7 +26,8 @@ export class GrpcServer implements HostedService {
   private readonly sendLimit: number;
   private readonly maxConcurrentCalls: number;
   private readonly shutdownTimeoutMs: number;
-  private readonly routes = new Map<string, { entry: Contribution; method: MethodDefinition; name: string | symbol; binding?: GrpcRequestBinding }>();
+  private readonly routes = new Map<string, { entry: Contribution; method: MethodDefinition; name: string | symbol; binding?: GrpcRequestBinding; checks: readonly AuthorizeCheck[] }>();
+  private readonly logger?: Logger;
   private readonly sessions = new Set<ServerHttp2Session>();
   private readonly active = new Map<GrpcCall, Promise<void>>();
   private state: "idle" | "starting" | "running" | "stopping" | "stopped" = "idle";
@@ -34,6 +37,7 @@ export class GrpcServer implements HostedService {
   private boundPort?: number;
 
   constructor(options: GrpcModuleOptions, private readonly provider: ServiceProvider, controllers: readonly Contribution[]) {
+    this.logger = provider.tryResolve(LOGGER);
     const address = options.address ?? "127.0.0.1:50051";
     const match = typeof address === "string" && /^(?:\[([^\]]+)\]|([^:[\]\s]+)):(\d{1,5})$/.exec(address);
     if (!match || Number(match[3]) > 65535 || options.address === null) throw new TypeError("gRPC address must be host:port or [IPv6]:port.");
@@ -68,7 +72,9 @@ export class GrpcServer implements HostedService {
           throw new TypeError(`gRPC request stream/DTO mismatch: ${method.path}.`);
         }
         const model = explicit ?? generated?.model;
-        this.routes.set(method.path, { entry, method, name, binding: model ? new GrpcRequestBinding(model, validator) : undefined });
+        const access = resolveAuthorizeMeta(entry.payload.controller, name);
+        const checks = access.allowAnonymous ? [] : access.authorize?.checks ?? [];
+        this.routes.set(method.path, { entry, method, name, binding: model ? new GrpcRequestBinding(model, validator) : undefined, checks });
       }
     }
     const tls = credentials.http2Options();
@@ -113,7 +119,7 @@ export class GrpcServer implements HostedService {
       reject(error instanceof GrpcError ? error.code : GrpcStatus.INVALID_ARGUMENT, error instanceof GrpcError ? error.message : "Invalid gRPC headers.");
       return;
     }
-    const execution = new GrpcCall(transport, route.method, route.name, route.entry.activation, this.provider, route.binding);
+    const execution = new GrpcCall(transport, route.method, route.name, route.entry.activation, this.provider, route.binding, route.checks, this.logger);
     const pending = execution.run().catch((error: unknown) => transport.fail(error))
       .finally(() => this.active.delete(execution));
     this.active.set(execution, pending);

package/core/grpc/GrpcTransport.ts

@@ -1,5 +1,5 @@
 import type { IncomingHttpHeaders, ServerHttp2Stream } from "node:http2";
-import type { GrpcContext } from "./contracts";
+import type { GrpcCallInfo } from "./contracts";
 import { Metadata } from "./Metadata";
 import { GrpcError } from "./GrpcError";
 import { GrpcStatus } from "./GrpcStatus";
@@ -7,7 +7,7 @@ import type { MethodDefinition } from "./serviceDefinition";
 
 /** Owns the standard five-byte gRPC envelope and one built-in HTTP/2 stream. */
 export class GrpcTransport {
-  readonly context: GrpcContext;
+  readonly context: GrpcCallInfo;
   private readonly abort = new AbortController();
   private sentHeaders = false;
   private ended = false;

package/core/grpc/contracts.ts

@@ -4,9 +4,10 @@ import type { ServerOptions, ServiceDefinition } from "./serviceDefinition";
 import type { Class, BazisModuleRef } from "../di";
 import type { ModelValidator } from "../http/Binding/modelValidator";
 import type { RequestModelClass } from "../http/Binding/requestModelRegistry";
+import type { AuthorizeContext } from "../http/Authorization/metadata";
 
-/** One instance per RPC, including the complete lifetime of a streaming RPC. */
-export interface GrpcContext {
+/** Transport facts of one RPC, before its DI scope exists. */
+export interface GrpcCallInfo {
   readonly metadata: Metadata;
   readonly signal: AbortSignal;
   readonly deadline: Date | number;
@@ -15,10 +16,16 @@ export interface GrpcContext {
   sendMetadata(metadata: Metadata): void;
 }
 
+/**
+ * One instance per RPC, including the complete lifetime of a streaming RPC.
+ * It is also what `@Authorize` checks see: `header(name)` reads text metadata,
+ * `services` is the RPC scope, `state` is shared with the handler.
+ */
+export interface GrpcContext extends GrpcCallInfo, AuthorizeContext {}
+
 export interface GrpcModuleOptions {
+  /** Modules whose `grpcControllers` are served (the whole tree). */
   readonly imports?: readonly BazisModuleRef[];
-  /** Normally contributed by feature-module grpcControllers. */
-  readonly controllers?: readonly Class<object>[];
   /** DTO validation, captured per server. Default: Bazis's modelValidatorAdapter. */
   readonly validator?: ModelValidator;
   /** host:port or [IPv6]:port, default 127.0.0.1:50051. Port 0 selects a free port. */

package/core/grpc/moduleControllers.ts

@@ -24,8 +24,8 @@ registerModuleOwnedProviderContributor((metadata, context) => {
 });
 
 /** @internal Discover only the feature tree published by this transport. */
-export function collectGrpcControllers(roots: readonly BazisModuleRef[], extra: readonly Class<object>[] = []): Set<Class<object>> {
-  const result = new Set(extra);
+export function collectGrpcControllers(roots: readonly BazisModuleRef[]): Set<Class<object>> {
+  const result = new Set<Class<object>>();
   const visited = new Set<BazisModuleRef>();
   const visit = (module: BazisModuleRef): void => {
     if (visited.has(module)) return;

package/core/http/Authorization/bearerToken.ts

@@ -1,11 +1,11 @@
-import type { HttpContext } from "../HttpContext/HttpContext";
+import type { AuthorizeContext } from "./metadata";
 
 /**
  * The token of an `Authorization: Bearer <token>` header, or `undefined`
  * without the header, with another scheme or with an empty token. The scheme
  * is case-insensitive (RFC 7235); surrounding spaces are trimmed.
  */
-export function bearerToken(ctx: Pick<HttpContext, "header">): string | undefined {
+export function bearerToken(ctx: Pick<AuthorizeContext, "header">): string | undefined {
   const match = /^\s*bearer\s+(\S+)\s*$/i.exec(ctx.header("authorization") ?? "");
   return match?.[1];
 }

package/core/http/Authorization/metadata.ts

@@ -1,4 +1,4 @@
-import type { HttpContext } from "../HttpContext/HttpContext";
+import type { ServiceScope } from "../../di";
 
 // Same one-line polyfill as the rest of the HTTP module: Bun executes TC39
 // decorators natively, but Symbol.metadata may be missing in the runtime.
@@ -6,6 +6,19 @@ import type { HttpContext } from "../HttpContext/HttpContext";
 
 const AUTHORIZE_META = Symbol.for("bazis:http:authorize");
 
+/**
+ * What an access check sees. An HTTP request (`HttpContext`) and a gRPC call
+ * (`GrpcContext`) both provide it, so one check protects both transports.
+ */
+export interface AuthorizeContext {
+  /** A request header (HTTP) or a text metadata value (gRPC), by case-insensitive name. */
+  header(name: string): string | undefined;
+  /** The DI scope of this request or call. */
+  readonly services: ServiceScope;
+  /** Values shared by the checks and the handler of this request or call. */
+  readonly state: Map<string, unknown>;
+}
+
 /**
  * Access check for `@Authorize`. Receives the request context and decides
  * whether to let it through. The HTTP kernel does not know *what* is checked
@@ -18,8 +31,10 @@ const AUTHORIZE_META = Symbol.for("bazis:http:authorize");
  *   (for example `UnauthorizedError` → `401` when there are no credentials at all).
  *
  * Dependencies (services, DB) come from `ctx.services` (the request scope).
+ * On a gRPC call `false`/`ForbiddenError` is PERMISSION_DENIED and
+ * `UnauthorizedError`/`JwtError` is UNAUTHENTICATED.
  */
-export type AuthorizeCheck = (ctx: HttpContext) => boolean | Promise<boolean>;
+export type AuthorizeCheck = (ctx: AuthorizeContext) => boolean | Promise<boolean>;
 
 /** Authorization requirement: one or more checks (all must pass). */
 export interface AuthorizeOptions {

package/core/http/Decorators/controller.ts

@@ -12,7 +12,7 @@ import { ownMeta } from "./metadata";
  * ```
  *
  * The controller is a regular DI service: register it in a module
- * (`controllers: [...]` on `BazisModule`, or `httpModule({ controllers: [...] })`)
+ * (`controllers: [...]` on `BazisModule`)
  * with scoped lifetime and declare constructor dependencies as usual — auto deps work.
  */
 export function Controller(prefix = "") {

package/core/http/Errors/upstreamFailure.ts

@@ -0,0 +1,22 @@
+/**
+ * Marks an error of a call to another service. The HTTP error boundary answers
+ * `504 Gateway Timeout` for a timeout and `502 Bad Gateway` otherwise, like it
+ * does for `HttpClientError`. Clients of other protocols (gRPC) set the mark,
+ * so the HTTP layer does not depend on them.
+ */
+export type UpstreamFailure = "timeout" | "failure";
+
+const UPSTREAM_FAILURE = Symbol.for("bazis.http.upstreamFailure");
+
+/** Sets the mark on `error` (non-enumerable) and returns it. */
+export function markUpstreamFailure<E extends object>(error: E, kind: UpstreamFailure): E {
+  Object.defineProperty(error, UPSTREAM_FAILURE, { value: kind, configurable: true });
+  return error;
+}
+
+/** The mark of an upstream failure, if any. */
+export function upstreamFailure(error: unknown): UpstreamFailure | undefined {
+  if (error === null || typeof error !== "object") return undefined;
+  const kind = (error as { [UPSTREAM_FAILURE]?: unknown })[UPSTREAM_FAILURE];
+  return kind === "timeout" || kind === "failure" ? kind : undefined;
+}

package/core/http/HttpServer.ts

@@ -19,7 +19,7 @@ import type { Router } from "./Routing/Router";
 import { parseRequestPath } from "./Routing/template";
 import { assertVersioningOptions, createVersionReader, type VersionReader } from "./Versioning/VersionReader";
 import { HTTP_ERROR_HOOK, ROUTE_MIDDLEWARE_COMPOSER, SERVER_MIDDLEWARE, sortByOrder } from "./middlewareTokens";
-import type { HealthEndpointOptions, RouteMiddlewareComposer, HttpModuleOptions } from "./options";
+import type { HealthEndpointOptions, RouteMiddlewareComposer, HttpModuleOptions, HttpServerOptions } from "./options";
 import { WEBSOCKET_UPGRADE, type WebSocketUpgrade } from "./WebSocketUpgrade";
 import { HttpSetupError } from "./Errors/HttpError";
 import { getModelValidator, type ModelValidator } from "./Binding/modelValidator";
@@ -96,7 +96,7 @@ export class HttpServer implements HostedService {
   private docs?: PreparedOpenApiDocs;
 
   constructor(
-    private readonly options: HttpModuleOptions,
+    private readonly options: HttpServerOptions,
     /** Root container: the per-request scope factory. */
     private readonly provider: ServiceProvider,
     /** Root resolver for optional kernel services (Environment). */
@@ -181,11 +181,11 @@ export class HttpServer implements HostedService {
       this.options.versioning,
       this.collectRouteComposer(),
     );
-    this.router = builder.build(this.options.controllers as readonly Class<object>[]);
+    this.router = builder.build(this.options.controllers);
     this.readVersion = createVersionReader(this.options.versioning);
     this.docs = prepareOpenApiDocs({
       option: this.options.docs,
-      controllers: this.options.controllers as readonly Class<object>[],
+      controllers: this.options.controllers,
       globalPrefix: this.options.prefix,
       versioning: this.options.versioning,
       environment: this.resolver.tryResolve(Environment),

package/core/http/Middleware/errorHandler.ts

@@ -3,6 +3,7 @@ import { redactSensitive, redactSensitiveText } from "../../../library/redaction
 import { HttpClientError, HttpErrorCode } from "../../../library/http-client/errors";
 import type { HttpContext } from "../HttpContext/HttpContext";
 import { HttpError } from "../Errors/HttpError";
+import { upstreamFailure } from "../Errors/upstreamFailure";
 import type { HttpMiddleware } from "./types";
 
 export interface ErrorHandlerOptions {
@@ -162,6 +163,8 @@ function unexpectedStatus(error: unknown, mapper?: (error: unknown) => number |
   if (error instanceof HttpClientError && error.code !== undefined) {
     return error.code === HttpErrorCode.Timeout ? [504, "Gateway Timeout"] : [502, "Bad Gateway"];
   }
+  const upstream = upstreamFailure(error);
+  if (upstream !== undefined) return upstream === "timeout" ? [504, "Gateway Timeout"] : [502, "Bad Gateway"];
   let mapped: number | undefined;
   try { mapped = mapper?.(error); } catch { mapped = undefined; }
   if (mapped !== undefined && Number.isInteger(mapped) && mapped >= 400 && mapped <= 599) return [mapped, REASONS[mapped] ?? (mapped >= 500 ? "Server Error" : "Client Error")];

package/core/http/httpModule.ts

@@ -1,10 +1,10 @@
 import { DI, HOSTED_SERVICE, Module, SERVICE_PROVIDER, collectModuleControllers, type BazisModule, type ProviderDefinition } from "../di";
 import { HttpServer } from "./HttpServer";
-import type { HttpModuleOptions } from "./options";
+import type { HttpModuleOptions, HttpServerOptions } from "./options";
 
 /**
- * Builds the HTTP module: discovers controllers from `imports` (and optional
- * `controllers` on feature modules) and registers the HttpServer hosted service.
+ * Builds the HTTP module: discovers the `controllers` of the modules in
+ * `imports` and registers the HttpServer hosted service.
  *
  * ```ts
  * @Module({
@@ -22,11 +22,9 @@ import type { HttpModuleOptions } from "./options";
  * ```
  */
 export function httpModule(options: HttpModuleOptions): BazisModule {
-  const allControllers = collectModuleControllers(options.imports ?? [], options.controllers);
-
-  const serverOptions: HttpModuleOptions = {
+  const serverOptions: HttpServerOptions = {
     ...options,
-    controllers: allControllers,
+    controllers: collectModuleControllers(options.imports ?? []),
   };
 
   const providers: ProviderDefinition[] = [
@@ -40,7 +38,6 @@ export function httpModule(options: HttpModuleOptions): BazisModule {
   @Module({
     imports: options.imports,
     providers,
-    controllers: options.controllers,
   })
   class HttpModule {}
 

package/core/http/index.ts

@@ -39,6 +39,7 @@ export { anyOf } from "./Authorization/anyOf";
 export {
   resolveAuthorizeMeta,
   type AuthorizeCheck,
+  type AuthorizeContext,
   type AuthorizeOptions,
   type ResolvedAuthorizeMeta,
 } from "./Authorization/metadata";
@@ -140,3 +141,4 @@ export {
   UnauthorizedError,
   UnsupportedMediaTypeError,
 } from "./Errors/HttpError";
+export { markUpstreamFailure, upstreamFailure, type UpstreamFailure } from "./Errors/upstreamFailure";

package/core/http/options.ts

@@ -56,11 +56,6 @@ export interface HttpModuleOptions {
    * Authorized/CORS-allowed clients can then inspect each redirect Location.
    */
   readonly inspectableRedirects?: boolean;
-  /**
-   * Controller classes (decorated with @Controller). Optional when controllers
-   * are declared on imported modules via `controllers` on `BazisModule`.
-   */
-  readonly controllers?: readonly Class<object>[];
   /** Request-model validator captured by this HTTP server instance. */
   readonly validator?: ModelValidator;
   /**
@@ -136,3 +131,8 @@ export interface HttpModuleOptions {
   /** Hosted-service startup phase (default 10 — after infrastructure). */
   readonly phase?: number;
 }
+
+/** @internal What `httpModule` hands to the server: the options plus the controllers it collected. */
+export interface HttpServerOptions extends HttpModuleOptions {
+  readonly controllers: readonly Class<object>[];
+}

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.31" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.33" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/kernel/health/HealthService.ts

@@ -1,4 +1,4 @@
-import type { ServiceResolver } from "../../di";
+import { HOSTED_SERVICE_HEALTH, type ServiceResolver } from "../../di";
 import { redactSensitiveText } from "../../../library/redaction";
 import { awaitAbortable } from "../internal/awaitAbortable";
 import { KernelError } from "../errors";
@@ -21,7 +21,8 @@ export class HealthService {
     const timeoutMs = bounded(options.timeoutMs ?? 5000, "timeoutMs", 2147483647);
     const checkTimeoutMs = bounded(options.checkTimeoutMs ?? 1000, "checkTimeoutMs", 2147483647);
     const concurrency = bounded(options.concurrency ?? 4, "concurrency", 1024);
-    const checks = this.resolver.resolveAll(HEALTH_CHECK);
+    // Hosted services (background) report whether they still run.
+    const checks: readonly HealthCheck[] = [...this.resolver.resolveAll(HEALTH_CHECK), ...this.resolver.resolveAll(HOSTED_SERVICE_HEALTH)];
     const entries: HealthReportEntry[] = new Array(checks.length);
     const report = new AbortController();
     const timer = setTimeout(() => report.abort(new Error("Health report timed out.")), timeoutMs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.31",
+  "version": "0.98.33",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",

package/core/background/backgroundModule.ts

@@ -1,42 +0,0 @@
-import {
-  DI,
-  HOSTED_SERVICE,
-  Module,
-  singleton,
-  type Class,
-  type HostedService,
-  type BazisModule,
-  type ProviderDefinition,
-} from "../di";
-
-export interface BackgroundModuleConfig {
-  /**
-   * Background service classes (subclasses of `BackgroundService` /
-   * `PeriodicBackgroundService`). Each is registered as a singleton (with
-   * auto-resolved constructor dependencies) and exposed as a `HOSTED_SERVICE`,
-   * so the kernel starts and gracefully stops it with the rest of the app.
-   */
-  readonly services: readonly Class<HostedService>[];
-}
-
-/**
- * Registers background services in DI and wires them into the kernel lifecycle.
- *
- * ```ts
- * @Module({ imports: [backgroundModule({ services: [SessionCleanup, Heartbeat] })] })
- * class AppModule {}
- * ```
- */
-export function backgroundModule(config: BackgroundModuleConfig): BazisModule {
-  const providers: ProviderDefinition[] = config.services.flatMap((ServiceClass) => [
-    singleton(ServiceClass),
-    DI.singleton(
-      DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => resolver.resolve(ServiceClass)),
-    ),
-  ]);
-
-  @Module({ providers })
-  class BackgroundModule {}
-
-  return BackgroundModule;
-}