diff --git a/apps/api/scripts/import-laddr/translators.ts b/apps/api/scripts/import-laddr/translators.ts index 6e622ec..e571daa 100644 --- a/apps/api/scripts/import-laddr/translators.ts +++ b/apps/api/scripts/import-laddr/translators.ts @@ -25,6 +25,7 @@ */ import { uuidv7 } from 'uuidv7'; +import { normalizeHandle, normalizeLegacyHandle } from '@cfp/shared'; import type { BlogPost, Person, @@ -130,14 +131,10 @@ export function safeSlug( ctx: { idMaps: IdMaps; warnings: Warnings; legacyId: number | string }, ): string { const allowedChars = allowUnderscore ? 'a-z0-9-_' : 'a-z0-9-'; - const replaceRe = allowUnderscore ? /[^a-z0-9_-]+/g : /[^a-z0-9-]+/g; const headRe = new RegExp(`^[a-z0-9][${allowedChars}]{1,${maxLen - 1}}$`); - let candidate = rawInput.toLowerCase().replace(replaceRe, '-'); - candidate = candidate.replace(/^[-_]+|[-_]+$/g, ''); + let candidate = normalizeHandle(rawInput, { maxLen, allowUnderscore }); if (candidate.length === 0) candidate = `legacy-${ctx.legacyId}`; - if (candidate.length > maxLen) candidate = candidate.slice(0, maxLen); - if (!/^[a-z0-9]/.test(candidate)) candidate = `s${candidate}`.slice(0, maxLen); if (candidate !== rawInput) { ctx.warnings.push( @@ -473,7 +470,7 @@ export function translateTag(row: RawTag, ctx: TranslateCtx): Tag | null { // contain underscores. Tag slugs only allow `[a-z0-9-]` — coerce, but // don't dedupe (tags are uniqued by `(namespace, slug)` already; collisions // surface as gitsheets-side write errors and are exceedingly rare). - const slug = split.slug.replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, ''); + const slug = normalizeLegacyHandle(split.slug, 'tag'); if (slug.length === 0) { ctx.warnings.push( `[tags] legacyId=${legacyId} slug "${split.slug}" reduced to empty after sanitization; skipped`, diff --git a/apps/api/src/plugins/legacy-redirect.ts b/apps/api/src/plugins/legacy-redirect.ts index 61a6b2f..ecba588 100644 --- a/apps/api/src/plugins/legacy-redirect.ts +++ b/apps/api/src/plugins/legacy-redirect.ts @@ -22,6 +22,8 @@ import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'; import fp from 'fastify-plugin'; +import { normalizeLegacyHandle } from '@cfp/shared'; + import type { InMemoryState } from '../store/memory/state.js'; /** Long cache — legacy URL shapes are permanent. */ @@ -133,8 +135,13 @@ async function legacyRedirectPlugin(fastify: FastifyInstance): Promise { // /project-buzz/[/...] → /projects//buzz/[/...] -- const buzzMatch = /^\/project-buzz\/([^/]+)(\/.*)?$/.exec(path); if (buzzMatch) { - const buzzSlug = buzzMatch[1] as string; + const rawSlug = buzzMatch[1] as string; const suffix = buzzMatch[2] ?? ''; + // Exact match first, then the legacy handle normalization + // (specs/behaviors/slug-handles.md → "Legacy handle normalization"). + const buzzSlug = state.buzzIdBySlug.has(rawSlug) + ? rawSlug + : normalizeLegacyHandle(rawSlug, 'buzz'); const buzzId = state.buzzIdBySlug.get(buzzSlug); if (buzzId !== undefined) { const buzz = state.projectBuzz.get(buzzId); @@ -155,9 +162,11 @@ async function legacyRedirectPlugin(fastify: FastifyInstance): Promise { // /tags/.[/...] → /tags//[/...] --------- // Pure URL transform; no lookup. The legacy dot-form was laddr's tag // handle shape; the new site uses path-form for routing distinction. - const dotTagMatch = /^\/tags\/([a-z]+)\.([^/]+)(\/.*)?$/.exec(path); + // laddr matched handles case-insensitively, so accept any-case namespaces; + // the slug-redirect plugin normalizes the slug leg. + const dotTagMatch = /^\/tags\/([a-zA-Z]+)\.([^/]+)(\/.*)?$/.exec(path); if (dotTagMatch) { - const namespace = dotTagMatch[1] as string; + const namespace = (dotTagMatch[1] as string).toLowerCase(); const slug = dotTagMatch[2] as string; const suffix = dotTagMatch[3] ?? ''; await sendRedirect(reply, `/tags/${namespace}/${slug}${suffix}${query}`); diff --git a/apps/api/src/plugins/slug-redirect.ts b/apps/api/src/plugins/slug-redirect.ts index c1705df..40db377 100644 --- a/apps/api/src/plugins/slug-redirect.ts +++ b/apps/api/src/plugins/slug-redirect.ts @@ -25,6 +25,7 @@ import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'; import fp from 'fastify-plugin'; +import { normalizeLegacyHandle } from '@cfp/shared'; import type { SlugHistory } from '@cfp/shared/schemas'; import { slugHistoryKey, type InMemoryState } from '../store/memory/state.js'; @@ -58,20 +59,12 @@ const patterns: readonly RoutePattern[] = [ // match runs first so we attempt to resolve both buzz and project; either // can independently redirect. // (Currently no slug-history writer for buzz, but the spec includes 'buzz' - // in SlugHistory.entityType so the plumbing supports it.) + // in SlugHistory.entityType so the plumbing supports it.) Buzz slugs are + // unique across all projects, so `buzzIdBySlug` is the live check. { entityType: 'buzz', match: /^\/projects\/([^/]+)\/buzz\/([^/]+)(\/.*)?$/, - liveIndex: (state, slug) => { - // Buzz slugs are keyed by `${projectId}:${buzzSlug}` in the live index; - // since we don't have the projectId at this point cheaply, treat the - // slug as missing-from-live whenever a slug-history record exists. - // This is the spec-permitted behavior: if a freed buzz slug was taken - // by a different project, the slug-history record points away anyway. - void state; - void slug; - return false; - }, + liveIndex: (state, slug) => state.buzzIdBySlug.has(slug), rebuild: (m, resolved) => `/projects/${m[1]}/buzz/${resolved}${m[3] ?? ''}`, }, { @@ -111,14 +104,11 @@ const patterns: readonly RoutePattern[] = [ * no rewriting is needed (slug already live, or no slug-history entry, or * the chain bottoms out at the same slug). */ -function resolveSlug( +function followHistory( state: InMemoryState, pattern: RoutePattern, startSlug: string, ): string | null { - // Live first — never redirect away from a slug that's currently a real entity. - if (pattern.liveIndex(state, startSlug)) return null; - let current = startSlug; for (let hop = 0; hop < MAX_HOPS; hop++) { const entry = state.slugHistory.get(slugHistoryKey(pattern.entityType, current)); @@ -138,6 +128,44 @@ function resolveSlug( return current === startSlug ? null : current; } +interface Resolution { + readonly slug: string; + /** True for a legacy-normalization hit, which never expires. */ + readonly permanent: boolean; +} + +/** + * Resolve a non-live slug: slug-history first, then the legacy handle + * normalization (specs/behaviors/slug-handles.md → "Legacy handle + * normalization"), which only redirects when the normalized slug is live or + * itself resolves through slug-history. + */ +function resolveSlug( + state: InMemoryState, + pattern: RoutePattern, + startSlug: string, +): Resolution | null { + // Live first — never redirect away from a slug that's currently a real entity. + if (pattern.liveIndex(state, startSlug)) return null; + + const viaHistory = followHistory(state, pattern, startSlug); + if (viaHistory !== null) return { slug: viaHistory, permanent: false }; + + const normalized = normalizeLegacyHandle(safeDecode(startSlug), pattern.entityType); + if (normalized === '' || normalized === startSlug) return null; + if (pattern.liveIndex(state, normalized)) return { slug: normalized, permanent: true }; + const normalizedViaHistory = followHistory(state, pattern, normalized); + return normalizedViaHistory !== null ? { slug: normalizedViaHistory, permanent: false } : null; +} + +function safeDecode(segment: string): string { + try { + return decodeURIComponent(segment); + } catch { + return segment; + } +} + async function slugRedirectPlugin(fastify: FastifyInstance): Promise { fastify.addHook('onRequest', async (request: FastifyRequest, reply: FastifyReply) => { if (request.method !== 'GET' && request.method !== 'HEAD') return; @@ -162,15 +190,16 @@ async function slugRedirectPlugin(fastify: FastifyInstance): Promise { const resolved = resolveSlug(state, pattern, slug); if (!resolved) continue; - const newPath = pattern.rebuild(m, resolved); + const newPath = pattern.rebuild(m, resolved.slug); const target = newPath + query; - // 5-minute cache: the redirect itself may expire when the 90-day - // window does; a short cache balances perf with not lying to clients - // about a permanent-looking redirect. + // Slug-history redirects get a 5-minute cache: they expire when the + // 90-day window does, so a short cache avoids lying to clients about a + // permanent-looking redirect. Legacy-normalization redirects never + // expire and can be cached for a day. await reply .code(301) .header('Location', target) - .header('Cache-Control', 'public, max-age=300') + .header('Cache-Control', `public, max-age=${resolved.permanent ? 86400 : 300}`) .send(); return; } diff --git a/apps/api/tests/legacy-redirect.test.ts b/apps/api/tests/legacy-redirect.test.ts index 7904643..58d39d1 100644 --- a/apps/api/tests/legacy-redirect.test.ts +++ b/apps/api/tests/legacy-redirect.test.ts @@ -181,6 +181,23 @@ describe('legacy-redirect plugin', () => { expect(res.headers.location).toBe('/projects/news-project/buzz/press-mention'); }); + it('normalizes a legacy-cased buzz slug', async () => { + const projectId = '01951a3c-0000-7000-8000-000000000503'; + const buzzId = '01951a3c-0000-7000-8000-000000000504'; + await seedProject('news-project', projectId, undefined); + await seedBuzz({ + projectId, + projectSlug: 'news-project', + buzzId, + buzzSlug: 'press-mention', + }); + app = await bootApp(); + + const res = await app.inject({ method: 'GET', url: '/project-buzz/Press_Mention' }); + expect(res.statusCode).toBe(301); + expect(res.headers.location).toBe('/projects/news-project/buzz/press-mention'); + }); + it('passes through unknown buzz slugs', async () => { app = await bootApp(); const res = await app.inject({ method: 'GET', url: '/project-buzz/nonexistent' }); @@ -210,6 +227,13 @@ describe('legacy-redirect plugin', () => { expect(res.headers.location).toBe('/tags/event/ecocamp-2014'); }); + it('lowercases a legacy-cased namespace', async () => { + app = await bootApp(); + const res = await app.inject({ method: 'GET', url: '/tags/Topic.transit' }); + expect(res.statusCode).toBe(301); + expect(res.headers.location).toBe('/tags/topic/transit'); + }); + it('does not match /tags/topic/transit (already path-form)', async () => { app = await bootApp(); const res = await app.inject({ method: 'GET', url: '/tags/topic/transit' }); diff --git a/apps/api/tests/slug-redirect.test.ts b/apps/api/tests/slug-redirect.test.ts index e3cc70d..f414d0b 100644 --- a/apps/api/tests/slug-redirect.test.ts +++ b/apps/api/tests/slug-redirect.test.ts @@ -256,3 +256,79 @@ describe('slug-redirect plugin', () => { expect(slugHistoryKey('buzz', 'x')).toBe('buzz:x'); }); }); + +describe('slug-redirect: legacy handle normalization', () => { + it('301s a mixed-case legacy project handle, cached for a day', async () => { + await seedProject('apps_for_philly', '01951a3c-0000-7000-8000-000000000201'); + app = await bootApp(); + + const res = await app.inject({ method: 'GET', url: '/projects/Apps_for_Philly' }); + expect(res.statusCode).toBe(301); + expect(res.headers.location).toBe('/projects/apps_for_philly'); + expect(res.headers['cache-control']).toContain('max-age=86400'); + }); + + it('normalizes punctuation and preserves the suffix', async () => { + await seedProject('sheldon-md', '01951a3c-0000-7000-8000-000000000202'); + app = await bootApp(); + + const res = await app.inject({ method: 'GET', url: '/projects/sheldon.md/edit' }); + expect(res.statusCode).toBe(301); + expect(res.headers.location).toBe('/projects/sheldon-md/edit'); + }); + + it('drops underscores for people and preserves the query', async () => { + await seedPerson('jane-doe', '01951a3c-0000-7000-8000-000000000203'); + app = await bootApp(); + + const res = await app.inject({ method: 'GET', url: '/members/Jane_Doe?tab=projects' }); + expect(res.statusCode).toBe(301); + expect(res.headers.location).toBe('/members/jane-doe?tab=projects'); + }); + + it('reaches the canonical member from a legacy /people/ URL', async () => { + await seedPerson('jane-doe', '01951a3c-0000-7000-8000-000000000204'); + app = await bootApp(); + + let url = '/people/Jane_Doe'; + for (let hop = 0; hop < 3; hop++) { + const res = await app.inject({ method: 'GET', url }); + if (res.statusCode !== 301) break; + url = res.headers.location as string; + } + expect(url).toBe('/members/jane-doe'); + }); + + it('normalizes a legacy tag handle', async () => { + await seedTag('topic', 'urban-design', '01951a3c-0000-7000-8000-000000000205'); + app = await bootApp(); + + const res = await app.inject({ method: 'GET', url: '/tags/topic/Urban_Design' }); + expect(res.statusCode).toBe(301); + expect(res.headers.location).toBe('/tags/topic/urban-design'); + }); + + it('follows slug-history from the normalized slug', async () => { + const id = '01951a3c-0000-7000-8000-000000000206'; + await seedProject('new-name', id); + await seedSlugHistory('project', 'old_name', 'new-name', id); + app = await bootApp(); + + const res = await app.inject({ method: 'GET', url: '/projects/Old_Name' }); + expect(res.statusCode).toBe(301); + expect(res.headers.location).toBe('/projects/new-name'); + }); + + it('does not redirect when the normalized slug is unknown', async () => { + app = await bootApp(); + const res = await app.inject({ method: 'GET', url: '/projects/No_Such_Thing' }); + expect(res.statusCode).not.toBe(301); + }); + + it('never redirects a live slug', async () => { + await seedProject('apps_for_philly', '01951a3c-0000-7000-8000-000000000207'); + app = await bootApp(); + const res = await app.inject({ method: 'GET', url: '/projects/apps_for_philly' }); + expect(res.statusCode).not.toBe(301); + }); +}); diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts index bef2b20..33b6978 100644 --- a/packages/shared/src/index.ts +++ b/packages/shared/src/index.ts @@ -1,2 +1,3 @@ export * from './schemas/index.js'; export * from './markdown.js'; +export * from './slug.js'; diff --git a/packages/shared/src/slug.ts b/packages/shared/src/slug.ts new file mode 100644 index 0000000..fb1806c --- /dev/null +++ b/packages/shared/src/slug.ts @@ -0,0 +1,42 @@ +/** + * Legacy handle normalization — specs/behaviors/slug-handles.md → + * "Legacy handle normalization". + * + * The one transform both the laddr importer (to mint slugs) and the web + * redirect layer (to resolve pre-normalization inbound links) apply, so the + * two can't drift. Collision suffixing (`-2`, `-3`, …) is the importer's + * concern and deliberately not part of this. + */ + +export type LegacyHandleEntity = 'person' | 'project' | 'tag' | 'buzz'; + +export interface HandleRules { + readonly maxLen: number; + readonly allowUnderscore: boolean; +} + +export const LEGACY_HANDLE_RULES: Readonly> = { + person: { maxLen: 50, allowUnderscore: false }, + project: { maxLen: 80, allowUnderscore: true }, + tag: { maxLen: 50, allowUnderscore: false }, + buzz: { maxLen: 50, allowUnderscore: false }, +}; + +/** + * Lowercase, replace each run of disallowed characters with `-`, trim + * leading/trailing `-`/`_`, truncate to `maxLen`, and prefix `s` if the + * result doesn't start with `[a-z0-9]`. Returns `''` when nothing survives. + */ +export function normalizeHandle(input: string, rules: HandleRules): string { + const replaceRe = rules.allowUnderscore ? /[^a-z0-9_-]+/g : /[^a-z0-9-]+/g; + let out = input.toLowerCase().replace(replaceRe, '-'); + out = out.replace(/^[-_]+|[-_]+$/g, ''); + if (out.length === 0) return ''; + if (out.length > rules.maxLen) out = out.slice(0, rules.maxLen); + if (!/^[a-z0-9]/.test(out)) out = `s${out}`.slice(0, rules.maxLen); + return out; +} + +export function normalizeLegacyHandle(input: string, entity: LegacyHandleEntity): string { + return normalizeHandle(input, LEGACY_HANDLE_RULES[entity]); +} diff --git a/packages/shared/tests/slug.test.ts b/packages/shared/tests/slug.test.ts new file mode 100644 index 0000000..096e80d --- /dev/null +++ b/packages/shared/tests/slug.test.ts @@ -0,0 +1,44 @@ +import { describe, expect, it } from 'vitest'; + +import { normalizeLegacyHandle } from '../src/slug.js'; + +describe('normalizeLegacyHandle', () => { + it('lowercases', () => { + expect(normalizeLegacyHandle('Apps_for_Philly', 'project')).toBe('apps_for_philly'); + expect(normalizeLegacyHandle('ChrisAlfano', 'person')).toBe('chrisalfano'); + }); + + it('keeps underscores for projects only', () => { + expect(normalizeLegacyHandle('jane_doe', 'project')).toBe('jane_doe'); + expect(normalizeLegacyHandle('Jane_Doe', 'person')).toBe('jane-doe'); + expect(normalizeLegacyHandle('urban_design', 'tag')).toBe('urban-design'); + }); + + it('collapses runs of disallowed characters into one hyphen', () => { + expect(normalizeLegacyHandle('sheldon.md', 'project')).toBe('sheldon-md'); + expect( + normalizeLegacyHandle('o.s.c.a.v.-open_system_for_computer_accessible_vision', 'project'), + ).toBe('o-s-c-a-v--open_system_for_computer_accessible_vision'); + expect(normalizeLegacyHandle('jane..doe', 'person')).toBe('jane-doe'); + }); + + it('trims leading and trailing separators', () => { + expect(normalizeLegacyHandle('_jane_', 'project')).toBe('jane'); + expect(normalizeLegacyHandle('.jane.', 'person')).toBe('jane'); + }); + + it('truncates to the entity max length', () => { + expect(normalizeLegacyHandle('a'.repeat(90), 'project')).toHaveLength(80); + expect(normalizeLegacyHandle('a'.repeat(60), 'person')).toHaveLength(50); + }); + + it('returns empty when nothing survives', () => { + expect(normalizeLegacyHandle('...', 'person')).toBe(''); + }); + + it('is idempotent on canonical slugs', () => { + for (const s of ['chris', 'clean-and-green-philly', 'philly_bike_action']) { + expect(normalizeLegacyHandle(s, 'project')).toBe(s); + } + }); +}); diff --git a/plans/legacy-handle-redirects.md b/plans/legacy-handle-redirects.md index 0f3771e..ba8d553 100644 --- a/plans/legacy-handle-redirects.md +++ b/plans/legacy-handle-redirects.md @@ -1,9 +1,10 @@ --- -status: planned +status: done depends: [] specs: - specs/behaviors/slug-handles.md - specs/behaviors/legacy-id-mapping.md +pr: 198 --- # Plan: permanent redirects for pre-normalization legacy handles @@ -52,11 +53,11 @@ Out: ## Validation -- [ ] `normalizeLegacyHandle` unit tests cover case, `.`, `_` (person vs. +- [x] `normalizeLegacyHandle` unit tests cover case, `.`, `_` (person vs. project), leading punctuation, truncation, and the `s` prefix -- [ ] Importer uses the shared function; the existing importer tests are +- [x] Importer uses the shared function; the existing importer tests are green and unchanged -- [ ] Redirect tests: `/projects/Apps_for_Philly` → 301 +- [x] Redirect tests: `/projects/Apps_for_Philly` → 301 `/projects/apps_for_philly`; `/projects/sheldon.md/edit` → 301 `/projects/sheldon-md/edit`; `/members/Jane_Doe?x=1` → 301 `/members/jane-doe?x=1`; `/people/Jane_Doe` reaches the canonical member @@ -65,7 +66,7 @@ Out: redirected - [ ] Production spot check: the 66 changed project handles from the 2026-09-08 import all 301 to their canonical slug -- [ ] `type-check` + `lint` + full api suite green +- [x] `type-check` + `lint` + full api suite green ## Risks / unknowns @@ -74,4 +75,16 @@ Out: ## Notes +- The production spot check stays unchecked until a release carrying this + ships. Run it with the project-handle list from legacy laddr + (`codeforphilly.live.k8s.phl.io/projects?format=json`). +- Buzz's live check changed from "never live" to `buzzIdBySlug.has()`. Buzz + slugs are globally unique, so the old comment's concern didn't apply. +- `/people/` takes two 301s (static rewrite, then normalization). + Not folded. +- Person usernames weren't measured. Pulling the legacy people list is a + bulk personal-data download. + ## Follow-ups + +- Tracked as: production spot check after the next release (see Notes).