From d567933a69d857d80205d58d736e4d2dc813f1dd Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 05:00:54 +0000 Subject: [PATCH 01/18] perf(explore): convert /explore/programs to ISR, resolve org badges client-side MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The page was force-dynamic solely because getViewerOrgs() read the session (headers()) plus an uncached membership.findMany — all to power the "Recommended by " card badge. That one per-viewer read made the whole page CDN-uncacheable (private, no-cache, no-store), so every visit invoked the function and was exposed to the ~24s cold-instance stall (#1124). - Drop getViewerOrgs from the server render; derive viewerOrgs in ProgramsInteractiveContent from session.user.organizationMemberships — the session already carries the same ACTIVE-membership data (#664 intact). - export const revalidate = 300, mirroring /explore/experts. - Flip fail-open to withBuildTimeRetry + rethrow: on a cacheable route a degraded 200 would be written to the durable cache and replayed (#1123); a thrown render caches nothing and lands in the existing error.tsx. - Raise trending-id windows 60->300 and curated-programs 120->300 and tag the trending caches "programs": effective revalidate is the MIN of the segment value and every data-cache window read in the render (#1110). Consequence: the route now prerenders during next build and reads the shared Supabase at build time (#932); withBuildTimeRetry covers the cold pooler connect. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SKb2cFx2XCYrPKDrrENgqJ --- .../programs/ProgramsInteractiveContent.tsx | 19 +++- app/explore/programs/page.tsx | 92 +++++-------------- lib/data/explore-programs.ts | 15 +-- 3 files changed, 48 insertions(+), 78 deletions(-) diff --git a/app/explore/programs/ProgramsInteractiveContent.tsx b/app/explore/programs/ProgramsInteractiveContent.tsx index fbce657e7..75062a3d8 100644 --- a/app/explore/programs/ProgramsInteractiveContent.tsx +++ b/app/explore/programs/ProgramsInteractiveContent.tsx @@ -32,8 +32,6 @@ interface ProgramsInteractiveContentProps { initialNewest: Program[]; initialTopics: TopicWithCount[]; initialStats: ProgramStats | null; - /** #664 — viewer's ACTIVE org memberships as { orgId: orgName }. */ - viewerOrgs?: Record; /** Every level in the catalog, read server-side — not just loaded rows. */ availableLevels?: PlanLevel[]; } @@ -65,13 +63,28 @@ export default function ProgramsInteractiveContent({ initialNewest, initialTopics, initialStats, - viewerOrgs = {}, availableLevels = [], }: ProgramsInteractiveContentProps) { const { data: session } = useSession(); const userId = session?.user?.id; const { formatPrice } = useCurrency(); + // #664 — viewer's ACTIVE org memberships as { orgId: orgName }, for the + // "Recommended by " card badge. Resolved client-side from the session + // payload (the same memberships OrgSwitcher and checkout trust) rather than + // server-side: this page is ISR, so its shared HTML must stay free of + // viewer-specific markup. Badges appear once the session hydrates. + const viewerOrgs = useMemo>( + () => + Object.fromEntries( + (session?.user?.organizationMemberships ?? []).map((m) => [ + m.organizationId, + m.organizationName, + ]), + ), + [session], + ); + // All UI state lives in one hook so the orchestrator stays thin. const { programType, diff --git a/app/explore/programs/page.tsx b/app/explore/programs/page.tsx index 9f0e03646..3b0849196 100644 --- a/app/explore/programs/page.tsx +++ b/app/explore/programs/page.tsx @@ -2,41 +2,22 @@ import { getCuratedPrograms, getTopicsWithCount, } from "@/lib/data/explore-programs"; -import { - emptyOnTransientDbError, - fallbackOnTransientDbError, -} from "@/lib/data/fail-open"; +import { withBuildTimeRetry } from "@/lib/data/fail-open"; import { sortPlanLevels } from "@/lib/labels/plan-labels"; import { unstable_cache } from "next/cache"; import prisma from "@/lib/prisma"; -import { getSession } from "@/lib/auth-server"; import ProgramsInteractiveContent from "./ProgramsInteractiveContent"; -// #664 — the viewer's ACTIVE org memberships, as { orgId: orgName }. Viewer- -// specific, so it must NOT enter the shared curated cache — it's fetched -// per-request here and prop-drilled to the card, which badges a plan -// "Recommended by " when the viewer's org sponsors that plan's program. -// -// Signed-out returns {} here because that is an ANSWER, not a failure. Failure -// is handled at the call site by the same fail-open helper the four sibling -// reads use — this used to be a bare `catch { return {} }`, which swallowed -// every error class and would have silently dropped every org badge on a mapper -// or schema regression, indefinitely and with no signal. (#1125) -async function getViewerOrgs(): Promise> { - const session = await getSession(); - const userId = session?.user?.id; - if (!userId) return {}; - const memberships = await prisma.membership.findMany({ - where: { userId, status: "ACTIVE" }, - select: { organization: { select: { id: true, name: true } } }, - }); - return Object.fromEntries( - memberships.map((m) => [m.organization.id, m.organization.name]), - ); -} - -// Stream behind the static layout's instant skeleton; don't prerender at build (#932). -export const dynamic = "force-dynamic"; +// ISR: every read below is viewer-agnostic, so the page is the same for every +// visitor and an ISR copy served from the durable cache skips the function +// invocation entirely — the only lever that avoids the cold-instance stall +// (#1124). The one per-viewer bit, the "Recommended by " badge (#664), +// resolves in the browser from session.user.organizationMemberships inside +// ProgramsInteractiveContent; nothing viewer-specific may re-enter this +// server render or the route silently pins back to dynamic. +// 300 matches the data-layer windows: the route's effective revalidate is the +// MIN of this and every unstable_cache window read during the render (#1110). +export const revalidate = 300; /** * Server-fetch the trending / newest curated rows, the topic list, and the @@ -49,44 +30,18 @@ export const dynamic = "force-dynamic"; * `useCuratedPrograms` / `useTopicsWithCount` hooks. */ export default async function ExplorePrograms() { - // Degrade gracefully: a heavy curated read that times out (cold query brushing - // the pg query budget) renders an empty row instead of erroring the whole page. - const [ - trendingPrograms, - newestPrograms, - topicsWithCount, - stats, - viewerOrgs, - levels, - ] = await Promise.all([ - getCuratedPrograms("all", "trending", 8).catch( - emptyOnTransientDbError("trending programs", { perRequest: true }), - ), - getCuratedPrograms("all", "newest", 8).catch( - emptyOnTransientDbError("newest programs", { perRequest: true }), - ), - getTopicsWithCount("all").catch( - emptyOnTransientDbError("topics", { perRequest: true }), - ), - // `null` here means "show the marketing numbers instead", which the client - // already handles. Routed through the helper rather than a local catch so a - // real defect surfaces instead of quietly pinning the hero to placeholders. - getCachedProgramCounts().catch( - fallbackOnTransientDbError("program stats", null, { perRequest: true }), - ), - getViewerOrgs().catch( - fallbackOnTransientDbError>( - "viewer orgs", - {}, - { - perRequest: true, - }, - ), - ), - getCachedProgramLevels().catch( - emptyOnTransientDbError("program levels", { perRequest: true }), - ), - ]); + // These used to degrade to empty rows per-request. Now that this route is + // ISR, a degraded 200 would be written to the durable cache and replayed to + // everyone until the window expired (#1123) — so retry once during build and + // otherwise throw, which caches nothing and lands in error.tsx instead. + const [trendingPrograms, newestPrograms, topicsWithCount, stats, levels] = + await Promise.all([ + withBuildTimeRetry(() => getCuratedPrograms("all", "trending", 8)), + withBuildTimeRetry(() => getCuratedPrograms("all", "newest", 8)), + withBuildTimeRetry(() => getTopicsWithCount("all")), + withBuildTimeRetry(getCachedProgramCounts), + withBuildTimeRetry(getCachedProgramLevels), + ]); return ( ); diff --git a/lib/data/explore-programs.ts b/lib/data/explore-programs.ts index a7c0d9169..e98f37994 100644 --- a/lib/data/explore-programs.ts +++ b/lib/data/explore-programs.ts @@ -72,10 +72,13 @@ const liveConsultantWhere = { * count of 0 and stay in the ranking — dropping them empties the Trending row * in a quiet window. * - * The scan is shared across requests for 60s via unstable_cache; the cached + * The scan is shared across requests for 300s via unstable_cache; the cached * value is the FULL ranked id array (callers slice — passing limit as an arg * would key separate entries). Staleness is harmless: trending order changing - * 60s late is invisible. + * a few minutes late is invisible. The window matches /explore/programs' + * `revalidate = 300` — a route's effective revalidate is the MIN of its + * segment value and every data-cache window read during the render (#1110), + * so a shorter window here would silently cap the route. */ /** Slot window shared by both plan families. */ const recentSlotWindow = () => { @@ -128,7 +131,7 @@ const getTrendingClassPlanIds = unstable_cache( ); }, ["trending-class-plan-ids"], - { revalidate: 60 }, + { revalidate: 300, tags: ["programs"] }, ); const getTrendingWebinarPlanIds = unstable_cache( @@ -156,7 +159,7 @@ const getTrendingWebinarPlanIds = unstable_cache( ); }, ["trending-webinar-plan-ids"], - { revalidate: 60 }, + { revalidate: 300, tags: ["programs"] }, ); /** @@ -241,7 +244,7 @@ export const getCuratedPrograms = unstable_cache( let webinarPlans; if (sort === "trending") { - // Shared 60s ranking cache — full list, sliced per caller (see the + // Shared 300s ranking cache — full list, sliced per caller (see the // class-plan twin above for why no limit arg). const sortedIds = (await getTrendingWebinarPlanIds()).slice(0, limit); @@ -300,7 +303,7 @@ export const getCuratedPrograms = unstable_cache( return toPlain(programs.slice(0, limit)); }, ["curated-programs"], - { revalidate: 120, tags: ["programs"] }, + { revalidate: 300, tags: ["programs"] }, ); // --------------------------------------------------------------------------- From ebfe492c9c4a5f90f5ddeaca4d01f38dbdd21dee Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 05:03:39 +0000 Subject: [PATCH 02/18] perf(explore): seed the experts browse grid from the ISR render MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The page server-rendered curated rows but the main grid still client-fetched /api/user/consultants on mount with no initialData — a second skeleton pass after the shell arrived. Add page 1 of the default view (the same cached getDefaultConsultantsPage the API's isDefaultView path serves) to the page's awaited reads and hand it to useConsultants as React Query initialData. The seed applies only when the filters are exactly DEFAULT_EXPERT_FILTERS — the client-side mirror of the API's isDefaultView predicate — so deep links like ?sort=rating keep their normal fetch. The query key is built purely from filter state (never the session), so server and client derive the identical key value on first render. Raise default-consultants-page's window 60->300: the route now reads it during the ISR render, and the effective revalidate is the MIN of the segment value and every data-cache window read (#1110). Freshness on writes still comes from purgeExpertSurfaces' revalidateTag("experts"). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SKb2cFx2XCYrPKDrrENgqJ --- .../experts/ExpertsInteractiveContent.tsx | 7 ++- app/explore/experts/hooks/useConsultants.ts | 48 ++++++++++++++++++- app/explore/experts/page.tsx | 31 +++++++++--- lib/data/explore-experts.ts | 10 ++-- 4 files changed, 83 insertions(+), 13 deletions(-) diff --git a/app/explore/experts/ExpertsInteractiveContent.tsx b/app/explore/experts/ExpertsInteractiveContent.tsx index 4322e1d34..9b3a933c2 100644 --- a/app/explore/experts/ExpertsInteractiveContent.tsx +++ b/app/explore/experts/ExpertsInteractiveContent.tsx @@ -14,6 +14,7 @@ import { useInfiniteScroll, useExpertFilterChips, } from "./hooks"; +import type { ConsultantsPage } from "./hooks/useConsultants"; import type { IExpertsMetaData, AffiliationType } from "./utils"; import { FilterPanel } from "./components/FilterPanel"; import { SearchBar, type SortOption } from "./components/SearchBar"; @@ -34,12 +35,16 @@ interface ExpertsInteractiveContentProps { metadata: IExpertsMetaData | null; trendingExperts: IConsultantCardData[]; newestExperts: IConsultantCardData[]; + /** Server-rendered page 1 of the default (unfiltered) grid — seeds the + * main listing query so first paint skips the client fetch. */ + initialConsultantsPage?: ConsultantsPage; } export default function ExpertsInteractiveContent({ metadata, trendingExperts, newestExperts, + initialConsultantsPage, }: ExpertsInteractiveContentProps) { const { filters, updateFilters, clearFilters } = useExpertsFilters(); const browseSectionRef = useRef(null); @@ -54,7 +59,7 @@ export default function ExpertsInteractiveContent({ isRefetching, hasMore, loadMore, - } = useConsultants(filters); + } = useConsultants(filters, initialConsultantsPage); // Sentinel-driven infinite scroll. The hook owns the IntersectionObserver // lifecycle (one observer per hasMore/isLoading transition, not one per diff --git a/app/explore/experts/hooks/useConsultants.ts b/app/explore/experts/hooks/useConsultants.ts index fdb7be7da..7db10e850 100644 --- a/app/explore/experts/hooks/useConsultants.ts +++ b/app/explore/experts/hooks/useConsultants.ts @@ -3,7 +3,40 @@ import { useInfiniteQuery, keepPreviousData } from "@tanstack/react-query"; import { useCallback, useMemo } from "react"; import type { IConsultantCardData } from "@/types/consultant"; -import { CONSULTANTS_PER_PAGE, type IExpertFilters } from "../utils"; +import { + CONSULTANTS_PER_PAGE, + DEFAULT_EXPERT_FILTERS, + type IExpertFilters, +} from "../utils"; + +/** One page of /api/user/consultants — also the shape of the RSC-seeded + * default page from getDefaultConsultantsPage (same function backs both). */ +export interface ConsultantsPage { + data: IConsultantCardData[]; + meta: { total: number; page: number; limit: number; totalPages: number }; +} + +// Seed only the exact query the server pre-rendered: the unfiltered default +// view (the API's isDefaultView predicate). A deep link like ?sort=rating has +// a different key and must fetch normally — seeding it with the nameAsc page +// would show wrongly-ordered results without a refetch. +function isDefaultExpertFilters(filters: IExpertFilters): boolean { + const d = DEFAULT_EXPERT_FILTERS; + return ( + filters.domain === d.domain && + filters.subdomain === d.subdomain && + filters.tags.length === 0 && + filters.experience === d.experience && + filters.search === d.search && + filters.sort === d.sort && + filters.minPrice === d.minPrice && + filters.maxPrice === d.maxPrice && + filters.minRating === d.minRating && + filters.companies.length === 0 && + filters.language === d.language && + filters.affiliationType === d.affiliationType + ); +} // Enhanced React Query fetcher function with error handling for consultants const fetchConsultantsData = async (url: string) => { @@ -24,7 +57,10 @@ const fetchConsultantsData = async (url: string) => { return res.json(); }; -export function useConsultants(filters: IExpertFilters) { +export function useConsultants( + filters: IExpertFilters, + initialPage?: ConsultantsPage, +) { const { domain: selectedDomain, subdomain: selectedSubdomain, @@ -112,6 +148,14 @@ export function useConsultants(filters: IExpertFilters) { return undefined; }, initialPageParam: 0, + // The RSC already rendered page 1 of the default view — hand it to React + // Query so the grid paints data instead of a second skeleton pass and no + // duplicate /api/user/consultants request fires on mount. The key is + // built purely from filter state (never the session), so server and + // client derive the identical key value from the first render. + ...(initialPage && isDefaultExpertFilters(filters) + ? { initialData: { pages: [initialPage], pageParams: [0] } } + : {}), placeholderData: keepPreviousData, staleTime: 2 * 60 * 1000, gcTime: 10 * 60 * 1000, diff --git a/app/explore/experts/page.tsx b/app/explore/experts/page.tsx index b635b245e..27f22bc5e 100644 --- a/app/explore/experts/page.tsx +++ b/app/explore/experts/page.tsx @@ -5,8 +5,10 @@ import ExpertsInteractiveContent from "./ExpertsInteractiveContent"; import { getExpertsMetadata, getCuratedExperts, + getDefaultConsultantsPage, } from "@/lib/data/explore-experts"; import { withBuildTimeRetry } from "@/lib/data/fail-open"; +import { CONSULTANTS_PER_PAGE } from "./utils"; // ISR, not force-dynamic. This listing reads no session and takes no // searchParams (filtering happens in the client component below), so the @@ -99,13 +101,27 @@ export default async function ExploreExperts() { // These used to degrade to empty rows on a transient timeout. This route is ISR, // so that empty page would be cached and served to everyone until the window // expired; retry once and otherwise throw, which caches nothing (#1119). - const [metadata, featuredExperts, trendingExperts, newestExperts] = - await Promise.all([ - withBuildTimeRetry(getExpertsMetadata), - withBuildTimeRetry(() => getCuratedExperts("rating", 5)), - withBuildTimeRetry(() => getCuratedExperts("trending", 8)), - withBuildTimeRetry(() => getCuratedExperts("newest", 8)), - ]); + const [ + metadata, + featuredExperts, + trendingExperts, + newestExperts, + initialConsultantsPage, + ] = await Promise.all([ + withBuildTimeRetry(getExpertsMetadata), + withBuildTimeRetry(() => getCuratedExperts("rating", 5)), + withBuildTimeRetry(() => getCuratedExperts("trending", 8)), + withBuildTimeRetry(() => getCuratedExperts("newest", 8)), + // Page 1 of the default grid — the same cached read the API's default + // view serves. Seeds the client useConsultants query so the browse grid + // paints with the HTML instead of a second skeleton-then-fetch pass. + // "nameAsc" must stay in sync with DEFAULT_EXPERT_FILTERS.sort: the + // client only applies this seed when its filters are exactly the + // defaults, so a mismatched sort here would go unused, not mis-render. + withBuildTimeRetry(() => + getDefaultConsultantsPage("nameAsc", CONSULTANTS_PER_PAGE), + ), + ]); return (
@@ -142,6 +158,7 @@ export default async function ExploreExperts() { metadata={metadata} trendingExperts={trendingExperts} newestExperts={newestExperts} + initialConsultantsPage={initialConsultantsPage} />
diff --git a/lib/data/explore-experts.ts b/lib/data/explore-experts.ts index b842cc1f3..c848a77f6 100644 --- a/lib/data/explore-experts.ts +++ b/lib/data/explore-experts.ts @@ -383,8 +383,12 @@ export const getCuratedExperts = unstable_cache( // data cache instead of opening a cross-region pooled connection on every load. // Tagged "experts" (same as getCuratedExperts) so it is cleared by the // revalidateTag("experts") that consultant verify/edit/delete now fires via -// purgeExpertSurfaces (lib/data/public-cache.ts); the 60s revalidate is the -// backstop. (#945 — pairs with the route's no-store fail-open; #932 caching.) +// purgeExpertSurfaces (lib/data/public-cache.ts); the 300s revalidate is the +// backstop. 300 (not 60) because /explore/experts now reads this during its +// ISR render to seed the browse grid, and a route's effective revalidate is +// the MIN of its segment value and every data-cache window read during the +// render (#1110) — 60 here would silently cap the route's declared 300. +// (#945 — pairs with the route's no-store fail-open; #932 caching.) export const getDefaultConsultantsPage = unstable_cache( async (sort: string, limit: number) => { const where: Prisma.ConsultantProfileWhereInput = { @@ -406,5 +410,5 @@ export const getDefaultConsultantsPage = unstable_cache( }; }, ["default-consultants-page"], - { revalidate: 60, tags: ["experts"] }, + { revalidate: 300, tags: ["experts"] }, ); From d6d87abbf3dc31df7efb0b7e293e11608bcd7741 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 05:12:12 +0000 Subject: [PATCH 03/18] perf(explore): seed the All Programs grid and smooth the session key flip MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The programs grid client-fetched /api/plans/classes + /api/plans/webinars on mount with no initialData — a second skeleton pass — and its query key contains the useSession() userId, so the session resolving mid-mount flipped the key and re-skeletoned the grid a third time for signed-in users. - Add placeholderData: keepPreviousData to usePrograms (mirrors useConsultants): key changes keep the previous rows on screen during the refetch. The signed-in refetch itself is preserved — it recomputes isRegistered. - New getDefaultProgramsPage (unstable_cache, 300s, tag "programs"): the server-side twin of the client's first fetch (page 1, limit 12, anonymous, include=classes), passed down and applied as initialData only on the anonymous unfiltered "all" key — exactly the query the server rendered. - Extract the queryFn's response->page mapping into buildProgramsPage, used by both the live fetch and the seed, so the seeded page cannot drift from what a real fetch produces. - Move the plan list where/orderBy/parse builders to lib/api/plans/plan-filters.ts (app/api/plans/shared/plan-filters.ts is now a re-export shim) and extract the routes' include shapes to lib/api/plans/plan-includes.ts, shared by both routes and the seed — lib/ must not import from app/, and hand-copied clauses would drift from the visibility rules (#726, #catalog-archive). Guard test updated to read the new location. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SKb2cFx2XCYrPKDrrENgqJ --- __tests__/enterprise/catalog-archive.test.ts | 4 +- app/api/plans/classes/route.ts | 82 +------ app/api/plans/shared/plan-filters.ts | 159 ++------------ app/api/plans/webinars/route.ts | 72 +------ .../programs/ProgramsInteractiveContent.tsx | 6 + app/explore/programs/hooks/usePrograms.ts | 203 +++++++++++------- app/explore/programs/page.tsx | 28 ++- lib/api/plans/plan-filters.ts | 157 ++++++++++++++ lib/api/plans/plan-includes.ts | 106 +++++++++ lib/data/explore-programs.ts | 90 +++++++- 10 files changed, 532 insertions(+), 375 deletions(-) create mode 100644 lib/api/plans/plan-filters.ts create mode 100644 lib/api/plans/plan-includes.ts diff --git a/__tests__/enterprise/catalog-archive.test.ts b/__tests__/enterprise/catalog-archive.test.ts index b90d717db..1c32006f6 100644 --- a/__tests__/enterprise/catalog-archive.test.ts +++ b/__tests__/enterprise/catalog-archive.test.ts @@ -27,7 +27,9 @@ import { join } from "path"; const read = (rel: string) => readFileSync(join(process.cwd(), rel), "utf8"); const CATALOG_ROUTE = "app/api/organizations/[orgId]/catalog/route.ts"; -const PLAN_FILTERS = "app/api/plans/shared/plan-filters.ts"; +// Moved from app/api/plans/shared/plan-filters.ts (now a re-export shim) so +// lib/data/explore-programs.ts can share the builders without importing app/. +const PLAN_FILTERS = "lib/api/plans/plan-filters.ts"; const VISIBILITY = "lib/api/plans/visibility.ts"; const EXPLORE = "lib/data/explore-programs.ts"; const SCHEMA = "prisma/schema.prisma"; diff --git a/app/api/plans/classes/route.ts b/app/api/plans/classes/route.ts index 8f3c092d9..56efffd08 100644 --- a/app/api/plans/classes/route.ts +++ b/app/api/plans/classes/route.ts @@ -1,6 +1,6 @@ import prisma from "@/lib/prisma"; import { NextRequest, NextResponse } from "next/server"; -import { CollaboratorStatus, PlanEmailSupport, Prisma } from "@prisma/client"; +import { PlanEmailSupport, Prisma } from "@prisma/client"; import { parsePlanFilters, buildPlanWhereClause, @@ -8,6 +8,7 @@ import { paginatedResponse, rankAndPaginate, } from "../shared/plan-filters"; +import { classPlanListInclude } from "@/lib/api/plans/plan-includes"; import { requireApiAuth, isPrivileged, @@ -28,80 +29,11 @@ export async function GET(request: NextRequest) { | Prisma.ClassPlanOrderByWithRelationInput | undefined; - // Build classes include based on whether registration data is requested - let classesInclude: boolean | Record = true; - if (includeRegistration) { - classesInclude = { - include: { - appointments: { - include: { - slotsOfAppointment: { - include: { - user: { select: { id: true } }, - }, - }, - }, - }, - }, - }; - } - - const includeOptions = { - consultantProfile: { - include: { - user: { - select: { - name: true, - image: true, - workExperiences: { - select: { - company: true, - companyDomain: true, - isCurrent: true, - }, - orderBy: [ - { isCurrent: "desc" as const }, - { startDate: "desc" as const }, - ], - take: 3, - }, - }, - }, - }, - }, - topics: true, - classContents: true, - collaborators: { - where: { status: CollaboratorStatus.ACCEPTED }, - include: { - consultantProfile: { - include: { - user: { - select: { - name: true, - image: true, - workExperiences: { - select: { - company: true, - companyDomain: true, - isCurrent: true, - }, - orderBy: [ - { isCurrent: "desc" as const }, - { startDate: "desc" as const }, - ], - take: 3, - }, - }, - }, - }, - }, - }, - }, - ...((includeClasses || includeRegistration) && { - classes: classesInclude, - }), - }; + // Shared with the /explore/programs RSC seed — see plan-includes.ts. + const includeOptions = classPlanListInclude({ + includeClasses: !!includeClasses, + includeRegistration, + }); // For trending sort, use a two-step Prisma approach: // 1. Lightweight select (IDs + nested slot IDs only) to rank by enrollment count diff --git a/app/api/plans/shared/plan-filters.ts b/app/api/plans/shared/plan-filters.ts index e7197060d..47eb79bd3 100644 --- a/app/api/plans/shared/plan-filters.ts +++ b/app/api/plans/shared/plan-filters.ts @@ -1,152 +1,17 @@ import { NextResponse } from "next/server"; -import { Prisma, type OrgPlanVisibility } from "@prisma/client"; -import { MARKETPLACE_VISIBILITY } from "@/lib/api/plans/visibility"; -export interface PlanFilterParams { - consultantId: string | null; - topicIds: string | null; - language: string | null; - domainId: string | null; - sort: string | null; - minPrice: number | undefined; - maxPrice: number | undefined; - search: string | null; - level: string | null; - page: number; - limit: number; - skip: number; -} - -/** - * Parse filter query params from a URLSearchParams with NaN guards on numeric values. - */ -export function parsePlanFilters( - searchParams: URLSearchParams, -): PlanFilterParams { - const page = parseInt(searchParams.get("page") || "1") || 1; - const limit = parseInt(searchParams.get("limit") || "10") || 10; - const skip = (page - 1) * limit; - - const rawMin = searchParams.get("minPrice"); - const rawMax = searchParams.get("maxPrice"); - const parsedMin = rawMin ? parseInt(rawMin) : undefined; - const parsedMax = rawMax ? parseInt(rawMax) : undefined; - - return { - consultantId: searchParams.get("consultantId"), - topicIds: searchParams.get("topicIds"), - language: searchParams.get("language"), - domainId: searchParams.get("domainId"), - sort: searchParams.get("sort"), - minPrice: - parsedMin !== undefined && !isNaN(parsedMin) ? parsedMin : undefined, - maxPrice: - parsedMax !== undefined && !isNaN(parsedMax) ? parsedMax : undefined, - search: searchParams.get("search"), - // "all" is the UI's no-op sentinel, not a stored level value. - level: - searchParams.get("level") === "all" ? null : searchParams.get("level"), - page, - limit, - skip, - }; -} - -/** - * Shared plan WHERE clause — structurally compatible with both - * Prisma.WebinarPlanWhereInput and Prisma.ClassPlanWhereInput. - */ -export interface PlanWhereClause { - consultantProfileId?: string; - language?: string; - level?: string; - price?: { gte?: number; lte?: number }; - title?: { contains: string; mode: "insensitive" }; - topics?: { some: { id: { in: string[] } } }; - consultantProfile?: { domainId: string }; - visibility?: { in: OrgPlanVisibility[] }; - /** #catalog-archive — `null` keeps withdrawn plans out of public lists. */ - archivedAt?: null; -} - -/** - * Build a Prisma where clause from parsed plan filters. - * The returned object is structurally compatible with both - * Prisma.WebinarPlanWhereInput and Prisma.ClassPlanWhereInput. - */ -export function buildPlanWhereClause( - filters: PlanFilterParams, -): PlanWhereClause { - // #726 — public marketplace must not surface ORG_ONLY plans. The filter - // is applied unconditionally here because every caller of this helper - // is a public surface; org-internal catalog endpoints have their own - // where-builders. - // #catalog-archive — an archived plan is withdrawn from sale. It is kept - // rather than deleted because the row carries the terms of every booking made - // against it (and the FK chain cascades to Payment), so discovery has to - // filter it out explicitly. Same reasoning as the visibility gate above: every - // caller here is a public surface. - const where: PlanWhereClause = { - visibility: { in: MARKETPLACE_VISIBILITY }, - archivedAt: null, - }; - - if (filters.consultantId) { - where.consultantProfileId = filters.consultantId; - } - if (filters.language) { - where.language = filters.language; - } - // Level used to be filtered client-side over the already-loaded infinite-scroll - // page, so a matching program on a later page simply never appeared. - if (filters.level) { - where.level = filters.level; - } - if (filters.minPrice !== undefined || filters.maxPrice !== undefined) { - const price: { gte?: number; lte?: number } = {}; - if (filters.minPrice !== undefined) price.gte = filters.minPrice; - if (filters.maxPrice !== undefined) price.lte = filters.maxPrice; - where.price = price; - } - if (filters.search) { - where.title = { contains: filters.search, mode: "insensitive" }; - } - if (filters.topicIds) { - const ids = filters.topicIds.split(",").filter(Boolean); - if (ids.length > 0) { - where.topics = { some: { id: { in: ids } } }; - } - } - if (filters.domainId) { - where.consultantProfile = { domainId: filters.domainId }; - } - - return where; -} - -/** - * Shared plan ORDER BY clause — structurally compatible with both - * Prisma.WebinarPlanOrderByWithRelationInput and Prisma.ClassPlanOrderByWithRelationInput. - */ -export interface PlanOrderByClause { - createdAt?: Prisma.SortOrder; - price?: Prisma.SortOrder; - title?: Prisma.SortOrder; -} - -/** - * Build a Prisma orderBy object from a sort string. - */ -export function buildPlanOrderBy( - sort: string | null, -): PlanOrderByClause | undefined { - if (sort === "newest") return { createdAt: "desc" }; - if (sort === "price-asc") return { price: "asc" }; - if (sort === "price-desc") return { price: "desc" }; - if (sort === "title-asc") return { title: "asc" }; - if (sort === "title-desc") return { title: "desc" }; - return undefined; -} +// The query builders live in lib/api/plans/plan-filters.ts so that +// lib/data/explore-programs.ts (the /explore/programs RSC seed) can share +// them — lib/ must not import from app/. Re-exported here to keep the +// routes' existing import paths working. +export { + parsePlanFilters, + buildPlanWhereClause, + buildPlanOrderBy, + type PlanFilterParams, + type PlanWhereClause, + type PlanOrderByClause, +} from "@/lib/api/plans/plan-filters"; /** * Build a standard paginated JSON response. diff --git a/app/api/plans/webinars/route.ts b/app/api/plans/webinars/route.ts index 3630952cb..02ec18fc5 100644 --- a/app/api/plans/webinars/route.ts +++ b/app/api/plans/webinars/route.ts @@ -9,6 +9,7 @@ import { paginatedResponse, rankAndPaginate, } from "../shared/plan-filters"; +import { webinarPlanListInclude } from "@/lib/api/plans/plan-includes"; import { requireApiAuth, isPrivileged, @@ -28,75 +29,8 @@ export async function GET(request: NextRequest) { | Prisma.WebinarPlanOrderByWithRelationInput | undefined; - // Build include object based on whether registration data is requested - const include: Record = { - consultantProfile: { - include: { - user: { - select: { - name: true, - image: true, - workExperiences: { - select: { - company: true, - companyDomain: true, - isCurrent: true, - }, - orderBy: [ - { isCurrent: "desc" as const }, - { startDate: "desc" as const }, - ], - take: 3, - }, - }, - }, - }, - }, - topics: true, - collaborators: { - where: { status: "ACCEPTED" }, - include: { - consultantProfile: { - include: { - user: { - select: { - name: true, - image: true, - workExperiences: { - select: { - company: true, - companyDomain: true, - isCurrent: true, - }, - orderBy: [ - { isCurrent: "desc" as const }, - { startDate: "desc" as const }, - ], - take: 3, - }, - }, - }, - }, - }, - }, - }, - }; - - if (includeRegistration) { - include.webinars = { - include: { - appointment: { - include: { - slotsOfAppointment: { - include: { - user: { select: { id: true } }, - }, - }, - }, - }, - }, - }; - } + // Shared with the /explore/programs RSC seed — see plan-includes.ts. + const include = webinarPlanListInclude({ includeRegistration }); // For trending sort, use a two-step Prisma approach: // 1. Lightweight select (IDs + nested slot IDs only) to rank by enrollment count diff --git a/app/explore/programs/ProgramsInteractiveContent.tsx b/app/explore/programs/ProgramsInteractiveContent.tsx index 75062a3d8..1aca9c0ca 100644 --- a/app/explore/programs/ProgramsInteractiveContent.tsx +++ b/app/explore/programs/ProgramsInteractiveContent.tsx @@ -7,6 +7,7 @@ import { GraduationCap, Video, Users, Sparkles } from "lucide-react"; import { useSession } from "@/lib/auth-client"; import { useCurrency } from "@/hooks/useCurrency"; import { type Program, type TopicWithCount } from "@/lib/explore/programs"; +import type { DefaultProgramsPage } from "@/lib/data/explore-programs"; import { useCuratedPrograms, useInfiniteScroll, @@ -32,6 +33,9 @@ interface ProgramsInteractiveContentProps { initialNewest: Program[]; initialTopics: TopicWithCount[]; initialStats: ProgramStats | null; + /** Server-rendered page 1 of the default All Programs grid — seeds the + * main listing query so first paint skips the client fetch. */ + initialProgramsPage?: DefaultProgramsPage; /** Every level in the catalog, read server-side — not just loaded rows. */ availableLevels?: PlanLevel[]; } @@ -63,6 +67,7 @@ export default function ProgramsInteractiveContent({ initialNewest, initialTopics, initialStats, + initialProgramsPage, availableLevels = [], }: ProgramsInteractiveContentProps) { const { data: session } = useSession(); @@ -113,6 +118,7 @@ export default function ProgramsInteractiveContent({ const { programs, isLoading, hasMore, loadMore } = usePrograms(programType, { userId, filters, + initialPage: initialProgramsPage, }); const { programs: trendingPrograms, isLoading: trendingLoading } = diff --git a/app/explore/programs/hooks/usePrograms.ts b/app/explore/programs/hooks/usePrograms.ts index 52233c0b0..0640efc34 100644 --- a/app/explore/programs/hooks/usePrograms.ts +++ b/app/explore/programs/hooks/usePrograms.ts @@ -1,6 +1,6 @@ "use client"; -import { useInfiniteQuery } from "@tanstack/react-query"; +import { useInfiniteQuery, keepPreviousData } from "@tanstack/react-query"; import { useMemo } from "react"; import { isUserEnrolled, @@ -9,6 +9,7 @@ import { import { ITEMS_PER_PAGE, generateProgramImageUrl, + type ApiMeta, type Program, type ProgramType, type ProgramFilters, @@ -18,6 +19,7 @@ import { import { buildFilterParams, fetchPlans, + type PlanApiResponse, type ClassPlanApiItem, type WebinarPlanApiItem, } from "./_helpers"; @@ -25,6 +27,105 @@ import { interface UseProgramsOptions { userId?: string | null; filters?: ProgramFilters; + /** Server-rendered page 1 of the anonymous, unfiltered default view + * (lib/data getDefaultProgramsPage) — seeds the "all" query so the grid + * paints without a client fetch. `data` is untyped for the same reason + * fetchPlans trusts `res.json()`: both sides carry the API's list shape. */ + initialPage?: { + classResponse: { data: unknown[]; meta: ApiMeta }; + webinarResponse: { data: unknown[]; meta: ApiMeta }; + }; +} + +interface ProgramsQueryPage { + programs: Program[]; + classMeta?: ApiMeta; + webinarMeta?: ApiMeta; +} + +/** + * Map raw plan-list responses into one query page. Shared by the queryFn + * (live /api/plans/* responses) and the RSC seed (getDefaultProgramsPage), + * so the seeded page cannot drift from what a real fetch would produce. + * Response order matches the request order in the queryFn: classes first + * when the tab includes classes, webinars after. + */ +function buildProgramsPage( + programType: ProgramType, + userId: string | null | undefined, + responses: PlanApiResponse[], +): ProgramsQueryPage { + let combinedPrograms: Program[] = []; + let classMeta: ApiMeta | undefined; + let webinarMeta: ApiMeta | undefined; + + if ((programType === "all" || programType === "class") && responses[0]) { + const classResponse = responses[0]; + classMeta = classResponse.meta; + if (classResponse.data) { + const formattedClasses = classResponse.data.map( + (plan): ClassPlanProgram => { + const typedPlan = plan as ClassPlanApiItem; + const classes = typedPlan.classes || []; + const appointments = classes.flatMap((c) => c.appointments ?? []); + const isRegistered = + userId && appointments.length > 0 + ? isUserEnrolled(appointments, userId) + : false; + + return { + ...typedPlan, + classes, + type: "class", + imageUrl: generateProgramImageUrl( + typedPlan.id, + 600, + 400, + typedPlan.imageUrl, + ), + isRegistered, + } as ClassPlanProgram; + }, + ); + combinedPrograms = [...combinedPrograms, ...formattedClasses]; + } + } + + if (programType === "all" || programType === "webinar") { + const webinarResponseIndex = programType === "all" ? 1 : 0; + if (responses[webinarResponseIndex]) { + const webinarResponse = responses[webinarResponseIndex]; + webinarMeta = webinarResponse.meta; + if (webinarResponse.data) { + const formattedWebinars = webinarResponse.data.map( + (plan): WebinarPlanProgram => { + const typedPlan = plan as WebinarPlanApiItem; + const webinars = typedPlan.webinars || []; + const isRegistered = + userId && webinars.length > 0 + ? isUserRegisteredForWebinar(webinars, userId) + : false; + + return { + ...typedPlan, + webinars, + type: "webinar", + imageUrl: generateProgramImageUrl( + typedPlan.id, + 600, + 400, + typedPlan.imageUrl, + ), + isRegistered, + } as WebinarPlanProgram; + }, + ); + combinedPrograms = [...combinedPrograms, ...formattedWebinars]; + } + } + } + + return { programs: combinedPrograms, classMeta, webinarMeta }; } /** @@ -36,10 +137,30 @@ export function usePrograms( programType: ProgramType, options: UseProgramsOptions = {}, ) { - const { userId, filters = {} } = options; + const { userId, filters = {}, initialPage } = options; const includeRegistration = !!userId; const filterStr = buildFilterParams(filters); + // Seed exactly one query: the anonymous, unfiltered "all" view — the key + // the server pre-rendered. The key contains `userId`, which is undefined + // while useSession() resolves; when it lands for a signed-in user the key + // flips and the refetch recomputes isRegistered (keepPreviousData below + // keeps the seeded rows on screen instead of re-skeletoning the grid). + const seededInitialData = useMemo(() => { + if (!initialPage || programType !== "all" || filterStr !== "" || userId) { + return undefined; + } + return { + pages: [ + buildProgramsPage("all", undefined, [ + initialPage.classResponse as PlanApiResponse, + initialPage.webinarResponse as PlanApiResponse, + ]), + ], + pageParams: [0], + }; + }, [initialPage, programType, filterStr, userId]); + const { data, error, @@ -71,78 +192,7 @@ export function usePrograms( requests.map((url) => fetchPlans(url)), ); - let combinedPrograms: Program[] = []; - let classMeta, webinarMeta; - - if ((programType === "all" || programType === "class") && responses[0]) { - const classResponse = responses[0]; - classMeta = classResponse.meta; - if (classResponse.data) { - const formattedClasses = classResponse.data.map( - (plan): ClassPlanProgram => { - const typedPlan = plan as ClassPlanApiItem; - const classes = typedPlan.classes || []; - const appointments = classes.flatMap( - (c) => c.appointments ?? [], - ); - const isRegistered = - userId && appointments.length > 0 - ? isUserEnrolled(appointments, userId) - : false; - - return { - ...typedPlan, - classes, - type: "class", - imageUrl: generateProgramImageUrl( - typedPlan.id, - 600, - 400, - typedPlan.imageUrl, - ), - isRegistered, - } as ClassPlanProgram; - }, - ); - combinedPrograms = [...combinedPrograms, ...formattedClasses]; - } - } - - if (programType === "all" || programType === "webinar") { - const webinarResponseIndex = programType === "all" ? 1 : 0; - if (responses[webinarResponseIndex]) { - const webinarResponse = responses[webinarResponseIndex]; - webinarMeta = webinarResponse.meta; - if (webinarResponse.data) { - const formattedWebinars = webinarResponse.data.map( - (plan): WebinarPlanProgram => { - const typedPlan = plan as WebinarPlanApiItem; - const webinars = typedPlan.webinars || []; - const isRegistered = - userId && webinars.length > 0 - ? isUserRegisteredForWebinar(webinars, userId) - : false; - - return { - ...typedPlan, - webinars, - type: "webinar", - imageUrl: generateProgramImageUrl( - typedPlan.id, - 600, - 400, - typedPlan.imageUrl, - ), - isRegistered, - } as WebinarPlanProgram; - }, - ); - combinedPrograms = [...combinedPrograms, ...formattedWebinars]; - } - } - } - - return { programs: combinedPrograms, classMeta, webinarMeta }; + return buildProgramsPage(programType, userId, responses); }, getNextPageParam: (lastPage, pages) => { let hasMoreClasses = false; @@ -182,6 +232,11 @@ export function usePrograms( return hasMore ? pages.length : undefined; }, initialPageParam: 0, + ...(seededInitialData ? { initialData: seededInitialData } : {}), + // Mirrors useConsultants: when the query key changes (a filter, or the + // session resolving and flipping the userId segment) keep the previous + // rows on screen during the refetch instead of dropping to a skeleton. + placeholderData: keepPreviousData, staleTime: 2 * 60 * 1000, gcTime: 10 * 60 * 1000, retry: 2, diff --git a/app/explore/programs/page.tsx b/app/explore/programs/page.tsx index 3b0849196..833e33f86 100644 --- a/app/explore/programs/page.tsx +++ b/app/explore/programs/page.tsx @@ -1,5 +1,6 @@ import { getCuratedPrograms, + getDefaultProgramsPage, getTopicsWithCount, } from "@/lib/data/explore-programs"; import { withBuildTimeRetry } from "@/lib/data/fail-open"; @@ -34,14 +35,24 @@ export default async function ExplorePrograms() { // ISR, a degraded 200 would be written to the durable cache and replayed to // everyone until the window expired (#1123) — so retry once during build and // otherwise throw, which caches nothing and lands in error.tsx instead. - const [trendingPrograms, newestPrograms, topicsWithCount, stats, levels] = - await Promise.all([ - withBuildTimeRetry(() => getCuratedPrograms("all", "trending", 8)), - withBuildTimeRetry(() => getCuratedPrograms("all", "newest", 8)), - withBuildTimeRetry(() => getTopicsWithCount("all")), - withBuildTimeRetry(getCachedProgramCounts), - withBuildTimeRetry(getCachedProgramLevels), - ]); + const [ + trendingPrograms, + newestPrograms, + topicsWithCount, + stats, + levels, + defaultProgramsPage, + ] = await Promise.all([ + withBuildTimeRetry(() => getCuratedPrograms("all", "trending", 8)), + withBuildTimeRetry(() => getCuratedPrograms("all", "newest", 8)), + withBuildTimeRetry(() => getTopicsWithCount("all")), + withBuildTimeRetry(getCachedProgramCounts), + withBuildTimeRetry(getCachedProgramLevels), + // Page 1 of the anonymous default grid — seeds the client usePrograms + // query so the All Programs section paints with the HTML instead of a + // second skeleton-then-fetch pass. + withBuildTimeRetry(getDefaultProgramsPage), + ]); return ( ); diff --git a/lib/api/plans/plan-filters.ts b/lib/api/plans/plan-filters.ts new file mode 100644 index 000000000..70a0555c5 --- /dev/null +++ b/lib/api/plans/plan-filters.ts @@ -0,0 +1,157 @@ +import { Prisma, type OrgPlanVisibility } from "@prisma/client"; +import { MARKETPLACE_VISIBILITY } from "@/lib/api/plans/visibility"; + +/** + * Query builders for the public plan list endpoints. + * + * Moved from app/api/plans/shared/plan-filters.ts (which re-exports these) + * so lib/data/explore-programs.ts can build the /explore/programs RSC seed + * with the exact same where/orderBy the API serves — app/ is the routing + * layer and lib/ must not import from it. + */ + +export interface PlanFilterParams { + consultantId: string | null; + topicIds: string | null; + language: string | null; + domainId: string | null; + sort: string | null; + minPrice: number | undefined; + maxPrice: number | undefined; + search: string | null; + level: string | null; + page: number; + limit: number; + skip: number; +} + +/** + * Parse filter query params from a URLSearchParams with NaN guards on numeric values. + */ +export function parsePlanFilters( + searchParams: URLSearchParams, +): PlanFilterParams { + const page = parseInt(searchParams.get("page") || "1") || 1; + const limit = parseInt(searchParams.get("limit") || "10") || 10; + const skip = (page - 1) * limit; + + const rawMin = searchParams.get("minPrice"); + const rawMax = searchParams.get("maxPrice"); + const parsedMin = rawMin ? parseInt(rawMin) : undefined; + const parsedMax = rawMax ? parseInt(rawMax) : undefined; + + return { + consultantId: searchParams.get("consultantId"), + topicIds: searchParams.get("topicIds"), + language: searchParams.get("language"), + domainId: searchParams.get("domainId"), + sort: searchParams.get("sort"), + minPrice: + parsedMin !== undefined && !isNaN(parsedMin) ? parsedMin : undefined, + maxPrice: + parsedMax !== undefined && !isNaN(parsedMax) ? parsedMax : undefined, + search: searchParams.get("search"), + // "all" is the UI's no-op sentinel, not a stored level value. + level: + searchParams.get("level") === "all" ? null : searchParams.get("level"), + page, + limit, + skip, + }; +} + +/** + * Shared plan WHERE clause — structurally compatible with both + * Prisma.WebinarPlanWhereInput and Prisma.ClassPlanWhereInput. + */ +export interface PlanWhereClause { + consultantProfileId?: string; + language?: string; + level?: string; + price?: { gte?: number; lte?: number }; + title?: { contains: string; mode: "insensitive" }; + topics?: { some: { id: { in: string[] } } }; + consultantProfile?: { domainId: string }; + visibility?: { in: OrgPlanVisibility[] }; + /** #catalog-archive — `null` keeps withdrawn plans out of public lists. */ + archivedAt?: null; +} + +/** + * Build a Prisma where clause from parsed plan filters. + * The returned object is structurally compatible with both + * Prisma.WebinarPlanWhereInput and Prisma.ClassPlanWhereInput. + */ +export function buildPlanWhereClause( + filters: PlanFilterParams, +): PlanWhereClause { + // #726 — public marketplace must not surface ORG_ONLY plans. The filter + // is applied unconditionally here because every caller of this helper + // is a public surface; org-internal catalog endpoints have their own + // where-builders. + // #catalog-archive — an archived plan is withdrawn from sale. It is kept + // rather than deleted because the row carries the terms of every booking made + // against it (and the FK chain cascades to Payment), so discovery has to + // filter it out explicitly. Same reasoning as the visibility gate above: every + // caller here is a public surface. + const where: PlanWhereClause = { + visibility: { in: MARKETPLACE_VISIBILITY }, + archivedAt: null, + }; + + if (filters.consultantId) { + where.consultantProfileId = filters.consultantId; + } + if (filters.language) { + where.language = filters.language; + } + // Level used to be filtered client-side over the already-loaded infinite-scroll + // page, so a matching program on a later page simply never appeared. + if (filters.level) { + where.level = filters.level; + } + if (filters.minPrice !== undefined || filters.maxPrice !== undefined) { + const price: { gte?: number; lte?: number } = {}; + if (filters.minPrice !== undefined) price.gte = filters.minPrice; + if (filters.maxPrice !== undefined) price.lte = filters.maxPrice; + where.price = price; + } + if (filters.search) { + where.title = { contains: filters.search, mode: "insensitive" }; + } + if (filters.topicIds) { + const ids = filters.topicIds.split(",").filter(Boolean); + if (ids.length > 0) { + where.topics = { some: { id: { in: ids } } }; + } + } + if (filters.domainId) { + where.consultantProfile = { domainId: filters.domainId }; + } + + return where; +} + +/** + * Shared plan ORDER BY clause — structurally compatible with both + * Prisma.WebinarPlanOrderByWithRelationInput and Prisma.ClassPlanOrderByWithRelationInput. + */ +export interface PlanOrderByClause { + createdAt?: Prisma.SortOrder; + price?: Prisma.SortOrder; + title?: Prisma.SortOrder; +} + +/** + * Build a Prisma orderBy object from a sort string. + */ +export function buildPlanOrderBy( + sort: string | null, +): PlanOrderByClause | undefined { + if (sort === "newest") return { createdAt: "desc" }; + if (sort === "price-asc") return { price: "asc" }; + if (sort === "price-desc") return { price: "desc" }; + if (sort === "title-asc") return { title: "asc" }; + if (sort === "title-desc") return { title: "desc" }; + return undefined; +} diff --git a/lib/api/plans/plan-includes.ts b/lib/api/plans/plan-includes.ts new file mode 100644 index 000000000..32977406c --- /dev/null +++ b/lib/api/plans/plan-includes.ts @@ -0,0 +1,106 @@ +import { CollaboratorStatus } from "@prisma/client"; + +/** + * Shared Prisma `include` shapes for the public plan list endpoints. + * + * Extracted from app/api/plans/{classes,webinars}/route.ts so the RSC seed + * for /explore/programs (lib/data/explore-programs.ts getDefaultProgramsPage) + * reads with the exact same shape the API serves. If a route needs an extra + * field on list items, add it here — a hand-copied include in the data layer + * would silently drift and break seed/fetch parity on the explore grid. + * Lives in lib/ (not app/api/plans/shared/) because lib/data imports it and + * lib/ must not depend on the app/ routing layer. + */ + +// Card-facing consultant summary: name, avatar, up to 3 work experiences. +const consultantProfileListInclude = { + include: { + user: { + select: { + name: true, + image: true, + workExperiences: { + select: { + company: true, + companyDomain: true, + isCurrent: true, + }, + orderBy: [ + { isCurrent: "desc" as const }, + { startDate: "desc" as const }, + ], + take: 3, + }, + }, + }, + }, +}; + +const collaboratorsListInclude = { + where: { status: CollaboratorStatus.ACCEPTED }, + include: { + consultantProfile: consultantProfileListInclude, + }, +}; + +/** Include for GET /api/plans/classes list items. */ +export function classPlanListInclude(opts: { + includeClasses: boolean; + includeRegistration: boolean; +}) { + // Registration needs each class's appointments + slot users to compute + // isRegistered client-side; the anonymous list only needs the classes rows. + let classesInclude: boolean | Record = true; + if (opts.includeRegistration) { + classesInclude = { + include: { + appointments: { + include: { + slotsOfAppointment: { + include: { + user: { select: { id: true } }, + }, + }, + }, + }, + }, + }; + } + + return { + consultantProfile: consultantProfileListInclude, + topics: true, + classContents: true, + collaborators: collaboratorsListInclude, + ...((opts.includeClasses || opts.includeRegistration) && { + classes: classesInclude, + }), + }; +} + +/** Include for GET /api/plans/webinars list items. */ +export function webinarPlanListInclude(opts: { includeRegistration: boolean }) { + const include: Record = { + consultantProfile: consultantProfileListInclude, + topics: true, + collaborators: collaboratorsListInclude, + }; + + if (opts.includeRegistration) { + include.webinars = { + include: { + appointment: { + include: { + slotsOfAppointment: { + include: { + user: { select: { id: true } }, + }, + }, + }, + }, + }, + }; + } + + return include; +} diff --git a/lib/data/explore-programs.ts b/lib/data/explore-programs.ts index e98f37994..b0b0d136d 100644 --- a/lib/data/explore-programs.ts +++ b/lib/data/explore-programs.ts @@ -4,14 +4,24 @@ import { readByIds } from "@/lib/data/read-by-ids"; import { toPlain } from "@/lib/data/serialize"; import type { Prisma } from "@prisma/client"; import { eventPlanDiscoverableWhere } from "@/lib/api/plans/visibility"; -import { generateProgramImageUrl } from "@/lib/explore/programs"; +import { generateProgramImageUrl, ITEMS_PER_PAGE } from "@/lib/explore/programs"; import type { + ApiMeta, Program, ClassPlanProgram, WebinarPlanProgram, ProgramType, TopicWithCount, } from "@/lib/explore/programs"; +import { + parsePlanFilters, + buildPlanWhereClause, + buildPlanOrderBy, +} from "@/lib/api/plans/plan-filters"; +import { + classPlanListInclude, + webinarPlanListInclude, +} from "@/lib/api/plans/plan-includes"; /** * Server-side data access for the explore programs page. @@ -363,3 +373,81 @@ export const getTopicsWithCount = unstable_cache( ["topics-with-count"], { revalidate: 300, tags: ["programs"] }, ); + +// --------------------------------------------------------------------------- +// Default "All Programs" page (RSC seed for the explore grid) +// --------------------------------------------------------------------------- + +/** Page 1 of the default (unfiltered, anonymous) All Programs grid. */ +export interface DefaultProgramsPage { + classResponse: { data: unknown[]; meta: ApiMeta }; + webinarResponse: { data: unknown[]; meta: ApiMeta }; +} + +/** + * Server-side twin of the client's first `usePrograms` fetch: + * `GET /api/plans/classes?page=1&limit=12&include=classes` + + * `GET /api/plans/webinars?page=1&limit=12`, anonymous (no registration data). + * + * Built from the routes' own where/orderBy/include builders — never hand-copy + * those here, or visibility rules (#726, #catalog-archive) drift between the + * seeded grid and what the API serves on scroll/filter. `isRegistered` is + * deliberately NOT part of this shape: the seed only ever applies to the + * anonymous query key, and the signed-in refetch recomputes registration. + * + * unstable_cache is keyed without args and tagged "programs", same purge as + * the curated reads; 300s matches the route's `revalidate` so this read does + * not cap the segment value (#1110). + */ +export const getDefaultProgramsPage = unstable_cache( + async (): Promise => { + const filters = parsePlanFilters( + new URLSearchParams({ page: "1", limit: String(ITEMS_PER_PAGE) }), + ); + const { page, limit, skip } = filters; + const orderBy = buildPlanOrderBy(filters.sort); + + const [classPlans, classTotal, webinarPlans, webinarTotal] = + await Promise.all([ + prisma.classPlan.findMany({ + where: buildPlanWhereClause(filters) as Prisma.ClassPlanWhereInput, + include: classPlanListInclude({ + includeClasses: true, + includeRegistration: false, + }), + skip, + take: limit, + ...(orderBy && { orderBy }), + }), + prisma.classPlan.count({ + where: buildPlanWhereClause(filters) as Prisma.ClassPlanWhereInput, + }), + prisma.webinarPlan.findMany({ + where: buildPlanWhereClause(filters) as Prisma.WebinarPlanWhereInput, + include: webinarPlanListInclude({ includeRegistration: false }), + skip, + take: limit, + ...(orderBy && { orderBy }), + }), + prisma.webinarPlan.count({ + where: buildPlanWhereClause(filters) as Prisma.WebinarPlanWhereInput, + }), + ]); + + // Same meta shape as the routes' paginatedResponse. + const meta = (total: number): ApiMeta => ({ + total, + page, + limit, + totalPages: Math.ceil(total / limit), + }); + + // toPlain — extended plan rows carry an inspect symbol (see serialize.ts) + return toPlain({ + classResponse: { data: classPlans, meta: meta(classTotal) }, + webinarResponse: { data: webinarPlans, meta: meta(webinarTotal) }, + }); + }, + ["default-programs-page"], + { revalidate: 300, tags: ["programs"] }, +); From e20e1b9861addbae29b20fa384625e1b54366635 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 05:13:56 +0000 Subject: [PATCH 04/18] fix(explore): FCP-capable loading states, experts error boundary, reachable programs CTA MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Render the real static hero copy in app/explore/experts/loading.tsx and ProgramsExploreSkeleton (used by the programs loading.tsx): a skeleton made only of pulsing boxes cannot fire First Contentful Paint (#1102) — FCP needs text, an image, canvas or SVG. Data-dependent parts stay skeletons. - Add app/explore/experts/error.tsx: the route's reads rethrow rather than degrade (#1119), and without a segment boundary a transient failure on a cache MISS replaced the whole app shell via app/error.tsx. - Add an always-visible "Browse Classes & Webinars" CTA in HowItWorksSection: the only other landing link to /explore/programs sits inside the reviews section's Suspense boundary and vanishes when there are no reviews. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SKb2cFx2XCYrPKDrrENgqJ --- app/explore/experts/error.tsx | 44 ++++++++++++++++++ app/explore/experts/loading.tsx | 38 +++++++++++++-- .../programs/ProgramsExploreSkeleton.tsx | 46 ++++++++++++++----- components/home/HowItWorksSection.tsx | 33 +++++++++---- 4 files changed, 136 insertions(+), 25 deletions(-) create mode 100644 app/explore/experts/error.tsx diff --git a/app/explore/experts/error.tsx b/app/explore/experts/error.tsx new file mode 100644 index 000000000..6ce11e080 --- /dev/null +++ b/app/explore/experts/error.tsx @@ -0,0 +1,44 @@ +"use client"; + +import { Button } from "@/components/ui/button"; +import { + Card, + CardContent, + CardFooter, + CardHeader, + CardTitle, +} from "@/components/ui/card"; + +// Load-bearing under the rethrow policy: the page's reads no longer degrade +// to empty rows (#1119), so a transient failure on a cache MISS throws and +// must land here instead of replacing the whole app shell via app/error.tsx. +export default function Error({ + error, + reset, +}: Readonly<{ + error: Error & { digest?: string }; + reset: () => void; +}>) { + return ( +
+ + + Something went wrong! + + +

+ {error.message || "An error occurred while loading the experts."} +

+ + + + + + +
+ ); +} diff --git a/app/explore/experts/loading.tsx b/app/explore/experts/loading.tsx index ac517688c..7520f3415 100644 --- a/app/explore/experts/loading.tsx +++ b/app/explore/experts/loading.tsx @@ -1,12 +1,42 @@ +import { Sparkles } from "lucide-react"; + +// The hero's static copy is rendered for real here — identical to the page's +// HeroSection — because a skeleton made only of pulsing boxes cannot fire +// First Contentful Paint (#1102): FCP needs text, an image, canvas or SVG. +// Only the data-dependent parts (stat values, the grid) stay as skeletons. export default function Loading() { return (
-
+
-
-
-
+
+ + + World-Class Mentorship + +
+ +

+ Meet Your Perfect Mentor +

+ +

+ Ready to level up? Our amazing mentors are here to guide you! + Connect with industry experts who understand your journey. +

+ +
+ {["Active Experts", "Average Rating", "Sessions Completed"].map( + (label) => ( +
+
+
+
{label}
+
+ ), + )} +
diff --git a/app/explore/programs/ProgramsExploreSkeleton.tsx b/app/explore/programs/ProgramsExploreSkeleton.tsx index 44a5fe483..420cdb059 100644 --- a/app/explore/programs/ProgramsExploreSkeleton.tsx +++ b/app/explore/programs/ProgramsExploreSkeleton.tsx @@ -1,21 +1,43 @@ import { Skeleton } from "@/components/ui/skeleton"; +import { Sparkles } from "lucide-react"; -/** Explore programs list: dark hero + tabs/filters + carousel rows. */ +/** Explore programs list: dark hero + tabs/filters + carousel rows. + * + * The hero's static copy is rendered for real — identical to + * ProgramsInteractiveContent's hero — because a skeleton made only of pulsing + * boxes cannot fire First Contentful Paint (#1102): FCP needs text, an image, + * canvas or SVG. Only the data-dependent parts stay as skeletons. */ export function ProgramsExploreSkeleton() { return (
-
- - - -
- {[1, 2, 3, 4].map((i) => ( -
- - -
- ))} +
+
+ + + Learn from the Best + +
+ +

+ Classes & Webinars +

+ +

+ Expand your knowledge with expert-led classes and live webinars. + Learn at your own pace or join interactive sessions. +

+ +
+ {["Classes Available", "Live Webinars", "Students Enrolled"].map( + (label) => ( +
+ + +
{label}
+
+ ), + )}
diff --git a/components/home/HowItWorksSection.tsx b/components/home/HowItWorksSection.tsx index 10dd56d05..f5915f020 100644 --- a/components/home/HowItWorksSection.tsx +++ b/components/home/HowItWorksSection.tsx @@ -81,15 +81,30 @@ export function HowItWorksSection() { Get started in minutes. Our streamlined process makes it easy to connect with the right expert for your needs.

- - - + {/* Both CTAs live here because this section is unconditional — + the only other /explore/programs link on the landing page sits + inside the reviews section's Suspense boundary and disappears + entirely when there are no reviews to show. */} +
+ + + + + + +
From 2066efea5f4773958c8be30ffdd5653b75da5dce Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 05:22:11 +0000 Subject: [PATCH 05/18] test(explore): anchor the perRequest detector on a fixture, not a live offender MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The guard's non-vacuous check required some route file to still opt into perRequest degrading. /explore/programs was the last one, and converting it to ISR-and-rethrow — the sweep this guard enforces — made the anchor fail. Use a fixture instead, the same pattern the file already applies to hasBareCatch for exactly this decay mode. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SKb2cFx2XCYrPKDrrENgqJ --- __tests__/explore/isr-routes-never-fail-open.test.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/__tests__/explore/isr-routes-never-fail-open.test.ts b/__tests__/explore/isr-routes-never-fail-open.test.ts index 3a4078902..b348d8edd 100644 --- a/__tests__/explore/isr-routes-never-fail-open.test.ts +++ b/__tests__/explore/isr-routes-never-fail-open.test.ts @@ -65,7 +65,13 @@ describe("#1119 — a cacheable route must never fail open", () => { // Guards against the walk silently matching nothing and passing vacuously. expect(files.length).toBeGreaterThan(50); expect(files.some((f) => isCacheable(f.src))).toBe(true); - expect(files.some((f) => degrades(f.src))).toBe(true); + // No live degrading route remains: /explore/programs, the last one, went + // ISR-and-rethrow — the very sweep this file enforces. Anchor the detector + // on a fixture instead (the hasBareCatch pattern below), so the guard + // stays non-vacuous without requiring a standing offender. + expect( + degrades('getX().catch(emptyOnTransientDbError("x", { perRequest: true }))'), + ).toBe(true); }); it("no route with a revalidate export opts into degrading", () => { From 83731ab41149b5ec0998ed8d1941bacb7ac058b1 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 05:42:26 +0000 Subject: [PATCH 06/18] refactor(explore): deduplicate error cards and hero copy for the Sonar gate SonarCloud flagged 5.9% duplication on new code (gate requires <=3%). The duplicated blocks were introduced by this PR: the experts error.tsx was a near-verbatim copy of the programs one, and both explore loading states duplicated their page hero markup to render real text for FCP (#1102). - New shared ExploreError card; both segment error.tsx files are now thin wrappers passing only their fallback message. - New ExpertsHeroCopy / ProgramsHeroCopy components; the page heroes and the loading states now render the same markup from one source instead of two. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SKb2cFx2XCYrPKDrrENgqJ --- app/explore/components/ExploreError.tsx | 45 ++++++++++++++++++ app/explore/experts/components/HeroCopy.tsx | 26 +++++++++++ app/explore/experts/error.tsx | 46 +++++-------------- app/explore/experts/loading.tsx | 18 +------- app/explore/experts/page.tsx | 19 ++------ .../programs/ProgramsExploreSkeleton.tsx | 18 +------- .../programs/ProgramsInteractiveContent.tsx | 19 ++------ app/explore/programs/components/HeroCopy.tsx | 26 +++++++++++ app/explore/programs/error.tsx | 46 +++++-------------- 9 files changed, 129 insertions(+), 134 deletions(-) create mode 100644 app/explore/components/ExploreError.tsx create mode 100644 app/explore/experts/components/HeroCopy.tsx create mode 100644 app/explore/programs/components/HeroCopy.tsx diff --git a/app/explore/components/ExploreError.tsx b/app/explore/components/ExploreError.tsx new file mode 100644 index 000000000..46b83dafe --- /dev/null +++ b/app/explore/components/ExploreError.tsx @@ -0,0 +1,45 @@ +"use client"; + +import { Button } from "@/components/ui/button"; +import { + Card, + CardContent, + CardFooter, + CardHeader, + CardTitle, +} from "@/components/ui/card"; + +/** Shared segment error card for the explore surfaces — the per-segment + * error.tsx files are thin wrappers so the markup lives once. */ +export default function ExploreError({ + error, + reset, + fallbackMessage, +}: Readonly<{ + error: Error & { digest?: string }; + reset: () => void; + fallbackMessage: string; +}>) { + return ( +
+ + + Something went wrong! + + +

+ {error.message || fallbackMessage} +

+ + + + + + +
+ ); +} diff --git a/app/explore/experts/components/HeroCopy.tsx b/app/explore/experts/components/HeroCopy.tsx new file mode 100644 index 000000000..a70a60886 --- /dev/null +++ b/app/explore/experts/components/HeroCopy.tsx @@ -0,0 +1,26 @@ +import { Sparkles } from "lucide-react"; + +/** Static hero copy shared by the page's HeroSection and loading.tsx, so the + * loading state renders real text (skeletons cannot fire FCP, #1102) + * without duplicating the markup. */ +export function ExpertsHeroCopy() { + return ( + <> +
+ + + World-Class Mentorship + +
+ +

+ Meet Your Perfect Mentor +

+ +

+ Ready to level up? Our amazing mentors are here to guide you! Connect + with industry experts who understand your journey. +

+ + ); +} diff --git a/app/explore/experts/error.tsx b/app/explore/experts/error.tsx index 6ce11e080..2edf27942 100644 --- a/app/explore/experts/error.tsx +++ b/app/explore/experts/error.tsx @@ -1,44 +1,20 @@ "use client"; -import { Button } from "@/components/ui/button"; -import { - Card, - CardContent, - CardFooter, - CardHeader, - CardTitle, -} from "@/components/ui/card"; +import ExploreError from "../components/ExploreError"; // Load-bearing under the rethrow policy: the page's reads no longer degrade // to empty rows (#1119), so a transient failure on a cache MISS throws and // must land here instead of replacing the whole app shell via app/error.tsx. -export default function Error({ - error, - reset, -}: Readonly<{ - error: Error & { digest?: string }; - reset: () => void; -}>) { +export default function Error( + props: Readonly<{ + error: Error & { digest?: string }; + reset: () => void; + }>, +) { return ( -
- - - Something went wrong! - - -

- {error.message || "An error occurred while loading the experts."} -

- - - - - - -
+ ); } diff --git a/app/explore/experts/loading.tsx b/app/explore/experts/loading.tsx index 7520f3415..31825366d 100644 --- a/app/explore/experts/loading.tsx +++ b/app/explore/experts/loading.tsx @@ -1,4 +1,4 @@ -import { Sparkles } from "lucide-react"; +import { ExpertsHeroCopy } from "./components/HeroCopy"; // The hero's static copy is rendered for real here — identical to the page's // HeroSection — because a skeleton made only of pulsing boxes cannot fire @@ -10,21 +10,7 @@ export default function Loading() {
-
- - - World-Class Mentorship - -
- -

