bazis 0.98.9 → 0.98.11

package/core/app/runApp.ts

@@ -8,6 +8,7 @@ import {
   type BazisModuleRef,
 } from "../di";
 import { loadBazisGeneratedRuntime } from "../generatedRuntime";
+import { missingCacheModuleCheck } from "../cache/http/missingCacheModuleCheck";
 import { httpModule, useModelValidator, type HttpModuleOptions, type ModelValidator } from "../http";
 import { grpcModule, type GrpcModuleOptions } from "../grpc";
 import { buildHttpOpenApiDocument } from "../http/OpenApi/openApiDocument";
@@ -256,6 +257,10 @@ export function composeApp(root: BazisModuleRef, options: RunAppOptions = {}): B
   if (options.cache !== undefined) {
     globals.push(options.cache);
   }
+  if (options.http !== undefined) {
+    // Warns about @OutputCache routes when no cache module is installed.
+    globals.push({ global: true, providers: [missingCacheModuleCheck()] });
+  }
   const appRoot: BazisModuleRef =
     globals.length > 0 || options.config !== undefined
       ? {

package/core/cache/SPEC.md

@@ -299,11 +299,11 @@ Infra separately publishes `DISTRIBUTED_CACHE_BACKEND`, `DISTRIBUTED_OUTPUT_CACH
 
 ## 5. Named policies
 
-Policies are reusable presets in `buildCacheModule({ policies })`. A decorator refers to one with `policy: "name"`.
+Policies are reusable presets in `memory({ policies })` (since 0.98.10; before only the internal `buildCacheModule`). A decorator refers to one with `policy: "name"`.
 Inline decorator fields **override** the policy (policy → inline, inline wins).
 
 ```ts
-buildCacheModule({
+memory({
   policies: {
     catalog: {
       seconds: 60,
@@ -340,7 +340,7 @@ Caches the **full HTTP response** after the action runs. On a cache hit the cont
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `seconds` | `number` | — | **Required** (inline or in the policy). The entry TTL |
-| `policy` | `string` | — | A policy name from `buildCacheModule({ policies })` |
+| `policy` | `string` | — | A policy name from `memory({ policies })` |
 | `tags` | `string[]` | — | Tags for `ICache.evictByTag(tag)` |
 | `enabled` | `boolean` | `true` | `false`: the middleware is not attached (the metadata is kept) |
 | `noStore` | `boolean` | `false` | `true`: neither read nor write the cache |
@@ -440,6 +440,8 @@ Sensitive response headers are **neither stored nor replayed**:
 
 The body is read whole (`arrayBuffer`): **streaming responses are not supported**.
 
+A response served from the cache carries `Age`: seconds since it was stored (since 0.98.10).
+
 ---
 
 ## 7. `@OutputRedisCache` — HTTP output cache (distributed)
@@ -1007,7 +1009,7 @@ without varyByUser or unlessAuthenticated — …
 ```
 
 For a migration you can temporarily enable the warning mode:
-`buildCacheModule({ outputCache: { insecureAuthorizedRouteBehavior: "warn" } })`.
+`memory({ outputCache: { insecureAuthorizedRouteBehavior: "warn" } })`.
 Disabling it fully (`"ignore"`) is acceptable only with an external security policy.
 
 ### 17.2. Recommendations by scenario

package/core/cache/cacheModule.ts

@@ -1,21 +1,32 @@
 import type { BazisModuleRef } from "../di";
-import { buildCacheModule } from "./internal/buildCacheProviders";
+import { buildCacheModule, type CacheOutputCacheOptions } from "./internal/buildCacheProviders";
 import type { CacheOptions } from "./types/CacheOptions";
+import type { CachePolicyRegistry } from "./types/CachePolicy";
+
+/** Options of {@link memory}: the in-memory store plus named policies and output-cache settings. */
+export interface MemoryCacheOptions extends CacheOptions {
+  /** Named policies shared by `@OutputCache({ policy })` and `@Cacheable({ policy })`. */
+  readonly policies?: CachePolicyRegistry;
+  /** HTTP output cache settings: global switch and the check of authorized routes. */
+  readonly outputCache?: CacheOutputCacheOptions;
+}
 
 /**
  * In-memory cache as a one-line value. Inject {@link ICache} anywhere; decorate
  * methods with `@Cacheable` or routes with `@OutputCache`.
  *
  * ```ts
- * createApp({ cache: memory({ maxEntries: 1000 }) });
+ * await runApp(AppModule, {
+ *   cache: memory({ maxEntries: 1000, policies: { catalog: { seconds: 60, tags: ["catalog"] } } }),
+ *   http: { port: 3000 },
+ * });
  * // or, inside a module: imports: [memory()]
  * ```
  *
- * Options are just the in-memory knobs (`maxEntries`, `defaultTtlSeconds`, …).
  * For multi-instance caching keep `memory()` and add a distributed backend in your
  * `@Infra` manifest via `redisConnect(redisConfig, { cache: "distributed" })`; `@CacheableRedis` /
  * `@OutputRedisCache` then pick the backend up from DI automatically.
  */
-export function memory(options: CacheOptions = {}): BazisModuleRef {
+export function memory(options: MemoryCacheOptions = {}): BazisModuleRef {
   return buildCacheModule(options);
 }

package/core/cache/distributed/codecs.ts

@@ -11,6 +11,7 @@ interface SerializedHttpPayload {
   readonly status: number;
   readonly headers: Readonly<Record<string, string>>;
   readonly body: string;
+  readonly storedAt?: number;
 }
 
 /** Codec for HTTP output payloads — body is base64 because JSON cannot hold bytes. */
@@ -20,6 +21,7 @@ export const httpPayloadCacheCodec: CacheCodec<CachedHttpPayload> = {
       status: payload.status,
       headers: payload.headers,
       body: Buffer.from(payload.body).toString("base64"),
+      ...(payload.storedAt !== undefined ? { storedAt: payload.storedAt } : {}),
     } satisfies SerializedHttpPayload),
   deserialize: (raw) => {
     const parsed = JSON.parse(raw) as SerializedHttpPayload;
@@ -27,6 +29,7 @@ export const httpPayloadCacheCodec: CacheCodec<CachedHttpPayload> = {
       status: parsed.status,
       headers: parsed.headers,
       body: Uint8Array.from(Buffer.from(parsed.body, "base64")),
+      ...(typeof parsed.storedAt === "number" ? { storedAt: parsed.storedAt } : {}),
     };
   },
 };

package/core/cache/http/CachedHttpPayload.ts

@@ -25,6 +25,8 @@ export interface CachedHttpPayload {
   readonly status: number;
   readonly headers: Readonly<Record<string, string>>;
   readonly body: Uint8Array;
+  /** When the response was stored (epoch ms); a cache hit derives `Age` from it. */
+  readonly storedAt?: number;
 }
 
 export interface CachedHttpPayloadReadOptions {
@@ -105,8 +107,9 @@ export async function responseToCachedPayload(
       headers[lower] = value;
     }
   });
+  const storedAt = Date.now();
   if (response.body === null) {
-    return { status: response.status, headers, body: new Uint8Array() };
+    return { status: response.status, headers, body: new Uint8Array(), storedAt };
   }
 
   let clone: ReturnType<Response["clone"]>;
@@ -124,13 +127,21 @@ export async function responseToCachedPayload(
   // The cached payload replaces the original response. Release its tee branch
   // after the clone has been fully materialized.
   await response.body.cancel().catch(() => undefined);
-  return { status: response.status, headers, body };
+  return { status: response.status, headers, body, storedAt };
 }
 
-export function cachedPayloadToResponse(payload: CachedHttpPayload): Response {
+/**
+ * Rebuilds the stored response. `hit: true` marks a response served from the
+ * cache with `Age` — seconds since it was stored (RFC 9111).
+ */
+export function cachedPayloadToResponse(payload: CachedHttpPayload, options: { readonly hit?: boolean } = {}): Response {
+  const headers = stripSensitiveResponseHeaders(payload.headers);
+  if (options.hit && payload.storedAt !== undefined) {
+    headers.age = String(Math.max(0, Math.floor((Date.now() - payload.storedAt) / 1000)));
+  }
   return new Response(payload.body as unknown as ConstructorParameters<typeof Response>[0], {
     status: payload.status,
-    headers: stripSensitiveResponseHeaders(payload.headers),
+    headers,
   });
 }
 

package/core/cache/http/missingCacheModuleCheck.ts

@@ -0,0 +1,32 @@
+import { singletonFactoryWithResolver, type ProviderDefinition } from "../../di";
+import { ROUTE_MIDDLEWARE_COMPOSER, type RouteMiddlewareComposerRegistration } from "../../http";
+import { LOGGER } from "../../kernel";
+import { outputCacheMetaOf, resolveOutputCacheRequirement } from "../decorators/outputCacheMetadata";
+import { ICache } from "../ICache";
+
+/**
+ * A route composer the application composition installs next to the HTTP
+ * server: it adds no middleware and only warns at startup about each
+ * `@OutputCache` route when no cache module is installed — then the decorator
+ * does nothing and every request runs the action.
+ */
+export function missingCacheModuleCheck(): ProviderDefinition {
+  return singletonFactoryWithResolver(ROUTE_MIDDLEWARE_COMPOSER, [], (resolver): RouteMiddlewareComposerRegistration => {
+    const cacheInstalled = resolver.tryResolve(ICache) !== undefined;
+    const logger = resolver.tryResolve(LOGGER);
+    return {
+      order: 0,
+      compose: (controllerClass, methodName) => {
+        if (cacheInstalled) return [];
+        const requirement = resolveOutputCacheRequirement(outputCacheMetaOf(controllerClass), methodName);
+        if (requirement === undefined || requirement.enabled === false) return [];
+        const message = `[cache] @OutputCache on ${controllerClass.name}.${String(methodName)} has no effect: `
+          + "no cache module is installed, so every request runs the action. "
+          + "Add `cache: memory()` to the runApp options.";
+        if (logger) logger.warn(message);
+        else console.warn(message);
+        return [];
+      },
+    };
+  });
+}

package/core/cache/http/outputCacheMiddleware.ts

@@ -79,7 +79,7 @@ export function outputCacheMiddleware(options: OutputCacheMiddlewareOptions): Ht
     const key = buildOutputCacheKey(ctx, routeName, config);
     const cached = cache.get(key);
     if (cached !== undefined) {
-      ctx.response = applyClientCacheHeaders(cachedPayloadToResponse(cached), clientCache);
+      ctx.response = applyClientCacheHeaders(cachedPayloadToResponse(cached, { hit: true }), clientCache);
       return;
     }
 

package/core/cache/http/outputRedisCacheMiddleware.ts

@@ -83,7 +83,7 @@ export function outputRedisCacheMiddleware(options: OutputRedisCacheMiddlewareOp
     const key = buildRedisOutputCacheKey(ctx, routeName, config);
     const cached = await cache.get(key);
     if (cached !== undefined) {
-      ctx.response = applyClientCacheHeaders(cachedPayloadToResponse(cached), clientCache);
+      ctx.response = applyClientCacheHeaders(cachedPayloadToResponse(cached, { hit: true }), clientCache);
       return;
     }
 

package/core/cache/index.ts

@@ -59,7 +59,7 @@ export {
   DISTRIBUTED_SERVICE_CACHE,
 } from "./tokens/DISTRIBUTED_CACHE";
 
-export { memory } from "./cacheModule";
+export { memory, type MemoryCacheOptions } from "./cacheModule";
 /** @internal Advanced builder used by the hosting layer. */
 export {
   buildCacheModule,

package/core/di/ServiceProvider.ts

@@ -36,6 +36,7 @@ import {
   isFactoryProvider,
   isKeyedDependency,
   isLazyDependency,
+  isOptionalDependency,
   isNamedDependency,
   isValueProvider,
 } from "./provider";
@@ -78,6 +79,7 @@ export class ServiceProvider implements ServiceResolver {
           ? { required: provider.useClass.length, declared: this.getClassProviderDeps(provider).length }
           : undefined,
       describeDependency: (dependency) => this.getDependencyDescriptor(dependency),
+      hasName: (name) => this.registry.lookupName(name) !== undefined,
       findRegistration: (token, key) => this.registry.find(token, key),
     };
   }
@@ -417,6 +419,9 @@ export class ServiceProvider implements ServiceResolver {
         resolved[index] = this.createLazy(dependency.token, dependency.key, scopeState, ownerLifetime, stack);
         continue;
       }
+      if (dependency.optional && !this.registry.find(dependency.token, dependency.key)) {
+        continue;
+      }
       resolved[index] = await this.resolveSingleAsync(dependency.token, dependency.key, scopeState, stack, ownerLifetime);
     }
     return resolved;
@@ -560,6 +565,9 @@ export class ServiceProvider implements ServiceResolver {
       if (dependency === undefined) {
         continue;
       }
+      if (dependency.optional && !this.registry.find(dependency.token, dependency.key)) {
+        continue;
+      }
       resolved[index] = dependency.lazy
         ? this.createLazy(dependency.token, dependency.key, scopeState, ownerLifetime, stack)
         : this.resolveSingle(dependency.token, dependency.key, scopeState, stack, ownerLifetime);
@@ -584,8 +592,14 @@ export class ServiceProvider implements ServiceResolver {
         continue;
       }
       const lazy = isLazyDependency(dep);
-      const descriptor = this.getDependencyDescriptor(lazy ? dep.inner : dep);
-      plan[index] = { token: descriptor.token, key: descriptor.key, lazy };
+      const optional = isOptionalDependency(dep);
+      if (optional && isNamedDependency(dep.inner) && !this.registry.lookupName(dep.inner.name)) {
+        // An optional dependency on a name nothing registered stays unset.
+        plan[index] = undefined;
+        continue;
+      }
+      const descriptor = this.getDependencyDescriptor(lazy || optional ? dep.inner : dep);
+      plan[index] = { token: descriptor.token, key: descriptor.key, lazy, ...(optional ? { optional } : {}) };
     }
     this.planCache.set(provider, plan);
     return plan;

package/core/di/index.ts

@@ -82,7 +82,7 @@ export {
   type OpenGenericTokenFamily,
   type Token,
 } from "./token";
-export { ProviderDefinition, keyedDependency, lazyDependency, namedDependency } from "./provider";
+export { ProviderDefinition, keyedDependency, lazyDependency, namedDependency, optionalDependency } from "./provider";
 export type {
   AsyncFactoryProvider,
   ClassProvider,
@@ -90,6 +90,7 @@ export type {
   KeyedDependency,
   Lazy,
   LazyDependency,
+  OptionalDependency,
   NamedDependency,
   Provider,
   ProviderDependencyList,

package/core/di/internal/GraphValidator.ts

@@ -1,5 +1,5 @@
 import { ServiceValidationError } from "../errors";
-import { isLazyDependency } from "../provider";
+import { isLazyDependency, isNamedDependency, isOptionalDependency } from "../provider";
 import type {
   KeyedDependency,
   NamedDependency,
@@ -24,6 +24,8 @@ export interface GraphValidationContext {
   dependencies(provider: Provider<unknown>): ProviderDependencyList;
   /** Constructor arity vs declared deps for class providers; `undefined` for non-class providers. */
   classShape(provider: Provider<unknown>): { readonly required: number; readonly declared: number } | undefined;
+  /** True when some registration carries this name (for optional named dependencies). */
+  hasName(name: string): boolean;
   describeDependency(
     dependency: Token<unknown> | KeyedDependency<unknown> | NamedDependency<unknown>,
   ): { readonly token: Token<unknown>; readonly key: ServiceKey | undefined };
@@ -88,8 +90,17 @@ export class GraphValidator {
           continue;
         }
         const isLazy = isLazyDependency(dependency);
-        const descriptor = this.context.describeDependency(isLazy ? dependency.inner : dependency);
+        const isOptional = isOptionalDependency(dependency);
+        const inner = isLazy || isOptional ? dependency.inner : dependency;
+        // An optional dependency on a name nothing registered is simply absent.
+        if (isOptional && isNamedDependency(inner) && !this.context.hasName(inner.name)) {
+          continue;
+        }
+        const descriptor = this.context.describeDependency(inner);
         const depRegistration = this.context.findRegistration(descriptor.token, descriptor.key);
+        if (!depRegistration && isOptional) {
+          continue;
+        }
         if (!depRegistration) {
           issues.add(
             `Missing dependency "${tokenToDebugName(descriptor.token)}" for "${tokenToDebugName(registration.token)}"`,

package/core/di/internal/ResolutionPlan.ts

@@ -13,6 +13,8 @@ export interface PlannedDependency {
   readonly token: Token<unknown>;
   readonly key: ServiceKey | undefined;
   readonly lazy: boolean;
+  /** Resolve to `undefined` when the token has no registration. */
+  readonly optional?: boolean;
 }
 
 export type ResolutionPlan = readonly (PlannedDependency | undefined)[];

package/core/di/module/autoDeps.ts

@@ -1,7 +1,8 @@
-import { lazyDependency, namedDependency, type ProviderDependencyList } from "../provider";
+import { lazyDependency, namedDependency, optionalDependency, type ProviderDependencyList } from "../provider";
 import type { Class } from "../token";
 
 const LAZY_PREFIX = "lazy:";
+const OPTIONAL_PREFIX = "optional:";
 // These registrations live for the process lifetime just like their
 // constructors. A Map, rather than a WeakMap, lets the generated-runtime
 // owner take an exact rollback snapshot before publishing a target slice.
@@ -24,7 +25,9 @@ export function getGeneratedClassDeps(useClass: Class<unknown>): ProviderDepende
     typeof dependency !== "string" ? dependency
       : dependency.startsWith(LAZY_PREFIX)
         ? lazyDependency(namedDependency(dependency.slice(LAZY_PREFIX.length)))
-        : namedDependency(dependency),
+        : dependency.startsWith(OPTIONAL_PREFIX)
+          ? optionalDependency(namedDependency(dependency.slice(OPTIONAL_PREFIX.length)))
+          : namedDependency(dependency),
   );
 }
 

package/core/di/module/encapsulation.ts

@@ -1,7 +1,7 @@
 import { ModuleEncapsulationError } from "../errors";
 import { getProviderDeps } from "../internal/providerDeps";
 import type { ProviderDefinition, ProviderDependencyList } from "../provider";
-import { isKeyedDependency, isLazyDependency, isNamedDependency } from "../provider";
+import { isKeyedDependency, isLazyDependency, isNamedDependency, isOptionalDependency } from "../provider";
 import type { OpenGenericTokenFamily, Token } from "../token";
 import { tokenToDebugName } from "../token";
 import { applyNamedDependencyEncapsulationHooks } from "./encapsulationHooks";
@@ -249,7 +249,7 @@ function checkDependency(
 
   // Laziness changes "when" a dependency is created, not "whether" the module
   // may see it — validate the inner descriptor with the same rules.
-  if (isLazyDependency(dep)) {
+  if (isLazyDependency(dep) || isOptionalDependency(dep)) {
     checkDependency(record, definition, dep.inner, context);
     return;
   }

package/core/di/module/moduleNameBinding.ts

@@ -3,7 +3,9 @@ import { getProviderDeps, withProviderDeps } from "../internal/providerDeps";
 import {
   isLazyDependency,
   isNamedDependency,
+  isOptionalDependency,
   lazyDependency,
+  optionalDependency,
   ProviderDefinition,
 } from "../provider";
 import type { ProviderDependencyList } from "../provider";
@@ -118,6 +120,14 @@ function rebindDependency(dep: Dependency, nameMap: Map<string, Token<unknown>[]
     }
     return dep;
   }
+  if (isOptionalDependency(dep)) {
+    const inner = dep.inner;
+    if (isNamedDependency(inner)) {
+      const token = resolveName(inner.name, nameMap);
+      return token ? optionalDependency(token) : dep;
+    }
+    return dep;
+  }
   if (isNamedDependency(dep)) {
     return resolveName(dep.name, nameMap) ?? dep;
   }

package/core/di/module/providerSelection.ts

@@ -2,7 +2,7 @@ import { ModuleEncapsulationError } from "../errors";
 import { getProviderDeps } from "../internal/providerDeps";
 import { NamedTokenIndex } from "../internal/NamedTokenIndex";
 import type { OpenGenericRegistration } from "../internal/OpenGenericRegistration";
-import { isKeyedDependency, isLazyDependency, isNamedDependency, type ProviderDefinition } from "../provider";
+import { isKeyedDependency, isLazyDependency, isNamedDependency, isOptionalDependency, type ProviderDefinition } from "../provider";
 import { tokenToDebugName, type Token } from "../token";
 import type { ServiceKey } from "../types";
 import { isFamilyExport, type ModuleGraphRecord } from "./encapsulation";
@@ -78,7 +78,7 @@ export function createProviderSelectionValidator(
   return (definition, record) => {
     for (const dependency of getProviderDeps(definition.provider)) {
       if (dependency === undefined) continue;
-      const dep = isLazyDependency(dependency) ? dependency.inner : dependency;
+      const dep = isLazyDependency(dependency) || isOptionalDependency(dependency) ? dependency.inner : dependency;
       const token = isNamedDependency(dep) ? names.lookup(dep.name) : isKeyedDependency(dep) ? dep.token : dep;
       if (!token) continue; // Missing dependencies retain their normal DI error.
       const key = isKeyedDependency(dep) ? dep.key : undefined;

package/core/di/provider/index.ts

@@ -18,9 +18,12 @@ export {
   isNamedDependency,
   lazyDependency,
   isLazyDependency,
+  optionalDependency,
+  isOptionalDependency,
   ProviderDefinition,
   type KeyedDependency,
   type Lazy,
   type LazyDependency,
+  type OptionalDependency,
 } from "./types";
 export { isAsyncFactoryProvider, isClassProvider, isFactoryProvider, isValueProvider } from "./providerGuards";

package/core/di/provider/types/OptionalDependency.ts

@@ -0,0 +1,26 @@
+import type { Token } from "../../token";
+import type { KeyedDependency } from "./KeyedDependency";
+import type { NamedDependency } from "./NamedDependency";
+
+/**
+ * Optional dependency: resolved when the token is registered, `undefined`
+ * otherwise. Codegen emits it for an optional constructor parameter
+ * (`cache?: ICache`, or one with a default value).
+ */
+export interface OptionalDependency<T> {
+  readonly optional: true;
+  readonly inner: Token<T> | KeyedDependency<T> | NamedDependency<T>;
+}
+
+export function optionalDependency<T>(inner: Token<T> | KeyedDependency<T> | NamedDependency<T>): OptionalDependency<T> {
+  return { optional: true, inner };
+}
+
+export function isOptionalDependency(value: unknown): value is OptionalDependency<unknown> {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      (value as Record<string, unknown>).optional === true &&
+      "inner" in (value as Record<string, unknown>),
+  );
+}

package/core/di/provider/types/ProviderDependencyList.ts

@@ -2,10 +2,12 @@ import type { Token } from "../../token";
 import type { KeyedDependency } from "./KeyedDependency";
 import type { LazyDependency } from "./LazyDependency";
 import type { NamedDependency } from "./NamedDependency";
+import type { OptionalDependency } from "./OptionalDependency";
 
 export type ProviderDependencyList = readonly (
   | Token<unknown>
   | KeyedDependency<unknown>
   | NamedDependency<unknown>
   | LazyDependency<unknown>
+  | OptionalDependency<unknown>
 )[];

package/core/di/provider/types/ResolvedDeps.ts

@@ -2,12 +2,15 @@ import type { Token } from "../../token";
 import type { KeyedDependency } from "./KeyedDependency";
 import type { Lazy, LazyDependency } from "./LazyDependency";
 import type { NamedDependency } from "./NamedDependency";
+import type { OptionalDependency } from "./OptionalDependency";
 
 export type ResolvedDeps<
-  D extends readonly (Token<unknown> | KeyedDependency<unknown> | NamedDependency<unknown> | LazyDependency<unknown>)[],
+  D extends readonly (Token<unknown> | KeyedDependency<unknown> | NamedDependency<unknown> | LazyDependency<unknown> | OptionalDependency<unknown>)[],
 > = {
   [K in keyof D]: D[K] extends LazyDependency<infer TResolvedLazy>
     ? Lazy<TResolvedLazy>
+    : D[K] extends OptionalDependency<infer TResolvedOptional>
+    ? TResolvedOptional | undefined
     : D[K] extends Token<infer TResolved>
       ? TResolved
       : D[K] extends KeyedDependency<infer TResolvedKeyed>

package/core/di/provider/types/index.ts

@@ -4,6 +4,7 @@ export type { FactoryProvider } from "./FactoryProvider";
 export { keyedDependency, isKeyedDependency, type KeyedDependency } from "./KeyedDependency";
 export { namedDependency, isNamedDependency, type NamedDependency } from "./NamedDependency";
 export { lazyDependency, isLazyDependency, type Lazy, type LazyDependency } from "./LazyDependency";
+export { optionalDependency, isOptionalDependency, type OptionalDependency } from "./OptionalDependency";
 export type { ProviderDependencyList } from "./ProviderDependencyList";
 export { ProviderDefinition } from "./ProviderDefinition";
 export type { ProviderLifetime } from "./ProviderLifetime";

package/core/http/Middleware/errorHandler.ts

@@ -1,5 +1,6 @@
 import { REQUEST_ID_STATE_KEY, type Logger } from "../../kernel";
 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 type { HttpMiddleware } from "./types";
@@ -124,15 +125,30 @@ export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware
         return;
       }
       safelyReportUnexpected(options, log, ctx, error);
+      const [status, title] = unexpectedStatus(error);
       ctx.response = options.exposeDetails
-        ? safeJsonResponse(500, {
-            error: "Internal Server Error",
+        ? safeJsonResponse(status, {
+            error: title,
             // Development only, but redacted like the log: a secret in an error
             // message must not reach a browser or a shared screenshot.
             message: redactSensitiveText(error instanceof Error ? error.message : String(error)),
             stack: error instanceof Error && error.stack !== undefined ? redactSensitiveText(error.stack) : undefined,
           })
-        : safeJsonResponse(500, { error: "Internal Server Error" });
+        : safeJsonResponse(status, { error: title });
     }
   };
 }
+
+/**
+ * An unhandled outbound HTTP failure is the upstream's fault, not ours:
+ * 504 when the call timed out, 502 otherwise. A client error without a code
+ * is a misconfiguration of our request (for example an invalid maxRedirects)
+ * and stays 500, like everything else. Upstream details never reach the
+ * client; the log keeps the full error.
+ */
+function unexpectedStatus(error: unknown): readonly [number, string] {
+  if (error instanceof HttpClientError && error.code !== undefined) {
+    return error.code === HttpErrorCode.Timeout ? [504, "Gateway Timeout"] : [502, "Bad Gateway"];
+  }
+  return [500, "Internal Server Error"];
+}

package/core/http-client/index.ts

@@ -16,8 +16,8 @@ import { DI, Module, createToken, type BazisModule, type ProviderDefinition } fr
 import { getOutboundCorrelationHeaders } from "../kernel";
 import {
   HttpClient,
+  HttpClientFactory,
   HttpClientFactoryBuilder,
-  type HttpClientFactory,
   type HeaderBag,
   type RequestConfig,
 } from "../../library/http-client";
@@ -44,9 +44,10 @@ export interface HttpClientModuleConfig {
 
 /**
  * Registers the outbound HTTP client in DI with correlation propagation wired
- * to the kernel request context:
- * - {@link HTTP_CLIENT_FACTORY} — named clients (fail-fast on unknown names);
- * - {@link HTTP_CLIENT} — the default injectable {@link HttpClient}.
+ * to the kernel request context. A service takes it by type:
+ * - `HttpClient` (or the {@link HTTP_CLIENT} token) — the default client;
+ * - `HttpClientFactory` (or {@link HTTP_CLIENT_FACTORY}) — named clients
+ *   (fail-fast on unknown names).
  */
 export function httpClientModule(config: HttpClientModuleConfig = {}): BazisModule {
   const correlationHeaders = config.correlationHeaders ?? getOutboundCorrelationHeaders;
@@ -83,11 +84,14 @@ export function httpClientModule(config: HttpClientModuleConfig = {}): BazisModu
   }
   const factory = builder.build();
 
+  const client = factory.createClient();
+  // One factory and one default client, under the class (injection by type)
+  // and under the original tokens.
   const providers: ProviderDefinition[] = [
+    DI.singleton(DI.valueProvider(HttpClientFactory, factory)),
     DI.singleton(DI.valueProvider(HTTP_CLIENT_FACTORY, factory)),
-    DI.singleton(
-      DI.factoryProvider(HTTP_CLIENT, [HTTP_CLIENT_FACTORY], (resolved: HttpClientFactory) => resolved.createClient()),
-    ),
+    DI.singleton(DI.valueProvider(HttpClient, client)),
+    DI.singleton(DI.valueProvider(HTTP_CLIENT, client)),
   ];
 
   @Module({ providers })

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.9" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.11" }, 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/scripts/di-generate.ts

@@ -152,7 +152,7 @@ const FRAMEWORK_INTERNAL_PREFIXES = FRAMEWORK_SOURCE === null ? [] : [
 ].map((prefix) => `${FRAMEWORK_SOURCE}/${prefix}`);
 
 // A declaration is an identity; short names are local to their source/module.
-interface CollectedDependency { readonly name: string; readonly target?: ts.ClassDeclaration; readonly lazy?: boolean; }
+interface CollectedDependency { readonly name: string; readonly target?: ts.ClassDeclaration; readonly lazy?: boolean; readonly optional?: boolean; }
 interface ConstructorDependencies {
   readonly deps: CollectedDependency[];
   readonly unsupportedInheritedParameter?: string;
@@ -619,7 +619,9 @@ function renderTargetDeps(): string {
     }
   }
   const lines = ["// This file is auto-generated by `bazis codegen`.", "// Do not edit manually."];
-  if (entries.some(([, deps]) => deps.some(dep => dep.target && dep.lazy))) lines.push('import { lazyDependency } from "bazis/core/di";');
+  const helpers = ["lazyDependency", "optionalDependency"].filter((helper) => entries.some(([, deps]) =>
+    deps.some((dep) => dep.target && (helper === "lazyDependency" ? dep.lazy : dep.optional))));
+  if (helpers.length > 0) lines.push(`import { ${helpers.join(", ")} } from "bazis/core/di";`);
   for (const [declaration, reference] of references) {
     const name = dependencyClassExportName(declaration);
     if (!name) throw new Error(`BAZIS_DI_CLASS_UNIMPORTABLE: ${sourceLocation(declaration)}`);
@@ -628,9 +630,9 @@ function renderTargetDeps(): string {
   lines.push("export const GENERATED_TARGET_CLASS_DEPS = Object.freeze([");
   for (const [declaration, dependencies] of entries) {
     const values = dependencies.map(dependency => {
-      if (!dependency.target) return JSON.stringify(dependency.name);
+      if (!dependency.target) return JSON.stringify(dependency.optional ? `optional:${dependency.name}` : dependency.name);
       const reference = references.get(dependency.target)!;
-      return dependency.lazy ? `lazyDependency(${reference})` : reference;
+      return dependency.lazy ? `lazyDependency(${reference})` : dependency.optional ? `optionalDependency(${reference})` : reference;
     });
     lines.push(`  [${references.get(declaration)}, [${values.join(", ")}]] as const,`);
   }
@@ -762,7 +764,7 @@ function resolveConfigViewDeps(): void {
         changed = false;
         break;
       }
-      resolved.push({ name: `Config:${prefixes[0]}` });
+      resolved.push({ name: `Config:${prefixes[0]}`, ...(dep.optional ? { optional: true } : {}) });
       changed = true;
     }
     if (changed && classDeps.has(declaration)) classDeps.set(declaration, resolved);
@@ -782,6 +784,12 @@ function validateDepsAgainstKnownTokens(): void {
       ) {
         continue;
       }
+      // An optional trailing parameter of a type DI does not know (`options: Options = {}`)
+      // is not injected: the constructor gets its default, as without codegen.
+      if (deps[index]!.optional) {
+        classDeps.set(declaration, deps.slice(0, index));
+        break;
+      }
       classDeps.delete(declaration);
       // A class DI must construct cannot lose a dependency silently: the app
       // would fail later, far from the cause. Other classes need no entry.
@@ -935,8 +943,11 @@ function readInheritedConstructorDeps(node: ts.ClassDeclaration): ConstructorDep
     }
   }
   const deps: CollectedDependency[] = [];
-  for (let index = 0; index <= lastRequired; index++) {
+  for (let index = 0; index < parameters.length; index++) {
     const parameter = parameters[index]!;
+    const parameterDeclaration = parameter.valueDeclaration;
+    const optional = parameterDeclaration !== undefined && ts.isParameter(parameterDeclaration)
+      && (parameterDeclaration.questionToken !== undefined || parameterDeclaration.initializer !== undefined);
     let type = checker.getTypeOfSymbolAtLocation(parameter, node);
     const declaration = parameter.valueDeclaration;
     // A default before a required argument still occupies a DI position. The
@@ -945,9 +956,14 @@ function readInheritedConstructorDeps(node: ts.ClassDeclaration): ConstructorDep
       const defined = type.types.filter((member) => !(member.flags & ts.TypeFlags.Undefined));
       if (defined.length === 1) type = defined[0]!;
     }
+    if (optional && type.isUnion()) {
+      const defined = type.types.filter((member) => !(member.flags & ts.TypeFlags.Undefined));
+      if (defined.length === 1) type = defined[0]!;
+    }
     const dependency = dependencyFromType(type);
+    if (!dependency && index > lastRequired) break;
     if (!dependency) return { deps: [], unsupportedInheritedParameter: parameter.name };
-    deps.push(dependency);
+    deps.push(optional && !dependency.lazy ? { ...dependency, optional: true } : dependency);
   }
   return { deps };
 }
@@ -983,16 +999,22 @@ function readConstructorTypeNames(node: ts.ClassDeclaration): ConstructorDepende
 
   const deps: CollectedDependency[] = [];
   const lastRequiredParamIndex = findLastRequiredParameterIndex(ctor);
-  for (let index = 0; index <= lastRequiredParamIndex; index += 1) {
+  for (let index = 0; index < ctor.parameters.length; index += 1) {
     const param = ctor.parameters[index];
     if (!param) {
       continue;
     }
+    // Optional parameters (`cache?: ICache`, `clock: Clock = new SystemClock()`)
+    // are injected when registered and left unset otherwise.
+    const optional = param.questionToken !== undefined || param.initializer !== undefined;
+    const trailing = index > lastRequiredParamIndex;
     const paramType = param.type;
     const refName = paramType ? getDependencyTypeName(paramType) : undefined;
     if (!refName || BUILTIN_DEPENDENCY_NAMES.has(refName)) {
+      if (trailing) break;
       return { deps: [], unsupportedParameter: { index, name: param.name.getText(), type: paramType?.getText() ?? "(no type)" } };
     }
+    const optionalFlag = optional ? { optional: true } : {};
 
     // `Lazy<X>` is a deferred dependency on X: encode it with a marker prefix
     // so the runtime injects a Lazy wrapper instead of resolving X eagerly.
@@ -1010,7 +1032,7 @@ function readConstructorTypeNames(node: ts.ClassDeclaration): ConstructorDepende
       const configType = paramType.typeArguments?.[0];
       const configTypeName = configType ? getDependencyTypeName(configType) : undefined;
       if (configTypeName) {
-        deps.push({ name: `ConfigView<${configTypeName}>` });
+        deps.push({ name: `ConfigView<${configTypeName}>`, ...optionalFlag });
         continue;
       }
     }
@@ -1019,12 +1041,12 @@ function readConstructorTypeNames(node: ts.ClassDeclaration): ConstructorDepende
       const entityType = paramType.typeArguments?.[0];
       const entityName = entityType ? getDependencyTypeName(entityType) : undefined;
       if (entityName) {
-        deps.push({ name: `IRepository<${entityName}>` });
+        deps.push({ name: `IRepository<${entityName}>`, ...optionalFlag });
         continue;
       }
     }
 
-    deps.push({ name: refName, target: dependencyClass(paramType!) });
+    deps.push({ name: refName, target: dependencyClass(paramType!), ...optionalFlag });
   }
 
   return { deps };

package/library/http-client/HttpClient.ts

@@ -6,7 +6,9 @@ import {
   appendQuery,
   basicAuthHeader,
   isBodyInit,
+  isAbsoluteUrl,
   mergeHeaderBags,
+  pageUrl,
   resolveUrl,
   shouldPropagateCorrelation,
 } from "./serialize";
@@ -188,7 +190,8 @@ export class HttpClient {
     return { ...merged, method: String(override.method ?? base.method ?? "GET").toUpperCase() };
   }
 
-  private async dispatch<T>(config: ResolvedRequestConfig): Promise<HttpResponse<T>> {
+  private async dispatch<T>(requested: ResolvedRequestConfig): Promise<HttpResponse<T>> {
+    const config = withAbsoluteBaseUrl(requested);
     if (config.inspectableRedirects !== undefined && typeof config.inspectableRedirects !== "boolean") {
       throw new HttpClientError("inspectableRedirects must be a boolean", { config });
     }
@@ -650,6 +653,26 @@ function isReplayableBody(body: RequestInit["body"]): boolean {
     || (typeof ReadableStream !== "undefined" && body instanceof ReadableStream));
 }
 
+/**
+ * A relative `baseUrl` (`"/api"`) is resolved against the page address once,
+ * so URL building and every origin check below see an absolute base. Outside
+ * a page there is nothing to resolve it against.
+ */
+function withAbsoluteBaseUrl(config: ResolvedRequestConfig): ResolvedRequestConfig {
+  const { baseUrl } = config;
+  if (!baseUrl || isAbsoluteUrl(baseUrl)) {
+    return config;
+  }
+  const page = pageUrl();
+  if (page === undefined) {
+    throw new HttpClientError(
+      `baseUrl "${baseUrl}" is relative: outside a browser page it must be absolute, for example "http://localhost:3000${baseUrl.startsWith("/") ? "" : "/"}${baseUrl}"`,
+      { config },
+    );
+  }
+  return { ...config, baseUrl: new URL(baseUrl, page).toString() };
+}
+
 function sameOrigin(left: string, right: string): boolean {
   try {
     return new URL(left).origin === new URL(right).origin;

package/library/http-client/HttpClientFactory.ts

@@ -2,9 +2,32 @@ import { HttpClient } from "./HttpClient";
 import { HttpClientConfigError } from "./errors";
 import type { RequestConfig } from "./types";
 
-/** Resolves pre-configured named clients (à la .NET `IHttpClientFactory`). */
-export interface HttpClientFactory {
-  createClient(name?: string): HttpClient;
+/**
+ * Resolves pre-configured named clients (à la .NET `IHttpClientFactory`).
+ * An abstract class, so a service can take it by type in its constructor.
+ */
+export abstract class HttpClientFactory {
+  public abstract createClient(name?: string): HttpClient;
+}
+
+class ConfiguredHttpClientFactory extends HttpClientFactory {
+  public constructor(
+    private readonly defaults: RequestConfig,
+    private readonly named: ReadonlyMap<string, RequestConfig>,
+  ) {
+    super();
+  }
+
+  public createClient(name?: string): HttpClient {
+    if (name === undefined) {
+      return new HttpClient(this.defaults);
+    }
+    const config = this.named.get(name);
+    if (config === undefined) {
+      throw new HttpClientConfigError(name, [...this.named.keys()]);
+    }
+    return new HttpClient(this.defaults).create(config);
+  }
 }
 
 /**
@@ -27,19 +50,6 @@ export class HttpClientFactoryBuilder {
   }
 
   public build(): HttpClientFactory {
-    const named = new Map(this.named);
-    const defaults = this.defaults;
-    return {
-      createClient(name?: string): HttpClient {
-        if (name === undefined) {
-          return new HttpClient(defaults);
-        }
-        const config = named.get(name);
-        if (config === undefined) {
-          throw new HttpClientConfigError(name, [...named.keys()]);
-        }
-        return new HttpClient(defaults).create(config);
-      },
-    };
+    return new ConfiguredHttpClientFactory(this.defaults, new Map(this.named));
   }
 }

package/library/http-client/index.ts

@@ -12,7 +12,7 @@
  */
 export { HttpClient } from "./HttpClient";
 export { InspectableRedirectProtocol } from "./redirectProtocol";
-export { HttpClientFactoryBuilder, type HttpClientFactory } from "./HttpClientFactory";
+export { HttpClientFactoryBuilder, HttpClientFactory } from "./HttpClientFactory";
 export { HttpClientError, HttpClientConfigError, HttpErrorCode } from "./errors";
 export { InterceptorManager, type FulfilledFn, type RejectedFn } from "./interceptors";
 export {

package/library/http-client/serialize.ts

@@ -8,6 +8,20 @@ const ABSOLUTE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
  * prefix), `baseUrl: "https://api/v1"` + `"/users"` → `…/v1/users`.
  * Absolute URLs and missing baseUrl pass through.
  */
+export function isAbsoluteUrl(url: string): boolean {
+  return ABSOLUTE_URL.test(url);
+}
+
+/**
+ * The address of the current page in a browser (or worker), else undefined.
+ * A relative `baseUrl` such as `"/api"` is resolved against it, like axios's
+ * `baseURL` in a browser app.
+ */
+export function pageUrl(): string | undefined {
+  const location = (globalThis as { location?: { href?: unknown } }).location;
+  return typeof location?.href === "string" ? location.href : undefined;
+}
+
 export function resolveUrl(baseUrl: string | undefined, url: string): string {
   if (!baseUrl || ABSOLUTE_URL.test(url)) {
     return url;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.9",
+  "version": "0.98.11",
   "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",