@tumbaland/backend-core 1.44.0 → 1.45.0

package/src/entitlements/client.test.ts

@@ -1,200 +0,0 @@
-jest.mock('../logging/logger', () => ({
-  __esModule: true,
-  default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn(), http: jest.fn() }
-}));
-
-import logger from '../logging/logger';
-import { clearEntitlementsCache, getEntitlements, invalidateEntitlements } from './client';
-import { DEFAULT_PLAN_LIMITS } from './definitions';
-
-const ORIGINAL_ENV = process.env;
-const ORIGINAL_FETCH = global.fetch;
-
-function jsonResponse(body: unknown, status = 200): Response {
-  return { ok: status >= 200 && status < 300, status, json: async () => body } as Response;
-}
-
-function paidResponse() {
-  return jsonResponse({
-    success: true,
-    planCode: 'support',
-    status: 'active',
-    limits: { meters: { storageBytes: 12345 } },
-    upgradeTo: 'support'
-  });
-}
-
-beforeEach(() => {
-  process.env = {
-    ...ORIGINAL_ENV,
-    PAYMENT_API_URL: 'http://payment-service:5005',
-    INTERNAL_SERVICE_TOKEN: 'test-internal-token',
-    SERVICE_NAME: 'album-service'
-  };
-  clearEntitlementsCache();
-  global.fetch = jest.fn();
-  (logger.error as jest.Mock).mockClear();
-});
-
-afterAll(() => {
-  process.env = ORIGINAL_ENV;
-  global.fetch = ORIGINAL_FETCH;
-});
-
-describe('getEntitlements', () => {
-  it('calls the internal endpoint with the service token and normalizes the answer', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
-
-    const result = await getEntitlements('User@Example.com');
-
-    expect(global.fetch).toHaveBeenCalledWith(
-      'http://payment-service:5005/internal/entitlements?email=user%40example.com',
-      expect.objectContaining({
-        headers: expect.objectContaining({ 'x-internal-token': 'test-internal-token', 'x-service-id': 'album-service' })
-      })
-    );
-    expect(result.planCode).toBe('support');
-    expect(result.upgradeTo).toBe('support');
-    expect(result.limits.meters.storageBytes).toBe(12345);
-    // Keys the payload omitted are filled from that plan's defaults rather than
-    // arriving undefined and comparing as NaN inside a quota check.
-    expect(result.limits.meters.seats).toBe(DEFAULT_PLAN_LIMITS.support.meters.seats);
-    expect(result.stale).toBeUndefined();
-  });
-
-  it('serves the cached answer within the TTL and refetches after it', async () => {
-    jest.useFakeTimers();
-    try {
-      (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
-
-      await getEntitlements('user@example.com');
-      await getEntitlements('user@example.com');
-      expect(global.fetch).toHaveBeenCalledTimes(1);
-
-      jest.advanceTimersByTime(60_001);
-      await getEntitlements('user@example.com');
-      expect(global.fetch).toHaveBeenCalledTimes(2);
-    } finally {
-      jest.useRealTimers();
-    }
-  });
-
-  it('treats casing and surrounding whitespace as the same user', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
-
-    await getEntitlements('user@example.com');
-    await getEntitlements('  User@Example.COM ');
-
-    expect(global.fetch).toHaveBeenCalledTimes(1);
-  });
-
-  it('collapses a concurrent burst for one user into a single request', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
-
-    await Promise.all(Array.from({ length: 10 }, () => getEntitlements('user@example.com')));
-
-    expect(global.fetch).toHaveBeenCalledTimes(1);
-  });
-
-  it('drops the cached answer on invalidate', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
-
-    await getEntitlements('user@example.com');
-    invalidateEntitlements('User@example.com');
-    await getEntitlements('user@example.com');
-
-    expect(global.fetch).toHaveBeenCalledTimes(2);
-  });
-});
-
-describe('when payment-service cannot be reached', () => {
-  it('fails closed to free limits rather than handing out the product', async () => {
-    (global.fetch as jest.Mock).mockRejectedValue(new Error('ECONNREFUSED'));
-
-    const result = await getEntitlements('user@example.com');
-
-    expect(result.planCode).toBe('free');
-    expect(result.limits).toEqual(DEFAULT_PLAN_LIMITS.free);
-    expect(result.stale).toBe(true);
-    expect(logger.error).toHaveBeenCalled();
-  });
-
-  it('fails closed on a non-2xx answer too', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(jsonResponse({ success: false }, 500));
-
-    const result = await getEntitlements('user@example.com');
-
-    expect(result.planCode).toBe('free');
-    expect(result.stale).toBe(true);
-  });
-
-  it('never caches a fallback, so recovery is immediate rather than a minute later', async () => {
-    (global.fetch as jest.Mock).mockRejectedValueOnce(new Error('ECONNREFUSED')).mockResolvedValue(paidResponse());
-
-    const failed = await getEntitlements('user@example.com');
-    const recovered = await getEntitlements('user@example.com');
-
-    expect(failed.stale).toBe(true);
-    expect(recovered.planCode).toBe('support');
-  });
-
-  it('fails closed without calling out at all when the channel is unconfigured', async () => {
-    delete process.env.PAYMENT_API_URL;
-
-    const result = await getEntitlements('user@example.com');
-
-    expect(global.fetch).not.toHaveBeenCalled();
-    expect(result.planCode).toBe('free');
-    expect(result.stale).toBe(true);
-    expect(logger.error).toHaveBeenCalledWith('Entitlement lookup not configured', expect.anything());
-  });
-});
-
-describe('base URL selection', () => {
-  it('prefers the container-network address over the public hostname', async () => {
-    process.env.PAYMENT_INTERNAL_URL = 'http://payment-service:5005';
-    process.env.PAYMENT_API_URL = 'https://payment-api.tumbaland.eu';
-    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
-
-    await getEntitlements('user@example.com');
-
-    // payment-front templates the public variable into the browser's
-    // config.json, so it cannot be pointed inward — hence the second variable.
-    expect(global.fetch).toHaveBeenCalledWith(
-      'http://payment-service:5005/internal/entitlements?email=user%40example.com',
-      expect.anything()
-    );
-  });
-
-  it('falls back to the public URL, so local dev and un-migrated deploys still work', async () => {
-    delete process.env.PAYMENT_INTERNAL_URL;
-    process.env.PAYMENT_API_URL = 'https://payment-api.tumbaland.eu';
-    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
-
-    await getEntitlements('user@example.com');
-
-    expect(global.fetch).toHaveBeenCalledWith(
-      'https://payment-api.tumbaland.eu/internal/entitlements?email=user%40example.com',
-      expect.anything()
-    );
-  });
-});
-
-describe('cache bounds', () => {
-  it('evicts the oldest entries instead of growing without limit', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
-
-    for (let i = 0; i < 5_001; i++) {
-      await getEntitlements(`user${i}@example.com`);
-    }
-    const callsAfterFill = (global.fetch as jest.Mock).mock.calls.length;
-
-    // The very first user was evicted by the 5001st, so this is a refetch.
-    await getEntitlements('user0@example.com');
-    expect((global.fetch as jest.Mock).mock.calls.length).toBe(callsAfterFill + 1);
-
-    // The most recent user is still cached.
-    await getEntitlements('user5000@example.com');
-    expect((global.fetch as jest.Mock).mock.calls.length).toBe(callsAfterFill + 1);
-  });
-});

