@proulr/bff-core 0.1.11 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proulr/bff-core",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -33,8 +33,8 @@
   },
   "dependencies": {
     "@hono/node-server": "^1.19.6",
-    "@proulr/rosetta": "^0.1.67",
-    "@proulr/sdui-contract": "^0.1.16",
+    "@proulr/rosetta": "^0.1.70",
+    "@proulr/sdui-contract": "^0.1.17",
     "@supabase/supabase-js": "^2.107.0",
     "dotenv": "^16.6.1",
     "hono": "^4.10.6",

package/src/bff-supabase-client.test.ts

@@ -0,0 +1,66 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('./bff-env-loader', () => ({ loadBffEnv: vi.fn() }));
+
+const createClient = vi.hoisted(() => vi.fn());
+vi.mock('@supabase/supabase-js', () => ({ createClient }));
+
+let clientSeq = 0;
+
+describe('createBffSupabaseClient', () => {
+  beforeEach(async () => {
+    createClient.mockReset();
+    createClient.mockImplementation(() => ({ id: ++clientSeq }));
+    vi.resetModules();
+    delete process.env.SUPABASE_INTERNAL_URL;
+    process.env.SUPABASE_URL = 'https://api.proulr.com';
+    process.env.SUPABASE_ANON_KEY = 'anon-key';
+  });
+
+  it('prefers SUPABASE_INTERNAL_URL (Kong loopback) over the public URL', async () => {
+    process.env.SUPABASE_INTERNAL_URL = 'http://127.0.0.1:8000';
+    const { createBffSupabaseClient } = await import('./bff-supabase-client');
+    createBffSupabaseClient('jwt-user-a');
+    expect(createClient).toHaveBeenCalledWith(
+      'http://127.0.0.1:8000',
+      'anon-key',
+      expect.anything(),
+    );
+  });
+
+  it('reuses the same client for the same token', async () => {
+    const { createBffSupabaseClient } = await import('./bff-supabase-client');
+    const first = createBffSupabaseClient('jwt-user-a');
+    const second = createBffSupabaseClient('jwt-user-a');
+    expect(second).toBe(first);
+    expect(createClient).toHaveBeenCalledTimes(1);
+  });
+
+  it('creates distinct clients per token and for anonymous', async () => {
+    const { createBffSupabaseClient } = await import('./bff-supabase-client');
+    const a = createBffSupabaseClient('jwt-user-a');
+    const b = createBffSupabaseClient('jwt-user-b');
+    const anon = createBffSupabaseClient();
+    expect(a).not.toBe(b);
+    expect(b).not.toBe(anon);
+    expect(createBffSupabaseClient()).toBe(anon);
+  });
+
+  it('evicts the least recently used client beyond the cache limit', async () => {
+    const { createBffSupabaseClient } = await import('./bff-supabase-client');
+    const first = createBffSupabaseClient('token-0');
+    for (let i = 1; i <= 64; i += 1) {
+      createBffSupabaseClient(`token-${i}`);
+    }
+    const recreated = createBffSupabaseClient('token-0');
+    expect(recreated).not.toBe(first);
+  });
+
+  it('throws when supabase is not configured', async () => {
+    delete process.env.SUPABASE_URL;
+    delete process.env.SUPABASE_ANON_KEY;
+    vi.resetModules();
+    const { createBffSupabaseClient } = await import('./bff-supabase-client');
+    expect(() => createBffSupabaseClient('t')).toThrow('bff_supabase_not_configured');
+  });
+});

package/src/bff-supabase-client.ts

@@ -3,19 +3,24 @@ import { loadBffEnv } from './bff-env-loader';
 
 loadBffEnv();
 
-const supabaseUrl = process.env.SUPABASE_URL ?? process.env.EXPO_PUBLIC_SUPABASE_URL ?? '';
+// SUPABASE_INTERNAL_URL bypasses the Cloudflare hairpin on the VPS (Kong
+// 127.0.0.1:8000). Never derive client-facing URLs (share/referral/functions)
+// from it — those must keep the public SUPABASE_URL.
+const supabaseUrl =
+  process.env.SUPABASE_INTERNAL_URL ??
+  process.env.SUPABASE_URL ??
+  process.env.EXPO_PUBLIC_SUPABASE_URL ?? '';
 const supabaseAnonKey =
   process.env.SUPABASE_ANON_KEY ?? process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY ?? '';
 
+const CLIENT_CACHE_LIMIT = 64;
+const clientsByToken = new Map<string, SupabaseClient>();
+
 export function isBffSupabaseConfigured(): boolean {
   return Boolean(supabaseUrl && supabaseAnonKey);
 }
 
-export function createBffSupabaseClient(authToken?: string): SupabaseClient {
-  if (!isBffSupabaseConfigured()) {
-    throw new Error('bff_supabase_not_configured');
-  }
-
+function buildClient(authToken?: string): SupabaseClient {
   return createClient(supabaseUrl, supabaseAnonKey, {
     auth: {
       persistSession: false,
@@ -31,3 +36,25 @@ export function createBffSupabaseClient(authToken?: string): SupabaseClient {
       : undefined,
   });
 }
+
+export function createBffSupabaseClient(authToken?: string): SupabaseClient {
+  if (!isBffSupabaseConfigured()) {
+    throw new Error('bff_supabase_not_configured');
+  }
+
+  const cacheKey = authToken ?? 'anon';
+  const cached = clientsByToken.get(cacheKey);
+  if (cached) {
+    clientsByToken.delete(cacheKey);
+    clientsByToken.set(cacheKey, cached);
+    return cached;
+  }
+
+  const client = buildClient(authToken);
+  clientsByToken.set(cacheKey, client);
+  if (clientsByToken.size > CLIENT_CACHE_LIMIT) {
+    const oldest = clientsByToken.keys().next().value;
+    if (oldest !== undefined) clientsByToken.delete(oldest);
+  }
+  return client;
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import type { SduiScreenBuilder, SduiScreenBuilderContext } from '@proulr/sdui-contract';
 import { createBffMetrics, isBffMetricsEnabled } from './bff-metrics';
+import { ScreenResponseCache, buildScreenCacheKey } from './screen-response-cache';
 
 export type SduiActionHandler = (
   ctx: SduiScreenBuilderContext,
@@ -44,6 +45,9 @@ export function createSduiBff(options: CreateSduiBffOptions) {
   const app = new Hono();
   const metricsEnabled = isBffMetricsEnabled();
   const metrics = metricsEnabled ? createBffMetrics(options.bffId) : null;
+  const screenCache = new ScreenResponseCache(
+    Number(process.env.BFF_SCREEN_CACHE_TTL_MS ?? 0) || 0,
+  );
 
   app.use('*', cors());
 
@@ -107,8 +111,22 @@ export function createSduiBff(options: CreateSduiBffOptions) {
 
     const query = Object.fromEntries(new URL(c.req.url).searchParams.entries());
     const authToken = readAuthToken(c.req.header('Authorization'));
-    const screen = await builder(buildContext({}, query, authToken));
-    return c.json(screen);
+    const cacheKey = buildScreenCacheKey({ screenId, query, authToken });
+    const hit = await screenCache.get(
+      cacheKey,
+      async () => builder(buildContext({}, query, authToken)),
+      c.req.header('If-None-Match'),
+    );
+
+    if (hit.notModified) {
+      return c.newResponse(null, 304, { ETag: hit.entry.etag });
+    }
+
+    return c.body(hit.entry.body, 200, {
+      'Content-Type': 'application/json; charset=utf-8',
+      ETag: hit.entry.etag,
+      'Cache-Control': 'private, no-cache',
+    });
   });
 
   app.post('/v1/actions/:actionId', async (c) => {
@@ -128,6 +146,7 @@ export function createSduiBff(options: CreateSduiBffOptions) {
     try {
       const authToken = readAuthToken(c.req.header('Authorization'));
       const result = await handler(buildContext({}, {}, authToken), body);
+      screenCache.purgeAll();
       return c.json({ ok: true, action_id: actionId, ...result });
     } catch (error) {
       console.warn(`[${options.bffId}] action ${actionId} failed`, error);
@@ -155,6 +174,13 @@ export function createSduiBff(options: CreateSduiBffOptions) {
 
 export * from '@proulr/sdui-contract';
 export { createBffSupabaseClient, isBffSupabaseConfigured } from './bff-supabase-client';
+export {
+  ScreenResponseCache,
+  buildScreenCacheKey,
+  computeScreenEtag,
+  type ScreenCacheEntry,
+  type ScreenCacheHit,
+} from './screen-response-cache';
 export {
   buildNativeAdInsertionSeed,
   insertRandomNativeAdSlots,

package/src/screen-response-cache.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest';
+import {
+  ScreenResponseCache,
+  buildScreenCacheKey,
+  computeScreenEtag,
+} from './screen-response-cache';
+
+describe('buildScreenCacheKey', () => {
+  it('is stable regardless of query insertion order', () => {
+    const a = buildScreenCacheKey({
+      screenId: 'chat.inbox',
+      query: { locale: 'pt-BR', filter: 'all' },
+      authToken: 'tok',
+    });
+    const b = buildScreenCacheKey({
+      screenId: 'chat.inbox',
+      query: { filter: 'all', locale: 'pt-BR' },
+      authToken: 'tok',
+    });
+    expect(a).toBe(b);
+  });
+
+  it('differs by screen id, query values and token', () => {
+    const base = { screenId: 'chat.inbox', query: { locale: 'pt-BR' }, authToken: 'tok' };
+    expect(buildScreenCacheKey(base)).not.toBe(
+      buildScreenCacheKey({ ...base, screenId: 'vibes.home' }),
+    );
+    expect(buildScreenCacheKey(base)).not.toBe(
+      buildScreenCacheKey({ ...base, query: { locale: 'en-US' } }),
+    );
+    expect(buildScreenCacheKey(base)).not.toBe(buildScreenCacheKey({ ...base, authToken: 'tok2' }));
+    expect(buildScreenCacheKey(base)).not.toBe(buildScreenCacheKey({ ...base, authToken: undefined }));
+  });
+
+  it('does not leak the raw auth token in the key', () => {
+    const key = buildScreenCacheKey({ screenId: 'x', query: {}, authToken: 'super-secret-jwt' });
+    expect(key).not.toContain('super-secret-jwt');
+  });
+});
+
+describe('computeScreenEtag', () => {
+  it('is deterministic per body and differs across bodies', () => {
+    expect(computeScreenEtag('{"a":1}')).toBe(computeScreenEtag('{"a":1}'));
+    expect(computeScreenEtag('{"a":1}')).not.toBe(computeScreenEtag('{"a":2}'));
+  });
+});
+
+describe('ScreenResponseCache', () => {
+  it('coalesces concurrent identical builds into a single builder call', async () => {
+    let calls = 0;
+    let release: (screen: Record<string, unknown>) => void = () => {};
+    const build = () => {
+      calls += 1;
+      return new Promise<Record<string, unknown>>((resolve) => {
+        release = resolve;
+      });
+    };
+
+    const cache = new ScreenResponseCache(0);
+    const p1 = cache.get('k', build);
+    const p2 = cache.get('k', build);
+    release({ ok: true });
+
+    const [h1, h2] = await Promise.all([p1, p2]);
+    expect(calls).toBe(1);
+    expect(h1.entry.body).toBe('{"ok":true}');
+    expect(h2.entry.body).toBe('{"ok":true}');
+  });
+
+  it('rebuilds after completion when ttl is 0', async () => {
+    let calls = 0;
+    const build = async () => ({ n: ++calls });
+    const cache = new ScreenResponseCache(0);
+
+    await cache.get('k', build);
+    const second = await cache.get('k', build);
+    expect(calls).toBe(2);
+    expect(second.entry.body).toBe('{"n":2}');
+  });
+
+  it('serves fresh entries within ttl and flags matching etag as not modified', async () => {
+    let calls = 0;
+    const build = async () => ({ n: ++calls });
+    let clock = 1_000;
+    const cache = new ScreenResponseCache(500, 512, () => clock);
+
+    const first = await cache.get('k', build);
+    clock += 400;
+    const second = await cache.get('k', build, first.entry.etag);
+
+    expect(calls).toBe(1);
+    expect(second.fresh).toBe(true);
+    expect(second.notModified).toBe(true);
+
+    clock += 200;
+    const third = await cache.get('k', build);
+    expect(calls).toBe(2);
+    expect(third.notModified).toBe(false);
+  });
+
+  it('does not serve a stale entry to an etag-mismatched request', async () => {
+    let calls = 0;
+    const build = async () => ({ n: ++calls });
+    const cache = new ScreenResponseCache(500);
+
+    await cache.get('k', build);
+    const hit = await cache.get('k', build, 'W/"other"');
+    expect(calls).toBe(1);
+    expect(hit.notModified).toBe(false);
+    expect(hit.fresh).toBe(true);
+  });
+
+  it('purgeAll forces the next build to run', async () => {
+    let calls = 0;
+    const build = async () => ({ n: ++calls });
+    const cache = new ScreenResponseCache(5_000);
+
+    await cache.get('k', build);
+    cache.purgeAll();
+    await cache.get('k', build);
+    expect(calls).toBe(2);
+  });
+
+  it('does not cache failures', async () => {
+    let calls = 0;
+    const build = async () => {
+      calls += 1;
+      if (calls === 1) throw new Error('boom');
+      return { ok: true };
+    };
+    const cache = new ScreenResponseCache(5_000);
+
+    await expect(cache.get('k', build)).rejects.toThrow('boom');
+    const ok = await cache.get('k', build);
+    expect(calls).toBe(2);
+    expect(ok.entry.body).toBe('{"ok":true}');
+  });
+
+  it('evicts the oldest entries beyond the limit', async () => {
+    let calls = 0;
+    const build = async () => ({ n: ++calls });
+    const cache = new ScreenResponseCache(60_000, 2);
+
+    await cache.get('a', build);
+    await cache.get('b', build);
+    await cache.get('c', build);
+    await cache.get('a', build);
+    expect(calls).toBe(4);
+    await cache.get('c', build);
+    expect(calls).toBe(4);
+  });
+});

package/src/screen-response-cache.ts

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+
+export type ScreenCacheKeyInput = {
+  screenId: string;
+  query: Record<string, string>;
+  authToken?: string;
+};
+
+export type ScreenCacheEntry = {
+  body: string;
+  etag: string;
+  freshUntil: number;
+};
+
+export type ScreenCacheHit = {
+  entry: ScreenCacheEntry;
+  fresh: boolean;
+  notModified: boolean;
+};
+
+export function buildScreenCacheKey(input: ScreenCacheKeyInput): string {
+  const queryPart = Object.keys(input.query)
+    .sort()
+    .map((name) => `${name}=${input.query[name]}`)
+    .join('&');
+  const hash = createHash('sha256');
+  hash.update(input.screenId);
+  hash.update('\u0000');
+  hash.update(queryPart);
+  hash.update('\u0000');
+  hash.update(input.authToken ?? 'anon');
+  return hash.digest('base64url');
+}
+
+export function computeScreenEtag(body: string): string {
+  return `W/"${createHash('sha256').update(body).digest('base64url').slice(0, 32)}"`;
+}
+
+/**
+ * Dedupes identical in-flight screen builds (the mount/focus revalidation storm
+ * fires the same GET 3-4x concurrently). `ttlMs > 0` additionally serves
+ * completed results while fresh; keep it low (default 0) so direct client-side
+ * writes stay near-real-time.
+ */
+export class ScreenResponseCache {
+  private entries = new Map<string, ScreenCacheEntry>();
+  private pending = new Map<string, Promise<ScreenCacheEntry>>();
+
+  constructor(
+    private readonly ttlMs: number,
+    private readonly limit: number = 512,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  get(
+    key: string,
+    build: () => Promise<unknown>,
+    ifNoneMatch?: string | null,
+  ): Promise<ScreenCacheHit> {
+    const fresh = this.entries.get(key);
+    if (fresh && fresh.freshUntil > this.now()) {
+      return Promise.resolve({ entry: fresh, fresh: true, notModified: ifNoneMatch === fresh.etag });
+    }
+
+    const pending = this.pending.get(key);
+    if (pending) {
+      return pending.then((entry) => ({
+        entry,
+        fresh: true,
+        notModified: ifNoneMatch === entry.etag,
+      }));
+    }
+
+    const promise = this.buildEntry(key, build);
+    this.pending.set(key, promise);
+    return promise.then((entry) => ({
+      entry,
+      fresh: true,
+      notModified: ifNoneMatch === entry.etag,
+    }));
+  }
+
+  purgeAll(): void {
+    this.entries.clear();
+  }
+
+  private async buildEntry(
+    key: string,
+    build: () => Promise<unknown>,
+  ): Promise<ScreenCacheEntry> {
+    try {
+      const screen = await build();
+      const body = JSON.stringify(screen);
+      const entry: ScreenCacheEntry = {
+        body,
+        etag: computeScreenEtag(body),
+        freshUntil: this.now() + this.ttlMs,
+      };
+      this.entries.set(key, entry);
+      this.evictOverflow();
+      return entry;
+    } finally {
+      this.pending.delete(key);
+    }
+  }
+
+  private evictOverflow(): void {
+    while (this.entries.size > this.limit) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest === undefined) break;
+      this.entries.delete(oldest);
+    }
+  }
+}