@bevel-software/platform-core-backend 0.9.1 → 0.11.0

package/src/modules/update-check/__tests__/update-check.service.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  UpdateCheckService,
+  isNewerVersion,
+  parseReleaseVersion,
+} from '../update-check.service.js';
+
+/**
+ * The update check's contract: lazy, cached, and SILENT on failure. The one
+ * thing it must never do is turn an offline deployment (or a GitHub hiccup,
+ * or a weird tag) into an error a user sees — every degraded path resolves to
+ * `updateAvailable: false`.
+ */
+
+/** A fetch stub answering like the GitHub releases endpoint. */
+function githubFetch(tag: string, notesUrl = 'https://github.com/Bevel-Software/Hexis/releases/tag/' + tag) {
+  return vi.fn().mockResolvedValue({
+    ok: true,
+    json: async () => ({ tag_name: tag, html_url: notesUrl }),
+  }) as unknown as typeof fetch & ReturnType<typeof vi.fn>;
+}
+
+function service(opts: {
+  enabled?: boolean;
+  current?: string;
+  fetchFn?: typeof fetch;
+  now?: () => number;
+}) {
+  return new UpdateCheckService({
+    enabled: opts.enabled ?? true,
+    currentVersion: opts.current ?? '0.9.1',
+    fetchFn: opts.fetchFn,
+    now: opts.now,
+  });
+}
+
+describe('version comparison', () => {
+  it('compares numerically per part, not as strings', () => {
+    expect(isNewerVersion('0.10.0', '0.9.1')).toBe(true);
+    expect(isNewerVersion('1.0.0', '0.99.99')).toBe(true);
+    expect(isNewerVersion('0.9.2', '0.9.1')).toBe(true);
+  });
+
+  it('equal or older is not newer', () => {
+    expect(isNewerVersion('0.9.1', '0.9.1')).toBe(false);
+    expect(isNewerVersion('0.9.0', '0.9.1')).toBe(false);
+    expect(isNewerVersion('0.8.9', '0.9.1')).toBe(false);
+  });
+
+  it('tolerates a leading v and refuses prerelease/malformed tags', () => {
+    expect(parseReleaseVersion('v0.10.0')).toEqual([0, 10, 0]);
+    expect(parseReleaseVersion('0.10.0-rc.1')).toBeNull();
+    expect(parseReleaseVersion('nightly')).toBeNull();
+    expect(parseReleaseVersion('')).toBeNull();
+    expect(isNewerVersion('0.10.0-rc.1', '0.9.1')).toBe(false);
+  });
+
+  it('an unparseable RUNNING version never announces an update', () => {
+    // `resolveAppVersion` answers 'unknown' when the manifest is unreadable —
+    // that must fail toward silence, not toward "everything is newer".
+    expect(isNewerVersion('0.10.0', 'unknown')).toBe(false);
+  });
+});
+
+describe('UpdateCheckService.check', () => {
+  it('reports an update when the published release is newer', async () => {
+    const fetchFn = githubFetch('v0.10.0');
+    const result = await service({ fetchFn }).check();
+    expect(result).toEqual({
+      updateAvailable: true,
+      current: '0.9.1',
+      latest: '0.10.0',
+      notesUrl: 'https://github.com/Bevel-Software/Hexis/releases/tag/v0.10.0',
+    });
+    // No credentials, ever — the request is the whole payload.
+    const [, init] = fetchFn.mock.calls[0] as [string, RequestInit];
+    expect(new Headers(init.headers).has('authorization')).toBe(false);
+    expect(new Headers(init.headers).get('accept')).toBe('application/vnd.github+json');
+  });
+
+  it('reports no update when equal or when the deployment is ahead', async () => {
+    expect(await service({ fetchFn: githubFetch('v0.9.1') }).check()).toMatchObject({
+      updateAvailable: false,
+      current: '0.9.1',
+      latest: '0.9.1',
+    });
+    expect(
+      await service({ fetchFn: githubFetch('v0.9.0'), current: '0.9.1' }).check(),
+    ).toMatchObject({ updateAvailable: false });
+  });
+
+  it('resolves a prerelease or malformed tag to "no update" without throwing', async () => {
+    const result = await service({ fetchFn: githubFetch('v0.10.0-rc.1') }).check();
+    expect(result.updateAvailable).toBe(false);
+    // A tag that didn't parse is not offered as "latest".
+    expect(result.latest).toBeUndefined();
+  });
+
+  it('refuses a double-prefixed tag — vv99.0.0 must not shed one v and pass', async () => {
+    // The RAW tag is what gets validated: stripping first would leave v99.0.0,
+    // which the parser's lenient `v?` accepts.
+    const result = await service({ fetchFn: githubFetch('vv99.0.0') }).check();
+    expect(result.updateAvailable).toBe(false);
+    expect(result.latest).toBeUndefined();
+  });
+
+  it('disabled: answers immediately and never touches the network', async () => {
+    const fetchFn = githubFetch('v99.0.0');
+    const result = await service({ enabled: false, fetchFn }).check();
+    expect(result).toEqual({ updateAvailable: false, current: '0.9.1' });
+    expect(fetchFn).not.toHaveBeenCalled();
+  });
+
+  it('a failed fetch is silent, and cached so a dead network is not re-probed', async () => {
+    let now = 0;
+    const fetchFn = vi.fn().mockRejectedValue(new Error('ENOTFOUND api.github.com'));
+    const svc = service({ fetchFn: fetchFn as unknown as typeof fetch, now: () => now });
+
+    expect(await svc.check()).toEqual({ updateAvailable: false, current: '0.9.1' });
+    // Within the failure TTL (~15min): served from cache.
+    now = 14 * 60 * 1000;
+    await svc.check();
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+    // Past it: retried.
+    now = 16 * 60 * 1000;
+    await svc.check();
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+  });
+
+  it('a success is cached for hours across requests', async () => {
+    let now = 0;
+    const fetchFn = githubFetch('v0.10.0');
+    const svc = service({ fetchFn, now: () => now });
+
+    const first = await svc.check();
+    now = 5 * 60 * 60 * 1000; // 5h — inside the 6h TTL
+    const second = await svc.check();
+    expect(second).toEqual(first);
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+
+    now = 7 * 60 * 60 * 1000; // past the TTL — refreshed
+    await svc.check();
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+  });
+
+  it('concurrent requests share one in-flight fetch', async () => {
+    let release!: (value: unknown) => void;
+    const gate = new Promise((resolve) => {
+      release = resolve;
+    });
+    const fetchFn = vi.fn().mockImplementation(async () => {
+      await gate;
+      return { ok: true, json: async () => ({ tag_name: 'v0.10.0', html_url: 'u' }) };
+    });
+    const svc = service({ fetchFn: fetchFn as unknown as typeof fetch });
+
+    const [a, b] = [svc.check(), svc.check()];
+    release(undefined);
+    expect(await a).toEqual(await b);
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('treats a non-2xx answer like any other failure: silent false', async () => {
+    const fetchFn = vi
+      .fn()
+      .mockResolvedValue({ ok: false, status: 403, json: async () => ({}) });
+    const result = await service({ fetchFn: fetchFn as unknown as typeof fetch }).check();
+    expect(result).toEqual({ updateAvailable: false, current: '0.9.1' });
+  });
+});

package/src/modules/update-check/update-check.routes.ts

@@ -0,0 +1,28 @@
+import express from 'express';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import type { UpdateCheckService } from './update-check.service.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+
+/**
+ * `GET /api/update-check` — ADMIN-ONLY (same `requireAdmin` shape as the setup
+ * routes): admins are the audience of the banner and the only ones who can act
+ * on it, and there is no reason to narrate the deployment's patch level to
+ * everyone else. The service behind it does the caching, so this is safe to
+ * call as often as the frontend likes.
+ */
+export function createUpdateCheckRoutes(
+  service: Pick<UpdateCheckService, 'check'>,
+  adminAccess: IAdminAccessService,
+): express.Router {
+  const router = express.Router();
+
+  router.get('/update-check', async (req, res) => {
+    if (!(await adminAccess.isAdmin(req.userEmail))) {
+      res.status(403).json({ error: 'Admins only' });
+      return;
+    }
+    res.json(await service.check());
+  });
+
+  return router;
+}

package/src/modules/update-check/update-check.service.ts

@@ -0,0 +1,130 @@
+/**
+ * In-app update check — the server learns the newest published Hexis release
+ * and tells admins when the running deployment is behind (the pattern Immich
+ * and Gitea use: a quiet banner, no auto-anything).
+ *
+ * Deliberate shape:
+ *
+ *  - LAZY, never on a timer. The first `check()` triggers the fetch; a
+ *    deployment nobody looks at makes zero calls. Results are cached (~6h),
+ *    concurrent callers share one in-flight request.
+ *  - The request goes to api.github.com and carries NOTHING but itself — no
+ *    auth token (public repo; this must never hold credentials), no
+ *    identifier, no telemetry. `UPDATE_CHECK=false` removes even that.
+ *  - FAILURE IS SILENT. Offline and air-gapped deployments must stay quiet,
+ *    not broken: a failed fetch is cached briefly (~15min, so a dead network
+ *    isn't re-probed per request) and reported as "no update available".
+ *  - Only a clean `x.y.z` newer than the running version counts. Prerelease
+ *    or malformed tags — and a running version we can't parse — resolve to
+ *    "no update" rather than a guess or a throw.
+ */
+
+export interface UpdateCheckResult {
+  updateAvailable: boolean;
+  /** The running version (this build's release version). */
+  current: string;
+  /** Newest published release, when the check reached GitHub and parsed one. */
+  latest?: string;
+  /** The release-notes page of that release. */
+  notesUrl?: string;
+}
+
+const RELEASES_LATEST_URL =
+  'https://api.github.com/repos/Bevel-Software/Hexis/releases/latest';
+const SUCCESS_TTL_MS = 6 * 60 * 60 * 1000;
+const FAILURE_TTL_MS = 15 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5_000;
+
+/** `v1.2.3` / `1.2.3` → `[1,2,3]`; anything else (prerelease included) → null. */
+export function parseReleaseVersion(raw: string): [number, number, number] | null {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(raw.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * Whether `latest` is STRICTLY newer than `current`. Numeric per-part compare
+ * (no string compare — `0.10.0` > `0.9.1`). Either side failing to parse is
+ * `false`: an answer we can't trust is not an update announcement.
+ */
+export function isNewerVersion(latest: string, current: string): boolean {
+  const a = parseReleaseVersion(latest);
+  const b = parseReleaseVersion(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return false;
+}
+
+export class UpdateCheckService {
+  private cached: { result: UpdateCheckResult; expiresAt: number } | null = null;
+  private inFlight: Promise<UpdateCheckResult> | null = null;
+
+  constructor(
+    private readonly opts: {
+      /** `UPDATE_CHECK` — false means no network, ever. */
+      enabled: boolean;
+      /** The running release version (see `resolveAppVersion`). */
+      currentVersion: string;
+      /** Injectable for tests; defaults to global fetch. */
+      fetchFn?: typeof fetch;
+      /** Injectable for tests; defaults to the GitHub releases endpoint. */
+      releasesUrl?: string;
+      /** Injectable clock for TTL tests; defaults to Date.now. */
+      now?: () => number;
+    },
+  ) {}
+
+  async check(): Promise<UpdateCheckResult> {
+    if (!this.opts.enabled) {
+      return { updateAvailable: false, current: this.opts.currentVersion };
+    }
+    const now = (this.opts.now ?? Date.now)();
+    if (this.cached && now < this.cached.expiresAt) return this.cached.result;
+    // One request serves every concurrent caller; `finally` clears the slot so
+    // the NEXT check after settlement reads the cache (or starts a fresh
+    // fetch once the TTL lapses).
+    this.inFlight ??= this.fetchAndCache().finally(() => {
+      this.inFlight = null;
+    });
+    return this.inFlight;
+  }
+
+  private async fetchAndCache(): Promise<UpdateCheckResult> {
+    const current = this.opts.currentVersion;
+    const nowFn = this.opts.now ?? Date.now;
+    try {
+      const fetchFn = this.opts.fetchFn ?? fetch;
+      const res = await fetchFn(this.opts.releasesUrl ?? RELEASES_LATEST_URL, {
+        headers: { Accept: 'application/vnd.github+json' },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      });
+      if (!res.ok) throw new Error(`GitHub answered ${res.status}`);
+      const body = (await res.json()) as { tag_name?: unknown; html_url?: unknown };
+      const tag = typeof body.tag_name === 'string' ? body.tag_name.trim() : '';
+      // Validate the RAW tag before normalizing: a malformed `vv1.2.3` would
+      // otherwise shed one prefix and land on `v1.2.3`, which the parser's
+      // lenient `v?` then accepts — announcing a tag we should distrust.
+      const latest = parseReleaseVersion(tag) ? tag.replace(/^v/, '') : '';
+      const notesUrl = typeof body.html_url === 'string' ? body.html_url : undefined;
+      const result: UpdateCheckResult = isNewerVersion(latest, current)
+        ? { updateAvailable: true, current, latest, notesUrl }
+        : // Equal, older, prerelease or malformed: all "no update". `latest`
+          // rides along only when it parsed — a garbage tag is not an answer.
+          {
+            updateAvailable: false,
+            current,
+            ...(parseReleaseVersion(latest) ? { latest } : {}),
+          };
+      this.cached = { result, expiresAt: nowFn() + SUCCESS_TTL_MS };
+      return result;
+    } catch {
+      // Silent by design — no log spam, no error to the UI. The short TTL is
+      // what keeps a dead network from being probed on every request.
+      const result: UpdateCheckResult = { updateAvailable: false, current };
+      this.cached = { result, expiresAt: nowFn() + FAILURE_TTL_MS };
+      return result;
+    }
+  }
+}