@tumbaland/backend-core 1.43.0 → 1.45.0

package/src/errors/HttpError.ts

@@ -1,91 +0,0 @@
-/**
- * Base class for errors that should be turned into a specific HTTP response
- * by the shared errorHandler, instead of every controller hand-rolling
- * try/catch + string-matching on error.message to pick a status code.
- *
- * Express 5 forwards rejected promises from async route handlers to the
- * mounted error handler automatically, so controllers can just
- * `throw new NotFoundError(...)` and stop wrapping in try/catch.
- */
-export class HttpError extends Error {
-  statusCode: number;
-  /**
-   * Extra fields merged into the JSON body by the shared errorHandler. Used by
-   * errors the client has to *act* on rather than just display — a 402 tells
-   * the upgrade dialog which meter blocked and which plan lifts it.
-   */
-  details?: Record<string, unknown>;
-
-  constructor(statusCode: number, message: string, details?: Record<string, unknown>) {
-    super(message);
-    this.name = new.target.name;
-    this.statusCode = statusCode;
-    this.details = details;
-    // Restore the prototype chain (needed when compiling to ES2018 targets
-    // where `extends Error` doesn't preserve instanceof checks correctly).
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-}
-
-export class BadRequestError extends HttpError {
-  constructor(message = 'Bad request') {
-    super(400, message);
-  }
-}
-
-export class UnauthorizedError extends HttpError {
-  constructor(message = 'Unauthorized') {
-    super(401, message);
-  }
-}
-
-export class ForbiddenError extends HttpError {
-  constructor(message = 'Access denied') {
-    super(403, message);
-  }
-}
-
-export class NotFoundError extends HttpError {
-  constructor(message = 'Not found') {
-    super(404, message);
-  }
-}
-
-export class ConflictError extends HttpError {
-  constructor(message = 'Conflict') {
-    super(409, message);
-  }
-}
-
-export class TooManyRequestsError extends HttpError {
-  constructor(message = 'Too many requests') {
-    super(429, message);
-  }
-}
-
-/**
- * Fields the upgrade dialog renders. Every one of them comes from the response
- * body, so the dialog needs no knowledge of which call failed.
- */
-export interface PaymentRequiredDetails {
-  /** Machine-readable reason, e.g. `QUOTA_EXCEEDED` or `FEATURE_NOT_IN_PLAN`. */
-  code: string;
-  meter?: string;
-  feature?: string;
-  used?: number;
-  limit?: number;
-  planCode?: string;
-  /** The cheapest plan that lifts this particular limit, when one exists. */
-  upgradeTo?: string;
-}
-
-/**
- * 402, never 403. 403 means "you may not"; 402 means "you may, for money" —
- * and the frontend needs to tell those apart to choose between an error toast
- * and an upgrade dialog.
- */
-export class PaymentRequiredError extends HttpError {
-  constructor(message: string, details: PaymentRequiredDetails) {
-    super(402, message, { ...details });
-  }
-}

package/src/groups/client.test.ts

@@ -1,215 +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 { clearGroupOwnerCache, getGroupOwner, invalidateGroupOwner } from './client';
-
-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 ownerResponse(overrides: Record<string, unknown> = {}) {
-  return jsonResponse({
-    success: true,
-    groupId: 'group-1',
-    ownerEmail: 'Owner@Example.com',
-    memberCount: 3,
-    deleted: false,
-    ...overrides
-  });
-}
-
-beforeEach(() => {
-  process.env = {
-    ...ORIGINAL_ENV,
-    GROUP_API_URL: 'http://group-service:5006',
-    INTERNAL_SERVICE_TOKEN: 'test-internal-token',
-    SERVICE_NAME: 'album-service'
-  };
-  clearGroupOwnerCache();
-  global.fetch = jest.fn();
-  (logger.error as jest.Mock).mockClear();
-  (logger.warn as jest.Mock).mockClear();
-});
-
-afterAll(() => {
-  process.env = ORIGINAL_ENV;
-  global.fetch = ORIGINAL_FETCH;
-});
-
-describe('getGroupOwner', () => {
-  it('calls the internal endpoint with the service token and normalizes the owner', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
-
-    const result = await getGroupOwner('group-1');
-
-    expect(global.fetch).toHaveBeenCalledWith(
-      'http://group-service:5006/internal/groups/group-1/owner',
-      expect.objectContaining({
-        headers: expect.objectContaining({ 'x-internal-token': 'test-internal-token', 'x-service-id': 'album-service' })
-      })
-    );
-    // Lowercased on arrival: it becomes a UsageMeter subjectId, which is
-    // lowercase, so an owner recorded with capitals would open a second meter.
-    expect(result?.ownerEmail).toBe('owner@example.com');
-    expect(result?.memberCount).toBe(3);
-    expect(result?.deleted).toBe(false);
-  });
-
-  it('resolves a soft-deleted group rather than dropping its storage', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse({ deleted: true }));
-
-    const result = await getGroupOwner('group-1');
-
-    expect(result?.ownerEmail).toBe('owner@example.com');
-    expect(result?.deleted).toBe(true);
-  });
-
-  it('serves the cached answer within the TTL and refetches after it', async () => {
-    jest.useFakeTimers();
-    try {
-      (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
-
-      await getGroupOwner('group-1');
-      await getGroupOwner('group-1');
-      expect(global.fetch).toHaveBeenCalledTimes(1);
-
-      jest.advanceTimersByTime(60_001);
-      await getGroupOwner('group-1');
-      expect(global.fetch).toHaveBeenCalledTimes(2);
-    } finally {
-      jest.useRealTimers();
-    }
-  });
-
-  it('collapses a concurrent burst for one group into a single request', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
-
-    await Promise.all(Array.from({ length: 10 }, () => getGroupOwner('group-1')));
-
-    expect(global.fetch).toHaveBeenCalledTimes(1);
-  });
-
-  it('drops the cached owner on invalidate, so a transferred group rebills at once', async () => {
-    (global.fetch as jest.Mock)
-      .mockResolvedValueOnce(ownerResponse())
-      .mockResolvedValue(ownerResponse({ ownerEmail: 'new-owner@example.com' }));
-
-    const before = await getGroupOwner('group-1');
-    invalidateGroupOwner('group-1');
-    const after = await getGroupOwner('group-1');
-
-    expect(before?.ownerEmail).toBe('owner@example.com');
-    expect(after?.ownerEmail).toBe('new-owner@example.com');
-  });
-
-  it('returns null without calling out on a blank group id', async () => {
-    expect(await getGroupOwner('   ')).toBeNull();
-    expect(global.fetch).not.toHaveBeenCalled();
-  });
-});
-
-describe('when the group cannot be resolved', () => {
-  it('returns null on a 404 and warns rather than erroring', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(jsonResponse({ success: false }, 404));
-
-    expect(await getGroupOwner('missing')).toBeNull();
-    expect(logger.warn).toHaveBeenCalled();
-    expect(logger.error).not.toHaveBeenCalled();
-  });
-
-  it('returns null and errors when group-service is unreachable', async () => {
-    (global.fetch as jest.Mock).mockRejectedValue(new Error('ECONNREFUSED'));
-
-    expect(await getGroupOwner('group-1')).toBeNull();
-    expect(logger.error).toHaveBeenCalled();
-  });
-
-  it('returns null when the answer carries no owner', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse({ ownerEmail: undefined }));
-
-    expect(await getGroupOwner('group-1')).toBeNull();
-    expect(logger.error).toHaveBeenCalled();
-  });
-
-  it('returns null without calling out at all when the channel is unconfigured', async () => {
-    delete process.env.GROUP_API_URL;
-
-    expect(await getGroupOwner('group-1')).toBeNull();
-    expect(global.fetch).not.toHaveBeenCalled();
-    expect(logger.error).toHaveBeenCalledWith('Group owner lookup not configured', expect.anything());
-  });
-});
-
-describe('base URL selection', () => {
-  it('prefers the container-network address over the public hostname', async () => {
-    process.env.GROUP_INTERNAL_URL = 'http://group-service:5006';
-    process.env.GROUP_API_URL = 'https://group-api.tumbaland.eu';
-    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
-
-    await getGroupOwner('group-1');
-
-    // The public variable is what the frontends hand to the browser, so it can
-    // never be pointed inward — this is the server-side half of that split.
-    expect(global.fetch).toHaveBeenCalledWith(
-      'http://group-service:5006/internal/groups/group-1/owner',
-      expect.anything()
-    );
-  });
-
-  it('falls back to the public URL, so local dev and un-migrated deploys still work', async () => {
-    delete process.env.GROUP_INTERNAL_URL;
-    process.env.GROUP_API_URL = 'https://group-api.tumbaland.eu';
-    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
-
-    await getGroupOwner('group-1');
-
-    expect(global.fetch).toHaveBeenCalledWith(
-      'https://group-api.tumbaland.eu/internal/groups/group-1/owner',
-      expect.anything()
-    );
-  });
-
-  it('never caches a failure, so recovery is immediate rather than a minute later', async () => {
-    (global.fetch as jest.Mock).mockRejectedValueOnce(new Error('ECONNREFUSED')).mockResolvedValue(ownerResponse());
-
-    const failed = await getGroupOwner('group-1');
-    const recovered = await getGroupOwner('group-1');
-
-    expect(failed).toBeNull();
-    expect(recovered?.ownerEmail).toBe('owner@example.com');
-  });
-
-  it('never caches a 404 either — a bad id must not spend a cache slot', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(jsonResponse({ success: false }, 404));
-
-    await getGroupOwner('missing');
-    await getGroupOwner('missing');
-
-    expect(global.fetch).toHaveBeenCalledTimes(2);
-  });
-});
-
-describe('cache bounds', () => {
-  it('evicts the oldest entries instead of growing without limit', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
-
-    for (let i = 0; i < 5_001; i++) {
-      await getGroupOwner(`group-${i}`);
-    }
-    const callsAfterFill = (global.fetch as jest.Mock).mock.calls.length;
-
-    // The very first group was evicted by the 5001st, so this is a refetch.
-    await getGroupOwner('group-0');
-    expect((global.fetch as jest.Mock).mock.calls.length).toBe(callsAfterFill + 1);
-
-    // The most recent group is still cached.
-    await getGroupOwner('group-5000');
-    expect((global.fetch as jest.Mock).mock.calls.length).toBe(callsAfterFill + 1);
-  });
-});

