From 7799fa71c9f237393e558c37a7a093af70d4d60c Mon Sep 17 00:00:00 2001
From: Alan Grainger <16197738+alangrainger@users.noreply.github.com>
Date: Fri, 5 Jun 2026 10:50:16 +1200
Subject: [PATCH] #244 Reverse metadata field defaults
---
CONTRIBUTING.md | 2 +-
README.md | 2 +-
app/config.json | 37 ++++----
app/src/client/init.ts | 2 +-
app/src/client/layout.ts | 4 +-
app/src/client/tiles.ts | 2 +-
app/src/config/migrations.ts | 122 +++++++++++++++++++++-----
app/src/gallery/builder.ts | 10 +--
app/src/gallery/exif.ts | 160 +++++++++++++++++++++++++----------
app/src/shared/types.ts | 10 +--
app/src/view/gallery.tsx | 2 +-
11 files changed, 246 insertions(+), 107 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e9cb545..4d5600c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -59,7 +59,7 @@ app/
text.ts escapeHtml + toString narrowing
view/ Preact SSR templates (.tsx)
shared/types.ts Types shared between server SSR and client (GalleryItem, etc.)
- client/ Client gallery, virtualization, lightbox, sidebar
+ client/ Client gallery, virtualisation, lightbox, sidebar
public/ Static assets served as-is
photoswipe/ Vendored PhotoSwipe v5
thumbhash/, fonts/, images/
diff --git a/README.md b/README.md
index 5751775..1ea8347 100644
--- a/README.md
+++ b/README.md
@@ -84,7 +84,7 @@ Check the container console output for any error messages.
docker-compose up -d
```
-6. Set the "External domain" in your Immich **Server Settings** to be whatever domain you use to publicly serve Immich Public Proxy:
+5. Set the "External domain" in your Immich **Server Settings** to be whatever domain you use to publicly serve Immich Public Proxy:
diff --git a/app/config.json b/app/config.json
index c3f0f37..f73867e 100644
--- a/app/config.json
+++ b/app/config.json
@@ -5,7 +5,7 @@
"Access-Control-Allow-Origin": "*"
},
"downloadOriginalPhoto": true,
- "downloadedFilename": 2,
+ "downloadedFilename": 0,
"allowDownloadAll": 0,
"downloadFromImmichConcurrencyLimit": 20,
"allowSlugLinks": true,
@@ -16,26 +16,25 @@
"sidebar": false
},
"exif": {
- "enabled": false,
- "dateTimeOriginal": true,
- "fileName": true,
- "dimensions": true,
- "fileSize": true,
- "make": true,
- "model": true,
- "lensModel": true,
- "exposureTime": true,
- "iso": true,
- "fNumber": true,
- "focalLength": true
+ "enableAll": false,
+ "dateTimeOriginal": false,
+ "fileName": false,
+ "dimensions": false,
+ "fileSize": false,
+ "make": false,
+ "model": false,
+ "lensModel": false,
+ "exposureTime": false,
+ "iso": false,
+ "fNumber": false,
+ "focalLength": false
},
"location": {
- "enabled": false,
- "city": true,
- "state": true,
- "country": true,
- "gps": true,
- "webLink": true
+ "enableAll": false,
+ "city": false,
+ "state": false,
+ "country": false,
+ "gps": false
}
},
"customInvalidResponse": false,
diff --git a/app/src/client/init.ts b/app/src/client/init.ts
index 7134957..2950eea 100644
--- a/app/src/client/init.ts
+++ b/app/src/client/init.ts
@@ -11,7 +11,7 @@ import type { InitParams } from '../shared/types.js'
import { state } from './state.js'
import { setupToolbar } from './selection.js'
import { initLightbox, openLightbox } from './lightbox.js'
-import { computeLayoutAndRender, onScroll } from './virtualization.js'
+import { computeLayoutAndRender, onScroll } from './virtualisation.js'
function readInitParams (): InitParams {
const el = document.getElementById('ipp-init')
diff --git a/app/src/client/layout.ts b/app/src/client/layout.ts
index c076b86..cb3f193 100644
--- a/app/src/client/layout.ts
+++ b/app/src/client/layout.ts
@@ -1,6 +1,6 @@
// Justified-rows + square-grid layout, with optional month grouping. Pure
// geometry: takes a container width, returns positions for every tile and
-// every header. Called by virtualization on first render and on resize.
+// every header. Called by virtualisation on first render and on resize.
import {
state,
@@ -26,7 +26,7 @@ export interface LayoutResult {
* for the gallery at the given container width.
*
* Reads `state.items` and `state.groupByDate`. Output is pure data - the
- * caller (virtualization) is responsible for actually placing DOM nodes
+ * caller (virtualisation) is responsible for actually placing DOM nodes
* according to the returned positions.
*
* Switches between a mobile square grid (under MOBILE_BREAKPOINT) and the
diff --git a/app/src/client/tiles.ts b/app/src/client/tiles.ts
index 78b9a94..ce828c9 100644
--- a/app/src/client/tiles.ts
+++ b/app/src/client/tiles.ts
@@ -15,7 +15,7 @@ function onThumbError (this: HTMLImageElement) {
}
// Cache of decoded thumbhash → PNG data URL. Same thumbhash on multiple
-// tile-creations (revisits during virtualization) reuses the same URL.
+// tile-creations (revisits during virtualisation) reuses the same URL.
const thumbhashCache = new Map()
function decodeThumbhash (base64: string): string | null {
diff --git a/app/src/config/migrations.ts b/app/src/config/migrations.ts
index d5321d8..54e4557 100644
--- a/app/src/config/migrations.ts
+++ b/app/src/config/migrations.ts
@@ -1,28 +1,46 @@
-// Backward-compatability shims that map legacy `config.json` key shapes
-// onto their current locations. Each one only fills in values the user
-// hasn't explicitly set on the new path, and prints a one-time deprecation
-// warning to the startup log.
-//
-// Delete in v3.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: 'enableAll', removeIn: 'v3.0', apply: applyEnableAllShim }
+]
+
/**
- * Apply every supported legacy-config shim to `config` in place.
+ * 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 {
- applyLightGalleryShim(config)
- applyTopLevelGalleryShim(config)
- applyDescriptionSplitShim(config)
+ for (const shim of SHIMS) shim.apply(config)
}
/**
- * 1.x users with a legacy `lightGallery.*` config section.
- * Maps `lightGallery.controls`, `lightGallery.download`, and
- * `lightGallery.mobileSettings.controls` onto `ipp.lightbox.*`.
- *
- * Delete in v3.0.
+ * 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
@@ -49,11 +67,10 @@ function applyLightGalleryShim (config: Config): void {
}
/**
- * 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.
- *
- * Delete in v3.0.
+ * 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
@@ -82,13 +99,12 @@ function applyTopLevelGalleryShim (config: Config): void {
}
/**
+ * 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.
- *
- * Delete in v3.0.
*/
function applyDescriptionSplitShim (config: Config): void {
const ipp = (config.ipp || (config.ipp = {})) as Record
@@ -105,3 +121,65 @@ function applyDescriptionSplitShim (config: Config): void {
'independently. See README.'
)
}
+
+/**
+ * SHIM: showMetadata.{exif,location}.enabled -> .enableAll, with per-
+ * field defaults flipped from `true` to `false`.
+ *
+ * New semantics: `enableAll: true` shows every field in the group;
+ * `enableAll: false` shows only fields with an explicit per-field `true`.
+ *
+ * Two compatibility hazards the shim guards against:
+ * (a) Old shipped `config.json` used `enabled: false` with every
+ * per-field flag set to `true` as documentation. Under new
+ * semantics those would become live opt-ins. When the legacy
+ * `enabled` was `false`, the shim zeroes out per-field flags so
+ * the runtime keeps the "nothing visible" behaviour the user had.
+ * (b) `enabled: true` with selective per-field `false` (e.g. to hide
+ * GPS while showing the rest of location) is no longer expressible
+ * because `enableAll: true` overrides per-field flags. The shim
+ * can't preserve that without enumerating every other field; we
+ * just log a warning telling the user to rewrite as explicit
+ * opt-ins.
+ */
+function applyEnableAllShim (config: Config): void {
+ const ipp = (config.ipp || (config.ipp = {})) as Record
+ const showMetadata = ipp.showMetadata as Record | undefined
+ if (!showMetadata) return
+
+ let migrated = false
+ for (const groupName of ['exif', 'location']) {
+ const group = showMetadata[groupName] as Record | undefined
+ if (!group || typeof group !== 'object') continue
+ if (group.enabled === undefined) continue
+
+ const legacyEnabled = !!group.enabled
+ if (group.enableAll === undefined) {
+ group.enableAll = legacyEnabled
+ }
+ delete group.enabled
+
+ // Hazard (a): zero out per-field flags when the legacy master was
+ // off. Under the old semantic those flags were dead code, so wiping
+ // them is a no-op behaviour-wise but stops the new semantic from
+ // treating them as live opt-ins.
+ if (!legacyEnabled) {
+ for (const key of Object.keys(group)) {
+ if (key === 'enableAll') continue
+ if (typeof group[key] === 'boolean') group[key] = false
+ }
+ }
+
+ migrated = true
+ }
+
+ if (migrated) {
+ console.log(
+ '[IPP] `ipp.showMetadata.exif.enabled` / `.location.enabled` are ' +
+ 'deprecated; renamed to `enableAll`. Per-field defaults are now ' +
+ '`false` and `enableAll: true` overrides them, so any per-field ' +
+ '`false` that used to subtract from an all-on group is now ignored. ' +
+ 'See README to rewrite "show all except X" as explicit opt-ins.'
+ )
+ }
+}
diff --git a/app/src/gallery/builder.ts b/app/src/gallery/builder.ts
index f4a8bef..662d155 100644
--- a/app/src/gallery/builder.ts
+++ b/app/src/gallery/builder.ts
@@ -14,7 +14,7 @@ import { h } from 'preact'
import { renderPage } from '../view/render'
import { Gallery, GalleryItem, GalleryProps } from '../view/gallery'
import { getFilename } from './filename'
-import { pickExif } from './exif'
+import { metadataGroupActive, pickExif } from './exif'
/**
* Render a gallery page for a given SharedLink.
@@ -39,10 +39,7 @@ export async function gallery (res: Response, share: SharedLink, openItem?: numb
// `metadataConfig` in the init JSON.
const descriptionInCaption = !!getConfigOption('ipp.showMetadata.description.caption', false)
const descriptionInSidebar = !!getConfigOption('ipp.showMetadata.description.sidebar', false)
- const exifGroupEnabled = !!getConfigOption('ipp.showMetadata.exif.enabled', false)
- const locationGroupEnabled = !!getConfigOption('ipp.showMetadata.location.enabled', false)
- const locationWebLink = locationGroupEnabled && !!getConfigOption('ipp.showMetadata.location.webLink', true)
- const sidebarHasContent = descriptionInSidebar || exifGroupEnabled || locationGroupEnabled
+ const sidebarHasContent = descriptionInSidebar || metadataGroupActive('exif') || metadataGroupActive('location')
// Build structured items in parallel
const items: GalleryItem[] = await Promise.all(share.assets.map(async (asset): Promise => {
@@ -135,8 +132,7 @@ export async function gallery (res: Response, share: SharedLink, openItem?: numb
metadataConfig: {
descriptionInCaption,
descriptionInSidebar,
- sidebarHasContent,
- locationWebLink
+ sidebarHasContent
},
groupByDate
}
diff --git a/app/src/gallery/exif.ts b/app/src/gallery/exif.ts
index 57a7174..4b3a740 100644
--- a/app/src/gallery/exif.ts
+++ b/app/src/gallery/exif.ts
@@ -1,16 +1,97 @@
-import { Asset } from '../types'
+import { Asset, ExifInfo } from '../types'
import { GalleryExif } from '../shared/types'
import { getConfigOption } from '../config/access'
+type Group = 'exif' | 'location'
+
+interface FieldRule {
+ // Config flag name, relative to the group (e.g. 'gps' -> ipp.showMetadata.location.gps)
+ flag: string
+ // Copies values from the Immich-side ExifInfo (+ asset for fileName) onto
+ // the gallery-side GalleryExif if they're present and non-empty.
+ emit: (out: GalleryExif, info: ExifInfo, asset: Asset) => void
+}
+
+/**
+ * Trivial copy: `out[key] = info[key]` when present. Used for fields where
+ * the config flag, source key, and output key all match.
+ */
+function copy (key: keyof ExifInfo & keyof GalleryExif): FieldRule {
+ return {
+ flag: key,
+ emit: (out, info) => {
+ const value = info[key]
+ if (value != null && value !== '') (out as Record)[key] = value
+ }
+ }
+}
+
+/*
+ Fields whose config flag, ExifInfo key, and GalleryExif key are all the
+ same string. `copy` handles the whole if/copy dance for each. Fields
+ that need special handling (fileName, dimensions, fileSize, gps) appear
+ inline in the `*_RULES` arrays below.
+*/
+const EXIF_FIELDS = [
+ 'dateTimeOriginal', 'make', 'model', 'lensModel',
+ 'exposureTime', 'iso', 'fNumber', 'focalLength'
+] as const
+
+const LOCATION_FIELDS = ['city', 'state', 'country'] as const
+
+const EXIF_RULES: FieldRule[] = [
+ ...EXIF_FIELDS.map(copy),
+ {
+ flag: 'fileName',
+ emit: (out, _info, asset) => {
+ if (asset.originalFileName) out.fileName = asset.originalFileName
+ }
+ },
+ {
+ flag: 'dimensions',
+ emit: (out, info) => {
+ if (info.exifImageWidth && info.exifImageHeight) {
+ out.width = info.exifImageWidth
+ out.height = info.exifImageHeight
+ }
+ }
+ },
+ {
+ flag: 'fileSize',
+ emit: (out, info) => {
+ if (info.fileSizeInByte) out.fileSizeInByte = info.fileSizeInByte
+ }
+ }
+]
+
+const LOCATION_RULES: FieldRule[] = [
+ ...LOCATION_FIELDS.map(copy),
+ {
+ flag: 'gps',
+ emit: (out, info) => {
+ if (info.latitude != null && info.longitude != null) {
+ out.latitude = info.latitude
+ out.longitude = info.longitude
+ }
+ }
+ }
+]
+
+const RULES: Record = {
+ exif: EXIF_RULES,
+ location: LOCATION_RULES
+}
+
/**
* Build the per-asset metadata sub-object included in the gallery JSON.
* Reads `ipp.showMetadata.exif.*` and `ipp.showMetadata.location.*` config:
- * each group has a master `enabled` toggle, and within each group the
- * per-field flags default to `true`. A field appears in the output only
- * when both the group is enabled AND the field's own flag is true.
+ * each group has a master `enableAll` toggle and a set of per-field flags
+ * that all default to `false`. A field appears in the output when either
+ * the group's `enableAll` is true, OR the field's own flag is true.
*
- * Returns `undefined` when neither group is enabled, or when no fields
- * survive gating (so the client knows there's no metadata to show).
+ * Returns `undefined` when neither group has any visible content, or when
+ * no fields survive gating (so the client knows there's no metadata to
+ * show).
*
* The server never sends Immich values that the operator hasn't opted in
* to via config; the client just renders what's present.
@@ -19,52 +100,37 @@ export function pickExif (asset: Asset): GalleryExif | undefined {
const exifInfo = asset?.exifInfo
if (!exifInfo) return undefined
- const exifEnabled = !!getConfigOption('ipp.showMetadata.exif.enabled', false)
- const locationEnabled = !!getConfigOption('ipp.showMetadata.location.enabled', false)
- if (!exifEnabled && !locationEnabled) return undefined
+ const exifActive = metadataGroupActive('exif')
+ const locationActive = metadataGroupActive('location')
+ if (!exifActive && !locationActive) return undefined
const out: GalleryExif = {}
-
- if (exifEnabled) {
- if (allow('exif.dateTimeOriginal') && exifInfo.dateTimeOriginal) {
- out.dateTimeOriginal = exifInfo.dateTimeOriginal
- }
- if (allow('exif.fileName') && asset.originalFileName) {
- out.fileName = asset.originalFileName
- }
- if (allow('exif.dimensions') && exifInfo.exifImageWidth && exifInfo.exifImageHeight) {
- out.width = exifInfo.exifImageWidth
- out.height = exifInfo.exifImageHeight
- }
- if (allow('exif.fileSize') && exifInfo.fileSizeInByte) {
- out.fileSizeInByte = exifInfo.fileSizeInByte
- }
- if (allow('exif.make') && exifInfo.make) out.make = exifInfo.make
- if (allow('exif.model') && exifInfo.model) out.model = exifInfo.model
- if (allow('exif.lensModel') && exifInfo.lensModel) out.lensModel = exifInfo.lensModel
- if (allow('exif.exposureTime') && exifInfo.exposureTime) out.exposureTime = exifInfo.exposureTime
- if (allow('exif.iso') && exifInfo.iso) out.iso = exifInfo.iso
- if (allow('exif.fNumber') && exifInfo.fNumber) out.fNumber = exifInfo.fNumber
- if (allow('exif.focalLength') && exifInfo.focalLength) out.focalLength = exifInfo.focalLength
- }
-
- if (locationEnabled) {
- if (allow('location.city') && exifInfo.city) out.city = exifInfo.city
- if (allow('location.state') && exifInfo.state) out.state = exifInfo.state
- if (allow('location.country') && exifInfo.country) out.country = exifInfo.country
- if (allow('location.gps') && exifInfo.latitude != null && exifInfo.longitude != null) {
- out.latitude = exifInfo.latitude
- out.longitude = exifInfo.longitude
- }
- }
-
+ if (exifActive) applyRules('exif', out, exifInfo, asset)
+ if (locationActive) applyRules('location', out, exifInfo, asset)
return Object.keys(out).length ? out : undefined
}
/**
- * Per-field gate. Defaults to `true` so that turning on a group exposes
- * every field unless the operator explicitly opts out of one.
+ * Returns true if a metadata group would render any field for the current
+ * config - either `enableAll` is set, or at least one per-field flag is
+ * explicitly `true`. Used by the sidebar visibility check.
*/
-function allow (field: string): boolean {
- return !!getConfigOption(`ipp.showMetadata.${field}`, true)
+export function metadataGroupActive (group: Group): boolean {
+ if (groupEnableAll(group)) return true
+ return RULES[group].some(rule => fieldFlag(group, rule.flag))
+}
+
+function applyRules (group: Group, out: GalleryExif, info: ExifInfo, asset: Asset): void {
+ const enableAll = groupEnableAll(group)
+ for (const rule of RULES[group]) {
+ if (enableAll || fieldFlag(group, rule.flag)) rule.emit(out, info, asset)
+ }
+}
+
+function groupEnableAll (group: Group): boolean {
+ return !!getConfigOption(`ipp.showMetadata.${group}.enableAll`, false)
+}
+
+function fieldFlag (group: Group, flag: string): boolean {
+ return !!getConfigOption(`ipp.showMetadata.${group}.${flag}`, false)
}
diff --git a/app/src/shared/types.ts b/app/src/shared/types.ts
index e88bd4b..ca21da8 100644
--- a/app/src/shared/types.ts
+++ b/app/src/shared/types.ts
@@ -6,10 +6,10 @@
/**
* Per-asset EXIF / location metadata shown in the info sidebar. Each field
- * is optional - the server only includes a field if both the group is
- * enabled (`ipp.showMetadata.exif.enabled` or `.location.enabled`) and the
- * per-field flag is true. Strings are plain text (the client uses
- * `textContent`, not `innerHTML`).
+ * is optional - the server only includes a field when either the group's
+ * `enableAll` is true (`ipp.showMetadata.exif.enableAll` /
+ * `.location.enableAll`) or the field's own per-field flag is true.
+ * Strings are plain text (the client uses `textContent`, not `innerHTML`).
*/
export interface GalleryExif {
dateTimeOriginal?: string // ISO date string; client formats with Intl.DateTimeFormat
@@ -45,7 +45,7 @@ export interface GalleryItem {
description?: string
downloadFilename: string
// Display dimensions after EXIF orientation correction; needed for the
- // pre-computed justified-rows layout that virtualization depends on.
+ // pre-computed justified-rows layout that virtualisation depends on.
width?: number
height?: number
// Base64-encoded thumbhash for an optional blur placeholder behind each tile
diff --git a/app/src/view/gallery.tsx b/app/src/view/gallery.tsx
index 5c6e83f..7d1aa1b 100644
--- a/app/src/view/gallery.tsx
+++ b/app/src/view/gallery.tsx
@@ -83,7 +83,7 @@ export function Gallery (props: GalleryProps) {
{props.description && (
{props.description}
)}
-{/* Container is intentionally empty - web.js's virtualization manager
+{/* Container is intentionally empty - web.js's virtualisation manager
populates it with only the tiles within the viewport buffer. */}
{props.showDownload && (