@getstrata/bootstrap 2.0.3 → 2.0.4

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @getstrata/bootstrap changelog
 
+## 2.0.4
+
+- Place cache rollout guidance beside outbox docs without overlapping API additions
+
 ## 2.0.3
 
 - Persist transactional events with leased tenant-aware SQL outbox workers

package/dist/bootstrap/buildModuleRoutes.d.ts

@@ -1,10 +1,11 @@
+import type { OpenApiRouteMap } from "@getstrata/core/openapi/registeredRoute";
 import type { AppDependencies, AppModule, AppRouteMap } from "./contracts";
 interface BuildModuleRoutesOptions {
     apiPrefix?: string;
     modules?: AppModule[];
     clearRegistry?: boolean;
 }
-declare function registerOpenApiRouteMap(routes: Record<string, unknown>, middleware: string[]): Record<string, unknown>;
+declare function registerOpenApiRouteMap(routes: Record<string, unknown>, middleware: string[], metadata?: OpenApiRouteMap): Record<string, unknown>;
 declare function buildModuleRoutes(dependencies: AppDependencies, options?: BuildModuleRoutesOptions): AppRouteMap;
 export type { BuildModuleRoutesOptions };
 export { buildModuleRoutes, registerOpenApiRouteMap };

package/dist/bootstrap/contracts.d.ts

@@ -8,7 +8,10 @@ interface ModuleRouteContext {
     cachedJson: CachedJson;
     kernel: HttpKernel;
 }
