emdash 0.36.0 → 0.38.0

package/src/database/repositories/entry-locks.ts

@@ -0,0 +1,257 @@
+import type { Kysely, RawBuilder } from "kysely";
+import { sql } from "kysely";
+
+import { isPostgres } from "../dialect-helpers.js";
+import type { Database } from "../types.js";
+
+export interface EntryLock {
+	collection: string;
+	entryId: string;
+	userId: string;
+	/** Display name of the holder, `null` when the account has none set. */
+	userName: string | null;
+	acquiredAt: string;
+	expiresAt: string;
+}
+
+export type EntryLockClaim =
+	| { outcome: "acquired"; lock: EntryLock }
+	| { outcome: "held"; lock: EntryLock };
+
+interface LockKey {
+	collection: string;
+	entryId: string;
+	userId: string;
+}
+
+interface LeaseInput extends LockKey {
+	leaseSeconds: number;
+}
+
+interface LockRow {
+	collection: string;
+	entry_id: string;
+	user_id: string;
+	token: string;
+	acquired_at: string;
+	expires_at: string;
+}
+
+/**
+ * A refused claim proves a live lease existed at statement time, so a second
+ * pass only runs when that lease lapsed or was released in between.
+ */
+const CLAIM_ATTEMPTS = 2;
+
+function toEntryLock(row: LockRow & { user_name: string | null }): EntryLock {
+	return {
+		collection: row.collection,
+		entryId: row.entry_id,
+		userId: row.user_id,
+		userName: row.user_name ?? null,
+		acquiredAt: row.acquired_at,
+		expiresAt: row.expires_at,
+	};
+}
+
+/**
+ * One lease per entry, keyed by `(collection, entry_id)`.
+ *
+ * Every timestamp comes from the database clock, so leases stay comparable
+ * across isolates whose wall clocks drift.
+ */
+export class EntryLockRepository {
+	constructor(private db: Kysely<Database>) {}
+
+	/**
+	 * Claims the entry for `userId`, or reports who holds it. An expired lease
+	 * and the caller's own lease are both claimable; anyone else's live lease
+	 * needs `takeover`.
+	 *
+	 * `token` identifies the caller's editing session. The row keeps the latest
+	 * one and `release` matches on it, so two tabs of one account can share an
+	 * entry without the first tab to close dropping the lease the other still
+	 * relies on.
+	 */
+	async acquire(
+		input: LeaseInput & { token: string; takeover?: boolean },
+	): Promise<EntryLockClaim> {
+		for (let attempt = 0; attempt < CLAIM_ATTEMPTS; attempt++) {
+			const claimed = await this.claim(input);
+			if (claimed) return { outcome: "acquired", lock: await this.withHolderName(claimed) };
+
+			const holder = await this.findLive(input.collection, input.entryId);
+			if (holder) return { outcome: "held", lock: holder };
+		}
+		throw new Error(`Entry lock claim did not settle for ${input.collection}/${input.entryId}`);
+	}
+
+	/**
+	 * Extends the caller's own live lease, and reports whether they had one.
+	 * `false` lets a write path tell "mine, extended" from "someone else's, or
+	 * none" without taking a lease it was never given.
+	 */
+	async refreshHeld(input: LeaseInput): Promise<boolean> {
+		const result = await this.db
+			.updateTable("_emdash_entry_locks")
+			.set({ expires_at: this.timestampOffset(input.leaseSeconds) })
+			.where("collection", "=", input.collection)
+			.where("entry_id", "=", input.entryId)
+			.where("user_id", "=", input.userId)
+			.where(this.leaseIsLive("expires_at"))
+			.executeTakeFirst();
+		return Number(result.numUpdatedRows ?? 0) > 0;
+	}
+
+	async findLive(collection: string, entryId: string): Promise<EntryLock | null> {
+		const row = await this.liveQuery(collection, entryId).executeTakeFirst();
+		return row ? toEntryLock(row) : null;
+	}
+
+	/** The live lease, but only while the collection still has locking switched on. */
+	async findEnforceable(collection: string, entryId: string): Promise<EntryLock | null> {
+		const row = await this.liveQuery(collection, entryId)
+			.innerJoin(
+				"_emdash_collections",
+				"_emdash_collections.slug",
+				"_emdash_entry_locks.collection",
+			)
+			.where("_emdash_collections.edit_locking", "!=", 0)
+			.executeTakeFirst();
+		return row ? toEntryLock(row) : null;
+	}
+
+	/**
+	 * Drops the caller's lease. With `token`, only the session that last
+	 * claimed the row can drop it; without, any session of the account can.
+	 */
+	async release(key: LockKey & { token?: string }): Promise<boolean> {
+		let query = this.db
+			.deleteFrom("_emdash_entry_locks")
+			.where("collection", "=", key.collection)
+			.where("entry_id", "=", key.entryId)
+			.where("user_id", "=", key.userId);
+		if (key.token !== undefined) query = query.where("token", "=", key.token);
+		const result = await query.executeTakeFirst();
+		return Number(result.numDeletedRows ?? 0) > 0;
+	}
+
+	/** Drops every lease on an entry, whoever holds it. */
+	async releaseEntry(collection: string, entryId: string): Promise<void> {
+		await this.db
+			.deleteFrom("_emdash_entry_locks")
+			.where("collection", "=", collection)
+			.where("entry_id", "=", entryId)
+			.execute();
+	}
+
+	/**
+	 * Insert-or-steal in one statement. The conflict branch keeps the original
+	 * acquisition time when the holder is unchanged, so the admin can show how
+	 * long the entry has been open rather than how long ago it was last typed
+	 * into.
+	 *
+	 * Column references in the conflict branch are table-qualified: Postgres
+	 * sees both the stored row and `excluded` there and rejects a bare name as
+	 * ambiguous.
+	 */
+	private async claim(
+		input: LeaseInput & { token: string; takeover?: boolean },
+	): Promise<LockRow | undefined> {
+		const now = this.timestampOffset(0);
+		const expiresAt = this.timestampOffset(input.leaseSeconds);
+		return this.db
+			.insertInto("_emdash_entry_locks")
+			.values({
+				collection: input.collection,
+				entry_id: input.entryId,
+				user_id: input.userId,
+				token: input.token,
+				acquired_at: now,
+				expires_at: expiresAt,
+			})
+			.onConflict((oc) => {
+				const update = oc.columns(["collection", "entry_id"]).doUpdateSet({
+					user_id: input.userId,
+					token: input.token,
+					acquired_at: sql<string>`CASE
+						WHEN ${sql.ref("_emdash_entry_locks.user_id")} = ${input.userId}
+						THEN ${sql.ref("_emdash_entry_locks.acquired_at")}
+						ELSE ${now}
+					END`,
+					expires_at: expiresAt,
+				});
+				if (input.takeover === true) return update;
+				return update.where((eb) =>
+					eb.or([
+						eb("_emdash_entry_locks.user_id", "=", input.userId),
+						this.leaseHasExpired("_emdash_entry_locks.expires_at"),
+					]),
+				);
+			})
+			.returningAll()
+			.executeTakeFirst();
+	}
+
+	private liveQuery(collection: string, entryId: string) {
+		return this.db
+			.selectFrom("_emdash_entry_locks")
+			.leftJoin("users", "users.id", "_emdash_entry_locks.user_id")
+			.select([
+				"_emdash_entry_locks.collection",
+				"_emdash_entry_locks.entry_id",
+				"_emdash_entry_locks.user_id",
+				"_emdash_entry_locks.token",
+				"_emdash_entry_locks.acquired_at",
+				"_emdash_entry_locks.expires_at",
+				"users.name as user_name",
+			])
+			.where("_emdash_entry_locks.collection", "=", collection)
+			.where("_emdash_entry_locks.entry_id", "=", entryId)
+			.where(this.leaseIsLive("_emdash_entry_locks.expires_at"));
+	}
+
+	private async withHolderName(row: LockRow): Promise<EntryLock> {
+		const user = await this.db
+			.selectFrom("users")
+			.select("name")
+			.where("id", "=", row.user_id)
+			.executeTakeFirst();
+		return {
+			collection: row.collection,
+			entryId: row.entry_id,
+			userId: row.user_id,
+			userName: user?.name ?? null,
+			acquiredAt: row.acquired_at,
+			expiresAt: row.expires_at,
+		};
+	}
+
+	private leaseIsLive(column: string) {
+		const expiresAt = sql.ref(column);
+		return isPostgres(this.db)
+			? sql<boolean>`${expiresAt}::timestamptz > clock_timestamp()`
+			: sql<boolean>`${expiresAt} > strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
+	}
+
+	private leaseHasExpired(column: string) {
+		const expiresAt = sql.ref(column);
+		return isPostgres(this.db)
+			? sql<boolean>`${expiresAt}::timestamptz <= clock_timestamp()`
+			: sql<boolean>`${expiresAt} <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
+	}
+
+	private timestampOffset(offsetSeconds: number): RawBuilder<string> {
+		if (isPostgres(this.db)) {
+			return sql<string>`to_char(
+				(clock_timestamp() AT TIME ZONE 'UTC') + (${offsetSeconds} * INTERVAL '1 second'),
+				'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'
+			)`;
+		}
+		return sql<string>`strftime(
+			'%Y-%m-%dT%H:%M:%fZ',
+			'now',
+			${`${offsetSeconds >= 0 ? "+" : ""}${offsetSeconds} seconds`}
+		)`;
+	}
+}

