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(albums): allow historical slug reuse and release on deletion

Ahmet Ömer880336d61c44
diff --git a/packages/core/src/album-slug.ts b/packages/core/src/album-slug.ts
index a94e408f..e902bd4f 100644
--- a/packages/core/src/album-slug.ts
+++ b/packages/core/src/album-slug.ts
@@ -7,7 +7,7 @@ import {
} from '@chronoframe/contracts/album-slug'
/** Convert a title to a stable, URL-safe base. Persistence owns uniqueness. */
-export function generatedAlbumSlug(title: string): string {
+export function generatedAlbumSlug(title: string, fallback = 'album'): string {
const result = slugify(title.normalize('NFKC'), {
separator: '-',
lowercase: true,
@@ -16,7 +16,7 @@ export function generatedAlbumSlug(title: string): string {
.replace(/^-+|-+$/g, '')
.slice(0, ALBUM_SLUG_MAX_LENGTH)
.replace(/-+$/g, '')
- if (!result) return 'album'
+ if (!result) return fallback
return isNumericAlbumPathSegment(result)
? `album-${result.slice(0, ALBUM_SLUG_MAX_LENGTH - 6)}`
: result
diff --git a/packages/database/README.md b/packages/database/README.md
index e86c48e8..90346531 100644
--- a/packages/database/README.md
+++ b/packages/database/README.md
@@ -8,7 +8,7 @@ Migrations are canonical here. `server/database/migrations` remains a compatibil
The default self-hosted Site is fixed by its entry, while every site repository requires an explicit existing Site. Migration creates default Workspace/Site memberships and enforces immutable ownership and same-site relationships. Settings uniqueness and caches include Site. Historical storage connection configurations are retained as immutable revisions for existing object references.
-Album slugs are reserved per Site after a rename or deletion. Deletion keeps a tombstone in `album_slugs` so an old URL can never identify a different album; the registry therefore grows with distinct URLs used over time. Automatic slug generation skips reserved values, and custom reuse returns a conflict.
+Current album slugs are exclusive per Site. A historical slug can be claimed by the same or another album, and deleting an album releases all its slugs. Automatic slug generation adds a suffix when a current slug conflicts; custom reuse of a current slug returns a conflict.
`pnpm db:migrate` and application startup use the same journal-compatible runner. Existing files with pending migrations receive a consistent `*.pre-migration-*.sqlite3` backup before changes. Schema and journal updates share a transaction, foreign keys are checked before commit, and enforcement is restored afterwards. Keep backups with their matching application versions; restoring only an older binary does not reverse schema constraints.
diff --git a/packages/database/migrations/0021_reusable_album_slugs.sql b/packages/database/migrations/0021_reusable_album_slugs.sql
new file mode 100644
index 00000000..ff0253d0
--- /dev/null
+++ b/packages/database/migrations/0021_reusable_album_slugs.sql
@@ -0,0 +1,39 @@
+DROP TRIGGER album_slugs_tombstone;
+--> statement-breakpoint
+CREATE TABLE album_slugs_new (
+ site_id INTEGER NOT NULL REFERENCES sites(id),
+ slug TEXT NOT NULL,
+ album_id INTEGER NOT NULL REFERENCES albums(id) ON DELETE CASCADE,
+ is_current INTEGER NOT NULL DEFAULT 0 CHECK (is_current IN (0, 1)),
+ PRIMARY KEY (site_id, slug)
+);
+--> statement-breakpoint
+INSERT INTO album_slugs_new (site_id, slug, album_id, is_current)
+SELECT s.site_id, s.slug, s.album_id, s.is_current
+FROM album_slugs AS s
+JOIN albums AS a ON a.id = s.album_id AND a.site_id = s.site_id;
+--> statement-breakpoint
+DROP TABLE album_slugs;
+--> statement-breakpoint
+ALTER TABLE album_slugs_new RENAME TO album_slugs;
+--> statement-breakpoint
+CREATE UNIQUE INDEX album_slugs_one_current ON album_slugs(site_id, album_id) WHERE is_current = 1;
+--> statement-breakpoint
+CREATE INDEX album_slugs_album ON album_slugs(site_id, album_id);
+--> statement-breakpoint
+CREATE TRIGGER album_slugs_same_site_insert BEFORE INSERT ON album_slugs
+WHEN NOT EXISTS (
+ SELECT 1 FROM albums WHERE id = NEW.album_id AND site_id = NEW.site_id
+)
+BEGIN SELECT RAISE(ABORT, 'cross-site or missing relation'); END;
+--> statement-breakpoint
+CREATE TRIGGER album_slugs_same_site_update BEFORE UPDATE OF album_id, site_id ON album_slugs
+WHEN NOT EXISTS (
+ SELECT 1 FROM albums WHERE id = NEW.album_id AND site_id = NEW.site_id
+)
+BEGIN SELECT RAISE(ABORT, 'cross-site or missing relation'); END;
+--> statement-breakpoint
+CREATE TRIGGER album_slugs_cleanup BEFORE DELETE ON albums
+BEGIN
+ DELETE FROM album_slugs WHERE album_id = OLD.id;
+END;
diff --git a/packages/database/migrations/meta/_journal.json b/packages/database/migrations/meta/_journal.json
index 87c68f22..1060bb5e 100644
--- a/packages/database/migrations/meta/_journal.json
+++ b/packages/database/migrations/meta/_journal.json
@@ -148,6 +148,13 @@
"when": 1792307738436,
"tag": "0020_album_slugs",
"breakpoints": true
+ },
+ {
+ "idx": 21,
+ "version": "6",
+ "when": 1792307739436,
+ "tag": "0021_reusable_album_slugs",
+ "breakpoints": true
}
]
}
diff --git a/packages/database/src/album-slugs.ts b/packages/database/src/album-slugs.ts
index 8d9cf261..aa1c4cea 100644
--- a/packages/database/src/album-slugs.ts
+++ b/packages/database/src/album-slugs.ts
@@ -50,7 +50,7 @@ export function claimAlbumSlug(
): string {
const automatic = requestedSlug.trim() === ''
const base = automatic
- ? generatedAlbumSlug(title)
+ ? generatedAlbumSlug(title, `album-${albumId}`)
: validateCustomAlbumSlug(requestedSlug)
for (let suffix = 0; suffix < 1_000_000; suffix++) {
const slug = automatic ? suffixedAlbumSlug(base, suffix) : base
@@ -66,12 +66,10 @@ export function claimAlbumSlug(
.get()
if (existing) {
if (existing.albumId === albumId && existing.isCurrent) return slug
- if (!automatic)
- throw new CoreError(
- 409,
- 'Album URL slug is in use or was previously used',
- )
- continue
+ if (existing.isCurrent) {
+ if (!automatic) throw new CoreError(409, 'Album URL slug is in use')
+ continue
+ }
}
db.update(tables.albumSlugs)
.set({ isCurrent: false })
@@ -83,9 +81,20 @@ export function claimAlbumSlug(
),
)
.run()
- db.insert(tables.albumSlugs)
- .values({ siteId: site.id, slug, albumId, isCurrent: true })
- .run()
+ if (existing)
+ db.update(tables.albumSlugs)
+ .set({ albumId, isCurrent: true })
+ .where(
+ and(
+ eq(tables.albumSlugs.siteId, site.id),
+ eq(tables.albumSlugs.slug, slug),
+ ),
+ )
+ .run()
+ else
+ db.insert(tables.albumSlugs)
+ .values({ siteId: site.id, slug, albumId, isCurrent: true })
+ .run()
return slug
}
throw new Error('Album slug namespace exhausted')
diff --git a/packages/database/src/schema.ts b/packages/database/src/schema.ts
index 60600e57..5324d868 100644
--- a/packages/database/src/schema.ts
+++ b/packages/database/src/schema.ts
@@ -254,9 +254,9 @@ export const albumSlugs = sqliteTable(
{
siteId: siteColumn(),
slug: text('slug').notNull(),
- albumId: integer('album_id').references(() => albums.id, {
- onDelete: 'set null',
- }),
+ albumId: integer('album_id')
+ .notNull()
+ .references(() => albums.id, { onDelete: 'cascade' }),
isCurrent: integer('is_current', { mode: 'boolean' })
.notNull()
.default(false),
diff --git a/tests/album-slug-persistence.test.ts b/tests/album-slug-persistence.test.ts
index d4e84bf2..1321b056 100644
--- a/tests/album-slug-persistence.test.ts
+++ b/tests/album-slug-persistence.test.ts
@@ -1,5 +1,14 @@
import assert from 'node:assert/strict'
import test from 'node:test'
+import {
+ cpSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
import Database from 'better-sqlite3'
import { drizzle } from 'drizzle-orm/better-sqlite3'
import { migrate } from 'drizzle-orm/better-sqlite3/migrator'
@@ -16,7 +25,7 @@ import { createSqliteAlbumWriteRepository } from '../packages/database/src/sqlit
const access = { authenticated: true }
-test('album slugs remain unique, redirectable, and reserved after deletion', async () => {
+test('only current album slugs conflict; historical and deleted slugs are reusable', async () => {
const statements: string[] = []
const sqlite = new Database(':memory:', {
verbose: (statement) => statements.push(statement),
@@ -83,9 +92,17 @@ test('album slugs remain unique, redirectable, and reserved after deletion', asy
resolveAlbumSlug(db, DEFAULT_SITE, 'my-album')?.isCurrent,
false,
)
- await assert.rejects(
- writer.update(second.id, { slug: 'my-album' }, access),
- (error) => error instanceof CoreError && error.statusCode === 409,
+ assert.equal(
+ (await writer.update(second.id, { slug: 'my-album' }, access)).slug,
+ 'my-album',
+ )
+ assert.equal(
+ resolveAlbumSlug(db, DEFAULT_SITE, 'my-album')?.albumId,
+ second.id,
+ )
+ assert.equal(
+ resolveAlbumSlug(db, DEFAULT_SITE, 'my-album')?.isCurrent,
+ true,
)
assert.equal(
(await writer.update(first.id, { title: 'Only Title' }, access)).slug,
@@ -102,51 +119,139 @@ test('album slugs remain unique, redirectable, and reserved after deletion', asy
assert.equal(
(await writer.update(first.id, { title: 'My Album', slug: '' }, access))
.slug,
- 'my-album-2',
+ 'my-album-1',
)
assert.equal(
resolveAlbumPath(db, DEFAULT_SITE, 'my-album')?.slug,
- 'my-album-2',
+ 'my-album',
)
assert.equal(
resolveAlbumPath(db, DEFAULT_SITE, 'my-album')?.isCanonical,
- false,
+ true,
)
assert.equal(
resolveAlbumPath(db, DEFAULT_SITE, 'a-new-title')?.slug,
- 'my-album-2',
+ 'my-album-1',
)
- await assert.rejects(
- writer.update(second.id, { slug: 'my-album' }, access),
- (error) => error instanceof CoreError && error.statusCode === 409,
+ assert.equal(
+ (await writer.update(first.id, { slug: 'a-new-title' }, access)).slug,
+ 'a-new-title',
+ )
+ assert.equal(
+ resolveAlbumSlug(db, DEFAULT_SITE, 'a-new-title')?.isCurrent,
+ true,
)
await assert.rejects(
writer.update(second.id, { slug: 'Invalid Slug' }, access),
(error) => error instanceof CoreError && error.statusCode === 400,
)
await writer.delete(first.id, access)
- assert.equal(resolveAlbumSlug(db, DEFAULT_SITE, 'my-album')?.albumId, null)
+ assert.equal(resolveAlbumSlug(db, DEFAULT_SITE, 'my-album-1'), undefined)
+ assert.equal(resolveAlbumSlug(db, DEFAULT_SITE, 'a-new-title'), undefined)
+ assert.equal(
+ (await writer.update(second.id, { slug: 'a-new-title' }, access)).slug,
+ 'a-new-title',
+ )
+ const replacement = await writer.create({ title: 'My Album 1' }, access)
+ assert.equal(replacement.slug, 'my-album-1')
assert.equal(
- resolveAlbumSlug(db, DEFAULT_SITE, 'a-new-title')?.albumId,
- null,
+ resolveAlbumSlug(db, DEFAULT_SITE, 'my-album-1')?.albumId,
+ replacement.id,
)
- await assert.rejects(
- writer.update(second.id, { slug: 'a-new-title' }, access),
- (error) =>
- error instanceof CoreError &&
- error.statusCode === 409 &&
- /previously used/.test(error.message),
+ const reusedHistory = await writer.create({ title: 'My Album' }, access)
+ assert.equal(reusedHistory.slug, 'my-album')
+ assert.equal(
+ resolveAlbumSlug(db, DEFAULT_SITE, 'my-album')?.isCurrent,
+ true,
)
assert.equal(
- (await writer.create({ title: 'My Album' }, access)).slug,
- 'my-album-3',
+ resolveAlbumSlug(db, DEFAULT_SITE, 'my-album')?.albumId,
+ reusedHistory.id,
)
} finally {
sqlite.close()
}
})
+test('untransliteratable titles use a stable album-id slug', async () => {
+ const sqlite = new Database(':memory:')
+ sqlite.pragma('foreign_keys = ON')
+ const db = drizzle(sqlite, { schema })
+ migrate(db, { migrationsFolder: './packages/database/migrations' })
+ try {
+ const writer = createAlbumWriter({
+ repository: createSqliteAlbumWriteRepository(db, DEFAULT_SITE),
+ clock: { now: () => new Date() },
+ hashPassword: async (value) => value,
+ })
+ const album = await writer.create({ title: '🎉' }, access)
+ assert.equal(album.slug, `album-${album.id}`)
+ assert.equal(
+ (await writer.update(album.id, { slug: '' }, access)).slug,
+ `album-${album.id}`,
+ )
+ } finally {
+ sqlite.close()
+ }
+})
+
+test('migration replaces tombstones and retains live slug history', () => {
+ const oldMigrations = mkdtempSync(join(tmpdir(), 'album-slugs-0020-'))
+ cpSync('./packages/database/migrations', oldMigrations, { recursive: true })
+ rmSync(join(oldMigrations, '0021_reusable_album_slugs.sql'))
+ const journalPath = join(oldMigrations, 'meta/_journal.json')
+ const journal = JSON.parse(readFileSync(journalPath, 'utf8'))
+ journal.entries.pop()
+ writeFileSync(journalPath, JSON.stringify(journal))
+ const sqlite = new Database(':memory:')
+ sqlite.pragma('foreign_keys = ON')
+ const db = drizzle(sqlite, { schema })
+ try {
+ migrate(db, { migrationsFolder: oldMigrations })
+ db.insert(schema.albums)
+ .values([{ title: 'Keep' }, { title: 'Delete' }])
+ .run()
+ sqlite.exec(`
+ INSERT INTO album_slugs (site_id, slug, album_id, is_current)
+ VALUES (1, 'keep', 1, 1), (1, 'old-keep', 1, 0), (1, 'delete', 2, 1);
+ DELETE FROM albums WHERE id = 2;
+ `)
+ assert.equal(resolveAlbumSlug(db, DEFAULT_SITE, 'delete')?.albumId, null)
+
+ migrate(db, { migrationsFolder: './packages/database/migrations' })
+ assert.equal(resolveAlbumSlug(db, DEFAULT_SITE, 'delete'), undefined)
+ assert.equal(resolveAlbumSlug(db, DEFAULT_SITE, 'keep')?.albumId, 1)
+ assert.equal(resolveAlbumSlug(db, DEFAULT_SITE, 'old-keep')?.albumId, 1)
+ assert.equal(
+ resolveAlbumSlug(db, DEFAULT_SITE, 'old-keep')?.isCurrent,
+ false,
+ )
+ const albumIdColumn = (
+ sqlite.prepare("PRAGMA table_info('album_slugs')").all() as Array<{
+ name: string
+ notnull: number
+ }>
+ ).find((column) => column.name === 'album_id')
+ assert.equal(albumIdColumn?.notnull, 1)
+ assert.ok(
+ (
+ sqlite
+ .prepare("PRAGMA foreign_key_list('album_slugs')")
+ .all() as Array<{ on_delete: string }>
+ ).some((foreignKey) => foreignKey.on_delete === 'CASCADE'),
+ )
+
+ sqlite.pragma('foreign_keys = OFF')
+ sqlite.exec('DELETE FROM albums WHERE id = 1')
+ assert.equal(resolveAlbumSlug(db, DEFAULT_SITE, 'keep'), undefined)
+ assert.equal(resolveAlbumSlug(db, DEFAULT_SITE, 'old-keep'), undefined)
+ } finally {
+ sqlite.close()
+ rmSync(oldMigrations, { recursive: true, force: true })
+ }
+})
+
test('backfill assigns deterministic slugs once for existing rows', () => {
const statements: string[] = []
const sqlite = new Database(':memory:', {