feat(agent-bff): let a host drop what was read from the SaaS

packages/agent-bff/src/build-bff.ts

@@ -68,6 +68,11 @@ export interface BuildBffOptions {
 
 export interface Bff {
   callback: BffCallback;
+  /**
+   * Forget what was read from the SaaS. A host that knows the schema just moved — an agent
+   * restarting on a customization refresh — calls this instead of waiting out the 24h TTL.
+   */
+  invalidate(): void;
 }
 
 const SESSION_TTL_SECONDS = 24 * 60 * 60;
@@ -318,6 +323,7 @@ function buildAgentRouteMiddlewares(
   bundle: ReadModelBundle | undefined,
   config: BFFConfig,
   logger: Logger,
+  permissionsCache: PermissionsCache,
 ): Middleware[] {
   if (!bundle) {
     logger(
@@ -337,7 +343,7 @@ function buildAgentRouteMiddlewares(
       forestServerUrl: apiKeyConfig.forestServerUrl,
       envSecret: apiKeyConfig.forestEnvSecret,
     }),
-    cache: new PermissionsCache(),
+    cache: permissionsCache,
     logger,
   });
 
@@ -381,26 +387,32 @@ function buildAiMiddlewares(config: BFFConfig, oauth: OAuthEdge, logger: Logger)
   ];
 }
 
