From 4e7af0ab57450c2ec385794ddeb7eff9647136b1 Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Thu, 16 Jul 2026 07:07:18 +1200 Subject: [PATCH] #267 Add minimum Immich version to prevent this issue --- app/src/immich.ts | 54 ++++++++++++++++++++++++++--- app/src/index.ts | 5 +++ app/src/types.ts | 9 +++++ app/tests/albumTimeline.test.ts | 7 ++-- app/tests/immichVersion.test.ts | 60 +++++++++++++++++++++++++++++++++ 5 files changed, 127 insertions(+), 8 deletions(-) create mode 100644 app/tests/immichVersion.test.ts diff --git a/app/src/immich.ts b/app/src/immich.ts index b3cac5a..515719c 100644 --- a/app/src/immich.ts +++ b/app/src/immich.ts @@ -3,6 +3,7 @@ import { Asset, AssetType, ImageSize, + ImmichVersion, IncomingShareRequest, KeyType, SharedLink, @@ -287,11 +288,7 @@ async function fetchShareByKey (key: string, password?: string, keyType: KeyType log('Expired link ' + key) } else { if (!Array.isArray(link.assets)) { - // Immich can return a shared link with no `assets` array (seen on - // 3.0.x INDIVIDUAL shares - see #267). The album path above always - // populates `link.assets`, so this only bites non-album shares. - // Treat a missing array as empty rather than letting `.filter` of - // undefined reject and take the whole process down. + // Defensive guard: the returned album should always(?) populate this array log('Shared link ' + key + ' returned no assets array (type ' + link.type + ')') link.assets = [] } @@ -589,6 +586,53 @@ export async function accessible () { return !!(await request('/server/ping')) } +// Minimum Immich server version IPP is compatible with +export const MIN_IMMICH_VERSION: ImmichVersion = { major: 2, minor: 0, patch: 0 } + +const formatVersion = (v: ImmichVersion) => `${v.major}.${v.minor}.${v.patch}` + +/** + * Fetch the Immich server version from the public `/server/version` endpoint + * (no auth required). Returns null if Immich is unreachable or the response + * isn't the expected `{ major, minor, patch }` shape. + */ +export async function getImmichVersion (): Promise { + const res = await request('/server/version') + if (res && typeof res.major === 'number' && typeof res.minor === 'number' && typeof res.patch === 'number') { + return { major: res.major, minor: res.minor, patch: res.patch } + } + return null +} + +/** + * True if `version` is at least MIN_IMMICH_VERSION. A prerelease of the + * minimum version (e.g. 3.0.0-beta) counts as supported. + */ +export function isImmichVersionSupported (version: ImmichVersion): boolean { + if (version.major !== MIN_IMMICH_VERSION.major) return version.major > MIN_IMMICH_VERSION.major + if (version.minor !== MIN_IMMICH_VERSION.minor) return version.minor > MIN_IMMICH_VERSION.minor + return version.patch >= MIN_IMMICH_VERSION.patch +} + +/** + * Startup guard. If we can positively confirm the Immich server is older than + * IPP supports, log and exit rather than silently serving broken album shares. + * If the version can't be determined (Immich not yet reachable at boot, or an + * unexpected response), log a warning and continue - a transient blip must not + * crash-loop the container, and per-request handling still copes. + */ +export async function enforceMinimumImmichVersion (): Promise { + const version = await getImmichVersion() + if (!version) { + log('Could not determine the Immich server version. Check that Immich is reachable and running ' + formatVersion(MIN_IMMICH_VERSION) + ' or newer.') + return + } + if (!isImmichVersionSupported(version)) { + console.error(dayjs().format() + ' FATAL: Immich server is version ' + formatVersion(version) + ', but IPP requires Immich ' + formatVersion(MIN_IMMICH_VERSION) + ' or newer.') + process.exit(1) + } +} + /** * Coerce an unknown `size` parameter from a URL into a valid ImageSize, * defaulting to preview when the input is missing or unrecognised. diff --git a/app/src/index.ts b/app/src/index.ts index 118cb8a..38a2efe 100644 --- a/app/src/index.ts +++ b/app/src/index.ts @@ -5,6 +5,7 @@ import express from 'express' import cookieSession from 'cookie-session' import { accessible, + enforceMinimumImmichVersion, fetchAssetDetail, getKeyTypeFromShare, getShareByKey, @@ -348,6 +349,10 @@ process.on('SIGTERM', () => { const port = Number(process.env.IPP_PORT) || 3000 const server = app.listen(port, () => { console.log(dayjs().format() + ' Server started on port ' + port) + // Bail out early if the Immich server is older than IPP supports, rather + // than silently serving broken album shares. Unknown/unreachable is + // tolerated (logs a warning and continues) - see enforceMinimumImmichVersion. + enforceMinimumImmichVersion().catch(e => console.error('Immich version check failed:', e)) // Clean up any zip-download staging dirs left behind by a previous // run that crashed before its finally block could run sweepStaleStagingDirs().catch(e => console.error('sweepStaleStagingDirs failed:', e)) diff --git a/app/src/types.ts b/app/src/types.ts index 0cc63f3..3972a0e 100644 --- a/app/src/types.ts +++ b/app/src/types.ts @@ -62,6 +62,15 @@ export interface Asset { needsDetail?: boolean; } +/** + * Immich server version as returned by `GET /server/version`. + */ +export interface ImmichVersion { + major: number; + minor: number; + patch: number; +} + /** * One entry of `GET /timeline/buckets` - a time bucket (month) and its count. */ diff --git a/app/tests/albumTimeline.test.ts b/app/tests/albumTimeline.test.ts index 7a598ae..4814293 100644 --- a/app/tests/albumTimeline.test.ts +++ b/app/tests/albumTimeline.test.ts @@ -134,9 +134,10 @@ describe('album timeline enumeration (Immich 3.0)', () => { expect(result.valid).toBe(false) }) - it('does not crash when an individual share returns no assets array (#267)', async () => { - // Immich 3.0.x can return an INDIVIDUAL shared link with no `assets` key. - // `.filter` of undefined used to reject and take the container down. + it('treats a share with no assets array as empty', async () => { + // Defensive guard (see #267): if Immich returns a link whose `assets` + // isn't an array, `.filter` of undefined would reject and, unhandled, + // exit the whole process. Treat it as an empty share instead. const noAssets = { type: 'INDIVIDUAL', key: 'real-key', allowDownload: true } vi.stubGlobal('fetch', vi.fn(async (url: string) => { if (url.includes('/shared-links/me')) return jsonResponse(noAssets) diff --git a/app/tests/immichVersion.test.ts b/app/tests/immichVersion.test.ts new file mode 100644 index 0000000..99e2048 --- /dev/null +++ b/app/tests/immichVersion.test.ts @@ -0,0 +1,60 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest' +import { getImmichVersion, isImmichVersionSupported, MIN_IMMICH_VERSION } from '../src/immich' + +// The startup guard that refuses to run against an Immich server older than +// IPP supports. The floor is 2.0.0 - the columnar timeline API IPP relies on +// to enumerate album shares landed in Immich 2.0. + +function jsonResponse (body: unknown, status = 200) { + return { + ok: status >= 200 && status < 300, + status, + headers: { get: (h: string) => (h.toLowerCase() === 'content-type' ? 'application/json' : null) }, + json: async () => body, + text: async () => JSON.stringify(body) + } +} + +describe('isImmichVersionSupported', () => { + it('accepts exactly the minimum version', () => { + expect(isImmichVersionSupported(MIN_IMMICH_VERSION)).toBe(true) + }) + + it('accepts newer major/minor/patch across the 2.x and 3.x lines', () => { + expect(isImmichVersionSupported({ major: 2, minor: 7, patch: 5 })).toBe(true) + expect(isImmichVersionSupported({ major: 3, minor: 0, patch: 2 })).toBe(true) + expect(isImmichVersionSupported({ major: 4, minor: 0, patch: 0 })).toBe(true) + }) + + it('rejects 1.x, which predates the columnar timeline API', () => { + expect(isImmichVersionSupported({ major: 1, minor: 137, patch: 3 })).toBe(false) + expect(isImmichVersionSupported({ major: 1, minor: 125, patch: 7 })).toBe(false) + }) +}) + +describe('getImmichVersion', () => { + beforeEach(() => { + process.env.IMMICH_URL = 'http://immich.test' + }) + afterEach(() => { + vi.unstubAllGlobals() + }) + + it('parses the /server/version response', async () => { + vi.stubGlobal('fetch', vi.fn(async (url: string) => { + if (url.includes('/server/version')) return jsonResponse({ major: 3, minor: 0, patch: 2, prerelease: null }) + throw new Error('Unexpected fetch to ' + url) + })) + expect(await getImmichVersion()).toEqual({ major: 3, minor: 0, patch: 2 }) + }) + + it('returns null when Immich is unreachable', async () => { + vi.stubGlobal('fetch', vi.fn(async () => { throw new Error('ECONNREFUSED') })) + expect(await getImmichVersion()).toBeNull() + }) + + it('returns null on an unexpected response shape', async () => { + vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ version: 'v3.0.2' }))) + expect(await getImmichVersion()).toBeNull() + }) +})