bazis 0.100.3 → 0.100.5

package/core/cache/distributed/connectionCache.ts

@@ -0,0 +1,24 @@
+import type { DistributedCacheStores } from "./DistributedCacheStores";
+import type { DistributedCacheSetOptions, IDistributedCache } from "./IDistributedCache";
+
+/**
+ * The `IDistributedCache` of one connection that services inject by type:
+ * values of `@CacheableRedis` and its own `get`/`getOrCreateAsync`; a tag is
+ * evicted from those values and from the `@OutputRedisCache` responses of the
+ * same connection, as `ICache.evictByTag` does in memory.
+ */
+export function connectionCache(stores: DistributedCacheStores, connection: string = stores.serviceCache.connectionNames[0]!): IDistributedCache {
+  const values = stores.serviceCache.resolve(connection);
+  const responses = stores.outputCache.resolve(connection);
+  return Object.freeze({
+    connectionName: values.connectionName,
+    keyPrefix: values.keyPrefix,
+    get: <T>(key: string) => values.get<T>(key),
+    getOrCreateAsync: <T>(key: string, factory: () => Promise<T | undefined>, options: DistributedCacheSetOptions) => values.getOrCreateAsync<T>(key, factory, options),
+    remove: (key: string) => values.remove(key),
+    async evictByTag(tag: string): Promise<number> {
+      const [fromValues, fromResponses] = await Promise.all([values.evictByTag(tag), responses.evictByTag(tag)]);
+      return fromValues + fromResponses;
+    },
+  });
+}

package/core/cache/distributed/index.ts

@@ -17,3 +17,4 @@ export type {
   DistributedCacheStores,
   DistributedCachePing,
 } from "./DistributedCacheStores";
+export { connectionCache } from "./connectionCache";

package/core/cache/http/missingCacheModuleCheck.ts

@@ -1,23 +1,44 @@
-import { singletonFactoryWithResolver, type ProviderDefinition } from "../../di";
+import { singletonFactoryWithResolver, type InjectionToken, type ProviderDefinition } from "../../di";
 import { ROUTE_MIDDLEWARE_COMPOSER, type RouteMiddlewareComposerRegistration } from "../../http";
 import { LOGGER } from "../../kernel";
 import { outputCacheMetaOf, resolveOutputCacheRequirement } from "../decorators/outputCacheMetadata";
+import { outputRedisCacheMetaOf, resolveOutputRedisCacheRequirement } from "../decorators/outputRedisCacheMetadata";
 import { ICache } from "../ICache";
