@rshono/core 1.0.0-rc.6 → 1.0.0-rc.8

package/dist/runtime/context.js

@@ -16,28 +16,67 @@ import { NotFoundSignal, RedirectSignal } from './control.js';
 const contextStorage = new AsyncLocalStorage();
 /** One {@link RequestContext} per Hono {@link Context}, so repeated `getRequestContext()` calls in a request share its lazy getters. */
 const wrappers = new WeakMap();
+/**
+ * Requests whose page render has begun — the point past which nothing can change the response head.
+ *
+ * A `WeakSet` keyed on the Hono {@link Context} rather than a field on {@link RequestContext},
+ * so marking a request costs nothing for the pages that never read their context: the wrapper is
+ * built lazily by {@link getRequestContext} and this must not be what forces it into existence.
+ */
+const rendering = new WeakSet();
+/**
+ * Marks the request as having entered its page render, which is what makes
+ * {@link RequestContext.setHeader} and `ctx.cookies.set()` start throwing.
+ *
+ * Framework internal — `renderComponent` calls this immediately before handing the page to React.
+ * Everything that legitimately writes to the response (middleware, a `'use server'` action, an
+ * endpoint route) has already run by then, so none of them are affected.
+ *
+ * @internal
+ */
+export function beginPageRender(c) {
+    rendering.add(c);
+}
+/**
+ * The shared explanation for a response mutation that arrived too late, thrown by
+ * {@link RequestContext.setHeader} and the `cookies` writers.
+ *
+ * Refusing beats the alternative, which was silent *and* inconsistent: a page setting a cookie got it
+ * on a full page load and lost it on a soft navigation, because the flight stream's response head is
+ * committed before the page component's first line runs. Nothing inside the render can fix that, so
+ * the message says where the write does belong instead.
+ */
+function tooLateToWrite(call) {
+    throw new Error(`[rshono] ${call} was called while rendering a page, which is too late to affect the response. ` +
+        'A page streams, so its response head is already committed by the time the component runs — the ' +
+        'write would land on a full page load and be silently dropped on a soft navigation. Do it from a ' +
+        "'use server' action instead; or, in middleware and { type: 'endpoint' } routes — which are handed " +
+        "Hono's `c` directly and run outside the request context — with `c.header(…)` / `setCookie(c, …)`.");
+}
+/** The shared explanation for a Hono `Context` member that a page has no way to use. See the stubs on {@link RequestContext}. */
+function notOnContext(call, instead) {
+    throw new Error(`[rshono] ctx.${call} does not exist. A page returns JSX and the framework builds the response from it, ` +
+        `so Hono's response builders have nothing to return to. ${instead}`);
+}
 /**
  * `process.env`, snapshotted on first read.
  *
- * It is not a plain object — every enumeration crosses into the host environment, which made
- * spreading it (~20µs) by far the most expensive thing {@link RequestContext.env} did, once per request that
- * touched it. Snapshotted lazily rather than at module load because `loadEnvFiles()` runs *after*
- * this module is imported, so an eager copy would miss everything from `.env`. The trade-off: a
- * `process.env` mutation after the first `ctx.env` read is not picked up.
+ * Enumerating it crosses into the host environment, which made the spread (~20µs) by far the most
+ * expensive thing {@link RequestContext.env} did, once per request that touched it. Lazily rather
+ * than at module load, because `loadEnvFiles()` runs *after* this module is imported and an eager
+ * copy would miss everything from `.env`. The trade-off: a `process.env` mutation after the first
+ * `ctx.env` read is not picked up.
  */
 let envSnapshot;
 function processEnv() {
     return (envSnapshot ??= typeof process !== 'undefined' && process.env ? { ...process.env } : {});
 }
 /**
- * True when this process is the SSG build prerendering `render: 'static'` routes,
- * rather than a server handling real requests. `build.ts` sets `RSHONO_PRERENDER`
- * before importing the app bundle and starting the prerender pass; the app bundle
- * inlines its own copy of this module, so a shared `process.env` (not a module-level
- * flag) is what reliably crosses that boundary. Read by {@link getRequestContext} to turn a
- * static route's request-context read into a clear build-time error instead of
- * silently baking synthetic build-time values (a `localhost` URL, no cookies, build
- * env) into the snapshot.
+ * True when this process is the SSG build prerendering `render: 'static'` routes rather than a server
+ * handling real requests. `build.ts` sets `RSHONO_PRERENDER` before importing the app bundle, which
+ * inlines its own copy of this module — so `process.env` is what crosses that boundary, not a
+ * module-level flag. {@link getRequestContext} reads it to fail loudly instead of baking synthetic
+ * build-time values (a `localhost` URL, no cookies, build env) into the prerendered page.
  */
 const prerendering = typeof process !== 'undefined' && !!process.env?.RSHONO_PRERENDER;
 /**
@@ -53,12 +92,10 @@ export function runWithContext(c, fn) {
     return contextStorage.run(c, fn);
 }
 /**
- * Reads the matched route params, returning an empty object when there is no
- * active route match (rather than throwing), so the fallback behaviour stays in
- * one place.
+ * The matched route params, or an empty object when there is no active match.
  *
- * Framework internal — the request renderer calls this to build a page's `params`
- * prop. Read them from that prop (or `ctx.raw.req.param()` outside a page) instead.
+ * Framework internal — the request renderer calls this to build a page's `params` prop, and
+ * {@link RequestContext.params} caches it. Read them from that prop, or from `ctx.params`.
  *
  * @internal
  */
