Skip to content

Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.

fix: publish metadata edits through versioned source objects

HoshinoSuzumiBotc09f7bcc3df2
diff --git a/packages/core/README.md b/packages/core/README.md
index 5819bc93..30a99f04 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -26,3 +26,9 @@ Photo object edits and database updates retain the existing cross-system
consistency boundary; source-version fencing and durable task recovery belong
to the later jobs batch. Self-hosted account-wide quota remains unlimited while
per-file limits continue to apply.
+
+Photo metadata edits stage a unique source object before publication. The database
+checks the captured source version and atomically updates the photo reference,
+resource generation, and any follow-up task. Failed or stale publications discard
+only their own staged object; they never restore bytes over a newer edit. Prior
+source objects remain available rather than being deleted during publication.
diff --git a/packages/core/src/mutations.ts b/packages/core/src/mutations.ts
index 0ad28449..4de6c363 100644
--- a/packages/core/src/mutations.ts
+++ b/packages/core/src/mutations.ts
@@ -137,6 +137,8 @@ export type PhotoUpdate = Partial<
| 'exif'
| 'fileSize'
| 'lastModified'
+ | 'storageKey'
+ | 'originalUrl'
| 'latitude'
| 'longitude'
| 'country'
@@ -146,17 +148,18 @@ export type PhotoUpdate = Partial<
>
>
export type PhotoRecord = Photo & {
+ mutationVersion?: number
originalDerivedKey?: string | null
storageReference?: { connectionId: number | null; revision: number }
}
export interface PhotoWriteRepository {
get(id: string): Promise<PhotoRecord | null>
- beginMutation?(id: string): Promise<void>
/** Persist a requested follow-up task in the same transaction as the resource update. */
update(
id: string,
update: PhotoUpdate,
reverseGeocode?: { latitude: number; longitude: number },
+ expectedVersion?: number,
): Promise<Photo | null>
delete(id: string): Promise<PhotoRecord | null>
}
@@ -201,9 +204,15 @@ export function createPhotoWriter(deps: {
storage: StorageResolver
clock: Clock
editMetadata(
- photo: Photo,
+ photo: PhotoRecord,
input: PhotoMetadataInput,
- ): Promise<Pick<Photo, 'exif' | 'fileSize'>>
+ ): Promise<
+ Pick<Photo, 'exif' | 'fileSize'> & {
+ storageKey?: string
+ originalUrl?: string | null
+ discard?(): Promise<void>
+ }
+ >
warn(error: unknown, operation: string): void
}) {
return {
@@ -234,13 +243,15 @@ export function createPhotoWriter(deps: {
'dashboard.photos.messages.noStorageKey',
)
const input = normalizePhotoMetadata(raw)
- await deps.repository.beginMutation?.(id)
const edited = await deps.editMetadata(photo, input)
const update: PhotoUpdate = {
exif: edited.exif,
fileSize: edited.fileSize,
lastModified: deps.clock.now().toISOString(),
}
+ if (edited.storageKey !== undefined) update.storageKey = edited.storageKey
+ if (edited.originalUrl !== undefined)
+ update.originalUrl = edited.originalUrl
if (input.title !== undefined) update.title = input.title || null
if (input.description !== undefined)
update.description = input.description || null
@@ -261,8 +272,16 @@ export function createPhotoWriter(deps: {
id,
update,
input.location ?? undefined,
+ photo.mutationVersion,
)
+ if (!updated) throw new CoreError(404, 'Photo not found')
} catch (error) {
+ try {
+ await edited.discard?.()
+ } catch (cleanupError) {
+ deps.warn(cleanupError, 'discard-photo-metadata')
+ }
+ if (error instanceof CoreError) throw error
deps.warn(error, 'update-photo-record')
throw new CoreError(
500,
diff --git a/packages/database/src/sqlite-mutations.ts b/packages/database/src/sqlite-mutations.ts
index a70d1f94..60c93e34 100644
--- a/packages/database/src/sqlite-mutations.ts
+++ b/packages/database/src/sqlite-mutations.ts
@@ -1,7 +1,7 @@
import { appendAlbumPhotos } from './album-membership.ts'
-import { createSqliteJobRepository, reserveResource } from './sqlite-jobs.ts'
-import { requireSite } from './site-repository.ts'
-import { type SiteContext } from '@chronoframe/core'
+import { createSqliteJobRepository } from './sqlite-jobs.ts'
+import { createSiteRepository, requireSite } from './site-repository.ts'
+import { CoreError, type SiteContext } from '@chronoframe/core'
import { and as siteAnd, eq as siteEq } from 'drizzle-orm'
import { and, eq, min } from 'drizzle-orm'
import type {
@@ -202,33 +202,31 @@ export function createSqlitePhotoWriteRepository(
})
return {
async get(id) {
- const photo = db
- .select()
- .from(tables.photos)
- .where(
- siteAnd(
- eq(tables.photos.id, id),
- siteEq(tables.photos.siteId, site.id),
- ),
- )
- .get()
- return photo ? record(photo) : null
- },
- async beginMutation(id) {
- const photo = db
- .select()
- .from(tables.photos)
- .where(and(eq(tables.photos.siteId, site.id), eq(tables.photos.id, id)))
- .get()
- if (photo)
- reserveResource(db, site, id, {
- storageConnectionId: photo.storageConnectionId,
- storageRevision: photo.storageRevision,
- storageKey: photo.storageKey,
- })
+ const snapshot = await createSiteRepository(db, site).capturePhoto(id)
+ return snapshot
+ ? { ...record(snapshot.photo), mutationVersion: snapshot.version }
+ : null
},
- async update(id, update, reverseGeocode) {
+ async update(id, update, reverseGeocode, expectedVersion) {
return db.transaction(() => {
+ if (expectedVersion !== undefined) {
+ const version = db
+ .select()
+ .from(tables.resourceVersions)
+ .where(
+ and(
+ eq(tables.resourceVersions.siteId, site.id),
+ eq(tables.resourceVersions.resourceId, id),
+ ),
+ )
+ .get()
+ if (
+ !version ||
+ version.deleted ||
+ version.version !== expectedVersion
+ )
+ throw new CoreError(409, 'Photo changed; retry the operation')
+ }
db.update(tables.photos)
.set(update)
.where(
diff --git a/server/services/resources/photo-metadata.ts b/server/services/resources/photo-metadata.ts
index a21e2fae..63607ca3 100644
--- a/server/services/resources/photo-metadata.ts
+++ b/server/services/resources/photo-metadata.ts
@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto'
import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import path from 'node:path'
@@ -76,6 +77,7 @@ export async function editPhotoMetadata(
const tempRoot = tmpdir()
await mkdir(tempRoot, { recursive: true })
const tempDir = await mkdtemp(path.join(tempRoot, 'cframe-edit-'))
+ const stagedKey = `.generated/metadata/${randomUUID()}/${path.posix.basename(photo.storageKey)}`
const ext = path.extname(photo.storageKey) || '.jpg'
const tempFile = path.join(tempDir, `edited${ext}`)
@@ -87,14 +89,30 @@ export async function editPhotoMetadata(
}
const updatedBuffer = await readFile(tempFile)
- // Stored keys already identify the full object; each provider handles its
- // own prefix normalization. Removing a substring can overwrite another key.
- await storageProvider.create(photo.storageKey, updatedBuffer)
-
+ // Publish to a unique object. The original stays untouched until the
+ // database atomically selects this revision and enqueues follow-up work.
const exifData = await extractExifData(updatedBuffer)
+ const staged = await storageProvider.create(stagedKey, updatedBuffer)
- return { exif: exifData, fileSize: updatedBuffer.length }
+ return {
+ exif: exifData,
+ fileSize: updatedBuffer.length,
+ storageKey: staged.key,
+ // HEIC originals retain their separately generated browser-readable JPEG.
+ originalUrl: /\.(?:heic|heif|hif)$/i.test(photo.storageKey)
+ ? photo.originalUrl
+ : storageProvider.getPublicUrl(staged.key),
+ discard: () => storageProvider.delete(stagedKey),
+ }
} catch (error) {
+ try {
+ await storageProvider.delete(stagedKey)
+ } catch (cleanupError) {
+ logger.image.warn(
+ 'Failed to discard staged metadata object',
+ cleanupError,
+ )
+ }
logger.image.error('Failed to update photo metadata', error)
throw new CoreError(
500,
diff --git a/server/utils/resource-writer.ts b/server/utils/resource-writer.ts
index cdaf8934..a6db1ab0 100644
--- a/server/utils/resource-writer.ts
+++ b/server/utils/resource-writer.ts
@@ -51,7 +51,15 @@ export function usePhotoWriter(event: H3Event) {
return editPhotoMetadata(
{ ...photo, storageKey: photo.storageKey },
input,
- await storageForPhoto(photo.id, storageProvider),
+ await (photo.storageReference
+ ? storageForReference(
+ {
+ storageConnectionId: photo.storageReference.connectionId,
+ storageRevision: photo.storageReference.revision,
+ },
+ storageProvider,
+ )
+ : storageForPhoto(photo.id, storageProvider)),
)
},
warn(error, operation) {
diff --git a/tests/core-mutations.test.ts b/tests/core-mutations.test.ts
index 86f99c6b..9e10166d 100644
--- a/tests/core-mutations.test.ts
+++ b/tests/core-mutations.test.ts
@@ -211,3 +211,119 @@ test('photo mutations keep normalized EXIF and database edits aligned and persis
sqlite.close()
}
})
+
+test('failed metadata publication preserves source bytes, photo, generation and queued work', async () => {
+ const { sqlite, db } = setup()
+ try {
+ db.insert(schema.photos)
+ .values({
+ id: 'p',
+ storageKey: 'p.jpg',
+ title: 'Original',
+ originalUrl: '/image/p.jpg',
+ })
+ .run()
+ const repository = createSqlitePhotoWriteRepository(db, DEFAULT_SITE)
+ const objects = new Map([['p.jpg', Buffer.from('original bytes')]])
+ const beforePhoto = db.select().from(schema.photos).get()
+ const beforeVersions = db.select().from(schema.resourceVersions).all()
+ sqlite.exec(
+ "CREATE TRIGGER fail_metadata_enqueue BEFORE INSERT ON pipeline_queue BEGIN SELECT RAISE(ABORT, 'enqueue failed'); END",
+ )
+ const writer = createPhotoWriter({
+ repository,
+ clock: { now: () => now },
+ storage: { forPhoto: async () => ({ delete: async () => {} }) },
+ editMetadata: async () => {
+ objects.set('staged.jpg', Buffer.from('edited bytes'))
+ return {
+ exif: null,
+ fileSize: 12,
+ storageKey: 'staged.jpg',
+ originalUrl: '/image/staged.jpg',
+ discard: async () => {
+ objects.delete('staged.jpg')
+ },
+ }
+ },
+ warn: () => {},
+ })
+ await assert.rejects(
+ writer.update(
+ 'p',
+ { title: 'Edited', location: { latitude: 1, longitude: 2 } },
+ access,
+ ),
+ /Failed to update photo metadata/,
+ )
+ assert.deepEqual([...objects], [['p.jpg', Buffer.from('original bytes')]])
+ assert.deepEqual(db.select().from(schema.photos).get(), beforePhoto)
+ assert.deepEqual(
+ db.select().from(schema.resourceVersions).all(),
+ beforeVersions,
+ )
+ assert.equal(db.select().from(schema.pipelineQueue).all().length, 0)
+ sqlite.exec('DROP TRIGGER fail_metadata_enqueue')
+ await writer.update(
+ 'p',
+ { title: 'Edited', location: { latitude: 1, longitude: 2 } },
+ access,
+ )
+ assert.equal(
+ db.select().from(schema.photos).get()!.storageKey,
+ 'staged.jpg',
+ )
+ assert.equal(db.select().from(schema.pipelineQueue).all().length, 1)
+ assert.ok(
+ db.select().from(schema.resourceVersions).get()!.version >
+ beforeVersions[0]!.version,
+ )
+ assert.deepEqual(objects.get('p.jpg'), Buffer.from('original bytes'))
+ } finally {
+ sqlite.close()
+ }
+})
+
+test('concurrent metadata publication keeps the winner and discards only the losing staged object', async () => {
+ const { sqlite, db } = setup()
+ try {
+ db.insert(schema.photos).values({ id: 'p', storageKey: 'p.jpg' }).run()
+ const repository = createSqlitePhotoWriteRepository(db, DEFAULT_SITE)
+ const objects = new Set(['p.jpg'])
+ const writer = createPhotoWriter({
+ repository,
+ clock: { now: () => now },
+ storage: { forPhoto: async () => ({ delete: async () => {} }) },
+ editMetadata: async () => {
+ objects.add('loser.jpg')
+ await repository.update('p', {
+ title: 'Winner',
+ storageKey: 'winner.jpg',
+ })
+ objects.add('winner.jpg')
+ return {
+ exif: null,
+ fileSize: 1,
+ storageKey: 'loser.jpg',
+ discard: async () => {
+ objects.delete('loser.jpg')
+ },
+ }
+ },
+ warn: () => {},
+ })
+ await assert.rejects(
+ writer.update('p', { title: 'Loser' }, access),
+ (error: unknown) =>
+ error instanceof CoreError && error.statusCode === 409,
+ )
+ assert.equal(db.select().from(schema.photos).get()!.title, 'Winner')
+ assert.equal(
+ db.select().from(schema.photos).get()!.storageKey,
+ 'winner.jpg',
+ )
+ assert.deepEqual([...objects].sort(), ['p.jpg', 'winner.jpg'])
+ } finally {
+ sqlite.close()
+ }
+})
diff --git a/tests/review-runtime.test.ts b/tests/review-runtime.test.ts
index 468ebd4a..12bd2efb 100644
--- a/tests/review-runtime.test.ts
+++ b/tests/review-runtime.test.ts
@@ -280,3 +280,48 @@ test('Live Photo management preserves missing photo and source conflict response
await assert.rejects(route({}), { statusCode: status })
}
})
+
+test('native metadata editing stages a unique object and discard preserves original bytes', async () => {
+ const { mkdtemp, rm } = await import('node:fs/promises')
+ const { tmpdir } = await import('node:os')
+ const { join } = await import('node:path')
+ const { LocalStorageProvider } = await import('@chronoframe/storage')
+ const { exiftool } = await import('exiftool-vendored')
+ const root = await mkdtemp(join(tmpdir(), 'metadata-publication-'))
+ try {
+ const provider = new LocalStorageProvider({
+ provider: 'local',
+ basePath: root,
+ prefix: 'photos',
+ })
+ const original = await sharp({
+ create: { width: 2, height: 3, channels: 3, background: 'blue' },
+ })
+ .jpeg()
+ .toBuffer()
+ await provider.create('photo.jpg', original)
+ const adapter = load('server/services/resources/photo-metadata.ts', {
+ '../image/exif': { extractExifData: async () => null },
+ '../../utils/logger': {
+ logger: { image: { error: () => {}, warn: () => {} } },
+ },
+ }).editPhotoMetadata
+ const staged = await adapter(
+ { storageKey: 'photos/photo.jpg' },
+ { title: 'Staged title' },
+ provider,
+ )
+ assert.notEqual(staged.storageKey, 'photos/photo.jpg')
+ assert.ok(staged.storageKey.startsWith('photos/.generated/metadata/'))
+ assert.deepEqual(await provider.get('photos/photo.jpg'), original)
+ const bytes = (await provider.get(staged.storageKey))!
+ assert.ok(bytes.length > original.length)
+ assert.equal((await sharp(bytes).metadata()).width, 2)
+ await staged.discard()
+ assert.equal(await provider.get(staged.storageKey), null)
+ assert.deepEqual(await provider.get('photos/photo.jpg'), original)
+ } finally {
+ await exiftool.end()
+ await rm(root, { recursive: true, force: true })
+ }
+})