From 255260ccb3fa7305033711670402d9c9ac265a2d Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Tue, 6 Oct 2026 09:23:57 +1300 Subject: [PATCH] Require Immich 3.x; code cleanup --- CONTRIBUTING.md | 10 +- app/src/client/sidebar.ts | 3 +- app/src/config/access.ts | 5 - app/src/config/migrations.ts | 241 ------------------ app/src/gallery/exif.ts | 40 +-- app/src/gallery/filename.ts | 37 +++ app/src/immich.ts | 6 +- app/src/index.ts | 21 +- app/src/share.ts | 43 +++- app/src/stream/asset.ts | 11 +- app/src/stream/download.ts | 39 +-- app/src/utils/log.ts | 5 - app/tests/albumTimeline.test.ts | 51 ++++ app/tests/assetMetadata.test.ts | 35 +-- app/tests/assetStream.test.ts | 35 +++ app/tests/canDownload.test.ts | 47 ++++ app/tests/contentDisposition.test.ts | 3 +- app/tests/downloadAssets.test.ts | 2 + app/tests/migrations.test.ts | 364 --------------------------- docs/.vitepress/config.ts | 2 +- docs/README.md | 2 +- docs/config/error-responses.md | 2 + docs/config/index.md | 2 +- docs/config/upgrading.md | 46 ++-- docs/installation.md | 2 +- docs/upgrading.md | 13 +- shared/src/config/loader.ts | 11 +- shared/src/http.ts | 18 +- shared/src/immich/client.ts | 2 +- shared/src/invalidRequest.ts | 21 +- shared/src/types.ts | 5 - shared/tests/errorHandling.test.ts | 13 +- shared/tests/immichVersion.test.ts | 10 +- 33 files changed, 347 insertions(+), 800 deletions(-) delete mode 100644 app/src/config/access.ts delete mode 100644 app/src/config/migrations.ts delete mode 100644 app/src/utils/log.ts create mode 100644 app/tests/canDownload.test.ts delete mode 100644 app/tests/migrations.test.ts diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a765d6..b010be8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,10 +39,10 @@ shared/ @ipp/core - read-side only, knows nothing about galler types.ts Share-level types (SharedLink, Asset, KeyType, ...) immich/client.ts Immich API request helper, URL building, key/id checks, version guard immich/share.ts fetchSharedLink, password login + token cache, auth headers, title - config/loader.ts loadConfig() reads env / file; the app passes its default path and migrations + config/loader.ts loadConfig() reads env / file; the app passes its default path config/access.ts getConfigOption() reads the loaded config - http.ts Operator-configured response headers, asyncHandler, errorHandler - invalidRequest.ts The 404 policy, with setInvalidRequestHandler for the app's own handler file + http.ts Operator-configured and no-store response headers, asyncHandler + invalidRequest.ts The 404 policy (never cached), errorHandler, and setInvalidRequestHandler for the app's own handler file session.ts Cookie session, decodeCookie, unlock handler, invalid-password response encrypt.ts Cookie-session encryption for password-protected shares utils/ log, sanitize (filenames), text (escaping), ttlLruCache, webStream @@ -61,8 +61,6 @@ app/ share.ts Share-level policy (canDownload, expiry date, motion photos) types.ts Gallery-only server types version.ts Release version and the static-asset cache-busting segment - config/ - migrations.ts Backward-compat shims for legacy config-key shapes gallery/ builder.ts Gallery view-model construction exif.ts EXIF / location whitelisting for the sidebar @@ -160,7 +158,7 @@ Beyond unit tests, exercise the gallery end-to-end against a real Immich instanc **Streaming.** Assets are streamed from Immich to the client without buffering to disk. Keep it that way. The `archiver` zip flow is also fully streamed (with per-asset retry, an idle-timeout transform, and abort-on-failure semantics). -**File organisation.** Group functions by cohesion, not by file count. A file deserves its own name when it carries a coherent concept worth a separate filename - "filename sanitization" or "config loader" pass; "narrow unknown to string" does not. When several small helpers share a theme, group them in one file (`utils/text.ts` for escaping + narrowing; `share.ts` for share-level info + policy). When a single concern is substantial enough to dominate a file on its own, give it its own name (`config/migrations.ts`, `stream/download.ts`). IPP optimises for audit reading rather than tree-shakeable reuse, so fewer cohesive files beat many one-export micro-modules. Same lens applies on the client (`app/src/client/`): each module is a viewport-of-code that earns its name. +**File organisation.** Group functions by cohesion, not by file count. A file deserves its own name when it carries a coherent concept worth a separate filename - "filename sanitization" or "config loader" pass; "narrow unknown to string" does not. When several small helpers share a theme, group them in one file (`utils/text.ts` for escaping + narrowing; `share.ts` for share-level info + policy). When a single concern is substantial enough to dominate a file on its own, give it its own name (`stream/download.ts`). IPP optimises for audit reading rather than tree-shakeable reuse, so fewer cohesive files beat many one-export micro-modules. Same lens applies on the client (`app/src/client/`): each module is a viewport-of-code that earns its name. Where to put a new function: ask what category of thing it is, not where it gets called from. Share-level policy decisions and share-derived info go in `share.ts`. Per-asset view-model transforms (filename derivation, EXIF whitelisting) go alongside `gallery/builder.ts`. HTTP response setup driven by operator config goes in core's `http.ts`. Streaming pipelines go in `stream/`. If a new function doesn't fit any existing category, prefer adding to the closest existing file over creating a new single-function module - revisit when a real second member of the category appears. diff --git a/app/src/client/sidebar.ts b/app/src/client/sidebar.ts index f87433a..7eb1b66 100644 --- a/app/src/client/sidebar.ts +++ b/app/src/client/sidebar.ts @@ -127,8 +127,7 @@ function writePersistedState (open: boolean) { // ----- content rendering --------------------------------------------------- // // Sidebar UI placement for each metadata field. Server-side gating lives in -// `gallery/exif.ts` (rules table); legacy-config migration lives in -// `config/migrations.ts`. Adding a new field requires updating all three. +// `gallery/exif.ts` (rules table). Adding a new field requires updating both. function renderContents (root: HTMLElement, item: GalleryItem | undefined) { root.replaceChildren() diff --git a/app/src/config/access.ts b/app/src/config/access.ts deleted file mode 100644 index 87a4504..0000000 --- a/app/src/config/access.ts +++ /dev/null @@ -1,5 +0,0 @@ -/* - Kept for operators who mount a copy of invalidRequestHandler.js taken from - IPP 3.x, which requires './config/access'. Delete in 4.0 with an upgrade note. -*/ -export { getConfigOption } from '@ipp/core' diff --git a/app/src/config/migrations.ts b/app/src/config/migrations.ts deleted file mode 100644 index b087e46..0000000 --- a/app/src/config/migrations.ts +++ /dev/null @@ -1,241 +0,0 @@ -/* - Backward-compatibility shims that map legacy `config.json` key shapes - onto their current locations. Each shim mutates the in-memory config - only - the on-disk file is never touched, so read-only mounts are safe. - - CONVENTION for keeping this file pruneable: - 1. Every shim function starts its JSDoc with a `SHIM:` marker line. - To list all current shims: grep -rn 'SHIM:' app/src - 2. Every shim is registered in `SHIMS` below with the version it - should be deleted in. When that version comes up, remove the - function, its registry entry, and any tests for it. - 3. Each shim should be self-contained and side-effect-free beyond - mutating the passed-in config. No imports from app code. -*/ - -type Config = Record - -interface Shim { - name: string - removeIn: string - apply: (config: Config) => void -} - -const SHIMS: Shim[] = [ - { name: 'lightGallery', removeIn: 'v3.0', apply: applyLightGalleryShim }, - { name: 'topLevelGallery', removeIn: 'v3.0', apply: applyTopLevelGalleryShim }, - { name: 'descriptionSplit', removeIn: 'v3.0', apply: applyDescriptionSplitShim }, - { name: 'metadataEnabled', removeIn: 'v3.0', apply: applyMetadataEnabledShim }, - { name: 'downloadOriginalPhoto', removeIn: 'v4.0', apply: applyDownloadQualityShim }, - { name: 'allowDownloadAll', removeIn: 'v4.0', apply: applyAllowDownloadRenameShim } -] - -/** - * Apply every registered legacy-config shim to `config` in place. - * Called from `loadConfig()` after reading the file or env JSON. - */ -export function applyMigrations (config: Config): void { - for (const shim of SHIMS) shim.apply(config) -} - -/** - * SHIM: lightGallery -> ipp.lightbox (1.x users with a legacy - * `lightGallery.*` config section). Maps `lightGallery.controls`, - * `lightGallery.download`, and `lightGallery.mobileSettings.controls` - * onto `ipp.lightbox.*`. - */ -function applyLightGalleryShim (config: Config): void { - if (!config.lightGallery || typeof config.lightGallery !== 'object') return - - const lg = config.lightGallery as Record - const mobile = (lg.mobileSettings || {}) as Record - const ipp = (config.ipp || (config.ipp = {})) as Record - const lightbox = (ipp.lightbox || (ipp.lightbox = {})) as Record - - if (lightbox.showArrows === undefined && lg.controls !== undefined) { - lightbox.showArrows = !!lg.controls - } - if (lightbox.showDownload === undefined && lg.download !== undefined) { - lightbox.showDownload = !!lg.download - } - if (lightbox.mobileArrows === undefined && mobile.controls !== undefined) { - lightbox.mobileArrows = !!mobile.controls - } - - console.log( - '[IPP] The `lightGallery` config section is deprecated; relevant keys ' + - 'have been mapped to `ipp.lightbox.*`. See README for the current options.' - ) -} - -/** - * SHIM: downloadOriginalPhoto -> maxDownloadQuality. The boolean is superseded - * by the `preview | fullsize | original` tier. Maps `true -> 'original'`, - * `false -> 'preview'`, only when `maxDownloadQuality` isn't already set. - */ -function applyDownloadQualityShim (config: Config): void { - const ipp = (config.ipp || (config.ipp = {})) as Record - if (typeof ipp.downloadOriginalPhoto !== 'boolean') return - if (ipp.maxDownloadQuality !== undefined) return - - ipp.maxDownloadQuality = ipp.downloadOriginalPhoto ? 'original' : 'preview' - - console.log( - '[IPP] `ipp.downloadOriginalPhoto` is deprecated; it has been mapped to ' + - '`ipp.maxDownloadQuality` (' + JSON.stringify(ipp.maxDownloadQuality) + - '). See README for the new `maxDownloadQuality` / `maxZoomQuality` options.' - ) -} - -/** - * SHIM: allowDownloadAll -> allowDownload (rename, same 0/1/2 values). Maps the - * legacy key forward only when the new one hasn't been set. - */ -function applyAllowDownloadRenameShim (config: Config): void { - const ipp = (config.ipp || (config.ipp = {})) as Record - if (ipp.allowDownloadAll === undefined) return - if (ipp.allowDownload !== undefined) return - - ipp.allowDownload = ipp.allowDownloadAll - - console.log( - '[IPP] `ipp.allowDownloadAll` has been renamed to `ipp.allowDownload` ' + - '(same `0` / `1` / `2` values). Please update your config.json. See README.' - ) -} - -/** - * SHIM: top-level ipp.* gallery keys -> ipp.gallery.*. Gallery-related - * keys that used to live directly on `ipp` now live under `ipp.gallery`. - * Maps legacy keys forward, only filling in fields the user hasn't - * already set on the new path. - */ -function applyTopLevelGalleryShim (config: Config): void { - const ipp = (config.ipp || (config.ipp = {})) as Record - const galleryKeyMigrations: Array<[string, string]> = [ - ['singleImageGallery', 'singleImage'], - ['singleItemAutoOpen', 'singleItemAutoOpen'], - ['showGalleryTitle', 'showTitle'], - ['showGalleryDescription', 'showDescription'], - ['groupGalleryByDate', 'groupByDate'] - ] - const legacyPresent = galleryKeyMigrations.some(([oldKey]) => ipp[oldKey] !== undefined) - if (!legacyPresent) return - - const gallery = (ipp.gallery || (ipp.gallery = {})) as Record - for (const [oldKey, newKey] of galleryKeyMigrations) { - if (ipp[oldKey] !== undefined && gallery[newKey] === undefined) { - gallery[newKey] = ipp[oldKey] - } - } - - console.log( - '[IPP] Top-level gallery keys (singleImageGallery, singleItemAutoOpen, ' + - 'showGalleryTitle, showGalleryDescription, groupGalleryByDate) are ' + - 'deprecated; please move them under `ipp.gallery.*`. See README.' - ) -} - -/** - * SHIM: showMetadata.description boolean -> { caption, sidebar } object. - * `ipp.showMetadata.description` used to be a single boolean controlling - * both the lightbox caption and (later) the sidebar. It is now an object - * with separate `caption` and `sidebar` flags. A legacy boolean value is - * migrated to `{ caption: , sidebar: }` so existing configs - * continue to render description in both places. - */ -function applyDescriptionSplitShim (config: Config): void { - const ipp = (config.ipp || (config.ipp = {})) as Record - const showMetadata = ipp.showMetadata as Record | undefined - if (!showMetadata) return - if (typeof showMetadata.description !== 'boolean') return - - const legacy = showMetadata.description - showMetadata.description = { caption: legacy, sidebar: legacy } - - console.log( - '[IPP] `ipp.showMetadata.description` as a boolean is deprecated; use ' + - '`{ "caption": , "sidebar": }` to control each surface ' + - 'independently. See README.' - ) -} - -/** - * SHIM: showMetadata.{exif,location}.enabled removed. Per-field flags are - * now the only gate, and they all default to `false`. - * - * The 2.3.0 shipped `config.json` had `enabled: false` plus every per- - * field flag set to `true` as documentation. Without this shim those - * `true`s would become live opt-ins on upgrade, silently exposing GPS - * coordinates and EXIF data on share pages. The shim rewrites legacy - * configs in memory at startup: - * - * - `enabled: true`: for each known field in the group, if the per- - * field flag is `undefined`, set it to `true` (the old default). - * Explicit `false` per-field flags are kept, so "all except X" - * patterns continue to work. - * - `enabled: false`: clear any per-field flag that is `true`. Under - * the old semantic those flags were dead code (the master switch - * hid them), so wiping them preserves the "nothing visible" - * behaviour the user had. - * - * The field lists below are frozen at v2.x. If new fields are added in - * future versions, they will not auto-appear for legacy `enabled: true` - * users - which is the safer privacy default and matches the policy the - * new design is establishing. - */ -// These lists are frozen at v2.3.0 and intentionally do NOT track the -// current field set. The server's source-of-truth rules table lives in -// `gallery/exif.ts`, and the sidebar's UI placement lives in -// `client/sidebar.ts`. New fields added in future versions deliberately -// won't auto-appear for legacy `enabled: true` users via this shim - they -// should opt in explicitly. -const LEGACY_EXIF_FIELDS = [ - 'dateTimeOriginal', 'fileName', 'dimensions', 'fileSize', - 'make', 'model', 'lensModel', 'exposureTime', 'iso', - 'fNumber', 'focalLength' -] - -const LEGACY_LOCATION_FIELDS = ['city', 'state', 'country', 'gps'] - -function applyMetadataEnabledShim (config: Config): void { - const ipp = (config.ipp || (config.ipp = {})) as Record - const showMetadata = ipp.showMetadata as Record | undefined - if (!showMetadata) return - - let migrated = false - const groups: Array<[string, string[]]> = [ - ['exif', LEGACY_EXIF_FIELDS], - ['location', LEGACY_LOCATION_FIELDS] - ] - for (const [groupName, fields] of groups) { - const group = showMetadata[groupName] as Record | undefined - if (!group || typeof group !== 'object') continue - if (group.enabled === undefined) continue - - const legacyEnabled = !!group.enabled - delete group.enabled - - if (legacyEnabled) { - for (const field of fields) { - if (group[field] === undefined) group[field] = true - } - } else { - for (const field of fields) { - if (group[field] === true) group[field] = false - } - } - - migrated = true - } - - if (migrated) { - console.log( - '[IPP] `ipp.showMetadata.exif.enabled` / `.location.enabled` are ' + - 'deprecated and have been removed. Per-field flags are now the ' + - 'only gate (all default `false`). Your legacy config has been ' + - 'rewritten in memory to preserve current behaviour; please update ' + - 'your `config.json` to the explicit per-field form. See README.' - ) - } -} diff --git a/app/src/gallery/exif.ts b/app/src/gallery/exif.ts index 6121d8e..040e93a 100644 --- a/app/src/gallery/exif.ts +++ b/app/src/gallery/exif.ts @@ -25,30 +25,21 @@ function copy (key: keyof ExifInfo & keyof GalleryExif): FieldRule { } } -/* - EXIF orientation values meaning the image is stored rotated 90/270 degrees, - so its displayed width and height are the stored ones swapped. 5-8 are the - standard EXIF set (see https://magnushoff.com/articles/jpeg-orientation/); - 90 / -90 are degree-style values Immich also emits - see `isFlipped` in its - `web/src/lib/utils/asset-utils.ts`. -*/ -const FLIPPED_ORIENTATIONS = [5, 6, 90, 7, 8, -90] - /** - * An asset's dimensions as displayed. Prefers the asset-level width/height, - * which Immich provides orientation-corrected from 3.0.0 + * Config paths of any `ipp.showMetadata.{exif,location}.enabled` key. IPP + * refuses to start while one is set: per-field flags are the only gate, and + * `true` flags beside such a key may not be meant for visitors. */ +export function removedMetadataSwitches (): string[] { + return ['exif', 'location'] + .map(group => 'ipp.showMetadata.' + group + '.enabled') + .filter(path => getConfigOption(path) !== undefined) +} + +/** An asset's dimensions as displayed; Immich stores them orientation-corrected. */ export function displayDimensions (asset: Asset): { width?: number, height?: number } { if (asset.width && asset.height) return { width: asset.width, height: asset.height } - - // Fallback for Immich 2.x - const info = asset.exifInfo - const width = info?.exifImageWidth - const height = info?.exifImageHeight - if (!width || !height) return {} - return FLIPPED_ORIENTATIONS.includes(Number(info?.orientation)) - ? { width: height, height: width } - : { width, height } + return {} } /* @@ -57,13 +48,8 @@ export function displayDimensions (asset: Asset): { width?: number, height?: num written inline in the `*_RULES` arrays below. Adding a new metadata field: this rules table is the server-side source - of truth. Two other places carry parallel knowledge of the field set: - - `client/sidebar.ts` (renderRow specs decide where the field appears - in the info sidebar UI) - - `config/migrations.ts` LEGACY_* arrays (frozen v2.x field list used - by the `enabled -> per-field` shim; do NOT extend when adding new - fields - new fields should not retroactively appear for legacy - `enabled: true` users). + of truth. `client/sidebar.ts` carries parallel knowledge of the field set + (renderRow specs decide where the field appears in the info sidebar UI). */ const EXIF_FIELDS = [ 'make', 'model', 'lensModel', diff --git a/app/src/gallery/filename.ts b/app/src/gallery/filename.ts index 8eb4b47..1071f46 100644 --- a/app/src/gallery/filename.ts +++ b/app/src/gallery/filename.ts @@ -118,3 +118,40 @@ export function responseMime (response: globalThis.Response): string | undefined export function servedMimeFrom (subpath: string, response: globalThis.Response): string | undefined { return subpath === '/original' ? undefined : responseMime(response) } + +/** + * Fill in originalFileName / originalMimeType from an asset response's + * `Content-Disposition` / `Content-Type` headers, for assets that arrived + * without them (lazy album grid assets). Returns a shallow copy so the cached + * share asset is never mutated. + */ +export function enrichFromHeaders (asset: Asset, response: globalThis.Response): Asset { + const fileName = filenameFromContentDisposition(response.headers.get('content-disposition')) + const mime = responseMime(response) + if (!fileName && !mime) return asset + return { + ...asset, + originalFileName: asset.originalFileName || fileName, + originalMimeType: asset.originalMimeType || mime + } +} + +/** + * Extract a filename from a `Content-Disposition` header. Prefers the RFC 5987 + * `filename*=UTF-8''...` form (percent-decoded) over the plain `filename=`. + * Returns undefined when neither is present. + */ +export function filenameFromContentDisposition (header: string | null): string | undefined { + if (!header) return undefined + const extended = header.match(/filename\*=(?:UTF-8'')?([^;]+)/i) + if (extended) { + const raw = extended[1].trim().replace(/^"|"$/g, '') + try { + return decodeURIComponent(raw) + } catch (e) { + return raw + } + } + const plain = header.match(/filename="?([^";]+)"?/i) + return plain ? plain[1].trim() : undefined +} diff --git a/app/src/immich.ts b/app/src/immich.ts index a4d7b13..cb748b2 100644 --- a/app/src/immich.ts +++ b/app/src/immich.ts @@ -23,7 +23,7 @@ import { TtlLruCache } from '@ipp/core' import { ImageSize, IncomingShareRequest, TimelineBucket, TimelineBucketAssets } from './types' -import { canDownload } from './share' +import { canDownload, servableAssets } from './share' import { assetBuffer } from './stream/asset' import { downloadAll } from './stream/download' import { gallery } from './gallery/builder' @@ -204,8 +204,8 @@ async function fetchShareByKey (key: string, password?: string, keyType: KeyType log('Shared link ' + key + ' returned no assets array (type ' + link.type + ')') link.assets = [] } - // Filter assets to exclude trashed assets - link.assets = link.assets.filter(asset => !asset.isTrashed) + // Drop trashed assets, and any Immich hasn't finished processing + link.assets = servableAssets(link.assets) // Populate the shared assets with the public key/password link.assets.forEach(asset => { asset.key = key diff --git a/app/src/index.ts b/app/src/index.ts index 2232860..93940e6 100644 --- a/app/src/index.ts +++ b/app/src/index.ts @@ -28,23 +28,32 @@ import { } from '@ipp/core' import { fetchAssetDetail, getShareByKey, handleShareRequest } from './immich' import { buildAssetMetadata } from './gallery/metadata' +import { removedMetadataSwitches } from './gallery/exif' import { assetBuffer } from './stream/asset' import { downloadAssets } from './stream/download' import dayjs from 'dayjs' import { Request } from 'express-serve-static-core' import { ImageSize } from './types' -import { applyMigrations } from './config/migrations' import { canDownload, findMotionPhotoStill } from './share' import { respondToInvalidRequest as ippInvalidRequestHandler } from './invalidRequestHandler' import { ASSET_VERSION } from './version' import { h } from 'preact' import { Home } from './view/home' -// Read config.json (or the inline CONFIG env var) and apply backward-compat -// migrations. Must run before any code that calls getConfigOption. The -// bundled config.json sits one level above this file (src/ in dev, dist/ in -// the image), which is /app/config.json in the image. -loadConfig({ defaultPath: resolve(__dirname, '../config.json'), migrate: applyMigrations }) +// Read config.json (or the inline CONFIG env var). Must run before any code +// that calls getConfigOption. The bundled config.json sits one level above +// this file (src/ in dev, dist/ in the image), which is /app/config.json in +// the image. +loadConfig({ defaultPath: resolve(__dirname, '../config.json') }) + +const removedSwitches = removedMetadataSwitches() +if (removedSwitches.length) { + console.error(dayjs().format() + ' FATAL: The config has ' + removedSwitches.join(' and ') + + ', which IPP no longer reads. Every per-field flag set to true in that group would now be shown to visitors. ' + + 'Remove the key, and set to true only the fields you want visitors to see. ' + + 'See https://docs.ipp.nz/config/upgrading') + process.exit(1) +} // Route every invalid response, including core's, through IPP's handler file, // so an operator's mounted replacement applies everywhere. diff --git a/app/src/share.ts b/app/src/share.ts index 96eff7b..8f575cc 100644 --- a/app/src/share.ts +++ b/app/src/share.ts @@ -1,4 +1,4 @@ -import { Asset, getConfigOption, SharedLink } from '@ipp/core' +import { Asset, getConfigOption, log, SharedLink, TtlLruCache } from '@ipp/core' import { DownloadAll } from './types' import dayjs from 'dayjs' @@ -10,17 +10,38 @@ import dayjs from 'dayjs' * does not affect image quality (see `gallery/sizing.ts`). */ export function canDownload (share: SharedLink): boolean { - const allowDownloadConfig = getConfigOption('ipp.allowDownload', 0) as DownloadAll - if (!allowDownloadConfig) { - // Downloading is disabled in config.json - return false - } else if (allowDownloadConfig === DownloadAll.always) { - // Always allowed to download in config.json - return true - } else { - // Return Immich's setting for this shared link - return !!share.allowDownload + const policy = getConfigOption('ipp.allowDownload', DownloadAll.disabled) + if (policy === DownloadAll.always) return true + if (policy === DownloadAll.perImmich) return !!share.allowDownload + if (policy !== DownloadAll.disabled && !warnedInvalidDownloadPolicy) { + warnedInvalidDownloadPolicy = true + log.warn('ipp.allowDownload is ' + JSON.stringify(policy) + ', which is not 0, 1 or 2. Downloads are off.') } + return false +} + +let warnedInvalidDownloadPolicy = false + +// Asset ids already warned about, so each warns at most once a day +const warnedUnprocessed = new TtlLruCache({ ttlMs: 24 * 60 * 60_000, max: 1000 }) + +/** + * Narrow a share's assets to what IPP can render: not trashed, and finished + * processing in Immich. `thumbhash` is the readiness signal: Immich's + * thumbnail job writes the files and only then sets it, so until it appears + * every image URL IPP hands out would 404. + */ +export function servableAssets (assets: Asset[]): Asset[] { + return assets.filter(asset => { + if (asset.isTrashed) return false + if (asset.thumbhash) return true + if (!warnedUnprocessed.get(asset.id)) { + warnedUnprocessed.set(asset.id, true) + log.warn('Asset ' + asset.id + ' is hidden because Immich has not generated its thumbnail yet. ' + + 'If it never appears, check the thumbnail job for that asset in Immich.') + } + return false + }) } const DEFAULT_EXPIRY_FORMAT = 'YYYY-MM-DD' diff --git a/app/src/stream/asset.ts b/app/src/stream/asset.ts index 6e4931b..95638a9 100644 --- a/app/src/stream/asset.ts +++ b/app/src/stream/asset.ts @@ -7,7 +7,7 @@ import { } from '../immich' import { Response } from 'express-serve-static-core' import { ImageSize, IncomingShareRequest } from '../types' -import { attachmentDisposition, getFilename, servedMimeFrom } from '../gallery/filename' +import { attachmentDisposition, enrichFromHeaders, getFilename, servedMimeFrom } from '../gallery/filename' import { isVideoAsset, resolveDownloadEndpoint, resolveImageEndpoint } from '../gallery/sizing' import { pipeline } from 'stream/promises' @@ -94,11 +94,14 @@ export async function assetBuffer (req: IncomingShareRequest, res: Response, ass return } + // An original can be any format Immich accepts, so never let a browser sniff it + res.setHeader('X-Content-Type-Options', 'nosniff') if (attachment) { res.setHeader('X-Accel-Buffering', 'no') - if (asset.originalFileName) { - res.setHeader('Content-Disposition', attachmentDisposition(getFilename(asset, servedSize, servedMimeFrom(subpath, data)))) - } + // Always an attachment, so an SVG can't render inline. Album assets have + // no originalFileName; Immich's own Content-Disposition carries it. + const named = asset.originalFileName ? asset : enrichFromHeaders(asset, data) + res.setHeader('Content-Disposition', attachmentDisposition(getFilename(named, servedSize, servedMimeFrom(subpath, data)))) } headerList.forEach(header => { const value = data.headers.get(header) diff --git a/app/src/stream/download.ts b/app/src/stream/download.ts index c129924..d3a2572 100644 --- a/app/src/stream/download.ts +++ b/app/src/stream/download.ts @@ -3,7 +3,7 @@ import { assetFetchUrl, authHeadersForAsset } from '../immich' import { Response } from 'express-serve-static-core' import archiver, { Archiver } from 'archiver' import { resolveDownloadEndpoint, ImageEndpoint } from '../gallery/sizing' -import { attachmentDisposition, getFilename, responseMime, servedMimeFrom } from '../gallery/filename' +import { attachmentDisposition, enrichFromHeaders, getFilename, servedMimeFrom } from '../gallery/filename' /** Attempts to get response headers from Immich for one asset before giving up. */ const MAX_ATTEMPTS = 3 @@ -216,43 +216,6 @@ async function fetchOne (share: SharedLink, asset: Asset, signal: AbortSignal): return { response: fetched.response, asset: namedAsset, endpoint, servedMime: servedMimeFrom(endpoint.subpath, fetched.response), url } } -/** - * Fill in originalFileName / originalMimeType from an asset response's - * `Content-Disposition` / `Content-Type` headers, for assets that arrived - * without them (lazy album grid assets). Returns a shallow copy so the cached - * share asset is never mutated. - */ -function enrichFromHeaders (asset: Asset, response: globalThis.Response): Asset { - const fileName = filenameFromContentDisposition(response.headers.get('content-disposition')) - const mime = responseMime(response) - if (!fileName && !mime) return asset - return { - ...asset, - originalFileName: asset.originalFileName || fileName, - originalMimeType: asset.originalMimeType || mime - } -} - -/** - * Extract a filename from a `Content-Disposition` header. Prefers the RFC 5987 - * `filename*=UTF-8''...` form (percent-decoded) over the plain `filename=`. - * Returns undefined when neither is present. - */ -export function filenameFromContentDisposition (header: string | null): string | undefined { - if (!header) return undefined - const extended = header.match(/filename\*=(?:UTF-8'')?([^;]+)/i) - if (extended) { - const raw = extended[1].trim().replace(/^"|"$/g, '') - try { - return decodeURIComponent(raw) - } catch (e) { - return raw - } - } - const plain = header.match(/filename="?([^";]+)"?/i) - return plain ? plain[1].trim() : undefined -} - type HeaderFetchOutcome = | { response: globalThis.Response } | { failure: { status?: number, error?: unknown } } diff --git a/app/src/utils/log.ts b/app/src/utils/log.ts deleted file mode 100644 index f097f96..0000000 --- a/app/src/utils/log.ts +++ /dev/null @@ -1,5 +0,0 @@ -/* - Kept for operators who mount a copy of invalidRequestHandler.js taken from - IPP 3.x, which requires './utils/log'. Delete in 4.0 with an upgrade note. -*/ -export { log } from '@ipp/core' diff --git a/app/tests/albumTimeline.test.ts b/app/tests/albumTimeline.test.ts index 63673ce..41d3ab2 100644 --- a/app/tests/albumTimeline.test.ts +++ b/app/tests/albumTimeline.test.ts @@ -105,6 +105,57 @@ describe('album timeline enumeration (Immich 3.0)', () => { expect(assets[0].width!).toBeGreaterThan(assets[0].height!) }) + it('withholds assets Immich has not finished generating thumbnails for', async () => { + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}) + const pending = { + ...bucketResponse, + id: bucketResponse.id.map(id => id.replace(/^a/, 'e')), + thumbhash: [null, null, 'hashC'], + isTrashed: [false, true, false] + } + vi.stubGlobal('fetch', vi.fn(async (url: string) => { + if (url.includes('/shared-links/me')) return jsonResponse(sharedLinkResponse()) + if (url.includes('/timeline/buckets')) return jsonResponse(bucketsResponse) + if (url.includes('/timeline/bucket')) return jsonResponse(pending) + throw new Error('Unexpected fetch to ' + url) + })) + const first = await getShareByKey(uniqueKey(), undefined, KeyType.key) + // A second share key stands in for the next cache refresh. + await getShareByKey(uniqueKey(), undefined, KeyType.key) + + expect(first.valid).toBe(true) + expect(first.link!.assets.map(a => a.id)).toEqual(['cccccccc-cccc-cccc-cccc-cccccccccccc']) + const warnings = warn.mock.calls.filter(c => String(c[0]).includes('eaaaaaaa-')) + expect(warnings).toHaveLength(1) + warn.mockRestore() + }) + + it('withholds unprocessed assets on an individual share too', async () => { + // Individual shares carry their assets inline on /shared-links/me rather + // than via the timeline, so the filter has to sit downstream of both. + vi.spyOn(console, 'warn').mockImplementation(() => {}) + const individual = { + type: 'INDIVIDUAL', + key: 'real-key', + allowDownload: true, + expiresAt: null, + showMetadata: true, + assets: [ + { id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', type: 'IMAGE', isTrashed: false, thumbhash: 'hashA' }, + { id: 'ffffffff-ffff-ffff-ffff-ffffffffffff', type: 'IMAGE', isTrashed: false, thumbhash: null } + ] + } + vi.stubGlobal('fetch', vi.fn(async (url: string) => { + if (url.includes('/shared-links/me')) return jsonResponse(individual) + throw new Error('Unexpected fetch to ' + url) + })) + const result = await getShareByKey(uniqueKey(), undefined, KeyType.key) + + expect(result.valid).toBe(true) + expect(result.link!.assets.map(a => a.id)).toEqual(['aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa']) + vi.mocked(console.warn).mockRestore() + }) + it('requests each bucket with an explicit UTC key so non-UTC databases match (#260)', async () => { const fetchMock = routeFetch(sharedLinkResponse()) vi.stubGlobal('fetch', fetchMock) diff --git a/app/tests/assetMetadata.test.ts b/app/tests/assetMetadata.test.ts index ddd753c..88c998d 100644 --- a/app/tests/assetMetadata.test.ts +++ b/app/tests/assetMetadata.test.ts @@ -1,6 +1,7 @@ import { describe, it, expect, beforeEach } from 'vitest' import { Asset, AssetType, KeyType, loadConfig, SharedLink } from '@ipp/core' import { buildAssetMetadata } from '../src/gallery/metadata' +import { removedMetadataSwitches } from '../src/gallery/exif' // buildAssetMetadata is the lazy-flow counterpart to the gallery builder's // per-item baking; it must apply the same showMetadata kill-switch and @@ -56,17 +57,11 @@ describe('buildAssetMetadata', () => { expect(meta.exif?.city).toBeUndefined() }) - // Immich 3.x applies EXIF orientation before storing asset.width / height, - // so a rotated photo reports portrait dimensions there while the exifImage* - // pair stays landscape. The asset-level pair must win. - it('reports dimensions in display orientation', () => { + it('reports the asset-level dimensions', () => { setConfig({ ipp: { showMetadata: { exif: { dimensions: true } } } }) const photo = asset() photo.width = 3000 photo.height = 4000 - photo.exifInfo!.exifImageWidth = 4000 - photo.exifInfo!.exifImageHeight = 3000 - photo.exifInfo!.orientation = '6' expect(buildAssetMetadata(photo, share()).exif).toMatchObject({ width: 3000, @@ -74,25 +69,17 @@ describe('buildAssetMetadata', () => { }) }) - // Immich 2.x has no asset-level width / height, so the raw EXIF pair is - // used, swapped when the orientation marks the image as stored rotated. - const exifOrientationCases: Array<[string | null, number, number]> = [ - ['6', 3000, 4000], - ['8', 3000, 4000], - ['90', 3000, 4000], - ['-90', 3000, 4000], - ['1', 4000, 3000], - [null, 4000, 3000] - ] + it('finds the removed metadata master switches, whatever their value', () => { + setConfig({ ipp: { showMetadata: { exif: { enabled: false, gps: true }, location: { enabled: true } } } }) + expect(removedMetadataSwitches()).toEqual(['ipp.showMetadata.exif.enabled', 'ipp.showMetadata.location.enabled']) - it.each(exifOrientationCases)('falls back to swapped exif dimensions without asset dimensions (orientation %s)', (orientation, width, height) => { + setConfig({ ipp: { showMetadata: { exif: { make: true } } } }) + expect(removedMetadataSwitches()).toEqual([]) + }) + + it('omits dimensions when Immich has no asset-level width / height', () => { setConfig({ ipp: { showMetadata: { exif: { dimensions: true } } } }) - const photo = asset() - photo.exifInfo!.exifImageWidth = 4000 - photo.exifInfo!.exifImageHeight = 3000 - photo.exifInfo!.orientation = orientation - - expect(buildAssetMetadata(photo, share()).exif).toMatchObject({ width, height }) + expect(buildAssetMetadata(asset(), share()).exif?.width).toBeUndefined() }) it('returns the photo timezone only when both date and timezone are enabled', () => { diff --git a/app/tests/assetStream.test.ts b/app/tests/assetStream.test.ts index 02f2bda..e667a5b 100644 --- a/app/tests/assetStream.test.ts +++ b/app/tests/assetStream.test.ts @@ -211,4 +211,39 @@ describe('assetBuffer streaming', () => { expect(res.headers['content-disposition']).toContain('a1.webp') expect(res.headers['content-type']).toBe('image/webp') }) + + describe('original tier on an album asset', () => { + // Album assets come from the timeline with no originalFileName or mime. + const albumAsset: Asset = { id: 'a2', key: 'testkey', keyType: KeyType.key, type: AssetType.image, isTrashed: false } + + function svgFetch (headers: Record) { + return vi.fn(async () => new globalThis.Response('', { + status: 200, + headers: { 'content-type': 'image/svg+xml', ...headers } + })) + } + + it('sends an attachment named from Immich\'s header, with nosniff', async () => { + vi.stubGlobal('fetch', svgFetch({ 'content-disposition': 'attachment; filename="drawing.svg"' })) + const res = new FakeRes() + await assetBuffer(makeRequest(), asResponse(res), albumAsset, ImageSize.original) + expect(res.headers['content-disposition']).toBe("attachment; filename*=UTF-8''drawing.svg") + expect(res.headers['x-content-type-options']).toBe('nosniff') + }) + + it('falls back to the asset id when Immich sends no filename', async () => { + vi.stubGlobal('fetch', svgFetch({})) + const res = new FakeRes() + await assetBuffer(makeRequest(), asResponse(res), albumAsset, ImageSize.original) + expect(res.headers['content-disposition']).toBe("attachment; filename*=UTF-8''a2.svg") + }) + }) + + it('serves display sizes inline, still with nosniff', async () => { + vi.stubGlobal('fetch', pullFetch(CHUNK, newSource())) + const res = new FakeRes() + await assetBuffer(makeRequest(), asResponse(res), asset, ImageSize.preview) + expect(res.headers['content-disposition']).toBeUndefined() + expect(res.headers['x-content-type-options']).toBe('nosniff') + }) }) diff --git a/app/tests/canDownload.test.ts b/app/tests/canDownload.test.ts new file mode 100644 index 0000000..7178d94 --- /dev/null +++ b/app/tests/canDownload.test.ts @@ -0,0 +1,47 @@ +import { describe, it, expect, beforeEach, vi } from 'vitest' +import { KeyType, loadConfig, SharedLink } from '@ipp/core' +import { canDownload } from '../src/share' + +// canDownload gates the download UI on ipp.allowDownload: 0 off, 1 follow the +// Immich share's toggle, 2 always. Anything else fails closed. + +function setConfig (config: unknown) { + process.env.CONFIG = JSON.stringify(config) + loadConfig() +} + +const share = (allowDownload: boolean): SharedLink => ({ + key: 'k', + keyType: KeyType.key, + type: 'ALBUM', + assets: [], + allowDownload +}) + +describe('canDownload', () => { + beforeEach(() => { + delete process.env.CONFIG + loadConfig() + vi.spyOn(console, 'warn').mockImplementation(() => {}) + }) + + it('is off by default', () => { + expect(canDownload(share(true))).toBe(false) + }) + + it('follows the Immich toggle with 1', () => { + setConfig({ ipp: { allowDownload: 1 } }) + expect(canDownload(share(true))).toBe(true) + expect(canDownload(share(false))).toBe(false) + }) + + it('is always on with 2', () => { + setConfig({ ipp: { allowDownload: 2 } }) + expect(canDownload(share(false))).toBe(true) + }) + + it.each([true, '1', '2', 3, -1])('fails closed for %j', value => { + setConfig({ ipp: { allowDownload: value } }) + expect(canDownload(share(true))).toBe(false) + }) +}) diff --git a/app/tests/contentDisposition.test.ts b/app/tests/contentDisposition.test.ts index bf58e83..bc6ac7f 100644 --- a/app/tests/contentDisposition.test.ts +++ b/app/tests/contentDisposition.test.ts @@ -1,6 +1,5 @@ import { describe, it, expect } from 'vitest' -import { filenameFromContentDisposition } from '../src/stream/download' -import { attachmentDisposition } from '../src/gallery/filename' +import { attachmentDisposition, filenameFromContentDisposition } from '../src/gallery/filename' // Used by the zip download path to recover the real filename for album grid // assets (which arrive without originalFileName) from the /original response. diff --git a/app/tests/downloadAssets.test.ts b/app/tests/downloadAssets.test.ts index c3b6be0..09743ba 100644 --- a/app/tests/downloadAssets.test.ts +++ b/app/tests/downloadAssets.test.ts @@ -66,6 +66,7 @@ class FakeRes extends Writable { } setHeader (name: string, value: string) { this.headers[name] = value; return this } + set (name: string, value: string) { return this.setHeader(name, value) } status (code: number) { this.statusCode = code; return this } send () { this.end(); return this } @@ -245,6 +246,7 @@ describe('downloadAssets', () => { expect(res.writableEnded).toBe(true) expect(res.received).toBe(0) expect(res.headers['Content-Type']).toBeUndefined() + expect(res.headers['Cache-Control']).toContain('no-store') }, 10_000) it('destroys the response when a later asset keeps failing', async () => { diff --git a/app/tests/migrations.test.ts b/app/tests/migrations.test.ts deleted file mode 100644 index cb25c2d..0000000 --- a/app/tests/migrations.test.ts +++ /dev/null @@ -1,364 +0,0 @@ -import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest' -import { applyMigrations } from '../src/config/migrations' - -/* - The migrations module mutates the passed-in config object in place and - logs a one-line deprecation notice when it makes a change. These tests - cover all four shims registered in `SHIMS`. Console output is silenced - per-test so the suite stays quiet and so we can assert on it where the - deprecation message is part of the contract. -*/ - -let logSpy: ReturnType - -beforeEach(() => { - logSpy = vi.spyOn(console, 'log').mockImplementation(() => {}) -}) - -afterEach(() => { - logSpy.mockRestore() -}) - -describe('applyMigrations', () => { - it('is a no-op for a fresh config that has no legacy keys', () => { - const config = { - ipp: { - showMetadata: { - exif: { dateTimeOriginal: true }, - location: { city: true } - }, - gallery: { showTitle: true }, - lightbox: { showArrows: true } - } - } - const before = JSON.stringify(config) - applyMigrations(config) - expect(JSON.stringify(config)).toBe(before) - expect(logSpy).not.toHaveBeenCalled() - }) - - it('is a no-op for a completely empty config', () => { - const config = {} - applyMigrations(config) - // applyMigrations seeds an `ipp` object on its way through, so empty in - // means `{ ipp: {} }` out - that's fine, just check no crash + no logs. - expect(logSpy).not.toHaveBeenCalled() - }) -}) - -describe('lightGallery shim', () => { - it('maps lightGallery.controls / download / mobileSettings to ipp.lightbox.*', () => { - const config = { - lightGallery: { - controls: false, - download: false, - mobileSettings: { controls: true } - } - } as Record - - applyMigrations(config) - - const ipp = config.ipp as Record - const lightbox = ipp.lightbox as Record - expect(lightbox.showArrows).toBe(false) - expect(lightbox.showDownload).toBe(false) - expect(lightbox.mobileArrows).toBe(true) - expect(logSpy).toHaveBeenCalledOnce() - }) - - it('does not overwrite values the user has already set on the new path', () => { - const config = { - lightGallery: { controls: false, download: false }, - ipp: { - lightbox: { showArrows: true, showDownload: true } - } - } as Record - - applyMigrations(config) - - const lightbox = (config.ipp as Record).lightbox as Record - expect(lightbox.showArrows).toBe(true) - expect(lightbox.showDownload).toBe(true) - }) - - it('does nothing when lightGallery is absent', () => { - const config = { ipp: { lightbox: { showArrows: true } } } as Record - applyMigrations(config) - expect(logSpy).not.toHaveBeenCalled() - }) -}) - -describe('topLevelGallery shim', () => { - it('moves legacy top-level keys under ipp.gallery.*', () => { - const config = { - ipp: { - singleImageGallery: true, - showGalleryTitle: false, - groupGalleryByDate: true - } - } as Record - - applyMigrations(config) - - const gallery = (config.ipp as Record).gallery as Record - expect(gallery.singleImage).toBe(true) - expect(gallery.showTitle).toBe(false) - expect(gallery.groupByDate).toBe(true) - expect(logSpy).toHaveBeenCalledOnce() - }) - - it('keeps the user-set value on the new path when both forms are present', () => { - const config = { - ipp: { - singleImageGallery: false, - gallery: { singleImage: true } - } - } as Record - - applyMigrations(config) - - const gallery = (config.ipp as Record).gallery as Record - expect(gallery.singleImage).toBe(true) - }) - - it('does nothing when no legacy keys are present', () => { - const config = { - ipp: { gallery: { singleImage: true } } - } as Record - applyMigrations(config) - expect(logSpy).not.toHaveBeenCalled() - }) -}) - -describe('descriptionSplit shim', () => { - it('expands boolean true to { caption: true, sidebar: true }', () => { - const config = { - ipp: { showMetadata: { description: true } } - } as Record - - applyMigrations(config) - - const description = ((config.ipp as Record).showMetadata as Record).description - expect(description).toEqual({ caption: true, sidebar: true }) - expect(logSpy).toHaveBeenCalledOnce() - }) - - it('expands boolean false to { caption: false, sidebar: false }', () => { - const config = { - ipp: { showMetadata: { description: false } } - } as Record - - applyMigrations(config) - - const description = ((config.ipp as Record).showMetadata as Record).description - expect(description).toEqual({ caption: false, sidebar: false }) - }) - - it('leaves an existing object form alone', () => { - const config = { - ipp: { - showMetadata: { - description: { caption: false, sidebar: true } - } - } - } as Record - - applyMigrations(config) - - const description = ((config.ipp as Record).showMetadata as Record).description - expect(description).toEqual({ caption: false, sidebar: true }) - expect(logSpy).not.toHaveBeenCalled() - }) -}) - -describe('metadataEnabled shim', () => { - it('legacy enabled=true defaults every unset per-field flag to true', () => { - const config = { - ipp: { - showMetadata: { - exif: { enabled: true } - } - } - } as Record - - applyMigrations(config) - - const exif = ((config.ipp as Record).showMetadata as Record).exif as Record - expect(exif.enabled).toBeUndefined() - expect(exif.dateTimeOriginal).toBe(true) - expect(exif.timeZone).toBeUndefined() - expect(exif.fileName).toBe(true) - expect(exif.dimensions).toBe(true) - expect(exif.fileSize).toBe(true) - expect(exif.make).toBe(true) - expect(exif.model).toBe(true) - expect(exif.lensModel).toBe(true) - expect(exif.exposureTime).toBe(true) - expect(exif.iso).toBe(true) - expect(exif.fNumber).toBe(true) - expect(exif.focalLength).toBe(true) - expect(logSpy).toHaveBeenCalledOnce() - }) - - it('legacy enabled=true preserves explicit per-field false ("all except X")', () => { - const config = { - ipp: { - showMetadata: { - location: { enabled: true, gps: false } - } - } - } as Record - - applyMigrations(config) - - const location = ((config.ipp as Record).showMetadata as Record).location as Record - expect(location.enabled).toBeUndefined() - expect(location.city).toBe(true) - expect(location.state).toBe(true) - expect(location.country).toBe(true) - expect(location.gps).toBe(false) - }) - - it('legacy enabled=false clears any per-field flags that were true', () => { - // This is the shipped 2.3.0 default shape: enabled=false + every per- - // field=true as documentation. Under the new semantic those `true`s - // would otherwise become live opt-ins; the shim zeroes them. - const config = { - ipp: { - showMetadata: { - exif: { - enabled: false, - dateTimeOriginal: true, - fileName: true, - make: true, - iso: true - } - } - } - } as Record - - applyMigrations(config) - - const exif = ((config.ipp as Record).showMetadata as Record).exif as Record - expect(exif.enabled).toBeUndefined() - expect(exif.dateTimeOriginal).toBe(false) - expect(exif.fileName).toBe(false) - expect(exif.make).toBe(false) - expect(exif.iso).toBe(false) - expect(logSpy).toHaveBeenCalledOnce() - }) - - it('legacy enabled=false leaves explicit per-field false alone', () => { - const config = { - ipp: { - showMetadata: { - location: { enabled: false, gps: false } - } - } - } as Record - - applyMigrations(config) - - const location = ((config.ipp as Record).showMetadata as Record).location as Record - expect(location.gps).toBe(false) - }) - - it('handles both exif and location groups in one pass', () => { - const config = { - ipp: { - showMetadata: { - exif: { enabled: true }, - location: { enabled: false, gps: true } - } - } - } as Record - - applyMigrations(config) - - const showMetadata = (config.ipp as Record).showMetadata as Record - const exif = showMetadata.exif as Record - const location = showMetadata.location as Record - expect(exif.dateTimeOriginal).toBe(true) - expect(location.gps).toBe(false) - // One deprecation log call regardless of how many groups were migrated - expect(logSpy).toHaveBeenCalledOnce() - }) - - it('does nothing when no legacy enabled key is present', () => { - const config = { - ipp: { - showMetadata: { - exif: { dateTimeOriginal: true } - } - } - } as Record - - applyMigrations(config) - - const exif = ((config.ipp as Record).showMetadata as Record).exif as Record - expect(exif.dateTimeOriginal).toBe(true) - expect(logSpy).not.toHaveBeenCalled() - }) - - it('does nothing when showMetadata is absent', () => { - const config = { ipp: {} } as Record - applyMigrations(config) - expect(logSpy).not.toHaveBeenCalled() - }) -}) - -describe('downloadOriginalPhoto shim', () => { - it('maps true -> maxDownloadQuality: original', () => { - const config = { ipp: { downloadOriginalPhoto: true } } as Record - applyMigrations(config) - expect((config.ipp as Record).maxDownloadQuality).toBe('original') - expect(logSpy).toHaveBeenCalledOnce() - }) - - it('maps false -> maxDownloadQuality: preview', () => { - const config = { ipp: { downloadOriginalPhoto: false } } as Record - applyMigrations(config) - expect((config.ipp as Record).maxDownloadQuality).toBe('preview') - }) - - it('does not overwrite an explicitly-set maxDownloadQuality', () => { - const config = { ipp: { downloadOriginalPhoto: false, maxDownloadQuality: 'fullsize' } } as Record - applyMigrations(config) - expect((config.ipp as Record).maxDownloadQuality).toBe('fullsize') - expect(logSpy).not.toHaveBeenCalled() - }) - - it('does nothing when downloadOriginalPhoto is absent', () => { - const config = { ipp: { maxDownloadQuality: 'original' } } as Record - applyMigrations(config) - expect(logSpy).not.toHaveBeenCalled() - }) -}) - -describe('allowDownloadAll rename shim', () => { - it('maps allowDownloadAll -> allowDownload, preserving the int value', () => { - const config = { ipp: { allowDownloadAll: 2 } } as Record - applyMigrations(config) - expect((config.ipp as Record).allowDownload).toBe(2) - expect(logSpy).toHaveBeenCalledOnce() - }) - - it('maps the falsy 0 value through (not skipped as "absent")', () => { - const config = { ipp: { allowDownloadAll: 0 } } as Record - applyMigrations(config) - expect((config.ipp as Record).allowDownload).toBe(0) - }) - - it('does not overwrite an explicitly-set allowDownload', () => { - const config = { ipp: { allowDownloadAll: 2, allowDownload: 1 } } as Record - applyMigrations(config) - expect((config.ipp as Record).allowDownload).toBe(1) - expect(logSpy).not.toHaveBeenCalled() - }) - - it('does nothing when allowDownloadAll is absent', () => { - const config = { ipp: { allowDownload: 1 } } as Record - applyMigrations(config) - expect(logSpy).not.toHaveBeenCalled() - }) -}) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index c9d252e..fa4b648 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -52,7 +52,7 @@ export default defineConfig({ { text: 'Lightbox', link: '/config/lightbox' }, { text: 'Metadata', link: '/config/metadata' }, { text: 'Error responses', link: '/config/error-responses' }, - { text: 'Legacy config keys', link: '/config/upgrading' } + { text: 'Renamed config keys', link: '/config/upgrading' } ] }, { diff --git a/docs/README.md b/docs/README.md index 0db2e54..23b67d0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -51,7 +51,7 @@ started because it is what people read first, not because it is a tutorial. If e | You are adding… | Put it in | |------------------------------------------------|-----------| -| A config key | The page for its group, in `config.json` order, with type and default. If you renamed a key, add a row to Legacy config keys and a shim in `app/src/config/migrations.ts`. | +| A config key | The page for its group, in `config.json` order, with type and default. Rename a key only in a major version, and add a row for it to Renamed config keys (`config/upgrading.md`). | | An environment variable | `config/environment-variables.md` | | Something visitors to a share will notice | `how-to-use.md` (Sharing from Immich) | | A reverse-proxy or hosting recipe | A new page under Guides | diff --git a/docs/config/error-responses.md b/docs/config/error-responses.md index 4e8ed6d..d765553 100644 --- a/docs/config/error-responses.md +++ b/docs/config/error-responses.md @@ -26,6 +26,8 @@ If you want to send a custom 404 page, you would do that with either of the belo If you want to go even further, you can write your own custom function. Do this by taking a copy of the `app/dist/invalidRequestHandler.js` file, then mounting it back as a Docker volume into the correct location for the container to use. +Take the copy from the image of the IPP major version you run. A copy from an earlier major version can fail to load. + ## Customising the response using your Reverse Proxy You can also choose to customise these responses using your reverse proxy, which might give you more flexibility depending on your use-case. diff --git a/docs/config/index.md b/docs/config/index.md index 120a448..bb91076 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -11,7 +11,7 @@ Connection settings (the Immich URL, public URL, port and config file location) - [Lightbox](/config/lightbox) - the PhotoSwipe image viewer. - [Metadata](/config/metadata) - description / EXIF / location reveal controls. - [Error responses](/config/error-responses) - customise what invalid requests return. -- [Legacy config keys](/config/upgrading) - renamed keys and compatibility shims. +- [Renamed config keys](/config/upgrading) - old keys and their current names. ## How to provide a config override diff --git a/docs/config/upgrading.md b/docs/config/upgrading.md index e67e13b..30bbd69 100644 --- a/docs/config/upgrading.md +++ b/docs/config/upgrading.md @@ -1,12 +1,12 @@ -# Legacy config keys +# Renamed config keys -A few config keys have been renamed or reshaped across versions. Old configs keep working through backward-compatibility shims, with a deprecation notice logged at startup; update to the current names to silence it. For how to update IPP itself, see [Upgrading](/upgrading). +IPP 4.0 no longer reads the old config keys below. Earlier versions mapped them to their current names at startup; 4.0 +ignores them, and the option falls back to its default. Check your `config.json` for each key in the left column and +move its value to the right column. For how to update IPP itself, see [Upgrading](/upgrading). -## Gallery keys moved under `ipp.gallery.*` (v2.0) +## Gallery keys -The old top-level keys are mapped automatically: - -| Legacy key | New key | +| Old key | Current key | |------------------------------|----------------------------------| | `ipp.singleImageGallery` | `ipp.gallery.singleImage` | | `ipp.singleItemAutoOpen` | `ipp.gallery.singleItemAutoOpen` | @@ -14,23 +14,33 @@ The old top-level keys are mapped automatically: | `ipp.showGalleryDescription` | `ipp.gallery.showDescription` | | `ipp.groupGalleryByDate` | `ipp.gallery.groupByDate` | -## `showMetadata.description` is now an object +## Lightbox keys -It used to be a single boolean. A legacy `description: true` migrates to `{ caption: true, sidebar: true }` (and `false` to both `false`). Move to the explicit form to silence the deprecation notice and so you can target the caption vs. the sidebar independently. +The `lightGallery` section from IPP 1.x became `ipp.lightbox`. -## `showMetadata.{exif,location}.enabled` was removed (v2.3.1) +| Old key | Current key | +|----------------------------------------|-----------------------------| +| `lightGallery.controls` | `ipp.lightbox.showArrows` | +| `lightGallery.download` | `ipp.lightbox.showDownload` | +| `lightGallery.mobileSettings.controls` | `ipp.lightbox.mobileArrows` | -Per-field flags are now the only gate, and all default to `false`. The shim preserves behaviour for legacy configs by rewriting them in memory at startup: +## Downloads -- Legacy `enabled: true` defaults every unset per-field flag in the group to `true`, matching the old "everything visible" behaviour. Per-field flags you had explicitly set to `false` (the "all except X" pattern) are kept. -- Legacy `enabled: false` clears any per-field flags that were `true`, matching the old "nothing visible" behaviour and stopping leftover documentation flags from the shipped 2.3 config from becoming live opt-ins. +| Old key | Current key | +|-----------------------------|-----------------------------------------------------------------| +| `ipp.allowDownloadAll` | `ipp.allowDownload`, same `0` / `1` / `2` values | +| `ipp.downloadOriginalPhoto` | `ipp.maxDownloadQuality`: `true` is `"original"`, `false` is `"preview"` | -A deprecation notice is printed at startup. Update your `config.json` to the explicit per-field form to silence it. +## Metadata -## `downloadOriginalPhoto` → `maxDownloadQuality` (v3.0) +`ipp.showMetadata.description` is an object, `{ "caption": , "sidebar": }`. A plain `true` or `false` is +ignored, so the description is hidden in both places until you change it. -The boolean becomes the quality tier: `true` maps to `"original"`, `false` to `"preview"`. The shim will be removed in v4.0. +`ipp.showMetadata.exif.enabled` and `ipp.showMetadata.location.enabled` are gone. The per-field flags are the only +gate, and each one defaults to `false`. -## `allowDownloadAll` → `allowDownload` (v3.0) - -Renamed, same `0` / `1` / `2` values. The shim will be removed in v4.0. +> [!WARNING] +> IPP will not start while either `enabled` key is in your config. A config from IPP 2.3 can have `"enabled": false` +> together with per-field flags set to `true`. Earlier versions kept those fields hidden, but 4.0 shows every field +> whose flag is `true`, GPS coordinates included. Remove the `enabled` key, and set to `true` only the fields you +> want visitors to see. diff --git a/docs/installation.md b/docs/installation.md index f06750c..ba2e7e6 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,7 +1,7 @@ # Installation > [!NOTE] -> IPP requires **Immich 2.0.0 or newer**. It checks the server version at startup and will exit with an error against an older Immich. +> IPP requires **Immich 3.0.0 or newer**. It checks the server version at startup and will exit with an error against an older Immich. ## Install with Docker / Podman diff --git a/docs/upgrading.md b/docs/upgrading.md index c7d22ec..4c6a4ce 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -15,9 +15,16 @@ If you pin a version tag rather than `latest`, bump it in your `docker-compose.y Check the [release notes](https://github.com/alangrainger/immich-public-proxy/releases) before moving to a new major version. Breaking changes and renamed config keys land in major versions and are listed there. +## Upgrading to 4.0 + +- **Immich 3.0.0 or newer is required.** Upgrade Immich first. +- **Old config keys are no longer read.** Check your `config.json` against [Renamed config keys](/config/upgrading). +- **A custom `invalidRequestHandler.js` must be copied again from the 4.0 image.** A copy taken from 3.x fails to + load. See [Custom function](/config/error-responses#custom-function). + ## Immich version -IPP requires **Immich 2.0.0 or newer** and checks the server version at startup. Against an older Immich it logs a +IPP requires **Immich 3.0.0 or newer** and checks the server version at startup. Against an older Immich it logs a fatal error and exits; if it can't determine the version at all (Immich unreachable), it logs a warning and carries on. When you upgrade Immich, check the IPP release notes for a matching release, as changes to Immich's API are picked up @@ -25,5 +32,5 @@ there. ## Config keys -Renamed or reshaped config keys keep working through backward-compatibility shims, with a deprecation notice logged -at startup. [Legacy config keys](/config/upgrading) maps each old form to its current name. +Config keys are renamed only in major versions, and the old name stops working then. [Renamed config +keys](/config/upgrading) maps each old key to its current name. diff --git a/shared/src/config/loader.ts b/shared/src/config/loader.ts index 1b8a58a..dd3a270 100644 --- a/shared/src/config/loader.ts +++ b/shared/src/config/loader.ts @@ -3,12 +3,10 @@ import { resolve } from 'path' export type Config = Record -/** Where each app keeps its config file, and how it upgrades legacy config shapes. */ +/** Where each app keeps its config file. */ export interface LoadConfigOptions { /** Absolute path of the bundled config file, used when `IPP_CONFIG` is unset. */ defaultPath?: string - /** Rewrites legacy keys in place before the config is cached. */ - migrate?: (config: Config) => void } // Module-level cache populated by `loadConfig()`. Access through @@ -19,8 +17,8 @@ let currentConfig: Config = {} /** * Read the runtime configuration from `process.env.CONFIG` (an inline JSON - * string, typically set in docker-compose) or from the config file. Applies - * the app's `migrate` hook, caches the result, and returns it. + * string, typically set in docker-compose) or from the config file, cache + * the result, and return it. * * The default path comes from the app, not from this module's location: * core is compiled into its own package, so a path relative to `__dirname` @@ -29,7 +27,7 @@ let currentConfig: Config = {} * Called once from each app's `index.ts` at startup. Safe to call again in * tests with a fresh env to reset state. */ -export function loadConfig ({ defaultPath, migrate }: LoadConfigOptions = {}): Config { +export function loadConfig ({ defaultPath }: LoadConfigOptions = {}): Config { let config: Config = {} try { if (process.env.CONFIG) { @@ -48,7 +46,6 @@ export function loadConfig ({ defaultPath, migrate }: LoadConfigOptions = {}): C console.log(e) } - migrate?.(config) currentConfig = config return config } diff --git a/shared/src/http.ts b/shared/src/http.ts index 7cfa5b1..149c244 100644 --- a/shared/src/http.ts +++ b/shared/src/http.ts @@ -1,7 +1,5 @@ import { NextFunction, Request, Response } from 'express-serve-static-core' import { getConfigOption } from './config/access' -import { respondToInvalidRequest } from './invalidRequest' -import { log } from './utils/log' /** * Apply the response headers configured under `ipp.responseHeaders` to the @@ -15,7 +13,7 @@ export function addResponseHeaders (res: Response): void { }) } -/** Stop browsers and shared caches storing a response from a password-protected share. */ +/** Stop browsers and shared caches storing a response: a password-protected share, or an error. */ export function addNoStoreHeaders (res: Response): void { res.set('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate') res.set('Pragma', 'no-cache') @@ -31,17 +29,3 @@ export function asyncHandler (fn: (req: Request, res: Response, next: NextFuncti fn(req, res, next).catch(next) } } - -/** - * Terminal Express error middleware. Logs the error server-side, then applies the - * same privacy policy as any other invalid request. - */ -export function errorHandler (err: unknown, req: Request, res: Response, _next: NextFunction): void { - log.error('Error handling ' + req.method + ' ' + req.path + ' - ' + - (err instanceof Error ? (err.stack || err.message) : String(err))) - if (res.headersSent) { - res.end() - return - } - respondToInvalidRequest(res, 404, 'Unhandled error for ' + req.path) -} diff --git a/shared/src/immich/client.ts b/shared/src/immich/client.ts index 9c82c39..138e0ac 100644 --- a/shared/src/immich/client.ts +++ b/shared/src/immich/client.ts @@ -78,7 +78,7 @@ export async function accessible () { } // Minimum Immich server version IPP is compatible with -export const MIN_IMMICH_VERSION: ImmichVersion = { major: 2, minor: 0, patch: 0 } +export const MIN_IMMICH_VERSION: ImmichVersion = { major: 3, minor: 0, patch: 0 } const formatVersion = (v: ImmichVersion) => `${v.major}.${v.minor}.${v.patch}` diff --git a/shared/src/invalidRequest.ts b/shared/src/invalidRequest.ts index 32a2a5c..27d058c 100644 --- a/shared/src/invalidRequest.ts +++ b/shared/src/invalidRequest.ts @@ -1,5 +1,6 @@ -import { Response } from 'express-serve-static-core' +import { NextFunction, Request, Response } from 'express-serve-static-core' import { getConfigOption } from './config/access' +import { addNoStoreHeaders } from './http' import { log } from './utils/log' /** The public contract of a 404 handler, kept stable for operator replacements. */ @@ -60,7 +61,25 @@ export function setInvalidRequestHandler (fn: InvalidRequestHandler): void { /** * Answer an invalid request through the registered handler. Every caller, in * core and in the apps, goes through here so a replacement applies everywhere. + * + * Never cacheable: routes apply `ipp.responseHeaders` (a 30-day public TTL by + * default) before they know the request is valid. */ export function respondToInvalidRequest (res: Response, defaultResponse: number | string | null, logMessage = ''): void { + addNoStoreHeaders(res) handler(res, defaultResponse, logMessage) } + +/** + * Terminal Express error middleware. Logs the error server-side, then applies the + * same privacy policy as any other invalid request. + */ +export function errorHandler (err: unknown, req: Request, res: Response, _next: NextFunction): void { + log.error('Error handling ' + req.method + ' ' + req.path + ' - ' + + (err instanceof Error ? (err.stack || err.message) : String(err))) + if (res.headersSent) { + res.end() + return + } + respondToInvalidRequest(res, 404, 'Unhandled error for ' + req.path) +} diff --git a/shared/src/types.ts b/shared/src/types.ts index 51977be..77d8b7a 100644 --- a/shared/src/types.ts +++ b/shared/src/types.ts @@ -10,11 +10,6 @@ export enum KeyType { export interface ExifInfo { description?: string; - exifImageWidth?: number; - exifImageHeight?: number; - // EXIF orientation string ("1".."8") or null. Values 5-8 indicate the image - // is rotated 90°/270°, so the displayed aspect ratio swaps width/height. - orientation?: string | null; // Additional EXIF fields surfaced by Immich for the metadata sidebar // (gated server-side by ipp.showMetadata.exif.* and .location.* config). dateTimeOriginal?: string | null; diff --git a/shared/tests/errorHandling.test.ts b/shared/tests/errorHandling.test.ts index b00ab06..25040c2 100644 --- a/shared/tests/errorHandling.test.ts +++ b/shared/tests/errorHandling.test.ts @@ -2,7 +2,8 @@ import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest' import express from 'express' import type { Server } from 'http' import type { AddressInfo } from 'net' -import { asyncHandler, errorHandler } from '../src/http' +import { asyncHandler } from '../src/http' +import { errorHandler } from '../src/invalidRequest' /* Regression tests for the per-request crash class: under Express 4 a rejected @@ -26,6 +27,10 @@ describe('asyncHandler + errorHandler', () => { app.get('/boom', asyncHandler(async () => { throw new TypeError("Cannot read properties of undefined (reading 'headers')") })) + app.get('/public-boom', asyncHandler(async (_req, res) => { + res.set('Cache-Control', 'public, max-age=2592000') + throw new Error('failed after the operator headers were applied') + })) app.get('/mid-stream', asyncHandler(async (_req, res) => { res.status(200) res.write('partial') @@ -50,6 +55,12 @@ describe('asyncHandler + errorHandler', () => { expect(await res.text()).toBe('') }) + it('sends the 404 no-store, replacing the public TTL a route set first', async () => { + const res = await fetch(base + '/public-boom') + expect(res.status).toBe(404) + expect(res.headers.get('cache-control')).toContain('no-store') + }) + it('keeps serving other requests after a route has thrown', async () => { await fetch(base + '/boom') const res = await fetch(base + '/ok') diff --git a/shared/tests/immichVersion.test.ts b/shared/tests/immichVersion.test.ts index 666a47c..6a0b0f8 100644 --- a/shared/tests/immichVersion.test.ts +++ b/shared/tests/immichVersion.test.ts @@ -2,8 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest' import { getImmichVersion, isImmichVersionSupported, MIN_IMMICH_VERSION } from '../src/immich/client' // 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. +// IPP supports (3.0.0). function jsonResponse (body: unknown, status = 200) { return { @@ -20,13 +19,14 @@ describe('isImmichVersionSupported', () => { 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) + it('accepts newer major/minor/patch', () => { expect(isImmichVersionSupported({ major: 3, minor: 0, patch: 2 })).toBe(true) + expect(isImmichVersionSupported({ major: 3, minor: 4, patch: 0 })).toBe(true) expect(isImmichVersionSupported({ major: 4, minor: 0, patch: 0 })).toBe(true) }) - it('rejects 1.x, which predates the columnar timeline API', () => { + it('rejects 2.x and 1.x', () => { + expect(isImmichVersionSupported({ major: 2, minor: 7, patch: 5 })).toBe(false) expect(isImmichVersionSupported({ major: 1, minor: 137, patch: 3 })).toBe(false) expect(isImmichVersionSupported({ major: 1, minor: 125, patch: 7 })).toBe(false) })