From 2d58887a15aa9a54b9748c2464bc5b9ae73cf3c8 Mon Sep 17 00:00:00 2001 From: adilallo <39313955+adilallo@users.noreply.github.com> Date: Tue, 21 Apr 2026 07:08:31 -0600 Subject: [PATCH 1/9] Web vitals: prefer external RUM --- .env.example | 7 + CONTRIBUTING.md | 2 +- app/(admin)/monitor/MonitorPageContent.tsx | 168 +++++++++++++++++ app/(admin)/monitor/page.tsx | 158 +--------------- app/api/web-vitals/route.ts | 163 ++++++----------- .../WebVitalsDashboard.container.tsx | 172 +++++++++++------- .../WebVitalsDashboard.types.ts | 7 + .../WebVitalsDashboard.view.tsx | 84 +++++---- docs/guides/backend-roadmap.md | 8 +- lib/server/validation/webVitalsSchema.ts | 15 ++ lib/server/webVitals/localFileStore.ts | 115 ++++++++++++ lib/server/webVitals/mode.ts | 31 ++++ .../en/components/webVitalsDashboard.json | 24 +++ messages/en/index.ts | 4 + messages/en/pages/monitor.json | 46 +++++ tests/unit/webVitalsMode.test.ts | 36 ++++ tests/unit/webVitalsSchema.test.ts | 45 +++++ 17 files changed, 713 insertions(+), 372 deletions(-) create mode 100644 app/(admin)/monitor/MonitorPageContent.tsx create mode 100644 lib/server/validation/webVitalsSchema.ts create mode 100644 lib/server/webVitals/localFileStore.ts create mode 100644 lib/server/webVitals/mode.ts create mode 100644 messages/en/components/webVitalsDashboard.json create mode 100644 messages/en/pages/monitor.json create mode 100644 tests/unit/webVitalsMode.test.ts create mode 100644 tests/unit/webVitalsSchema.test.ts diff --git a/.env.example b/.env.example index 1a818e9..4e6ab5a 100644 --- a/.env.example +++ b/.env.example @@ -13,3 +13,10 @@ SMTP_FROM="Community Rule " # Set to `true` to sync the create-flow draft with `/api/drafts/me` when the user is signed in. NEXT_PUBLIC_ENABLE_BACKEND_SYNC= + +# Web vitals API (CR-80): `external` = structured logs only, no writes under `.next` (default in production). +# `local` = file-based aggregates under `.next/web-vitals` (default in development). Omit to use defaults. +# WEB_VITALS_STORAGE=external + +# Optional: URL shown on /monitor when using external storage (Grafana, Kibana, vendor RUM, etc.). +# NEXT_PUBLIC_RUM_DASHBOARD_URL= diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3231c04..0e46bd5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,7 @@ Use `npx prisma studio` to inspect the database. | GET / POST | `/api/rules` | List or publish rules. | | GET | `/api/templates` | List curated templates. Optional repeatable `facet.=` query params re-rank results (and may include `scores` in the JSON). See [docs/guides/template-recommendation-matrix.md](docs/guides/template-recommendation-matrix.md) §9.1. | | GET | `/api/create-flow/methods` | Facet-aware scores for custom-rule card steps: required `section` (`communication` \| `membership` \| `decisionApproaches` \| `conflictManagement`) and optional `facet.*` params (same facet groups as `/api/templates`). Returns `methods` with match metadata for re-ordering in the wizard. | -| POST / GET | `/api/web-vitals` | Ingest or read aggregated web vitals (file-based store under `.next` today; not ideal for multi-instance — see [docs/guides/backend-roadmap.md](docs/guides/backend-roadmap.md) §7). | +| POST / GET | `/api/web-vitals` | Ingest or read web vitals. **Production default:** `external` — structured logs only (no writes under `.next`; safe for read-only FS). **Development default:** `local` — aggregates under `.next/web-vitals`. Override with `WEB_VITALS_STORAGE`. See [docs/guides/backend-roadmap.md](docs/guides/backend-roadmap.md) §7. | ### Magic-link sign-in diff --git a/app/(admin)/monitor/MonitorPageContent.tsx b/app/(admin)/monitor/MonitorPageContent.tsx new file mode 100644 index 0000000..dd839f9 --- /dev/null +++ b/app/(admin)/monitor/MonitorPageContent.tsx @@ -0,0 +1,168 @@ +"use client"; + +import WebVitalsDashboard from "../../components/sections/WebVitalsDashboard"; +import TopNav from "../../components/navigation/TopNav"; +import Footer from "../../components/navigation/Footer"; +import { useMessages } from "../../contexts/MessagesContext"; + +export default function MonitorPageContent() { + const m = useMessages(); + const p = m.pages.monitor; + + return ( +
+ + +
+
+
+

+ {p.title} +

+

+ {p.description} +

+
+ +
+
+

+ {p.performanceTargets.title} +

+
+
+ + {p.performanceTargets.loadTime} + + + {p.performanceTargets.loadTimeTarget} + +
+
+ + {p.performanceTargets.lcp} + + + {p.performanceTargets.lcpTarget} + +
+
+ + {p.performanceTargets.fid} + + + {p.performanceTargets.fidTarget} + +
+
+ + {p.performanceTargets.cls} + + + {p.performanceTargets.clsTarget} + +
+
+ + {p.performanceTargets.lighthouse} + + + {p.performanceTargets.lighthouseTarget} + +
+
+
+ +
+

+ {p.optimizationStatus.title} +

+
+
+ ✅ + + {p.optimizationStatus.codeSplitting} + +
+
+ ✅ + + {p.optimizationStatus.reactMemo} + +
+
+ ✅ + + {p.optimizationStatus.imageOptimization} + +
+
+ ✅ + + {p.optimizationStatus.fontPreloading} + +
+
+ ✅ + + {p.optimizationStatus.bundleAnalysis} + +
+
+ ✅ + + {p.optimizationStatus.errorBoundaries} + +
+
+
+
+ + + +
+

+ {p.monitoringCommands.title} +

+
+
+

+ {p.monitoringCommands.bundleAnalyze.title} +

+ + {p.monitoringCommands.bundleAnalyze.command} + +
+
+

+ {p.monitoringCommands.e2ePerformance.title} +

+ + {p.monitoringCommands.e2ePerformance.command} + +
+
+

+ {p.monitoringCommands.lhciDesktop.title} +

+ + {p.monitoringCommands.lhciDesktop.command} + +
+
+

+ {p.monitoringCommands.performanceBudget.title} +