package/src/groups/client.ts

@@ -1,182 +0,0 @@
-import logger from '../logging/logger';
-
-/**
- * Who a group's pooled usage bills to, read over the internal-service channel.
- *
- * The JWT carries `groups` — the ids a user belongs to — but never says who
- * owns them, and no service outside group-service has the collection. So a
- * chokepoint that needs the *quota subject* for a group album or a group ticker
- * has to ask. See MONETIZATION.md's note on why that subject is the owner and
- * not the uploader.
- *
- * Same 60s TTL as the entitlement client, for a weaker reason: ownership moves
- * far more rarely than a plan does, so the cache could be much longer, but a
- * stale owner bills the wrong person and one shared number is one fewer thing
- * to reason about. The enforcement points are writes, so the traffic is low
- * either way.
- */
-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;
-
-export interface GroupOwner {
-  groupId: string;
-  ownerEmail: string;
-  memberCount: number;
-  /** Soft-deleted groups still resolve: their photos still occupy storage. */
-  deleted: boolean;
-  /** True when group-service could not be reached and nothing was resolved. */
-  stale?: boolean;
-}
-
-interface CacheEntry {
-  value: GroupOwner;
-  expiresAt: number;
-}
-
-const cache = new Map<string, CacheEntry>();
-
-/**
- * Concurrent callers for one group share a request — a burst of uploads into
- * the same shared album is the expected shape of this traffic.
- */
-const inFlight = new Map<string, Promise<GroupOwner | null>>();
-
-function putInCache(groupId: string, value: GroupOwner): 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(groupId, { value, expiresAt: Date.now() + CACHE_TTL_MS });
-}
-
-interface GroupOwnerResponse {
-  success?: boolean;
-  groupId?: string;
-  ownerEmail?: string;
-  memberCount?: number;
-  deleted?: boolean;
-}
-
-/**
- * Prefers the container-network address over the public hostname.
- *
- * `GROUP_API_URL` cannot simply be pointed inward: the frontend containers
- * template that same variable into the `config.json` the *browser* downloads,
- * so a Docker-internal value there breaks every group call in the UI. One
- * variable genuinely has two consumers with incompatible needs, so this is the
- * server-side half of it.
- *
- * Falling back to the public URL keeps local dev (where only `GROUP_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.
- */
-export function internalGroupUrl(): string | undefined {
-  return process.env.GROUP_INTERNAL_URL || process.env.GROUP_API_URL;
-}
-
-async function fetchGroupOwner(groupId: string): Promise<GroupOwner | null> {
-  const baseUrl = internalGroupUrl();
-  const token = process.env.INTERNAL_SERVICE_TOKEN;
-  const serviceId = process.env.SERVICE_NAME || 'unknown-service';
-
-  if (!baseUrl || !token) {
-    logger.error('Group owner lookup not configured', {
-      hasGroupApiUrl: Boolean(baseUrl),
-      hasInternalToken: Boolean(token)
-    });
-    return null;
-  }
-
-  try {
-    const response = await fetch(`${baseUrl}/internal/groups/${encodeURIComponent(groupId)}/owner`, {
-      method: 'GET',
-      headers: {
-        'Content-Type': 'application/json',
-        'x-internal-token': token,
-        'x-service-id': serviceId
-      },
-      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
-    });
-
-    // A 404 is an answer, not an outage: the group is gone. Distinguished from
-    // an unreachable service because the two want opposite handling — one is
-    // permanent and cacheable, the other must be retried on the next request.
-    if (response.status === 404) {
-      logger.warn('Group owner lookup found no such group', { groupId });
-      return null;
-    }
-
-    if (!response.ok) {
-      logger.error('Group owner lookup failed', { groupId, status: response.status });
-      return null;
-    }
-
-    const body = (await response.json()) as GroupOwnerResponse;
-    if (!body.ownerEmail) {
-      logger.error('Group owner lookup returned no owner', { groupId });
-      return null;
-    }
-
-    return {
-      groupId: body.groupId ?? groupId,
-      ownerEmail: body.ownerEmail.trim().toLowerCase(),
-      memberCount: body.memberCount ?? 0,
-      deleted: body.deleted === true
-    };
-  } catch (err) {
-    logger.error('Group owner lookup errored', { groupId, error: (err as Error)?.message });
-    return null;
-  }
-}
-
-/**
- * The group's owner, cached for {@link CACHE_TTL_MS}, or `null` when the group
- * does not exist or group-service could not answer.
- *
- * Nothing negative is cached — neither a missing group nor a failure. A group
- * that 404s is nearly always a caller passing a bad id, so caching it would
- * spend memory on garbage, and caching a failure would keep billing the wrong
- * subject for a minute after the outage ended.
- */
-export async function getGroupOwner(groupId: string): Promise<GroupOwner | null> {
-  const key = String(groupId).trim();
-  if (!key) return null;
-
-  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 = fetchGroupOwner(key)
-    .then(value => {
-      if (value) putInCache(key, value);
-      return value;
-    })
-    .finally(() => {
-      inFlight.delete(key);
-    });
-
-  inFlight.set(key, request);
-  return request;
-}
-
-/**
- * Drop a group's cached owner. Call after anything that moves the `owner` role,
- * to collapse the window in which usage bills to the previous owner.
- */
-export function invalidateGroupOwner(groupId: string): void {
-  cache.delete(String(groupId).trim());
-}
-
-/** Empties the whole cache. Test seam, and a lever after a bulk ownership edit. */
-export function clearGroupOwnerCache(): void {
-  cache.clear();
-  inFlight.clear();
-}