@@ -80,18 +117,36 @@ function firstForwardedValue(header) {
 // Read through `typeof` so that degrades to the safe answer — don't trust — instead of a ReferenceError.
 const trustProxy = typeof __RSHONO_CONFIG__ !== 'undefined' && __RSHONO_CONFIG__.trustProxy;
 /**
- * Resolves the browser-facing {@link URL} for a request.
+ * Resolves the browser-facing {@link URL} for a request, from a Hono {@link Context}.
  *
- * `c.req.url` reflects the internal address the server was reached on, which is wrong behind a
- * proxy or load balancer. `X-Forwarded-Host` / `X-Forwarded-Proto` fix that up — **but only when
- * `trustProxy` is enabled in `rshono.config.ts`** (always the case under `rshono dev`). Those
- * headers are client-supplied: honouring them unconditionally lets anyone who can reach the server
- * dictate the origin of every absolute URL the app builds — canonical tags, emails, redirects — and
- * poison a shared cache with them. So the default is to ignore them entirely.
+ * `c.req.url` reflects the internal address the server was reached on, which is wrong behind a proxy.
+ * `X-Forwarded-Host` / `X-Forwarded-Proto` fix that up — **but only when `trustProxy` is enabled in
+ * `rshono.config.ts`** (always so under `rshono dev`). They are client-supplied, so honouring them
+ * unconditionally would let anyone who can reach the server dictate the origin of every absolute URL
+ * the app builds, and poison a shared cache with it.
  *
- * Framework internal — prefer {@link RequestContext.url}, which caches the result per request.
+ * This is the form for **middleware**, which is handed `c` and runs outside the request context. In
+ * a server component or a `'use server'` action prefer {@link RequestContext.url}, which is this same
+ * value cached per request.
  *
- * @internal
+ * Its main use is giving Hono's own middleware the origin the browser actually used, since they all
+ * read `c.req.url` on their own and so see the internal one:
+ *
+ * @example
+ * ```ts
+ * // src/server.ts — a CSRF check that still works behind a proxy that rewrites Host
+ * import { publicUrl } from '@rshono/core/server';
+ * import { csrf } from 'hono/csrf';
+ *
+ * server.use(csrf({ origin: (origin, c) => origin === publicUrl(c).origin }));
+ * ```
+ *
+ * A fresh instance per call, so mutating it disturbs nothing else.
+ *
+ * @param c - The Hono {@link Context} for the request.
+ * @returns The browser-facing URL — proxy-corrected under `trustProxy`, `c.req.url` otherwise.
+ *
+ * @see {@link https://www.rshono.com/docs/configuration#proxy-headers | Docs — proxy headers}
  */
 export function publicUrl(c) {
     const url = new URL(c.req.url);
@@ -134,38 +189,91 @@ export function publicUrl(c) {
  *   return <p>{ctx.url.pathname} — {session ?? 'anonymous'}</p>;
  * }
  * ```
+ *
+ * @see {@link https://www.rshono.com/docs/api#rshonocoreserver | Docs — `@rshono/core/server`}
+ * @see {@link https://hono.dev/docs/api/context | Hono — Context}, reachable in full via {@link RequestContext.hono}
  */
 export class RequestContext {
     #raw;
     #url;
     #env;
+    #params;
+    /**
+     * Framework internal — one instance is created per request and handed to you by
+     * {@link getRequestContext} or the `ctx` page prop. Application code never calls this.
+     *
+     * @internal
+     */
     constructor(c) {
         this.#raw = c;
     }
     /**
-     * The underlying Hono {@link Context}. Escape hatch for anything this wrapper does not expose — and
-     * deliberately most things. `req`, `method`, `params` and a `header()` setter used to sit on this class
-     * as one-line pass-throughs to `c.req`, `c.req.method`, `c.req.param()` and `c.header()`; they are
-     * reachable through here (`ctx.raw.req`, `ctx.raw.header(…)`) and adding no name of their own is the
-     * point. What stays below is what this wrapper actually *does*: a proxy-aware cached URL, an env that
-     * merges runtime bindings over process env, and cookies without a second import.
+     * The underlying Hono {@link Context} — the escape hatch for what this wrapper does not expose,
+     * such as `executionCtx.waitUntil()` on Workers.
+     *
+     * Its response builders (`redirect`, `notFound`, `json`, `body`, `status`, …) still do nothing from
+     * inside a page, for the reason the stubs on this class explain: reaching them through here
+     * bypasses the error, it does not make them work.
      *
-     * A getter over a private field rather than a plain property, so it is not an *own enumerable*
-     * one — which matters more than it looks. React's diagnostic for a value that cannot be sent to a
-     * client component (`describeObjectForErrorMessage`) walks `Object.keys` recursively with no depth
-     * limit and no cycle guard, and the Hono context graph reaches the socket and the whole server
-     * through `req.raw` and `env`. While this was a plain property, passing a `RequestContext` to a `'use client'`
-     * component blew the stack *inside that message builder* — so React's actual, accurate "you cannot
-     * pass this" error never got printed. Hidden from `Object.keys`, the walk stops here.
+     * @example
+     * ```ts
+     * getRequestContext().hono.executionCtx.waitUntil(logAsync()); // Workers
+     * ```
+     *
+     * @see {@link https://hono.dev/docs/api/context | Hono — Context}
      */
-    get raw() {
+    // A prototype getter rather than a plain property, so it is not *own enumerable*. React's
+    // diagnostic for a value that cannot be sent to a client component walks `Object.keys` recursively
+    // with no depth limit and no cycle guard, and the Hono context graph reaches the socket and the
+    // whole server through `req.raw` and `env` — as a plain property this blew the stack inside the
+    // message builder, so React's accurate "you cannot pass this" error never got printed. Every member
+    // here is a getter or method for the same reason; `cookies` is the one own enumerable property, and
+    // it is a shallow object of four functions.
+    get hono() {
         return this.#raw;
     }
     /**
-     * The browser-facing request URL, proxy-header aware (see {@link publicUrl}) —
-     * read `url.pathname`, `url.searchParams` and the rest off it. Parsed once and
-     * cached, so the same instance comes back on every read within a request; treat
-     * it as read-only for that reason.
+     * The parsed request — method, headers, path params, query and the body readers. Hono's
+     * {@link Context.req}, unwrapped, so `ctx.req.header('authorization')` rather than
+     * `ctx.hono.req.header(…)`.
+     *
+     * Reads only. Setting a *response* header is {@link RequestContext.setHeader}, deliberately in a
+     * different place — Hono's `c.header()` writing the response while `c.req.header()` reads the
+     * request is a well-worn source of confusion.
+     *
+     * @example
+     * ```ts
+     * const ctx = getRequestContext();
+     * ctx.req.method;                     // 'GET'
+     * ctx.req.header('authorization');    // string | undefined
+     * ctx.req.query('tab');               // string | undefined
+     * ```
+     *
+     * @see {@link https://hono.dev/docs/api/request | Hono — HonoRequest}
+     */
+    get req() {
+        return this.#raw.req;
+    }
+    /**
+     * Matched route params for this request, e.g. `{ id: '42' }` for `/profile/:id`. Empty when there
+     * is no active route match.
+     *
+     * A **page** is handed the same record as its `params` prop, typed key-by-key from its route path,
+     * and that is the better read where it is available. This is for everywhere else — a nested server
+     * component, or a `'use server'` action — which get no props from the framework.
+     */
+    get params() {
+        return (this.#params ??= readParams(this.#raw));
+    }
+    /**
+     * The browser-facing request URL — read `url.pathname`, `url.searchParams` and the
+     * rest off it. Parsed once and cached, so the same instance comes back on every
+     * read within a request; treat it as read-only for that reason.
+     *
+     * `X-Forwarded-Host` / `-Proto` are honoured only when `trustProxy` is enabled in
+     * `rshono.config.ts`, since any client can send them.
+     *
+     * @see {@link https://www.rshono.com/docs/configuration#proxy-headers | Docs — proxy headers}
      */
     get url() {
         return (this.#url ??= publicUrl(this.#raw));
@@ -173,6 +281,15 @@ export class RequestContext {
     /**
      * Typed variables set by middleware via `c.set('user', …)`, read here as
      * `ctx.var.user`. Type them by parameterising this class's {@link Env}.
+     *
+     * @example
+     * ```ts
+     * type AppEnv = { Variables: { user: { id: string } } };
+     * const { user } = getRequestContext<AppEnv>().var; // typed, set by your middleware
+     * ```
+     *
+     * @see {@link https://hono.dev/docs/api/context#var | Hono — c.var}
+     * @see {@link https://www.rshono.com/docs/hono#typing-the-context | Docs — typing the context}
      */
     get var() {
         return this.#raw.var;
@@ -182,6 +299,9 @@ export class RequestContext {
      * (bindings win on conflict). Computed once and cached.
      *
      * @example `const key = getRequestContext().env.STRIPE_SECRET_KEY;`
+     *
+     * @see {@link https://hono.dev/docs/api/context#env | Hono — c.env}
+     * @see {@link https://www.rshono.com/docs/configuration#environment-and-secrets | Docs — environment and secrets}
      */
     get env() {
         if (this.#env)
@@ -200,31 +320,125 @@ export class RequestContext {
      * ctx.cookies.set('session', id, { httpOnly: true, sameSite: 'Lax', path: '/' });
      * ctx.cookies.delete('session', { path: '/' });
      * ```
+     *
+     * @see {@link https://hono.dev/docs/helpers/cookie | Hono — cookie helper}, which this wraps
      */
     cookies = {
-        /** Reads a single cookie by name, or `undefined` if absent. */
+        /** Reads a single cookie by name, or `undefined` if absent. Safe anywhere, a page included. */
         get: (name) => getCookie(this.#raw, name),
-        /** Reads every cookie as a `{ name: value }` record. */
+        /** Reads every cookie as a `{ name: value }` record. Safe anywhere, a page included. */
         all: () => getCookie(this.#raw),
-        /** Sets a cookie on the response. See Hono's {@link CookieOptions} for `path`, `httpOnly`, `maxAge`, etc. */
-        set: (name, value, options) => setCookie(this.#raw, name, value, options),
-        /** Clears a cookie. Pass the same `path`/`domain` it was set with so the browser matches it. */
+        /**
+         * Sets a cookie on the response. See Hono's {@link CookieOptions} for `path`, `httpOnly`,
+         * `maxAge`, etc.
+         *
+         * **Throws inside a page render** — see {@link RequestContext.setHeader}, of which a `Set-Cookie`
+         * is a special case. Set cookies from a `'use server'` action, or with Hono's `setCookie(c, …)`
+         * in middleware and endpoint routes.
+         *
+         * @throws If called while a page is rendering, where it could not reach the browser reliably.
+         *
+         * @see {@link https://hono.dev/docs/helpers/cookie#options | Hono — cookie options}
+         */
+        set: (name, value, options) => {
+            this.#assertWritable('ctx.cookies.set()');
+            setCookie(this.#raw, name, value, options);
+        },
+        /**
+         * Clears a cookie. Pass the same `path`/`domain` it was set with so the browser matches it.
+         * Throws inside a page render, exactly as `set` does.
+         *
+         * @throws If called while a page is rendering.
+         */
         delete: (name, options) => {
+            this.#assertWritable('ctx.cookies.delete()');
             deleteCookie(this.#raw, name, options);
         },
     };
+    /** Guards every write that has to reach the response head. See {@link tooLateToWrite}. */
+    #assertWritable(call) {
+        if (rendering.has(this.#raw))
+            tooLateToWrite(call);
+    }
+    /**
+     * Sets a header on the response — from a `'use server'` action, which is the one place a request
+     * context exists *and* the response is still open.
+     *
+     * From inside a page it throws: a page streams, so by then the response head is committed. Hono's
+     * `c.header()` fails there silently and inconsistently — landing on a full page load, vanishing on
+     * a soft navigation — so this refuses rather than doing it half the time.
+     *
+     * Middleware and `{ type: 'endpoint' }` routes run outside the request context but are handed
+     * Hono's `c` directly, so they use `c.header(…)`. That is also where a header belonging to the
+     * *page* rather than to one action goes — `Cache-Control`, `X-Robots-Tag` — since middleware runs
+     * before the render.
+     *
+     * @param name - Header name, case-insensitive.
+     * @param value - Header value.
+     * @param options - `{ append: true }` to add another value rather than replace.
+     * @throws If called while a page is rendering, where it could not reach the browser reliably.
+     *
+     * @example
+     * ```ts
+     * 'use server';
+     * export async function logout() {
+     *   const ctx = getRequestContext();
+     *   ctx.cookies.delete('session', { path: '/' });
+     *   ctx.setHeader('clear-site-data', '"cache", "storage"');
+     *   redirect('/');
+     * }
+     * ```
+     */
+    setHeader(name, value, options) {
+        this.#assertWritable('ctx.setHeader()');
+        this.#raw.header(name, value, options);
+    }
+    // Hono's response builders, restated as errors naming what to use instead. A page returns JSX and
+    // `renderComponent` builds the response from it, so every one of these is a silent no-op through
+    // `ctx.hono`. `@deprecated` is the compile-time signal — an editor strikes them through in
+    // autocomplete — and the thrown message is the one that explains. Each takes `...args: unknown[]`
+    // it never reads so that `ctx.redirect('/dashboard')` reaches that message rather than stopping at
+    // "Expected 0 arguments, but got 1".
+    /** @deprecated Not available on a page's context — use `redirect()` from `@rshono/core/server`. */
+    redirect(...args) {
+        return notOnContext('redirect(location, status?)', "Use `redirect()` from '@rshono/core/server', which throws a signal the framework turns into a real redirect.");
+    }
+    /** @deprecated Not available on a page's context — use `notFound()` from `@rshono/core/server`. */
+    notFound(...args) {
+        return notOnContext('notFound()', "Use `notFound()` from '@rshono/core/server', which aborts the render and shows the app's not-found page.");
+    }
+    /** @deprecated A page renders JSX. For a JSON response, use an `{ type: 'endpoint' }` route. */
+    json(...args) {
+        return notOnContext('json(object)', "For a JSON response use an { type: 'endpoint' } route; to read the request body use `ctx.req.json()`.");
+    }
+    /** @deprecated A page renders JSX. For a text response, use an `{ type: 'endpoint' }` route. */
+    text(...args) {
+        return notOnContext('text(string)', "For a text response use an { type: 'endpoint' } route; to read the request body use `ctx.req.text()`.");
+    }
+    /** @deprecated A page renders JSX, which the framework turns into HTML for you. */
+    html(...args) {
+        return notOnContext('html(string)', "A page's JSX is already its HTML; for a hand-built HTML response use an { type: 'endpoint' } route.");
+    }
+    /** @deprecated Not available on a page's context. To read the request body, use `ctx.req`. */
+    body(...args) {
+        return notOnContext('body(data, …)', "To read the *request* body use `ctx.req.json()` / `ctx.req.text()` / `ctx.req.formData()`; to build a response, use an { type: 'endpoint' } route.");
+    }
+    /** @deprecated A page's status is set by the framework — use `notFound()`, or an endpoint route. */
+    status(...args) {
+        return notOnContext('status(code)', "A page's status is the framework's: 200, 404 via `notFound()`, 500 when it throws. For any other code use an { type: 'endpoint' } route.");
+    }
+    /** @deprecated Renamed — use `ctx.setHeader(name, value)`, which is valid from a `'use server'` action. */
+    header(...args) {
+        return notOnContext('header(name, value)', "Use `ctx.setHeader(name, value)` from a 'use server' action, or `c.header(…)` in middleware — a page renders too late to set one.");
+    }
 }
 /**
- * Returns the {@link RequestContext} for the current request.
- *
- * This is the primary entry point for reading request data from a server
- * component or server action — the URL, cookies, params, env, and middleware
- * variables. The returned wrapper is memoised per request, so repeated calls in
- * the same request are cheap and return the same instance.
+ * Returns the {@link RequestContext} for the current request — the URL, cookies, params, env and
+ * middleware variables, read from a server component or a server action. Memoised per request, so
+ * repeated calls return the same instance.
  *
- * A **page** component is handed the very same object as its `ctx` prop, so this
- * import is for everywhere else: a nested server component, or a `'use server'`
- * action module — neither of which receives props from the framework.
+ * A **page** component is handed that same object as its `ctx` prop, so this import is for everywhere
+ * else: a nested server component, or a `'use server'` action module.
  *
  * @typeParam E - The app's Hono {@link Env}, to type {@link RequestContext.var} and {@link RequestContext.env}.
  * @throws If called at module load, where there is no ambient context to resolve.
@@ -241,6 +455,8 @@ export class RequestContext {
  *   redirect('/dashboard');
  * }
  * ```
+ *
+ * @see {@link https://www.rshono.com/docs/api#rshonocoreserver | Docs — `@rshono/core/server`}
  */
 export function getRequestContext() {
     if (prerendering) {
@@ -322,6 +538,8 @@ let errorHandler;
  *   Sentry.captureException(error, { tags: { source }, extra: { url: request.url } });
  * });
  * ```
+ *
+ * @see {@link https://www.rshono.com/docs/hono#error-reporting | Docs — error reporting}
  */
 export function onServerError(handler) {
     errorHandler = handler;

package/dist/runtime/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"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","sourcesContent":["/// <reference path=\"../types/rshono-config.d.ts\" />\n/**\n * The request context: {@link getRequestContext} and the {@link RequestContext} wrapper it returns,\n * the {@link redirect} / {@link notFound} control-flow helpers, and the\n * {@link onServerError} reporting funnel — plus the `@internal` plumbing that binds\n * a request to the async context in the first place.\n *\n * The public half of this module is re-exported by `runtime/server.ts`, which is\n * what the `@rshono/core/server` subpath resolves to; import *that* from an app. Nothing\n * here is safe in a `'use client'` module — those run in the browser, with no bound\n * request context.\n */\n\nimport type { Context, Env } from 'hono';\nimport { deleteCookie, getCookie, setCookie } from 'hono/cookie';\nimport type { CookieOptions } from 'hono/utils/cookie';\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { NotFoundSignal, RedirectSignal } from './control.js';\n\n/**\n * HTTP status codes accepted by {@link redirect}.\n *\n * - `301` Moved Permanently, `308` Permanent Redirect — cacheable, permanent.\n * - `302` Found, `307` Temporary Redirect — temporary.\n * - `303` See Other — the default; forces a `GET` on the target, which is what\n *   you almost always want after a form action (post/redirect/get).\n */\nexport type RedirectStatus = 301 | 302 | 303 | 307 | 308;\n\nconst contextStorage = new AsyncLocalStorage<Context>();\n\n/** One {@link RequestContext} per Hono {@link Context}, so repeated `getRequestContext()` calls in a request share its lazy getters. */\nconst wrappers = new WeakMap<Context, RequestContext>();\n\n/**\n * `process.env`, snapshotted on first read.\n *\n * It is not a plain object — every enumeration crosses into the host environment, which made\n * spreading it (~20µs) by far the most expensive thing {@link RequestContext.env} did, once per request that\n * touched it. Snapshotted lazily rather than at module load because `loadEnvFiles()` runs *after*\n * this module is imported, so an eager copy would miss everything from `.env`. The trade-off: a\n * `process.env` mutation after the first `ctx.env` read is not picked up.\n */\nlet envSnapshot: Record<string, string | undefined> | undefined;\n\nfunction processEnv(): Record<string, string | undefined> {\n  return (envSnapshot ??= typeof process !== 'undefined' && process.env ? { ...process.env } : {});\n}\n\n/**\n * True when this process is the SSG build prerendering `render: 'static'` routes,\n * rather than a server handling real requests. `build.ts` sets `RSHONO_PRERENDER`\n * before importing the app bundle and starting the prerender pass; the app bundle\n * inlines its own copy of this module, so a shared `process.env` (not a module-level\n * flag) is what reliably crosses that boundary. Read by {@link getRequestContext} to turn a\n * static route's request-context read into a clear build-time error instead of\n * silently baking synthetic build-time values (a `localhost` URL, no cookies, build\n * env) into the snapshot.\n */\nconst prerendering = typeof process !== 'undefined' && !!process.env?.RSHONO_PRERENDER;\n\n/**\n * Runs `fn` with the given Hono {@link Context} bound as the ambient request\n * context, so that {@link getRequestContext} resolves to it anywhere in the call tree.\n *\n * Framework internal — the request handler wraps every render and action in\n * this. Application code should reach for {@link getRequestContext} instead.\n *\n * @internal\n */\nexport function runWithContext<T>(c: Context, fn: () => T): T {\n  return contextStorage.run(c, fn);\n}\n\n/**\n * Reads the matched route params, returning an empty object when there is no\n * active route match (rather than throwing), so the fallback behaviour stays in\n * one place.\n *\n * Framework internal — the request renderer calls this to build a page's `params`\n * prop. Read them from that prop (or `ctx.raw.req.param()` outside a page) instead.\n *\n * @internal\n */\nexport function readParams(c: Context): Record<string, string> {\n  try {\n    return c.req.param();\n  } catch {\n    return {};\n  }\n}\n\n/** A proxy chain appends to these headers, so the client-facing value is the first entry. */\nfunction firstForwardedValue(header: string | undefined): string | undefined {\n  const first = header?.split(',')[0]?.trim();\n  return first || undefined;\n}\n\n// DefinePlugin inlines the config into the server bundle, but this module is the public\n// `@rshono/core/server` entry and could be loaded by tooling that doesn't (a unit test, a one-off script).\n// Read through `typeof` so that degrades to the safe answer — don't trust — instead of a ReferenceError.\nconst trustProxy = typeof __RSHONO_CONFIG__ !== 'undefined' && __RSHONO_CONFIG__.trustProxy;\n\n/**\n * Resolves the browser-facing {@link URL} for a request.\n *\n * `c.req.url` reflects the internal address the server was reached on, which is wrong behind a\n * proxy or load balancer. `X-Forwarded-Host` / `X-Forwarded-Proto` fix that up — **but only when\n * `trustProxy` is enabled in `rshono.config.ts`** (always the case under `rshono dev`). Those\n * headers are client-supplied: honouring them unconditionally lets anyone who can reach the server\n * dictate the origin of every absolute URL the app builds — canonical tags, emails, redirects — and\n * poison a shared cache with them. So the default is to ignore them entirely.\n *\n * Framework internal — prefer {@link RequestContext.url}, which caches the result per request.\n *\n * @internal\n */\nexport function publicUrl(c: Context): URL {\n  const url = new URL(c.req.url);\n  if (!trustProxy) return url;\n\n  const forwardedHost = firstForwardedValue(c.req.header('x-forwarded-host'));\n  // Parsed rather than assigned to `url.host`, because that setter *keeps the existing port* when\n  // the new value has none — leaving the internal port on the public URL (`example.com:3000`).\n  const forwarded = forwardedHost ? URL.parse(`http://${forwardedHost}`) : null;\n  if (forwarded) {\n    url.hostname = forwarded.hostname;\n    url.port = forwarded.port; // '' when the forwarded host carries no port, which clears it\n  }\n\n  // Restricted to the two schemes a browser can actually have requested; anything else (a proxy\n  // sending junk, or a client trying its luck) leaves the scheme alone.\n  const forwardedProto = firstForwardedValue(c.req.header('x-forwarded-proto'));\n  if (forwardedProto === 'http' || forwardedProto === 'https') url.protocol = forwardedProto;\n\n  return url;\n}\n\n/**\n * The environment available to a request: Cloudflare/Workers `Bindings` merged\n * with process env vars. Values not declared in `Bindings` are typed as\n * `string | undefined`. See {@link RequestContext.env}.\n */\nexport type EnvVars<E extends Env> = E['Bindings'] & Record<string, string | undefined>;\n\n/**\n * Ergonomic, read-mostly wrapper around Hono's {@link Context} for use inside\n * server components and server actions.\n *\n * Obtain one with {@link getRequestContext}, or — in a page component — take it straight\n * off the `ctx` prop, which is this same object. Never construct it yourself. One\n * instance is reused for the lifetime of a request, so its lazy getters\n * ({@link RequestContext.url}, {@link RequestContext.env}) are computed at most once.\n *\n * @typeParam E - The Hono {@link Env} describing this app's `Bindings` and\n *   `Variables`, so {@link RequestContext.var} and {@link RequestContext.env} stay typed.\n *\n * @example\n * ```tsx\n * import { getRequestContext } from '@rshono/core/server';\n *\n * export default async function Whoami() {\n *   const ctx = getRequestContext();\n *   const session = ctx.cookies.get('session');\n *   return <p>{ctx.url.pathname} — {session ?? 'anonymous'}</p>;\n * }\n * ```\n */\nexport class RequestContext<E extends Env = Env> {\n  #raw: Context<E>;\n  #url?: URL;\n  #env?: EnvVars<E>;\n\n  constructor(c: Context<E>) {\n    this.#raw = c;\n  }\n\n  /**\n   * The underlying Hono {@link Context}. Escape hatch for anything this wrapper does not expose — and\n   * deliberately most things. `req`, `method`, `params` and a `header()` setter used to sit on this class\n   * as one-line pass-throughs to `c.req`, `c.req.method`, `c.req.param()` and `c.header()`; they are\n   * reachable through here (`ctx.raw.req`, `ctx.raw.header(…)`) and adding no name of their own is the\n   * point. What stays below is what this wrapper actually *does*: a proxy-aware cached URL, an env that\n   * merges runtime bindings over process env, and cookies without a second import.\n   *\n   * A getter over a private field rather than a plain property, so it is not an *own enumerable*\n   * one — which matters more than it looks. React's diagnostic for a value that cannot be sent to a\n   * client component (`describeObjectForErrorMessage`) walks `Object.keys` recursively with no depth\n   * limit and no cycle guard, and the Hono context graph reaches the socket and the whole server\n   * through `req.raw` and `env`. While this was a plain property, passing a `RequestContext` to a `'use client'`\n   * component blew the stack *inside that message builder* — so React's actual, accurate \"you cannot\n   * pass this\" error never got printed. Hidden from `Object.keys`, the walk stops here.\n   */\n  get raw(): Context<E> {\n    return this.#raw;\n  }\n\n  /**\n   * The browser-facing request URL, proxy-header aware (see {@link publicUrl}) —\n   * read `url.pathname`, `url.searchParams` and the rest off it. Parsed once and\n   * cached, so the same instance comes back on every read within a request; treat\n   * it as read-only for that reason.\n   */\n  get url(): URL {\n    return (this.#url ??= publicUrl(this.#raw as Context));\n  }\n\n  /**\n   * Typed variables set by middleware via `c.set('user', …)`, read here as\n   * `ctx.var.user`. Type them by parameterising this class's {@link Env}.\n   */\n  get var(): Readonly<E['Variables']> {\n    return this.#raw.var;\n  }\n\n  /**\n   * Environment for the request: process env vars merged with runtime bindings\n   * (bindings win on conflict). Computed once and cached.\n   *\n   * @example `const key = getRequestContext().env.STRIPE_SECRET_KEY;`\n   */\n  get env(): EnvVars<E> {\n    if (this.#env) return this.#env;\n    const bindings = this.#raw.env as Record<string, unknown> | undefined;\n    // The snapshot is shared, so hand it back as-is when there are no bindings to merge over it.\n    return (this.#env = (bindings ? { ...processEnv(), ...bindings } : processEnv()) as EnvVars<E>);\n  }\n\n  /**\n   * Read and write request/response cookies.\n   *\n   * @example\n   * ```ts\n   * const ctx = getRequestContext();\n   * ctx.cookies.get('session');                       // string | undefined\n   * ctx.cookies.set('session', id, { httpOnly: true, sameSite: 'Lax', path: '/' });\n   * ctx.cookies.delete('session', { path: '/' });\n   * ```\n   */\n  cookies = {\n    /** Reads a single cookie by name, or `undefined` if absent. */\n    get: (name: string): string | undefined => getCookie(this.#raw, name),\n    /** Reads every cookie as a `{ name: value }` record. */\n    all: (): Record<string, string> => getCookie(this.#raw),\n    /** Sets a cookie on the response. See Hono's {@link CookieOptions} for `path`, `httpOnly`, `maxAge`, etc. */\n    set: (name: string, value: string, options?: CookieOptions): void => setCookie(this.#raw, name, value, options),\n    /** Clears a cookie. Pass the same `path`/`domain` it was set with so the browser matches it. */\n    delete: (name: string, options?: CookieOptions): void => {\n      deleteCookie(this.#raw, name, options);\n    },\n  };\n}\n\n/**\n * Returns the {@link RequestContext} for the current request.\n *\n * This is the primary entry point for reading request data from a server\n * component or server action — the URL, cookies, params, env, and middleware\n * variables. The returned wrapper is memoised per request, so repeated calls in\n * the same request are cheap and return the same instance.\n *\n * A **page** component is handed the very same object as its `ctx` prop, so this\n * import is for everywhere else: a nested server component, or a `'use server'`\n * action module — neither of which receives props from the framework.\n *\n * @typeParam E - The app's Hono {@link Env}, to type {@link RequestContext.var} and {@link RequestContext.env}.\n * @throws If called at module load, where there is no ambient context to resolve.\n * @throws If called while prerendering a `render: 'static'` route, which has no\n *   per-request context at build time — mark the route `render: 'dynamic'` instead.\n *\n * @example\n * ```ts\n * 'use server';\n * import { getRequestContext, redirect } from '@rshono/core/server';\n *\n * export async function login(form: FormData) {\n *   getRequestContext().cookies.set('session', String(form.get('email')), { httpOnly: true });\n *   redirect('/dashboard');\n * }\n * ```\n */\nexport function getRequestContext<E extends Env = Env>(): RequestContext<E> {\n  if (prerendering) {\n    throw new Error(\n      \"[rshono] getRequestContext() was called while prerendering a `render: 'static'` route. A static page \" +\n        'is rendered once at build time, so it has no per-request context to read (URL, cookies, ' +\n        \"headers, env). Change this route to `render: 'dynamic'` so it renders per request, or remove \" +\n        'the getRequestContext() call.',\n    );\n  }\n  const c = contextStorage.getStore();\n  if (!c) {\n    throw new Error(\n      '[rshono] getRequestContext() was called outside a request. It only works inside a server component or a server action, not at module load.',\n    );\n  }\n  let ctx = wrappers.get(c);\n  if (!ctx) {\n    ctx = new RequestContext(c);\n    wrappers.set(c, ctx);\n  }\n  return ctx as unknown as RequestContext<E>;\n}\n\n/**\n * Redirects the request to `location` by throwing a control signal that the\n * framework catches and turns into an HTTP redirect response.\n *\n * Because it throws, it never returns — TypeScript narrows away any code after\n * the call, and you do not need to `return` it. Do not wrap it in a `try/catch`\n * that swallows the signal.\n *\n * @param location - Absolute path or URL to redirect to, e.g. `/dashboard`.\n * @param status - Redirect {@link RedirectStatus}; defaults to `303` (See Other),\n *   the correct choice after a form action so the browser follows up with a `GET`.\n *\n * @example\n * ```ts\n * const session = getRequestContext().cookies.get('session');\n * if (!session) redirect('/login');\n * // session is defined below this line\n * ```\n */\nexport function redirect(location: string, status: RedirectStatus = 303): never {\n  throw new RedirectSignal(location, status);\n}\n\n/**\n * Aborts the current render with a 404, rendering the app's not-found page.\n *\n * Like {@link redirect}, this throws a control signal and never returns, so\n * TypeScript narrows away everything after the call. Do not catch-and-swallow it.\n *\n * @example\n * ```tsx\n * export default async function Page({ params }: PageProps<'/users/:id'>) {\n *   const user = await db.user.find(params.id);\n *   if (!user) notFound();\n *   return <Profile user={user} />; // user is non-null here\n * }\n * ```\n */\nexport function notFound(): never {\n  throw new NotFoundSignal();\n}\n\n/**\n * Which stage of a request produced an error handed to an {@link ServerErrorHandler}.\n *\n * - `action` — a `'use server'` function threw. React sends the client an opaque marker with no\n *   message in production, so this is the only place the real error is visible.\n * - `render` — a server component threw while the flight payload was being produced.\n * - `ssr` — SSR failed before the HTML shell could be sent, so the `error` page was unreachable too.\n * - `request` — anything else that reached the top-level handler, including a thrown endpoint route.\n */\nexport type ServerErrorSource = 'action' | 'render' | 'ssr' | 'request';\n\n/** What an {@link ServerErrorHandler} is told about an error, beyond the error itself. */\nexport interface ServerErrorContext {\n  /** The stage that produced it — see {@link ServerErrorSource}. */\n  source: ServerErrorSource;\n  /** The request being served, for the URL, method and headers. */\n  request: Request;\n}\n\n/** Handler registered with {@link onServerError}. Called for the side effect; its return value is ignored. */\nexport type ServerErrorHandler = (error: unknown, context: ServerErrorContext) => void;\n\nlet errorHandler: ServerErrorHandler | undefined;\n\n/**\n * Registers a handler for every error the framework catches, so they can reach an error tracker\n * (Sentry, Datadog, a log pipeline) instead of only `stderr`.\n *\n * Call it **once, at the top level of `src/server.ts`** — that module is imported as the server\n * starts, before any request is served. Registering again replaces the previous handler.\n *\n * Errors are still written to `stderr` either way, so a handler adds a destination rather than\n * replacing one. A handler that throws is caught and logged: reporting must never be able to fail\n * a request.\n *\n * @example\n * ```ts\n * // src/server.ts\n * import * as Sentry from '@sentry/node';\n * import { onServerError } from '@rshono/core/server';\n *\n * onServerError((error, { source, request }) => {\n *   Sentry.captureException(error, { tags: { source }, extra: { url: request.url } });\n * });\n * ```\n */\nexport function onServerError(handler: ServerErrorHandler): void {\n  errorHandler = handler;\n}\n\n/**\n * Logs an error and forwards it to the registered {@link ServerErrorHandler}.\n *\n * Framework internal — the single funnel every caught server-side error goes through, so that\n * adding a reporting destination is one registration rather than a hook per call site.\n *\n * @internal\n */\nexport function reportServerError(error: unknown, info: ServerErrorContext & { message: string }): void {\n  console.error(info.message, error);\n  if (!errorHandler) return;\n  try {\n    errorHandler(error, { source: info.source, request: info.request });\n  } catch (handlerError) {\n    console.error('[rshono] the onServerError handler threw:', handlerError);\n  }\n}\n"]}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"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","sourcesContent":["/// <reference path=\"../types/rshono-config.d.ts\" />\n/**\n * The request context: {@link getRequestContext} and the {@link RequestContext} wrapper it returns,\n * the {@link redirect} / {@link notFound} control-flow helpers, and the\n * {@link onServerError} reporting funnel — plus the `@internal` plumbing that binds\n * a request to the async context in the first place.\n *\n * The public half of this module is re-exported by `runtime/server.ts`, which is\n * what the `@rshono/core/server` subpath resolves to; import *that* from an app. Nothing\n * here is safe in a `'use client'` module — those run in the browser, with no bound\n * request context.\n */\n\nimport type { Context, Env } from 'hono';\nimport { deleteCookie, getCookie, setCookie } from 'hono/cookie';\nimport type { CookieOptions } from 'hono/utils/cookie';\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { NotFoundSignal, RedirectSignal } from './control.js';\n\n/**\n * HTTP status codes accepted by {@link redirect}.\n *\n * - `301` Moved Permanently, `308` Permanent Redirect — cacheable, permanent.\n * - `302` Found, `307` Temporary Redirect — temporary.\n * - `303` See Other — the default; forces a `GET` on the target, which is what\n *   you almost always want after a form action (post/redirect/get).\n *\n * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status#redirection_messages | MDN — redirection status codes}\n */\nexport type RedirectStatus = 301 | 302 | 303 | 307 | 308;\n\nconst contextStorage = new AsyncLocalStorage<Context>();\n\n/** One {@link RequestContext} per Hono {@link Context}, so repeated `getRequestContext()` calls in a request share its lazy getters. */\nconst wrappers = new WeakMap<Context, RequestContext>();\n\n/**\n * Requests whose page render has begun — the point past which nothing can change the response head.\n *\n * A `WeakSet` keyed on the Hono {@link Context} rather than a field on {@link RequestContext},\n * so marking a request costs nothing for the pages that never read their context: the wrapper is\n * built lazily by {@link getRequestContext} and this must not be what forces it into existence.\n */\nconst rendering = new WeakSet<Context>();\n\n/**\n * Marks the request as having entered its page render, which is what makes\n * {@link RequestContext.setHeader} and `ctx.cookies.set()` start throwing.\n *\n * Framework internal — `renderComponent` calls this immediately before handing the page to React.\n * Everything that legitimately writes to the response (middleware, a `'use server'` action, an\n * endpoint route) has already run by then, so none of them are affected.\n *\n * @internal\n */\nexport function beginPageRender(c: Context): void {\n  rendering.add(c);\n}\n\n/**\n * The shared explanation for a response mutation that arrived too late, thrown by\n * {@link RequestContext.setHeader} and the `cookies` writers.\n *\n * Refusing beats the alternative, which was silent *and* inconsistent: a page setting a cookie got it\n * on a full page load and lost it on a soft navigation, because the flight stream's response head is\n * committed before the page component's first line runs. Nothing inside the render can fix that, so\n * the message says where the write does belong instead.\n */\nfunction tooLateToWrite(call: string): never {\n  throw new Error(\n    `[rshono] ${call} was called while rendering a page, which is too late to affect the response. ` +\n      'A page streams, so its response head is already committed by the time the component runs — the ' +\n      'write would land on a full page load and be silently dropped on a soft navigation. Do it from a ' +\n      \"'use server' action instead; or, in middleware and { type: 'endpoint' } routes — which are handed \" +\n      \"Hono's `c` directly and run outside the request context — with `c.header(…)` / `setCookie(c, …)`.\",\n  );\n}\n\n/** The shared explanation for a Hono `Context` member that a page has no way to use. See the stubs on {@link RequestContext}. */\nfunction notOnContext(call: string, instead: string): never {\n  throw new Error(\n    `[rshono] ctx.${call} does not exist. A page returns JSX and the framework builds the response from it, ` +\n      `so Hono's response builders have nothing to return to. ${instead}`,\n  );\n}\n\n/**\n * `process.env`, snapshotted on first read.\n *\n * Enumerating it crosses into the host environment, which made the spread (~20µs) by far the most\n * expensive thing {@link RequestContext.env} did, once per request that touched it. Lazily rather\n * than at module load, because `loadEnvFiles()` runs *after* this module is imported and an eager\n * copy would miss everything from `.env`. The trade-off: a `process.env` mutation after the first\n * `ctx.env` read is not picked up.\n */\nlet envSnapshot: Record<string, string | undefined> | undefined;\n\nfunction processEnv(): Record<string, string | undefined> {\n  return (envSnapshot ??= typeof process !== 'undefined' && process.env ? { ...process.env } : {});\n}\n\n/**\n * True when this process is the SSG build prerendering `render: 'static'` routes rather than a server\n * handling real requests. `build.ts` sets `RSHONO_PRERENDER` before importing the app bundle, which\n * inlines its own copy of this module — so `process.env` is what crosses that boundary, not a\n * module-level flag. {@link getRequestContext} reads it to fail loudly instead of baking synthetic\n * build-time values (a `localhost` URL, no cookies, build env) into the prerendered page.\n */\nconst prerendering = typeof process !== 'undefined' && !!process.env?.RSHONO_PRERENDER;\n\n/**\n * Runs `fn` with the given Hono {@link Context} bound as the ambient request\n * context, so that {@link getRequestContext} resolves to it anywhere in the call tree.\n *\n * Framework internal — the request handler wraps every render and action in\n * this. Application code should reach for {@link getRequestContext} instead.\n *\n * @internal\n */\nexport function runWithContext<T>(c: Context, fn: () => T): T {\n  return contextStorage.run(c, fn);\n}\n\n/**\n * The matched route params, or an empty object when there is no active match.\n *\n * Framework internal — the request renderer calls this to build a page's `params` prop, and\n * {@link RequestContext.params} caches it. Read them from that prop, or from `ctx.params`.\n *\n * @internal\n */\nexport function readParams(c: Context): Record<string, string> {\n  try {\n    return c.req.param();\n  } catch {\n    return {};\n  }\n}\n\n/** A proxy chain appends to these headers, so the client-facing value is the first entry. */\nfunction firstForwardedValue(header: string | undefined): string | undefined {\n  const first = header?.split(',')[0]?.trim();\n  return first || undefined;\n}\n\n// DefinePlugin inlines the config into the server bundle, but this module is the public\n// `@rshono/core/server` entry and could be loaded by tooling that doesn't (a unit test, a one-off script).\n// Read through `typeof` so that degrades to the safe answer — don't trust — instead of a ReferenceError.\nconst trustProxy = typeof __RSHONO_CONFIG__ !== 'undefined' && __RSHONO_CONFIG__.trustProxy;\n\n/**\n * Resolves the browser-facing {@link URL} for a request, from a Hono {@link Context}.\n *\n * `c.req.url` reflects the internal address the server was reached on, which is wrong behind a proxy.\n * `X-Forwarded-Host` / `X-Forwarded-Proto` fix that up — **but only when `trustProxy` is enabled in\n * `rshono.config.ts`** (always so under `rshono dev`). They are client-supplied, so honouring them\n * unconditionally would let anyone who can reach the server dictate the origin of every absolute URL\n * the app builds, and poison a shared cache with it.\n *\n * This is the form for **middleware**, which is handed `c` and runs outside the request context. In\n * a server component or a `'use server'` action prefer {@link RequestContext.url}, which is this same\n * value cached per request.\n *\n * Its main use is giving Hono's own middleware the origin the browser actually used, since they all\n * read `c.req.url` on their own and so see the internal one:\n *\n * @example\n * ```ts\n * // src/server.ts — a CSRF check that still works behind a proxy that rewrites Host\n * import { publicUrl } from '@rshono/core/server';\n * import { csrf } from 'hono/csrf';\n *\n * server.use(csrf({ origin: (origin, c) => origin === publicUrl(c).origin }));\n * ```\n *\n * A fresh instance per call, so mutating it disturbs nothing else.\n *\n * @param c - The Hono {@link Context} for the request.\n * @returns The browser-facing URL — proxy-corrected under `trustProxy`, `c.req.url` otherwise.\n *\n * @see {@link https://www.rshono.com/docs/configuration#proxy-headers | Docs — proxy headers}\n */\nexport function publicUrl(c: Context): URL {\n  const url = new URL(c.req.url);\n  if (!trustProxy) return url;\n\n  const forwardedHost = firstForwardedValue(c.req.header('x-forwarded-host'));\n  // Parsed rather than assigned to `url.host`, because that setter *keeps the existing port* when\n  // the new value has none — leaving the internal port on the public URL (`example.com:3000`).\n  const forwarded = forwardedHost ? URL.parse(`http://${forwardedHost}`) : null;\n  if (forwarded) {\n    url.hostname = forwarded.hostname;\n    url.port = forwarded.port; // '' when the forwarded host carries no port, which clears it\n  }\n\n  // Restricted to the two schemes a browser can actually have requested; anything else (a proxy\n  // sending junk, or a client trying its luck) leaves the scheme alone.\n  const forwardedProto = firstForwardedValue(c.req.header('x-forwarded-proto'));\n  if (forwardedProto === 'http' || forwardedProto === 'https') url.protocol = forwardedProto;\n\n  return url;\n}\n\n/**\n * The environment available to a request: Cloudflare/Workers `Bindings` merged\n * with process env vars. Values not declared in `Bindings` are typed as\n * `string | undefined`. See {@link RequestContext.env}.\n *\n * @see {@link https://hono.dev/docs/getting-started/cloudflare-workers#bindings | Hono — bindings}\n */\nexport type EnvVars<E extends Env> = E['Bindings'] & Record<string, string | undefined>;\n\n/**\n * Ergonomic, read-mostly wrapper around Hono's {@link Context} for use inside\n * server components and server actions.\n *\n * Obtain one with {@link getRequestContext}, or — in a page component — take it straight\n * off the `ctx` prop, which is this same object. Never construct it yourself. One\n * instance is reused for the lifetime of a request, so its lazy getters\n * ({@link RequestContext.url}, {@link RequestContext.env}) are computed at most once.\n *\n * @typeParam E - The Hono {@link Env} describing this app's `Bindings` and\n *   `Variables`, so {@link RequestContext.var} and {@link RequestContext.env} stay typed.\n *\n * @example\n * ```tsx\n * import { getRequestContext } from '@rshono/core/server';\n *\n * export default async function Whoami() {\n *   const ctx = getRequestContext();\n *   const session = ctx.cookies.get('session');\n *   return <p>{ctx.url.pathname} — {session ?? 'anonymous'}</p>;\n * }\n * ```\n *\n * @see {@link https://www.rshono.com/docs/api#rshonocoreserver | Docs — `@rshono/core/server`}\n * @see {@link https://hono.dev/docs/api/context | Hono — Context}, reachable in full via {@link RequestContext.hono}\n */\nexport class RequestContext<E extends Env = Env> {\n  #raw: Context<E>;\n  #url?: URL;\n  #env?: EnvVars<E>;\n  #params?: Record<string, string>;\n\n  /**\n   * Framework internal — one instance is created per request and handed to you by\n   * {@link getRequestContext} or the `ctx` page prop. Application code never calls this.\n   *\n   * @internal\n   */\n  constructor(c: Context<E>) {\n    this.#raw = c;\n  }\n\n  /**\n   * The underlying Hono {@link Context} — the escape hatch for what this wrapper does not expose,\n   * such as `executionCtx.waitUntil()` on Workers.\n   *\n   * Its response builders (`redirect`, `notFound`, `json`, `body`, `status`, …) still do nothing from\n   * inside a page, for the reason the stubs on this class explain: reaching them through here\n   * bypasses the error, it does not make them work.\n   *\n   * @example\n   * ```ts\n   * getRequestContext().hono.executionCtx.waitUntil(logAsync()); // Workers\n   * ```\n   *\n   * @see {@link https://hono.dev/docs/api/context | Hono — Context}\n   */\n  // A prototype getter rather than a plain property, so it is not *own enumerable*. React's\n  // diagnostic for a value that cannot be sent to a client component walks `Object.keys` recursively\n  // with no depth limit and no cycle guard, and the Hono context graph reaches the socket and the\n  // whole server through `req.raw` and `env` — as a plain property this blew the stack inside the\n  // message builder, so React's accurate \"you cannot pass this\" error never got printed. Every member\n  // here is a getter or method for the same reason; `cookies` is the one own enumerable property, and\n  // it is a shallow object of four functions.\n  get hono(): Context<E> {\n    return this.#raw;\n  }\n\n  /**\n   * The parsed request — method, headers, path params, query and the body readers. Hono's\n   * {@link Context.req}, unwrapped, so `ctx.req.header('authorization')` rather than\n   * `ctx.hono.req.header(…)`.\n   *\n   * Reads only. Setting a *response* header is {@link RequestContext.setHeader}, deliberately in a\n   * different place — Hono's `c.header()` writing the response while `c.req.header()` reads the\n   * request is a well-worn source of confusion.\n   *\n   * @example\n   * ```ts\n   * const ctx = getRequestContext();\n   * ctx.req.method;                     // 'GET'\n   * ctx.req.header('authorization');    // string | undefined\n   * ctx.req.query('tab');               // string | undefined\n   * ```\n   *\n   * @see {@link https://hono.dev/docs/api/request | Hono — HonoRequest}\n   */\n  get req(): Context<E>['req'] {\n    return this.#raw.req;\n  }\n\n  /**\n   * Matched route params for this request, e.g. `{ id: '42' }` for `/profile/:id`. Empty when there\n   * is no active route match.\n   *\n   * A **page** is handed the same record as its `params` prop, typed key-by-key from its route path,\n   * and that is the better read where it is available. This is for everywhere else — a nested server\n   * component, or a `'use server'` action — which get no props from the framework.\n   */\n  get params(): Record<string, string> {\n    return (this.#params ??= readParams(this.#raw as Context));\n  }\n\n  /**\n   * The browser-facing request URL — read `url.pathname`, `url.searchParams` and the\n   * rest off it. Parsed once and cached, so the same instance comes back on every\n   * read within a request; treat it as read-only for that reason.\n   *\n   * `X-Forwarded-Host` / `-Proto` are honoured only when `trustProxy` is enabled in\n   * `rshono.config.ts`, since any client can send them.\n   *\n   * @see {@link https://www.rshono.com/docs/configuration#proxy-headers | Docs — proxy headers}\n   */\n  get url(): URL {\n    return (this.#url ??= publicUrl(this.#raw as Context));\n  }\n\n  /**\n   * Typed variables set by middleware via `c.set('user', …)`, read here as\n   * `ctx.var.user`. Type them by parameterising this class's {@link Env}.\n   *\n   * @example\n   * ```ts\n   * type AppEnv = { Variables: { user: { id: string } } };\n   * const { user } = getRequestContext<AppEnv>().var; // typed, set by your middleware\n   * ```\n   *\n   * @see {@link https://hono.dev/docs/api/context#var | Hono — c.var}\n   * @see {@link https://www.rshono.com/docs/hono#typing-the-context | Docs — typing the context}\n   */\n  get var(): Readonly<E['Variables']> {\n    return this.#raw.var;\n  }\n\n  /**\n   * Environment for the request: process env vars merged with runtime bindings\n   * (bindings win on conflict). Computed once and cached.\n   *\n   * @example `const key = getRequestContext().env.STRIPE_SECRET_KEY;`\n   *\n   * @see {@link https://hono.dev/docs/api/context#env | Hono — c.env}\n   * @see {@link https://www.rshono.com/docs/configuration#environment-and-secrets | Docs — environment and secrets}\n   */\n  get env(): EnvVars<E> {\n    if (this.#env) return this.#env;\n    const bindings = this.#raw.env as Record<string, unknown> | undefined;\n    // The snapshot is shared, so hand it back as-is when there are no bindings to merge over it.\n    return (this.#env = (bindings ? { ...processEnv(), ...bindings } : processEnv()) as EnvVars<E>);\n  }\n\n  /**\n   * Read and write request/response cookies.\n   *\n   * @example\n   * ```ts\n   * const ctx = getRequestContext();\n   * ctx.cookies.get('session');                       // string | undefined\n   * ctx.cookies.set('session', id, { httpOnly: true, sameSite: 'Lax', path: '/' });\n   * ctx.cookies.delete('session', { path: '/' });\n   * ```\n   *\n   * @see {@link https://hono.dev/docs/helpers/cookie | Hono — cookie helper}, which this wraps\n   */\n  cookies = {\n    /** Reads a single cookie by name, or `undefined` if absent. Safe anywhere, a page included. */\n    get: (name: string): string | undefined => getCookie(this.#raw, name),\n    /** Reads every cookie as a `{ name: value }` record. Safe anywhere, a page included. */\n    all: (): Record<string, string> => getCookie(this.#raw),\n    /**\n     * Sets a cookie on the response. See Hono's {@link CookieOptions} for `path`, `httpOnly`,\n     * `maxAge`, etc.\n     *\n     * **Throws inside a page render** — see {@link RequestContext.setHeader}, of which a `Set-Cookie`\n     * is a special case. Set cookies from a `'use server'` action, or with Hono's `setCookie(c, …)`\n     * in middleware and endpoint routes.\n     *\n     * @throws If called while a page is rendering, where it could not reach the browser reliably.\n     *\n     * @see {@link https://hono.dev/docs/helpers/cookie#options | Hono — cookie options}\n     */\n    set: (name: string, value: string, options?: CookieOptions): void => {\n      this.#assertWritable('ctx.cookies.set()');\n      setCookie(this.#raw, name, value, options);\n    },\n    /**\n     * Clears a cookie. Pass the same `path`/`domain` it was set with so the browser matches it.\n     * Throws inside a page render, exactly as `set` does.\n     *\n     * @throws If called while a page is rendering.\n     */\n    delete: (name: string, options?: CookieOptions): void => {\n      this.#assertWritable('ctx.cookies.delete()');\n      deleteCookie(this.#raw, name, options);\n    },\n  };\n\n  /** Guards every write that has to reach the response head. See {@link tooLateToWrite}. */\n  #assertWritable(call: string): void {\n    if (rendering.has(this.#raw as Context)) tooLateToWrite(call);\n  }\n\n  /**\n   * Sets a header on the response — from a `'use server'` action, which is the one place a request\n   * context exists *and* the response is still open.\n   *\n   * From inside a page it throws: a page streams, so by then the response head is committed. Hono's\n   * `c.header()` fails there silently and inconsistently — landing on a full page load, vanishing on\n   * a soft navigation — so this refuses rather than doing it half the time.\n   *\n   * Middleware and `{ type: 'endpoint' }` routes run outside the request context but are handed\n   * Hono's `c` directly, so they use `c.header(…)`. That is also where a header belonging to the\n   * *page* rather than to one action goes — `Cache-Control`, `X-Robots-Tag` — since middleware runs\n   * before the render.\n   *\n   * @param name - Header name, case-insensitive.\n   * @param value - Header value.\n   * @param options - `{ append: true }` to add another value rather than replace.\n   * @throws If called while a page is rendering, where it could not reach the browser reliably.\n   *\n   * @example\n   * ```ts\n   * 'use server';\n   * export async function logout() {\n   *   const ctx = getRequestContext();\n   *   ctx.cookies.delete('session', { path: '/' });\n   *   ctx.setHeader('clear-site-data', '\"cache\", \"storage\"');\n   *   redirect('/');\n   * }\n   * ```\n   */\n  setHeader(name: string, value: string, options?: { append?: boolean }): void {\n    this.#assertWritable('ctx.setHeader()');\n    this.#raw.header(name, value, options);\n  }\n\n  // Hono's response builders, restated as errors naming what to use instead. A page returns JSX and\n  // `renderComponent` builds the response from it, so every one of these is a silent no-op through\n  // `ctx.hono`. `@deprecated` is the compile-time signal — an editor strikes them through in\n  // autocomplete — and the thrown message is the one that explains. Each takes `...args: unknown[]`\n  // it never reads so that `ctx.redirect('/dashboard')` reaches that message rather than stopping at\n  // \"Expected 0 arguments, but got 1\".\n\n  /** @deprecated Not available on a page's context — use `redirect()` from `@rshono/core/server`. */\n  redirect(...args: unknown[]): never {\n    return notOnContext(\n      'redirect(location, status?)',\n      \"Use `redirect()` from '@rshono/core/server', which throws a signal the framework turns into a real redirect.\",\n    );\n  }\n\n  /** @deprecated Not available on a page's context — use `notFound()` from `@rshono/core/server`. */\n  notFound(...args: unknown[]): never {\n    return notOnContext('notFound()', \"Use `notFound()` from '@rshono/core/server', which aborts the render and shows the app's not-found page.\");\n  }\n\n  /** @deprecated A page renders JSX. For a JSON response, use an `{ type: 'endpoint' }` route. */\n  json(...args: unknown[]): never {\n    return notOnContext('json(object)', \"For a JSON response use an { type: 'endpoint' } route; to read the request body use `ctx.req.json()`.\");\n  }\n\n  /** @deprecated A page renders JSX. For a text response, use an `{ type: 'endpoint' }` route. */\n  text(...args: unknown[]): never {\n    return notOnContext('text(string)', \"For a text response use an { type: 'endpoint' } route; to read the request body use `ctx.req.text()`.\");\n  }\n\n  /** @deprecated A page renders JSX, which the framework turns into HTML for you. */\n  html(...args: unknown[]): never {\n    return notOnContext('html(string)', \"A page's JSX is already its HTML; for a hand-built HTML response use an { type: 'endpoint' } route.\");\n  }\n\n  /** @deprecated Not available on a page's context. To read the request body, use `ctx.req`. */\n  body(...args: unknown[]): never {\n    return notOnContext(\n      'body(data, …)',\n      \"To read the *request* body use `ctx.req.json()` / `ctx.req.text()` / `ctx.req.formData()`; to build a response, use an { type: 'endpoint' } route.\",\n    );\n  }\n\n  /** @deprecated A page's status is set by the framework — use `notFound()`, or an endpoint route. */\n  status(...args: unknown[]): never {\n    return notOnContext(\n      'status(code)',\n      \"A page's status is the framework's: 200, 404 via `notFound()`, 500 when it throws. For any other code use an { type: 'endpoint' } route.\",\n    );\n  }\n\n  /** @deprecated Renamed — use `ctx.setHeader(name, value)`, which is valid from a `'use server'` action. */\n  header(...args: unknown[]): never {\n    return notOnContext(\n      'header(name, value)',\n      \"Use `ctx.setHeader(name, value)` from a 'use server' action, or `c.header(…)` in middleware — a page renders too late to set one.\",\n    );\n  }\n}\n\n/**\n * Returns the {@link RequestContext} for the current request — the URL, cookies, params, env and\n * middleware variables, read from a server component or a server action. Memoised per request, so\n * repeated calls return the same instance.\n *\n * A **page** component is handed that same object as its `ctx` prop, so this import is for everywhere\n * else: a nested server component, or a `'use server'` action module.\n *\n * @typeParam E - The app's Hono {@link Env}, to type {@link RequestContext.var} and {@link RequestContext.env}.\n * @throws If called at module load, where there is no ambient context to resolve.\n * @throws If called while prerendering a `render: 'static'` route, which has no\n *   per-request context at build time — mark the route `render: 'dynamic'` instead.\n *\n * @example\n * ```ts\n * 'use server';\n * import { getRequestContext, redirect } from '@rshono/core/server';\n *\n * export async function login(form: FormData) {\n *   getRequestContext().cookies.set('session', String(form.get('email')), { httpOnly: true });\n *   redirect('/dashboard');\n * }\n * ```\n *\n * @see {@link https://www.rshono.com/docs/api#rshonocoreserver | Docs — `@rshono/core/server`}\n */\nexport function getRequestContext<E extends Env = Env>(): RequestContext<E> {\n  if (prerendering) {\n    throw new Error(\n      \"[rshono] getRequestContext() was called while prerendering a `render: 'static'` route. A static page \" +\n        'is rendered once at build time, so it has no per-request context to read (URL, cookies, ' +\n        \"headers, env). Change this route to `render: 'dynamic'` so it renders per request, or remove \" +\n        'the getRequestContext() call.',\n    );\n  }\n  const c = contextStorage.getStore();\n  if (!c) {\n    throw new Error(\n      '[rshono] getRequestContext() was called outside a request. It only works inside a server component or a server action, not at module load.',\n    );\n  }\n  let ctx = wrappers.get(c);\n  if (!ctx) {\n    ctx = new RequestContext(c);\n    wrappers.set(c, ctx);\n  }\n  return ctx as unknown as RequestContext<E>;\n}\n\n/**\n * Redirects the request to `location` by throwing a control signal that the\n * framework catches and turns into an HTTP redirect response.\n *\n * Because it throws, it never returns — TypeScript narrows away any code after\n * the call, and you do not need to `return` it. Do not wrap it in a `try/catch`\n * that swallows the signal.\n *\n * @param location - Absolute path or URL to redirect to, e.g. `/dashboard`.\n * @param status - Redirect {@link RedirectStatus}; defaults to `303` (See Other),\n *   the correct choice after a form action so the browser follows up with a `GET`.\n *\n * @example\n * ```ts\n * const session = getRequestContext().cookies.get('session');\n * if (!session) redirect('/login');\n * // session is defined below this line\n * ```\n */\nexport function redirect(location: string, status: RedirectStatus = 303): never {\n  throw new RedirectSignal(location, status);\n}\n\n/**\n * Aborts the current render with a 404, rendering the app's not-found page.\n *\n * Like {@link redirect}, this throws a control signal and never returns, so\n * TypeScript narrows away everything after the call. Do not catch-and-swallow it.\n *\n * @example\n * ```tsx\n * export default async function Page({ params }: PageProps<'/users/:id'>) {\n *   const user = await db.user.find(params.id);\n *   if (!user) notFound();\n *   return <Profile user={user} />; // user is non-null here\n * }\n * ```\n */\nexport function notFound(): never {\n  throw new NotFoundSignal();\n}\n\n/**\n * Which stage of a request produced an error handed to an {@link ServerErrorHandler}.\n *\n * - `action` — a `'use server'` function threw. React sends the client an opaque marker with no\n *   message in production, so this is the only place the real error is visible.\n * - `render` — a server component threw while the flight payload was being produced.\n * - `ssr` — SSR failed before the HTML shell could be sent, so the `error` page was unreachable too.\n * - `request` — anything else that reached the top-level handler, including a thrown endpoint route.\n */\nexport type ServerErrorSource = 'action' | 'render' | 'ssr' | 'request';\n\n/** What an {@link ServerErrorHandler} is told about an error, beyond the error itself. */\nexport interface ServerErrorContext {\n  /** The stage that produced it — see {@link ServerErrorSource}. */\n  source: ServerErrorSource;\n  /** The request being served, for the URL, method and headers. */\n  request: Request;\n}\n\n/** Handler registered with {@link onServerError}. Called for the side effect; its return value is ignored. */\nexport type ServerErrorHandler = (error: unknown, context: ServerErrorContext) => void;\n\nlet errorHandler: ServerErrorHandler | undefined;\n\n/**\n * Registers a handler for every error the framework catches, so they can reach an error tracker\n * (Sentry, Datadog, a log pipeline) instead of only `stderr`.\n *\n * Call it **once, at the top level of `src/server.ts`** — that module is imported as the server\n * starts, before any request is served. Registering again replaces the previous handler.\n *\n * Errors are still written to `stderr` either way, so a handler adds a destination rather than\n * replacing one. A handler that throws is caught and logged: reporting must never be able to fail\n * a request.\n *\n * @example\n * ```ts\n * // src/server.ts\n * import * as Sentry from '@sentry/node';\n * import { onServerError } from '@rshono/core/server';\n *\n * onServerError((error, { source, request }) => {\n *   Sentry.captureException(error, { tags: { source }, extra: { url: request.url } });\n * });\n * ```\n *\n * @see {@link https://www.rshono.com/docs/hono#error-reporting | Docs — error reporting}\n */\nexport function onServerError(handler: ServerErrorHandler): void {\n  errorHandler = handler;\n}\n\n/**\n * Logs an error and forwards it to the registered {@link ServerErrorHandler}.\n *\n * Framework internal — the single funnel every caught server-side error goes through, so that\n * adding a reporting destination is one registration rather than a hook per call site.\n *\n * @internal\n */\nexport function reportServerError(error: unknown, info: ServerErrorContext & { message: string }): void {\n  console.error(info.message, error);\n  if (!errorHandler) return;\n  try {\n    errorHandler(error, { source: info.source, request: info.request });\n  } catch (handlerError) {\n    console.error('[rshono] the onServerError handler threw:', handlerError);\n  }\n}\n"]}

package/dist/runtime/control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../src/runtime/control.ts"],"names":[],"mappings":"AAGA,qBAAa,cAAe,SAAQ,KAAK;IAGrC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM;IAHzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,YACW,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAKxB;CACF;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,sBAAoB;IACnC,cAGC;CACF;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,cAAc,CAAC;AAE5D,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,MAAM,CAEjE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQ/F"}
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../src/runtime/control.ts"],"names":[],"mappings":"AAUA,qBAAa,cAAe,SAAQ,KAAK;IAGrC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM;IAHzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,YACW,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAKxB;CACF;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,sBAAoB;IACnC,cAGC;CACF;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,cAAc,CAAC;AAE5D,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,MAAM,CAEjE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQ/F"}

package/dist/runtime/control.js

@@ -1,3 +1,10 @@
+/**
+ * `redirect()` and `notFound()` as thrown errors, and the `digest` string that carries them.
+ *
+ * The digest is the only part that survives React: an error thrown inside a server component reaches
+ * the browser as a digest with no message, so the redirect target has to be encoded into it. The
+ * server catches the class (`isControlSignal`), the client matches the string (`isControlDigest`).
+ */
 const REDIRECT_PREFIX = 'RSHONO_REDIRECT;';
 const NOT_FOUND_DIGEST = 'RSHONO_NOT_FOUND';
 export class RedirectSignal extends Error {

package/dist/runtime/control.js.map

@@ -1 +1 @@
-{"version":3,"file":"control.js","sourceRoot":"","sources":["../../src/runtime/control.ts"],"names":[],"mappings":"AAAA,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAC3C,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AAE5C,MAAM,OAAO,cAAe,SAAQ,KAAK;IAG5B,QAAQ;IACR,MAAM;IAHR,MAAM,CAAS;IACxB,YACW,QAAgB,EAChB,MAAc;QAEvB,KAAK,CAAC,wBAAwB,QAAQ,EAAE,CAAC,CAAC;wBAHjC,QAAQ;sBACR,MAAM;QAGf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,GAAG,eAAe,GAAG,MAAM,IAAI,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC9E,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,MAAM,GAAG,gBAAgB,CAAC;IACnC;QACE,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAID,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,KAAK,YAAY,cAAc,IAAI,KAAK,YAAY,cAAc,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAe;IAC7C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,KAAK,gBAAgB,IAAI,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC;AAC3G,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AACtE,CAAC","sourcesContent":["const REDIRECT_PREFIX = 'RSHONO_REDIRECT;';\nconst NOT_FOUND_DIGEST = 'RSHONO_NOT_FOUND';\n\nexport class RedirectSignal extends Error {\n  readonly digest: string;\n  constructor(\n    readonly location: string,\n    readonly status: number,\n  ) {\n    super(`[rshono] redirect to ${location}`);\n    this.name = 'RedirectSignal';\n    this.digest = `${REDIRECT_PREFIX}${status};${encodeURIComponent(location)}`;\n  }\n}\n\nexport class NotFoundSignal extends Error {\n  readonly digest = NOT_FOUND_DIGEST;\n  constructor() {\n    super('[rshono] notFound');\n    this.name = 'NotFoundSignal';\n  }\n}\n\nexport type ControlSignal = RedirectSignal | NotFoundSignal;\n\nexport function isControlSignal(error: unknown): error is ControlSignal {\n  return error instanceof RedirectSignal || error instanceof NotFoundSignal;\n}\n\nexport function isControlDigest(digest: unknown): digest is string {\n  return typeof digest === 'string' && (digest === NOT_FOUND_DIGEST || digest.startsWith(REDIRECT_PREFIX));\n}\n\nexport function parseRedirectDigest(digest: string): { location: string; status: number } | null {\n  if (!digest.startsWith(REDIRECT_PREFIX)) return null;\n  const rest = digest.slice(REDIRECT_PREFIX.length);\n  const sep = rest.indexOf(';');\n  if (sep === -1) return null;\n  const status = Number(rest.slice(0, sep));\n  const location = decodeURIComponent(rest.slice(sep + 1));\n  return { location, status: Number.isFinite(status) ? status : 307 };\n}\n"]}
+{"version":3,"file":"control.js","sourceRoot":"","sources":["../../src/runtime/control.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAC3C,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AAE5C,MAAM,OAAO,cAAe,SAAQ,KAAK;IAG5B,QAAQ;IACR,MAAM;IAHR,MAAM,CAAS;IACxB,YACW,QAAgB,EAChB,MAAc;QAEvB,KAAK,CAAC,wBAAwB,QAAQ,EAAE,CAAC,CAAC;wBAHjC,QAAQ;sBACR,MAAM;QAGf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,GAAG,eAAe,GAAG,MAAM,IAAI,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC9E,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,MAAM,GAAG,gBAAgB,CAAC;IACnC;QACE,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAID,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,KAAK,YAAY,cAAc,IAAI,KAAK,YAAY,cAAc,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAe;IAC7C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,KAAK,gBAAgB,IAAI,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC;AAC3G,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AACtE,CAAC","sourcesContent":["/**\n * `redirect()` and `notFound()` as thrown errors, and the `digest` string that carries them.\n *\n * The digest is the only part that survives React: an error thrown inside a server component reaches\n * the browser as a digest with no message, so the redirect target has to be encoded into it. The\n * server catches the class (`isControlSignal`), the client matches the string (`isControlDigest`).\n */\nconst REDIRECT_PREFIX = 'RSHONO_REDIRECT;';\nconst NOT_FOUND_DIGEST = 'RSHONO_NOT_FOUND';\n\nexport class RedirectSignal extends Error {\n  readonly digest: string;\n  constructor(\n    readonly location: string,\n    readonly status: number,\n  ) {\n    super(`[rshono] redirect to ${location}`);\n    this.name = 'RedirectSignal';\n    this.digest = `${REDIRECT_PREFIX}${status};${encodeURIComponent(location)}`;\n  }\n}\n\nexport class NotFoundSignal extends Error {\n  readonly digest = NOT_FOUND_DIGEST;\n  constructor() {\n    super('[rshono] notFound');\n    this.name = 'NotFoundSignal';\n  }\n}\n\nexport type ControlSignal = RedirectSignal | NotFoundSignal;\n\nexport function isControlSignal(error: unknown): error is ControlSignal {\n  return error instanceof RedirectSignal || error instanceof NotFoundSignal;\n}\n\nexport function isControlDigest(digest: unknown): digest is string {\n  return typeof digest === 'string' && (digest === NOT_FOUND_DIGEST || digest.startsWith(REDIRECT_PREFIX));\n}\n\nexport function parseRedirectDigest(digest: string): { location: string; status: number } | null {\n  if (!digest.startsWith(REDIRECT_PREFIX)) return null;\n  const rest = digest.slice(REDIRECT_PREFIX.length);\n  const sep = rest.indexOf(';');\n  if (sep === -1) return null;\n  const status = Number(rest.slice(0, sep));\n  const location = decodeURIComponent(rest.slice(sep + 1));\n  return { location, status: Number.isFinite(status) ? status : 307 };\n}\n"]}