+ + {p.monitoringCommands.performanceBudget.command} + +
+
+
+
+
+ +
+
+ ); +} diff --git a/app/(admin)/monitor/page.tsx b/app/(admin)/monitor/page.tsx index 9ba8ff2..fe924de 100644 --- a/app/(admin)/monitor/page.tsx +++ b/app/(admin)/monitor/page.tsx @@ -1,159 +1,5 @@ -import WebVitalsDashboard from "../../components/sections/WebVitalsDashboard"; -import TopNav from "../../components/navigation/TopNav"; -import Footer from "../../components/navigation/Footer"; +import MonitorPageContent from "./MonitorPageContent"; export default function MonitorPage() { - return ( -
- - -
-
-
-

- Performance Monitoring -

-

- Real-time monitoring of Core Web Vitals and performance metrics - for Community Rule 3.0 -

-
- -
-
-

- Performance Targets -

-
-
- - Load Time - - - < 2 seconds - -
-
- - LCP - - - < 2.5s - -
-
- - FID - - - < 100ms - -
-
- - CLS - - < 0.1 -
-
- - Lighthouse Score - - > 90 -
-
-
- -
-

- Optimization Status -

-
-
- ✅ - - Code Splitting & Dynamic Imports - -
-
- ✅ - - React.memo Optimizations - -
-
- ✅ - - Image Optimization - -
-
- ✅ - - Font Preloading - -
-
- ✅ - - Bundle Analysis - -
-
- ✅ - - Error Boundaries - -
-
-
-
- - - -
-

- Monitoring Commands -

-
-
-

- Bundle Analysis -

- - npm run bundle:analyze - -
-
-

- Performance Monitor -

- - npm run performance:monitor - -
-
-

- Web Vitals Tracking -

- - npm run web-vitals:track - -
-
-

- All Monitoring -

- - npm run monitor:all - -
-
-
-
-
- -
-
- ); + return ; } diff --git a/app/api/web-vitals/route.ts b/app/api/web-vitals/route.ts index a1beafe..ea2b1df 100644 --- a/app/api/web-vitals/route.ts +++ b/app/api/web-vitals/route.ts @@ -1,90 +1,71 @@ import { NextRequest, NextResponse } from "next/server"; -import fs from "fs"; -import path from "path"; import { logger } from "../../../lib/logger"; +import { getWebVitalsStorageMode } from "../../../lib/server/webVitals/mode"; +import { + appendLocalWebVital, + readLocalAggregatedMetrics, + type WebVitalData, +} from "../../../lib/server/webVitals/localFileStore"; +import { readLimitedJson } from "../../../lib/server/validation/requestBody"; +import { webVitalIngestSchema } from "../../../lib/server/validation/webVitalsSchema"; +import { jsonFromZodError } from "../../../lib/server/validation/zodHttp"; -const WEB_VITALS_DIR = path.join(process.cwd(), ".next", "web-vitals"); - -interface WebVitalData { - metric: string; - data: { - value: number; - rating: string; - }; - url: string; - userAgent: string; - timestamp: string; - receivedAt: string; +function normalizeTimestamp(raw: string | number): string { + if (typeof raw === "number" && Number.isFinite(raw)) { + return new Date(raw).toISOString(); + } + return new Date(raw).toISOString(); } -interface WebVitalMetrics { - [metric: string]: { - count: number; - average: number; - min: number; - max: number; - goodCount: number; - needsImprovementCount: number; - poorCount: number; - lastUpdated: string; - }; -} - -// Ensure web-vitals directory exists -if (!fs.existsSync(WEB_VITALS_DIR)) { - fs.mkdirSync(WEB_VITALS_DIR, { recursive: true }); +function logExternalIngest(body: WebVitalData): void { + const line = JSON.stringify({ + kind: "web_vital_ingest", + metric: body.metric, + value: body.data.value, + rating: body.data.rating, + url: body.url, + receivedAt: body.receivedAt, + }); + logger.info(line); } export async function POST(request: NextRequest) { try { - const body = await request.json(); - const { metric, data, url, userAgent, timestamp } = body as { - metric: string; - data: { value: number; rating: string }; - url: string; - userAgent: string; - timestamp: string; - }; + const limited = await readLimitedJson(request); + if (limited.ok === false) { + return limited.response; + } + + const parsed = webVitalIngestSchema.safeParse(limited.value); + if (!parsed.success) return jsonFromZodError(parsed.error); + + const body = parsed.data; - // Store the metric data const vitalsData: WebVitalData = { - metric, - data, - url, - userAgent, - timestamp: new Date(timestamp).toISOString(), + metric: body.metric, + data: { + value: body.data.value, + rating: body.data.rating, + }, + url: body.url, + userAgent: body.userAgent, + timestamp: normalizeTimestamp(body.timestamp), receivedAt: new Date().toISOString(), }; - // Save to file (in production, you would save to a database) - const filePath = path.join(WEB_VITALS_DIR, `${metric}.json`); - let existingData: WebVitalData[] = []; + const mode = getWebVitalsStorageMode(); - if (fs.existsSync(filePath)) { - try { - const fileContent = fs.readFileSync(filePath, "utf8"); - existingData = JSON.parse(fileContent) as WebVitalData[]; - } catch (error) { - const err = error as Error; - logger.warn("Could not parse existing vitals data:", err.message); - } + if (mode === "external") { + logExternalIngest(vitalsData); + return NextResponse.json({ success: true, storage: "external" }); } - existingData.push(vitalsData); - - // Keep only last 100 entries per metric - if (existingData.length > 100) { - existingData = existingData.slice(-100); - } - - fs.writeFileSync(filePath, JSON.stringify(existingData, null, 2)); - - // Log for monitoring + appendLocalWebVital(vitalsData); logger.info( - `Web Vital received: ${metric} = ${data.value}ms (${data.rating})`, + `Web Vital received: ${body.metric} = ${body.data.value}ms (${body.data.rating})`, ); - return NextResponse.json({ success: true }); + return NextResponse.json({ success: true, storage: "local" }); } catch (error) { logger.error("Error processing web vital:", error); return NextResponse.json( @@ -96,51 +77,17 @@ export async function POST(request: NextRequest) { export async function GET() { try { - const metrics: WebVitalMetrics = {}; + const mode = getWebVitalsStorageMode(); - if (fs.existsSync(WEB_VITALS_DIR)) { - const files = fs.readdirSync(WEB_VITALS_DIR); - - files.forEach((file) => { - if (file.endsWith(".json")) { - const metric = file.replace(".json", ""); - const fileContent = fs.readFileSync( - path.join(WEB_VITALS_DIR, file), - "utf8", - ); - const data = JSON.parse(fileContent) as WebVitalData[]; - - if (data.length > 0) { - const values = data - .map((d) => d.data.value) - .filter((v) => v !== undefined); - const ratings = data - .map((d) => d.data.rating) - .filter((r) => r !== undefined); - - metrics[metric] = { - count: data.length, - average: - values.length > 0 - ? Math.round( - values.reduce((a, b) => a + b, 0) / values.length, - ) - : 0, - min: values.length > 0 ? Math.min(...values) : 0, - max: values.length > 0 ? Math.max(...values) : 0, - goodCount: ratings.filter((r) => r === "good").length, - needsImprovementCount: ratings.filter( - (r) => r === "needs-improvement", - ).length, - poorCount: ratings.filter((r) => r === "poor").length, - lastUpdated: data[data.length - 1]?.receivedAt || "", - }; - } - } + if (mode === "external") { + return NextResponse.json({ + metrics: {}, + storage: "external" as const, }); } - return NextResponse.json({ metrics }); + const metrics = readLocalAggregatedMetrics(); + return NextResponse.json({ metrics, storage: "local" as const }); } catch (error) { logger.error("Error fetching web vitals:", error); return NextResponse.json( diff --git a/app/components/sections/WebVitalsDashboard/WebVitalsDashboard.container.tsx b/app/components/sections/WebVitalsDashboard/WebVitalsDashboard.container.tsx index 8f2d7ce..05767a1 100644 --- a/app/components/sections/WebVitalsDashboard/WebVitalsDashboard.container.tsx +++ b/app/components/sections/WebVitalsDashboard/WebVitalsDashboard.container.tsx @@ -1,6 +1,7 @@ "use client"; import { memo, useEffect, useState } from "react"; +import { useMessages } from "../../../contexts/MessagesContext"; import { logger } from "../../../../lib/logger"; import WebVitalsDashboardView from "./WebVitalsDashboard.view"; import type { Metrics, Vitals, VitalData } from "./WebVitalsDashboard.types"; @@ -18,17 +19,55 @@ const createInitialVitals = (): Vitals => ({ ttfb: createInitialVital(), }); +function reportWebVitalToApi( + metric: keyof Vitals, + value: number, + rating: VitalData["rating"], +): void { + if (typeof window === "undefined") return; + if (rating === "unknown") return; + + const body = { + metric, + data: { value, rating }, + url: window.location.href, + userAgent: navigator.userAgent, + timestamp: new Date().toISOString(), + }; + + void fetch("/api/web-vitals", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body), + }).catch((err: unknown) => { + logger.error("Web vitals ingest failed:", err); + }); +} + const WebVitalsDashboardContainer = memo(() => { + const m = useMessages(); + const copy = m.webVitalsDashboard; const [vitals, setVitals] = useState(createInitialVitals); const [metrics, setMetrics] = useState({}); const [loading, setLoading] = useState(true); + const [storage, setStorage] = useState<"external" | "local">("local"); + + const rumDashboardUrl = + typeof process.env.NEXT_PUBLIC_RUM_DASHBOARD_URL === "string" && + process.env.NEXT_PUBLIC_RUM_DASHBOARD_URL.trim() !== "" + ? process.env.NEXT_PUBLIC_RUM_DASHBOARD_URL.trim() + : null; useEffect(() => { const fetchVitals = async () => { try { const response = await fetch("/api/web-vitals"); - const data = (await response.json()) as { metrics?: Metrics }; + const data = (await response.json()) as { + metrics?: Metrics; + storage?: "external" | "local"; + }; setMetrics(data.metrics || {}); + setStorage(data.storage === "external" ? "external" : "local"); } catch (error) { logger.error("Error fetching web vitals:", error); } finally { @@ -39,77 +78,71 @@ const WebVitalsDashboardContainer = memo(() => { fetchVitals(); if (typeof window !== "undefined") { - import("web-vitals").then((webVitals) => { - // web-vitals v4 typings don't expose legacy get* names the same way; runtime bundle still provides them for this dashboard. - const { getCLS, getFID, getFCP, getLCP, getTTFB } = - webVitals as unknown as { - getCLS: ( - _fn: (_m: { value: number; rating: string }) => void, - ) => void; - getFID: ( - _fn: (_m: { value: number; rating: string }) => void, - ) => void; - getFCP: ( - _fn: (_m: { value: number; rating: string }) => void, - ) => void; - getLCP: ( - _fn: (_m: { value: number; rating: string }) => void, - ) => void; - getTTFB: ( - _fn: (_m: { value: number; rating: string }) => void, - ) => void; - }; + // web-vitals v4+ exposes onLCP / onCLS / … — legacy getLCP was removed. + import("web-vitals").then( + ({ onCLS, onFID, onFCP, onLCP, onTTFB }) => { + onLCP((metric) => { + const rating = metric.rating as VitalData["rating"]; + setVitals((prev) => ({ + ...prev, + lcp: { + value: Math.round(metric.value), + rating, + }, + })); + reportWebVitalToApi("lcp", Math.round(metric.value), rating); + }); - getLCP((metric: { value: number; rating: VitalData["rating"] }) => { - setVitals((prev) => ({ - ...prev, - lcp: { - value: Math.round(metric.value), - rating: metric.rating, - }, - })); - }); + onFID((metric) => { + const rating = metric.rating as VitalData["rating"]; + setVitals((prev) => ({ + ...prev, + fid: { + value: Math.round(metric.value), + rating, + }, + })); + reportWebVitalToApi("fid", Math.round(metric.value), rating); + }); - getFID((metric: { value: number; rating: VitalData["rating"] }) => { - setVitals((prev) => ({ - ...prev, - fid: { - value: Math.round(metric.value), - rating: metric.rating, - }, - })); - }); + onCLS((metric) => { + const rounded = Math.round(metric.value * 1000) / 1000; + const rating = metric.rating as VitalData["rating"]; + setVitals((prev) => ({ + ...prev, + cls: { + value: rounded, + rating, + }, + })); + reportWebVitalToApi("cls", rounded, rating); + }); - getCLS((metric: { value: number; rating: VitalData["rating"] }) => { - setVitals((prev) => ({ - ...prev, - cls: { - value: Math.round(metric.value * 1000) / 1000, - rating: metric.rating, - }, - })); - }); + onFCP((metric) => { + const rating = metric.rating as VitalData["rating"]; + setVitals((prev) => ({ + ...prev, + fcp: { + value: Math.round(metric.value), + rating, + }, + })); + reportWebVitalToApi("fcp", Math.round(metric.value), rating); + }); - getFCP((metric: { value: number; rating: VitalData["rating"] }) => { - setVitals((prev) => ({ - ...prev, - fcp: { - value: Math.round(metric.value), - rating: metric.rating, - }, - })); - }); - - getTTFB((metric: { value: number; rating: VitalData["rating"] }) => { - setVitals((prev) => ({ - ...prev, - ttfb: { - value: Math.round(metric.value), - rating: metric.rating, - }, - })); - }); - }); + onTTFB((metric) => { + const rating = metric.rating as VitalData["rating"]; + setVitals((prev) => ({ + ...prev, + ttfb: { + value: Math.round(metric.value), + rating, + }, + })); + reportWebVitalToApi("ttfb", Math.round(metric.value), rating); + }); + }, + ); } }, []); @@ -118,6 +151,9 @@ const WebVitalsDashboardContainer = memo(() => { vitals={vitals} metrics={metrics} loading={loading} + storage={storage} + copy={copy} + rumDashboardUrl={rumDashboardUrl} /> ); }); diff --git a/app/components/sections/WebVitalsDashboard/WebVitalsDashboard.types.ts b/app/components/sections/WebVitalsDashboard/WebVitalsDashboard.types.ts index 945bb7f..bb6deeb 100644 --- a/app/components/sections/WebVitalsDashboard/WebVitalsDashboard.types.ts +++ b/app/components/sections/WebVitalsDashboard/WebVitalsDashboard.types.ts @@ -1,3 +1,5 @@ +import type messages from "../../../../messages/en/index"; + export interface VitalData { value: number; rating: "good" | "needs-improvement" | "poor" | "unknown"; @@ -26,8 +28,13 @@ export interface Metrics { [key: string]: MetricData; } +export type WebVitalsDashboardCopy = typeof messages.webVitalsDashboard; + export interface WebVitalsDashboardViewProps { vitals: Vitals; metrics: Metrics; loading: boolean; + storage: "external" | "local"; + copy: WebVitalsDashboardCopy; + rumDashboardUrl: string | null; } diff --git a/app/components/sections/WebVitalsDashboard/WebVitalsDashboard.view.tsx b/app/components/sections/WebVitalsDashboard/WebVitalsDashboard.view.tsx index ec1d073..593a915 100644 --- a/app/components/sections/WebVitalsDashboard/WebVitalsDashboard.view.tsx +++ b/app/components/sections/WebVitalsDashboard/WebVitalsDashboard.view.tsx @@ -26,17 +26,20 @@ const getRatingIcon = (rating: string): string => { } }; -const formatValue = (metric: string, value: number): string => { +function formatValue(metric: string, value: number): string { if (metric === "cls") { return value.toFixed(3); } return `${value}ms`; -}; +} function WebVitalsDashboardView({ vitals, metrics, loading, + storage, + copy, + rumDashboardUrl, }: WebVitalsDashboardViewProps) { if (loading) { return ( @@ -59,9 +62,31 @@ function WebVitalsDashboardView({ return (

- Web Vitals Dashboard + {copy.title}

+ {storage === "external" && ( +
+

+ {copy.externalNoticeTitle} +

+

{copy.externalNoticeBody}

+ {rumDashboardUrl ? ( + + {copy.externalDashboardLinkLabel} + + ) : null} +
+ )} +
{Object.entries(vitals).map(([metric, data]) => (
- Value: {formatValue(metric, data.value)} + {copy.valueLabel}: {formatValue(metric, data.value)}
- Rating: {data.rating.replace("-", " ")} + {copy.ratingLabel}: {data.rating.replace("-", " ")}
))}
- {/* Historical Metrics */} {Object.keys(metrics).length > 0 && (

- Historical Metrics + {copy.historicalMetricsTitle}

{Object.entries(metrics).map(([metric, data]) => ( @@ -98,20 +122,26 @@ function WebVitalsDashboardView({ >

{metric.toUpperCase()}

-
Count: {data.count}
-
Average: {formatValue(metric, data.average)}
- Range: {formatValue(metric, data.min)} -{" "} + {copy.countLabel}: {data.count} +
+
+ {copy.averageLabel}: {formatValue(metric, data.average)} +
+
+ {copy.rangeLabel}: {formatValue(metric, data.min)} -{" "} {formatValue(metric, data.max)}
- Good: {data.goodCount} + {copy.goodLabel}: {data.goodCount} - Needs Improvement: {data.needsImprovementCount} + {copy.needsImprovementLabel}: {data.needsImprovementCount} + + + {copy.poorLabel}: {data.poorCount} - Poor: {data.poorCount}
@@ -120,32 +150,16 @@ function WebVitalsDashboardView({
)} - {/* Performance Guidelines */}

- Performance Guidelines + {copy.performanceGuidelinesTitle}

    -
  • - • LCP: Good < 2.5s, Needs Improvement 2.5-4s, - Poor > 4s -
    • -
  • - • FID: Good < 100ms, Needs Improvement - 100-300ms, Poor > 300ms -
    • -
  • - • CLS: Good < 0.1, Needs Improvement 0.1-0.25, - Poor > 0.25 -
    • -
  • - • FCP: Good < 1.8s, Needs Improvement 1.8-3s, - Poor > 3s -
    • -
  • - • TTFB: Good < 800ms, Needs Improvement - 800-1800ms, Poor > 1800ms -
    • +
  • • {copy.guidelines.lcp}
    • +
  • • {copy.guidelines.fid}
    • +
  • • {copy.guidelines.cls}
    • +
  • • {copy.guidelines.fcp}
    • +
  • • {copy.guidelines.ttfb}
diff --git a/docs/guides/backend-roadmap.md b/docs/guides/backend-roadmap.md index 3c3ec32..d5fb602 100644 --- a/docs/guides/backend-roadmap.md +++ b/docs/guides/backend-roadmap.md @@ -10,7 +10,7 @@ Temporary working notes for building the backend. Safe to delete once the stack - **PostgreSQL + Prisma**: schema and migrations under `prisma/`; product APIs under `app/api/*` (health, auth/magic-link, session, drafts, rules, templates, web-vitals). - **Server modules** in `lib/server/` (db, session, mail, rate limiting, etc.). - **Create flow:** **Anonymous** users mirror in-progress state to **`create-flow-anonymous`** in `localStorage`; **Exit** opens the save-progress magic-link modal; after verify, [`PostLoginDraftTransfer`](app/(app)/create/PostLoginDraftTransfer.tsx) can **PUT** `/api/drafts/me` when **`NEXT_PUBLIC_ENABLE_BACKEND_SYNC=true`**. **Signed-in** users get a **fresh** in-memory session per “Create rule” entry, but with sync on the layout may **hydrate** from **`GET /api/drafts/me`** via [`SignedInDraftHydration`](app/(app)/create/SignedInDraftHydration.tsx); **Save & Exit** (from `community-structure` onward) **PUT**s when sync is on. **Log in** from the marketing header uses the global modal ([`AuthModalProvider`](app/contexts/AuthModalContext.tsx)); **`/login`** remains for verify errors and deep links. **Step order and URLs:** [`docs/create-flow.md`](docs/create-flow.md) and [`app/(app)/create/utils/flowSteps.ts`](app/(app)/create/utils/flowSteps.ts). -- **Web vitals** [`app/api/web-vitals/route.ts`](app/api/web-vitals/route.ts) still use **file-based** storage under `.next` (not suitable for multi-instance production). +- **Web vitals** [`app/api/web-vitals/route.ts`](app/api/web-vitals/route.ts): **production default** is **`external`** (structured logs; no `.next` writes). **`local`** file-based mode remains for development (`WEB_VITALS_STORAGE`). - **CI:** [`.gitea/workflows/ci.yaml`](.gitea/workflows/ci.yaml) (build, test, lint, `prisma validate`); no in-repo production deploy definition. ### HTTP API (implemented in repo) @@ -28,7 +28,7 @@ Mirrors [CONTRIBUTING.md](../CONTRIBUTING.md) **API routes** table (including `/ | GET / POST | `/api/rules` | List or publish rules | | GET | `/api/templates` | List curated templates; optional `facet.*` re-ranks (see [template-recommendation-matrix.md](template-recommendation-matrix.md)) | | GET | `/api/create-flow/methods` | Facet scores for wizard method lists (`section` + optional `facet.*`) | -| POST / GET | `/api/web-vitals` | Web vitals ingest / aggregate (file-based under `.next` today; production path §7) | +| POST / GET | `/api/web-vitals` | Web vitals ingest / read aggregates (`external` default in production — logs only; `local` under `.next` in dev — see §7) | **Product sign-in** uses **magic link** (`/api/auth/magic-link/*`). @@ -136,7 +136,7 @@ Match the current API behavior; tighten as product evolves: **Operator / local (always manual):** Steps 1–4 — env file, Docker Postgres, `npm ci`, `prisma migrate dev`, `npm run dev`. -**Backend behavior already in the repo:** Steps **5–10** match implemented Route Handlers and middleware (`lib/server/*`). **Step 11** (web vitals) is **not** production-ready (files under `.next`); treat as follow-up work aligned with §7. +**Backend behavior already in the repo:** Steps **5–10** match implemented Route Handlers and middleware (`lib/server/*`). **Step 11** (web vitals): production defaults to **`external`** (no `.next` writes); optional vendor RUM or DB persistence remains a deliberate ops choice per §7. **Product / frontend still open (not only “backend exists”):** Sign-in UI, wiring publish from the create flow, template seed + UI consumption (flat list first), **canon create-flow alignment** (Ticket 17 / [CR-89](https://linear.app/community-rule/issue/CR-89/product-canon-custom-create-rule-wizard-routes-resume-progress-repo) — progress bar, resume URL, `[step]` cleanup; spec in [`docs/create-flow.md`](create-flow.md)), **spreadsheet-driven template recommendations** (Ticket 16 / [CR-88](https://linear.app/community-rule/issue/CR-88/backend-template-recommendation-matrix-xlsx-sheets-ingestion) — after v1 templates), **profile / my rules dashboard** (Ticket 15)—see §12 and [docs/backend-linear-tickets.md](backend-linear-tickets.md). @@ -182,7 +182,7 @@ npm run dev **Step 10.** **Frontend draft sync:** Set `NEXT_PUBLIC_ENABLE_BACKEND_SYNC=true` in `.env` so **Save & Exit** and **post-login anonymous → account transfer** can **PUT** `/api/drafts/me`. Without sync, drafts are **not** written to the server (anonymous progress still lives in `localStorage` only). -**Step 11.** **Web vitals:** Move off `.next` files—**prefer an external analytics or logging pipeline** (see §7). Use Postgres for vitals only as a deliberate ops choice. +**Step 11.** **Web vitals:** Production uses **`external`** storage (structured logs). Add a browser RUM SDK or Postgres-backed vitals only as a deliberate ops choice (see §7). --- diff --git a/lib/server/validation/webVitalsSchema.ts b/lib/server/validation/webVitalsSchema.ts new file mode 100644 index 0000000..34a4f11 --- /dev/null +++ b/lib/server/validation/webVitalsSchema.ts @@ -0,0 +1,15 @@ +import { z } from "zod"; + +/** POST /api/web-vitals — browser ingest payload */ +export const webVitalIngestSchema = z.object({ + metric: z.string().min(1).max(64), + data: z.object({ + value: z.number().finite(), + rating: z.string().min(1).max(32), + }), + url: z.string().min(1).max(8192), + userAgent: z.string().max(512).optional().default(""), + timestamp: z.union([z.string(), z.number()]), +}); + +export type WebVitalIngestInput = z.infer; diff --git a/lib/server/webVitals/localFileStore.ts b/lib/server/webVitals/localFileStore.ts new file mode 100644 index 0000000..26352f2 --- /dev/null +++ b/lib/server/webVitals/localFileStore.ts @@ -0,0 +1,115 @@ +import fs from "fs"; +import path from "path"; +import { logger } from "../../logger"; + +const WEB_VITALS_DIR = path.join(process.cwd(), ".next", "web-vitals"); + +export interface WebVitalData { + metric: string; + data: { + value: number; + rating: string; + }; + url: string; + userAgent: string; + timestamp: string; + receivedAt: string; +} + +export interface WebVitalMetrics { + [metric: string]: { + count: number; + average: number; + min: number; + max: number; + goodCount: number; + needsImprovementCount: number; + poorCount: number; + lastUpdated: string; + }; +} + +function ensureWebVitalsDir(): void { + if (!fs.existsSync(WEB_VITALS_DIR)) { + fs.mkdirSync(WEB_VITALS_DIR, { recursive: true }); + } +} + +export function appendLocalWebVital(vitalsData: WebVitalData): void { + ensureWebVitalsDir(); + const filePath = path.join(WEB_VITALS_DIR, `${vitalsData.metric}.json`); + let existingData: WebVitalData[] = []; + + if (fs.existsSync(filePath)) { + try { + const fileContent = fs.readFileSync(filePath, "utf8"); + existingData = JSON.parse(fileContent) as WebVitalData[]; + } catch (error) { + const err = error as Error; + logger.warn("Could not parse existing vitals data:", err.message); + } + } + + existingData.push(vitalsData); + + if (existingData.length > 100) { + existingData = existingData.slice(-100); + } + + fs.writeFileSync(filePath, JSON.stringify(existingData, null, 2)); +} + +export function readLocalAggregatedMetrics(): WebVitalMetrics { + const metrics: WebVitalMetrics = {}; + + if (!fs.existsSync(WEB_VITALS_DIR)) { + return metrics; + } + + const files = fs.readdirSync(WEB_VITALS_DIR); + + files.forEach((file) => { + if (!file.endsWith(".json")) return; + const metric = file.replace(".json", ""); + let data: WebVitalData[]; + try { + const fileContent = fs.readFileSync( + path.join(WEB_VITALS_DIR, file), + "utf8", + ); + data = JSON.parse(fileContent) as WebVitalData[]; + } catch (error) { + logger.warn( + `Skipping corrupt web vitals file ${file}:`, + (error as Error).message, + ); + return; + } + + if (data.length === 0) return; + + const values = data + .map((d) => d.data.value) + .filter((v) => v !== undefined); + const ratings = data + .map((d) => d.data.rating) + .filter((r) => r !== undefined); + + metrics[metric] = { + count: data.length, + average: + values.length > 0 + ? Math.round(values.reduce((a, b) => a + b, 0) / values.length) + : 0, + min: values.length > 0 ? Math.min(...values) : 0, + max: values.length > 0 ? Math.max(...values) : 0, + goodCount: ratings.filter((r) => r === "good").length, + needsImprovementCount: ratings.filter((r) => r === "needs-improvement") + .length, + poorCount: ratings.filter((r) => r === "poor").length, + lastUpdated: data[data.length - 1]?.receivedAt || "", + }; + }); + + return metrics; +} diff --git a/lib/server/webVitals/mode.ts b/lib/server/webVitals/mode.ts new file mode 100644 index 0000000..1ab50be --- /dev/null +++ b/lib/server/webVitals/mode.ts @@ -0,0 +1,31 @@ +/** + * Web vitals persistence mode (CR-80). Default: external in production, local in dev. + * Does not require a specific observability vendor — ops can pipe structured logs to any stack. + */ +export type WebVitalsStorageMode = "external" | "local"; + +const VALID: WebVitalsStorageMode[] = ["external", "local"]; + +function normalizeEnv( + raw: string | undefined, +): WebVitalsStorageMode | undefined { + const v = raw?.trim().toLowerCase(); + if (v === "external" || v === "local") return v; + if (v === "database") { + // Reserved for Ticket 9 option C — not implemented yet; safe default. + return "external"; + } + return undefined; +} + +/** + * Resolves storage mode from `WEB_VITALS_STORAGE` or defaults: + * - `production` → `external` (no `.next` writes; ingest logs only) + * - otherwise → `local` (file-based under `.next/web-vitals` for dev/admin) + */ +export function getWebVitalsStorageMode(): WebVitalsStorageMode { + const fromEnv = normalizeEnv(process.env.WEB_VITALS_STORAGE); + if (fromEnv && VALID.includes(fromEnv)) return fromEnv; + + return process.env.NODE_ENV === "production" ? "external" : "local"; +} diff --git a/messages/en/components/webVitalsDashboard.json b/messages/en/components/webVitalsDashboard.json new file mode 100644 index 0000000..d93b589 --- /dev/null +++ b/messages/en/components/webVitalsDashboard.json @@ -0,0 +1,24 @@ +{ + "_comment": "Admin Web Vitals dashboard copy", + "title": "Web Vitals Dashboard", + "historicalMetricsTitle": "Historical Metrics", + "performanceGuidelinesTitle": "Performance Guidelines", + "valueLabel": "Value", + "ratingLabel": "Rating", + "countLabel": "Count", + "averageLabel": "Average", + "rangeLabel": "Range", + "goodLabel": "Good", + "needsImprovementLabel": "Needs Improvement", + "poorLabel": "Poor", + "externalNoticeTitle": "Server-side aggregates", + "externalNoticeBody": "Production uses external storage for web vitals. Historical totals are not kept in this app; use your log pipeline or metrics dashboard. Live values below still reflect this browser session.", + "externalDashboardLinkLabel": "Open metrics dashboard", + "guidelines": { + "lcp": "LCP: Good < 2.5s, Needs Improvement 2.5–4s, Poor > 4s", + "fid": "FID: Good < 100ms, Needs Improvement 100–300ms, Poor > 300ms", + "cls": "CLS: Good < 0.1, Needs Improvement 0.1–0.25, Poor > 0.25", + "fcp": "FCP: Good < 1.8s, Needs Improvement 1.8–3s, Poor > 3s", + "ttfb": "TTFB: Good < 800ms, Needs Improvement 800–1800ms, Poor > 1800ms" + } +} diff --git a/messages/en/index.ts b/messages/en/index.ts index 2a44d79..0c54a8b 100644 --- a/messages/en/index.ts +++ b/messages/en/index.ts @@ -11,9 +11,11 @@ import menuBar from "./components/menuBar.json"; import quoteBlock from "./components/quoteBlock.json"; import ruleCard from "./components/ruleCard.json"; import ruleStack from "./components/ruleStack.json"; +import webVitalsDashboard from "./components/webVitalsDashboard.json"; import home from "./pages/home.json"; import templates from "./pages/templates.json"; import learn from "./pages/learn.json"; +import monitor from "./pages/monitor.json"; import login from "./pages/login.json"; import profile from "./pages/profile.json"; import navigation from "./navigation.json"; @@ -62,10 +64,12 @@ export default { quoteBlock, ruleCard, ruleStack, + webVitalsDashboard, pages: { home, templates, learn, + monitor, login, profile, }, diff --git a/messages/en/pages/monitor.json b/messages/en/pages/monitor.json new file mode 100644 index 0000000..5508bb6 --- /dev/null +++ b/messages/en/pages/monitor.json @@ -0,0 +1,46 @@ +{ + "_comment": "Admin /monitor performance page", + "title": "Performance Monitoring", + "description": "Real-time monitoring of Core Web Vitals and performance metrics for Community Rule 3.0", + "performanceTargets": { + "title": "Performance Targets", + "loadTime": "Load Time", + "loadTimeTarget": "< 2 seconds", + "lcp": "LCP", + "lcpTarget": "< 2.5s", + "fid": "FID", + "fidTarget": "< 100ms", + "cls": "CLS", + "clsTarget": "< 0.1", + "lighthouse": "Lighthouse Score", + "lighthouseTarget": "> 90" + }, + "optimizationStatus": { + "title": "Optimization Status", + "codeSplitting": "Code Splitting & Dynamic Imports", + "reactMemo": "React.memo Optimizations", + "imageOptimization": "Image Optimization", + "fontPreloading": "Font Preloading", + "bundleAnalysis": "Bundle Analysis", + "errorBoundaries": "Error Boundaries" + }, + "monitoringCommands": { + "title": "Monitoring Commands", + "bundleAnalyze": { + "title": "Bundle analysis", + "command": "npm run bundle:analyze" + }, + "e2ePerformance": { + "title": "E2E performance (Core Web Vitals)", + "command": "npm run e2e:performance" + }, + "lhciDesktop": { + "title": "Lighthouse CI (desktop preset)", + "command": "npm run lhci:desktop" + }, + "performanceBudget": { + "title": "Lighthouse CI with performance budgets", + "command": "npm run performance:budget" + } + } +} diff --git a/tests/unit/webVitalsMode.test.ts b/tests/unit/webVitalsMode.test.ts new file mode 100644 index 0000000..656a4d5 --- /dev/null +++ b/tests/unit/webVitalsMode.test.ts @@ -0,0 +1,36 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { getWebVitalsStorageMode } from "../../lib/server/webVitals/mode"; + +describe("getWebVitalsStorageMode", () => { + afterEach(() => { + vi.unstubAllEnvs(); + }); + + it("returns external when WEB_VITALS_STORAGE=external", () => { + vi.stubEnv("WEB_VITALS_STORAGE", "external"); + vi.stubEnv("NODE_ENV", "development"); + expect(getWebVitalsStorageMode()).toBe("external"); + }); + + it("returns local when WEB_VITALS_STORAGE=local", () => { + vi.stubEnv("WEB_VITALS_STORAGE", "local"); + vi.stubEnv("NODE_ENV", "production"); + expect(getWebVitalsStorageMode()).toBe("local"); + }); + + it("defaults to external in production when unset", () => { + vi.stubEnv("NODE_ENV", "production"); + expect(getWebVitalsStorageMode()).toBe("external"); + }); + + it("defaults to local in development when unset", () => { + vi.stubEnv("NODE_ENV", "development"); + expect(getWebVitalsStorageMode()).toBe("local"); + }); + + it("maps database to external until implemented", () => { + vi.stubEnv("WEB_VITALS_STORAGE", "database"); + vi.stubEnv("NODE_ENV", "development"); + expect(getWebVitalsStorageMode()).toBe("external"); + }); +}); diff --git a/tests/unit/webVitalsSchema.test.ts b/tests/unit/webVitalsSchema.test.ts new file mode 100644 index 0000000..f385e46 --- /dev/null +++ b/tests/unit/webVitalsSchema.test.ts @@ -0,0 +1,45 @@ +import { describe, expect, it } from "vitest"; +import { webVitalIngestSchema } from "../../lib/server/validation/webVitalsSchema"; + +describe("webVitalIngestSchema", () => { + it("accepts a valid payload", () => { + const parsed = webVitalIngestSchema.safeParse({ + metric: "lcp", + data: { value: 1200, rating: "good" }, + url: "https://example.com/path", + userAgent: "jest", + timestamp: "2026-01-01T00:00:00.000Z", + }); + expect(parsed.success).toBe(true); + }); + + it("accepts numeric timestamp", () => { + const parsed = webVitalIngestSchema.safeParse({ + metric: "cls", + data: { value: 0.05, rating: "good" }, + url: "https://example.com/", + timestamp: 1_700_000_000_000, + }); + expect(parsed.success).toBe(true); + }); + + it("rejects empty metric", () => { + const parsed = webVitalIngestSchema.safeParse({ + metric: "", + data: { value: 1, rating: "good" }, + url: "https://example.com/", + timestamp: "2026-01-01T00:00:00.000Z", + }); + expect(parsed.success).toBe(false); + }); + + it("rejects empty url", () => { + const parsed = webVitalIngestSchema.safeParse({ + metric: "lcp", + data: { value: 1, rating: "good" }, + url: "", + timestamp: "2026-01-01T00:00:00.000Z", + }); + expect(parsed.success).toBe(false); + }); +}); From 0e7a57052bd157774c64bc96ad7b14e1e5294f60 Mon Sep 17 00:00:00 2001 From: adilallo <39313955+adilallo@users.noreply.github.com> Date: Tue, 21 Apr 2026 22:35:49 -0600 Subject: [PATCH 2/9] Public rule and detail page added --- app/(marketing)/rules/[id]/page.tsx | 72 ++++++++++++++++++++++++ app/api/rules/[id]/route.ts | 21 +++++++ lib/server/publishedRules.ts | 48 ++++++++++++++++ tests/unit/rulesByIdRoute.test.ts | 85 +++++++++++++++++++++++++++++ 4 files changed, 226 insertions(+) create mode 100644 app/(marketing)/rules/[id]/page.tsx create mode 100644 app/api/rules/[id]/route.ts create mode 100644 lib/server/publishedRules.ts create mode 100644 tests/unit/rulesByIdRoute.test.ts diff --git a/app/(marketing)/rules/[id]/page.tsx b/app/(marketing)/rules/[id]/page.tsx new file mode 100644 index 0000000..e8f4f62 --- /dev/null +++ b/app/(marketing)/rules/[id]/page.tsx @@ -0,0 +1,72 @@ +import type { Metadata } from "next"; +import { notFound } from "next/navigation"; +import { getPublicPublishedRuleById } from "../../../../lib/server/publishedRules"; +import { parseDocumentSectionsForDisplay } from "../../../../lib/create/buildPublishPayload"; +import CommunityRuleDocument from "../../../components/sections/CommunityRuleDocument"; +import HeaderLockup from "../../../components/type/HeaderLockup"; + +interface PageProps { + params: Promise<{ id: string }>; +} + +export async function generateMetadata({ + params, +}: PageProps): Promise { + const { id } = await params; + const rule = await getPublicPublishedRuleById(id); + if (!rule) { + return { + title: "Rule Not Found", + description: "The requested CommunityRule could not be found.", + }; + } + const description = + typeof rule.summary === "string" && rule.summary.trim().length > 0 + ? rule.summary + : undefined; + return { + title: rule.title, + description, + openGraph: { + title: rule.title, + description, + type: "article", + url: `https://communityrule.com/rules/${rule.id}`, + siteName: "CommunityRule", + }, + twitter: { + card: "summary_large_image", + title: rule.title, + description, + }, + }; +} + +export default async function PublicRuleDetailPage({ params }: PageProps) { + const { id } = await params; + const rule = await getPublicPublishedRuleById(id); + if (!rule) { + notFound(); + } + + const sections = parseDocumentSectionsForDisplay(rule.document); + const description = + typeof rule.summary === "string" && rule.summary.trim().length > 0 + ? rule.summary + : undefined; + + return ( +
+
+ + +
+
+ ); +} diff --git a/app/api/rules/[id]/route.ts b/app/api/rules/[id]/route.ts new file mode 100644 index 0000000..9b7330e --- /dev/null +++ b/app/api/rules/[id]/route.ts @@ -0,0 +1,21 @@ +import { NextResponse } from "next/server"; +import { isDatabaseConfigured } from "../../../../lib/server/env"; +import { dbUnavailable } from "../../../../lib/server/responses"; +import { getPublicPublishedRuleById } from "../../../../lib/server/publishedRules"; + +type RouteContext = { params: Promise<{ id: string }> }; + +export async function GET(_request: Request, context: RouteContext) { + if (!isDatabaseConfigured()) { + return dbUnavailable(); + } + + const { id } = await context.params; + + const rule = await getPublicPublishedRuleById(id); + if (!rule) { + return NextResponse.json({ error: "Not found" }, { status: 404 }); + } + + return NextResponse.json({ rule }); +} diff --git a/lib/server/publishedRules.ts b/lib/server/publishedRules.ts new file mode 100644 index 0000000..e458a64 --- /dev/null +++ b/lib/server/publishedRules.ts @@ -0,0 +1,48 @@ +import { prisma } from "./db"; +import { isDatabaseConfigured } from "./env"; + +/** + * Public fields safe to expose via the unauthenticated rule detail surfaces + * (`GET /api/rules/[id]` and `/rules/[id]`). `userId` is intentionally omitted. + */ +const PUBLISHED_RULE_PUBLIC_SELECT = { + id: true, + title: true, + summary: true, + document: true, + createdAt: true, + updatedAt: true, +} as const; + +export type PublicPublishedRule = { + id: string; + title: string; + summary: string | null; + document: unknown; + createdAt: Date; + updatedAt: Date; +}; + +/** + * Fetch a single published rule by id for public read surfaces. + * + * Returns `null` when the database is not configured, the id does not match + * any row, or the query throws — callers render a 404 in all missing cases + * and are expected to surface the "DB not configured" state separately if + * they care about distinguishing it (the API route does; the page does not). + */ +export async function getPublicPublishedRuleById( + id: string, +): Promise { + if (!isDatabaseConfigured()) return null; + if (typeof id !== "string" || id.trim() === "") return null; + try { + const rule = await prisma.publishedRule.findUnique({ + where: { id }, + select: PUBLISHED_RULE_PUBLIC_SELECT, + }); + return rule; + } catch { + return null; + } +} diff --git a/tests/unit/rulesByIdRoute.test.ts b/tests/unit/rulesByIdRoute.test.ts new file mode 100644 index 0000000..5d415c7 --- /dev/null +++ b/tests/unit/rulesByIdRoute.test.ts @@ -0,0 +1,85 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +const isDatabaseConfiguredMock = vi.fn(); +const findUniqueMock = vi.fn(); + +vi.mock("../../lib/server/env", () => ({ + isDatabaseConfigured: () => isDatabaseConfiguredMock(), +})); + +vi.mock("../../lib/server/db", () => ({ + prisma: { + publishedRule: { + findUnique: (...args: unknown[]) => findUniqueMock(...args), + }, + }, +})); + +import { GET } from "../../app/api/rules/[id]/route"; + +function makeContext(id: string) { + return { params: Promise.resolve({ id }) }; +} + +beforeEach(() => { + isDatabaseConfiguredMock.mockReset(); + findUniqueMock.mockReset(); +}); + +describe("GET /api/rules/[id]", () => { + it("returns 503 when the database is not configured", async () => { + isDatabaseConfiguredMock.mockReturnValue(false); + const res = await GET(new Request("https://x.test/api/rules/abc"), makeContext("abc")); + expect(res.status).toBe(503); + expect(findUniqueMock).not.toHaveBeenCalled(); + }); + + it("returns 404 when no published rule matches the id", async () => { + isDatabaseConfiguredMock.mockReturnValue(true); + findUniqueMock.mockResolvedValueOnce(null); + const res = await GET( + new Request("https://x.test/api/rules/missing"), + makeContext("missing"), + ); + expect(res.status).toBe(404); + const body = (await res.json()) as { error: string }; + expect(typeof body.error).toBe("string"); + expect(findUniqueMock).toHaveBeenCalledWith( + expect.objectContaining({ where: { id: "missing" } }), + ); + }); + + it("returns 404 when the query throws (swallowed by helper)", async () => { + isDatabaseConfiguredMock.mockReturnValue(true); + findUniqueMock.mockRejectedValueOnce(new Error("db down")); + const res = await GET( + new Request("https://x.test/api/rules/broken"), + makeContext("broken"), + ); + expect(res.status).toBe(404); + }); + + it("returns 200 with { rule } when a published rule exists", async () => { + isDatabaseConfiguredMock.mockReturnValue(true); + const row = { + id: "rule-1", + title: "Mutual Aid Mondays", + summary: "A grassroots community in Denver.", + document: { sections: [] }, + createdAt: new Date("2026-01-01T00:00:00Z"), + updatedAt: new Date("2026-01-02T00:00:00Z"), + }; + findUniqueMock.mockResolvedValueOnce(row); + const res = await GET( + new Request("https://x.test/api/rules/rule-1"), + makeContext("rule-1"), + ); + expect(res.status).toBe(200); + const body = (await res.json()) as { + rule: { id: string; title: string; summary: string | null }; + }; + expect(body.rule.id).toBe("rule-1"); + expect(body.rule.title).toBe("Mutual Aid Mondays"); + expect(body.rule.summary).toBe("A grassroots community in Denver."); + }); +}); From c7f22a09908e48eb64ab442bdbbb3b202b7f41ca Mon Sep 17 00:00:00 2001 From: adilallo <39313955+adilallo@users.noreply.github.com> Date: Tue, 21 Apr 2026 22:48:23 -0600 Subject: [PATCH 3/9] CI: Postgres migration smoke --- .gitea/workflows/migrate-smoke.yaml | 74 +++++++++++++++++++++++++++++ CONTRIBUTING.md | 10 ++++ 2 files changed, 84 insertions(+) create mode 100644 .gitea/workflows/migrate-smoke.yaml diff --git a/.gitea/workflows/migrate-smoke.yaml b/.gitea/workflows/migrate-smoke.yaml new file mode 100644 index 0000000..73b5796 --- /dev/null +++ b/.gitea/workflows/migrate-smoke.yaml @@ -0,0 +1,74 @@ +name: Migrate Smoke +run-name: "${{ gitea.actor }} triggered migrate smoke" + +on: + workflow_dispatch: {} + pull_request: + branches: [main] + paths: + - "prisma/**" + - ".gitea/workflows/migrate-smoke.yaml" + push: + branches: [main] + paths: + - "prisma/**" + - ".gitea/workflows/migrate-smoke.yaml" + +env: + NODE_VERSION: "20" + NEXT_TELEMETRY_DISABLED: "1" + # Non-default host port so a local dev Postgres on 5432 keeps working. + PG_HOST_PORT: "5433" + POSTGRES_USER: communityrule + POSTGRES_PASSWORD: communityrule + POSTGRES_DB: communityrule + +jobs: + migrate: + runs-on: [self-hosted, macos-latest] + env: + CI: true + DATABASE_URL: "postgresql://communityrule:communityrule@127.0.0.1:5433/communityrule" + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "${{ env.NODE_VERSION }}" + cache: npm + + - name: Start Postgres + run: | + set -euo pipefail + docker rm -f migrate-smoke-pg >/dev/null 2>&1 || true + docker run -d --name migrate-smoke-pg \ + -e POSTGRES_USER="$POSTGRES_USER" \ + -e POSTGRES_PASSWORD="$POSTGRES_PASSWORD" \ + -e POSTGRES_DB="$POSTGRES_DB" \ + -p "${PG_HOST_PORT}:5432" \ + postgres:16-alpine + + - name: Wait for Postgres + run: | + set -euo pipefail + for i in {1..30}; do + if docker exec migrate-smoke-pg pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB" >/dev/null 2>&1; then + echo "Postgres ready after ${i}s" + exit 0 + fi + sleep 1 + done + echo "Postgres did not become ready in 30s" + docker logs migrate-smoke-pg || true + exit 1 + + - run: npm ci --no-audit --fund=false + + - name: Apply migrations + run: npm run db:deploy + + - name: Verify Prisma can connect to migrated DB + run: echo "SELECT 1;" | npx --no-install prisma db execute --stdin --url "$DATABASE_URL" + + - name: Stop Postgres + if: always() + run: docker rm -f migrate-smoke-pg >/dev/null 2>&1 || true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0e46bd5..d3938f8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,6 +21,16 @@ Use `npx prisma studio` to inspect the database. production, or any shared database. Add a **new** migration that corrects the schema instead. Full policy: [docs/guides/backend-roadmap.md](docs/guides/backend-roadmap.md) §8. +- **CI smoke:** [`.gitea/workflows/migrate-smoke.yaml`](.gitea/workflows/migrate-smoke.yaml) + spins up a throwaway Postgres and runs `npm run db:deploy` whenever + `prisma/**` changes on a PR (or via `workflow_dispatch`). If the + runner cannot run Docker/Postgres, run the same check locally before + merging migration changes: + + ```bash + docker compose up -d postgres + npm run db:deploy + ``` ### API routes From 4d066dad0e14bccf7c710ad4ab3ecd0fa41955b7 Mon Sep 17 00:00:00 2001 From: adilallo <39313955+adilallo@users.noreply.github.com> Date: Wed, 22 Apr 2026 18:54:32 -0600 Subject: [PATCH 4/9] Cloudron deployment plan --- CONTRIBUTING.md | 5 + docs/README.md | 1 + docs/guides/backend-linear-tickets.md | 70 +++++++++--- docs/guides/backend-roadmap.md | 12 +- docs/guides/ops-backend-deploy.md | 154 ++++++++++++++++++++++++++ 5 files changed, 220 insertions(+), 22 deletions(-) create mode 100644 docs/guides/ops-backend-deploy.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3938f8..d93d4d5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,6 +15,11 @@ Use `npx prisma studio` to inspect the database. +Deploying to staging or production (MEDLab Cloudron) — see +[docs/guides/ops-backend-deploy.md](docs/guides/ops-backend-deploy.md) +for the admin handoff and the linked Linear tickets for the actual +deployment-pipeline work. + ### Prisma migrations - **Never edit** a migration that has already been applied to staging, diff --git a/docs/README.md b/docs/README.md index 79b4c7f..b84f71c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,6 +23,7 @@ These will be deleted once the backend services are stood up: - [guides/backend-roadmap.md](./guides/backend-roadmap.md) - [guides/backend-linear-tickets.md](./guides/backend-linear-tickets.md) - [guides/template-recommendation-matrix.md](./guides/template-recommendation-matrix.md) +- [guides/ops-backend-deploy.md](./guides/ops-backend-deploy.md) — admin handoff for deploying to MEDLab's Cloudron. ## Cursor rules diff --git a/docs/guides/backend-linear-tickets.md b/docs/guides/backend-linear-tickets.md index e7e3983..78f7328 100644 --- a/docs/guides/backend-linear-tickets.md +++ b/docs/guides/backend-linear-tickets.md @@ -11,7 +11,8 @@ A backend review was merged into **[docs/backend-roadmap.md](backend-roadmap.md) ### Audit note (Linear CR-72+ vs repo, 2026-04) - **Done in Linear and shipped:** **CR-72–CR-76**, **CR-77** (publish from create flow), **CR-78** (template seed), **CR-79**, **CR-88**, **CR-89**. The **CR-72 → CR-83** numbering is the original **sequential plan**, not current blocking order; the **core product vertical** through publish + templates is effectively complete in-repo. -- **Backlog (still open):** **CR-80** (web vitals — file-based route remains), **CR-81** (public rule detail — no `GET /api/rules/[id]` or marketing detail page yet), **CR-82** (CI migrate smoke), **CR-83** (no `docs/ops-backend-deploy.md` yet), **CR-84** / **CR-85** (parallel hygiene), **CR-86** (profile + account + draft resume — UI mostly placeholder), **CR-90** / **CR-91**, **CR-93** (template grid facets on marketing). +- **Backlog (still open):** **CR-80** (web vitals — file-based route remains), **CR-81** (public rule detail — no `GET /api/rules/[id]` or marketing detail page yet), **CR-82** (CI migrate smoke), **CR-84** / **CR-85** (parallel hygiene), **CR-86** (profile + account + draft resume — UI mostly placeholder), **CR-90** / **CR-91**, **CR-93** (template grid facets on marketing). +- **CR-83 Done (admin handoff scope):** [`docs/guides/ops-backend-deploy.md`](ops-backend-deploy.md) shipped as the **admin handoff sheet** (access, env vars, platform settings, open decisions). The full deploy runbook is intentionally split out — see the new follow-up tickets in [Ticket 12 / CR-83 follow-ups](#follow-up-tickets-filed-under-cr-83) below. - **CR-86** is **no longer blocked** by publish — **CR-77** is **Done**; profile work is gated by **implementation**, not waiting on publish wiring. - **Not in this ticket list** but called out in **[docs/backend-roadmap.md](backend-roadmap.md):** shared **rate-limit store** (e.g. Redis) before multi-instance; **`GET /api/create-flow/methods`** exists for facet scoring (Ticket 16 / CR-88) but is not duplicated as a separate doc ticket. @@ -535,29 +536,58 @@ _Section B — Final Review screen `+` button per category:_ --- -## Ticket 12 — Staging / production runbook (operator checklist) +## Ticket 12 — Staging / production admin handoff (Cloudron at MEDLab) **Depends on:** Tickets 1–8 complete enough to deploy a vertical slice. -**Server / admin:** **This is the main ticket where you need the admin.** You draft the runbook; **admin fills in real hostnames, DB endpoint, SMTP, backup tooling, and who runs `migrate deploy`.** Without their input, you cannot complete production-ready deploy steps. +**Server / admin:** **This is the handoff ticket.** Scope is **narrowed** vs. the original "full operator runbook" framing: the deliverable is the **admin-handoff sheet** — exactly what access, env vars, and platform decisions to ask MEDLab's Cloudron admin for. The full deploy runbook (build / push / install / migrate / smoke / rollback) is **split out into a follow-up ticket** so CR-83 isn't blocked on access we don't have yet. -**Goal:** Single doc for admin: env vars, TLS, DB backups, migrations, Docker, SMTP, health checks. +**Goal:** Single short doc the admin can read end-to-end and respond to in one round-trip: required access, Cloudron-injected vs. manually-set env vars, platform settings to confirm (`httpPort`, `healthCheckPath`, addons, memory, backups), and the open product decisions only admin can answer (subdomains, sender address, registry choice, cutover overlap, retention). -**Implementation:** +**Platform context:** Target is **Cloudron at MEDLab** (same host as the legacy [`CommunityRule/CommunityRuleBackend`](https://git.medlab.host/CommunityRule/CommunityRuleBackend), which is Express + MySQL with a 30-min `run.sh` watchdog). New app is a properly packaged Cloudron app (Docker image + `CloudronManifest.json`), uses the **postgresql + sendmail + localstorage** addons, and replaces the legacy service entirely — **no data migration**. Cloudron's container supervisor replaces the old watchdog. -1. Add `docs/ops-backend-deploy.md` (or similar) with numbered steps: - - Required env: `DATABASE_URL`, `SESSION_SECRET`, `SMTP_URL`, `SMTP_FROM`, optional `NEXT_PUBLIC_ENABLE_BACKEND_SYNC`. - - `docker compose` vs `Dockerfile` deploy; `prisma migrate deploy` before traffic. - - Reverse proxy: `GET /api/health` for LB health. - - Backups and restore drill for Postgres. - - SMTP DNS (SPF/DKIM). -2. Cross-link [docs/backend-roadmap.md](docs/backend-roadmap.md) §11 (environments) and §8 (migrations policy); note **never rewrite applied migrations** and where application logs go. +**Implementation (shipped):** + +1. [`docs/guides/ops-backend-deploy.md`](ops-backend-deploy.md) — admin handoff sheet (~1 page): + - **§2 Access checklist** (Cloudron admin login, registry creds, DNS, `cloudron` CLI, log access, read of legacy app config). + - **§3 Env vars** split into Cloudron auto-injected (`CLOUDRON_POSTGRESQL_URL`, `CLOUDRON_MAIL_SMTP_*`) vs. manually-set (`SESSION_SECRET`, `SMTP_FROM`, `NEXT_PUBLIC_ENABLE_BACKEND_SYNC`). + - **§4 Platform settings** (`httpPort: 3000`, `healthCheckPath: /api/health`, memory, backups, TLS). + - **§5 Decisions** (subdomains, sender, registry, cutover, retention). + - **§7 Old vs new deltas** (addons, watchdog, OTP→magic link, sender, API surface — all reasons not to reuse legacy infra). + - **§8 Follow-up tickets** (the six tickets below). +2. Cross-links: [`docs/guides/backend-roadmap.md`](backend-roadmap.md) §11 (environments — names Cloudron at MEDLab) and §8 (migrations policy — never rewrite applied migrations). **Acceptance criteria:** -- [ ] Someone who did not write the code can deploy and roll back migrations with only the doc. +- [x] Admin can grant the right access + answer the open decisions in one pass without further back-and-forth. +- [x] Doc is ~1 page and explicitly lists what is **not** in scope so admin doesn't expect a full deploy walkthrough. +- [x] Six follow-up tickets enumerated and linked (see below). -**Files:** new `docs/ops-backend-deploy.md`. +**Files:** [`docs/guides/ops-backend-deploy.md`](ops-backend-deploy.md), [`docs/guides/backend-roadmap.md`](backend-roadmap.md), [`docs/README.md`](../README.md), [`CONTRIBUTING.md`](../../CONTRIBUTING.md). + +**Status:** [CR-83](https://linear.app/community-rule/issue/CR-83/backend-stagingproduction-runbook-admin-handoff-docsops-backend) **Done** (admin handoff scope). Deployment-pipeline implementation tracked in the follow-up tickets below. + +### Follow-up tickets filed under CR-83 + +All six are titled `[Backend] …`, assigned to Vinod, in the **community-rule** team, **Backlog** state. IDs filled in once filed via Linear MCP. + +| # | Linear | Title | Depends on | +| - | ------ | ----- | ---------- | +| 1 | [CR-96](https://linear.app/community-rule/issue/CR-96/backend-bridge-cloudron-env-vars-to-canonical-names) | `[Backend] Bridge CLOUDRON_* env vars to canonical names` | none — can ship now | +| 2 | [CR-97](https://linear.app/community-rule/issue/CR-97/backend-container-image-registry-choose-build-push) | `[Backend] Container image registry: choose, build, push` | registry decision (handoff §5) | +| 3 | [CR-98](https://linear.app/community-rule/issue/CR-98/backend-cloudron-staging-install-smoke) | `[Backend] Cloudron staging install + smoke` | CR-96 + CR-97 + Cloudron CLI access + staging DNS | +| 4 | [CR-99](https://linear.app/community-rule/issue/CR-99/backend-cloudron-production-install-dns-cutover) | `[Backend] Cloudron production install + DNS cutover` | CR-98 green for the agreed overlap window | +| 5 | [CR-100](https://linear.app/community-rule/issue/CR-100/backend-steady-state-operator-runbook) | `[Backend] Steady-state operator runbook` | CR-98 (write what we actually did) | +| 6 | [CR-101](https://linear.app/community-rule/issue/CR-101/backend-decommission-legacy-expressmysql-backend) | `[Backend] Decommission legacy Express/MySQL backend` | CR-99 + sign-off window | + +**Per-ticket detail:** + +1. **Bridge `CLOUDRON_*` env vars to canonical names.** Cloudron injects `CLOUDRON_POSTGRESQL_URL` and `CLOUDRON_MAIL_SMTP_SERVER/PORT/USERNAME/PASSWORD`; the app reads `DATABASE_URL` / `SMTP_URL`. Recommended approach: read both names in [`lib/server/env.ts`](../../lib/server/env.ts) and assemble `SMTP_URL` from the four parts in [`lib/server/mail.ts`](../../lib/server/mail.ts) when only the Cloudron names are present. Alternative: a `start.sh` shim in the image. Acceptance: with only `CLOUDRON_*` set, app connects to DB and sends mail; with only canonical names set (current behavior), unchanged; unit tests cover both. +2. **Container image registry: choose, build, push.** Acceptance: `docker pull /communityrule:` works from a Cloudron-reachable network. CI builds and pushes on merge to `main` (stretch). +3. **Cloudron staging install + smoke.** Acceptance: `curl https:///api/health` returns `{"ok":true,"database":"connected"}`; magic-link request → click link → `GET /api/auth/session` returns a user; publishing a rule succeeds. +4. **Cloudron production install + DNS cutover.** Acceptance: production subdomain resolves to the new app; old subdomain still works during overlap; sign-in + publish succeed against production; backups confirmed. +5. **Steady-state operator runbook.** Lives at `docs/guides/ops-runbook.md` (sibling to the handoff). Covers deploy a new version, rollback, restore drill cadence, multi-instance limitations from [`backend-roadmap.md`](backend-roadmap.md) §5/§7. Acceptance: a fresh reader can deploy + roll back using only this doc. +6. **Decommission legacy Express/MySQL backend.** Acceptance: old Cloudron app stopped + uninstalled; old MySQL addon backed up once and removed; legacy Gitea repo README updated to point at this app. Priority: Low. --- @@ -661,7 +691,7 @@ _Section B — Final Review screen `+` button per category:_ | 9 | 9 | Web vitals persistence | | 10 | 10 | Public rule detail (optional) | | 11 | 11 | CI migrate smoke (optional) | -| 12 | 12 | Ops runbook | +| 12 | 12 | Ops admin handoff (Cloudron) **Done** | | 13 | 13 | API errors + request-id logging | | 14 | 14 | Session lifecycle + cleanup | | 15 | 15 | Profile + account (Figma profile) | @@ -678,7 +708,7 @@ Tickets **10–11** can be deferred without blocking the core “auth + drafts + ## Linear (Community-rule team) -**Main chain (historical):** **CR-72 → CR-83** was the original **strict sequence**; **repo + Linear status today:** **CR-72–CR-79**, **CR-88**, **CR-89** are **Done**; **CR-77** (publish) **Done**; **CR-80–CR-83** remain **Backlog** (web vitals, public rule detail, CI migrate smoke, ops runbook — optional / ops tail). **Parallel:** **CR-84**, **CR-85** (**Backlog**); **CR-86** / Ticket 15 (**Backlog** — publish **not** a blocker); **CR-93** (**Backlog**); **CR-90** / Ticket 18 (stakeholder invites); **CR-91** / Ticket 19 (`Add` button behavior). +**Main chain (historical):** **CR-72 → CR-83** was the original **strict sequence**; **repo + Linear status today:** **CR-72–CR-79**, **CR-83**, **CR-88**, **CR-89** are **Done**; **CR-77** (publish) **Done**; **CR-80–CR-82** remain **Backlog** (web vitals, public rule detail, CI migrate smoke). **CR-83** (admin handoff) shipped as a narrow handoff sheet; the actual Cloudron deployment pipeline is split into the **`[Backend]` follow-up tickets** filed under it (env-var bridging → image registry → staging → production cutover → operator runbook → legacy decommission). **Parallel:** **CR-84**, **CR-85** (**Backlog**); **CR-86** / Ticket 15 (**Backlog** — publish **not** a blocker); **CR-93** (**Backlog**); **CR-90** / Ticket 18 (stakeholder invites); **CR-91** / Ticket 19 (`Add` button behavior). | Doc ticket | Linear | Title (short) | | ---------: | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | @@ -693,7 +723,13 @@ Tickets **10–11** can be deferred without blocking the core “auth + drafts + | 9 | [CR-80](https://linear.app/community-rule/issue/CR-80/backend-persist-web-vitals-outside-next-db-or-external-rum) | Web vitals (prefer external) | | 10 | [CR-81](https://linear.app/community-rule/issue/CR-81/backend-public-rule-detail-page-get-apirulesid-optional) | Public rule detail (optional) | | 11 | [CR-82](https://linear.app/community-rule/issue/CR-82/backend-ci-postgres-migration-smoke-optional) | CI migrate smoke (optional) | -| 12 | [CR-83](https://linear.app/community-rule/issue/CR-83/backend-stagingproduction-runbook-admin-handoff-docsops-backend) | Ops runbook / admin handoff | +| 12 | [CR-83](https://linear.app/community-rule/issue/CR-83/backend-stagingproduction-runbook-admin-handoff-docsops-backend) | Ops admin handoff (Cloudron) **Done** | +| 12.1 | [CR-96](https://linear.app/community-rule/issue/CR-96/backend-bridge-cloudron-env-vars-to-canonical-names) | `[Backend] Bridge CLOUDRON_* env vars to canonical names` | +| 12.2 | [CR-97](https://linear.app/community-rule/issue/CR-97/backend-container-image-registry-choose-build-push) | `[Backend] Container image registry: choose, build, push` | +| 12.3 | [CR-98](https://linear.app/community-rule/issue/CR-98/backend-cloudron-staging-install-smoke) | `[Backend] Cloudron staging install + smoke` | +| 12.4 | [CR-99](https://linear.app/community-rule/issue/CR-99/backend-cloudron-production-install-dns-cutover) | `[Backend] Cloudron production install + DNS cutover` | +| 12.5 | [CR-100](https://linear.app/community-rule/issue/CR-100/backend-steady-state-operator-runbook) | `[Backend] Steady-state operator runbook` | +| 12.6 | [CR-101](https://linear.app/community-rule/issue/CR-101/backend-decommission-legacy-expressmysql-backend) | `[Backend] Decommission legacy Express/MySQL backend` | | 13 | [CR-84](https://linear.app/community-rule/issue/CR-84/backend-api-error-contract-request-id-logging) | API errors + request-id logging | | 14 | [CR-85](https://linear.app/community-rule/issue/CR-85/backend-custom-session-lifecycle-cleanup-invalidation-policy) | Session lifecycle + cleanup | | 15 | [CR-86](https://linear.app/community-rule/issue/CR-86/backend-profile-dashboard-account-figma-profile) | Profile + account (Figma 22143:900069) | diff --git a/docs/guides/backend-roadmap.md b/docs/guides/backend-roadmap.md index d5fb602..9071a3b 100644 --- a/docs/guides/backend-roadmap.md +++ b/docs/guides/backend-roadmap.md @@ -206,13 +206,15 @@ npm run dev **Optional QA:** Run automated tests against an **ephemeral** database in CI instead of maintaining a fourth long-lived server. +**Target platform:** **Cloudron at MEDLab** — same host as the legacy [`CommunityRule/CommunityRuleBackend`](https://git.medlab.host/CommunityRule/CommunityRuleBackend) (Express + MySQL). The new app is packaged as a proper Cloudron app (Docker image + `CloudronManifest.json`, **postgresql + sendmail + localstorage** addons). Cloudron's container supervisor replaces the legacy 30-min `run.sh` watchdog. Admin handoff (access, env vars, platform settings, open decisions): [`docs/guides/ops-backend-deploy.md`](ops-backend-deploy.md). Note: Cloudron injects `CLOUDRON_POSTGRESQL_URL` and `CLOUDRON_MAIL_SMTP_*`; the app reads `DATABASE_URL` / `SMTP_URL`, so a small env-var bridge in [`lib/server/env.ts`](../../lib/server/env.ts) / [`lib/server/mail.ts`](../../lib/server/mail.ts) is needed (tracked in [**CR-96**](https://linear.app/community-rule/issue/CR-96/backend-bridge-cloudron-env-vars-to-canonical-names), filed under CR-83 — see [backend-linear-tickets.md](backend-linear-tickets.md) Ticket 12 follow-ups). + **Admin / infra (coordinate with whoever runs the server):** -1. TLS certificates and hostnames. -2. PostgreSQL backups and restore drill. -3. SMTP DNS (SPF, DKIM). -4. Health check URL for reverse proxy (`/api/health`). -5. Log retention and alerts for 5xx errors. +1. TLS certificates and hostnames. _On Cloudron: handled by the platform per chosen subdomain._ +2. PostgreSQL backups and restore drill. _On Cloudron: daily snapshots; configure retention in admin UI._ +3. SMTP DNS (SPF, DKIM). _On Cloudron: handled for the platform-managed domain._ +4. Health check URL for reverse proxy (`/api/health`). _On Cloudron: set `healthCheckPath` in `CloudronManifest.json`._ +5. Log retention and alerts for 5xx errors. _On Cloudron: app log viewer; export off-platform if longer retention is needed._ --- diff --git a/docs/guides/ops-backend-deploy.md b/docs/guides/ops-backend-deploy.md new file mode 100644 index 0000000..5fbe0c4 --- /dev/null +++ b/docs/guides/ops-backend-deploy.md @@ -0,0 +1,154 @@ +# Backend deploy — admin handoff + +This is the list of access, environment variables, and platform decisions +needed to deploy CommunityRule (the new Next.js + Postgres app in this +repo) onto MEDLab's Cloudron. Hand it to the Cloudron admin; once they +confirm what is checked below, the actual deploy happens in the +follow-up tickets listed in §8. + +## 1. Context + +- This app **replaces** the old Express + MySQL backend at + [`CommunityRule/CommunityRuleBackend`](https://git.medlab.host/CommunityRule/CommunityRuleBackend). +- It is packaged as a real Cloudron app (Docker image + + `CloudronManifest.json`). No `/app/data` drop-in. No `run.sh` + watchdog — Cloudron's container supervisor handles restarts. +- **Greenfield Postgres.** No data migration from the old MySQL addon. + Old auth (4-digit OTP in `email_otp`) is replaced by hashed + magic-link tokens; old API and `rules` / `version_history` tables do + not map to anything in the new app. + +## 2. Access I need + +Check off as granted: + +- [ ] **Cloudron admin login** for the MEDLab instance, or "deploy + app" capability scoped to one app slot. +- [ ] **Container registry credentials** — read/write to wherever + images get pushed (Docker Hub, GHCR, MEDLab self-hosted registry — + admin's choice; see §6). +- [ ] **DNS** — ability to add/edit a subdomain record pointing at the + Cloudron host, or confirmation that admin will add the records I + specify. +- [ ] **`cloudron` CLI access** from my workstation (token-based; no + SSH needed for normal ops). +- [ ] **Cloudron app log access** — web UI is fine; SSH only if web + logs aren't enough. +- [ ] **Read access to the existing legacy app's Cloudron config** so + I can confirm domain / cert / SMTP setup before cutover. + +## 3. Environment variables + +### Cloudron auto-injects (admin: confirm the addons are enabled) + +- `CLOUDRON_POSTGRESQL_URL` — from the **postgresql** addon. The app + reads `DATABASE_URL`; bridging is a small in-app code change (see + §8 ticket 1). +- `CLOUDRON_MAIL_SMTP_SERVER` / `_PORT` / `_USERNAME` / `_PASSWORD` — + from the **sendmail** addon. The app reads `SMTP_URL`; bridged the + same way. + +### I set manually via `cloudron configure --app --set-env` + +- `SESSION_SECRET` — long random (`openssl rand -hex 32`). Required, + ≥ 16 chars. Rotating it logs everyone out. +- `SMTP_FROM` — visible "From:" address on sign-in emails. Cloudron + does **not** inject this. Recommend `hello@communityrule.info` (same + as the old service) unless admin wants a new address. +- `NEXT_PUBLIC_ENABLE_BACKEND_SYNC=true` — turns on Postgres draft + persistence for signed-in users. Recommended for production. + +## 4. Platform settings to confirm + +- Container `httpPort`: **3000** (matches [`Dockerfile`](../../Dockerfile) + `ENV PORT=3000`). +- Health-check path: **`/api/health`** + ([`app/api/health/route.ts`](../../app/api/health/route.ts) returns + `200 {"ok":true,"database":"connected"}` when healthy, `503` + otherwise). +- Memory limit: start at **512 MB**; raise if Next.js standalone OOMs + under load. +- Backups: confirm Cloudron's daily snapshot is on for both this app + and its postgresql addon. +- TLS, DNS, SPF/DKIM: handled by Cloudron for the chosen subdomain — + confirm. + +## 5. Decisions I need from admin + +1. **Subdomains** for staging and production. Default proposal: + `staging-app.communityrule.info` + `app.communityrule.info`. +2. **Sender address** — reuse legacy `hello@communityrule.info`, or + pick a new one? +3. **Container registry** — MEDLab self-hosted, Docker Hub (under + what org), or GHCR? +4. **Cutover overlap** — how many days should the old service keep + running in parallel before we uninstall it? +5. **Backup retention** beyond Cloudron defaults? (If "defaults are + fine," say so.) + +## 6. What is intentionally NOT in this doc + +So admin doesn't expect more than this scope: + +- The deploy runbook itself (build / push / install / migrate / smoke + / rollback) — written **after** access in §2 is granted; see §8 + ticket 5. +- Code changes to bridge `CLOUDRON_*` env vars to `DATABASE_URL` / + `SMTP_URL` — I do those locally and ship the image with bridging + built in; see §8 ticket 1. +- Decommissioning the legacy Express/MySQL service — does not happen + until the new app is green in production; see §8 ticket 6. + +## 7. Old vs new backend deltas + +So nothing surprises admin or users at cutover: + +- Old addons: **MySQL + sendmail**. New addons: **postgresql + + sendmail + localstorage**. Different DB addon entirely; do not + reuse the old one. +- Old service ran from `/app/data/public/communityRuleBackend` with a + 30-min `lsof`-based `run.sh` watchdog — not a packaged Cloudron + app. New app is a proper Cloudron app; Cloudron supervises it. +- Old auth = plaintext 4-digit OTP. New auth = magic **link** in + email. If users report "I'm not getting a code," remind them to + look for a link. +- Old code hardcoded `from: 'hello@communityrule.info'` in + [`controllers/emailController.js`](https://git.medlab.host/CommunityRule/CommunityRuleBackend/raw/branch/master/controllers/emailController.js) + because Cloudron does not inject a `MAIL_FROM`. New app reads + `SMTP_FROM` — see §3. +- Old API surface (`/api/send_otp`, `/api/publish_rule`, etc.) and + schema (`rules` + `version_history` tables, soft-delete via + `deleted` column) **do not overlap**. No data migration. + +## 8. Follow-up tickets + +All filed in Linear, titled `[Backend] …`, assigned to me, in the +**Community-rule** team, **Backlog** state. + +1. [**CR-96**](https://linear.app/community-rule/issue/CR-96/backend-bridge-cloudron-env-vars-to-canonical-names) + — `[Backend] Bridge CLOUDRON_* env vars to canonical names`. No + admin dependency; can land now. +2. [**CR-97**](https://linear.app/community-rule/issue/CR-97/backend-container-image-registry-choose-build-push) + — `[Backend] Container image registry: choose, build, push`. + Depends on registry decision (§5). +3. [**CR-98**](https://linear.app/community-rule/issue/CR-98/backend-cloudron-staging-install-smoke) + — `[Backend] Cloudron staging install + smoke`. Blocked by CR-96 + + CR-97; needs Cloudron CLI access + staging DNS. +4. [**CR-99**](https://linear.app/community-rule/issue/CR-99/backend-cloudron-production-install-dns-cutover) + — `[Backend] Cloudron production install + DNS cutover`. Blocked + by CR-98 green for the agreed overlap window. +5. [**CR-100**](https://linear.app/community-rule/issue/CR-100/backend-steady-state-operator-runbook) + — `[Backend] Steady-state operator runbook`. Blocked by CR-98 + (we write it after we've actually done it). +6. [**CR-101**](https://linear.app/community-rule/issue/CR-101/backend-decommission-legacy-expressmysql-backend) + — `[Backend] Decommission legacy Express/MySQL backend`. Blocked + by CR-99 + sign-off window. Priority: Low. + +## 9. Related docs + +- [`docs/guides/backend-roadmap.md`](backend-roadmap.md) §11 + (environments) and §8 (Prisma migrations policy). +- [`docs/guides/backend-linear-tickets.md`](backend-linear-tickets.md) + Ticket 12 / CR-83 — this doc satisfies it. +- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) — local dev setup + (Postgres, magic-link, draft sync). From 5457d3554bda7ad1bd3bdf0c2bbd45c3fafcde89 Mon Sep 17 00:00:00 2001 From: adilallo <39313955+adilallo@users.noreply.github.com> Date: Wed, 22 Apr 2026 19:15:04 -0600 Subject: [PATCH 5/9] API error contract --- .cursor/rules/api-routes.mdc | 21 +++-- app/api/auth/logout/route.ts | 5 +- app/api/auth/magic-link/request/route.ts | 44 ++++------ app/api/auth/magic-link/verify/route.ts | 103 +++++++++++++++-------- app/api/auth/session/route.ts | 5 +- app/api/drafts/me/route.ts | 24 +++--- app/api/rules/[id]/route.ts | 28 +++--- app/api/rules/route.ts | 16 ++-- docs/guides/backend-linear-tickets.md | 10 +-- docs/guides/backend-roadmap.md | 4 +- lib/server/apiRoute.ts | 45 ++++++++++ lib/server/requestId.ts | 70 +++++++++++++++ lib/server/responses.ts | 81 +++++++++++++++++- tests/unit/apiRoute.test.ts | 86 +++++++++++++++++++ tests/unit/draftsMeRoute.test.ts | 100 ++++++++++++++++++++++ tests/unit/requestId.test.ts | 60 +++++++++++++ tests/unit/responses.test.ts | 98 +++++++++++++++++++++ tests/unit/rulesByIdRoute.test.ts | 34 ++++++-- 18 files changed, 717 insertions(+), 117 deletions(-) create mode 100644 lib/server/apiRoute.ts create mode 100644 lib/server/requestId.ts create mode 100644 tests/unit/apiRoute.test.ts create mode 100644 tests/unit/draftsMeRoute.test.ts create mode 100644 tests/unit/requestId.test.ts create mode 100644 tests/unit/responses.test.ts diff --git a/.cursor/rules/api-routes.mdc b/.cursor/rules/api-routes.mdc index 79d428c..42c9f31 100644 --- a/.cursor/rules/api-routes.mdc +++ b/.cursor/rules/api-routes.mdc @@ -45,9 +45,19 @@ Keep new routes within this shape so auth, config, and validation stay uniform. 4. **Prisma access** via `import { prisma } from "lib/server/db"`. Do not instantiate `PrismaClient` directly. -5. **Responses** via `NextResponse.json(...)`. Shared shapes (`dbUnavailable`) - live in `lib/server/responses.ts`; add new shared responses there when a - pattern repeats in two routes. +5. **Responses** via `NextResponse.json(...)`. Shared shapes + (`dbUnavailable`, `unauthorized`, `notFound`, `rateLimited`, + `serverMisconfigured`, `internalError`) and the generic `errorJson(code, + message, status, opts?)` live in `lib/server/responses.ts`. Add new + shared responses there when a pattern repeats in two routes. + +6. **Errors + observability.** All 4xx/5xx bodies use the canonical shape + `{ error: { code, message }, details? }` with codes from the + `ApiErrorCode` union in `lib/server/responses.ts`. Wrap handlers with + `apiRoute("scope.name", async (req, ctx, { requestId }) => { ... })` + from `lib/server/apiRoute.ts` so an `x-request-id` is generated / + forwarded onto every response and uncaught throws return a canonical + 500 with the id logged via `lib/logger`. # Server-only isolation @@ -68,9 +78,8 @@ instead of introducing new patterns: - **Rate limiting.** `lib/server/rateLimit.ts` is an in-memory stopgap marked for replacement. Reuse `rateLimitKey()` where limiting is needed; don't - design a new limiter. -- **Error response shape.** Currently `{ error: string }` + HTTP status. No - error codes yet — don't add a taxonomy until one is designed. + design a new limiter. When returning 429, prefer `rateLimited(retryAfterMs)` + from `responses.ts` so the body and `Retry-After` header stay uniform. - **Pagination / filtering.** Only `rules/route.ts` paginates (`take` capped at 100). Mirror it if you add list endpoints; don't invent cursors or offset contracts unilaterally. diff --git a/app/api/auth/logout/route.ts b/app/api/auth/logout/route.ts index 2602fb9..dfa2936 100644 --- a/app/api/auth/logout/route.ts +++ b/app/api/auth/logout/route.ts @@ -2,12 +2,13 @@ import { NextResponse } from "next/server"; import { isDatabaseConfigured } from "../../../../lib/server/env"; import { dbUnavailable } from "../../../../lib/server/responses"; import { destroySessionFromRequest } from "../../../../lib/server/session"; +import { apiRoute } from "../../../../lib/server/apiRoute"; -export async function POST() { +export const POST = apiRoute("auth.logout", async () => { if (!isDatabaseConfigured()) { return dbUnavailable(); } await destroySessionFromRequest(); return NextResponse.json({ ok: true }); -} +}); diff --git a/app/api/auth/magic-link/request/route.ts b/app/api/auth/magic-link/request/route.ts index 067f2b6..c91a166 100644 --- a/app/api/auth/magic-link/request/route.ts +++ b/app/api/auth/magic-link/request/route.ts @@ -10,13 +10,20 @@ import { } from "../../../../../lib/server/hash"; import { sendMagicLinkEmail } from "../../../../../lib/server/mail"; import { rateLimitKey } from "../../../../../lib/server/rateLimit"; -import { dbUnavailable } from "../../../../../lib/server/responses"; -import { logger } from "../../../../../lib/logger"; +import { + dbUnavailable, + errorJson, + rateLimited, + serverMisconfigured, +} from "../../../../../lib/server/responses"; +import { logRouteError } from "../../../../../lib/server/requestId"; +import { apiRoute } from "../../../../../lib/server/apiRoute"; import { safeInternalPath } from "../../../../../lib/safeInternalPath"; const MAGIC_LINK_TTL_MS = 15 * 60 * 1000; const EMAIL_MIN_INTERVAL_MS = 60 * 1000; const IP_MIN_INTERVAL_MS = 20 * 1000; +const SCOPE = "auth.magicLink.request"; function normalizeEmail(raw: unknown): string | null { if (typeof raw !== "string") return null; @@ -32,7 +39,7 @@ function readNextPath(body: unknown): string | null { return safeInternalPath(n); } -export async function POST(request: NextRequest) { +export const POST = apiRoute(SCOPE, async (request: NextRequest, _ctx, { requestId }) => { if (!isDatabaseConfigured()) { return dbUnavailable(); } @@ -41,7 +48,7 @@ export async function POST(request: NextRequest) { try { body = await request.json(); } catch { - return NextResponse.json({ error: "Invalid JSON" }, { status: 400 }); + return errorJson("invalid_json", "Invalid JSON", 400); } const email = normalizeEmail( @@ -50,10 +57,7 @@ export async function POST(request: NextRequest) { : null, ); if (!email) { - return NextResponse.json( - { error: "Valid email required" }, - { status: 400 }, - ); + return errorJson("validation_error", "Valid email required", 400); } const ip = @@ -63,28 +67,19 @@ export async function POST(request: NextRequest) { const rlEmail = rateLimitKey(`magic-email:${email}`, EMAIL_MIN_INTERVAL_MS); if (rlEmail.ok === false) { - return NextResponse.json( - { error: "Too many requests", retryAfterMs: rlEmail.retryAfterMs }, - { status: 429 }, - ); + return rateLimited(rlEmail.retryAfterMs); } const rlIp = rateLimitKey(`magic-ip:${ip}`, IP_MIN_INTERVAL_MS); if (rlIp.ok === false) { - return NextResponse.json( - { error: "Too many requests", retryAfterMs: rlIp.retryAfterMs }, - { status: 429 }, - ); + return rateLimited(rlIp.retryAfterMs); } let pepper: string; try { pepper = getSessionPepper(); } catch { - return NextResponse.json( - { error: "Server misconfiguration" }, - { status: 500 }, - ); + return serverMisconfigured(); } const token = newSessionToken(); @@ -108,13 +103,10 @@ export async function POST(request: NextRequest) { try { await sendMagicLinkEmail(email, verifyUrl); } catch (err) { - logger.error("sendMagicLinkEmail failed:", err); + logRouteError(SCOPE, requestId, err, { phase: "sendMagicLinkEmail", email }); await prisma.magicLinkToken.deleteMany({ where: { email } }); - return NextResponse.json( - { error: "Could not send email" }, - { status: 502 }, - ); + return errorJson("mail_failed", "Could not send email", 502); } return NextResponse.json({ ok: true }); -} +}); diff --git a/app/api/auth/magic-link/verify/route.ts b/app/api/auth/magic-link/verify/route.ts index a8e2261..02f24cd 100644 --- a/app/api/auth/magic-link/verify/route.ts +++ b/app/api/auth/magic-link/verify/route.ts @@ -10,52 +10,83 @@ import { setSessionCookie, } from "../../../../../lib/server/session"; import { dbUnavailable } from "../../../../../lib/server/responses"; +import { + REQUEST_ID_HEADER, + getOrCreateRequestId, + logRouteError, +} from "../../../../../lib/server/requestId"; import { safeInternalPath } from "../../../../../lib/safeInternalPath"; +const SCOPE = "auth.magicLink.verify"; + export async function GET(request: NextRequest) { + const requestId = getOrCreateRequestId(request); + if (!isDatabaseConfigured()) { - return dbUnavailable(); + const res = dbUnavailable(); + res.headers.set(REQUEST_ID_HEADER, requestId); + return res; } - const token = request.nextUrl.searchParams.get("token"); - if (!token || token.length < 10) { - return NextResponse.redirect( - new URL("/login?error=invalid_link", request.url), - ); - } - - let pepper: string; try { - pepper = getSessionPepper(); - } catch { - return NextResponse.redirect(new URL("/login?error=server", request.url)); - } + const token = request.nextUrl.searchParams.get("token"); + if (!token || token.length < 10) { + return redirectWithRequestId( + request, + "/login?error=invalid_link", + requestId, + ); + } - const tokenHash = hashSessionToken(token, pepper); + let pepper: string; + try { + pepper = getSessionPepper(); + } catch (err) { + logRouteError(SCOPE, requestId, err, { phase: "getSessionPepper" }); + return redirectWithRequestId(request, "/login?error=server", requestId); + } - const row = await prisma.magicLinkToken.findUnique({ - where: { tokenHash }, - }); + const tokenHash = hashSessionToken(token, pepper); - if (!row || row.expiresAt < new Date()) { - return NextResponse.redirect( - new URL("/login?error=expired_link", request.url), + const row = await prisma.magicLinkToken.findUnique({ + where: { tokenHash }, + }); + + if (!row || row.expiresAt < new Date()) { + return redirectWithRequestId( + request, + "/login?error=expired_link", + requestId, + ); + } + + await prisma.magicLinkToken.delete({ where: { id: row.id } }); + + const user = await prisma.user.upsert({ + where: { email: row.email }, + create: { email: row.email }, + update: {}, + }); + + const { token: sessionToken, expiresAt } = await createSessionForUser( + user.id, ); + await setSessionCookie(sessionToken, expiresAt); + + const dest = safeInternalPath(row.nextPath); + return redirectWithRequestId(request, dest, requestId); + } catch (err) { + logRouteError(SCOPE, requestId, err); + return redirectWithRequestId(request, "/login?error=server", requestId); } - - await prisma.magicLinkToken.delete({ where: { id: row.id } }); - - const user = await prisma.user.upsert({ - where: { email: row.email }, - create: { email: row.email }, - update: {}, - }); - - const { token: sessionToken, expiresAt } = await createSessionForUser( - user.id, - ); - await setSessionCookie(sessionToken, expiresAt); - - const dest = safeInternalPath(row.nextPath); - return NextResponse.redirect(new URL(dest, request.url)); +} + +function redirectWithRequestId( + request: NextRequest, + path: string, + requestId: string, +): NextResponse { + const res = NextResponse.redirect(new URL(path, request.url)); + res.headers.set(REQUEST_ID_HEADER, requestId); + return res; } diff --git a/app/api/auth/session/route.ts b/app/api/auth/session/route.ts index 430262b..fb4aed7 100644 --- a/app/api/auth/session/route.ts +++ b/app/api/auth/session/route.ts @@ -2,8 +2,9 @@ import { NextResponse } from "next/server"; import { isDatabaseConfigured } from "../../../../lib/server/env"; import { dbUnavailable } from "../../../../lib/server/responses"; import { getSessionUser } from "../../../../lib/server/session"; +import { apiRoute } from "../../../../lib/server/apiRoute"; -export async function GET() { +export const GET = apiRoute("auth.session", async () => { if (!isDatabaseConfigured()) { return dbUnavailable(); } @@ -16,4 +17,4 @@ export async function GET() { return NextResponse.json({ user: { id: user.id, email: user.email }, }); -} +}); diff --git a/app/api/drafts/me/route.ts b/app/api/drafts/me/route.ts index dbde8ca..667cc9d 100644 --- a/app/api/drafts/me/route.ts +++ b/app/api/drafts/me/route.ts @@ -2,20 +2,24 @@ import type { Prisma } from "@prisma/client"; import { NextRequest, NextResponse } from "next/server"; import { prisma } from "../../../../lib/server/db"; import { isDatabaseConfigured } from "../../../../lib/server/env"; -import { dbUnavailable } from "../../../../lib/server/responses"; +import { + dbUnavailable, + unauthorized, +} from "../../../../lib/server/responses"; import { getSessionUser } from "../../../../lib/server/session"; +import { apiRoute } from "../../../../lib/server/apiRoute"; import { putDraftBodySchema } from "../../../../lib/server/validation/createFlowSchemas"; import { readLimitedJson } from "../../../../lib/server/validation/requestBody"; import { jsonFromZodError } from "../../../../lib/server/validation/zodHttp"; -export async function GET() { +export const GET = apiRoute("drafts.me.get", async () => { if (!isDatabaseConfigured()) { return dbUnavailable(); } const user = await getSessionUser(); if (!user) { - return NextResponse.json({ error: "Unauthorized" }, { status: 401 }); + return unauthorized(); } const draft = await prisma.ruleDraft.findUnique({ @@ -27,16 +31,16 @@ export async function GET() { ? { payload: draft.payload, updatedAt: draft.updatedAt } : null, }); -} +}); -export async function PUT(request: NextRequest) { +export const PUT = apiRoute("drafts.me.put", async (request: NextRequest) => { if (!isDatabaseConfigured()) { return dbUnavailable(); } const user = await getSessionUser(); if (!user) { - return NextResponse.json({ error: "Unauthorized" }, { status: 401 }); + return unauthorized(); } const parsedBody = await readLimitedJson(request); @@ -67,16 +71,16 @@ export async function PUT(request: NextRequest) { return NextResponse.json({ draft: { payload: draft.payload, updatedAt: draft.updatedAt }, }); -} +}); -export async function DELETE() { +export const DELETE = apiRoute("drafts.me.delete", async () => { if (!isDatabaseConfigured()) { return dbUnavailable(); } const user = await getSessionUser(); if (!user) { - return NextResponse.json({ error: "Unauthorized" }, { status: 401 }); + return unauthorized(); } // Idempotent: missing draft is a no-op so callers can fire-and-forget after @@ -84,4 +88,4 @@ export async function DELETE() { await prisma.ruleDraft.deleteMany({ where: { userId: user.id } }); return NextResponse.json({ ok: true }); -} +}); diff --git a/app/api/rules/[id]/route.ts b/app/api/rules/[id]/route.ts index 9b7330e..5d6e497 100644 --- a/app/api/rules/[id]/route.ts +++ b/app/api/rules/[id]/route.ts @@ -1,21 +1,25 @@ import { NextResponse } from "next/server"; import { isDatabaseConfigured } from "../../../../lib/server/env"; -import { dbUnavailable } from "../../../../lib/server/responses"; +import { dbUnavailable, notFound } from "../../../../lib/server/responses"; import { getPublicPublishedRuleById } from "../../../../lib/server/publishedRules"; +import { apiRoute } from "../../../../lib/server/apiRoute"; type RouteContext = { params: Promise<{ id: string }> }; -export async function GET(_request: Request, context: RouteContext) { - if (!isDatabaseConfigured()) { - return dbUnavailable(); - } +export const GET = apiRoute( + "rules.byId", + async (_request, context) => { + if (!isDatabaseConfigured()) { + return dbUnavailable(); + } - const { id } = await context.params; + const { id } = await context.params; - const rule = await getPublicPublishedRuleById(id); - if (!rule) { - return NextResponse.json({ error: "Not found" }, { status: 404 }); - } + const rule = await getPublicPublishedRuleById(id); + if (!rule) { + return notFound(); + } - return NextResponse.json({ rule }); -} + return NextResponse.json({ rule }); + }, +); diff --git a/app/api/rules/route.ts b/app/api/rules/route.ts index 5b9d352..e003871 100644 --- a/app/api/rules/route.ts +++ b/app/api/rules/route.ts @@ -2,13 +2,17 @@ import type { Prisma } from "@prisma/client"; import { NextRequest, NextResponse } from "next/server"; import { prisma } from "../../../lib/server/db"; import { isDatabaseConfigured } from "../../../lib/server/env"; -import { dbUnavailable } from "../../../lib/server/responses"; +import { + dbUnavailable, + unauthorized, +} from "../../../lib/server/responses"; import { getSessionUser } from "../../../lib/server/session"; +import { apiRoute } from "../../../lib/server/apiRoute"; import { publishRuleBodySchema } from "../../../lib/server/validation/createFlowSchemas"; import { readLimitedJson } from "../../../lib/server/validation/requestBody"; import { jsonFromZodError } from "../../../lib/server/validation/zodHttp"; -export async function GET(request: NextRequest) { +export const GET = apiRoute("rules.list", async (request: NextRequest) => { if (!isDatabaseConfigured()) { return dbUnavailable(); } @@ -29,16 +33,16 @@ export async function GET(request: NextRequest) { }); return NextResponse.json({ rules }); -} +}); -export async function POST(request: NextRequest) { +export const POST = apiRoute("rules.publish", async (request: NextRequest) => { if (!isDatabaseConfigured()) { return dbUnavailable(); } const user = await getSessionUser(); if (!user) { - return NextResponse.json({ error: "Unauthorized" }, { status: 401 }); + return unauthorized(); } const parsedBody = await readLimitedJson(request); @@ -70,4 +74,4 @@ export async function POST(request: NextRequest) { createdAt: rule.createdAt, }, }); -} +}); diff --git a/docs/guides/backend-linear-tickets.md b/docs/guides/backend-linear-tickets.md index 78f7328..4af47bc 100644 --- a/docs/guides/backend-linear-tickets.md +++ b/docs/guides/backend-linear-tickets.md @@ -11,7 +11,7 @@ A backend review was merged into **[docs/backend-roadmap.md](backend-roadmap.md) ### Audit note (Linear CR-72+ vs repo, 2026-04) - **Done in Linear and shipped:** **CR-72–CR-76**, **CR-77** (publish from create flow), **CR-78** (template seed), **CR-79**, **CR-88**, **CR-89**. The **CR-72 → CR-83** numbering is the original **sequential plan**, not current blocking order; the **core product vertical** through publish + templates is effectively complete in-repo. -- **Backlog (still open):** **CR-80** (web vitals — file-based route remains), **CR-81** (public rule detail — no `GET /api/rules/[id]` or marketing detail page yet), **CR-82** (CI migrate smoke), **CR-84** / **CR-85** (parallel hygiene), **CR-86** (profile + account + draft resume — UI mostly placeholder), **CR-90** / **CR-91**, **CR-93** (template grid facets on marketing). +- **Backlog (still open):** **CR-80** (web vitals — file-based route remains), **CR-81** (public rule detail — no `GET /api/rules/[id]` or marketing detail page yet), **CR-82** (CI migrate smoke), **CR-85** (parallel hygiene — session lifecycle), **CR-86** (profile + account + draft resume — UI mostly placeholder), **CR-90** / **CR-91**, **CR-93** (template grid facets on marketing). **CR-84 Done** — canonical error contract `{ error: { code, message }, details? }` and `x-request-id` propagation shipped via `lib/server/{responses,requestId,apiRoute}.ts`; auth + drafts + rules routes migrated, remaining `app/api/*` are a follow-up pass. - **CR-83 Done (admin handoff scope):** [`docs/guides/ops-backend-deploy.md`](ops-backend-deploy.md) shipped as the **admin handoff sheet** (access, env vars, platform settings, open decisions). The full deploy runbook is intentionally split out — see the new follow-up tickets in [Ticket 12 / CR-83 follow-ups](#follow-up-tickets-filed-under-cr-83) below. - **CR-86** is **no longer blocked** by publish — **CR-77** is **Done**; profile work is gated by **implementation**, not waiting on publish wiring. - **Not in this ticket list** but called out in **[docs/backend-roadmap.md](backend-roadmap.md):** shared **rate-limit store** (e.g. Redis) before multi-instance; **`GET /api/create-flow/methods`** exists for facet scoring (Ticket 16 / CR-88) but is not duplicated as a separate doc ticket. @@ -607,12 +607,12 @@ All six are titled `[Backend] …`, assigned to Vinod, in the **community-rule** **Acceptance criteria:** -- [ ] At least auth + draft + rules routes return the agreed shape for new code paths. -- [ ] Errors in logs include request id when available. +- [x] At least auth + draft + rules routes return the agreed shape for new code paths. +- [x] Errors in logs include request id when available. -**Files:** `lib/server/` (new helper), selected `app/api/**/route.ts`, optional tests. +**Files:** [`lib/server/responses.ts`](lib/server/responses.ts), [`lib/server/requestId.ts`](lib/server/requestId.ts), [`lib/server/apiRoute.ts`](lib/server/apiRoute.ts); migrated `app/api/auth/**/route.ts`, `app/api/drafts/me/route.ts`, `app/api/rules/route.ts`, `app/api/rules/[id]/route.ts`; tests in `tests/unit/{responses,requestId,apiRoute,draftsMeRoute,rulesByIdRoute}.test.ts`. -**Linear:** [CR-84](https://linear.app/community-rule/issue/CR-84/backend-api-error-contract-request-id-logging) (**CR-73** Done — ready to pick up). +**Linear:** [CR-84](https://linear.app/community-rule/issue/CR-84/backend-api-error-contract-request-id-logging) **Done** (**CR-73** Done — was ready to pick up). --- diff --git a/docs/guides/backend-roadmap.md b/docs/guides/backend-roadmap.md index 9071a3b..b735d88 100644 --- a/docs/guides/backend-roadmap.md +++ b/docs/guides/backend-roadmap.md @@ -115,9 +115,9 @@ Match the current API behavior; tighten as product evolves: ## 7. API responses, errors, and observability -**Error JSON (target):** Prefer a stable shape, e.g. `{ "error": { "code": "string", "message": "string" }, "details"?: ... }` for 4xx/5xx, instead of only `{ "error": "string" }`. Validation errors can map into `details`. Implement gradually in route handlers. +**Error JSON (implemented):** 4xx/5xx bodies use the canonical shape `{ "error": { "code": "string", "message": "string" }, "details"?: ... }`. Codes come from the `ApiErrorCode` union in [`lib/server/responses.ts`](../lib/server/responses.ts) (helpers: `errorJson`, `dbUnavailable`, `unauthorized`, `notFound`, `rateLimited`, `serverMisconfigured`, `internalError`); validation failures use [`jsonFromZodError`](../lib/server/validation/zodHttp.ts) and surface flattened issues in `details`. **Migrated:** auth (`/api/auth/*`), drafts (`/api/drafts/me`), rules (`/api/rules`, `/api/rules/[id]`). Remaining `app/api/*` handlers (e.g. `web-vitals`, `templates`, `create-flow/methods`, `health`) are a follow-up pass; new routes should adopt the helpers from day one. -**Logging:** Use the shared [`lib/logger.ts`](../lib/logger.ts) where possible. Include a **request correlation id** (reuse `x-request-id` if present, else generate) on API routes and log it with errors so support can tie logs together. +**Logging:** Use the shared [`lib/logger.ts`](../lib/logger.ts) where possible. Wrap route handlers with [`apiRoute(scope, handler)`](../lib/server/apiRoute.ts) so a sanitized `x-request-id` is generated (or forwarded) onto every response and uncaught throws return the canonical 500 with the id logged via `logRouteError` ([`lib/server/requestId.ts`](../lib/server/requestId.ts)). Pass the `requestId` through to in-handler `logRouteError(scope, requestId, err, extra?)` calls when catching expected failures (e.g. mail send) so support can tie logs together. **Metrics:** No vendor required for v1; optional later: request duration, error counts. diff --git a/lib/server/apiRoute.ts b/lib/server/apiRoute.ts new file mode 100644 index 0000000..3c68be3 --- /dev/null +++ b/lib/server/apiRoute.ts @@ -0,0 +1,45 @@ +import type { NextRequest, NextResponse } from "next/server"; +import { internalError } from "./responses"; +import { + getOrCreateRequestId, + logRouteError, + withRequestId, +} from "./requestId"; + +export interface ApiRouteMeta { + requestId: string; +} + +export type ApiHandler = ( + request: NextRequest, + ctx: Ctx, + meta: ApiRouteMeta, +) => Promise | NextResponse; + +/** + * Minimal wrapper around a Route Handler that: + * + * - generates or forwards an `x-request-id`, + * - attaches that id to every response (success and error), + * - catches uncaught throws, logs them with the id via `lib/logger`, and + * returns the canonical 500 `internal_error` body. + * + * Pass a `scope` like `"auth.magicLink.request"` so logs are filterable per + * route. Handlers that don't need request-id correlation can skip the + * wrapper. + */ +export function apiRoute( + scope: string, + handler: ApiHandler, +): (request: NextRequest, ctx: Ctx) => Promise { + return async (request, ctx) => { + const requestId = getOrCreateRequestId(request); + try { + const res = await handler(request, ctx, { requestId }); + return withRequestId(res, requestId); + } catch (err) { + logRouteError(scope, requestId, err); + return withRequestId(internalError(), requestId); + } + }; +} diff --git a/lib/server/requestId.ts b/lib/server/requestId.ts new file mode 100644 index 0000000..8f865e1 --- /dev/null +++ b/lib/server/requestId.ts @@ -0,0 +1,70 @@ +import type { NextResponse } from "next/server"; +import { logger } from "../logger"; + +export const REQUEST_ID_HEADER = "x-request-id"; + +const MAX_REQUEST_ID_LENGTH = 128; +const REQUEST_ID_PATTERN = /^[A-Za-z0-9_.-]+$/; + +/** + * Returns the incoming `x-request-id` header (sanitized) when present and + * well-formed, otherwise generates a fresh UUID. Sanitization rejects + * oversized values and characters outside `[A-Za-z0-9_.-]` so log lines + * cannot be poisoned by client-controlled input. + */ +export function getOrCreateRequestId(request: Request): string { + const raw = request.headers.get(REQUEST_ID_HEADER); + if (raw) { + const trimmed = raw.trim(); + if ( + trimmed.length > 0 && + trimmed.length <= MAX_REQUEST_ID_LENGTH && + REQUEST_ID_PATTERN.test(trimmed) + ) { + return trimmed; + } + } + return crypto.randomUUID(); +} + +/** + * Attach the request id to a response so callers (and log drains) can + * correlate logs with the response. Returns the same response for chaining. + */ +export function withRequestId( + res: T, + requestId: string, +): T { + res.headers.set(REQUEST_ID_HEADER, requestId); + return res; +} + +interface ErrorLogPayload { + scope: string; + requestId: string; + message: string; + stack?: string; + [key: string]: unknown; +} + +/** + * Structured error log including the request id. Use from route handlers + * (and the `apiRoute` wrapper) so support can tie a 5xx back to log lines. + */ +export function logRouteError( + scope: string, + requestId: string, + err: unknown, + extra?: Record, +): void { + const payload: ErrorLogPayload = { + scope, + requestId, + message: err instanceof Error ? err.message : String(err), + ...(extra ?? {}), + }; + if (err instanceof Error && err.stack) { + payload.stack = err.stack; + } + logger.error(payload); +} diff --git a/lib/server/responses.ts b/lib/server/responses.ts index 0ccfe6a..9eed8f2 100644 --- a/lib/server/responses.ts +++ b/lib/server/responses.ts @@ -1,8 +1,83 @@ import { NextResponse } from "next/server"; +/** + * Canonical API error contract for `app/api/**`. + * + * Response body shape: `{ error: { code, message }, details? }`. + * + * Codes are kept intentionally small. Add a new code only when an existing + * one cannot describe the failure; route handlers should not invent codes + * inline (use `errorJson(code, …)` here so the union stays the source of + * truth). + */ +export type ApiErrorCode = + | "db_unavailable" + | "unauthorized" + | "forbidden" + | "not_found" + | "validation_error" + | "invalid_json" + | "payload_too_large" + | "rate_limited" + | "server_misconfigured" + | "mail_failed" + | "internal_error"; + +export interface ApiErrorBody { + error: { code: ApiErrorCode; message: string }; + details?: unknown; +} + +interface ErrorOpts { + details?: unknown; + headers?: HeadersInit; +} + +export function errorJson( + code: ApiErrorCode, + message: string, + status: number, + opts: ErrorOpts = {}, +): NextResponse { + const body: ApiErrorBody = { error: { code, message } }; + if (opts.details !== undefined) { + body.details = opts.details; + } + return NextResponse.json(body, { status, headers: opts.headers }); +} + export function dbUnavailable(): NextResponse { - return NextResponse.json( - { error: "Database is not configured (DATABASE_URL)." }, - { status: 503 }, + return errorJson( + "db_unavailable", + "Database is not configured (DATABASE_URL).", + 503, ); } + +export function unauthorized(message = "Unauthorized"): NextResponse { + return errorJson("unauthorized", message, 401); +} + +export function notFound(message = "Not found"): NextResponse { + return errorJson("not_found", message, 404); +} + +export function rateLimited(retryAfterMs: number): NextResponse { + const retryAfterSec = Math.max(1, Math.ceil(retryAfterMs / 1000)); + return errorJson("rate_limited", "Too many requests", 429, { + details: { retryAfterMs }, + headers: { "retry-after": String(retryAfterSec) }, + }); +} + +export function serverMisconfigured( + message = "Server misconfiguration", +): NextResponse { + return errorJson("server_misconfigured", message, 500); +} + +export function internalError( + message = "Internal server error", +): NextResponse { + return errorJson("internal_error", message, 500); +} diff --git a/tests/unit/apiRoute.test.ts b/tests/unit/apiRoute.test.ts new file mode 100644 index 0000000..429e2b8 --- /dev/null +++ b/tests/unit/apiRoute.test.ts @@ -0,0 +1,86 @@ +import { NextRequest, NextResponse } from "next/server"; +import { afterEach, describe, expect, it, vi } from "vitest"; + +const errorMock = vi.fn(); +vi.mock("../../lib/logger", () => ({ + logger: { + debug: vi.fn(), + info: vi.fn(), + warn: vi.fn(), + error: (...args: unknown[]) => errorMock(...args), + }, +})); + +import { apiRoute } from "../../lib/server/apiRoute"; +import { REQUEST_ID_HEADER } from "../../lib/server/requestId"; + +afterEach(() => { + errorMock.mockReset(); +}); + +function makeReq(headers: Record = {}): NextRequest { + return new NextRequest("https://x.test/api/x", { headers }); +} + +describe("lib/server/apiRoute", () => { + it("attaches a generated x-request-id to a successful response", async () => { + const handler = apiRoute("test.scope", () => + NextResponse.json({ ok: true }), + ); + const res = await handler(makeReq(), undefined); + expect(res.status).toBe(200); + const id = res.headers.get(REQUEST_ID_HEADER); + expect(id).toBeTruthy(); + expect(id).toMatch( + /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/, + ); + }); + + it("forwards an incoming x-request-id and exposes it to the handler", async () => { + const incoming = "req_forwarded-1"; + let seen: string | undefined; + const handler = apiRoute("test.scope", (_req, _ctx, { requestId }) => { + seen = requestId; + return NextResponse.json({ ok: true }); + }); + const res = await handler( + makeReq({ [REQUEST_ID_HEADER]: incoming }), + undefined, + ); + expect(seen).toBe(incoming); + expect(res.headers.get(REQUEST_ID_HEADER)).toBe(incoming); + }); + + it("returns canonical 500 + logs when the handler throws", async () => { + const handler = apiRoute("test.scope", () => { + throw new Error("boom"); + }); + const res = await handler(makeReq(), undefined); + expect(res.status).toBe(500); + const body = (await res.json()) as { + error: { code: string; message: string }; + }; + expect(body.error.code).toBe("internal_error"); + expect(res.headers.get(REQUEST_ID_HEADER)).toBeTruthy(); + + expect(errorMock).toHaveBeenCalledTimes(1); + const payload = errorMock.mock.calls[0][0] as Record; + expect(payload.scope).toBe("test.scope"); + expect(payload.requestId).toBe(res.headers.get(REQUEST_ID_HEADER)); + expect(payload.message).toBe("boom"); + }); + + it("passes the route ctx through to the handler", async () => { + type Ctx = { params: Promise<{ id: string }> }; + const handler = apiRoute("test.scope", async (_req, ctx) => { + const { id } = await ctx.params; + return NextResponse.json({ id }); + }); + const res = await handler(makeReq(), { + params: Promise.resolve({ id: "abc" }), + }); + expect(res.status).toBe(200); + const body = (await res.json()) as { id: string }; + expect(body.id).toBe("abc"); + }); +}); diff --git a/tests/unit/draftsMeRoute.test.ts b/tests/unit/draftsMeRoute.test.ts new file mode 100644 index 0000000..456c680 --- /dev/null +++ b/tests/unit/draftsMeRoute.test.ts @@ -0,0 +1,100 @@ +import { NextRequest } from "next/server"; +import { beforeEach, describe, expect, it, vi } from "vitest"; + +const isDatabaseConfiguredMock = vi.fn(); +const getSessionUserMock = vi.fn(); +const findUniqueMock = vi.fn(); + +vi.mock("../../lib/server/env", () => ({ + isDatabaseConfigured: () => isDatabaseConfiguredMock(), +})); + +vi.mock("../../lib/server/db", () => ({ + prisma: { + ruleDraft: { + findUnique: (...args: unknown[]) => findUniqueMock(...args), + upsert: vi.fn(), + deleteMany: vi.fn(), + }, + }, +})); + +vi.mock("../../lib/server/session", () => ({ + getSessionUser: () => getSessionUserMock(), +})); + +import { GET } from "../../app/api/drafts/me/route"; + +beforeEach(() => { + isDatabaseConfiguredMock.mockReset(); + getSessionUserMock.mockReset(); + findUniqueMock.mockReset(); +}); + +describe("GET /api/drafts/me", () => { + it("returns 503 with the canonical shape when the database is not configured", async () => { + isDatabaseConfiguredMock.mockReturnValue(false); + const res = await GET( + new NextRequest("https://x.test/api/drafts/me"), + undefined, + ); + expect(res.status).toBe(503); + const body = (await res.json()) as { + error: { code: string; message: string }; + }; + expect(body.error.code).toBe("db_unavailable"); + expect(res.headers.get("x-request-id")).toBeTruthy(); + }); + + it("returns 401 unauthorized with the canonical shape when no session user", async () => { + isDatabaseConfiguredMock.mockReturnValue(true); + getSessionUserMock.mockResolvedValueOnce(null); + const res = await GET( + new NextRequest("https://x.test/api/drafts/me"), + undefined, + ); + expect(res.status).toBe(401); + const body = (await res.json()) as { + error: { code: string; message: string }; + }; + expect(body.error).toEqual({ + code: "unauthorized", + message: "Unauthorized", + }); + expect(res.headers.get("x-request-id")).toBeTruthy(); + expect(findUniqueMock).not.toHaveBeenCalled(); + }); + + it("forwards an incoming x-request-id on the response", async () => { + isDatabaseConfiguredMock.mockReturnValue(true); + getSessionUserMock.mockResolvedValueOnce(null); + const res = await GET( + new NextRequest("https://x.test/api/drafts/me", { + headers: { "x-request-id": "req_drafts-1" }, + }), + undefined, + ); + expect(res.headers.get("x-request-id")).toBe("req_drafts-1"); + }); + + it("returns the draft when present", async () => { + isDatabaseConfiguredMock.mockReturnValue(true); + getSessionUserMock.mockResolvedValueOnce({ + id: "u1", + email: "x@y.test", + }); + findUniqueMock.mockResolvedValueOnce({ + payload: { foo: 1 }, + updatedAt: new Date("2026-01-01T00:00:00Z"), + }); + const res = await GET( + new NextRequest("https://x.test/api/drafts/me"), + undefined, + ); + expect(res.status).toBe(200); + const body = (await res.json()) as { + draft: { payload: { foo: number } } | null; + }; + expect(body.draft?.payload).toEqual({ foo: 1 }); + }); +}); diff --git a/tests/unit/requestId.test.ts b/tests/unit/requestId.test.ts new file mode 100644 index 0000000..6df6ff9 --- /dev/null +++ b/tests/unit/requestId.test.ts @@ -0,0 +1,60 @@ +import { NextResponse } from "next/server"; +import { describe, expect, it } from "vitest"; +import { + REQUEST_ID_HEADER, + getOrCreateRequestId, + withRequestId, +} from "../../lib/server/requestId"; + +function reqWith(headers: Record): Request { + return new Request("https://x.test/api/x", { headers }); +} + +describe("lib/server/requestId", () => { + it("generates a UUID when no header is present", () => { + const id = getOrCreateRequestId(reqWith({})); + expect(id).toMatch( + /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/, + ); + }); + + it("preserves a well-formed incoming x-request-id", () => { + const incoming = "req_abc-123.456"; + const id = getOrCreateRequestId(reqWith({ [REQUEST_ID_HEADER]: incoming })); + expect(id).toBe(incoming); + }); + + it("trims surrounding whitespace from a well-formed id", () => { + const id = getOrCreateRequestId( + reqWith({ [REQUEST_ID_HEADER]: " abc-123 " }), + ); + expect(id).toBe("abc-123"); + }); + + it("rejects oversized ids and falls back to a UUID", () => { + const huge = "a".repeat(200); + const id = getOrCreateRequestId(reqWith({ [REQUEST_ID_HEADER]: huge })); + expect(id).not.toBe(huge); + expect(id).toMatch( + /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/, + ); + }); + + it("rejects ids with disallowed characters", () => { + // Spaces, semicolons, slashes are valid HTTP header bytes but disallowed + // by our `[A-Za-z0-9_.-]` pattern. + const bad = "abc def;