fix: retry concurrent taxonomy slug collisions

Author: ascorbic

packages/core/src/api/handlers/taxonomies.ts

@@ -19,6 +19,15 @@ import { fetchVisibleTermCounts } from "../../taxonomies/term-counts.js";
 import type { ApiResult } from "../types.js";
 
 const NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+const MAX_GENERATED_TERM_SLUG_ATTEMPTS = 16;
+
+function isTermSlugUniqueViolation(error: unknown): boolean {
+	const message = error instanceof Error ? error.message.toLowerCase() : "";
+	return (
+		(message.includes("unique constraint failed") || message.includes("duplicate key")) &&
+		message.includes("slug")
+	);
+}
 
 // ---------------------------------------------------------------------------
 // Response types
@@ -820,6 +829,7 @@ export async function handleTermCreate(
 		translationOf?: string;
 	},
 ): Promise<ApiResult<TermResponse>> {
+	let attemptedSlug = input.slug;
 	try {
 		const locale = resolveConfiguredLocale(input.locale ?? getI18nConfig()?.defaultLocale ?? "en");
 		// Taxonomy definitions are per-locale, but terms can exist in any locale
@@ -829,21 +839,20 @@ export async function handleTermCreate(
 		if (!lookup.success) return lookup;
 
 		const repo = new TaxonomyRepository(db);
-		const generatedSlug = input.slug === undefined;
-		const slug = input.slug ?? (await repo.generateUniqueSlug(taxonomyName, input.label, locale));
 
 		// Coerce empty-string parentId to undefined (treat as "no parent").
 		const parentId =
 			input.parentId === "" || input.parentId === undefined ? undefined : input.parentId;
 
 		// Conflict check is scoped to locale (per-locale slugs are unique).
-		const existing = generatedSlug ? null : await repo.findBySlug(taxonomyName, slug, locale);
+		const existing =
+			input.slug === undefined ? null : await repo.findBySlug(taxonomyName, input.slug, locale);
 		if (existing) {
 			return {
 				success: false,
 				error: {
 					code: "CONFLICT",
-					message: `Term '${slug}' already exists in '${taxonomyName}' (${locale})`,
+					message: `Term '${input.slug}' already exists in '${taxonomyName}' (${locale})`,
 				},
 			};
 		}
@@ -875,15 +884,33 @@ export async function handleTermCreate(
 			return { success: false, error: parentError };
 		}
 
-		const term = await repo.create({
-			name: taxonomyName,
-			slug,
-			label: input.label,
-			parentId: parentId ?? undefined,
-			data: input.description ? { description: input.description } : undefined,
-			locale,
-			translationOf: input.translationOf,
-		});
+		const create = (slug: string) =>
+			repo.create({
+				name: taxonomyName,
+				slug,
+				label: input.label,
+				parentId: parentId ?? undefined,
+				data: input.description ? { description: input.description } : undefined,
+				locale,
+				translationOf: input.translationOf,
+			});
+		let term: Awaited<ReturnType<typeof create>> | undefined;
+		let lastSlugConflict: unknown;
+		if (input.slug !== undefined) {
+			term = await create(input.slug);
+		} else {
+			for (let attempt = 0; attempt < MAX_GENERATED_TERM_SLUG_ATTEMPTS; attempt++) {
+				attemptedSlug = await repo.generateUniqueSlug(taxonomyName, input.label, locale);
+				try {
+					term = await create(attemptedSlug);
+					break;
+				} catch (error) {
+					if (!isTermSlugUniqueViolation(error)) throw error;
+					lastSlugConflict = error;
+				}
+			}
+		}
+		if (!term) throw lastSlugConflict ?? new Error("Failed to create taxonomy term");
 
 		invalidateTermCache();
 
@@ -903,7 +930,16 @@ export async function handleTermCreate(
 				},
 			},
 		};
-	} catch {
+	} catch (error) {
+		if (isTermSlugUniqueViolation(error)) {
+			return {
+				success: false,
+				error: {
+					code: "CONFLICT",
+					message: `Term with slug '${attemptedSlug ?? "(generated)"}' already exists in taxonomy '${taxonomyName}'`,
+				},
+			};
+		}
 		return {
 			success: false,
 			error: { code: "TERM_CREATE_ERROR", message: "Failed to create term" },

packages/core/tests/unit/taxonomies/term-slug-generation.test.ts

@@ -1,20 +1,13 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, expect, it } from "vitest";
 
 import { handleTaxonomyCreate, handleTermCreate } from "../../../src/api/handlers/taxonomies.js";
-import { createTermBody } from "../../../src/api/schemas/taxonomies.js";
 import {
 	describeEachDialect,
 	setupForDialectWithCollections,
 	teardownForDialect,
 	type DialectTestContext,
 } from "../../utils/test-db.js";
 
-describe("taxonomy term create schema", () => {
-	it("allows the server to derive a slug from the label", () => {
-		expect(createTermBody.safeParse({ label: "音楽" }).success).toBe(true);
-	});
-});
-
 describeEachDialect("taxonomy term slug generation", (dialect) => {
 	let ctx: DialectTestContext;
 
@@ -66,6 +59,20 @@ describeEachDialect("taxonomy term slug generation", (dialect) => {
 		expect(second.data.term.slug).toBe("音楽-1");
 	});
 
+	it("recovers when concurrent generated slugs collide", async () => {
+		const results = await Promise.all(
+			Array.from({ length: 6 }, () =>
+				handleTermCreate(ctx.db, "tags", { label: "同時", locale: "en" }),
+			),
+		);
+
+		expect(results.every((result) => result.success)).toBe(true);
+		const slugs = results.flatMap((result) => (result.success ? [result.data.term.slug] : []));
+		expect(new Set(slugs)).toEqual(
+			new Set(["同時", "同時-1", "同時-2", "同時-3", "同時-4", "同時-5"]),
+		);
+	});
+
 	it("keeps generated slug uniqueness scoped to the locale", async () => {
 		const english = await handleTermCreate(ctx.db, "tags", { label: "音楽", locale: "en" });
 		const japanese = await handleTermCreate(ctx.db, "tags", { label: "音楽", locale: "ja" });