+import { DISTRIBUTED_OUTPUT_CACHE } from "../tokens/DISTRIBUTED_CACHE";
+import type { CachedHttpPayload } from "./CachedHttpPayload";
+import { createRouteOutputCacheComposerWithOptions } from "./composeOutputCache";
+
+/** After the authorization checks, like the output cache of the cache module. */
+const OUTPUT_CACHE_COMPOSER_ORDER = 100;
 
 /**
  * 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.
+ * server for applications without a cache module (`cache: memory()`):
+ *
+ * - `@OutputRedisCache` needs only the distributed backend of `@Infra`, so
+ *   the routes are served from Redis; without a backend the start fails and
+ *   names the route;
+ * - `@OutputCache` needs the in-memory store: the start warns that the
+ *   decorator has no effect.
  */
 export function missingCacheModuleCheck(): ProviderDefinition {
   return singletonFactoryWithResolver(ROUTE_MIDDLEWARE_COMPOSER, [], (resolver): RouteMiddlewareComposerRegistration => {
     const cacheInstalled = resolver.tryResolve(ICache) !== undefined;
     const logger = resolver.tryResolve(LOGGER);
+    const redis = createRouteOutputCacheComposerWithOptions({
+      policies: {},
+      globalEnabled: true,
+      cacheToken: ICache as InjectionToken<ICache<CachedHttpPayload>>,
+      securityWarnings: { behavior: "throw" },
+      distributedEnabled: resolver.has(DISTRIBUTED_OUTPUT_CACHE),
+    });
     return {
-      order: 0,
-      compose: (controllerClass, methodName) => {
+      order: OUTPUT_CACHE_COMPOSER_ORDER,
+      compose: (controllerClass, methodName, meta, action) => {
         if (cacheInstalled) return [];
+        if (resolveOutputRedisCacheRequirement(outputRedisCacheMetaOf(controllerClass), methodName) !== undefined) {
+          return redis(controllerClass, methodName, meta, action);
+        }
         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: `

package/core/cache/index.ts

@@ -52,6 +52,7 @@ export {
   type DistributedCachePing,
   type DistributedCacheSetOptions,
   IDistributedCache,
+  connectionCache,
 } from "./distributed";
 export {
   DISTRIBUTED_CACHE_BACKEND,

package/core/cache/internal/buildCacheProviders.ts

@@ -3,6 +3,7 @@ import {
   CLASS_PROVIDER_HOOK,
   OptionsValidationError,
   singleton,
+  singletonFactoryWithResolver,
   singletonValue,
   type InjectionToken,
   type Options,
@@ -17,6 +18,7 @@ import type { CachedHttpPayload } from "../http/CachedHttpPayload";
 import { ICache } from "../ICache";
 import { MemoryCache } from "../MemoryCache";
 import { CACHE_POLICIES } from "../tokens/CACHE_POLICIES";
+import { DISTRIBUTED_OUTPUT_CACHE } from "../tokens/DISTRIBUTED_CACHE";
 import { CACHE_OPTIONS, validateCacheOptions, type CacheOptions } from "../types/CacheOptions";
 import type { CachePolicyRegistry } from "../types/CachePolicy";
 
@@ -113,22 +115,21 @@ function cacheOptionsProvider(config: CacheModuleConfig): ProviderDefinition {
 /** Registers the `@OutputCache` / `@OutputRedisCache` middleware via the HTTP DI token. */
 function outputCacheComposerProvider(config: CacheModuleConfig): ProviderDefinition {
   const token = config.token ?? ICache;
-  const compose = createRouteOutputCacheComposerWithOptions({
-    policies: config.policies ?? {},
-    globalEnabled: config.outputCache?.enabled !== false,
-    cacheToken: token as InjectionToken<ICache<CachedHttpPayload>>,
-    securityWarnings: {
-      behavior: outputCacheSecurityBehavior(config.outputCache),
-      requireAuthenticationByDefault: config.outputCache?.requireAuthenticationByDefault,
-    },
-    // Registries for `@OutputRedisCache` are published by Infra through DI.
-    // Without a registry the middleware reports an error on the first request.
-    distributedEnabled: true,
-  });
-  return singletonValue(ROUTE_MIDDLEWARE_COMPOSER, {
+  return singletonFactoryWithResolver(ROUTE_MIDDLEWARE_COMPOSER, [], (resolver) => ({
     order: OUTPUT_CACHE_COMPOSER_ORDER,
-    compose,
-  } satisfies RouteMiddlewareComposerRegistration);
+    compose: createRouteOutputCacheComposerWithOptions({
+      policies: config.policies ?? {},
+      globalEnabled: config.outputCache?.enabled !== false,
+      cacheToken: token as InjectionToken<ICache<CachedHttpPayload>>,
+      securityWarnings: {
+        behavior: outputCacheSecurityBehavior(config.outputCache),
+        requireAuthenticationByDefault: config.outputCache?.requireAuthenticationByDefault,
+      },
+      // `@OutputRedisCache` needs the backend Infra publishes; without one the
+      // start fails and names the route instead of every request failing.
+      distributedEnabled: resolver.has(DISTRIBUTED_OUTPUT_CACHE),
+    }),
+  } satisfies RouteMiddlewareComposerRegistration));
 }
 
 function outputCacheSecurityBehavior(options: CacheOutputCacheOptions | undefined): "throw" | "warn" | "ignore" {

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.100.3" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.100.5" }, 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/infra/connectors/llm.ts

@@ -31,7 +31,9 @@ export interface LlmConnectorOptions {
   /**
    * Check the provider at start (the adapter's `connect`: `GET /models` for an
    * OpenAI-compatible API, five seconds), so a wrong key or address stops the
-   * start instead of the first agent request. Default `true`.
+   * start instead of the first agent request. By default it runs in
+   * development and production and not in the `test` environment, where a
+   * test replaces the model; `true` checks there too, `false` never checks.
    */
   readonly checkOnStart?: boolean;
 }
@@ -92,7 +94,7 @@ export function llmConnect<T extends LlmConfigShape>(
   adapter: LlmProviderAdapter,
   options: LlmConnectorOptions = {},
 ): InfraConnector<AgentModelProvider> {
-  const described = new WeakMap<AgentModelProvider, { connection: LlmConnectionOptions; settings: string[] }>();
+  const described = new WeakMap<AgentModelProvider, { connection: LlmConnectionOptions; settings: string[]; check: boolean }>();
   return identifyConnector({
     token: AGENT_MODEL_PROVIDER,
     config,
@@ -101,11 +103,14 @@ export function llmConnect<T extends LlmConfigShape>(
     create(configs) {
       const connection = resolveLlmConnectionOptions(config, options, configs);
       const provider = adapter.create(connection);
-      described.set(provider, { connection, settings: settingNames(config, configs, ["baseUrl", "apiKey"]) });
+      // The environment of this kernel's configuration: tests do not call the real provider.
+      const environment = (configs?.get(config) as { environment?: string } | undefined)?.environment;
+      const check = options.checkOnStart ?? environment !== "test";
+      described.set(provider, { connection, settings: settingNames(config, configs, ["baseUrl", "apiKey"]), check });
       return provider;
     },
     connect(provider, signal) {
-      if (options.checkOnStart === false) return;
+      if (described.get(provider)?.check === false || options.checkOnStart === false) return;
       return adapter.connect?.(provider, signal);
     },
     describe(provider, { connected }) {
@@ -114,7 +119,7 @@ export function llmConnect<T extends LlmConfigShape>(
       return {
         kind: `${known.connection.provider} · ${known.connection.model}`,
         address: known.connection.baseUrl,
-        details: connected && options.checkOnStart !== false && adapter.connect !== undefined ? ["checked"] : [],
+        details: connected && known.check && adapter.connect !== undefined ? ["checked"] : [],
         settings: known.settings,
       };
     },

package/core/infra/connectors/redis.ts

@@ -4,6 +4,7 @@ import {
   DISTRIBUTED_OUTPUT_CACHE,
   DISTRIBUTED_SERVICE_CACHE,
   IDistributedCache,
+  connectionCache,
   type DistributedCacheStores,
 } from "../../cache";
 import { createToken, DI, type InjectionToken, type ProviderDefinition } from "../../di";
@@ -79,9 +80,7 @@ function distributedCacheProviders(tuning: RedisDistributedCacheTuning, token: I
     // This connector's one connection by type, for services that evict tags or
     // read values; its name may be "default" or the configured `connection`.
     DI.singleton(
-      DI.factoryProvider(IDistributedCache, [DISTRIBUTED_CACHE_BACKEND], (backend: DistributedCacheStores) =>
-        backend.serviceCache.resolve(backend.serviceCache.connectionNames[0]),
-      ),
+      DI.factoryProvider(IDistributedCache, [DISTRIBUTED_CACHE_BACKEND], (backend: DistributedCacheStores) => connectionCache(backend)),
     ),
   ];
 }

package/core/websocket/adapter/redis-delivery-store.ts

@@ -14,6 +14,14 @@ export interface RedisReliableDeliveryOptions {
   readonly maxReadBytes?: number;
 }
 
+/** Redis settings without which an acknowledged write may be lost. */
+const DURABLE_REDIS: Readonly<Record<string, string>> = Object.freeze({
+  appendonly: "yes",
+  appendfsync: "always",
+  "no-appendfsync-on-rewrite": "no",
+  "maxmemory-policy": "noeviction",
+});
+
 export class RedisRoomDeliveryStore implements ReliableRoomDelivery {
   private readonly limits: Required<Omit<RedisReliableDeliveryOptions, "requireAof">>;
   private readonly requireAof: boolean;
@@ -47,9 +55,18 @@ export class RedisRoomDeliveryStore implements ReliableRoomDelivery {
     if (Array.isArray(settings)) for (let i = 0; i < settings.length; i += 2) values.set(settings[i]!, settings[i + 1]!);
     else for (const [key, value] of Object.entries(settings)) values.set(key, value);
     const info = await this.operations.send("INFO", ["persistence"]) as string;
-    if (values.get("appendonly") !== "yes" || values.get("appendfsync") !== "always" || values.get("maxmemory-policy") !== "noeviction"
-      || values.get("no-appendfsync-on-rewrite") !== "no"
-      || !info.includes("aof_last_write_status:ok") || !info.includes("loading:0")) throw new WebSocketDeliveryError("DURABILITY_CONFIGURATION");
+    const problems = Object.entries(DURABLE_REDIS)
+      .filter(([name, needed]) => values.get(name) !== needed)
+      .map(([name, needed]) => `${name} is ${values.get(name) ?? "unknown"}, needs ${needed}`);
+    if (!info.includes("aof_last_write_status:ok")) problems.push("the last append-only file write failed (aof_last_write_status)");
+    if (!info.includes("loading:0")) problems.push("Redis is still loading its data");
+    if (problems.length > 0) {
+      throw new WebSocketDeliveryError(
+        "DURABILITY_CONFIGURATION",
+        `WebSocket delivery needs a Redis that does not lose writes: ${problems.join("; ")}. `
+          + "Set them in redis.conf or with CONFIG SET; otherwise undelivered messages and sessions may be lost.",
+      );
+    }
   }
 
   async publish(request: ReliableRoomPublication): Promise<ReliableBroadcastReceipt> {

package/core/websocket/middleware.ts

@@ -1,3 +1,4 @@
+import type { ServiceResolver } from "../di";
 import type { SocketUser } from "./types";
 import { JwtError } from "../../library/jwt";
 import { UnauthorizedError } from "../http";
@@ -23,6 +24,11 @@ export interface WsAuthenticationContext {
   readonly namespace: string;
   readonly path?: string;
   readonly request?: Request;
+  /**
+   * The application's services, for a token check that needs them
+   * (`services.resolve(AuthTokens)`). Set by `runApp({ websocket })`.
+   */
+  readonly services?: ServiceResolver;
 }
 
 export type WsAccessTokenAuthenticator = (

package/core/websocket/websocketModule.ts

@@ -35,8 +35,14 @@ export interface WebSocketModuleConfig {
   readonly allowQueryToken?: boolean;
   /** Default allowed origins when a gateway does not specify its own. */
   readonly cors?: { origins?: string[] };
-  /** Pluggable broadcast/session adapter (defaults to in-memory, single-node). */
-  readonly adapter?: WebSocketAdapter;
+  /**
+   * Broadcast/session adapter built from the application's services (the
+   * in-memory single-node adapter when absent). Several instances share rooms
+   * and sessions through Redis:
+   * `adapter: (services) => new RedisWebSocketAdapter(services.resolve(IRedis))`.
+   * Called when the HTTP server starts, after the infrastructure is connected.
+   */
+  readonly adapter?: (services: ServiceResolver) => WebSocketAdapter;
   /** Wire codec (defaults to JSON). */
   readonly codec?: PacketCodec;
   /** Default replay confirmation mode. A client can opt in with ?replay=client-ack. */
@@ -83,11 +89,12 @@ export function websocketModule(config: WebSocketModuleConfig): BazisModule {
         const logger = resolver.tryResolve(LOGGER);
         return new WebSocketServer({
           namespaces,
-          authenticator: config.authenticator ?? null,
+          // The token check gets the application's services, like the adapter.
+          authenticator: config.authenticator ? (token, context) => config.authenticator!(token, { ...context!, services: resolver }) : null,
           requireAuth: config.requireAuth ?? false,
           allowQueryToken: config.allowQueryToken ?? false,
           ...(config.cors?.origins ? { defaultCorsOrigins: config.cors.origins } : {}),
-          ...(config.adapter ? { adapter: config.adapter } : {}),
+          ...(config.adapter ? { adapter: buildAdapter(config.adapter, resolver) } : {}),
           ...(config.codec ? { codec: config.codec } : {}),
           ...(config.replayDelivery ? { replayDelivery: config.replayDelivery } : {}),
           ...(config.onDiagnostic ? { onDiagnostic: config.onDiagnostic } : {}),
@@ -114,3 +121,12 @@ export function websocketModule(config: WebSocketModuleConfig): BazisModule {
 
   return markGlobal(WebSocketModule);
 }
+
+function buildAdapter(factory: unknown, services: ServiceResolver): WebSocketAdapter {
+  if (typeof factory !== "function") {
+    throw new Error("websocket.adapter must be a function of the application services: adapter: (services) => new RedisWebSocketAdapter(services.resolve(IRedis)).");
+  }
+  const adapter = (factory as (services: ServiceResolver) => WebSocketAdapter)(services);
+  if (adapter === null || typeof adapter !== "object") throw new Error("websocket.adapter must return a WebSocket adapter.");
+  return adapter;
+}

package/package.json

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