package/src/database/repositories/media-usage.ts

@@ -1801,12 +1801,21 @@ export class MediaUsageRepository {
 		};
 	}
 
+	/**
+	 * Scans for reclaimable occurrences, or resolves to `null` when the sweep was
+	 * never issued because the lease is gone or the tick is out of budget. An
+	 * empty array means the scan ran and found nothing, which lets the caller
+	 * retire the sweep window; `null` must leave the cursor where it was.
+	 */
 	async findMediaUsageCleanupCandidates(input: {
 		cutoff: string;
 		cursor: MediaUsageCleanupCursor | null;
 		limit: number;
 		cleanupLease?: MediaUsageCleanupLease;
-	}): Promise<MediaUsageCleanupCandidate[]> {
+		canIssueStatement?: () => boolean;
+	}): Promise<MediaUsageCleanupCandidate[] | null> {
+		if (!(await this.admitCleanupScan(input.cleanupLease, input.canIssueStatement))) return null;
+
 		let query = this.db
 			.selectFrom("_emdash_media_usage as u")
 			.leftJoin("_emdash_media_usage_sources as s", "s.source_key", "u.source_key")
@@ -1828,19 +1837,11 @@ export class MediaUsageRepository {
 			.orderBy("u.created_at", "asc")
 			.orderBy("u.id", "asc")
 			.limit(Math.max(0, Math.floor(input.limit)));
-		if (input.cleanupLease) {
-			query = query.where(this.activeCleanupLeaseExpression(input.cleanupLease));
-		}
 
 		if (input.cursor) {
+			const cursor = input.cursor;
 			query = query.where((eb) =>
-				eb.or([
-					eb("u.created_at", ">", input.cursor!.createdAt),
-					eb.and([
-						eb("u.created_at", "=", input.cursor!.createdAt),
-						eb("u.id", ">", input.cursor!.id),
-					]),
-				]),
+				eb(eb.refTuple("u.created_at", "u.id"), ">", eb.tuple(cursor.createdAt, cursor.id)),
 			);
 		}
 
@@ -1928,9 +1929,9 @@ export class MediaUsageRepository {
 				options.canIssueStatement,
 			);
 		}
-		if (!canIssueCleanupStatement(options.canIssueStatement)) return 0;
+		if (!(await this.admitCleanupScan(options.cleanupLease, options.canIssueStatement))) return 0;
 
-		let query = this.db
+		const rows = await this.db
 			.selectFrom("_emdash_media_usage as u")
 			.leftJoin("_emdash_media_usage_sources as s", (join) =>
 				join.onRef("s.source_key", "=", "u.source_key"),
@@ -1946,11 +1947,8 @@ export class MediaUsageRepository {
 			.where(this.noActiveGenerationWriteExpression("u"))
 			.orderBy("u.created_at", "asc")
 			.orderBy("u.id", "asc")
-			.limit(batchLimit);
-		if (options.cleanupLease) {
-			query = query.where(this.activeCleanupLeaseExpression(options.cleanupLease));
-		}
-		const rows = await query.execute();
+			.limit(batchLimit)
+			.execute();
 
 		return this.deleteOrphanCandidateIds(
 			rows.map((row) => row.id),
@@ -1975,9 +1973,9 @@ export class MediaUsageRepository {
 				options.canIssueStatement,
 			);
 		}
-		if (!canIssueCleanupStatement(options.canIssueStatement)) return 0;
+		if (!(await this.admitCleanupScan(options.cleanupLease, options.canIssueStatement))) return 0;
 
-		let query = this.db
+		const rows = await this.db
 			.selectFrom("_emdash_media_usage as u")
 			.innerJoin("_emdash_media_usage_sources as s", (join) =>
 				join.onRef("s.source_key", "=", "u.source_key"),
@@ -1994,11 +1992,8 @@ export class MediaUsageRepository {
 			.where(this.noActiveGenerationWriteExpression("u"))
 			.orderBy("u.created_at", "asc")
 			.orderBy("u.id", "asc")
-			.limit(batchLimit);
-		if (options.cleanupLease) {
-			query = query.where(this.activeCleanupLeaseExpression(options.cleanupLease));
-		}
-		const rows = await query.execute();
+			.limit(batchLimit)
+			.execute();
 
 		return this.deleteStaleCandidateIds(
 			rows.map((row) => row.id),
@@ -2023,9 +2018,9 @@ export class MediaUsageRepository {
 				options.canIssueStatement,
 			);
 		}
-		if (!canIssueCleanupStatement(options.canIssueStatement)) return 0;
+		if (!(await this.admitCleanupScan(options.cleanupLease, options.canIssueStatement))) return 0;
 
-		let query = this.db
+		const rows = await this.db
 			.selectFrom("_emdash_media_usage as u")
 			.innerJoin("_emdash_media_usage_sources as s", (join) =>
 				join.onRef("s.source_key", "=", "u.source_key"),
@@ -2042,11 +2037,8 @@ export class MediaUsageRepository {
 			.where(this.noActiveGenerationWriteExpression("u"))
 			.orderBy("u.created_at", "asc")
 			.orderBy("u.id", "asc")
-			.limit(batchLimit);
-		if (options.cleanupLease) {
-			query = query.where(this.activeCleanupLeaseExpression(options.cleanupLease));
-		}
-		const rows = await query.execute();
+			.limit(batchLimit)
+			.execute();
 
 		return this.deleteAbandonedCandidateIds(
 			rows.map((row) => row.id),
@@ -2062,16 +2054,16 @@ export class MediaUsageRepository {
 		canIssueStatement?: () => boolean,
 	): Promise<number> {
 		const batchLimit = Math.floor(limit);
-		if (batchLimit <= 0 || !canIssueCleanupStatement(canIssueStatement)) return 0;
-		let query = this.db
+		if (batchLimit <= 0) return 0;
+		if (!(await this.admitCleanupScan(cleanupLease, canIssueStatement))) return 0;
+		const rows = await this.db
 			.selectFrom("_emdash_media_usage_generation_writes")
 			.select("lease_token")
 			.where(this.generationWriteLeaseHasExpired("expires_at"))
 			.orderBy("expires_at", "asc")
 			.orderBy("lease_token", "asc")
-			.limit(batchLimit);
-		if (cleanupLease) query = query.where(this.activeCleanupLeaseExpression(cleanupLease));
-		const rows = await query.execute();
+			.limit(batchLimit)
+			.execute();
 		if (rows.length === 0 || !canIssueCleanupStatement(canIssueStatement)) return 0;
 		let deleteQuery = this.db
 			.deleteFrom("_emdash_media_usage_generation_writes")
@@ -2906,6 +2898,43 @@ export class MediaUsageRepository {
 			)`;
 	}
 
+	/**
+	 * Gates a bounded cleanup scan on the lease and the tick's statement budget.
+	 *
+	 * The budget is re-read after the lease row because that read is itself a
+	 * statement: an isolate suspended across it can resume with the budget spent.
+	 */
+	private async admitCleanupScan(
+		cleanupLease: MediaUsageCleanupLease | undefined,
+		canIssueStatement: (() => boolean) | undefined,
+	): Promise<boolean> {
+		if (!canIssueCleanupStatement(canIssueStatement)) return false;
+		if (!cleanupLease) return true;
+		return (
+			(await this.holdsCleanupLease(cleanupLease)) && canIssueCleanupStatement(canIssueStatement)
+		);
+	}
+
+	/**
+	 * Reads the lease row on its own so a lost lease can short-circuit a sweep.
+	 *
+	 * As a row-level `EXISTS` inside a `LIMIT`ed scan this predicate is constant
+	 * across every candidate row: when it is false the limit is unreachable and
+	 * the scan reads the whole `created_at` range before returning nothing.
+	 * Mutating statements still carry {@link activeCleanupLeaseExpression},
+	 * which is what actually fences a displaced owner.
+	 */
+	private async holdsCleanupLease(cleanupLease: MediaUsageCleanupLease): Promise<boolean> {
+		let query = this.db
+			.selectFrom("_emdash_media_usage_cleanup")
+			.select("task_key")
+			.where("task_key", "=", "projection_gc")
+			.where("lease_token", "=", cleanupLease.leaseToken)
+			.where(this.cleanupLeaseExpiryIsInFuture("_emdash_media_usage_cleanup.lease_expires_at"));
+		if (isPostgres(this.db)) query = query.forUpdate();
+		return (await query.executeTakeFirst()) !== undefined;
+	}
+
 	private activeCleanupLeaseExpression(cleanupLease: MediaUsageCleanupLease) {
 		const rowLock = isPostgres(this.db) ? sql` FOR UPDATE` : sql``;
 		return sql<boolean>`EXISTS (

package/src/database/repositories/media.ts

@@ -83,6 +83,7 @@ export interface CreateMediaInput {
 	dominantColor?: string;
 	status?: MediaStatus;
 	authorId?: string;
+	folderId?: string | null;
 }
 
 export interface FindManyMediaOptions {
@@ -105,6 +106,13 @@ export interface UpdateMediaInput extends FocalPointUpdate {
 	folderId?: string | null;
 }
 
+export interface ReplaceReadyMediaInput {
+	size: number;
+	width: number;
+	height: number;
+	contentHash: string;
+}
+
 export interface FindMediaPageOptions extends Omit<FindManyMediaOptions, "cursor"> {
 	page: number;
 }
@@ -148,7 +156,7 @@ export class MediaRepository {
 			status: input.status ?? "ready",
 			created_at: now,
 			author_id: input.authorId ?? null,
-			folder_id: null,
+			folder_id: input.folderId ?? null,
 		};
 
 		await this.db.insertInto("media").values(row).execute();
@@ -166,6 +174,7 @@ export class MediaRepository {
 		storageKey: string;
 		contentHash?: string;
 		authorId?: string;
+		folderId?: string | null;
 	}): Promise<MediaItem> {
 		return this.create({
 			...input,
@@ -375,6 +384,30 @@ export class MediaRepository {
 		return row ? this.rowToItem(row) : null;
 	}
 
+	async findAvailableFilename(filename: string): Promise<string> {
+		const exists = async (candidate: string) =>
+			Boolean(
+				await this.db
+					.selectFrom("media")
+					.select("id")
+					.where(sql<string>`lower(filename)`, "=", candidate.toLowerCase())
+					.executeTakeFirst(),
+			);
+		if (!(await exists(filename))) return filename;
+
+		const extensionIndex = filename.lastIndexOf(".");
+		const hasExtension = extensionIndex > 0;
+		const extension = hasExtension ? filename.slice(extensionIndex) : "";
+		const stem = hasExtension ? filename.slice(0, extensionIndex) : filename;
+		let copyNumber = 2;
+		let candidate = `${stem}-${copyNumber}${extension}`;
+		while (await exists(candidate)) {
+			copyNumber += 1;
+			candidate = `${stem}-${copyNumber}${extension}`;
+		}
+		return candidate;
+	}
+
 	/**
 	 * Find media by content hash
 	 * Used for deduplication - same content = same hash
@@ -480,6 +513,32 @@ export class MediaRepository {
 		return this.findById(id);
 	}
 
+	async replaceReadyFile(
+		id: string,
+		expectedStorageKey: string,
+		input: ReplaceReadyMediaInput,
+	): Promise<MediaItem | null> {
+		const row = await this.db
+			.updateTable("media")
+			.set({
+				size: input.size,
+				width: input.width,
+				height: input.height,
+				content_hash: input.contentHash,
+				blurhash: null,
+				dominant_color: null,
+				focal_x: null,
+				focal_y: null,
+			})
+			.where("id", "=", id)
+			.where("status", "=", "ready")
+			.where("storage_key", "=", expectedStorageKey)
+			.returningAll()
+			.executeTakeFirst();
+
+		return row ? this.rowToItem(row) : null;
+	}
+
 	/**
 	 * Delete media item
 	 */

package/src/database/repositories/options.ts

@@ -1,5 +1,15 @@
-import { sql, type Kysely, type SqlBool } from "kysely";
-
+import { sql, type Insertable, type Kysely, type SqlBool } from "kysely";
+
+import {
+	assertStorageKey,
+	assertStorageRevision,
+	serializeConditionalValue,
+} from "../../plugins/conditional-storage.js";
+import type {
+	VersionedValue,
+	ConditionalWriteResult,
+	ConditionalDeleteResult,
+} from "../../plugins/types.js";
 import type { Database, OptionTable } from "../types.js";
 
 function escapeLike(value: string): string {
@@ -42,16 +52,19 @@ export class OptionsRepository {
 	 * Set an option value (creates or updates)
 	 */
 	async set<T = unknown>(name: string, value: T): Promise<void> {
-		const row: OptionTable = {
+		const row: Insertable<OptionTable> = {
 			name,
 			value: JSON.stringify(value),
+			revision: crypto.randomUUID(),
 		};
 
 		// Upsert: insert or replace
 		await this.db
 			.insertInto("options")
 			.values(row)
-			.onConflict((oc) => oc.column("name").doUpdateSet({ value: row.value }))
+			.onConflict((oc) =>
+				oc.column("name").doUpdateSet({ value: row.value, revision: row.revision }),
+			)
 			.execute();
 	}
 
@@ -64,9 +77,10 @@ export class OptionsRepository {
 	 * existed (regardless of its value — even an empty string or null).
 	 */
 	async setIfAbsent<T = unknown>(name: string, value: T): Promise<boolean> {
-		const row: OptionTable = {
+		const row: Insertable<OptionTable> = {
 			name,
 			value: JSON.stringify(value),
+			revision: crypto.randomUUID(),
 		};
 
 		const result = await this.db
@@ -80,6 +94,56 @@ export class OptionsRepository {
 		return (result.numInsertedOrUpdatedRows ?? 0n) > 0n;
 	}
 
+	async getVersioned<T = unknown>(name: string): Promise<VersionedValue<T> | null> {
+		assertStorageKey(name, 2048);
+		const row = await this.db
+			.selectFrom("options")
+			.select(["value", "revision"])
+			.where("name", "=", name)
+			.executeTakeFirst();
+		if (!row) return null;
+		return { value: JSON.parse(row.value), revision: row.revision };
+	}
+
+	async compareAndSet(
+		name: string,
+		expectedRevision: string | null,
+		value: unknown,
+	): Promise<ConditionalWriteResult> {
+		assertStorageKey(name, 2048);
+		if (expectedRevision !== null) assertStorageRevision(expectedRevision);
+		const serialized = serializeConditionalValue(value);
+		const revision = crypto.randomUUID();
+		const row =
+			expectedRevision === null
+				? await this.db
+						.insertInto("options")
+						.values({ name, value: serialized, revision })
+						.onConflict((oc) => oc.column("name").doNothing())
+						.returning("revision")
+						.executeTakeFirst()
+				: await this.db
+						.updateTable("options")
+						.set({ value: serialized, revision })
+						.where("name", "=", name)
+						.where("revision", "=", expectedRevision)
+						.returning("revision")
+						.executeTakeFirst();
+		return row ? { applied: true, revision: row.revision } : { applied: false };
+	}
+
+	async compareAndDelete(name: string, expectedRevision: string): Promise<ConditionalDeleteResult> {
+		assertStorageKey(name, 2048);
+		assertStorageRevision(expectedRevision);
+		const row = await this.db
+			.deleteFrom("options")
+			.where("name", "=", name)
+			.where("revision", "=", expectedRevision)
+			.returning("name")
+			.executeTakeFirst();
+		return { applied: row !== undefined };
+	}
+
 	/**
 	 * Delete an option
 	 */