From cefe2e81ff2b2d943e9e36ae7a9fbbe3597c616b Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Fri, 5 Jun 2026 12:46:28 +1200 Subject: [PATCH] Refactor duplicated patterns into shared helpers --- app/src/client/sidebar.ts | 111 ++++++++++++++++++------------- app/src/client/virtualisation.ts | 51 ++++++++------ app/src/config/migrations.ts | 6 ++ app/src/gallery/exif.ts | 9 +++ app/src/immich.ts | 49 +++----------- app/src/utils/ttlLruCache.ts | 68 +++++++++++++++++++ app/tests/ttlLruCache.test.ts | 110 ++++++++++++++++++++++++++++++ 7 files changed, 294 insertions(+), 110 deletions(-) create mode 100644 app/src/utils/ttlLruCache.ts create mode 100644 app/tests/ttlLruCache.test.ts diff --git a/app/src/client/sidebar.ts b/app/src/client/sidebar.ts index 2d16143..dfe691d 100644 --- a/app/src/client/sidebar.ts +++ b/app/src/client/sidebar.ts @@ -123,6 +123,10 @@ 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. function renderContents (root: HTMLElement, item: GalleryItem | undefined) { root.replaceChildren() @@ -213,67 +217,78 @@ function renderDateRow (iso: string): HTMLElement { return row } -function renderFileRow (exif: GalleryExif): HTMLElement | null { - if (!exif.fileName && !exif.width && !exif.fileSizeInByte) return null - const row = makeRow(ICON_IMAGE) +interface RowSpec { + icon: string + // Title paragraph at the top of the row body. Falsy values are omitted. + label?: string | null + labelClass?: string + // Stats rendered as `` chips in a flex row beneath the label. + // Nullish entries are skipped, so callers can write + // `exif.iso != null ? 'ISO ' + exif.iso : null` and not branch. + stats: Array +} + +/** + * Build one info-sidebar row. Returns `null` when the row would have + * neither a label nor any non-null stat, so the caller can skip appending. + */ +function renderRow (spec: RowSpec): HTMLElement | null { + const presentStats = spec.stats.filter((s): s is string => s != null && s !== '') + if (!spec.label && presentStats.length === 0) return null + + const row = makeRow(spec.icon) const body = row.querySelector('.ipp-sidebar-row-body') as HTMLElement - if (exif.fileName) { - const name = document.createElement('p') - name.className = 'ipp-sidebar-filename' - name.textContent = exif.fileName - body.appendChild(name) + if (spec.label) { + const p = document.createElement('p') + if (spec.labelClass) p.className = spec.labelClass + p.textContent = spec.label + body.appendChild(p) } - if (exif.width && exif.height) { + if (presentStats.length) { const stats = document.createElement('div') stats.className = 'ipp-sidebar-stats' - const mp = Math.round((exif.width * exif.height) / 1_000_000) - if (mp >= 1) stats.appendChild(makeStat(mp + ' MP')) - stats.appendChild(makeStat(exif.width + ' x ' + exif.height)) - if (exif.fileSizeInByte) stats.appendChild(makeStat(formatBytes(exif.fileSizeInByte))) - body.appendChild(stats) - } else if (exif.fileSizeInByte) { - const stats = document.createElement('div') - stats.className = 'ipp-sidebar-stats' - stats.appendChild(makeStat(formatBytes(exif.fileSizeInByte))) + for (const s of presentStats) stats.appendChild(makeStat(s)) body.appendChild(stats) } return row } +function renderFileRow (exif: GalleryExif): HTMLElement | null { + const hasDims = !!(exif.width && exif.height) + const mp = hasDims ? Math.round((exif.width! * exif.height!) / 1_000_000) : 0 + return renderRow({ + icon: ICON_IMAGE, + label: exif.fileName, + labelClass: 'ipp-sidebar-filename', + stats: [ + hasDims && mp >= 1 ? mp + ' MP' : null, + hasDims ? exif.width + ' x ' + exif.height : null, + exif.fileSizeInByte ? formatBytes(exif.fileSizeInByte) : null + ] + }) +} + function renderCameraRow (exif: GalleryExif): HTMLElement | null { - if (!exif.make && !exif.model && exif.exposureTime == null && exif.iso == null) return null - const row = makeRow(ICON_CAMERA) - const body = row.querySelector('.ipp-sidebar-row-body') as HTMLElement - const label = [exif.make, exif.model].filter(Boolean).join(' ').trim() - if (label) { - const p = document.createElement('p') - p.textContent = label - body.appendChild(p) - } - const stats = document.createElement('div') - stats.className = 'ipp-sidebar-stats' - if (exif.exposureTime) stats.appendChild(makeStat(exif.exposureTime + ' s')) - if (exif.iso != null) stats.appendChild(makeStat('ISO ' + exif.iso)) - if (stats.childElementCount) body.appendChild(stats) - return row + return renderRow({ + icon: ICON_CAMERA, + label: [exif.make, exif.model].filter(Boolean).join(' ').trim() || null, + stats: [ + exif.exposureTime ? exif.exposureTime + ' s' : null, + exif.iso != null ? 'ISO ' + exif.iso : null + ] + }) } function renderLensRow (exif: GalleryExif): HTMLElement | null { - if (!exif.lensModel && exif.fNumber == null && exif.focalLength == null) return null - const row = makeRow(ICON_IRIS) - const body = row.querySelector('.ipp-sidebar-row-body') as HTMLElement - if (exif.lensModel) { - const p = document.createElement('p') - p.className = 'ipp-sidebar-lens' - p.textContent = exif.lensModel - body.appendChild(p) - } - const stats = document.createElement('div') - stats.className = 'ipp-sidebar-stats' - if (exif.fNumber != null) stats.appendChild(makeStat('f/' + exif.fNumber)) - if (exif.focalLength != null) stats.appendChild(makeStat(exif.focalLength + ' mm')) - if (stats.childElementCount) body.appendChild(stats) - return row + return renderRow({ + icon: ICON_IRIS, + label: exif.lensModel, + labelClass: 'ipp-sidebar-lens', + stats: [ + exif.fNumber != null ? 'f/' + exif.fNumber : null, + exif.focalLength != null ? exif.focalLength + ' mm' : null + ] + }) } function renderLocation (exif: GalleryExif): HTMLElement { diff --git a/app/src/client/virtualisation.ts b/app/src/client/virtualisation.ts index 6b2698d..8913788 100644 --- a/app/src/client/virtualisation.ts +++ b/app/src/client/virtualisation.ts @@ -56,18 +56,7 @@ export function virtualize () { if (l.top > bottom) break neededTiles.add(l.index) } - for (const [index, el] of state.renderedTiles) { - if (!neededTiles.has(index)) { - el.remove() - state.renderedTiles.delete(index) - } - } - for (const index of neededTiles) { - if (state.renderedTiles.has(index)) continue - const tile = createTile(index) - state.container.appendChild(tile) - state.renderedTiles.set(index, tile) - } + syncRendered(neededTiles, state.renderedTiles, createTile) // Group headers (when grouping is enabled; headers is empty otherwise) const neededHeaders = new Set() @@ -76,19 +65,39 @@ export function virtualize () { if (h.top > bottom) break neededHeaders.add(h.label) } - for (const [label, el] of state.renderedHeaders) { - if (!neededHeaders.has(label)) { + syncRendered(neededHeaders, state.renderedHeaders, (label) => { + const h = state.headers.find(x => x.label === label) + return h ? createHeader(h) : null + }) +} + +/** + * Reconcile a Map of rendered DOM elements against the set of keys that + * should currently be on screen: remove elements whose key is no longer + * needed, then create + append elements for keys that aren't rendered yet. + * + * The `create` callback may return `null` when the key can't be resolved + * (e.g. a stale header label that no longer matches any layout entry); in + * that case nothing is added for the key and the Map is left alone. + */ +function syncRendered ( + needed: Set, + rendered: Map, + create: (key: K) => HTMLElement | null +): void { + if (!state.container) return + for (const [key, el] of rendered) { + if (!needed.has(key)) { el.remove() - state.renderedHeaders.delete(label) + rendered.delete(key) } } - for (const label of neededHeaders) { - if (state.renderedHeaders.has(label)) continue - const h = state.headers.find(x => x.label === label) - if (!h) continue - const el = createHeader(h) + for (const key of needed) { + if (rendered.has(key)) continue + const el = create(key) + if (!el) continue state.container.appendChild(el) - state.renderedHeaders.set(label, el) + rendered.set(key, el) } } diff --git a/app/src/config/migrations.ts b/app/src/config/migrations.ts index 65b9b84..bfa6400 100644 --- a/app/src/config/migrations.ts +++ b/app/src/config/migrations.ts @@ -146,6 +146,12 @@ function applyDescriptionSplitShim (config: Config): void { * 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', diff --git a/app/src/gallery/exif.ts b/app/src/gallery/exif.ts index 0e2537a..2ffbb93 100644 --- a/app/src/gallery/exif.ts +++ b/app/src/gallery/exif.ts @@ -31,6 +31,15 @@ function copy (key: keyof ExifInfo & keyof GalleryExif): FieldRule { 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. + + 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). */ const EXIF_FIELDS = [ 'dateTimeOriginal', 'make', 'model', 'lensModel', diff --git a/app/src/immich.ts b/app/src/immich.ts index 4cc43ae..f52d47c 100644 --- a/app/src/immich.ts +++ b/app/src/immich.ts @@ -23,6 +23,7 @@ import { renderPage } from './view/render' import { Password } from './view/password' import { respondToInvalidRequest } from './invalidRequestHandler' import { encrypt } from './encrypt' +import { TtlLruCache } from './utils/ttlLruCache' /* In-process cache for share-link lookups. Each direct-asset request (e.g. @@ -40,15 +41,8 @@ import { encrypt } from './encrypt' across concurrent requests. Current callers (notably the in-place `share.assets.sort(...)` in render.ts) happen to be idempotent so this is safe today, but new callers should clone before mutating. - - Eviction is LRU: each cache hit moves the entry to the end of the Map's - insertion order, and overflow drops the oldest (least-recently-used) - entry. TTL handles freshness; size cap handles memory. */ -type ShareCacheEntry = { promise: Promise; expiresAt: number } -const shareCache = new Map() -const shareCacheTtlMs = 120_000 -const shareCacheMax = 100 +const shareCache = new TtlLruCache>({ ttlMs: 120_000, max: 100 }) /* Immich replaced the deprecated `?password=...` query-param auth for shared @@ -60,10 +54,7 @@ const shareCacheMax = 100 cache key (often empty) and falls through to a fresh login that Immich will reject - IPP never serves cached tokens to unauthenticated visitors. */ -type TokenCacheEntry = { promise: Promise; expiresAt: number } -const tokenCache = new Map() -const tokenCacheTtlMs = 120_000 -const tokenCacheMax = 100 +const tokenCache = new TtlLruCache>({ ttlMs: 120_000, max: 100 }) /** * Make a request to Immich API. We're not using the SDK to limit @@ -197,24 +188,11 @@ export async function handleShareRequest (req: IncomingShareRequest, res: Respon */ export async function getShareByKey (key: string, password?: string, keyType: KeyType = KeyType.key): Promise { const cacheKey = `${keyType}:${key}:${password ?? ''}` - const now = Date.now() const cached = shareCache.get(cacheKey) - if (cached && cached.expiresAt > now) { - // Move-to-end to mark this entry as most-recently-used for LRU eviction - shareCache.delete(cacheKey) - shareCache.set(cacheKey, cached) - return cached.promise - } + if (cached) return cached const promise = fetchShareByKey(key, password, keyType) - shareCache.set(cacheKey, { - promise, - expiresAt: now + shareCacheTtlMs - }) - if (shareCache.size > shareCacheMax) { - const oldest = shareCache.keys().next().value - if (oldest !== undefined && oldest !== cacheKey) shareCache.delete(oldest) - } + shareCache.set(cacheKey, promise) promise.then( (result) => { if (!result?.valid) shareCache.delete(cacheKey) }, () => { shareCache.delete(cacheKey) } @@ -352,22 +330,11 @@ export async function authHeaders (keyType: KeyType, key: string, password?: str */ async function getSharedLinkToken (key: string, password: string, keyType: KeyType): Promise { const cacheKey = `${keyType}:${key}:${password}` - const now = Date.now() const cached = tokenCache.get(cacheKey) - if (cached && cached.expiresAt > now) { - tokenCache.delete(cacheKey) - tokenCache.set(cacheKey, cached) - return cached.promise - } + if (cached) return cached + const promise = sharedLinkLogin(key, password, keyType) - tokenCache.set(cacheKey, { - promise, - expiresAt: now + tokenCacheTtlMs - }) - if (tokenCache.size > tokenCacheMax) { - const oldest = tokenCache.keys().next().value - if (oldest !== undefined && oldest !== cacheKey) tokenCache.delete(oldest) - } + tokenCache.set(cacheKey, promise) promise.then( (token) => { if (!token) tokenCache.delete(cacheKey) }, () => { tokenCache.delete(cacheKey) } diff --git a/app/src/utils/ttlLruCache.ts b/app/src/utils/ttlLruCache.ts new file mode 100644 index 0000000..b375278 --- /dev/null +++ b/app/src/utils/ttlLruCache.ts @@ -0,0 +1,68 @@ +/* + Time-to-live + size-bounded LRU cache. Used by `immich.ts` to memoise + share-link lookups and `POST /shared-links/login` tokens, where: + + - TTL gives us freshness without rebuilding share state on every asset + request. + - LRU + size cap keeps memory bounded under a wide key space (one entry + per `(keyType, key, password)` combination). + - Move-to-end on `get` makes "recently accessed" stay alive across + bursts and lets long-tail keys age out. + + The cache is intentionally storage-only. Callers handle the "should this + value stay cached?" decision after the underlying fetch resolves (e.g. + delete on null result, delete on rejection). Keeping that policy at the + call site means we don't bake validation rules into a generic cache. +*/ + +interface Entry { + value: V + expiresAt: number +} + +export class TtlLruCache { + private readonly entries = new Map>() + private readonly ttlMs: number + private readonly max: number + + constructor (opts: { ttlMs: number, max: number }) { + this.ttlMs = opts.ttlMs + this.max = opts.max + } + + /** + * Get the value for `key`, refreshing its LRU position. Returns + * `undefined` if the entry is missing or expired (expired entries are + * dropped on access). + */ + get (key: string): V | undefined { + const entry = this.entries.get(key) + if (!entry) return undefined + if (entry.expiresAt <= Date.now()) { + this.entries.delete(key) + return undefined + } + // Move-to-end so LRU eviction drops the least recently accessed. + this.entries.delete(key) + this.entries.set(key, entry) + return entry.value + } + + /** + * Insert or replace `key` with `value` and a fresh TTL. Evicts the + * oldest entry when the cache exceeds its size cap (unless the oldest + * is the entry we just wrote, which shouldn't happen but is guarded + * just in case). + */ + set (key: string, value: V): void { + this.entries.set(key, { value, expiresAt: Date.now() + this.ttlMs }) + if (this.entries.size > this.max) { + const oldest = this.entries.keys().next().value + if (oldest !== undefined && oldest !== key) this.entries.delete(oldest) + } + } + + delete (key: string): void { + this.entries.delete(key) + } +} diff --git a/app/tests/ttlLruCache.test.ts b/app/tests/ttlLruCache.test.ts new file mode 100644 index 0000000..ca22a83 --- /dev/null +++ b/app/tests/ttlLruCache.test.ts @@ -0,0 +1,110 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest' +import { TtlLruCache } from '../src/utils/ttlLruCache' + +/* + All TTL-based assertions rely on Vitest's fake-timer system mocking + `Date.now()`. `vi.advanceTimersByTime` advances both the timer queue + and the system clock the cache reads from. +*/ + +beforeEach(() => { + vi.useFakeTimers() +}) + +afterEach(() => { + vi.useRealTimers() +}) + +describe('TtlLruCache', () => { + it('returns undefined for an unknown key', () => { + const cache = new TtlLruCache({ ttlMs: 1000, max: 10 }) + expect(cache.get('missing')).toBeUndefined() + }) + + it('returns the value after set', () => { + const cache = new TtlLruCache({ ttlMs: 1000, max: 10 }) + cache.set('a', 'apple') + expect(cache.get('a')).toBe('apple') + }) + + it('returns undefined exactly at the TTL boundary', () => { + const cache = new TtlLruCache({ ttlMs: 1000, max: 10 }) + cache.set('a', 'apple') + vi.advanceTimersByTime(999) + expect(cache.get('a')).toBe('apple') + vi.advanceTimersByTime(1) + expect(cache.get('a')).toBeUndefined() + }) + + it('drops expired entries on access so they do not count toward the size cap', () => { + const cache = new TtlLruCache({ ttlMs: 100, max: 2 }) + cache.set('a', '1') + vi.advanceTimersByTime(200) + // Read once so the expired entry is dropped from the internal map. + expect(cache.get('a')).toBeUndefined() + // The cache should now have capacity for two fresh entries with no + // collateral eviction of either. + cache.set('b', '2') + cache.set('c', '3') + expect(cache.get('b')).toBe('2') + expect(cache.get('c')).toBe('3') + }) +}) + +describe('TtlLruCache delete', () => { + it('removes an existing entry', () => { + const cache = new TtlLruCache({ ttlMs: 1000, max: 10 }) + cache.set('a', '1') + cache.delete('a') + expect(cache.get('a')).toBeUndefined() + }) + + it('is a no-op for a missing key', () => { + const cache = new TtlLruCache({ ttlMs: 1000, max: 10 }) + expect(() => cache.delete('missing')).not.toThrow() + }) +}) + +describe('TtlLruCache LRU eviction', () => { + it('evicts the oldest entry when set causes overflow', () => { + const cache = new TtlLruCache({ ttlMs: 10_000, max: 2 }) + cache.set('a', '1') + cache.set('b', '2') + cache.set('c', '3') // overflow - 'a' is the oldest, gets evicted + expect(cache.get('a')).toBeUndefined() + expect(cache.get('b')).toBe('2') + expect(cache.get('c')).toBe('3') + }) + + it('get refreshes LRU position so a recently-read entry survives eviction', () => { + const cache = new TtlLruCache({ ttlMs: 10_000, max: 2 }) + cache.set('a', '1') + cache.set('b', '2') + // Touch 'a' so it becomes the most-recently-used. 'b' is now oldest. + cache.get('a') + cache.set('c', '3') // overflow - 'b' should be evicted, not 'a' + expect(cache.get('a')).toBe('1') + expect(cache.get('b')).toBeUndefined() + expect(cache.get('c')).toBe('3') + }) +}) + +describe('TtlLruCache re-set', () => { + it('replaces the value when set is called twice for the same key', () => { + const cache = new TtlLruCache({ ttlMs: 1000, max: 10 }) + cache.set('a', '1') + cache.set('a', '2') + expect(cache.get('a')).toBe('2') + }) + + it('resets the TTL on re-set', () => { + const cache = new TtlLruCache({ ttlMs: 1000, max: 10 }) + cache.set('a', '1') + vi.advanceTimersByTime(800) + cache.set('a', '2') // bumps expiry to 1000ms from now + vi.advanceTimersByTime(800) + // 800 + 800 = 1600ms past the original set, but only 800ms past the + // re-set, so the entry should still be live. + expect(cache.get('a')).toBe('2') + }) +})