@pylonsync/functions 0.3.292 → 0.3.293

package/dist/ssr-runtime.d.ts

@@ -0,0 +1,419 @@
+/**
+ * Is the runtime in dev mode? MUST match the Rust host's `is_dev_mode()`
+ * (crates/runtime/src/frontend.rs): `PYLON_DEV_MODE` is on ONLY for the exact
+ * strings "1" or "true" (case-insensitive). A bare `if (process.env.PYLON_DEV_MODE)`
+ * is WRONG — the string "false"/"0" is truthy in JS, so an explicit
+ * `PYLON_DEV_MODE=false` on a PROD machine would wrongly enable dev behavior
+ * (e.g. the live-reload `<script>` was being injected into prod pages, whose
+ * EventSource then 404-retried `/_pylon/dev/live` forever).
+ */
+export declare function isDevMode(): boolean;
+/**
+ * The message payload the host sends. Matches RenderRouteMessage in
+ * crates/functions/src/protocol.rs.
+ */
+export interface RenderRouteMessage {
+    type: "render_route";
+    call_id: string;
+    /**
+     * Project-relative module path (e.g. "app/hello/page"). The
+     * adapter joins cwd + this + the right extension (.tsx → .ts).
+     */
+    component: string;
+    /**
+     * Project-relative module paths for the layout chain, walked
+     * root → leaf. Each layout's default export wraps the next as
+     * `children`. Absent / empty when no layouts apply.
+     *
+     * Example:
+     *   layouts: ["app/layout", "app/blog/layout"]
+     *   component: "app/blog/[slug]/page"
+     *
+     * Resolves to:
+     *   <RootLayout>
+     *     <BlogLayout>
+     *       <Page {...props} />
+     *     </BlogLayout>
+     *   </RootLayout>
+     */
+    layouts?: string[];
+    /** The matched route pattern (e.g. `/blog/:slug`). */
+    route_path: string;
+    /** The incoming URL path (e.g. `/blog/hello-world`). */
+    url: string;
+    /** Dynamic-segment matches keyed by name (e.g. `{slug: "hello-world"}`). */
+    params: Record<string, string>;
+    /** Parsed query string. */
+    search_params: Record<string, string>;
+    /** Lowercased header names → values. */
+    headers: Record<string, string>;
+    /** Parsed cookies. */
+    cookies: Record<string, string>;
+    /** Pylon auth context. */
+    auth: {
+        user_id: string | null;
+        is_admin: boolean;
+        tenant_id: string | null;
+        roles: string[];
+    };
+    /**
+     * Initial HTTP status the response controller starts at (default 200).
+     * The host sets this to 404 when dispatching a `not-found.tsx` render
+     * for an unmatched URL, so the boundary streams at 404 without the
+     * component having to call `response.setStatus`. A page can still
+     * override it via `response.setStatus`.
+     */
+    initial_status?: number;
+}
+type Send = (msg: Record<string, unknown>) => void;
+/**
+ * Control-flow signal a page or layout throws to short-circuit the
+ * render: `response.redirect(url)` / `response.notFound()`. The adapter
+ * catches it and turns it into a 3xx + Location or a 404 instead of a
+ * normal 200 body. Extends Error so React's stream rejects cleanly when
+ * it's thrown during the shell render. (Throw it OUTSIDE an error
+ * boundary — an enclosing boundary would swallow the signal.)
+ */
+export declare class PylonRouteControl extends Error {
+    kind: "redirect" | "notFound";
+    url?: string;
+    redirectStatus?: number;
+    constructor(kind: "redirect" | "notFound");
+}
+/**
+ * Normalize a thrown value into a route-control signal: either the framework's
+ * own `PylonRouteControl` (`response.redirect()` / `response.notFound()`) or a
+ * branded `NotFoundError` thrown by `@pylonsync/react`'s `notFound()` from a
+ * page/layout render. Returns `null` for an ordinary error so the caller falls
+ * through to its real error-handling path.
+ */
+export declare function asRouteControl(err: unknown): PylonRouteControl | null;
+export interface SsrCookieOptions {
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+    expires?: Date | string;
+    /** Defaults to true (secure default). Pass false for a client-readable cookie. */
+    httpOnly?: boolean;
+    secure?: boolean;
+    /** Defaults to "lax". */
+    sameSite?: "strict" | "lax" | "none";
+}
+export interface ResponseState {
+    status: number;
+    headers: Record<string, string>;
+    cookies: string[];
+}
+/**
+ * The per-render `response` controller handed to every page + layout in
+ * props. Pylon already has a backend for data/mutations, so SSR's job is
+ * just the response envelope: status, redirects, 404, and the occasional
+ * Set-Cookie.
+ *
+ * IMPORTANT — call these during the SYNCHRONOUS shell render (the
+ * component body, before any `await` / Suspense boundary). The HTTP head
+ * is committed when the shell is ready; status/headers/cookies set from a
+ * suspended subtree that streams in later are lost, and a redirect()/
+ * notFound() thrown below a Suspense boundary is caught by React's error
+ * handling rather than turned into a 3xx/404 (same constraint as Next's
+ * streaming SSR). Per render, not shared across requests.
+ */
+export interface SsrResponse {
+    /** Set the HTTP status (100–599). Default 200. */
+    setStatus(code: number): void;
+    /** Set a response header (name must be a token; value CR/LF/NUL-free). */
+    setHeader(name: string, value: string): void;
+    /** Append a Set-Cookie. Defaults: HttpOnly + SameSite=Lax. */
+    setCookie(name: string, value: string, opts?: SsrCookieOptions): void;
+    /** Throw to send a 3xx (default 307) + Location, no body. Shell-render only. */
+    redirect(url: string, status?: number): never;
+    /**
+     * Throw to send a 404. Renders the nearest `not-found.tsx` (walking up
+     * from the page's directory, wrapped in the route's layout chain), or a
+     * minimal framework body if none is defined. Shell-render only — a throw
+     * below a Suspense boundary is swallowed by React.
+     */
+    notFound(): never;
+}
+export declare function makeResponseController(state: ResponseState, defaultRedirectStatus?: number): SsrResponse;
+/**
+ * Merge page-set headers + cookies into the response_start header map.
+ * Cookies are newline-joined under `set-cookie`; the host splits them
+ * into one `Set-Cookie` header each (newline is forbidden inside a
+ * cookie, so it can't be turned into header injection).
+ */
+export declare function finalizeHeaders(state: ResponseState, extra?: Record<string, string>): Record<string, string>;
+/**
+ * Phase 1 SSR handler. Resolves the component, renders it via
+ * react-dom/server.renderToReadableStream, pumps chunks back to the
+ * host as base64-encoded NDJSON.
+ *
+ * Errors fall back to a type:"error" frame so the host can return a
+ * 500 with the error body. Mid-stream errors (after the first chunk
+ * has flushed) are uncatchable here — React's `onError` would have
+ * to feed into a separate signal, deferred to Phase 1.5.
+ */
+/**
+ * Page SEO metadata. A page exports `export const metadata = {...}`
+ * (static) or `export async function generateMetadata(props)` (dynamic,
+ * e.g. param-derived titles). Kept flat — no deep nesting beyond og/twitter.
+ *
+ * React 19 hoists the resulting <title>/<meta>/<link> into <head>. A page
+ * `title` overrides a layout's static `<title>` (both render; the browser
+ * uses the last, which is the page's). React does NOT dedupe arbitrary
+ * `<meta>`, so set `description`/OG in EITHER the layout OR page metadata,
+ * not both, to avoid duplicate tags.
+ */
+/** A single OpenGraph image (for `openGraph.images` — multiple images). */
+export interface OgImage {
+    url: string;
+    secureUrl?: string;
+    type?: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+}
+export interface SsrMetadata {
+    title?: string;
+    description?: string;
+    keywords?: string | string[];
+    canonical?: string;
+    robots?: string;
+    /** `<meta name="author">` — one tag per author. */
+    authors?: string | string[];
+    /** `<meta name="theme-color">` — browser UI tint for the page. */
+    themeColor?: string;
+    openGraph?: {
+        title?: string;
+        description?: string;
+        image?: string;
+        /** `og:image:secure_url` — set automatically to the https image URL. */
+        imageSecureUrl?: string;
+        /** `og:image:type` (e.g. "image/png"). */
+        imageType?: string;
+        /** `og:image:width` / `og:image:height` in pixels. */
+        imageWidth?: number;
+        imageHeight?: number;
+        imageAlt?: string;
+        /** Additional images beyond the primary `image` (each emits its own
+         *  `og:image` + dimensions). Provide absolute URLs. */
+        images?: OgImage[];
+        url?: string;
+        type?: string;
+        /** `og:locale` (e.g. "en_US"). */
+        locale?: string;
+        /** `og:site_name` — the brand the page belongs to (e.g. "Pylon").
+         *  Discord and other unfurlers show this above the title. */
+        siteName?: string;
+        /** `article:*` tags for `og:type=article` pages. */
+        article?: {
+            author?: string | string[];
+            publishedTime?: string;
+            modifiedTime?: string;
+            section?: string;
+            tags?: string | string[];
+        };
+    };
+    twitter?: {
+        card?: string;
+        title?: string;
+        description?: string;
+        image?: string;
+        /** `twitter:site` / `twitter:creator` — @handles. */
+        site?: string;
+        creator?: string;
+        /** `twitter:image:alt` — alt text for the card image. */
+        imageAlt?: string;
+    };
+    /** `<link rel="icon">` / `<link rel="apple-touch-icon">`. Auto-wired
+     *  from the app/icon.* + app/apple-icon.* + app/favicon.ico file
+     *  conventions, or set explicitly. */
+    icons?: {
+        icon?: {
+            url: string;
+            type?: string;
+            sizes?: string;
+        };
+        apple?: {
+            url: string;
+            type?: string;
+            sizes?: string;
+        };
+    };
+    /** Alternate URLs. `languages` emits `<link rel="alternate" hreflang>`
+     *  per locale; `canonical` is an alias for the top-level `canonical`. */
+    alternates?: {
+        canonical?: string;
+        languages?: Record<string, string>;
+    };
+    /** Structured data, emitted as `<script type="application/ld+json">`.
+     *  One object or an array (each item gets its own script). Serialized with
+     *  `<` escaped so values can't break out of the script element. */
+    jsonLd?: Record<string, unknown> | Record<string, unknown>[];
+}
+/**
+ * Build a React fragment of <title>/<meta>/<link> from a page's metadata.
+ * React 19 auto-hoists these into <head> wherever they render, and the
+ * host's </head> splice preserves them. React escapes all text/attrs, so
+ * there's no manual XSS handling. Returns null when there's nothing to emit.
+ */
+export declare function renderMetadata(React: any, m: SsrMetadata | undefined): any;
+/** Import a project-relative module, trying each common extension. */
+export declare function importModule(cwd: string, relPath: string): Promise<any>;
+/** Pure origin resolution (exported for tests).
+ *
+ *  SECURITY: the request `Host` (and `X-Forwarded-Proto`) is attacker-
+ *  controlled. It's only trusted to build the absolute origin baked into
+ *  `og:image` / canonical URLs when it's in the allowlist — the configured
+ *  public/canonical host, an explicit `PYLON_TRUSTED_HOSTS` entry, or
+ *  loopback. An untrusted (or absent) Host falls back to the configured
+ *  public origin. Without this, `Host: evil.com` on a cacheable
+ *  (force-static / `revalidate`) render bakes `https://evil.com/_pylon/og…`
+ *  into the HTML, which is then teed into the shared ISR/CDN cache and
+ *  served to every subsequent visitor (cache poisoning). */
+export declare function resolveOrigin(opts: {
+    host?: string;
+    forwardedProto?: string;
+    publicUrl?: string;
+    canonicalHost?: string;
+    trustedHostsCsv?: string;
+}): string;
+/** SECURITY: validate a `response.redirect()` target to prevent OPEN REDIRECTS.
+ *  Mirrors the OAuth-layer `validate_trusted_redirect` (crates/auth). A relative
+ *  same-site path is always allowed; an absolute URL only when it's http(s) to a
+ *  trusted host — the app's public/canonical origin, a `PYLON_TRUSTED_HOSTS`
+ *  entry, or loopback. Everything else is rejected: protocol-relative
+ *  `//evil.com`, backslash tricks (`/\evil.com` — browsers normalize `\`→`/`),
+ *  other-origin absolutes, and `javascript:`/`data:` schemes. So the natural
+ *  `response.redirect(searchParams.get("next"))` can't be turned into an
+ *  off-site redirect by attacker-supplied input. Exported for tests. */
+export declare function isSafeRedirect(url: string, opts: {
+    publicUrl?: string;
+    canonicalHost?: string;
+    trustedHostsCsv?: string;
+}): boolean;
+/** Merge auto-discovered favicons (icon.* / apple-icon.* / favicon.ico)
+ *  into a page's metadata. Explicit `metadata.icons.*` wins. */
+export declare function applyAutoIcons(component: string, metadata: SsrMetadata | undefined): SsrMetadata | undefined;
+export declare function applyAutoSocialImages(component: string, headers: Record<string, string> | undefined, metadata: SsrMetadata | undefined): SsrMetadata | undefined;
+/**
+ * Build the hydration tail appended after React's stream EOFs: the
+ * `__PYLON_DATA__` JSON blob (props + ssrData) + the per-route entry
+ * `<script>` that hydrates it, + (dev) the live-reload snippet. Shared by the
+ * page render AND the now-hydrated boundary render (#279) so a boundary
+ * hydrates through the EXACT same path as a page.
+ *
+ * `kind` marks an error/not-found boundary so the client knows whether to
+ * synthesize a `reset()`. For an error boundary, `errorForClient` is the SAFE
+ * projection ({message, digest}) — the raw `Error` (and its stack) is NEVER
+ * serialized (the dev overlay owns dev stacks; preserves the #270 posture).
+ */
+export declare function buildHydrationTail(args: {
+    component: string;
+    layouts: string[];
+    props: any;
+    ssrData: Record<string, any>;
+    manifestRoute: {
+        file: string;
+        imports: string[];
+        css: string[];
+    } | null;
+    publicPrefix: string;
+    manifestErr: string | null;
+    kind?: "error" | "not-found";
+    errorForClient?: {
+        message: string;
+        digest?: string;
+    };
+}): string;
+/**
+ * A short, non-reversible correlation id for an error — surfaced to the
+ * client error boundary as `error.digest` (matching server logs) WITHOUT
+ * carrying any stack content. FNV-1a over message+stack, 8 hex chars.
+ */
+export declare function errorDigest(err: any): string;
+/**
+ * #278: does this route STREAM (vs buffer the whole document)? Streaming is
+ * opt-in: a `loading.tsx` (route-level Suspense) or `export const streaming =
+ * true` (inner-boundary). Pure for testing.
+ */
+export declare function computeWantsStream(hasLoading: boolean, mod: any): boolean;
+/**
+ * #277: how long an opt-in page stays cacheable, in seconds — or null if it
+ * never opted in. `export const revalidate = N` (N>0) → N; `dynamic:
+ * "force-static"` → a year (only a deploy invalidates); else null. Pure.
+ */
+export declare function computeRevalidateSecs(mod: any): number | null;
+/**
+ * #277 cache verdict — the security-critical predicate, extracted pure so the
+ * leak class (a personalized/streaming render marked cacheable) is a TEST, not
+ * a mental walkthrough. INVARIANT: result ⟹ !wantsStream (a streaming render
+ * commits its head before auth/cookies/status are final, so it can never be
+ * cached). Fail-closed: every condition must hold.
+ */
+export declare function computeCacheVerdict(args: {
+    revalidateSecs: number | null;
+    forceDynamic: boolean;
+    authTouched: boolean;
+    cookieCount: number;
+    strictPolicies: boolean;
+    wantsStream: boolean;
+    status: number;
+}): boolean;
+/**
+ * #278: diff the response head committed at `response_start` against the final
+ * state after EOF, to catch a late response.* mutation from a suspended subtree
+ * that the already-sent head couldn't carry. Returns the dropped pieces, or
+ * null if nothing was lost. Pure.
+ */
+export declare function diffCommittedResponse(snapshot: {
+    status: number;
+    cookies: string[];
+    headerKeys: string[];
+}, final: {
+    status: number;
+    cookies: string[];
+    headers: Record<string, string>;
+}): {
+    droppedCookies: string[];
+    statusChanged: boolean;
+    newHeaderKeys: string[];
+} | null;
+/** One URL entry in a sitemap (mirrors Next's `MetadataRoute.Sitemap[number]`). */
+export interface SitemapEntry {
+    url: string;
+    lastModified?: string | Date;
+    changeFrequency?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+    priority?: number;
+    /** hreflang alternates, e.g. `{ languages: { "en-US": "https://…/en" } }`. */
+    alternates?: {
+        languages?: Record<string, string>;
+    };
+}
+/** Return type of a default export in `app/sitemap.ts`. */
+export type Sitemap = SitemapEntry[];
+export interface RobotsRule {
+    userAgent?: string | string[];
+    allow?: string | string[];
+    disallow?: string | string[];
+    crawlDelay?: number;
+}
+/** Return type of a default export in `app/robots.ts`. */
+export interface Robots {
+    rules: RobotsRule | RobotsRule[];
+    sitemap?: string | string[];
+    host?: string;
+}
+/** Serialize sitemap entries to a sitemaps.org 0.9 XML document. */
+export declare function serializeSitemap(entries: Sitemap | undefined): string;
+/** Serialize a robots config to robots.txt text. */
+export declare function serializeRobots(robots: Robots | undefined): string;
+/**
+ * Import app/sitemap or app/robots, run its default export, serialize the
+ * result, and stream it back with the right content-type. Errors surface as a
+ * 500 with a short plain-text message (so a broken sitemap doesn't wedge the
+ * runner). 1-hour cache — sitemaps/robots change rarely; tune via a CDN.
+ */
+export declare function handleDataRoute(msg: RenderRouteMessage, kind: "sitemap" | "robots", send: Send): Promise<void>;
+export declare function handleRenderRoute(msg: RenderRouteMessage, send: Send): Promise<void>;
+export {};