- Meet Your Perfect Mentor -

- -

- Ready to level up? Our amazing mentors are here to guide you! - Connect with industry experts who understand your journey. -

+
{["Active Experts", "Average Rating", "Sessions Completed"].map( diff --git a/app/explore/experts/page.tsx b/app/explore/experts/page.tsx index 27f22bc5e..a92158ec3 100644 --- a/app/explore/experts/page.tsx +++ b/app/explore/experts/page.tsx @@ -1,5 +1,6 @@ import { Suspense } from "react"; -import { Sparkles, Users, Star, TrendingUp } from "lucide-react"; +import { Users, Star, TrendingUp } from "lucide-react"; +import { ExpertsHeroCopy } from "./components/HeroCopy"; import { FeaturedExperts } from "./components/FeaturedExperts"; import ExpertsInteractiveContent from "./ExpertsInteractiveContent"; import { @@ -62,21 +63,7 @@ function HeroSection({
-
- - - World-Class Mentorship - -
- -

- Meet Your Perfect Mentor -

- -

- Ready to level up? Our amazing mentors are here to guide you! - Connect with industry experts who understand your journey. -

+
{STATS.map((stat) => ( diff --git a/app/explore/programs/ProgramsExploreSkeleton.tsx b/app/explore/programs/ProgramsExploreSkeleton.tsx index 420cdb059..c0f9772f2 100644 --- a/app/explore/programs/ProgramsExploreSkeleton.tsx +++ b/app/explore/programs/ProgramsExploreSkeleton.tsx @@ -1,5 +1,5 @@ import { Skeleton } from "@/components/ui/skeleton"; -import { Sparkles } from "lucide-react"; +import { ProgramsHeroCopy } from "./components/HeroCopy"; /** Explore programs list: dark hero + tabs/filters + carousel rows. * @@ -12,21 +12,7 @@ export function ProgramsExploreSkeleton() {
-
- - - Learn from the Best - -
- -

- Classes & Webinars -

- -

- Expand your knowledge with expert-led classes and live webinars. - Learn at your own pace or join interactive sessions. -

+
{["Classes Available", "Live Webinars", "Students Enrolled"].map( diff --git a/app/explore/programs/ProgramsInteractiveContent.tsx b/app/explore/programs/ProgramsInteractiveContent.tsx index 1aca9c0ca..edea5736d 100644 --- a/app/explore/programs/ProgramsInteractiveContent.tsx +++ b/app/explore/programs/ProgramsInteractiveContent.tsx @@ -3,7 +3,7 @@ import { PlanLevel } from "@prisma/client"; import { useCallback, useMemo } from "react"; import { motion } from "framer-motion"; -import { GraduationCap, Video, Users, Sparkles } from "lucide-react"; +import { GraduationCap, Video, Users } from "lucide-react"; import { useSession } from "@/lib/auth-client"; import { useCurrency } from "@/hooks/useCurrency"; import { type Program, type TopicWithCount } from "@/lib/explore/programs"; @@ -16,6 +16,7 @@ import { useProgramsFilters, useTopicsWithCount, } from "./hooks"; +import { ProgramsHeroCopy } from "./components/HeroCopy"; import ProgramTabs from "./components/ProgramTabs"; import SectionHeader from "./components/SectionHeader"; import AdvancedFilters from "./components/AdvancedFilters"; @@ -211,21 +212,7 @@ export default function ProgramsInteractiveContent({ animate={{ opacity: 1, y: 0 }} transition={{ duration: 0.6 }} > -
- - - Learn from the Best - -
- -

- Classes & Webinars -

- -

- Expand your knowledge with expert-led classes and live webinars. - Learn at your own pace or join interactive sessions. -

+
{stats.map((stat, index) => ( diff --git a/app/explore/programs/components/HeroCopy.tsx b/app/explore/programs/components/HeroCopy.tsx new file mode 100644 index 000000000..811de4f44 --- /dev/null +++ b/app/explore/programs/components/HeroCopy.tsx @@ -0,0 +1,26 @@ +import { Sparkles } from "lucide-react"; + +/** Static hero copy shared by ProgramsInteractiveContent's hero and + * ProgramsExploreSkeleton (the loading state), so the skeleton renders real + * text (skeletons cannot fire FCP, #1102) without duplicating the markup. */ +export function ProgramsHeroCopy() { + return ( + <> +
+ + + Learn from the Best + +
+ +

+ Classes & Webinars +

+ +

+ Expand your knowledge with expert-led classes and live webinars. Learn + at your own pace or join interactive sessions. +

+ + ); +} diff --git a/app/explore/programs/error.tsx b/app/explore/programs/error.tsx index c5bd0c858..8e81cea32 100644 --- a/app/explore/programs/error.tsx +++ b/app/explore/programs/error.tsx @@ -1,41 +1,17 @@ "use client"; -import { Button } from "@/components/ui/button"; -import { - Card, - CardContent, - CardFooter, - CardHeader, - CardTitle, -} from "@/components/ui/card"; +import ExploreError from "../components/ExploreError"; -export default function Error({ - error, - reset, -}: Readonly<{ - error: Error & { digest?: string }; - reset: () => void; -}>) { +export default function Error( + props: Readonly<{ + error: Error & { digest?: string }; + reset: () => void; + }>, +) { return ( -
- - - Something went wrong! - - -

- {error.message || "An error occurred while loading the programs."} -

- - - - - - -
+ ); } From 887237a5f1d69eafc1cf7943ed772d793e8f365e Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 05:47:32 +0000 Subject: [PATCH 07/18] fix(explore): stop shadowing the Error global in segment error boundaries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SonarCloud's remaining quality-gate failure (C reliability on new code) is rule S2137: both explore error.tsx files declared `export default function Error(...)`, shadowing the global Error object. Next.js only requires a default-exported component, not the name — rename to ExpertsError / ProgramsError. Reproduced locally with eslint-plugin-sonarjs (sonarjs/no-globals-shadowing) since sonarcloud.io is unreachable from this environment. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SKb2cFx2XCYrPKDrrENgqJ --- app/explore/experts/error.tsx | 4 +++- app/explore/programs/error.tsx | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/app/explore/experts/error.tsx b/app/explore/experts/error.tsx index 2edf27942..593a169e5 100644 --- a/app/explore/experts/error.tsx +++ b/app/explore/experts/error.tsx @@ -5,7 +5,9 @@ import ExploreError from "../components/ExploreError"; // Load-bearing under the rethrow policy: the page's reads no longer degrade // to empty rows (#1119), so a transient failure on a cache MISS throws and // must land here instead of replacing the whole app shell via app/error.tsx. -export default function Error( +// Named ExpertsError, not Error — shadowing the Error global is a Sonar +// reliability bug (S2137), and Next.js only requires the default export. +export default function ExpertsError( props: Readonly<{ error: Error & { digest?: string }; reset: () => void; diff --git a/app/explore/programs/error.tsx b/app/explore/programs/error.tsx index 8e81cea32..66694233a 100644 --- a/app/explore/programs/error.tsx +++ b/app/explore/programs/error.tsx @@ -2,7 +2,9 @@ import ExploreError from "../components/ExploreError"; -export default function Error( +// Named ProgramsError, not Error — shadowing the Error global is a Sonar +// reliability bug (S2137), and Next.js only requires the default export. +export default function ProgramsError( props: Readonly<{ error: Error & { digest?: string }; reset: () => void; From 5c150850de124161611116e0a64fc8aec0ec6504 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 07:10:20 +0000 Subject: [PATCH 08/18] =?UTF-8?q?fix(explore):=20address=20CodeRabbit=20re?= =?UTF-8?q?view=20=E2=80=94=20pagination=20bounds,=20error=20copy,=20CTA?= =?UTF-8?q?=20markup?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Clamp public page/limit pagination inputs in parsePlanFilters (defaults on malformed/negative, caps of 10000/100): a crafted query could previously reach Prisma with a negative skip (throws -> 500), a negative take (reads from the END of the table), or an arbitrarily large slice. Also switches the file to Number.parseInt (Sonar). Unit coverage added for negative, zero, malformed, fractional and oversized values. - ExploreError now always renders the route-specific fallback copy: in production Next.js replaces Server Component error messages with a generic string, so error.message never said anything useful. The digest is shown as a support reference. - HowItWorksSection CTAs use Button asChild so the Link renders the interactive element itself — a - - - + - + +
diff --git a/lib/api/plans/plan-filters.ts b/lib/api/plans/plan-filters.ts index 70a0555c5..cc1daddc0 100644 --- a/lib/api/plans/plan-filters.ts +++ b/lib/api/plans/plan-filters.ts @@ -25,20 +25,37 @@ export interface PlanFilterParams { skip: number; } +// Public pagination inputs are clamped, not rejected: malformed values fall +// back to the defaults and oversized ones are bounded, so a crafted query +// cannot reach Prisma with a negative `skip` (it throws), a negative `take` +// (it reads from the END of the table), or an arbitrarily large slice. +const MAX_PAGE = 10_000; +const MAX_LIMIT = 100; + +function clampPositiveInt( + raw: string | null, + fallback: number, + max: number, +): number { + const parsed = Number.parseInt(raw ?? "", 10); + if (Number.isNaN(parsed) || parsed < 1) return fallback; + return Math.min(parsed, max); +} + /** * Parse filter query params from a URLSearchParams with NaN guards on numeric values. */ export function parsePlanFilters( searchParams: URLSearchParams, ): PlanFilterParams { - const page = parseInt(searchParams.get("page") || "1") || 1; - const limit = parseInt(searchParams.get("limit") || "10") || 10; + const page = clampPositiveInt(searchParams.get("page"), 1, MAX_PAGE); + const limit = clampPositiveInt(searchParams.get("limit"), 10, MAX_LIMIT); const skip = (page - 1) * limit; const rawMin = searchParams.get("minPrice"); const rawMax = searchParams.get("maxPrice"); - const parsedMin = rawMin ? parseInt(rawMin) : undefined; - const parsedMax = rawMax ? parseInt(rawMax) : undefined; + const parsedMin = rawMin ? Number.parseInt(rawMin, 10) : undefined; + const parsedMax = rawMax ? Number.parseInt(rawMax, 10) : undefined; return { consultantId: searchParams.get("consultantId"), From 74f58138d5c11f00167c6a489580022a3ffaab5e Mon Sep 17 00:00:00 2001 From: Kaustav Ghosh <44238657+teetangh@users.noreply.github.com> Date: Sat, 22 Aug 2026 12:34:57 +0530 Subject: [PATCH 09/18] perf(platform): 2GB handler memory, post-deploy warm-up, prod keep-warm (#1124) A brand-new Netlify function instance stalls its event loop ~24s before any application work; reproduced 2026-08-22 on preview 1195 (11/12 concurrent unique-key requests at 27.8-31.0s TTFB). Three mitigations: - netlify.toml: ___netlify-handler + ___netlify-odb-handler at 2048 MB. Lambda CPU scales with memory, and cold-boot JS/GC at ~0.5 vCPU is the leading explanation for the stall. Measured-or-reverted: verify on the preview burst test. Billing scales linearly with configured memory. - warm-deploy.yml: on deployment_status success, prime /api/health first (guaranteed invocation absorbs the boot stall), then hot pages SEQUENTIALLY (concurrent pings would spawn one stalled instance each), then generic RSC payloads. Covers production AND previews - previews are where the cost is worst since nothing there is ever warm. - keep-warm.yml: every 5 minutes ping prod /api/health on both hosts so a lone visitor on an idle site meets a warm instance instead of a stalled boot. Previews deliberately not warmed. --- .github/workflows/keep-warm.yml | 65 +++++++++++++++++++ .github/workflows/warm-deploy.yml | 104 ++++++++++++++++++++++++++++++ netlify.toml | 36 +++++++++++ 3 files changed, 205 insertions(+) create mode 100644 .github/workflows/keep-warm.yml create mode 100644 .github/workflows/warm-deploy.yml diff --git a/.github/workflows/keep-warm.yml b/.github/workflows/keep-warm.yml new file mode 100644 index 000000000..b0b45b0de --- /dev/null +++ b/.github/workflows/keep-warm.yml @@ -0,0 +1,65 @@ +name: Keep Warm + +# Keep at least one warm function instance on PRODUCTION between real traffic. +# +# The Next.js server handler stalls its event loop for ~24s on a brand-new +# instance's first invocation (#1124). A single warm instance does not remove +# that stall — burst traffic still spawns fresh instances that each pay it — +# but it removes the stall from the COMMON case: a lone visitor clicking +# through an otherwise idle site, which is exactly the shape of manual testing +# and low-traffic days. +# +# Every ping is a billable invocation (~12/hour ≈ 8.6k/month at the 5-minute +# cadence); disable this workflow if that trade stops making sense. Previews +# are deliberately NOT warmed: each PR has its own isolated cache scope and +# subdomain, so warming one preview does nothing for another, and idle previews +# going cold is unavoidable (warm-deploy.yml covers their first minutes). +# +# GitHub schedule triggers are best-effort with no SLA and can lag several +# minutes; treat the interval as "roughly every 5 minutes", not exact. + +on: + schedule: + - cron: "*/5 * * * *" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: keep-warm + cancel-in-progress: false + +jobs: + ping: + runs-on: ubuntu-latest + timeout-minutes: 5 + + steps: + # The canonical production origins: the Netlify host and the pinned + # NEXT_PUBLIC_APP_URL domain. Edge cache scopes are per-host, so both are + # pinged; the function instance underneath is shared. + # + # /api/health guarantees a handler invocation (a page GET can be served + # entirely off the CDN cache without touching the function), so instance + # warmth does not depend on cache misses. It is also the cheapest route + # that proves end-to-end liveness: LIMIT-1 DB probe + status reads, and + # doubles as an outage signal — if these pings start failing, prod is + # degraded whether or not any user has noticed yet. + - name: Ping production + env: + HOSTS: "https://familiarisenow.com https://familiarise.netlify.app" + run: | + for host in $HOSTS; do + curl -sS -o /dev/null -w "$host/api/health: ttfb=%{time_starttransfer}s code=%{http_code}\n" \ + --max-time 60 --retry 1 --retry-delay 3 \ + "$host/api/health" || echo "::warning::keep-warm ping failed for $host" + done + + # NOTE: hot page caches are deliberately NOT refreshed here. The ISR + # windows on / and /explore/experts are 1h/5m; refreshing them every 5 + # minutes would force continuous background regeneration invocations for + # content that changes on the order of days. The durable cache already + # persists entries across instances (Netlify Blobs), so cache priming + # only matters right after a deploy — that is warm-deploy.yml's job. + # This workflow's single job is instance warmth via the health ping. diff --git a/.github/workflows/warm-deploy.yml b/.github/workflows/warm-deploy.yml new file mode 100644 index 000000000..550b15a5e --- /dev/null +++ b/.github/workflows/warm-deploy.yml @@ -0,0 +1,104 @@ +name: Warm Deploy + +# Prime the caches and function instances of a freshly finished deploy. +# +# A deploy starts every ISR/CDN cache entry empty, and a Netlify function +# instance that has never served a request stalls its event loop for roughly +# 24s before executing anything (#1124 — measured 27.8–31.0s TTFB across 11/12 +# concurrent unique-key requests on preview 1195). The FIRST real visitor after +# each deploy therefore pays full price per hot route. This workflow pays it +# instead, in a controlled order: +# +# 1. /api/health first — guarantees one function invocation, so the instance +# that will serve everything else absorbs the cold-boot stall here rather +# than on a page render. +# 2. Hot public pages sequentially afterwards — primes their CDN/durable +# entries while the instance from step 1 is still warm. SEQUENTIAL ON +# PURPOSE: concurrent pings would spawn one stalled instance EACH, which +# is precisely the pathology being mitigated. +# +# Fires on Netlify's deployment statuses for production deploys, branch deploys +# AND pull-request previews — previews are where the cold cost is worst, +# because their cache scope is isolated and nothing is ever warm. +# +# This does not keep instances alive (see keep-warm.yml); it only removes the +# empty-cache window right after a deploy. + +on: + deployment_status: + states: + - success + workflow_dispatch: + inputs: + base_url: + description: "Deploy origin to warm (defaults to production)" + required: false + default: "https://familiarisenow.com" + +permissions: + contents: read + +concurrency: + group: warm-deploy-${{ github.event.deployment.id || github.run_id }} + cancel-in-progress: false + +jobs: + warm: + # Netlify also reports inactive/other states; only successful deploys with + # a resolvable environment URL are worth warming. + if: github.event_name == 'workflow_dispatch' || github.event.deployment_status.state == 'success' + runs-on: ubuntu-latest + timeout-minutes: 10 + + steps: + - name: Resolve deploy URL + id: url + env: + EVENT_URL: ${{ github.event.deployment_status.environment_url }} + PAYLOAD_WEB_URL: ${{ github.event.deployment.payload.web_url }} + DISPATCH_URL: ${{ inputs.base_url }} + run: | + BASE="${DISPATCH_URL:-${EVENT_URL:-${PAYLOAD_WEB_URL:-}}}" + if [ -z "$BASE" ]; then + echo "::error::No environment_url on the deployment status; cannot warm." + exit 1 + fi + # Strip a trailing slash so the path concatenations below stay clean. + BASE="${BASE%/}" + echo "base=$BASE" >> "$GITHUB_OUTPUT" + echo "Warming $BASE" + + # The first request against a brand-new instance can legitimately take + # ~30s (#1124), so max-time must sit well above that or the warm-up would + # kill the very request doing the warming. + - name: Warm the function instance (health probe) + run: | + curl -sS -o /dev/null -w "health: ttfb=%{time_starttransfer}s code=%{http_code}\n" \ + --max-time 60 --retry 1 --retry-delay 2 \ + "${{ steps.url.outputs.base }}/api/health" + + # Hot public routes in click-order value. Keep this list short and + # deliberate: every line is a billable invocation, and sequential curls + # share the instance warmed above. + - name: Warm hot public pages + run: | + BASE="${{ steps.url.outputs.base }}" + for path in "/" "/explore/experts" "/explore/community" "/about"; do + curl -sS -o /dev/null -w "$path: ttfb=%{time_starttransfer}s code=%{http_code}\n" \ + --max-time 45 "$BASE$path" || true + sleep 1 + done + + # RSC navigation payloads are what an actual click fetches; priming + # them means the first soft navigation hits the CDN instead of the + # function. A generic RSC request also re-walks the render path, keeping + # the instance hot. + - name: Warm RSC navigation payloads + run: | + BASE="${{ steps.url.outputs.base }}" + for path in "/explore/experts" "/about"; do + curl -sS -o /dev/null -H "RSC: 1" \ + -w "rsc $path: ttfb=%{time_starttransfer}s code=%{http_code}\n" \ + --max-time 45 "$BASE$path?_rsc=warmup" || true + sleep 1 + done diff --git a/netlify.toml b/netlify.toml index 4130e2e41..dc2c8f07e 100644 --- a/netlify.toml +++ b/netlify.toml @@ -14,6 +14,42 @@ # The standard build image has 8 GB, so this stays inside the container cap. NODE_OPTIONS = "--max-old-space-size=6144" +# ───────────────────────────────────────────────────────────────────────────── +# Function memory (#1124) +# +# A brand-new instance of the Next.js server handler stalls its event loop for +# roughly 24s on its first invocation, BEFORE any application work — the whole +# of the 20–30s tail on public routes (issue #1124, reproduced 2026-08-22: +# 11/12 concurrent unique-key requests to a deploy preview landed at +# 27.8–31.0s TTFB while same-key requests coalesced at 2.7–5.4s). The function +# boots at AWS_LAMBDA_FUNCTION_MEMORY_SIZE=1024 → ~0.5 vCPU with 675–795 MB RSS +# at rest, so cold-boot JS evaluation + GC at that CPU share is the leading +# explanation. +# +# Lambda scales CPU linearly with memory, and Netlify now exposes per-function +# memory on Credit-based Pro/Enterprise (docs updated 2026-07; unavailable when +# #1124 was first written up). Doubling to 2048 MB doubles the boot CPU share, +# which should shrink the stall proportionally IF that reading is right. This +# is a measured-or-reverted claim: verify on the deploy preview burst test +# before believing it, and revert if the distribution doesn't move. +# +# Cost: function billing scales linearly with configured memory (GB-Hours), so +# this doubles compute cost per invocation. Warm invocations are milliseconds, +# so in absolute terms this is small; the stall itself was also being billed at +# ~30s per hit before this change. +# +# Both generated functions are covered. ___netlify-handler serves SSR/API/RSC +# traffic; ___netlify-odb-handler serves ISR regeneration/fallback — the exact +# path a cache-missed public page takes. The names are what +# @netlify/plugin-nextjs generates and are stable across deploys of a runtime +# major. +# ───────────────────────────────────────────────────────────────────────────── +[functions."___netlify-handler"] + memory = 2048 + +[functions."___netlify-odb-handler"] + memory = 2048 + # Skip builds for Dependabot PRs [context.deploy-preview] ignore = """ From 289d884e29e7b948fba16c8602cb3eac8ccf79dd Mon Sep 17 00:00:00 2001 From: Kaustav Ghosh <44238657+teetangh@users.noreply.github.com> Date: Sat, 22 Aug 2026 12:40:02 +0530 Subject: [PATCH 10/18] fix(ci): stagger keep-warm off 00:05 for the workflow-hygiene guard */5 fires at :05 past every hour including 00:05, where retry-failed-emails starts; check-workflow-hygiene.ts fails CI on recurring start collisions. 3-59/5 keeps the identical cadence on a free minute map. --- .github/workflows/keep-warm.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/keep-warm.yml b/.github/workflows/keep-warm.yml index b0b45b0de..ed53b762b 100644 --- a/.github/workflows/keep-warm.yml +++ b/.github/workflows/keep-warm.yml @@ -20,7 +20,11 @@ name: Keep Warm on: schedule: - - cron: "*/5 * * * *" + # 3-59/5 = :03,:08,:13… — same 5-minute cadence as */5 but offset off the + # fleet's minute map: scripts/ci/check-workflow-hygiene.ts fails CI on any + # recurring start-time collision, and */5 lands on 00:05 where + # retry-failed-emails already fires. + - cron: "3-59/5 * * * *" workflow_dispatch: permissions: From f2e5d1a93c591a4f8b1bea61349b2dbef1b4736a Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 22 Aug 2026 07:11:34 +0000 Subject: [PATCH 11/18] fix(ci): keep-warm loops its 5-minute pings inside one hourly job MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit check-workflow-hygiene forbids two multi-daily crons sharing any start minute, and this fleet's minute map leaves only :00/:03/:10/:15 free of multi-daily jobs — no 12-per-hour (or 6-per-hour) cron lattice can pass. Start hourly at :10 (a free minute) and run the 5-minute ping cadence as an in-job loop (11 rounds x 300s sleep, timeout 58m). Warmth cadence and Netlify-side cost are unchanged; only the hourly start is exposed to GitHub's best-effort schedule lag now, instead of all twelve firings. concurrency cancel-in-progress flips to true so a lagged start supersedes the previous hour's loop instead of double-pinging. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SKb2cFx2XCYrPKDrrENgqJ --- .github/workflows/keep-warm.yml | 43 +++++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 13 deletions(-) diff --git a/.github/workflows/keep-warm.yml b/.github/workflows/keep-warm.yml index ed53b762b..2c1bb6a68 100644 --- a/.github/workflows/keep-warm.yml +++ b/.github/workflows/keep-warm.yml @@ -16,15 +16,23 @@ name: Keep Warm # going cold is unavoidable (warm-deploy.yml covers their first minutes). # # GitHub schedule triggers are best-effort with no SLA and can lag several -# minutes; treat the interval as "roughly every 5 minutes", not exact. +# minutes; only the hourly START is exposed to that lag — the 5-minute ping +# cadence itself runs as an in-job loop and is exact. on: schedule: - # 3-59/5 = :03,:08,:13… — same 5-minute cadence as */5 but offset off the - # fleet's minute map: scripts/ci/check-workflow-hygiene.ts fails CI on any - # recurring start-time collision, and */5 lands on 00:05 where - # retry-failed-emails already fires. - - cron: "3-59/5 * * * *" + # Hourly at :10, with the 5-minute ping cadence implemented as a loop + # INSIDE the job rather than as a */5 cron. The check-workflow-hygiene + # gate forbids two multi-daily crons sharing any start minute, and this + # fleet's minute map is dense enough that no 12-per-hour (or even + # 6-per-hour) schedule has a clean lattice — an offset grid like 3-59/5 + # still collides with the hourly and */6 jobs at :08/:13/:18/:23/:28/ + # :33/:38/:58, and :00, :03, :10 and :15 are the only minutes free of + # multi-daily jobs. One hourly start on a free minute keeps the gate + # green while the loop below preserves the real warm cadence; it also + # shrinks exposure to GitHub's best-effort schedule lag (one delayed + # start per hour instead of twelve). + - cron: "10 * * * *" workflow_dispatch: permissions: @@ -32,12 +40,15 @@ permissions: concurrency: group: keep-warm - cancel-in-progress: false + # A lagged start can overlap the previous hour's loop; the newer run + # supersedes it rather than double-pinging. + cancel-in-progress: true jobs: ping: runs-on: ubuntu-latest - timeout-minutes: 5 + # One hour of 5-minute pings, then exit before the next scheduled run. + timeout-minutes: 58 steps: # The canonical production origins: the Netlify host and the pinned @@ -50,14 +61,20 @@ jobs: # that proves end-to-end liveness: LIMIT-1 DB probe + status reads, and # doubles as an outage signal — if these pings start failing, prod is # degraded whether or not any user has noticed yet. - - name: Ping production + - name: Ping production every 5 minutes for an hour env: HOSTS: "https://familiarisenow.com https://familiarise.netlify.app" run: | - for host in $HOSTS; do - curl -sS -o /dev/null -w "$host/api/health: ttfb=%{time_starttransfer}s code=%{http_code}\n" \ - --max-time 60 --retry 1 --retry-delay 3 \ - "$host/api/health" || echo "::warning::keep-warm ping failed for $host" + # 11 rounds x 5-minute sleep ≈ 55 minutes of coverage per hourly + # run; the next run picks up at :10. Pings are sequential and the + # loop sleeps between rounds, so this never bursts the function. + for round in $(seq 1 11); do + for host in $HOSTS; do + curl -sS -o /dev/null -w "$host/api/health: ttfb=%{time_starttransfer}s code=%{http_code}\n" \ + --max-time 60 --retry 1 --retry-delay 3 \ + "$host/api/health" || echo "::warning::keep-warm ping failed for $host" + done + if [ "$round" -lt 11 ]; then sleep 300; fi done # NOTE: hot page caches are deliberately NOT refreshed here. The ISR From 634c0d5a0b1262a3a4126e22d412ea0efbdef177 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 22 Aug 2026 07:14:01 +0000 Subject: [PATCH 12/18] fix(ci): address CodeRabbit review on the warm-up workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Drop the `states:` block under deployment_status: that trigger supports no filter keys, so the block was inert config — the job-level `deployment_status.state == 'success'` condition is (and was) the real gate. - Parse the /api/health BODY in both workflows: the endpoint is fail-open and answers HTTP 200 with status "degraded" when the database is unreachable, so a bare curl exit code is not a health verdict. warm-deploy now FAILS on a non-healthy status (the ISR pages rethrow on DB failure, so warming a degraded origin would 500 every ping and cache nothing); keep-warm WARNS and keeps looping, since the ping still warms the instance and doubles as the outage signal. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SKb2cFx2XCYrPKDrrENgqJ --- .github/workflows/keep-warm.yml | 20 +++++++++++++++++--- .github/workflows/warm-deploy.yml | 25 ++++++++++++++++++++----- 2 files changed, 37 insertions(+), 8 deletions(-) diff --git a/.github/workflows/keep-warm.yml b/.github/workflows/keep-warm.yml index 2c1bb6a68..826efb16b 100644 --- a/.github/workflows/keep-warm.yml +++ b/.github/workflows/keep-warm.yml @@ -68,11 +68,25 @@ jobs: # 11 rounds x 5-minute sleep ≈ 55 minutes of coverage per hourly # run; the next run picks up at :10. Pings are sequential and the # loop sleeps between rounds, so this never bursts the function. + # + # /api/health is fail-open: HTTP 200 with status "degraded" when the + # DB is unreachable, so the body is parsed too. Degradation is a + # WARNING here, not a failure — the ping still warmed the instance, + # and the loop keeps running so warmth (and the outage signal) + # continue through the incident. for round in $(seq 1 11); do for host in $HOSTS; do - curl -sS -o /dev/null -w "$host/api/health: ttfb=%{time_starttransfer}s code=%{http_code}\n" \ - --max-time 60 --retry 1 --retry-delay 3 \ - "$host/api/health" || echo "::warning::keep-warm ping failed for $host" + if BODY=$(curl -sS -w "\n$host/api/health: ttfb=%{time_starttransfer}s code=%{http_code}" \ + --fail --max-time 60 --retry 1 --retry-delay 3 \ + "$host/api/health"); then + echo "${BODY##*$'\n'}" + STATUS=$(printf '%s' "$BODY" | head -n 1 | jq -r '.status // "unknown"') + if [ "$STATUS" != "healthy" ]; then + echo "::warning::keep-warm: $host reports health status '$STATUS' — prod degraded" + fi + else + echo "::warning::keep-warm ping failed for $host" + fi done if [ "$round" -lt 11 ]; then sleep 300; fi done diff --git a/.github/workflows/warm-deploy.yml b/.github/workflows/warm-deploy.yml index 550b15a5e..9e3cc99bc 100644 --- a/.github/workflows/warm-deploy.yml +++ b/.github/workflows/warm-deploy.yml @@ -24,10 +24,11 @@ name: Warm Deploy # This does not keep instances alive (see keep-warm.yml); it only removes the # empty-cache window right after a deploy. +# deployment_status supports no trigger-level filter (no `types`/`states` +# narrowing exists for it) — the workflow fires on every status event and the +# job-level `if` below is the real gate. on: deployment_status: - states: - - success workflow_dispatch: inputs: base_url: @@ -71,11 +72,25 @@ jobs: # The first request against a brand-new instance can legitimately take # ~30s (#1124), so max-time must sit well above that or the warm-up would # kill the very request doing the warming. + # + # /api/health is deliberately fail-open: it answers HTTP 200 with + # status "degraded" + database "unreachable" when the DB is down, so a + # bare curl exit code is NOT a health verdict. Parse the body: warming a + # degraded origin is worse than useless — the ISR pages rethrow on DB + # failure (#1123), so every page ping would 500, cache nothing, and the + # run would still report success. Fail here instead so the red run says + # "deploy is up but degraded; nothing was warmed". - name: Warm the function instance (health probe) run: | - curl -sS -o /dev/null -w "health: ttfb=%{time_starttransfer}s code=%{http_code}\n" \ - --max-time 60 --retry 1 --retry-delay 2 \ - "${{ steps.url.outputs.base }}/api/health" + BODY=$(curl -sS -w "\nhealth: ttfb=%{time_starttransfer}s code=%{http_code}" \ + --fail --max-time 60 --retry 1 --retry-delay 2 \ + "${{ steps.url.outputs.base }}/api/health") + echo "${BODY##*$'\n'}" + STATUS=$(printf '%s' "$BODY" | head -n 1 | jq -r '.status // "unknown"') + if [ "$STATUS" != "healthy" ]; then + echo "::error::health status is '$STATUS' (not healthy) — origin degraded, skipping page warming" + exit 1 + fi # Hot public routes in click-order value. Keep this list short and # deliberate: every line is a billable invocation, and sequential curls From 886d7bff59cf84196bd265254beebe404122a057 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 22 Aug 2026 07:19:44 +0000 Subject: [PATCH 13/18] test(ci): give the cron-lock registry an HTTP-only workflow category MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit keep-warm.yml is the first scheduled workflow that never enters the app — its job is a curl heartbeat against /api/health (#1124), so there is no .ts entrypoint to resolve and nothing a cron lock could protect; a double-run costs one extra GET against a public endpoint. The #1169 registry only knew entrypoint-bearing jobs (LOCK_EXEMPT still requires a resolvable entrypoint, per cron-heartbeat.yml). Add an HTTP_ONLY map with the same contracts as LOCK_EXEMPT: named reason per workflow, staleness-checked, and evicted if the job ever grows a real lock. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SKb2cFx2XCYrPKDrrENgqJ --- .../maintenance/cron-lock-registry.test.ts | 30 +++++++++++++++---- 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/__tests__/maintenance/cron-lock-registry.test.ts b/__tests__/maintenance/cron-lock-registry.test.ts index ba68a99fe..e5730d3a0 100644 --- a/__tests__/maintenance/cron-lock-registry.test.ts +++ b/__tests__/maintenance/cron-lock-registry.test.ts @@ -51,6 +51,15 @@ const LOCK_EXEMPT: Record = { "cron-heartbeat.yml": "deliberately unlocked — read-only dead-man switch", }; +// Scheduled workflows whose job never enters the app: pure HTTP probes with +// no .ts entrypoint to resolve and nothing a cron lock could protect — a +// double-run costs one extra GET against a public endpoint. Keep this list +// to jobs that only curl; anything that executes repo code belongs in the +// entrypoint/lock regime above. +const HTTP_ONLY: Record = { + "keep-warm.yml": "curl heartbeat against /api/health (#1124) — no app code runs", +}; + interface Row { workflow: string; entrypoint: string | null; @@ -172,14 +181,19 @@ describe("cron lock registry (#1169)", () => { it("resolves an entrypoint for every scheduled workflow", () => { const unresolved = registry - .filter((r) => !r.entrypoint) + .filter((r) => !r.entrypoint && !(r.workflow in HTTP_ONLY)) .map((r) => r.workflow); expect(unresolved).toEqual([]); }); it("locks every scheduled job, or names why it does not", () => { const unlocked = registry - .filter((r) => !r.lockedIn && !(r.workflow in LOCK_EXEMPT)) + .filter( + (r) => + !r.lockedIn && + !(r.workflow in LOCK_EXEMPT) && + !(r.workflow in HTTP_ONLY), + ) .map((r) => `${r.workflow} → ${r.entrypoint} (no withCronLock)`); // Wrap the core in withCronLock rather than adding to LOCK_EXEMPT: an @@ -188,15 +202,19 @@ describe("cron lock registry (#1169)", () => { }); it("keeps every exemption pointing at a workflow that still exists", () => { - const stale = Object.keys(LOCK_EXEMPT).filter( - (wf) => !registry.some((r) => r.workflow === wf), - ); + const stale = [ + ...Object.keys(LOCK_EXEMPT), + ...Object.keys(HTTP_ONLY), + ].filter((wf) => !registry.some((r) => r.workflow === wf)); expect(stale).toEqual([]); }); it("drops an exemption once the job grows a real lock", () => { const redundant = registry - .filter((r) => r.workflow in LOCK_EXEMPT && r.lockedIn) + .filter( + (r) => + (r.workflow in LOCK_EXEMPT || r.workflow in HTTP_ONLY) && r.lockedIn, + ) .map((r) => r.workflow); expect(redundant).toEqual([]); }); From 17228d7e04d58ac3ab99d55752f86db563a68a96 Mon Sep 17 00:00:00 2001 From: Kaustav Ghosh <44238657+teetangh@users.noreply.github.com> Date: Sat, 22 Aug 2026 13:19:38 +0530 Subject: [PATCH 14/18] =?UTF-8?q?fix(netlify):=20target=20=5F=5F=5Fnetlify?= =?UTF-8?q?-server-handler=20=E2=80=94=20the=20v1=20handler=20names=20matc?= =?UTF-8?q?h=20nothing?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 2048 MB override was silently inert: runtime API v2 (@netlify/plugin-nextjs@5.15.13) generates a single ___netlify-server-handler; ___netlify-handler/___netlify-odb-handler are v1 names. Confirmed via listSiteFunctions — one function on the site, m=1024. The first preview burst (11/12 at 32.8-35.1s, indistinguishable from the 1024 MB baseline) measured a no-op, which is exactly why this correction exists before any revert verdict. --- netlify.toml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/netlify.toml b/netlify.toml index dc2c8f07e..fece4bb31 100644 --- a/netlify.toml +++ b/netlify.toml @@ -38,16 +38,16 @@ # so in absolute terms this is small; the stall itself was also being billed at # ~30s per hit before this change. # -# Both generated functions are covered. ___netlify-handler serves SSR/API/RSC -# traffic; ___netlify-odb-handler serves ISR regeneration/fallback — the exact -# path a cache-missed public page takes. The names are what -# @netlify/plugin-nextjs generates and are stable across deploys of a runtime -# major. +# One generated function covers everything. Runtime API v2 consolidated the old +# SSR handler and ISR/odb handler into a single ___netlify-server-handler +# (@netlify/plugin-nextjs@5.15.13, confirmed via listSiteFunctions on 2026-08-22: +# the only function on the site, m=1024). The classic ___netlify-handler / +# ___netlify-odb-handler names belong to runtime v1 and match NOTHING today — an +# earlier draft targeted them and Netlify silently ignored the override, which +# is exactly how a "measured" no-op happens. If the adapter major bumps again, +# re-enumerate names before trusting this block. # ───────────────────────────────────────────────────────────────────────────── -[functions."___netlify-handler"] - memory = 2048 - -[functions."___netlify-odb-handler"] +[functions."___netlify-server-handler"] memory = 2048 # Skip builds for Dependabot PRs From 08b10ce4e49a7d560da9b2c8e6eef6918418bdf3 Mon Sep 17 00:00:00 2001 From: Kaustav Ghosh <44238657+teetangh@users.noreply.github.com> Date: Sat, 22 Aug 2026 13:43:45 +0530 Subject: [PATCH 15/18] revert(netlify): 2048 MB handler memory measured no better, possibly worse Correctly-applied treatment (___netlify-server-handler, confirmed the only generated function) vs same-protocol control on preview bursts: 1024 MB: 11/12 slow at 27.8-31.0s 2048 MB: 11/12 slow at 35.9-37.6s + one platform 500 Doubling CPU share does not shrink the #1124 stall; memory-starved boot is a weakened explanation. Reverted per the measured-or-reverted doctrine; both readings recorded inline so this lever is not re-pulled blind. --- netlify.toml | 54 ++++++++++++++++++++++++---------------------------- 1 file changed, 25 insertions(+), 29 deletions(-) diff --git a/netlify.toml b/netlify.toml index fece4bb31..c8c8adfbb 100644 --- a/netlify.toml +++ b/netlify.toml @@ -15,40 +15,36 @@ NODE_OPTIONS = "--max-old-space-size=6144" # ───────────────────────────────────────────────────────────────────────────── -# Function memory (#1124) +# Function memory for #1124 — ASSESSED AND REVERTED. Do not re-add without +# rereading the two measurements below. # -# A brand-new instance of the Next.js server handler stalls its event loop for -# roughly 24s on its first invocation, BEFORE any application work — the whole -# of the 20–30s tail on public routes (issue #1124, reproduced 2026-08-22: -# 11/12 concurrent unique-key requests to a deploy preview landed at -# 27.8–31.0s TTFB while same-key requests coalesced at 2.7–5.4s). The function -# boots at AWS_LAMBDA_FUNCTION_MEMORY_SIZE=1024 → ~0.5 vCPU with 675–795 MB RSS -# at rest, so cold-boot JS evaluation + GC at that CPU share is the leading -# explanation. +# The stall: a brand-new instance of the Next.js server handler blocks its +# event loop ~24s before any application work — the whole of the 20–30s tail +# on public routes (#1124; reproduced 2026-08-22: 11/12 concurrent unique-key +# requests to deploy preview 1195 at 27.8–31.0s TTFB while same-key requests +# coalesced at 2.7–5.4s). Leading hypothesis was cold-boot JS/GC at Lambda's +# memory-proportional CPU share (1024 MB → ~0.5 vCPU, RSS 675–795 MB at rest). # -# Lambda scales CPU linearly with memory, and Netlify now exposes per-function -# memory on Credit-based Pro/Enterprise (docs updated 2026-07; unavailable when -# #1124 was first written up). Doubling to 2048 MB doubles the boot CPU share, -# which should shrink the stall proportionally IF that reading is right. This -# is a measured-or-reverted claim: verify on the deploy preview burst test -# before believing it, and revert if the distribution doesn't move. +# Netlify now exposes per-function `memory` up to 4096 MB on Credit-based +# Pro/Enterprise, so the hypothesis became testable. Two preview measurements, +# same 12-way concurrent unique-key protocol, 2026-08-22: # -# Cost: function billing scales linearly with configured memory (GB-Hours), so -# this doubles compute cost per invocation. Warm invocations are milliseconds, -# so in absolute terms this is small; the stall itself was also being billed at -# ~30s per hit before this change. +# 1024 MB (control) 11/12 slow at 27.8–31.0 s +# 2048 MB (treatment) 11/12 slow at 35.9–37.6 s, one platform 500 # -# One generated function covers everything. Runtime API v2 consolidated the old -# SSR handler and ISR/odb handler into a single ___netlify-server-handler -# (@netlify/plugin-nextjs@5.15.13, confirmed via listSiteFunctions on 2026-08-22: -# the only function on the site, m=1024). The classic ___netlify-handler / -# ___netlify-odb-handler names belong to runtime v1 and match NOTHING today — an -# earlier draft targeted them and Netlify silently ignored the override, which -# is exactly how a "measured" no-op happens. If the adapter major bumps again, -# re-enumerate names before trusting this block. +# No improvement; possibly a regression (a doubled heap is more boot work, not +# less, if initialization dominates). Doubling CPU share does not touch this +# stall, so "memory/CPU-starved boot" is now a weakened explanation and the +# effective levers are the ones that avoid invoking a cold instance at all: +# ISR cache hits, warm-deploy priming, and netlify/functions keep-warm. +# +# GOTCHA that made the first measurement worthless: runtime API v2 +# (@netlify/plugin-nextjs@5.15.13) generates ONE function named +# ___netlify-server-handler. The classic ___netlify-handler / +# ___netlify-odb-handler names belong to v1 and match NOTHING — a toml block +# targeting them is silently ignored (confirmed via searchSiteFunctions: +# m stayed 1024). Re-enumerate names after any adapter bump. # ───────────────────────────────────────────────────────────────────────────── -[functions."___netlify-server-handler"] - memory = 2048 # Skip builds for Dependabot PRs [context.deploy-preview] From 6ff6038a4b00ea9d03586ddd1b210a8a6711232f Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 22 Aug 2026 08:19:52 +0000 Subject: [PATCH 16/18] =?UTF-8?q?fix(ci):=20move=20keep-warm=20to=20:03=20?= =?UTF-8?q?=E2=80=94=20dev's=20expire-stale-requests=20took=20:10?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit dev commit d8484ae6 (booking journey hardening 2a) re-scheduled expire-stale-requests to hourly-at-:10, the minute keep-warm had claimed, so the PR merge build failed the workflow-hygiene gate even though both branches passed alone. Re-derived the free-minute pool against the merged fleet — only :00, :03 and :15 remain free of multi-daily crons — and moved keep-warm to :03, with the shrinking-pool caveat recorded in the comment. Includes the dev merge itself (clean). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SKb2cFx2XCYrPKDrrENgqJ --- .github/workflows/keep-warm.yml | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/.github/workflows/keep-warm.yml b/.github/workflows/keep-warm.yml index 826efb16b..d5cb01ce0 100644 --- a/.github/workflows/keep-warm.yml +++ b/.github/workflows/keep-warm.yml @@ -21,18 +21,23 @@ name: Keep Warm on: schedule: - # Hourly at :10, with the 5-minute ping cadence implemented as a loop + # Hourly at :03, with the 5-minute ping cadence implemented as a loop # INSIDE the job rather than as a */5 cron. The check-workflow-hygiene # gate forbids two multi-daily crons sharing any start minute, and this # fleet's minute map is dense enough that no 12-per-hour (or even # 6-per-hour) schedule has a clean lattice — an offset grid like 3-59/5 # still collides with the hourly and */6 jobs at :08/:13/:18/:23/:28/ - # :33/:38/:58, and :00, :03, :10 and :15 are the only minutes free of - # multi-daily jobs. One hourly start on a free minute keeps the gate - # green while the loop below preserves the real warm cadence; it also - # shrinks exposure to GitHub's best-effort schedule lag (one delayed - # start per hour instead of twelve). - - cron: "10 * * * *" + # :33/:38/:58. One hourly start on a free minute keeps the gate green + # while the loop below preserves the real warm cadence; it also shrinks + # exposure to GitHub's best-effort schedule lag (one delayed start per + # hour instead of twelve). + # + # :03 because the free-minute pool is nearly empty and SHRINKS as dev + # moves: this job started at :10 and dev's expire-stale-requests went + # hourly-at-:10 the same day, colliding in the PR merge build. As of + # 2026-08-22 the only minutes free of multi-daily crons are :00, :03 + # and :15 — re-derive that set before moving this again. + - cron: "3 * * * *" workflow_dispatch: permissions: From 58fb03fce3948b15b4c4c1eb552e11d886424e6e Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 22 Aug 2026 08:22:01 +0000 Subject: [PATCH 17/18] fix(ci): address CodeRabbit round 3 on the warm-up workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - warm-deploy: the deploy URL comes from the deployment event payload and was template-expanded into three run scripts — a URL containing shell syntax would alter the script before bash parses it (zizmor template-injection). Validate it as a bare https origin at resolve time and pass it through env indirection ("$BASE_URL") in every step. - warm-deploy: warm /explore/programs too (page + RSC payload) — the route this PR converts to ISR was missing from the warm list. - keep-warm: deadline guard at 50 minutes. If both hosts hit --max-time on the initial attempt and the retry every round, the loop's worst case (~95 min) exceeds the 58-minute job timeout and GitHub would cancel mid-loop; stop starting rounds instead and let the next hourly run pick up. - cron-lock registry: HTTP_ONLY now only exempts a row while it truly has no entrypoint, and a new invariant test fails the moment an HTTP_ONLY workflow grows one — name-keyed exemptions can't outlive their justification. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SKb2cFx2XCYrPKDrrENgqJ --- .github/workflows/keep-warm.yml | 13 +++++++++- .github/workflows/warm-deploy.yml | 24 +++++++++++++++---- .../maintenance/cron-lock-registry.test.ts | 14 ++++++++++- 3 files changed, 44 insertions(+), 7 deletions(-) diff --git a/.github/workflows/keep-warm.yml b/.github/workflows/keep-warm.yml index d5cb01ce0..b4ea61a18 100644 --- a/.github/workflows/keep-warm.yml +++ b/.github/workflows/keep-warm.yml @@ -71,15 +71,26 @@ jobs: HOSTS: "https://familiarisenow.com https://familiarise.netlify.app" run: | # 11 rounds x 5-minute sleep ≈ 55 minutes of coverage per hourly - # run; the next run picks up at :10. Pings are sequential and the + # run; the next run picks up next hour. Pings are sequential and the # loop sleeps between rounds, so this never bursts the function. # + # DEADLINE guard: the happy path fits easily, but if both hosts hit + # --max-time on the initial attempt AND the retry every round, the + # arithmetic exceeds the 58-minute job timeout (~95 min worst case) + # and GitHub would cancel mid-loop. Stop starting new rounds once + # 50 minutes have elapsed instead — the next hourly run continues. + # # /api/health is fail-open: HTTP 200 with status "degraded" when the # DB is unreachable, so the body is parsed too. Degradation is a # WARNING here, not a failure — the ping still warmed the instance, # and the loop keeps running so warmth (and the outage signal) # continue through the incident. + DEADLINE=$((SECONDS + 50 * 60)) for round in $(seq 1 11); do + if [ "$SECONDS" -ge "$DEADLINE" ]; then + echo "::notice::keep-warm stopping at round $round — 50-minute deadline reached" + break + fi for host in $HOSTS; do if BODY=$(curl -sS -w "\n$host/api/health: ttfb=%{time_starttransfer}s code=%{http_code}" \ --fail --max-time 60 --retry 1 --retry-delay 3 \ diff --git a/.github/workflows/warm-deploy.yml b/.github/workflows/warm-deploy.yml index 9e3cc99bc..909f55fcb 100644 --- a/.github/workflows/warm-deploy.yml +++ b/.github/workflows/warm-deploy.yml @@ -66,6 +66,14 @@ jobs: fi # Strip a trailing slash so the path concatenations below stay clean. BASE="${BASE%/}" + # The URL comes from the deployment event payload, i.e. from outside + # this repo. It is only ever used through env indirection below, but + # validate the shape anyway so nothing resembling shell syntax (or a + # control character) ever reaches a run script or GITHUB_OUTPUT. + if ! printf '%s' "$BASE" | grep -Eq '^https://[A-Za-z0-9.-]+(:[0-9]+)?$'; then + echo "::error::environment_url '$BASE' is not a bare https origin; refusing to warm" + exit 1 + fi echo "base=$BASE" >> "$GITHUB_OUTPUT" echo "Warming $BASE" @@ -81,10 +89,12 @@ jobs: # run would still report success. Fail here instead so the red run says # "deploy is up but degraded; nothing was warmed". - name: Warm the function instance (health probe) + env: + BASE_URL: ${{ steps.url.outputs.base }} run: | BODY=$(curl -sS -w "\nhealth: ttfb=%{time_starttransfer}s code=%{http_code}" \ --fail --max-time 60 --retry 1 --retry-delay 2 \ - "${{ steps.url.outputs.base }}/api/health") + "$BASE_URL/api/health") echo "${BODY##*$'\n'}" STATUS=$(printf '%s' "$BODY" | head -n 1 | jq -r '.status // "unknown"') if [ "$STATUS" != "healthy" ]; then @@ -96,9 +106,11 @@ jobs: # deliberate: every line is a billable invocation, and sequential curls # share the instance warmed above. - name: Warm hot public pages + env: + BASE_URL: ${{ steps.url.outputs.base }} run: | - BASE="${{ steps.url.outputs.base }}" - for path in "/" "/explore/experts" "/explore/community" "/about"; do + BASE="$BASE_URL" + for path in "/" "/explore/experts" "/explore/programs" "/explore/community" "/about"; do curl -sS -o /dev/null -w "$path: ttfb=%{time_starttransfer}s code=%{http_code}\n" \ --max-time 45 "$BASE$path" || true sleep 1 @@ -109,9 +121,11 @@ jobs: # function. A generic RSC request also re-walks the render path, keeping # the instance hot. - name: Warm RSC navigation payloads + env: + BASE_URL: ${{ steps.url.outputs.base }} run: | - BASE="${{ steps.url.outputs.base }}" - for path in "/explore/experts" "/about"; do + BASE="$BASE_URL" + for path in "/explore/experts" "/explore/programs" "/about"; do curl -sS -o /dev/null -H "RSC: 1" \ -w "rsc $path: ttfb=%{time_starttransfer}s code=%{http_code}\n" \ --max-time 45 "$BASE$path?_rsc=warmup" || true diff --git a/__tests__/maintenance/cron-lock-registry.test.ts b/__tests__/maintenance/cron-lock-registry.test.ts index e5730d3a0..b814ad7dd 100644 --- a/__tests__/maintenance/cron-lock-registry.test.ts +++ b/__tests__/maintenance/cron-lock-registry.test.ts @@ -192,7 +192,9 @@ describe("cron lock registry (#1169)", () => { (r) => !r.lockedIn && !(r.workflow in LOCK_EXEMPT) && - !(r.workflow in HTTP_ONLY), + // HTTP_ONLY only exempts a job while it truly runs no app code; a + // workflow that later grows an entrypoint re-enters the lock regime. + !(r.workflow in HTTP_ONLY && !r.entrypoint), ) .map((r) => `${r.workflow} → ${r.entrypoint} (no withCronLock)`); @@ -209,6 +211,16 @@ describe("cron lock registry (#1169)", () => { expect(stale).toEqual([]); }); + it("keeps HTTP_ONLY limited to workflows that never enter the app", () => { + // The exemption's whole justification is "no app code runs". A workflow + // that gains a tsx/npm-run entrypoint must leave HTTP_ONLY and take a + // real lock (or argue its way into LOCK_EXEMPT with an entrypoint). + const grown = registry + .filter((r) => r.workflow in HTTP_ONLY && r.entrypoint) + .map((r) => `${r.workflow} → ${r.entrypoint}`); + expect(grown).toEqual([]); + }); + it("drops an exemption once the job grows a real lock", () => { const redundant = registry .filter( From 0646d8f5bebb689e6db9abb137e06a6b0a7c2358 Mon Sep 17 00:00:00 2001 From: Kaustav Ghosh <44238657+teetangh@users.noreply.github.com> Date: Sat, 22 Aug 2026 15:35:39 +0530 Subject: [PATCH 18/18] =?UTF-8?q?docs(skill):=20record=20the=20stall=20res?= =?UTF-8?q?olution=20=E2=80=94=202048=20MB=20eliminates=20it;=20handler=20?= =?UTF-8?q?renamed=20in=20runtime=20v2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Measured A/B (same minute, same burst protocol): 1024 MB stalls 11-12/12 at 27.8-39.6s with platform-500 saturation; 2048 MB runs 16/16 at 3.1-4.9s. Also records the v1->v2 function rename hazard (silently inert overrides) and that deployment_status/schedule workflows read the default branch. --- .../skills/nextjs-netlify-caching/SKILL.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/.claude/skills/nextjs-netlify-caching/SKILL.md b/.claude/skills/nextjs-netlify-caching/SKILL.md index 126da4707..42c39cde0 100644 --- a/.claude/skills/nextjs-netlify-caching/SKILL.md +++ b/.claude/skills/nextjs-netlify-caching/SKILL.md @@ -212,14 +212,46 @@ The fix, shipped in #1123, is that degrading is now opt-in per call site (`perRe So on an ISR route, throwing is strictly better than degrading: the one unlucky visitor gets an error boundary, everyone else keeps the last good copy, and nothing bad is written down. +## The stall was resolved on 2026-08-22 by doubling handler memory — and the function changed names under us + +The ~24 s cold-instance event-loop stall described above is **confirmed CPU-proportional cold-boot work and is eliminated at 2048 MB**. Measured as an A/B against two live previews in the same minute, same protocol (N concurrent unique-key RSC requests to `/explore/experts` on a freshly deployed function): + +| handler | N | stalled | slow-mode TTFB | fast-mode | +|---|---|---|---|---| +| 1024 MB (preview 1195) | 12 | 11/12 | 27.8–31.0 s | 0.75 s | +| 1024 MB (preview 1148, see hazard below) | 12 | 11/12 | 32.8–35.1 s | 3.1 s | +| **2048 MB (preview 1148)** | 16 | **0/16** | — | **3.1–4.9 s** | +| 1024 MB control re-run, same minute | 12 | 12/12 | 31.9–39.6 s (+4 bare platform-500s) | — | + +Warm-mode render times were unchanged (~3–5 s), so this is pure tail removal. The fix shipped in PR #1148 as `[functions."___netlify-server-handler"] memory = 2048` in `netlify.toml`. Billing scales linearly with configured memory. Full write-up on issue #1124. + +Three facts that each cost an afternoon: + +**The generated function is `___netlify-server-handler` at @netlify/plugin-nextjs@5.15.13 (runtime API v2) — one consolidated SSR+ISR handler.** The classic `___netlify-handler` / `___netlify-odb-handler` names belong to runtime v1 and match nothing. Re-enumerate names after any adapter bump (`netlify api searchSiteFunctions --data '{"site_id": …}'`; the record's `m` field is the configured memory). + +**A `[functions."name"]` block targeting a nonexistent name is silently inert.** No warning, deploy green, config present in the repo. An earlier draft of the memory bump targeted the v1 names; its preview burst read 32.8–35.1 s and looked like a genuine refutation of the memory hypothesis. Verify the treatment landed (`searchSiteFunctions`, or a distribution shift against a same-minute control) before believing any null result. + +**Netlify per-function `memory`/`vcpu` exists since ~2026-07 on Credit-based Pro/Enterprise** (1024–4096 MB, 0.5–2.0 vCPU). This section previously recorded the stall as unmitigable because that lever did not exist when #1124 was written. It also cannot be set for framework-generated functions via in-source `config` exports — `netlify.toml` keyed by generated name works. + +Two warmers ship alongside (#1148): `warm-deploy.yml` fires on Netlify `deployment_status: success` and primes `/api/health` → hot pages sequentially → RSC payloads per deploy; `keep-warm.yml` starts hourly at `:10` and loops 5-minute `/api/health` pings inside the job (every minute of the GH cron map is owned by some multi-daily fleet job, so no sub-hourly cron lattice passes check-workflow-hygiene). Both activate only after merging to the default branch: `schedule` and `deployment_status` triggers read the workflow file from the default branch, not from a PR's merge ref — a preview of the PR adding them proves nothing about them. + + ## Options assessed and rejected — do not re-propose without new information Partial Prerendering and Cache Components are not merely "a Next 16 feature" — they are unreachable from our pinned version. At `next@15.5.15`, `packages/next/src/server/config.ts` throws `CanaryOnlyError` on a stable build for both `experimental.ppr` and `experimental.cacheComponents`, so even `experimental.ppr = "incremental"` fails at config load rather than degrading. Next's own [ppr-preview](https://nextjs.org/docs/messages/ppr-preview) page confirms a canary release is required. This matters because PPR is the textbook answer to "a static page with one dynamic hole", and on this version that answer simply does not exist — a `Suspense` boundary around a dynamic read does **not** rescue static rendering without PPR. Separately, `use cache` would not help a route whose every segment is auth-gated, and every dashboard route here is auth-gated. Caching a dynamic route at the CDN with `Netlify-CDN-Cache-Control` is technically sound and was considered for the public pages, but it still invokes the function on every cache miss, so it does not solve the cold start the way prerendering does. It remains the right tool when build-time data access is genuinely unacceptable. +**Raising the handler's memory is measured dead (2026-08-22, PR #1148 branch).** Netlify now exposes per-function `memory` up to 4096 MB on Credit-based Pro/Enterprise (`[functions."NAME"]` in `netlify.toml`; unavailable when #1124 was first written). Same 12-way concurrent unique-key burst protocol on deploy previews: 1024 MB control put 11/12 requests at 27.8–31.0 s; a correctly-applied 2048 MB treatment put 11/12 at 35.9–37.6 s with one platform 500. No improvement, possibly a regression. The "CPU-starved boot" reading of the #1124 stall is therefore weakened — do not re-pull this lever without a new mechanism hypothesis. + Verified clean and not worth re-investigating: `next/image` usage (there are zero raw `` tags), fonts (`next/font/google` with `display: swap`), `staleTimes`, `serverExternalPackages`, the Prisma singleton, and the bundle-analyzer tooling. +## Function-name and config-verification facts (added 2026-08-22) + +Runtime API v2 of `@netlify/plugin-nextjs@5.15.13` generates **one** function named `___netlify-server-handler`. The classic v1 names `___netlify-handler` / `___netlify-odb-handler` match nothing on this site; a `[functions."___netlify-handler"]` block in `netlify.toml` is **silently ignored**, and every request keeps serving at 1024 MB while the config reads as if it were doing something — an earlier #1124 attempt lost its entire first measurement to this. Enumerate real names and per-function memory with `netlify api searchSiteFunctions --data '{"site_id": …}'` (response shape: list of deploys → `.functions[].n` name, `.functions[].m` memory MB); note it scopes to the published production deploy, not preview deploys. Re-enumerate names after any adapter bump. + +Two more verification gotchas from the same day: GitHub webhook-style triggers (`deployment_status`, `schedule`) read the workflow file **from the default branch only**, so new warm-up workflows stay inert on PR previews until merged to dev — CI green does not mean they ran. And `scripts/ci/check-workflow-hygiene.ts` rejects any two recurring crons sharing a start minute; every minute of the day is owned by some multi-daily workflow in this fleet, which is why keep-warm runs as one hourly start (:10) looping 5-minute pings inside the job rather than as a `*/5` cron. + ## Project constraints that constrain every change here ESLint warnings are blocking, because SonarCloud fails the quality gate on unused variables. Never filter ESLint output for errors alone.