package/src/groups/index.ts

@@ -1,7 +0,0 @@
-export { getGroupOwner, invalidateGroupOwner, clearGroupOwnerCache } from './client';
-export type { GroupOwner } from './client';
-
-export { groupOwnerSubject } from './subject';
-export type { GroupIdResolver } from './subject';
-
-export { getUserGroupIds, currentGroupsOf, clearMembershipCache } from './membership';

package/src/groups/membership.test.ts

@@ -1,84 +0,0 @@
-import { clearMembershipCache, currentGroupsOf, getUserGroupIds } from './membership';
-import logger from '../logging/logger';
-
-jest.mock('../logging/logger', () => ({ __esModule: true, default: { error: jest.fn(), warn: jest.fn() } }));
-
-const ORIGINAL_ENV = process.env;
-const answer = (data: unknown, ok = true, status = 200) =>
-  ({ ok, status, json: async () => ({ success: ok, data }) }) as unknown as Response;
-
-beforeEach(() => {
-  clearMembershipCache();
-  jest.useRealTimers();
-  process.env = {
-    ...ORIGINAL_ENV,
-    GROUP_INTERNAL_URL: 'http://group-service:5006',
-    INTERNAL_SERVICE_TOKEN: 'internal-token',
-    SERVICE_NAME: 'album-service'
-  };
-  global.fetch = jest.fn().mockResolvedValue(answer(['g1', 'g2']));
-});
-
-afterAll(() => {
-  process.env = ORIGINAL_ENV;
-});
-
-it('asks group-service over the internal channel', async () => {
-  await expect(getUserGroupIds('Ada@Example.com')).resolves.toEqual(['g1', 'g2']);
-
-  expect(global.fetch).toHaveBeenCalledWith(
-    'http://group-service:5006/api/groups/mine/ids?userEmail=ada%40example.com',
-    expect.objectContaining({
-      headers: expect.objectContaining({ 'x-internal-token': 'internal-token', 'x-service-id': 'album-service' })
-    })
-  );
-});
-
-it('answers from the cache for 30 seconds, then asks again', async () => {
-  jest.useFakeTimers();
-
-  await getUserGroupIds('ada@example.com');
-  await getUserGroupIds('ADA@example.com');
-  expect(global.fetch).toHaveBeenCalledTimes(1);
-
-  jest.advanceTimersByTime(30_001);
-  await getUserGroupIds('ada@example.com');
-  expect(global.fetch).toHaveBeenCalledTimes(2);
-});
-
-it('shares one request between callers asking at the same time', async () => {
-  await Promise.all([getUserGroupIds('ada@example.com'), getUserGroupIds('ada@example.com')]);
-
-  expect(global.fetch).toHaveBeenCalledTimes(1);
-});
-
-it('keeps the last known membership while group-service is unreachable', async () => {
-  jest.useFakeTimers();
-  await getUserGroupIds('ada@example.com');
-  jest.advanceTimersByTime(30_001);
-  (global.fetch as jest.Mock).mockRejectedValue(new Error('connect ECONNREFUSED'));
-
-  await expect(getUserGroupIds('ada@example.com')).resolves.toEqual(['g1', 'g2']);
-  expect(logger.warn).toHaveBeenCalled();
-});
-
-it('grants no groups when it has never been able to ask', async () => {
-  (global.fetch as jest.Mock).mockResolvedValue(answer(null, false, 503));
-
-  await expect(getUserGroupIds('ada@example.com')).resolves.toEqual([]);
-  expect(logger.error).toHaveBeenCalled();
-});
-
-it('grants no groups when not configured, without calling anything', async () => {
-  delete process.env.GROUP_INTERNAL_URL;
-  delete process.env.GROUP_API_URL;
-
-  await expect(getUserGroupIds('ada@example.com')).resolves.toEqual([]);
-  expect(global.fetch).not.toHaveBeenCalled();
-});
-
-it('never takes the groups from the token', async () => {
-  (global.fetch as jest.Mock).mockResolvedValue(answer(['g2']));
-
-  await expect(currentGroupsOf({ email: 'ada@example.com', groups: ['g1', 'g9'] })).resolves.toEqual(['g2']);
-});