Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.
TypeScript albumsexif-extractiongeocodinglive-photomotion-photophoto-galleryphoto-sharingwebgl-viewer
feat(cloud): support custom album slugs and permanent redirects
Timothy Yin41975c767a69
diff --git a/apps/cloud/app/components/CloudAlbumsManager.vue b/apps/cloud/app/components/CloudAlbumsManager.vueindex 29d79def..db570e71 100644--- a/apps/cloud/app/components/CloudAlbumsManager.vue+++ b/apps/cloud/app/components/CloudAlbumsManager.vue@@ -1,4 +1,5 @@<script setup lang="ts">+import { isValidAlbumSlug } from '@chronoframe/contracts/album-slug'import type { Album, Photo } from '@chronoframe/contracts/resources'import type { TableColumn } from '@nuxt/ui'const {@@ -27,6 +28,7 @@ const search = ref(''),generation = ref(0)const draft = reactive({title: '',+ slug: '',description: '',isHidden: false,passwordEnabled: false,@@ -87,6 +89,7 @@ function create() {hadPassword.value = falseObject.assign(draft, {title: '',+ slug: '',description: '',isHidden: false,passwordEnabled: false,@@ -118,6 +121,7 @@ async function edit(album: Album) {hadPassword.value = !!data.album.hasPasswordObject.assign(draft, {title: data.album.title,+ slug: data.album.slug || '',description: data.album.description || '',isHidden: !!data.album.isHidden,passwordEnabled: !!data.album.hasPassword,@@ -158,6 +162,14 @@ function movePhoto(index: number, step: number) {}async function save() {if (!loaded.value || saving.value || !draft.title.trim()) return+ if (draft.slug.trim() && !isValidAlbumSlug(draft.slug.trim())) {+ toast.add({+ title:+ 'Use lowercase letters, numbers and single hyphens; the slug cannot be numeric only.',+ color: 'error',+ })+ return+ }if (draft.passwordEnabled && !hadPassword.value && !draft.password) {toast.add({ title: 'Enter an album password.', color: 'error' })return@@ -177,7 +189,7 @@ async function save() {const id = crypto.getRandomValues(new Uint32Array(1))[0] || 1await api(base.value + '/albums', {method: 'POST',- body: { id, title: draft.title, isHidden: true },+ body: { id, title: draft.title, slug: draft.slug, isHidden: true },})selected.value = idrevision.value = 1@@ -189,6 +201,7 @@ async function save() {body: {revision: revision.value,title: draft.title,+ slug: draft.slug,description: draft.description || null,isHidden: draft.isHidden,photoIds: draft.photoIds,@@ -429,6 +442,11 @@ function menu(album: Album) {><ConsoleAlbumDetailsFieldsv-model:title="draft.title"v-model:description="draft.description"+ v-model:slug="draft.slug"+ show-slug+ :current-slug="+ selected ? albums.find((a) => a.id === selected)?.slug : undefined+ "/><UCheckboxv-model="draft.isHidden"label="Hide album"diff --git a/apps/cloud/app/composables/useCloudSiteMedia.ts b/apps/cloud/app/composables/useCloudSiteMedia.tsindex 5fa77639..dfdc856d 100644--- a/apps/cloud/app/composables/useCloudSiteMedia.ts+++ b/apps/cloud/app/composables/useCloudSiteMedia.ts@@ -138,19 +138,21 @@ export function useCloudMediaWorkspace(props: {const diagnostic = (error as { data?: { data?: { code?: string } } }).data?.data?.codemessage.value =- diagnostic && Object.hasOwn(STORAGE_CONNECTION_MESSAGES, diagnostic)- ? STORAGE_CONNECTION_MESSAGES[- diagnostic as keyof typeof STORAGE_CONNECTION_MESSAGES- ]- : code === 503- ? 'Media services need deployment configuration. Check the selected environment settings.'- : code === 409- ? 'This item changed. Refresh and try again.'- : code === 429- ? 'The preview resource limit has been reached.'- : code === 403- ? 'Administrator access is required.'- : 'The operation failed. Check the entered values and your connection, then retry.'+ diagnostic === 'album_slug_conflict'+ ? 'This album URL is already used or reserved by an older link. Choose another slug.'+ : diagnostic && Object.hasOwn(STORAGE_CONNECTION_MESSAGES, diagnostic)+ ? STORAGE_CONNECTION_MESSAGES[+ diagnostic as keyof typeof STORAGE_CONNECTION_MESSAGES+ ]+ : code === 503+ ? 'Media services need deployment configuration. Check the selected environment settings.'+ : code === 409+ ? 'This item changed. Refresh and try again.'+ : code === 429+ ? 'The preview resource limit has been reached.'+ : code === 403+ ? 'Administrator access is required.'+ : 'The operation failed. Check the entered values and your connection, then retry.'return false} finally {busy.value = falsediff --git a/apps/cloud/server/api/sites/[siteId]/media/[...operation].ts b/apps/cloud/server/api/sites/[siteId]/media/[...operation].tsindex 7dec9288..2fdd01cd 100644--- a/apps/cloud/server/api/sites/[siteId]/media/[...operation].ts+++ b/apps/cloud/server/api/sites/[siteId]/media/[...operation].ts@@ -1,3 +1,5 @@+import type { MediaDatabase } from '@chronoframe/database/cloud-media'+import { createCloudAlbumWithSlug } from '@chronoframe/database/cloud-album-slugs'import { deleteCloudPhotos } from '../../../../utils/cloud-photo-delete'import { updateCloudAlbum } from '../../../../utils/cloud-album-editor'import { getRouterParam, createError } from 'h3'@@ -456,16 +458,14 @@ export default definePlatformHandler(async (event) => {if (event.method === 'POST') {const albumId = String(number(body.id))const title = text(body.title, 80)- if (body.isHidden === true) {- const created = await raw- .prepare(- 'INSERT INTO cloud_albums(site_id,id,title,hidden,created_at,updated_at) SELECT ?,?,?,1,?,? WHERE (SELECT COUNT(*) FROM cloud_albums WHERE site_id=?)<100 ON CONFLICT DO NOTHING RETURNING id',- )- .bind(siteId, albumId, title, now, now, siteId)- .first()- if (!created) throw createError({ statusCode: 409 })- } else await repository.createAlbum(albumId, title)- return { id: Number(albumId) }+ const slug = await createCloudAlbumWithSlug(+ raw as unknown as MediaDatabase,+ siteId,+ albumId,+ title,+ { hidden: body.isHidden === true, slug: body.slug },+ )+ return { id: Number(albumId), slug }}}if (@@ -502,6 +502,11 @@ export default definePlatformHandler(async (event) => {'DELETE FROM cloud_album_photos WHERE site_id=? AND album_id=?',).bind(siteId, albumId),+ raw+ .prepare(+ 'UPDATE cloud_album_slugs SET album_id=NULL,is_current=0 WHERE site_id=? AND album_id=?',+ )+ .bind(siteId, albumId),raw.prepare('DELETE FROM cloud_albums WHERE site_id=? AND id=?').bind(siteId, albumId),diff --git a/apps/cloud/server/utils/cloud-album-editor.ts b/apps/cloud/server/utils/cloud-album-editor.tsindex b6bcf61f..4aebcca0 100644--- a/apps/cloud/server/utils/cloud-album-editor.ts+++ b/apps/cloud/server/utils/cloud-album-editor.ts@@ -1,3 +1,9 @@+import { CoreError } from '@chronoframe/core'+import {+ cloudAlbumSlugConflict,+ prepareCloudAlbumSlug,+} from '@chronoframe/database/cloud-album-slugs'+import type { MediaDatabase } from '@chronoframe/database/cloud-media'import { createError } from 'h3'import type { platformDatabase } from '../../../shared/platform/runtime'type CloudDatabase = ReturnType<typeof platformDatabase>@@ -9,7 +15,8 @@ export async function updateCloudAlbum(siteId: number,id: number,body: Record<string, unknown>,-) {+ slugAttempt = 0,+): Promise<{ revision: number }> {const revision = body.revision,title = body.titleif (@@ -84,7 +91,16 @@ export async function updateCloudAlbum(const guard ='EXISTS(SELECT 1 FROM cloud_albums WHERE site_id=? AND id=? AND revision=?)'const args = [siteId, String(id), Number(revision)]- const statements = []+ const claim = await prepareCloudAlbumSlug(+ db as unknown as MediaDatabase,+ siteId,+ String(id),+ title.trim(),+ body.slug,+ guard,+ args,+ )+ const statements = [...claim.statements]if (photoIds) {statements.push(db@@ -139,7 +155,23 @@ export async function updateCloudAlbum(...args,),)- const results = await db.batch(statements)+ let results+ try {+ results = await db.batch(statements)+ } catch (error) {+ if (!cloudAlbumSlugConflict(error)) throw error+ if (+ (body.slug === undefined ||+ (typeof body.slug === 'string' && !body.slug.trim())) &&+ slugAttempt < 3+ )+ return updateCloudAlbum(db, siteId, id, body, slugAttempt + 1)+ throw new CoreError(+ 409,+ 'Album URL slug already exists',+ 'album_slug_conflict',+ )+ }if (results.at(-1)?.meta.changes !== 1) throw createError({ statusCode: 409 })return { revision: Number(revision) + 1 }}diff --git a/apps/shared/platform/runtime.ts b/apps/shared/platform/runtime.tsindex a925703a..c8e3d9f0 100644--- a/apps/shared/platform/runtime.ts+++ b/apps/shared/platform/runtime.ts@@ -98,6 +98,21 @@ export function definePlatformHandler<T>(false,)}+ if (+ (error as { statusCode?: number; code?: string })?.statusCode === 409 &&+ (error as { code?: string }).code === 'album_slug_conflict'+ ) {+ setResponseHeader(event, 'Cache-Control', 'no-store')+ return sendError(+ event,+ createError({+ statusCode: 409,+ statusMessage: 'Album URL slug already exists',+ data: { code: 'album_slug_conflict' },+ }),+ false,+ )+ }const code = (error as { statusCode?: number })?.statusCodeconst messages: Record<number, string> = {400: 'Invalid request',diff --git a/apps/site/app/middleware/site.global.ts b/apps/site/app/middleware/site.global.tsindex 714f1191..ddd61653 100644--- a/apps/site/app/middleware/site.global.ts+++ b/apps/site/app/middleware/site.global.ts@@ -1,3 +1,5 @@+import { isAlbumPagePath } from '@chronoframe/gallery/shared/utils/albumPath'+export default defineNuxtRouteMiddleware(async (to) => {const context = useEntryContext()if (@@ -22,7 +24,7 @@ export default defineNuxtRouteMiddleware(async (to) => {!/^\/[a-zA-Z0-9_-]{1,128}$/.test(to.path) &&to.path !== '/' &&to.path !== '/albums' &&- !/^\/albums\/[1-9][0-9]*$/.test(to.path)+ !isAlbumPagePath(to.path))return abortNavigation(createError({ statusCode: 404 }))})diff --git a/apps/site/server/api/public/albums/resolve/[slug].get.ts b/apps/site/server/api/public/albums/resolve/[slug].get.tsnew file mode 100644index 00000000..43b195b7--- /dev/null+++ b/apps/site/server/api/public/albums/resolve/[slug].get.ts@@ -0,0 +1,23 @@+import { createError, getRouterParam } from 'h3'+import { resolveCloudAlbumPath } from '@chronoframe/database/cloud-album-slugs'+import type { MediaDatabase } from '@chronoframe/database/cloud-media'+import {+ definePlatformHandler,+ platformDatabase,+} from '../../../../../../shared/platform/runtime'+import { publicSiteContext } from '../../../../../../shared/platform/context'+export default definePlatformHandler(async (event) => {+ const context = await publicSiteContext(event)+ const resolved = await resolveCloudAlbumPath(+ platformDatabase(event) as unknown as MediaDatabase,+ context.site.id,+ getRouterParam(event, 'slug') ?? '',+ )+ if (!resolved || resolved.isHidden)+ throw createError({ statusCode: 404, statusMessage: 'Album not found' })+ return {+ albumId: resolved.albumId,+ slug: resolved.slug,+ isCanonical: resolved.isCanonical,+ }+})diff --git a/apps/site/server/middleware/album-slug-redirect.ts b/apps/site/server/middleware/album-slug-redirect.tsnew file mode 100644index 00000000..2d375df4--- /dev/null+++ b/apps/site/server/middleware/album-slug-redirect.ts@@ -0,0 +1,31 @@+import { createError, sendRedirect, setResponseHeader } from 'h3'+import { resolveCloudAlbumPath } from '@chronoframe/database/cloud-album-slugs'+import type { MediaDatabase } from '@chronoframe/database/cloud-media'+import {+ platformDatabase,+ platformRequestURL,+} from '../../../shared/platform/runtime'+import { publicSiteContext } from '../../../shared/platform/context'+export default defineEventHandler(async (event) => {+ if (event.method !== 'GET' && event.method !== 'HEAD') return+ const url = platformRequestURL(event)+ const match = /^\/albums\/([^/]+)\/?$/.exec(url.pathname)+ if (!match) return+ setResponseHeader(event, 'Cache-Control', 'no-store')+ let segment: string+ try {+ segment = decodeURIComponent(match[1]!)+ } catch {+ throw createError({ statusCode: 404, statusMessage: 'Album not found' })+ }+ const context = await publicSiteContext(event)+ const resolved = await resolveCloudAlbumPath(+ platformDatabase(event) as unknown as MediaDatabase,+ context.site.id,+ segment,+ )+ if (!resolved || resolved.isHidden)+ throw createError({ statusCode: 404, statusMessage: 'Album not found' })+ if (!resolved.isCanonical || url.pathname !== `/albums/${resolved.slug}`)+ return sendRedirect(event, `/albums/${resolved.slug}${url.search}`, 301)+})diff --git a/apps/site/server/middleware/platform-boundary.ts b/apps/site/server/middleware/platform-boundary.tsindex 115d9637..27af0a03 100644--- a/apps/site/server/middleware/platform-boundary.ts+++ b/apps/site/server/middleware/platform-boundary.ts@@ -17,6 +17,9 @@ export default defineEventHandler((event) => {'/api/public/photos','/api/public/albums',].includes(path) ||+ /^\/api\/public\/albums\/resolve\/(?:[a-z0-9]+(?:-[a-z0-9]+)*)$/.test(+ path,+ ) ||/^\/api\/public\/albums\/[1-9][0-9]*$/.test(path) ||/^\/api\/public\/photos\/[a-z0-9_-]+\/(?:albums|reactions)$/.test(path) ||/^\/api\/public\/media\/[a-z0-9_-]+\/(?:original|thumbnail|live-video|display)$/.test(diff --git a/packages/contracts/src/resources.ts b/packages/contracts/src/resources.tsindex 768d8630..cca83edc 100644--- a/packages/contracts/src/resources.ts+++ b/packages/contracts/src/resources.ts@@ -35,7 +35,7 @@ export interface Photo {export interface Album {id: number- /** Present for Self-hosted albums; Cloud currently uses the numeric ID in URLs. */+ /** Canonical public URL segment; older clients may omit it. */slug?: stringtitle: stringdescription: string | nulldiff --git a/packages/core/package.json b/packages/core/package.jsonindex 1b4ce353..d53a2570 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -4,13 +4,15 @@"private": true,"type": "module","exports": {- ".": "./src/index.ts"+ ".": "./src/index.ts",+ "./album-slug": "./src/album-slug.ts"},"scripts": {"type-check": "tsc --noEmit"},"dependencies": {- "@chronoframe/contracts": "workspace:*"+ "@chronoframe/contracts": "workspace:*",+ "transliteration": "2.6.1"},"devDependencies": {"typescript": "^5.9.3"diff --git a/packages/core/src/album-slug.ts b/packages/core/src/album-slug.tsnew file mode 100644index 00000000..a94e408f--- /dev/null+++ b/packages/core/src/album-slug.ts@@ -0,0 +1,37 @@+import { slugify } from 'transliteration'+import { CoreError } from './errors.ts'+import {+ ALBUM_SLUG_MAX_LENGTH,+ isNumericAlbumPathSegment,+ isValidAlbumSlug,+} from '@chronoframe/contracts/album-slug'++/** Convert a title to a stable, URL-safe base. Persistence owns uniqueness. */+export function generatedAlbumSlug(title: string): string {+ const result = slugify(title.normalize('NFKC'), {+ separator: '-',+ lowercase: true,+ })+ .replace(/[^a-z0-9]+/g, '-')+ .replace(/^-+|-+$/g, '')+ .slice(0, ALBUM_SLUG_MAX_LENGTH)+ .replace(/-+$/g, '')+ if (!result) return 'album'+ return isNumericAlbumPathSegment(result)+ ? `album-${result.slice(0, ALBUM_SLUG_MAX_LENGTH - 6)}`+ : result+}++/** Keep a manually chosen slug exact after trimming surrounding whitespace. */+export function validateCustomAlbumSlug(input: string): string {+ const slug = input.trim()+ if (!isValidAlbumSlug(slug))+ throw new CoreError(400, 'Invalid album URL slug')+ return slug+}++export function suffixedAlbumSlug(base: string, suffix: number): string {+ if (suffix === 0) return base+ const ending = `-${suffix}`+ return `${base.slice(0, ALBUM_SLUG_MAX_LENGTH - ending.length).replace(/-+$/g, '')}${ending}`+}diff --git a/packages/database/package.json b/packages/database/package.jsonindex cc37a360..d6f0b37a 100644--- a/packages/database/package.json+++ b/packages/database/package.json@@ -13,7 +13,8 @@"./album-slugs": "./src/album-slugs.ts","./cloud-media": "./src/cloud-media.ts","./cloud-execution": "./src/cloud-execution.ts",- "./cloud-resources": "./src/cloud-resources.ts"+ "./cloud-resources": "./src/cloud-resources.ts",+ "./cloud-album-slugs": "./src/cloud-album-slugs.ts"},"scripts": {"type-check": "tsc --noEmit"diff --git a/packages/database/src/album-slug.ts b/packages/database/src/album-slug.tsindex 59c37563..23ab364c 100644--- a/packages/database/src/album-slug.ts+++ b/packages/database/src/album-slug.ts@@ -1,37 +1,6 @@-import { slugify } from 'transliteration'-import { CoreError } from '@chronoframe/core'-import {- ALBUM_SLUG_MAX_LENGTH,- isNumericAlbumPathSegment,- isValidAlbumSlug,-} from '@chronoframe/contracts/album-slug'--/** Convert a title to a stable, URL-safe base. Persistence owns uniqueness. */-export function generatedAlbumSlug(title: string): string {- const result = slugify(title.normalize('NFKC'), {- separator: '-',- lowercase: true,- })- .replace(/[^a-z0-9]+/g, '-')- .replace(/^-+|-+$/g, '')- .slice(0, ALBUM_SLUG_MAX_LENGTH)- .replace(/-+$/g, '')- if (!result) return 'album'- return isNumericAlbumPathSegment(result)- ? `album-${result.slice(0, ALBUM_SLUG_MAX_LENGTH - 6)}`- : result-}--/** Keep a manually chosen slug exact after trimming surrounding whitespace. */-export function validateCustomAlbumSlug(input: string): string {- const slug = input.trim()- if (!isValidAlbumSlug(slug))- throw new CoreError(400, 'Invalid album URL slug')- return slug-}--export function suffixedAlbumSlug(base: string, suffix: number): string {- if (suffix === 0) return base- const ending = `-${suffix}`- return `${base.slice(0, ALBUM_SLUG_MAX_LENGTH - ending.length).replace(/-+$/g, '')}${ending}`-}+// Shared by the SQLite and edge-safe D1 slug registries.+export {+ generatedAlbumSlug,+ validateCustomAlbumSlug,+ suffixedAlbumSlug,+} from '@chronoframe/core/album-slug'diff --git a/packages/database/src/cloud-album-slugs.ts b/packages/database/src/cloud-album-slugs.tsnew file mode 100644index 00000000..b34434e8--- /dev/null+++ b/packages/database/src/cloud-album-slugs.ts@@ -0,0 +1,249 @@+import { CoreError } from '@chronoframe/core'+import {+ generatedAlbumSlug,+ suffixedAlbumSlug,+ validateCustomAlbumSlug,+} from '@chronoframe/core/album-slug'+import {+ ALBUM_SLUG_MAX_LENGTH,+ isNumericAlbumPathSegment,+ isValidAlbumSlug,+} from '@chronoframe/contracts/album-slug'+import type { MediaDatabase } from './cloud-media.ts'++async function rows<T>(+ db: MediaDatabase,+ sql: string,+ ...values: (string | number | null)[]+) {+ return (+ await db+ .prepare(sql)+ .bind(...values)+ .all<T>()+ ).results+}+export function cloudAlbumSlugConflict(error: unknown): boolean {+ return /(?:NOT NULL constraint failed: cloud_album_slugs.site_id|UNIQUE constraint failed: cloud_album_slugs)/.test(+ String(error),+ )+}+/** Every statement retains the caller's revision/creation guard inside the D1 batch. */+export async function prepareCloudAlbumSlug(+ db: MediaDatabase,+ siteId: number,+ albumId: string,+ title: string,+ requested: unknown,+ guard: string,+ args: (string | number | null)[],+) {+ if (requested !== undefined && typeof requested !== 'string')+ throw new CoreError(400, 'Invalid album URL slug')+ const current = (+ await rows<{ slug: string }>(+ db,+ 'SELECT slug FROM cloud_album_slugs WHERE site_id=? AND album_id=? AND is_current=1',+ siteId,+ albumId,+ )+ )[0]?.slug+ if (requested === undefined && current)+ return { slug: current, statements: [] }+ const automatic = requested === undefined || String(requested).trim() === ''+ let slug: string+ if (automatic) {+ const base = generatedAlbumSlug(title)+ const candidates = Array.from({ length: 1001 }, (_, i) =>+ suffixedAlbumSlug(base, i),+ )+ const available = await rows<{ slug: string }>(+ db,+ `SELECT value AS slug FROM json_each(?) WHERE NOT EXISTS(SELECT 1 FROM cloud_album_slugs s WHERE s.site_id=? AND s.slug=value AND (s.album_id IS NULL OR s.album_id<>?)) ORDER BY CAST(key AS INTEGER) LIMIT 1`,+ JSON.stringify(candidates),+ siteId,+ albumId,+ )+ if (!available[0])+ throw new CoreError(409, 'Choose a different album URL slug')+ slug = available[0].slug+ } else slug = validateCustomAlbumSlug(String(requested))+ const statements = [+ // A conflicting owner/tombstone deliberately violates NOT NULL. D1 rolls the+ // WHOLE batch back, rather than clearing the old current URL and losing it.+ db+ .prepare(+ `INSERT INTO cloud_album_slugs(site_id,slug,album_id,is_current) SELECT ?,?,?,0 WHERE ${guard} ON CONFLICT(site_id,slug) DO UPDATE SET site_id=CASE WHEN cloud_album_slugs.album_id=excluded.album_id THEN cloud_album_slugs.site_id ELSE NULL END`,+ )+ .bind(siteId, slug, albumId, ...args),+ db+ .prepare(+ `UPDATE cloud_album_slugs SET is_current=0 WHERE site_id=? AND album_id=? AND is_current=1 AND ${guard}`,+ )+ .bind(siteId, albumId, ...args),+ db+ .prepare(+ `UPDATE cloud_album_slugs SET is_current=1 WHERE site_id=? AND slug=? AND album_id=? AND ${guard}`,+ )+ .bind(siteId, slug, albumId, ...args),+ ]+ return { slug, statements }+}+/** Lazy, idempotent repair matches SQLite's startup backfill without requiring Node in D1 migrations. */+export async function ensureCloudAlbumSlugs(db: MediaDatabase, siteId: number) {+ const missing = await rows<{ id: string; title: string }>(+ db,+ `SELECT id,title FROM cloud_albums a WHERE site_id=? AND NOT EXISTS(SELECT 1 FROM cloud_album_slugs s WHERE s.site_id=a.site_id AND s.album_id=a.id AND s.is_current=1) ORDER BY CAST(id AS INTEGER) LIMIT 100`,+ siteId,+ )+ for (const album of missing) {+ for (let attempt = 0; attempt < 4; attempt++) {+ const guard =+ 'EXISTS(SELECT 1 FROM cloud_albums WHERE site_id=? AND id=?) AND NOT EXISTS(SELECT 1 FROM cloud_album_slugs WHERE site_id=? AND album_id=? AND is_current=1)'+ const claim = await prepareCloudAlbumSlug(+ db,+ siteId,+ album.id,+ album.title,+ undefined,+ guard,+ [siteId, album.id, siteId, album.id],+ )+ if (!claim.statements.length) break+ try {+ await db.batch(claim.statements)+ break+ } catch (error) {+ if (!cloudAlbumSlugConflict(error) || attempt === 3) throw error+ }+ }+ }+}+export async function createCloudAlbumWithSlug(+ db: MediaDatabase,+ siteId: number,+ id: string,+ title: string,+ options: { hidden?: boolean; slug?: unknown } = {},+) {+ if (!/^[1-9][0-9]*$/.test(id) || !Number.isSafeInteger(Number(id)))+ throw new CoreError(400, 'Canonical numeric album ID required')+ if (options.slug !== undefined && typeof options.slug !== 'string')+ throw new CoreError(400, 'Invalid album URL slug')+ const existing = (+ await rows<{ title: string }>(+ db,+ 'SELECT title FROM cloud_albums WHERE site_id=? AND id=?',+ siteId,+ id,+ )+ )[0]+ if (existing) {+ if (existing.title !== title)+ throw new CoreError(409, 'Album identifier already used')+ await ensureCloudAlbumSlugs(db, siteId)+ const current = (+ await rows<{ slug: string }>(+ db,+ 'SELECT slug FROM cloud_album_slugs WHERE site_id=? AND album_id=? AND is_current=1',+ siteId,+ id,+ )+ )[0]!+ if (+ typeof options.slug === 'string' &&+ options.slug.trim() &&+ options.slug.trim() !== current.slug+ )+ throw new CoreError(409, 'Album identifier already used')+ return current.slug+ }+ for (let attempt = 0; attempt < 4; attempt++) {+ const guard =+ 'EXISTS(SELECT 1 FROM cloud_albums WHERE site_id=? AND id=? AND title=?) AND NOT EXISTS(SELECT 1 FROM cloud_album_slugs WHERE site_id=? AND album_id=? AND is_current=1)'+ const claim = await prepareCloudAlbumSlug(+ db,+ siteId,+ id,+ title,+ options.slug,+ guard,+ [siteId, id, title, siteId, id],+ )+ const now = Date.now()+ try {+ await db.batch([+ db+ .prepare(+ 'INSERT INTO cloud_albums(site_id,id,title,hidden,created_at,updated_at) SELECT ?,?,?,?,?,? WHERE (SELECT COUNT(*) FROM cloud_albums WHERE site_id=?)<100 ON CONFLICT DO NOTHING',+ )+ .bind(siteId, id, title, options.hidden ? 1 : 0, now, now, siteId),+ ...claim.statements,+ ])+ const result = (+ await rows<{ title: string; slug: string }>(+ db,+ 'SELECT a.title,s.slug FROM cloud_albums a JOIN cloud_album_slugs s ON s.site_id=a.site_id AND s.album_id=a.id AND s.is_current=1 WHERE a.site_id=? AND a.id=?',+ siteId,+ id,+ )+ )[0]+ if (!result) throw new CoreError(429, 'Album limit reached')+ if (+ result.title !== title ||+ (typeof options.slug === 'string' &&+ options.slug.trim() &&+ options.slug.trim() !== result.slug)+ )+ throw new CoreError(409, 'Album identifier already used')+ return result.slug+ } catch (error) {+ if (!cloudAlbumSlugConflict(error)) throw error+ if (+ (typeof options.slug === 'string' && options.slug.trim()) ||+ attempt === 3+ )+ throw new CoreError(+ 409,+ 'Album URL slug already exists',+ 'album_slug_conflict',+ )+ }+ }+ throw new CoreError(+ 409,+ 'Album URL slug already exists',+ 'album_slug_conflict',+ )+}+export async function resolveCloudAlbumPath(+ db: MediaDatabase,+ siteId: number,+ segment: string,+) {+ if (segment.length > ALBUM_SLUG_MAX_LENGTH) return null+ const numeric = isNumericAlbumPathSegment(segment)+ if (+ numeric &&+ (!Number.isSafeInteger(Number(segment)) || Number(segment) < 1)+ )+ return null+ if (!numeric && !isValidAlbumSlug(segment)) return null+ await ensureCloudAlbumSlugs(db, siteId)+ const result = (+ await rows<{ albumId: string; slug: string; hidden: number }>(+ db,+ `SELECT a.id AS albumId,current.slug,a.hidden FROM cloud_albums a JOIN cloud_album_slugs current ON current.site_id=a.site_id AND current.album_id=a.id AND current.is_current=1 ${numeric ? '' : 'JOIN cloud_album_slugs requested ON requested.site_id=a.site_id AND requested.album_id=a.id'} WHERE a.site_id=? AND ${numeric ? 'a.id=?' : 'requested.slug=?'}`,+ siteId,+ numeric ? String(Number(segment)) : segment,+ )+ )[0]+ return result+ ? {+ albumId: Number(result.albumId),+ slug: result.slug,+ isCanonical: !numeric && segment === result.slug,+ isHidden: !!result.hidden,+ }+ : null+}diff --git a/packages/database/src/cloud-media.ts b/packages/database/src/cloud-media.tsindex eae88264..fa37bfbf 100644--- a/packages/database/src/cloud-media.ts+++ b/packages/database/src/cloud-media.ts@@ -1,3 +1,4 @@+import { createCloudAlbumWithSlug } from './cloud-album-slugs.ts'import {assertSiteContext,CoreError,@@ -74,23 +75,7 @@ export function createCloudMediaRepository()},async createAlbum(id: string, title: string) {- if (!/^[1-9][0-9]*$/.test(id) || !Number.isSafeInteger(Number(id)))- throw new CoreError(400, 'Canonical numeric album ID required')- await db.batch([- statement(- 'INSERT INTO cloud_albums(site_id,id,title) SELECT ?,?,? WHERE (SELECT COUNT(*) FROM cloud_albums WHERE site_id=?)<100 ON CONFLICT DO NOTHING',- text(id),- text(title),- siteId,- ),- ])- const existing = await first<{ title: string }>(- 'SELECT title FROM cloud_albums WHERE site_id=? AND id=?',- id,- )- if (!existing) throw new CoreError(429, 'Album limit reached')- if (existing.title !== title)- throw new CoreError(409, 'Album identifier already used')+ await createCloudAlbumWithSlug(db, siteId, text(id), text(title))},async addToAlbum(albumId: string, photoId: string) {if (diff --git a/packages/database/src/cloud-resources.ts b/packages/database/src/cloud-resources.tsindex 4e23ffa9..472f39e0 100644--- a/packages/database/src/cloud-resources.ts+++ b/packages/database/src/cloud-resources.ts@@ -1,3 +1,4 @@+import { ensureCloudAlbumSlugs } from './cloud-album-slugs.ts'import {assertSiteContext,type SiteContext,@@ -15,6 +16,8 @@ export function createCloudResourceRepository(mediaPrefix: string,): ResourceReadRepository {assertSiteContext(site)+ let slugRepair: Promise<void> | undefined+ const ensureSlugs = () => (slugRepair ??= ensureCloudAlbumSlugs(db, site.id))const all = async <T>(sql: string, ...values: (string | number | null)[]) =>(await db@@ -63,6 +66,7 @@ export function createCloudResourceRepository(const album = (r: Record<string, unknown>): AlbumReadRecord => ({resource: {id: Number(r.id),+ slug: String(r.slug),title: String(r.title),description: r.description ? String(r.description) : null,coverPhotoId: r.ready_cover_photo_id@@ -76,7 +80,7 @@ export function createCloudResourceRepository(},passwordHash: r.password_hash ? String(r.password_hash) : null,})- const albumSelect = `SELECT a.*,v.password_hash,(SELECT p.id FROM cloud_photos p WHERE p.site_id=a.site_id AND p.id=a.cover_photo_id AND ${ready}) AS ready_cover_photo_id FROM cloud_albums a LEFT JOIN platform_album_access v ON v.site_id=a.site_id AND CAST(v.album_id AS TEXT)=a.id WHERE a.site_id=?`+ const albumSelect = `SELECT a.*,(SELECT slug FROM cloud_album_slugs s WHERE s.site_id=a.site_id AND s.album_id=a.id AND s.is_current=1) AS slug,v.password_hash,(SELECT p.id FROM cloud_photos p WHERE p.site_id=a.site_id AND p.id=a.cover_photo_id AND ${ready}) AS ready_cover_photo_id FROM cloud_albums a LEFT JOIN platform_album_access v ON v.site_id=a.site_id AND CAST(v.album_id AS TEXT)=a.id WHERE a.site_id=?`async function memberships(photoId?: string) {return (await all<{@@ -117,6 +121,7 @@ export function createCloudResourceRepository().map(photo)},async listAlbums() {+ await ensureSlugs()return (await all<Record<string, unknown>>(albumSelect + ' ORDER BY a.position,a.created_at DESC LIMIT 100',@@ -124,6 +129,7 @@ export function createCloudResourceRepository().map(album)},async getAlbum(id) {+ await ensureSlugs()const row = (await all<Record<string, unknown>>(albumSelect + ' AND a.id=?',diff --git a/packages/gallery/app/components/album/Listing.vue b/packages/gallery/app/components/album/Listing.vueindex 8f547134..e22ad965 100644--- a/packages/gallery/app/components/album/Listing.vue+++ b/packages/gallery/app/components/album/Listing.vue@@ -13,7 +13,6 @@ const appSlogan = useSettingRef('app:slogan')const { homeView, photoWallPath } = useHomeView()const { photos } = usePhotos()const { loggedIn } = useUserSession()-const useSlugs = useEntryCapabilities().edition === 'self-hosted'const {data: albums,status,@@ -297,7 +296,7 @@ const hoveredAlbum = ref<number | null>(null)<NuxtLinkv-for="album in visibleAlbums":key="album.id"- :to="albumPagePath(album, useSlugs)"+ :to="albumPagePath(album, true)"class="block"@mouseenter="hoveredAlbum = album.id"@mouseleave="hoveredAlbum = null"diff --git a/packages/gallery/app/components/photo/InfoPanel.vue b/packages/gallery/app/components/photo/InfoPanel.vueindex 7acccc45..63c675f6 100644--- a/packages/gallery/app/components/photo/InfoPanel.vue+++ b/packages/gallery/app/components/photo/InfoPanel.vue@@ -26,7 +26,6 @@ interface Album {const dayjs = useDayjs()const router = useRouter()const { localizeExif } = useExifLocalization()-const useSlugs = useEntryCapabilities().edition === 'self-hosted'const props = defineProps<Props>()@@ -485,7 +484,7 @@ const onTagClick = (tag: string) => {}const onAlbumClick = (album: Album) => {- window.open(albumPagePath(album, useSlugs))+ window.open(albumPagePath(album, true))}</script>diff --git a/packages/gallery/app/pages/albums/[albumId].vue b/packages/gallery/app/pages/albums/[albumId].vueindex ae6dd5f9..2482660d 100644--- a/packages/gallery/app/pages/albums/[albumId].vue+++ b/packages/gallery/app/pages/albums/[albumId].vue@@ -2,33 +2,20 @@const galleryApi = useGalleryApi()import { motion } from 'motion-v'-import { numericAlbumId } from '@chronoframe/gallery/shared/utils/albumPath'const route = useRoute()const router = useRouter()const dayjs = useDayjs()const { user } = useUserSession()const { albumListPath } = useHomeView()-const useSlugs = useEntryCapabilities().edition === 'self-hosted'-const albumSegment = computed(() => String(route.params.albumId))-const { data: resolved, error: resolveError } = useSlugs- ? await useGalleryFetch<{- albumId: number- slug: string- isCanonical: boolean- }>(() => `/api/albums/resolve/${encodeURIComponent(albumSegment.value)}`, {- watch: [albumSegment],- })- : {- data: computed(() => {- const id = numericAlbumId(albumSegment.value)- return id === null- ? null- : { albumId: id, slug: String(id), isCanonical: true }- }),- error: ref(null),- }+const { data: resolved, error: resolveError } = await useGalleryFetch<{+ albumId: number+ slug: string+ isCanonical: boolean+}>(() => `/api/albums/resolve/${encodeURIComponent(albumSegment.value)}`, {+ watch: [albumSegment],+})if (resolveError.value || !resolved.value)throw createError({ statusCode: 404, statusMessage: $t('album.notFound') })if (!resolved.value.isCanonical)diff --git a/packages/platform/migrations/0012_cloud_album_slugs.sql b/packages/platform/migrations/0012_cloud_album_slugs.sqlnew file mode 100644index 00000000..9ce90cb0--- /dev/null+++ b/packages/platform/migrations/0012_cloud_album_slugs.sql@@ -0,0 +1,12 @@+-- The registry owns both current URLs and permanently reserved historical URLs.+CREATE TABLE cloud_album_slugs (+ site_id INTEGER NOT NULL REFERENCES platform_sites(id),+ slug TEXT NOT NULL,+ album_id TEXT,+ is_current INTEGER NOT NULL DEFAULT 0 CHECK(is_current IN (0,1)),+ PRIMARY KEY(site_id,slug),+ FOREIGN KEY(site_id,album_id) REFERENCES cloud_albums(site_id,id),+ CHECK(album_id IS NOT NULL OR is_current=0)+);+CREATE UNIQUE INDEX cloud_album_one_current_slug ON cloud_album_slugs(site_id,album_id) WHERE is_current=1;+CREATE INDEX cloud_album_slug_album ON cloud_album_slugs(site_id,album_id);diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex aade53e6..6c87bea9 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -348,6 +348,9 @@ importers:"@chronoframe/contracts":specifier: workspace:*version: link:../contracts+ transliteration:+ specifier: 2.6.1+ version: 2.6.1devDependencies:typescript:specifier: ^5.9.3diff --git a/scripts/check-entry-boundaries.mjs b/scripts/check-entry-boundaries.mjsindex 36c857da..f73602f4 100644--- a/scripts/check-entry-boundaries.mjs+++ b/scripts/check-entry-boundaries.mjs@@ -44,6 +44,7 @@ for (const entry of ['cloud', 'site']) {'@chronoframe/database/cloud-media','@chronoframe/database/cloud-execution','@chronoframe/database/cloud-resources',+ '@chronoframe/database/cloud-album-slugs','@chronoframe/storage/s3-edge','@chronoframe/storage/credential-cipher','@chronoframe/storage/connection-probe',diff --git a/tests/cloud-album-editor.test.ts b/tests/cloud-album-editor.test.tsindex d9c392ed..4df0609f 100644--- a/tests/cloud-album-editor.test.ts+++ b/tests/cloud-album-editor.test.ts@@ -22,6 +22,9 @@ test('album metadata and password changes share a revision fence and retain tenaargs = vreturn statement},+ async all() {+ return { results: sqlite.prepare(sql).all(...args) }+ },async first() {return sqlite.prepare(sql).get(...args)},diff --git a/tests/cloud-album-slugs.test.ts b/tests/cloud-album-slugs.test.tsnew file mode 100644index 00000000..167a418a--- /dev/null+++ b/tests/cloud-album-slugs.test.ts@@ -0,0 +1,206 @@+import assert from 'node:assert/strict'+import test from 'node:test'+import { createRequire } from 'node:module'+import { readFile, readdir } from 'node:fs/promises'+import {+ createCloudAlbumWithSlug,+ resolveCloudAlbumPath,+} from '../packages/database/src/cloud-album-slugs.ts'+import { updateCloudAlbum } from '../apps/cloud/server/utils/cloud-album-editor.ts'+import type { PlatformD1 } from '../packages/platform/src/index.ts'+const require = createRequire(import.meta.url)+const { Miniflare, convertV4MiniflareOptions } = createRequire(+ require.resolve('wrangler/package.json'),+)('miniflare')++test('Real D1 album slugs share normalization, reserve history/tombstones and isolate Sites with atomic revision guards', async () => {+ const mf = new Miniflare(+ convertV4MiniflareOptions({+ modules: true,+ compatibilityDate: '2026-10-25',+ script: 'export default {fetch(){return new Response("test")}}',+ d1Databases: ['DB'],+ }),+ )+ try {+ const db = await mf.getD1Database('DB')+ for (const file of (await readdir('packages/platform/migrations'))+ .filter((n) => n.endsWith('.sql'))+ .sort()) {+ const sql = await readFile('packages/platform/migrations/' + file, 'utf8')+ for (const statement of sql+ .replace(/^--.*$/gm, '')+ .split(';')+ .map((s) => s.trim())+ .filter(Boolean))+ await db.prepare(statement).run()+ }+ await db+ .prepare(+ "INSERT INTO platform_workspaces(id,name) VALUES(1,'One'),(2,'Two')",+ )+ .run()+ await db+ .prepare(+ "INSERT INTO platform_sites(id,workspace_id,name,published) VALUES(1,1,'One',1),(2,2,'Two',1)",+ )+ .run()+ assert.equal(+ await createCloudAlbumWithSlug(db, 1, '1', '你好 World'),+ 'ni-hao-world',+ )+ assert.equal(+ await createCloudAlbumWithSlug(db, 1, '2', 'Beta', { slug: 'beta' }),+ 'beta',+ )+ assert.equal(+ await createCloudAlbumWithSlug(db, 2, '1', 'Foreign', {+ slug: 'ni-hao-world',+ }),+ 'ni-hao-world',+ )+ await db+ .prepare(+ "INSERT INTO cloud_albums(site_id,id,title) VALUES(1,'3','Legacy')",+ )+ .run()+ assert.equal((await resolveCloudAlbumPath(db, 1, '0003'))?.slug, 'legacy')+ const editor = db as PlatformD1+ await updateCloudAlbum(editor, 1, 1, {+ revision: 1,+ title: 'Renamed',+ slug: 'travel-2026',+ description: 'Changed',+ password: 'protected-password',+ })+ for (const path of ['1', 'ni-hao-world']) {+ const resolved = await resolveCloudAlbumPath(db, 1, path)+ assert.equal(resolved?.albumId, 1)+ assert.equal(resolved?.slug, 'travel-2026')+ assert.equal(resolved?.isCanonical, false)+ }+ assert.equal(+ (await resolveCloudAlbumPath(db, 1, 'travel-2026'))?.isCanonical,+ true,+ )+ const access = await db+ .prepare(+ 'SELECT * FROM platform_album_access WHERE site_id=1 AND album_id=1',+ )+ .first()+ await assert.rejects(+ updateCloudAlbum(editor, 1, 1, {+ revision: 1,+ title: 'Stale',+ slug: 'lost-update',+ password: null,+ }),+ { statusCode: 409 },+ )+ assert.equal(await resolveCloudAlbumPath(db, 1, 'lost-update'), null)+ assert.deepEqual(+ await db+ .prepare(+ 'SELECT * FROM platform_album_access WHERE site_id=1 AND album_id=1',+ )+ .first(),+ access,+ )+ await assert.rejects(+ updateCloudAlbum(editor, 1, 2, {+ revision: 1,+ title: 'Corrupted',+ slug: 'ni-hao-world',+ password: 'should-not-save',+ }),+ { statusCode: 409 },+ )+ assert.equal(+ (+ await db+ .prepare("SELECT title FROM cloud_albums WHERE site_id=1 AND id='2'")+ .first()+ ).title,+ 'Beta',+ )+ assert.equal(+ await db+ .prepare(+ 'SELECT 1 FROM platform_album_access WHERE site_id=1 AND album_id=2',+ )+ .first(),+ null,+ )+ const concurrent = await Promise.all([+ createCloudAlbumWithSlug(db, 1, '4', 'Same title'),+ createCloudAlbumWithSlug(db, 1, '5', 'Same title'),+ ])+ assert.equal(new Set(concurrent).size, 2)+ const race = await Promise.allSettled(+ [4, 5].map((id) =>+ updateCloudAlbum(editor, 1, id, {+ revision: 1,+ title: 'Race',+ slug: 'shared-target',+ }),+ ),+ )+ assert.equal(race.filter((r) => r.status === 'fulfilled').length, 1)+ assert.equal(race.filter((r) => r.status === 'rejected').length, 1)+ assert.equal(+ (+ await db+ .prepare(+ "SELECT COUNT(*) n FROM cloud_album_slugs WHERE site_id=1 AND album_id IN ('4','5') AND is_current=1",+ )+ .first()+ ).n,+ 2,+ )+ await db.batch([+ db.prepare(+ 'DELETE FROM platform_album_access WHERE site_id=1 AND album_id=1',+ ),+ db.prepare(+ "UPDATE cloud_album_slugs SET album_id=NULL,is_current=0 WHERE site_id=1 AND album_id='1'",+ ),+ db.prepare("DELETE FROM cloud_albums WHERE site_id=1 AND id='1'"),+ ])+ assert.equal(await resolveCloudAlbumPath(db, 1, 'ni-hao-world'), null)+ assert.equal(await resolveCloudAlbumPath(db, 1, 'travel-2026'), null)+ assert.equal(+ (await resolveCloudAlbumPath(db, 2, 'ni-hao-world'))?.albumId,+ 1,+ )+ await assert.rejects(+ createCloudAlbumWithSlug(db, 1, '10', 'Reclaim', { slug: 'travel-2026' }),+ { statusCode: 409 },+ )+ assert.equal(+ await db+ .prepare("SELECT 1 FROM cloud_albums WHERE site_id=1 AND id='10'")+ .first(),+ null,+ 'failed claim rolls back the new album as well',+ )+ assert.equal(+ await createCloudAlbumWithSlug(db, 1, '10', '你好 World'),+ 'ni-hao-world-1',+ )+ for (const slug of ['123', 'Bad Slug', '../bad', 'a'.repeat(81)])+ await assert.rejects(+ createCloudAlbumWithSlug(db, 1, '99', 'Invalid', { slug }),+ { statusCode: 400 },+ )+ for (const path of [+ 'bad--slug',+ '0',+ '../bad',+ '999999999999999999999',+ 'a'.repeat(81),+ ])+ assert.equal(await resolveCloudAlbumPath(db, 1, path), null)+ } finally {+ await mf.dispose()+ }+})diff --git a/tests/cloud-media-repositories.test.ts b/tests/cloud-media-repositories.test.tsindex 017a0510..bd45e894 100644--- a/tests/cloud-media-repositories.test.ts+++ b/tests/cloud-media-repositories.test.ts@@ -117,6 +117,21 @@ for (const backend of ['SQLite', 'D1'] as const) {)await run(part)}+ for (const file of [+ '0008_cloud_albums.sql',+ '0012_cloud_album_slugs.sql',+ ]) {+ const sql = await readFile(+ new URL('../packages/platform/migrations/' + file, import.meta.url),+ 'utf8',+ )+ for (const part of sql+ .replace(/^--.*$/gm, '')+ .split(';')+ .map((s) => s.trim())+ .filter(Boolean))+ await run(part)+ }assert.equal((await db