package/dist/testing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Test-side helpers for `pylon test`.
+ *
+ * The CLI already starts each test FILE with a fresh in-memory database
+ * (`PYLON_IN_MEMORY=1`), so tests across files never cross-contaminate.
+ * This module covers the finer-grained case: isolating individual
+ * `test(...)` blocks within a single file.
+ *
+ * Two integration patterns are supported:
+ *
+ * 1. **Manual** — call `resetDb()` from a `beforeEach` hook.
+ * 2. **Automatic** — call `installTestIsolation()` at the top of the file
+ *    and every `test()` block runs with a reset store.
+ *
+ * Both require the test file to run under `pylon test` (not raw
+ * `bun test`), because resetDb talks to the server via HTTP.
+ */
+/**
+ * Reset the in-memory database to empty. Returns when the server confirms.
+ *
+ * Only works when the server is running in in-memory dev mode — production
+ * deployments refuse this call. Safe to no-op when the reset endpoint is
+ * unreachable so tests using this helper still work under raw `bun test`
+ * (they just won't reset between cases).
+ */
+export declare function resetDb(baseUrl?: string): Promise<void>;
+/**
+ * Bun-friendly `beforeEach(resetDb)` installer. Looks up Bun's global
+ * `beforeEach` via `globalThis`; no-ops under other runners.
+ */
+export declare function installTestIsolation(baseUrl?: string): void;