Refactor duplicated patterns into shared helpers

This commit is contained in:
Alan Grainger
2026-06-05 12:46:28 +12:00
parent c1b58011aa
commit cefe2e81ff
7 changed files with 294 additions and 110 deletions
+63 -48
View File
@@ -123,6 +123,10 @@ function writePersistedState (open: boolean) {
} }
// ----- content rendering --------------------------------------------------- // ----- 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) { function renderContents (root: HTMLElement, item: GalleryItem | undefined) {
root.replaceChildren() root.replaceChildren()
@@ -213,67 +217,78 @@ function renderDateRow (iso: string): HTMLElement {
return row return row
} }
function renderFileRow (exif: GalleryExif): HTMLElement | null { interface RowSpec {
if (!exif.fileName && !exif.width && !exif.fileSizeInByte) return null icon: string
const row = makeRow(ICON_IMAGE) // Title paragraph at the top of the row body. Falsy values are omitted.
label?: string | null
labelClass?: string
// Stats rendered as `<span>` 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<string | null | undefined>
}
/**
* 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 const body = row.querySelector('.ipp-sidebar-row-body') as HTMLElement
if (exif.fileName) { if (spec.label) {
const name = document.createElement('p') const p = document.createElement('p')
name.className = 'ipp-sidebar-filename' if (spec.labelClass) p.className = spec.labelClass
name.textContent = exif.fileName p.textContent = spec.label
body.appendChild(name) body.appendChild(p)
} }
if (exif.width && exif.height) { if (presentStats.length) {
const stats = document.createElement('div') const stats = document.createElement('div')
stats.className = 'ipp-sidebar-stats' stats.className = 'ipp-sidebar-stats'
const mp = Math.round((exif.width * exif.height) / 1_000_000) for (const s of presentStats) stats.appendChild(makeStat(s))
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)))
body.appendChild(stats) body.appendChild(stats)
} }
return row 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 { function renderCameraRow (exif: GalleryExif): HTMLElement | null {
if (!exif.make && !exif.model && exif.exposureTime == null && exif.iso == null) return null return renderRow({
const row = makeRow(ICON_CAMERA) icon: ICON_CAMERA,
const body = row.querySelector('.ipp-sidebar-row-body') as HTMLElement label: [exif.make, exif.model].filter(Boolean).join(' ').trim() || null,
const label = [exif.make, exif.model].filter(Boolean).join(' ').trim() stats: [
if (label) { exif.exposureTime ? exif.exposureTime + ' s' : null,
const p = document.createElement('p') exif.iso != null ? 'ISO ' + exif.iso : null
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
} }
function renderLensRow (exif: GalleryExif): HTMLElement | null { function renderLensRow (exif: GalleryExif): HTMLElement | null {
if (!exif.lensModel && exif.fNumber == null && exif.focalLength == null) return null return renderRow({
const row = makeRow(ICON_IRIS) icon: ICON_IRIS,
const body = row.querySelector('.ipp-sidebar-row-body') as HTMLElement label: exif.lensModel,
if (exif.lensModel) { labelClass: 'ipp-sidebar-lens',
const p = document.createElement('p') stats: [
p.className = 'ipp-sidebar-lens' exif.fNumber != null ? 'f/' + exif.fNumber : null,
p.textContent = exif.lensModel exif.focalLength != null ? exif.focalLength + ' mm' : null
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
} }
function renderLocation (exif: GalleryExif): HTMLElement { function renderLocation (exif: GalleryExif): HTMLElement {
+32 -23
View File
@@ -56,18 +56,7 @@ export function virtualize () {
if (l.top > bottom) break if (l.top > bottom) break
neededTiles.add(l.index) neededTiles.add(l.index)
} }
for (const [index, el] of state.renderedTiles) { syncRendered(neededTiles, state.renderedTiles, createTile)
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)
}
// Group headers (when grouping is enabled; headers is empty otherwise) // Group headers (when grouping is enabled; headers is empty otherwise)
const neededHeaders = new Set<string>() const neededHeaders = new Set<string>()
@@ -76,19 +65,39 @@ export function virtualize () {
if (h.top > bottom) break if (h.top > bottom) break
neededHeaders.add(h.label) neededHeaders.add(h.label)
} }
for (const [label, el] of state.renderedHeaders) { syncRendered(neededHeaders, state.renderedHeaders, (label) => {
if (!neededHeaders.has(label)) {
el.remove()
state.renderedHeaders.delete(label)
}
}
for (const label of neededHeaders) {
if (state.renderedHeaders.has(label)) continue
const h = state.headers.find(x => x.label === label) const h = state.headers.find(x => x.label === label)
if (!h) continue return h ? createHeader(h) : null
const el = createHeader(h) })
}
/**
* 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<K> (
needed: Set<K>,
rendered: Map<K, HTMLElement>,
create: (key: K) => HTMLElement | null
): void {
if (!state.container) return
for (const [key, el] of rendered) {
if (!needed.has(key)) {
el.remove()
rendered.delete(key)
}
}
for (const key of needed) {
if (rendered.has(key)) continue
const el = create(key)
if (!el) continue
state.container.appendChild(el) state.container.appendChild(el)
state.renderedHeaders.set(label, el) rendered.set(key, el)
} }
} }
+6
View File
@@ -146,6 +146,12 @@ function applyDescriptionSplitShim (config: Config): void {
* users - which is the safer privacy default and matches the policy the * users - which is the safer privacy default and matches the policy the
* new design is establishing. * 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 = [ const LEGACY_EXIF_FIELDS = [
'dateTimeOriginal', 'fileName', 'dimensions', 'fileSize', 'dateTimeOriginal', 'fileName', 'dimensions', 'fileSize',
'make', 'model', 'lensModel', 'exposureTime', 'iso', 'make', 'model', 'lensModel', 'exposureTime', 'iso',
+9
View File
@@ -31,6 +31,15 @@ function copy (key: keyof ExifInfo & keyof GalleryExif): FieldRule {
same string. `copy` handles the whole if/copy dance for each. Fields same string. `copy` handles the whole if/copy dance for each. Fields
that need special handling (fileName, dimensions, fileSize, gps) appear that need special handling (fileName, dimensions, fileSize, gps) appear
inline in the `*_RULES` arrays below. 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 = [ const EXIF_FIELDS = [
'dateTimeOriginal', 'make', 'model', 'lensModel', 'dateTimeOriginal', 'make', 'model', 'lensModel',
+8 -41
View File
@@ -23,6 +23,7 @@ import { renderPage } from './view/render'
import { Password } from './view/password' import { Password } from './view/password'
import { respondToInvalidRequest } from './invalidRequestHandler' import { respondToInvalidRequest } from './invalidRequestHandler'
import { encrypt } from './encrypt' import { encrypt } from './encrypt'
import { TtlLruCache } from './utils/ttlLruCache'
/* /*
In-process cache for share-link lookups. Each direct-asset request (e.g. 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 across concurrent requests. Current callers (notably the in-place
`share.assets.sort(...)` in render.ts) happen to be idempotent so this is `share.assets.sort(...)` in render.ts) happen to be idempotent so this is
safe today, but new callers should clone before mutating. 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<SharedLinkResult>; expiresAt: number } const shareCache = new TtlLruCache<Promise<SharedLinkResult>>({ ttlMs: 120_000, max: 100 })
const shareCache = new Map<string, ShareCacheEntry>()
const shareCacheTtlMs = 120_000
const shareCacheMax = 100
/* /*
Immich replaced the deprecated `?password=...` query-param auth for shared 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 cache key (often empty) and falls through to a fresh login that Immich will
reject - IPP never serves cached tokens to unauthenticated visitors. reject - IPP never serves cached tokens to unauthenticated visitors.
*/ */
type TokenCacheEntry = { promise: Promise<string | null>; expiresAt: number } const tokenCache = new TtlLruCache<Promise<string | null>>({ ttlMs: 120_000, max: 100 })
const tokenCache = new Map<string, TokenCacheEntry>()
const tokenCacheTtlMs = 120_000
const tokenCacheMax = 100
/** /**
* Make a request to Immich API. We're not using the SDK to limit * 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<SharedLinkResult> { export async function getShareByKey (key: string, password?: string, keyType: KeyType = KeyType.key): Promise<SharedLinkResult> {
const cacheKey = `${keyType}:${key}:${password ?? ''}` const cacheKey = `${keyType}:${key}:${password ?? ''}`
const now = Date.now()
const cached = shareCache.get(cacheKey) const cached = shareCache.get(cacheKey)
if (cached && cached.expiresAt > now) { if (cached) return cached
// Move-to-end to mark this entry as most-recently-used for LRU eviction
shareCache.delete(cacheKey)
shareCache.set(cacheKey, cached)
return cached.promise
}
const promise = fetchShareByKey(key, password, keyType) const promise = fetchShareByKey(key, password, keyType)
shareCache.set(cacheKey, { shareCache.set(cacheKey, promise)
promise,
expiresAt: now + shareCacheTtlMs
})
if (shareCache.size > shareCacheMax) {
const oldest = shareCache.keys().next().value
if (oldest !== undefined && oldest !== cacheKey) shareCache.delete(oldest)
}
promise.then( promise.then(
(result) => { if (!result?.valid) shareCache.delete(cacheKey) }, (result) => { if (!result?.valid) shareCache.delete(cacheKey) },
() => { 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<string | null> { async function getSharedLinkToken (key: string, password: string, keyType: KeyType): Promise<string | null> {
const cacheKey = `${keyType}:${key}:${password}` const cacheKey = `${keyType}:${key}:${password}`
const now = Date.now()
const cached = tokenCache.get(cacheKey) const cached = tokenCache.get(cacheKey)
if (cached && cached.expiresAt > now) { if (cached) return cached
tokenCache.delete(cacheKey)
tokenCache.set(cacheKey, cached)
return cached.promise
}
const promise = sharedLinkLogin(key, password, keyType) const promise = sharedLinkLogin(key, password, keyType)
tokenCache.set(cacheKey, { tokenCache.set(cacheKey, promise)
promise,
expiresAt: now + tokenCacheTtlMs
})
if (tokenCache.size > tokenCacheMax) {
const oldest = tokenCache.keys().next().value
if (oldest !== undefined && oldest !== cacheKey) tokenCache.delete(oldest)
}
promise.then( promise.then(
(token) => { if (!token) tokenCache.delete(cacheKey) }, (token) => { if (!token) tokenCache.delete(cacheKey) },
() => { tokenCache.delete(cacheKey) } () => { tokenCache.delete(cacheKey) }
+68
View File
@@ -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<V> {
value: V
expiresAt: number
}
export class TtlLruCache<V> {
private readonly entries = new Map<string, Entry<V>>()
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)
}
}
+110
View File
@@ -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<string>({ ttlMs: 1000, max: 10 })
expect(cache.get('missing')).toBeUndefined()
})
it('returns the value after set', () => {
const cache = new TtlLruCache<string>({ 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<string>({ 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<string>({ 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<string>({ 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<string>({ 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<string>({ 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<string>({ 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<string>({ 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<string>({ 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')
})
})