+import type { OpenApiRouteMap } from "@getstrata/core/openapi/registeredRoute";
 interface AppModule {
+    /** Paths match this module's API route map before apiPrefix is applied. */
+    openApi?: OpenApiRouteMap;
     name: string;
     order?: number;
     tableName?: string;
@@ -18,4 +21,5 @@ interface AppModule {
     routes?(context: ModuleRouteContext): AppRouteMap;
     webRoutes?(context: ModuleRouteContext): AppRouteMap;
 }
+export type { OpenApiOperation, OpenApiRouteMap, OpenApiSchema, } from "@getstrata/core/openapi/registeredRoute";
 export type { AppModule, ModuleRouteContext };

package/dist/bootstrap/listeners/invalidateCacheOnModelWrite.d.ts

@@ -1,3 +1,12 @@
 import { type EventBus } from "@getstrata/core/events";
-declare function registerInvalidateCacheOnModelWriteListeners(bus?: EventBus): void;
-export { registerInvalidateCacheOnModelWriteListeners };
+import type { DurableListener, SqlOutbox } from "@getstrata/core/events/outbox";
+import type { CacheLike } from "../../types/services";
+interface ModelCacheInvalidationOptions {
+    outbox?: SqlOutbox;
+}
+/** Include in the application's one outbox registry; never dispatch through Redis queues. */
+declare function createModelCacheInvalidationListener(resolveCache?: () => CacheLike): DurableListener;
+/** Durable mode requires the outbox schema and an explicit business transaction. */
+declare function registerInvalidateCacheOnModelWriteListeners(bus?: EventBus, options?: ModelCacheInvalidationOptions): () => void;
+export type { ModelCacheInvalidationOptions };
+export { createModelCacheInvalidationListener, registerInvalidateCacheOnModelWriteListeners };

package/dist/entries/buildModuleRoutes.js

@@ -428,22 +428,22 @@ function readSharedRouteRegistry() {
 var routeRegistry = readSharedRouteRegistry();
 
 // ../../src/bootstrap/buildModuleRoutes.ts
-function registerOpenApiRoute(method, path, middleware) {
-  routeRegistry.register({ method, path, middleware });
+function registerOpenApiRoute(method, path, middleware, openApi) {
+  routeRegistry.register({ method, path, middleware, ...openApi ? { openApi } : {} });
 }
-function registerOpenApiRouteMap(routes, middleware) {
+function registerOpenApiRouteMap(routes, middleware, metadata = {}) {
   const registered = {};
   for (const [path, handler] of Object.entries(routes)) {
     if (handler && typeof handler === "object" && !Array.isArray(handler)) {
       const methodMap = handler;
       registered[path] = methodMap;
       for (const method of Object.keys(methodMap)) {
-        registerOpenApiRoute(method.toUpperCase(), path, middleware);
+        registerOpenApiRoute(method.toUpperCase(), path, middleware, metadata[path]?.[method.toUpperCase()]);
       }
       continue;
     }
     registered[path] = handler;
-    registerOpenApiRoute("GET", path, middleware);
+    registerOpenApiRoute("GET", path, middleware, metadata[path]?.GET);
   }
   return registered;
 }
@@ -462,14 +462,29 @@ function buildModuleRoutes(dependencies, options = {}) {
   const middleware = [...kernel.globalMiddleware(), ...kernel.group("api")];
   const cachedJson = createCachedJson(dependencies);
   const moduleRoutes = {};
+  const metadata = {};
   for (const module of modules) {
     if (!module.routes) {
       continue;
     }
-    Object.assign(moduleRoutes, module.routes({ dependencies, cachedJson, kernel }));
+    const routes = module.routes({ dependencies, cachedJson, kernel });
+    for (const [path, operations] of Object.entries(module.openApi ?? {})) {
+      if (!(path in routes))
+        throw new Error(`OpenAPI metadata has no API route: ${module.name} ${path}`);
+      const methods = typeof routes[path] === "function" ? ["GET"] : Object.keys(routes[path]).map((method) => method.toUpperCase());
+      for (const method of Object.keys(operations))
+        if (!methods.includes(method))
+          throw new Error(`OpenAPI metadata has no API handler: ${method} ${path}`);
+    }
+    for (const path of Object.keys(routes)) {
+      delete metadata[path];
+      if (module.openApi?.[path])
+        metadata[path] = module.openApi[path];
+    }
+    Object.assign(moduleRoutes, routes);
   }
   const prefixedModuleRoutes = prefixRouteMap(apiPrefix, moduleRoutes);
-  return applyMiddlewareToRoutes(registerOpenApiRouteMap(prefixedModuleRoutes, ["global", "api"]), middleware);
+  return applyMiddlewareToRoutes(registerOpenApiRouteMap(prefixedModuleRoutes, ["global", "api"], prefixRouteMap(apiPrefix, metadata)), middleware);
 }
 export {
   buildModuleRoutes,

package/dist/entries/buildWebModuleRoutes.js

@@ -431,22 +431,22 @@ function readSharedRouteRegistry() {
 var routeRegistry = readSharedRouteRegistry();
 
 // ../../src/bootstrap/buildModuleRoutes.ts
-function registerOpenApiRoute(method, path, middleware) {
-  routeRegistry.register({ method, path, middleware });
+function registerOpenApiRoute(method, path, middleware, openApi) {
+  routeRegistry.register({ method, path, middleware, ...openApi ? { openApi } : {} });
 }
-function registerOpenApiRouteMap(routes, middleware) {
+function registerOpenApiRouteMap(routes, middleware, metadata = {}) {
   const registered = {};
   for (const [path, handler] of Object.entries(routes)) {
     if (handler && typeof handler === "object" && !Array.isArray(handler)) {
       const methodMap = handler;
       registered[path] = methodMap;
       for (const method of Object.keys(methodMap)) {
-        registerOpenApiRoute(method.toUpperCase(), path, middleware);
+        registerOpenApiRoute(method.toUpperCase(), path, middleware, metadata[path]?.[method.toUpperCase()]);
       }
       continue;
     }
     registered[path] = handler;
-    registerOpenApiRoute("GET", path, middleware);
+    registerOpenApiRoute("GET", path, middleware, metadata[path]?.GET);
   }
   return registered;
 }
@@ -465,14 +465,29 @@ function buildModuleRoutes(dependencies, options = {}) {
   const middleware = [...kernel.globalMiddleware(), ...kernel.group("api")];
   const cachedJson = createCachedJson(dependencies);
   const moduleRoutes = {};
+  const metadata = {};
   for (const module of modules) {
     if (!module.routes) {
       continue;
     }
-    Object.assign(moduleRoutes, module.routes({ dependencies, cachedJson, kernel }));
+    const routes = module.routes({ dependencies, cachedJson, kernel });
+    for (const [path, operations] of Object.entries(module.openApi ?? {})) {
+      if (!(path in routes))
+        throw new Error(`OpenAPI metadata has no API route: ${module.name} ${path}`);
+      const methods = typeof routes[path] === "function" ? ["GET"] : Object.keys(routes[path]).map((method) => method.toUpperCase());
+      for (const method of Object.keys(operations))
+        if (!methods.includes(method))
+          throw new Error(`OpenAPI metadata has no API handler: ${method} ${path}`);
+    }
+    for (const path of Object.keys(routes)) {
+      delete metadata[path];
+      if (module.openApi?.[path])
+        metadata[path] = module.openApi[path];
+    }
+    Object.assign(moduleRoutes, routes);
   }
   const prefixedModuleRoutes = prefixRouteMap(apiPrefix, moduleRoutes);
-  return applyMiddlewareToRoutes(registerOpenApiRouteMap(prefixedModuleRoutes, ["global", "api"]), middleware);
+  return applyMiddlewareToRoutes(registerOpenApiRouteMap(prefixedModuleRoutes, ["global", "api"], prefixRouteMap(apiPrefix, metadata)), middleware);
 }
 
 // ../../src/bootstrap/buildWebModuleRoutes.ts

package/dist/entries/context.js

@@ -437,14 +437,88 @@ function discoverModelTableNames() {
 
 // ../../src/bootstrap/listeners/invalidateCacheOnModelWrite.ts
 var MODEL_WRITE_ACTIONS = ["created", "updated", "deleted", "restored", "force-deleted"];
-function registerInvalidateCacheOnModelWriteListeners(bus = eventBus2) {
-  for (const tableName of discoverModelTableNames()) {
-    for (const action of MODEL_WRITE_ACTIONS) {
-      bus.listen(modelEventName(tableName, action), async () => {
+var CACHE_EVENT = "strata.cache.invalidate-tags";
+var STATE_KEY = Symbol.for("@getstrata/modelCacheInvalidationRegistrations");
+function registrations() {
+  const global = globalThis;
+  global[STATE_KEY] ??= new WeakMap;
+  return global[STATE_KEY];
+}
+function requireCacheTags(value) {
+  if (!Array.isArray(value) || !value.length || value.length > 128 || !value.every((tag) => typeof tag === "string" && tag.length > 0 && tag.length <= 256))
+    throw new Error("Invalid durable cache invalidation payload.");
+  return value;
+}
+function createModelCacheInvalidationListener(resolveCache = resolveApplicationCache) {
+  return {
+    name: "strata.cache.invalidate-tags.v1",
+    event: CACHE_EVENT,
+    async handle(event, { signal }) {
+      const payload = event.payload;
+      if (event.version !== 1)
+        throw new Error("Invalid durable cache invalidation version.");
+      const tags = requireCacheTags(payload?.tags);
+      signal.throwIfAborted();
+      await new InvalidateCacheTagsJob(resolveCache()).handle({ tags });
+      signal.throwIfAborted();
+    }
+  };
+}
+function registerInvalidateCacheOnModelWriteListeners(bus = eventBus2, options = {}) {
+  if (options.outbox && !options.outbox.hasListener("strata.cache.invalidate-tags.v1", CACHE_EVENT))
+    throw new Error("The application outbox must include createModelCacheInvalidationListener().");
+  const writes = discoverModelTableNames().flatMap((tableName) => MODEL_WRITE_ACTIONS.map((action) => ({
+    tableName,
+    action,
+    tags: cacheTagsForModelWrite(tableName, action)
+  })));
+  if (options.outbox) {
+    for (const write of writes)
+      if (write.tags.length)
+        requireCacheTags(write.tags);
+  }
+  const state = registrations();
+  const previous = state.get(bus);
+  if (previous?.durable && !options.outbox)
+    return () => {};
+  previous?.suspend();
+  const unsubscribe = [];
+  const subscribe = [];
+  const registration = {
+    durable: !!options.outbox,
+    suspend() {
+      for (const stop of unsubscribe.splice(0))
+        stop();
+    },
+    resume() {
+      for (const start of subscribe)
+        unsubscribe.push(start());
+      state.set(bus, registration);
+    },
+    dispose() {
+      if (state.get(bus) !== registration)
+        return;
+      registration.suspend();
+      if (previous)
+        previous.resume();
+      else
+        state.delete(bus);
+    }
+  };
+  for (const { tableName, action, tags: durableTags } of writes) {
+    const event = modelEventName(tableName, action);
+    if (options.outbox) {
+      if (!durableTags.length)
+        continue;
+      const outbox = options.outbox;
+      subscribe.push(() => bus.listenTransactional(event, async () => {
+        await outbox.publish(CACHE_EVENT, { tags: durableTags });
+      }));
+    } else {
+      subscribe.push(() => bus.listen(event, async () => {
         const tags = cacheTagsForModelWrite(tableName, action);
-        if (tags.length === 0) {
+        if (!tags.length)
           return;
-        }
         let cache;
         let queue;
         try {
@@ -455,9 +529,11 @@ function registerInvalidateCacheOnModelWriteListeners(bus = eventBus2) {
         }
         const job = createTrackedJob("cache.invalidate-tags", new InvalidateCacheTagsJob(cache));
         await queue.dispatch(job, { tags });
-      });
+      }));
     }
   }
+  registration.resume();
+  return registration.dispose;
 }
 
 // ../../src/bootstrap/providers/listeners.ts

package/dist/entries/createWebRoutes.js

@@ -437,22 +437,22 @@ function readSharedRouteRegistry() {
 var routeRegistry = readSharedRouteRegistry();
 
 // ../../src/bootstrap/buildModuleRoutes.ts
-function registerOpenApiRoute(method, path, middleware) {
-  routeRegistry.register({ method, path, middleware });
+function registerOpenApiRoute(method, path, middleware, openApi) {
+  routeRegistry.register({ method, path, middleware, ...openApi ? { openApi } : {} });
 }
-function registerOpenApiRouteMap(routes, middleware) {
+function registerOpenApiRouteMap(routes, middleware, metadata = {}) {
   const registered = {};
   for (const [path, handler] of Object.entries(routes)) {
     if (handler && typeof handler === "object" && !Array.isArray(handler)) {
       const methodMap = handler;
       registered[path] = methodMap;
       for (const method of Object.keys(methodMap)) {
-        registerOpenApiRoute(method.toUpperCase(), path, middleware);
+        registerOpenApiRoute(method.toUpperCase(), path, middleware, metadata[path]?.[method.toUpperCase()]);
       }
       continue;
     }
     registered[path] = handler;
-    registerOpenApiRoute("GET", path, middleware);
+    registerOpenApiRoute("GET", path, middleware, metadata[path]?.GET);
   }
   return registered;
 }
@@ -471,14 +471,29 @@ function buildModuleRoutes(dependencies, options = {}) {
   const middleware = [...kernel.globalMiddleware(), ...kernel.group("api")];
   const cachedJson = createCachedJson(dependencies);
   const moduleRoutes = {};
+  const metadata = {};
   for (const module of modules) {
     if (!module.routes) {
       continue;
     }
-    Object.assign(moduleRoutes, module.routes({ dependencies, cachedJson, kernel }));
+    const routes = module.routes({ dependencies, cachedJson, kernel });
+    for (const [path, operations] of Object.entries(module.openApi ?? {})) {
+      if (!(path in routes))
+        throw new Error(`OpenAPI metadata has no API route: ${module.name} ${path}`);
+      const methods = typeof routes[path] === "function" ? ["GET"] : Object.keys(routes[path]).map((method) => method.toUpperCase());
+      for (const method of Object.keys(operations))
+        if (!methods.includes(method))
+          throw new Error(`OpenAPI metadata has no API handler: ${method} ${path}`);
+    }
+    for (const path of Object.keys(routes)) {
+      delete metadata[path];
+      if (module.openApi?.[path])
+        metadata[path] = module.openApi[path];
+    }
+    Object.assign(moduleRoutes, routes);
   }
   const prefixedModuleRoutes = prefixRouteMap(apiPrefix, moduleRoutes);
-  return applyMiddlewareToRoutes(registerOpenApiRouteMap(prefixedModuleRoutes, ["global", "api"]), middleware);
+  return applyMiddlewareToRoutes(registerOpenApiRouteMap(prefixedModuleRoutes, ["global", "api"], prefixRouteMap(apiPrefix, metadata)), middleware);
 }
 
 // ../../src/bootstrap/buildWebModuleRoutes.ts

package/dist/entries/dependencies.js

@@ -437,14 +437,88 @@ function discoverModelTableNames() {
 
 // ../../src/bootstrap/listeners/invalidateCacheOnModelWrite.ts
 var MODEL_WRITE_ACTIONS = ["created", "updated", "deleted", "restored", "force-deleted"];
-function registerInvalidateCacheOnModelWriteListeners(bus = eventBus2) {
-  for (const tableName of discoverModelTableNames()) {
-    for (const action of MODEL_WRITE_ACTIONS) {
-      bus.listen(modelEventName(tableName, action), async () => {
+var CACHE_EVENT = "strata.cache.invalidate-tags";
+var STATE_KEY = Symbol.for("@getstrata/modelCacheInvalidationRegistrations");
+function registrations() {
+  const global = globalThis;
+  global[STATE_KEY] ??= new WeakMap;
+  return global[STATE_KEY];
+}
+function requireCacheTags(value) {
+  if (!Array.isArray(value) || !value.length || value.length > 128 || !value.every((tag) => typeof tag === "string" && tag.length > 0 && tag.length <= 256))
+    throw new Error("Invalid durable cache invalidation payload.");
+  return value;
+}
+function createModelCacheInvalidationListener(resolveCache = resolveApplicationCache) {
+  return {
+    name: "strata.cache.invalidate-tags.v1",
+    event: CACHE_EVENT,
+    async handle(event, { signal }) {
+      const payload = event.payload;
+      if (event.version !== 1)
+        throw new Error("Invalid durable cache invalidation version.");
+      const tags = requireCacheTags(payload?.tags);
+      signal.throwIfAborted();
+      await new InvalidateCacheTagsJob(resolveCache()).handle({ tags });
+      signal.throwIfAborted();
+    }
+  };
+}
+function registerInvalidateCacheOnModelWriteListeners(bus = eventBus2, options = {}) {
+  if (options.outbox && !options.outbox.hasListener("strata.cache.invalidate-tags.v1", CACHE_EVENT))
+    throw new Error("The application outbox must include createModelCacheInvalidationListener().");
+  const writes = discoverModelTableNames().flatMap((tableName) => MODEL_WRITE_ACTIONS.map((action) => ({
+    tableName,
+    action,
+    tags: cacheTagsForModelWrite(tableName, action)
+  })));
+  if (options.outbox) {
+    for (const write of writes)
+      if (write.tags.length)
+        requireCacheTags(write.tags);
+  }
+  const state = registrations();
+  const previous = state.get(bus);
+  if (previous?.durable && !options.outbox)
+    return () => {};
+  previous?.suspend();
+  const unsubscribe = [];
+  const subscribe = [];
+  const registration = {
+    durable: !!options.outbox,
+    suspend() {
+      for (const stop of unsubscribe.splice(0))
+        stop();
+    },
+    resume() {
+      for (const start of subscribe)
+        unsubscribe.push(start());
+      state.set(bus, registration);
+    },
+    dispose() {
+      if (state.get(bus) !== registration)
+        return;
+      registration.suspend();
+      if (previous)
+        previous.resume();
+      else
+        state.delete(bus);
+    }
+  };
+  for (const { tableName, action, tags: durableTags } of writes) {
+    const event = modelEventName(tableName, action);
+    if (options.outbox) {
+      if (!durableTags.length)
+        continue;
+      const outbox = options.outbox;
+      subscribe.push(() => bus.listenTransactional(event, async () => {
+        await outbox.publish(CACHE_EVENT, { tags: durableTags });
+      }));
+    } else {
+      subscribe.push(() => bus.listen(event, async () => {
         const tags = cacheTagsForModelWrite(tableName, action);
-        if (tags.length === 0) {
+        if (!tags.length)
           return;
-        }
         let cache;
         let queue;
         try {
@@ -455,9 +529,11 @@ function registerInvalidateCacheOnModelWriteListeners(bus = eventBus2) {
         }
         const job = createTrackedJob("cache.invalidate-tags", new InvalidateCacheTagsJob(cache));
         await queue.dispatch(job, { tags });
-      });
+      }));
     }
   }
+  registration.resume();
+  return registration.dispose;
 }
 
 // ../../src/bootstrap/providers/listeners.ts

package/dist/entries/listeners/invalidateCacheOnModelWrite.js

@@ -102,14 +102,88 @@ function discoverModelTableNames() {
 
 // ../../src/bootstrap/listeners/invalidateCacheOnModelWrite.ts
 var MODEL_WRITE_ACTIONS = ["created", "updated", "deleted", "restored", "force-deleted"];
-function registerInvalidateCacheOnModelWriteListeners(bus = eventBus) {
-  for (const tableName of discoverModelTableNames()) {
-    for (const action of MODEL_WRITE_ACTIONS) {
-      bus.listen(modelEventName(tableName, action), async () => {
+var CACHE_EVENT = "strata.cache.invalidate-tags";
+var STATE_KEY = Symbol.for("@getstrata/modelCacheInvalidationRegistrations");
+function registrations() {
+  const global = globalThis;
+  global[STATE_KEY] ??= new WeakMap;
+  return global[STATE_KEY];
+}
+function requireCacheTags(value) {
+  if (!Array.isArray(value) || !value.length || value.length > 128 || !value.every((tag) => typeof tag === "string" && tag.length > 0 && tag.length <= 256))
+    throw new Error("Invalid durable cache invalidation payload.");
+  return value;
+}
+function createModelCacheInvalidationListener(resolveCache = resolveApplicationCache) {
+  return {
+    name: "strata.cache.invalidate-tags.v1",
+    event: CACHE_EVENT,
+    async handle(event, { signal }) {
+      const payload = event.payload;
+      if (event.version !== 1)
+        throw new Error("Invalid durable cache invalidation version.");
+      const tags = requireCacheTags(payload?.tags);
+      signal.throwIfAborted();
+      await new InvalidateCacheTagsJob(resolveCache()).handle({ tags });
+      signal.throwIfAborted();
+    }
+  };
+}
+function registerInvalidateCacheOnModelWriteListeners(bus = eventBus, options = {}) {
+  if (options.outbox && !options.outbox.hasListener("strata.cache.invalidate-tags.v1", CACHE_EVENT))
+    throw new Error("The application outbox must include createModelCacheInvalidationListener().");
+  const writes = discoverModelTableNames().flatMap((tableName) => MODEL_WRITE_ACTIONS.map((action) => ({
+    tableName,
+    action,
+    tags: cacheTagsForModelWrite(tableName, action)
+  })));
+  if (options.outbox) {
+    for (const write of writes)
+      if (write.tags.length)
+        requireCacheTags(write.tags);
+  }
+  const state = registrations();
+  const previous = state.get(bus);
+  if (previous?.durable && !options.outbox)
+    return () => {};
+  previous?.suspend();
+  const unsubscribe = [];
+  const subscribe = [];
+  const registration = {
+    durable: !!options.outbox,
+    suspend() {
+      for (const stop of unsubscribe.splice(0))
+        stop();
+    },
+    resume() {
+      for (const start of subscribe)
+        unsubscribe.push(start());
+      state.set(bus, registration);
+    },
+    dispose() {
+      if (state.get(bus) !== registration)
+        return;
+      registration.suspend();
+      if (previous)
+        previous.resume();
+      else
+        state.delete(bus);
+    }
+  };
+  for (const { tableName, action, tags: durableTags } of writes) {
+    const event = modelEventName(tableName, action);
+    if (options.outbox) {
+      if (!durableTags.length)
+        continue;
+      const outbox = options.outbox;
+      subscribe.push(() => bus.listenTransactional(event, async () => {
+        await outbox.publish(CACHE_EVENT, { tags: durableTags });
+      }));
+    } else {
+      subscribe.push(() => bus.listen(event, async () => {
         const tags = cacheTagsForModelWrite(tableName, action);
-        if (tags.length === 0) {
+        if (!tags.length)
           return;
-        }
         let cache;
         let queue;
         try {
@@ -120,10 +194,13 @@ function registerInvalidateCacheOnModelWriteListeners(bus = eventBus) {
         }
         const job = createTrackedJob("cache.invalidate-tags", new InvalidateCacheTagsJob(cache));
         await queue.dispatch(job, { tags });
-      });
+      }));
     }
   }
+  registration.resume();
+  return registration.dispose;
 }
 export {
+  createModelCacheInvalidationListener,
   registerInvalidateCacheOnModelWriteListeners
 };

package/dist/entries/providers.js

@@ -427,14 +427,88 @@ function discoverModelTableNames() {
 
 // ../../src/bootstrap/listeners/invalidateCacheOnModelWrite.ts
 var MODEL_WRITE_ACTIONS = ["created", "updated", "deleted", "restored", "force-deleted"];
-function registerInvalidateCacheOnModelWriteListeners(bus = eventBus2) {
-  for (const tableName of discoverModelTableNames()) {
-    for (const action of MODEL_WRITE_ACTIONS) {
-      bus.listen(modelEventName(tableName, action), async () => {
+var CACHE_EVENT = "strata.cache.invalidate-tags";
+var STATE_KEY = Symbol.for("@getstrata/modelCacheInvalidationRegistrations");
+function registrations() {
+  const global = globalThis;
+  global[STATE_KEY] ??= new WeakMap;
+  return global[STATE_KEY];
+}
+function requireCacheTags(value) {
+  if (!Array.isArray(value) || !value.length || value.length > 128 || !value.every((tag) => typeof tag === "string" && tag.length > 0 && tag.length <= 256))
+    throw new Error("Invalid durable cache invalidation payload.");
+  return value;
+}
+function createModelCacheInvalidationListener(resolveCache = resolveApplicationCache) {
+  return {
+    name: "strata.cache.invalidate-tags.v1",
+    event: CACHE_EVENT,
+    async handle(event, { signal }) {
+      const payload = event.payload;
+      if (event.version !== 1)
+        throw new Error("Invalid durable cache invalidation version.");
+      const tags = requireCacheTags(payload?.tags);
+      signal.throwIfAborted();
+      await new InvalidateCacheTagsJob(resolveCache()).handle({ tags });
+      signal.throwIfAborted();
+    }
+  };
+}
+function registerInvalidateCacheOnModelWriteListeners(bus = eventBus2, options = {}) {
+  if (options.outbox && !options.outbox.hasListener("strata.cache.invalidate-tags.v1", CACHE_EVENT))
+    throw new Error("The application outbox must include createModelCacheInvalidationListener().");
+  const writes = discoverModelTableNames().flatMap((tableName) => MODEL_WRITE_ACTIONS.map((action) => ({
+    tableName,
+    action,
+    tags: cacheTagsForModelWrite(tableName, action)
+  })));
+  if (options.outbox) {
+    for (const write of writes)
+      if (write.tags.length)
+        requireCacheTags(write.tags);
+  }
+  const state = registrations();
+  const previous = state.get(bus);
+  if (previous?.durable && !options.outbox)
+    return () => {};
+  previous?.suspend();
+  const unsubscribe = [];
+  const subscribe = [];
+  const registration = {
+    durable: !!options.outbox,
+    suspend() {
+      for (const stop of unsubscribe.splice(0))
+        stop();
+    },
+    resume() {
+      for (const start of subscribe)
+        unsubscribe.push(start());
+      state.set(bus, registration);
+    },
+    dispose() {
+      if (state.get(bus) !== registration)
+        return;
+      registration.suspend();
+      if (previous)
+        previous.resume();
+      else
+        state.delete(bus);
+    }
+  };
+  for (const { tableName, action, tags: durableTags } of writes) {
+    const event = modelEventName(tableName, action);
+    if (options.outbox) {
+      if (!durableTags.length)
+        continue;
+      const outbox = options.outbox;
+      subscribe.push(() => bus.listenTransactional(event, async () => {
+        await outbox.publish(CACHE_EVENT, { tags: durableTags });
+      }));
+    } else {
+      subscribe.push(() => bus.listen(event, async () => {
         const tags = cacheTagsForModelWrite(tableName, action);
-        if (tags.length === 0) {
+        if (!tags.length)
           return;
-        }
         let cache;
         let queue;
         try {
@@ -445,9 +519,11 @@ function registerInvalidateCacheOnModelWriteListeners(bus = eventBus2) {
         }
         const job = createTrackedJob("cache.invalidate-tags", new InvalidateCacheTagsJob(cache));
         await queue.dispatch(job, { tags });
-      });
+      }));
     }
   }
+  registration.resume();
+  return registration.dispose;
 }
 
 // ../../src/bootstrap/providers/listeners.ts

package/dist/index.js

@@ -436,22 +436,22 @@ function readSharedRouteRegistry() {
 var routeRegistry = readSharedRouteRegistry();
 
 // ../../src/bootstrap/buildModuleRoutes.ts
-function registerOpenApiRoute(method, path, middleware) {
-  routeRegistry.register({ method, path, middleware });
+function registerOpenApiRoute(method, path, middleware, openApi) {
+  routeRegistry.register({ method, path, middleware, ...openApi ? { openApi } : {} });
 }
-function registerOpenApiRouteMap(routes, middleware) {
+function registerOpenApiRouteMap(routes, middleware, metadata = {}) {
   const registered = {};
   for (const [path, handler] of Object.entries(routes)) {
     if (handler && typeof handler === "object" && !Array.isArray(handler)) {
       const methodMap = handler;
       registered[path] = methodMap;
       for (const method of Object.keys(methodMap)) {
-        registerOpenApiRoute(method.toUpperCase(), path, middleware);
+        registerOpenApiRoute(method.toUpperCase(), path, middleware, metadata[path]?.[method.toUpperCase()]);
       }
       continue;
     }
     registered[path] = handler;
-    registerOpenApiRoute("GET", path, middleware);
+    registerOpenApiRoute("GET", path, middleware, metadata[path]?.GET);
   }
   return registered;
 }
@@ -470,14 +470,29 @@ function buildModuleRoutes(dependencies, options = {}) {
   const middleware = [...kernel.globalMiddleware(), ...kernel.group("api")];
   const cachedJson = createCachedJson(dependencies);
   const moduleRoutes = {};
+  const metadata = {};
   for (const module of modules) {
     if (!module.routes) {
       continue;
     }
-    Object.assign(moduleRoutes, module.routes({ dependencies, cachedJson, kernel }));
+    const routes = module.routes({ dependencies, cachedJson, kernel });
+    for (const [path, operations] of Object.entries(module.openApi ?? {})) {
+      if (!(path in routes))
+        throw new Error(`OpenAPI metadata has no API route: ${module.name} ${path}`);
+      const methods = typeof routes[path] === "function" ? ["GET"] : Object.keys(routes[path]).map((method) => method.toUpperCase());
+      for (const method of Object.keys(operations))
+        if (!methods.includes(method))
+          throw new Error(`OpenAPI metadata has no API handler: ${method} ${path}`);
+    }
+    for (const path of Object.keys(routes)) {
+      delete metadata[path];
+      if (module.openApi?.[path])
+        metadata[path] = module.openApi[path];
+    }
+    Object.assign(moduleRoutes, routes);
   }
   const prefixedModuleRoutes = prefixRouteMap(apiPrefix, moduleRoutes);
-  return applyMiddlewareToRoutes(registerOpenApiRouteMap(prefixedModuleRoutes, ["global", "api"]), middleware);
+  return applyMiddlewareToRoutes(registerOpenApiRouteMap(prefixedModuleRoutes, ["global", "api"], prefixRouteMap(apiPrefix, metadata)), middleware);
 }
 // ../../src/bootstrap/buildWebModuleRoutes.ts
 import { applyMiddlewareToRoutes as applyMiddlewareToRoutes2 } from "@getstrata/core/http/middleware";
@@ -823,14 +838,73 @@ import { eventBus as eventBus2, modelEventName } from "@getstrata/core/events";
 import { InvalidateCacheTagsJob } from "@getstrata/core/jobs/invalidateCacheTagsJob";
 import { createTrackedJob } from "@getstrata/core/queue/createAppQueue";
 var MODEL_WRITE_ACTIONS = ["created", "updated", "deleted", "restored", "force-deleted"];
-function registerInvalidateCacheOnModelWriteListeners(bus = eventBus2) {
-  for (const tableName of discoverModelTableNames()) {
-    for (const action of MODEL_WRITE_ACTIONS) {
-      bus.listen(modelEventName(tableName, action), async () => {
+var CACHE_EVENT = "strata.cache.invalidate-tags";
+var STATE_KEY = Symbol.for("@getstrata/modelCacheInvalidationRegistrations");
+function registrations() {
+  const global = globalThis;
+  global[STATE_KEY] ??= new WeakMap;
+  return global[STATE_KEY];
+}
+function requireCacheTags(value) {
+  if (!Array.isArray(value) || !value.length || value.length > 128 || !value.every((tag) => typeof tag === "string" && tag.length > 0 && tag.length <= 256))
+    throw new Error("Invalid durable cache invalidation payload.");
+  return value;
+}
+function registerInvalidateCacheOnModelWriteListeners(bus = eventBus2, options = {}) {
+  if (options.outbox && !options.outbox.hasListener("strata.cache.invalidate-tags.v1", CACHE_EVENT))
+    throw new Error("The application outbox must include createModelCacheInvalidationListener().");
+  const writes = discoverModelTableNames().flatMap((tableName) => MODEL_WRITE_ACTIONS.map((action) => ({
+    tableName,
+    action,
+    tags: cacheTagsForModelWrite(tableName, action)
+  })));
+  if (options.outbox) {
+    for (const write of writes)
+      if (write.tags.length)
+        requireCacheTags(write.tags);
+  }
+  const state = registrations();
+  const previous = state.get(bus);
+  if (previous?.durable && !options.outbox)
+    return () => {};
+  previous?.suspend();
+  const unsubscribe = [];
+  const subscribe = [];
+  const registration = {
+    durable: !!options.outbox,
+    suspend() {
+      for (const stop of unsubscribe.splice(0))
+        stop();
+    },
+    resume() {
+      for (const start of subscribe)
+        unsubscribe.push(start());
+      state.set(bus, registration);
+    },
+    dispose() {
+      if (state.get(bus) !== registration)
+        return;
+      registration.suspend();
+      if (previous)
+        previous.resume();
+      else
+        state.delete(bus);
+    }
+  };
+  for (const { tableName, action, tags: durableTags } of writes) {
+    const event = modelEventName(tableName, action);
+    if (options.outbox) {
+      if (!durableTags.length)
+        continue;
+      const outbox = options.outbox;
+      subscribe.push(() => bus.listenTransactional(event, async () => {
+        await outbox.publish(CACHE_EVENT, { tags: durableTags });
+      }));
+    } else {
+      subscribe.push(() => bus.listen(event, async () => {
         const tags = cacheTagsForModelWrite(tableName, action);
-        if (tags.length === 0) {
+        if (!tags.length)
           return;
-        }
         let cache;
         let queue;
         try {
@@ -841,9 +915,11 @@ function registerInvalidateCacheOnModelWriteListeners(bus = eventBus2) {
         }
         const job = createTrackedJob("cache.invalidate-tags", new InvalidateCacheTagsJob(cache));
         await queue.dispatch(job, { tags });
-      });
+      }));
     }
   }
+  registration.resume();
+  return registration.dispose;
 }
 
 // ../../src/bootstrap/providers/listeners.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getstrata/bootstrap",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Strata application bootstrap: HttpKernel, DI, web session helpers",
   "type": "module",
   "license": "MIT",
@@ -185,7 +185,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@getstrata/core": "^2.0.3",
+    "@getstrata/core": "^2.0.4",
     "typescript": "^5.9.0 || ^6.0.0 || ^7.0.0"
   },
   "engines": {