+interface AgentEdge {
+  middlewares: Middleware[];
+  invalidate(): void;
+}
+
 function buildAgentMiddlewares(
   config: BFFConfig,
   logger: Logger,
   oauth: OAuthEdge,
   aiMiddlewares: Middleware[],
   basePath: string,
-): Middleware[] {
+): AgentEdge {
   const { forestAuthSecret, defaultTimezone } = config;
 
   if (!forestAuthSecret) {
     logger('Warn', 'Agent edge disabled: FOREST_AUTH_SECRET is missing');
 
-    return [];
+    return { middlewares: [], invalidate: () => undefined };
   }
 
   const apiKeyStep = buildApiKeyMiddleware(config, logger) ?? createApiKeyUnavailableGuard(logger);
   // One store for the whole edge. The document only unfolds when the agent is reachable too: with no
   // AGENT_URL every data path answers 501, so concrete paths would advertise a dead surface.
   const bundle = resolveReadModelBundle(config, logger);
   const source = toUnfoldSource(bundle, config, logger);
+  const permissionsCache = new PermissionsCache();
 
   const chain: Middleware[] = [
     createAuthModeMiddleware({ authSecret: forestAuthSecret }),
@@ -430,10 +442,19 @@ function buildAgentMiddlewares(
       : []),
     ...aiMiddlewares,
     createTimezoneMiddleware({ defaultTimezone }),
-    ...buildAgentRouteMiddlewares(bundle, config, logger),
+    ...buildAgentRouteMiddlewares(bundle, config, logger, permissionsCache),
   ];
 
-  return chain.map(agentScoped);
+  return {
+    middlewares: chain.map(agentScoped),
+    invalidate: () => {
+      // The one trace an invalidation leaves: the operator asked "the schema is wrong" needs to
+      // establish that one happened and when, and the age gauge cannot say it.
+      logger('Info', 'Dropping the SaaS read caches on host request');
+      bundle?.store.invalidate();
+      permissionsCache.clear();
+    },
+  };
 }
 
 /**
@@ -462,7 +483,8 @@ export default async function buildBff({
 
   const oauth = buildOAuthMiddlewares(config, logger);
   const aiMiddlewares = buildAiMiddlewares(config, oauth, logger);
-  const agentMiddlewares = buildAgentMiddlewares(config, logger, oauth, aiMiddlewares, mountPath);
+  const agentEdge = buildAgentMiddlewares(config, logger, oauth, aiMiddlewares, mountPath);
+  const agentMiddlewares = agentEdge.middlewares;
   const hasAgentEdge = agentMiddlewares.length > 0;
   const agentErrorMiddleware = hasAgentEdge ? [agentScoped(createErrorMiddleware({ logger }))] : [];
   const agentJsonOnlyGuard = hasAgentEdge ? [agentScoped(createJsonOnlyGuard())] : [];
@@ -490,5 +512,5 @@ export default async function buildBff({
   const app = new Koa();
   for (const middleware of middlewares) app.use(middleware);
 
-  return { callback: app.callback() };
+  return { callback: app.callback(), invalidate: agentEdge.invalidate };
 }

packages/agent-bff/src/permissions/permissions-cache.ts

@@ -31,6 +31,7 @@ export default class PermissionsCache {
   private readonly ttlMs: number;
 
   private entry: CacheEntry | undefined;
+  private generationValue = 0;
 
   constructor({ now = Date.now, ttlMs = PERMISSIONS_CACHE_TTL_MS }: PermissionsCacheOptions = {}) {
     this.now = now;
@@ -49,7 +50,22 @@ export default class PermissionsCache {
     return this.getFreshEntry()?.permissions;
   }
 
-  set(permissions: EvaluatedPermissions): void {
+  /**
+   * The generation a fetch must be started against. Read it before the fetch and hand it back to
+   * `set`, so a response that crossed a `clear()` cannot become the shared entry.
+   */
+  get generation(): number {
+    return this.generationValue;
+  }
+
+  /**
+   * Store a fetched payload, unless a `clear()` landed while the fetch was in flight: it read the
+   * permissions the invalidation declared stale, and with a single shared entry one late write would
+   * hand a revoked access to every caller for a full TTL.
+   */
+  set(permissions: EvaluatedPermissions, generation: number): void {
+    if (generation !== this.generationValue) return;
+
     const previous = this.getFreshEntry();
     const carriesTheSameUsers =
       previous !== undefined && sameUsers(previous.permissions.users, permissions.users);
@@ -67,6 +83,7 @@ export default class PermissionsCache {
 
   clear(): void {
     this.entry = undefined;
+    this.generationValue += 1;
   }
 
   private getFreshEntry(): CacheEntry | undefined {

packages/agent-bff/src/permissions/permissions-routes-middleware.ts

@@ -70,6 +70,7 @@ async function resolvePermissions({
   logger: Logger;
 }): Promise<{ permissions: EvaluatedPermissions; fromFreshFetch: boolean }> {
   let resolved: EnvironmentAndUserPermissions;
+  const { generation } = cache;
 
   try {
     resolved = await client.fetchPermissions();
@@ -90,7 +91,7 @@ async function resolvePermissions({
     users: resolved.users,
   };
 
-  cache.set(permissions);
+  cache.set(permissions, generation);
 
   return { permissions, fromFreshFetch: true };
 }

packages/agent-bff/src/read-model/create-read-model.ts

@@ -32,7 +32,7 @@ export default function createReadModel({
   // Wrap once so a throwing metrics backend can never break business logic anywhere in the bundle.
   const resolvedMetrics = safeMetrics(metrics ?? createConsoleMetrics(logger));
   const fetcher = new ForestSchemaClient({ forestServerUrl, envSecret });
-  const schemaCache = new SchemaCache({ fetcher, metrics: resolvedMetrics, now });
+  const schemaCache = new SchemaCache({ fetcher, metrics: resolvedMetrics, logger, now });
   const capabilitiesCache = new CapabilitiesCache({ now });
   const store = new ReadModelStore(schemaCache, capabilitiesCache);
   const actionEndpointResolver = new ActionEndpointResolver(

packages/agent-bff/src/read-model/read-model-store.ts

@@ -34,6 +34,18 @@ export default class ReadModelStore {
     return (await this.getSchemaSnapshot()).readModel;
   }
 
+  /**
+   * Forget the cached schema and the capabilities that belong to it, then force the read-model to be
+   * rebuilt. The capabilities are dropped here rather than left to the next revision change: a
+   * `clear()` also drops a schema write that was in flight, and a dropped write moves nothing the
+   * snapshot can notice, so inferring the invalidation from the revision would miss it.
+   */
+  invalidate(): void {
+    this.schemaCache.clear();
+    this.capabilitiesCache.clear();
+    this.builtRevision = -1;
+  }
+
   async getSchemaSnapshot(): Promise<SchemaSnapshot> {
     const collections = await this.schemaCache.get();
     const { revision } = this.schemaCache;

packages/agent-bff/src/read-model/schema-cache.ts

@@ -1,24 +1,42 @@
 import type { SchemaFetcher } from './forest-schema-client';
+import type { Logger } from '../ports/logger-port';
 import type { Metrics } from '../ports/metrics-port';
 import type { ForestSchemaCollection } from '@forestadmin/forestadmin-client';
 
 import SchemaUnavailableError from './errors';
 
 export const ONE_DAY_MS = 24 * 60 * 60 * 1000;
 
+/**
+ * How long after a `clear()` the cache keeps re-reading the schema, and how often. An invalidation
+ * says "the agent just changed its schema", but the SaaS the BFF reads from may not have finished
+ * recording it: caching whatever comes back on the very next read would pin the old schema for a
+ * full day. Within this window a read costs one request every few seconds, which is nothing next to
+ * serving a collection the agent exposes and the BFF 404s.
+ */
+export const REVALIDATION_WINDOW_MS = 60 * 1000;
+export const REVALIDATION_TTL_MS = 5 * 1000;
+
 export const SCHEMA_CACHE_REFRESH_ERROR = 'schema_cache_refresh_error';
 export const SCHEMA_CACHE_AGE_SECONDS = 'schema_cache_age_seconds';
 
 export interface SchemaCacheOptions {
   fetcher: SchemaFetcher;
   metrics: Metrics;
+  logger?: Logger;
   now?: () => number;
   ttlMs?: number;
 }
 
 interface CacheEntry {
   collections: ForestSchemaCollection[];
   fetchedAt: number;
+  /**
+   * Decided when the entry is written, not when it is read: a read taken while the revalidation
+   * window was open cannot be trusted for a day, and must not be promoted to a long-lived entry the
+   * moment the window closes.
+   */
+  expiresAt: number;
 }
 
 /**
@@ -30,22 +48,32 @@ interface CacheEntry {
 export default class SchemaCache {
   private readonly fetcher: SchemaFetcher;
   private readonly metrics: Metrics;
+  private readonly logger: Logger;
   private readonly now: () => number;
   private readonly ttlMs: number;
 
   private entry: CacheEntry | null = null;
   private inFlight: Promise<ForestSchemaCollection[]> | null = null;
   private revisionValue = 0;
-
-  constructor({ fetcher, metrics, now = Date.now, ttlMs = ONE_DAY_MS }: SchemaCacheOptions) {
+  private generation = 0;
+  private revalidatingUntil = 0;
+
+  constructor({
+    fetcher,
+    metrics,
+    logger = () => undefined,
+    now = Date.now,
+    ttlMs = ONE_DAY_MS,
+  }: SchemaCacheOptions) {
     this.fetcher = fetcher;
     this.metrics = metrics;
+    this.logger = logger;
     this.now = now;
     this.ttlMs = ttlMs;
   }
 
   async get(): Promise<ForestSchemaCollection[]> {
-    if (this.entry && this.now() - this.entry.fetchedAt < this.ttlMs) {
+    if (this.entry && this.now() < this.entry.expiresAt) {
       this.emitAge();
 
       return this.entry.collections;
@@ -54,6 +82,23 @@ export default class SchemaCache {
     return this.refresh();
   }
 
+  /**
+   * Expire what is cached and re-read it eagerly for a while. Called when something outside knows
+   * the schema moved — an agent restarting on a customization refresh, say.
+   *
+   * The entry is expired, not dropped: every read now goes through a refresh, so nothing the host
+   * declared stale is served while the SaaS answers, but the class keeps its safety net — a refresh
+   * that fails still has a last good schema to fall back on. Dropping it would turn a restart
+   * during a SaaS blip into a `503 schema_unavailable` on every data route.
+   */
+  clear(): void {
+    this.generation += 1;
+    this.inFlight = null;
+    this.revalidatingUntil = this.now() + REVALIDATION_WINDOW_MS;
+
+    if (this.entry) this.entry = { ...this.entry, expiresAt: this.now() };
+  }
+
   ageSeconds(): number | undefined {
     if (!this.entry) return undefined;
 
@@ -66,15 +111,21 @@ export default class SchemaCache {
 
   private async refresh(): Promise<ForestSchemaCollection[]> {
     if (!this.inFlight) {
-      this.inFlight = this.doRefresh().finally(() => {
-        this.inFlight = null;
+      // Identity-guarded, because `clear()` detaches the in-flight fetch: a read that lands after an
+      // invalidation must start its own, not join the one that read the invalidated schema.
+      const pending: Promise<ForestSchemaCollection[]> = this.doRefresh().finally(() => {
+        if (this.inFlight === pending) this.inFlight = null;
       });
+
+      this.inFlight = pending;
     }
 
     return this.inFlight;
   }
 
   private async doRefresh(): Promise<ForestSchemaCollection[]> {
+    const { generation } = this;
+
     try {
       const collections = await this.fetcher.fetchSchema();
 
@@ -83,16 +134,29 @@ export default class SchemaCache {
       // failed fetch and fall through to the failure path below.
       if (collections.length === 0) throw new Error('Forest returned an empty schema');
 
-      this.entry = { collections, fetchedAt: this.now() };
-      this.revisionValue += 1;
-      this.emitAge();
+      // Skip the write if a clear() happened while this fetch was in flight: it read the schema the
+      // invalidation declared stale, and caching it now would undo the invalidation.
+      if (this.generation === generation) {
+        const fetchedAt = this.now();
+
+        this.entry = { collections, fetchedAt, expiresAt: fetchedAt + this.ttlFor(fetchedAt) };
+        this.revisionValue += 1;
+        this.emitAge();
+      }
 
       return collections;
     } catch (error) {
       this.metrics.increment(SCHEMA_CACHE_REFRESH_ERROR);
+      // The counter alone cannot tell "the SaaS returned an empty array" from "the SaaS is down"
+      // from "the env secret is wrong", and the cause is otherwise swallowed: it becomes the `cause`
+      // of a `SchemaUnavailableError` the error middleware serialises without logging.
+      this.logger('Warn', 'Schema refresh failed', {
+        cause: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
+        servedStale: this.entry !== null,
+      });
 
       // Warm cache: keep serving the last good schema (stale), do not poison — the next read
-      // re-attempts because `fetchedAt` is unchanged and the entry stays expired.
+      // re-attempts because `expiresAt` is unchanged and the entry stays expired.
       if (this.entry) {
         this.emitAge();
 
@@ -104,6 +168,10 @@ export default class SchemaCache {
     }
   }
 
+  private ttlFor(fetchedAt: number): number {
+    return fetchedAt < this.revalidatingUntil ? REVALIDATION_TTL_MS : this.ttlMs;
+  }
+
   private emitAge(): void {
     const age = this.ageSeconds();
     if (age !== undefined) this.metrics.gauge(SCHEMA_CACHE_AGE_SECONDS, age);