package/src/entitlements/client.ts

@@ -1,179 +0,0 @@
-import logger from '../logging/logger';
-import { FALLBACK_PLAN, normalizeLimits, resolveLimits } from './definitions';
-import { Entitlements } from './types';
-
-/**
- * Entitlements are read over the internal-service channel, not carried on the
- * JWT.
- *
- * The JWT is signed for 24h and no service outside auth-service checks
- * `tokenVersion`, so a plan embedded in it would be stale in both directions:
- * a user who upgrades waits up to a day for what they just paid for, and a user
- * who cancels keeps paid features for up to a day. A 60-second cache in front
- * of a live lookup bounds that to a minute, and the enforcement points are
- * writes and dispatches — low frequency — so the network cost is negligible.
- */
-const CACHE_TTL_MS = 60_000;
-
-/** Bounded so a service under enumeration can't grow the cache without limit. */
-const MAX_CACHE_ENTRIES = 5_000;
-
-const REQUEST_TIMEOUT_MS = 3_000;
-
-interface CacheEntry {
-  value: Entitlements;
-  expiresAt: number;
-}
-
-const cache = new Map<string, CacheEntry>();
-
-/**
- * Concurrent callers for the same email share one request. Without this, a
- * burst of uploads from one user on a cold cache fans out into one
- * payment-service call each.
- */
-const inFlight = new Map<string, Promise<Entitlements>>();
-
-function cacheKey(email: string): string {
-  return email.trim().toLowerCase();
-}
-
-function putInCache(key: string, value: Entitlements): void {
-  if (cache.size >= MAX_CACHE_ENTRIES) {
-    // Map iterates in insertion order, so the first key is the oldest write.
-    const oldest = cache.keys().next();
-    if (!oldest.done) cache.delete(oldest.value);
-  }
-  cache.set(key, { value, expiresAt: Date.now() + CACHE_TTL_MS });
-}
-
-/**
- * Fail closed: an unreachable payment-service degrades everyone to free limits
- * rather than handing the product out for the length of the outage. The blast
- * radius is bounded by design — reads are never gated, only writes and
- * dispatches — so the worst case is "cannot upload for a minute", not
- * "cannot use the app".
- */
-function fallbackEntitlements(email: string): Entitlements {
-  return {
-    email,
-    planCode: FALLBACK_PLAN,
-    status: null,
-    limits: resolveLimits(FALLBACK_PLAN),
-    stale: true
-  };
-}
-
-interface EntitlementResponse {
-  success?: boolean;
-  planCode?: string;
-  status?: string | null;
-  limits?: Parameters<typeof normalizeLimits>[0];
-  upgradeTo?: string;
-}
-
-/**
- * Prefers the container-network address over the public hostname.
- *
- * `PAYMENT_API_URL` cannot simply be pointed inward: payment-front's entrypoint
- * templates that same variable into the `config.json` the *browser* downloads,
- * so a Docker-internal value there breaks the subscription and checkout pages.
- * One variable, two consumers with incompatible needs — this is the server-side
- * half of it.
- *
- * Falling back keeps local dev (where only `PAYMENT_API_URL` is set) and any
- * un-migrated deployment working; it just takes the long way round, out through
- * the proxy and back, carrying the internal token across the public edge.
- */
-function internalPaymentUrl(): string | undefined {
-  return process.env.PAYMENT_INTERNAL_URL || process.env.PAYMENT_API_URL;
-}
-
-async function fetchEntitlements(email: string): Promise<Entitlements> {
-  const baseUrl = internalPaymentUrl();
-  const token = process.env.INTERNAL_SERVICE_TOKEN;
-  const serviceId = process.env.SERVICE_NAME || 'unknown-service';
-
-  if (!baseUrl || !token) {
-    logger.error('Entitlement lookup not configured', {
-      hasPaymentApiUrl: Boolean(baseUrl),
-      hasInternalToken: Boolean(token)
-    });
-    return fallbackEntitlements(email);
-  }
-
-  try {
-    const response = await fetch(`${baseUrl}/internal/entitlements?email=${encodeURIComponent(email)}`, {
-      method: 'GET',
-      headers: {
-        'Content-Type': 'application/json',
-        'x-internal-token': token,
-        'x-service-id': serviceId
-      },
-      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
-    });
-
-    if (!response.ok) {
-      logger.error('Entitlement lookup failed', { email, status: response.status });
-      return fallbackEntitlements(email);
-    }
-
-    const body = (await response.json()) as EntitlementResponse;
-    const planCode = body.planCode || FALLBACK_PLAN;
-    return {
-      email,
-      planCode,
-      status: body.status ?? null,
-      // Re-normalized on this side too: the payload crossed a network boundary
-      // and a partially-configured plan must not leave a meter undefined.
-      limits: normalizeLimits(body.limits, planCode),
-      upgradeTo: body.upgradeTo
-    };
-  } catch (err) {
-    logger.error('Entitlement lookup errored', { email, error: (err as Error)?.message });
-    return fallbackEntitlements(email);
-  }
-}
-
-/**
- * The user's current plan and limits, cached for {@link CACHE_TTL_MS}.
- *
- * Failures are never cached — a fallback result would otherwise pin a paying
- * user to free limits for a full minute after the outage ended.
- */
-export async function getEntitlements(email: string): Promise<Entitlements> {
-  const key = cacheKey(email);
-
-  const cached = cache.get(key);
-  if (cached && cached.expiresAt > Date.now()) return cached.value;
-
-  const pending = inFlight.get(key);
-  if (pending) return pending;
-
-  const request = fetchEntitlements(key)
-    .then(value => {
-      if (!value.stale) putInCache(key, value);
-      return value;
-    })
-    .finally(() => {
-      inFlight.delete(key);
-    });
-
-  inFlight.set(key, request);
-  return request;
-}
-
-/**
- * Drop a user's cached entitlements. Call after anything that changes their
- * plan (checkout completed, subscription canceled) to collapse the staleness
- * window from 60s to zero for the user who is watching.
- */
-export function invalidateEntitlements(email: string): void {
-  cache.delete(cacheKey(email));
-}
-
-/** Empties the whole cache. Test seam, and a usable lever after a bulk plan edit. */
-export function clearEntitlementsCache(): void {
-  cache.clear();
-  inFlight.clear();
-}

package/src/entitlements/definitions.test.ts

@@ -1,161 +0,0 @@
-import {
-  DEFAULT_PLAN_LIMITS,
-  FALLBACK_PLAN,
-  FEATURE_KEYS,
-  METER_KEYS,
-  STAFF_PLAN,
-  UNLIMITED,
-  applyLimits,
-  fitsWithin,
-  isFeatureKey,
-  isMeterKey,
-  meterPeriod,
-  normalizeLimits,
-  resolveLimits
-} from './definitions';
-
-describe('resolveLimits', () => {
-  it('returns the defaults for a known plan code', () => {
-    expect(resolveLimits('support')).toEqual(DEFAULT_PLAN_LIMITS.support);
-  });
-
-  it('falls back to free for an unknown code, never to unlimited', () => {
-    expect(resolveLimits('enterprise-typo')).toEqual(DEFAULT_PLAN_LIMITS.free);
-    expect(resolveLimits(undefined)).toEqual(DEFAULT_PLAN_LIMITS[FALLBACK_PLAN]);
-  });
-
-  it('returns a copy, so a caller mutating limits cannot poison the defaults', () => {
-    const limits = resolveLimits('free');
-    limits.meters.storageBytes = 999;
-    limits.features.cleanExport = true;
-
-    expect(resolveLimits('free').meters.storageBytes).toBe(DEFAULT_PLAN_LIMITS.free.meters.storageBytes);
-    expect(resolveLimits('free').features.cleanExport).toBe(false);
-  });
-});
-
-describe('normalizeLimits', () => {
-  it('applies stored values over the plan defaults', () => {
-    const limits = normalizeLimits({ meters: { storageBytes: 123 }, retentionDays: 30 }, 'support');
-
-    expect(limits.meters.storageBytes).toBe(123);
-    expect(limits.retentionDays).toBe(30);
-    // Untouched keys keep the plan's defaults rather than resetting to free.
-    expect(limits.meters.trackedTickers).toBe(DEFAULT_PLAN_LIMITS.support.meters.trackedTickers);
-  });
-
-  it('drops keys that no code enforces', () => {
-    const limits = normalizeLimits(
-      { meters: { storageBytes: 5, wormholes: 1000 }, features: { cleanExport: true, teleport: true } },
-      'free'
-    );
-
-    expect(limits.meters).not.toHaveProperty('wormholes');
-    expect(limits.features).not.toHaveProperty('teleport');
-    expect(Object.keys(limits.meters).sort()).toEqual([...METER_KEYS].sort());
-  });
-
-  it('normalizes any negative ceiling to UNLIMITED and floors fractions', () => {
-    const limits = normalizeLimits({ meters: { aiJobs: -5, trackedTickers: 7.9 }, retentionDays: -2 }, 'free');
-
-    expect(limits.meters.aiJobs).toBe(UNLIMITED);
-    expect(limits.meters.trackedTickers).toBe(7);
-    expect(limits.retentionDays).toBe(UNLIMITED);
-  });
-
-  it('ignores non-numeric and non-boolean junk instead of producing NaN limits', () => {
-    const limits = normalizeLimits(
-      { meters: { seats: 'lots' as unknown as number }, features: { cleanExport: 'yes' as unknown as boolean } },
-      'support'
-    );
-
-    expect(limits.meters.seats).toBe(DEFAULT_PLAN_LIMITS.support.meters.seats);
-    expect(limits.features.cleanExport).toBe(true);
-  });
-
-  it('returns the plan defaults for an empty or missing payload', () => {
-    expect(normalizeLimits(undefined, 'support')).toEqual(DEFAULT_PLAN_LIMITS.support);
-    expect(normalizeLimits(null, 'support')).toEqual(DEFAULT_PLAN_LIMITS.support);
-    expect(normalizeLimits({}, 'support')).toEqual(DEFAULT_PLAN_LIMITS.support);
-  });
-
-  it('resolves an unknown plan code to free even when limits are stored', () => {
-    const limits = normalizeLimits({ meters: { seats: 3 } }, 'gold-tier-that-never-shipped');
-
-    expect(limits.meters.seats).toBe(3);
-    expect(limits.meters.storageBytes).toBe(DEFAULT_PLAN_LIMITS.free.meters.storageBytes);
-    expect(limits.features.cleanExport).toBe(false);
-  });
-});
-
-describe('applyLimits', () => {
-  it('layers a partial set over a complete one without mutating the base', () => {
-    const base = resolveLimits('free');
-
-    const layered = applyLimits(base, { meters: { storageBytes: 500 } });
-
-    expect(layered.meters.storageBytes).toBe(500);
-    expect(base.meters.storageBytes).toBe(DEFAULT_PLAN_LIMITS.free.meters.storageBytes);
-  });
-
-  it('stacks: defaults, then plan, then a per-user override', () => {
-    const planLimits = normalizeLimits({ meters: { storageBytes: 100, seats: 2 } }, 'free');
-
-    const withOverride = applyLimits(planLimits, { meters: { storageBytes: 5000 }, features: { cleanExport: true } });
-
-    expect(withOverride.meters.storageBytes).toBe(5000); // override wins
-    expect(withOverride.meters.seats).toBe(2); // plan wins where the override is silent
-    expect(withOverride.meters.aiJobs).toBe(DEFAULT_PLAN_LIMITS.free.meters.aiJobs); // default underneath both
-    expect(withOverride.features.cleanExport).toBe(true);
-  });
-});
-
-describe('the staff plan', () => {
-  it('grants every meter and feature without limit', () => {
-    const limits = resolveLimits(STAFF_PLAN);
-
-    for (const meter of METER_KEYS) {
-      expect(limits.meters[meter]).toBe(UNLIMITED);
-    }
-    expect(limits.retentionDays).toBe(UNLIMITED);
-    expect(limits.features.cleanExport).toBe(true);
-  });
-});
-
-describe('fitsWithin', () => {
-  it('treats UNLIMITED as always fitting', () => {
-    expect(fitsWithin(UNLIMITED, Number.MAX_SAFE_INTEGER, 1)).toBe(true);
-  });
-
-  it('allows landing exactly on the limit but not passing it', () => {
-    expect(fitsWithin(10, 9, 1)).toBe(true);
-    expect(fitsWithin(10, 10, 1)).toBe(false);
-  });
-});
-
-describe('key registry', () => {
-  it('recognizes only registered keys', () => {
-    expect(isMeterKey('storageBytes')).toBe(true);
-    expect(isMeterKey('storagebytes')).toBe(false);
-    expect(isFeatureKey('cleanExport')).toBe(true);
-    expect(isFeatureKey('planner')).toBe(false);
-  });
-
-  it('assigns every meter a period', () => {
-    expect(meterPeriod('aiJobs')).toBe('MONTH');
-    expect(meterPeriod('storageBytes')).toBe('ALL');
-  });
-
-  it('gives every registered plan a value for every registered key', () => {
-    for (const [code, limits] of Object.entries(DEFAULT_PLAN_LIMITS)) {
-      for (const meter of METER_KEYS) {
-        expect(typeof limits.meters[meter]).toBe(`number`);
-      }
-      for (const feature of FEATURE_KEYS) {
-        expect(typeof limits.features[feature]).toBe('boolean');
-      }
-      expect(typeof limits.retentionDays).toBe(`number`);
-      expect(code).toBeTruthy();
-    }
-  });
-});