@rsc-kit/mcp 0.13.1 → 0.15.0

package/guides/authorization.md

@@ -0,0 +1,288 @@
+# Authorization
+
+> Protecting pages, server actions and API routes.
+
+There are three ways into your app — a page, a server action, an API route —
+and each needs its own check. Guarding one does not guard the others.
+
+## Protect a page
+
+Put a `middleware.ts` in the directory you want to protect:
+
+```ts title="src/app/admin/middleware.ts"
+import { redirect } from '@rsc-kit/core/redirect';
+import { currentUser } from '../../auth';
+
+export default async function middleware() {
+  const user = await currentUser();
+
+  if (!user?.isAdmin) redirect('/login');
+}
+```
+
+It runs before anything in that directory or below it renders. Return nothing
+to allow; redirect or throw to refuse.
+
+Middleware compose up the tree like layouts — outermost first — and **every**
+request runs the whole chain: a full page load, a navigation, a prefetch, a
+revalidation. There is no flag to remember; the file is the declaration.
+
+<Aside type="caution" title="Do not put the check in a layout">
+  It looks like it works, and it does on a full page load. But a navigation
+  tells the server which layouts the browser already has, and the server skips
+  them — that is what makes navigation fast. A request can claim to have your
+  layout, and then the check never runs.
+
+  `middleware.ts` is never skipped.
+</Aside>
+
+## Protect a server action
+
+An action is a public endpoint. Anyone can call it directly:
+
+```bash
+curl -X POST /_rsc/action \
+  -H 'X-RSC-Action: 0339292364be#placeOrder' \
+  -H 'X-RSC-Content-Type: text/plain;charset=UTF-8' \
+  --data-binary '["a rubber duck"]'
+```
+
+That is not a hole to plug — an action *is* an RPC endpoint and its id is not a
+secret. It means the check goes **inside the action**, not in the component that
+renders the button:
+
+```ts title="src/actions.ts"
+'use server'
+
+import { currentUser } from './auth';
+
+export async function placeOrder(item: string) {
+  const user = await currentUser();
+
+  if (!user) throw new Error('Not signed in');
+
+  // …
+}
+```
+
+<Aside type="caution" title="Middleware does not cover actions">
+  Middleware runs when a route renders. An action renders no route, so none of
+  them run. Each entry point defends itself.
+</Aside>
+
+### Write the check once
+
+One action is fine. Twenty is twenty chances to forget, and the one you forget
+is the one that matters. Put the check on a client and build every action from
+it:
+
+```ts title="src/server/client.ts"
+'use server'
+
+import { createActionClient } from '@rsc-kit/core/action'
+
+export const client = createActionClient()
+  .use(async ({ next }) => {
+    const user = await currentUser()
+
+    if (!user) throw new ServerAuthenticationError()
+
+    return next({ ctx: { user } })
+  })
+```
+
+```ts title="src/server/orders.ts"
+'use server'
+
+import { client } from './client'
+
+export const placeOrder = client.input(schema).handler(async ({ input, ctx }) =>
+  orders.create(ctx.user.id, input),
+)
+
+export const listOrders = client.query(async ({ ctx }) => orders.forUser(ctx.user.id))
+```
+
+`ctx.user` is typed and non-null inside the handler, because the only way to get
+there was through the middleware that put it in. **An action cannot be added
+without the check** — not because a rule says so, but because there is no other
+constructor to reach for.
+
+`.handler()` makes an action, `.query()` makes a [read](/guides/queries/), and
+both run the same chain. Add a second `.use()` for a role check and it applies
+to everything built from that client:
+
+```ts
+export const admin = client.use(async ({ ctx, next }) => {
+  if (!ctx.user.isAdmin) throw new ServerAuthorizationError()
+
+  return next({ ctx })
+})
+```
+
+Authorise on **identity, not arguments**. `cancelOrder(id)` that trusts the id
+is the whole of an IDOR — the caller chooses the id, so the handler has to check
+the row belongs to `ctx.user`.
+
+## Protect an API route
+
+A [route](/guides/api-routes/) runs the same middleware a page in that directory
+would. Put it under a guarded path and it is guarded:
+
+```text
+src/app/admin/
+  middleware.ts          ← guards everything below
+  page.tsx               ← guarded
+  api/export/route.ts    ← guarded too
+```
+
+A refused route answers **401** or **403** rather than redirecting, and names
+the destination in `X-RSC-Redirect` if the middleware wanted one. A `fetch`
+would follow a redirect and hand back a login page as though it were your data.
+
+For a route with no middleware above it, check inside the handler:
+
+```ts title="src/app/api/orders/route.ts"
+import { currentUser } from '../../../auth';
+
+export async function GET(): Promise<Response> {
+  const user = await currentUser();
+
+  if (!user) return new Response('Unauthorized', { status: 401 });
+
+  return Response.json(await orders(user.id));
+}
+```
+
+## Read the session
+
+There is no request object. `headers()` and `cookies()` read the one in flight:
+
+```ts title="src/app/[locale]/middleware.ts"
+import { redirect } from '@rsc-kit/core/redirect';
+import { cookies, headers } from '@rsc-kit/core/request';
+
+export default async function middleware() {
+  const jar = await cookies();
+  const locale = jar.get('locale') ?? negotiate((await headers()).get('accept-language'));
+
+  if (!locale) redirect('/en');
+}
+```
+
+They work anywhere a request is in flight — middleware, server components,
+actions, API routes — so whatever you already use for locale, feature flags or
+tenants works inside a plain async function. `request()` gives you the whole
+`Request` for anything the two do not cover.
+
+They are async for a reason worth knowing: at build time there is no request, so
+a read *suspends*. React freezes the shell above it and only the part that
+wanted a header renders per visitor. A synchronous read would force the whole
+page to re-render for everyone.
+
+### Ask once
+
+Middleware wants to know who you are; the layout wants their name; the page
+wants their permissions. Wrap the lookup in `cache()` and that is one query:
+
+```ts title="src/session.ts"
+import { cache } from '@rsc-kit/core/cache';
+
+export const currentUser = cache(async () => {
+  const id = await sessionId();
+
+  return db.user(id);
+});
+```
+
+The scope is one request. Two requests never see each other's answers, and
+nothing survives between them. Outside a request it just calls through, so
+shared code does not need to know where it is running.
+
+## Set a cookie
+
+Middleware runs before the response exists, which makes it the place to put a
+header or a cookie on it:
+
+```ts title="src/app/account/middleware.ts"
+import { cookies, responseHeaders } from '@rsc-kit/core/request'
+
+// Middleware runs before anything below it renders, which is also before the
+// host has built a response — so this is the one place left where a header or a
+// cookie can still be put on it. A component runs after, while the response is
+// already streaming, and writing from there throws rather than being dropped.
+//
+// The page below is frozen at build time and stays frozen: what is written here
+// is per request, so neither costs the other anything.
+export default async function middleware() {
+  responseHeaders().set('X-Account-Section', 'yes')
+
+  const jar = await cookies()
+
+  if (!jar.get('seen-account')) {
+    jar.set('seen-account', new Date().toISOString(), { httpOnly: true, sameSite: 'lax' })
+  }
+}
+```
+
+Actions can write too, which is the case that matters — signing someone in is a
+mutation that has to leave a cookie behind:
+
+```ts title="src/app/login/actions.ts"
+'use server';
+
+import { action } from '@rsc-kit/core/action';
+import { cookies } from '@rsc-kit/core/request';
+
+export const login = action.input(credentials).handler(async ({ input }) => {
+  const session = await authenticate(input);
+
+  (await cookies()).set('session', session.token, {
+    httpOnly: true,
+    secure: true,
+    sameSite: 'lax',
+    maxAge: 60 * 60 * 24 * 7,
+  });
+});
+```
+
+`get`, `set` and `delete` over the request in flight is the whole surface an
+auth library needs, so you can wire in whichever one you use.
+
+<Aside type="caution" title="A component is too late">
+  By the time a page renders, the status and headers are already on the wire.
+  Writing from a component throws and tells you to move it to middleware —
+  rather than accepting the call and quietly dropping it.
+</Aside>
+
+## A guarded page can still be frozen
+
+Whether the content is the same for everyone, and whether *you* may see it, are
+different questions. The build answers the first; middleware answers the second,
+per request. So an internal page whose bytes never vary is frozen at build time
+and the middleware decides who gets the file:
+
+| Route | Navigation |
+| --- | --- |
+| Guarded and frozen — check, then serve from disk | 6.7 ms |
+| Guarded, rendered on demand | 2626.7 ms |
+| Unguarded, frozen | 0.6 ms |
+
+The check runs before the file is read, so a refusal never touches it.
+
+<Aside type="caution" title="Two places this does not hold">
+  **A static export cannot guard anything.** A static host serves files without
+  running code, so exporting a guarded route publishes it to whoever asks.
+
+  **Do not put a guarded page in a shared cache.** Your origin runs the check; a
+  CDN holding the response serves it to the next caller without asking.
+</Aside>
+
+## Where each check goes
+
+| Question | Where it goes |
+| --- | --- |
+| May this person see this section? | `middleware.ts` in its directory |
+| May this caller run this action? | Inside the action |
+| May this caller use this endpoint? | Inside the route handler |
+| Should the page show different things to different people? | The page — it renders per request anyway |

package/guides/caching.md

@@ -0,0 +1,57 @@
+# Asking once per request
+
+> cache() — one lookup, however many places need it.
+
+Middleware checks who you are. The layout wants their name. The page wants their
+permissions. That is three calls and one answer.
+
+Wrap the lookup:
+
+```ts
+import { cache } from '@rsc-kit/core/cache'
+
+export const currentUser = cache(async () => db.user(await sessionId()))
+```
+
+Now call it wherever you need it. The first call runs; the rest get the same
+answer:
+
+```tsx
+export async function middleware() {
+  if (!(await currentUser())) redirect('/login')
+}
+
+export default async function Page() {
+  const user = await currentUser()   // already resolved
+
+  return <h1>Hello {user.name}</h1>
+}
+```
+
+## One request, and no further
+
+Two requests in flight never see each other's answers, and nothing survives into
+the next one. The scope opens when the request arrives and is torn down with it.
+
+That is the whole safety story: a table that outlived its request would not be a
+stale cache, it would be one visitor seeing another's data.
+
+## Arguments
+
+Compared the way React compares them — primitives by value, objects by identity:
+
+```ts
+const post = cache(async (id: string) => db.post(id))
+
+post('a')   // runs
+post('a')   // reuses the first
+post('b')   // runs
+```
+
+Two objects that look the same are two different calls, so pass an id rather
+than an object when you want the reuse.
+
+<Aside type="note" title="Not React's cache()">
+  Same idea, wider scope. Middleware runs before any component does, which is
+  exactly where the duplicate lookups start — and React has no scope open yet.
+</Aside>

package/guides/connection.md

@@ -0,0 +1,98 @@
+# Rendering per request
+
+> Marking work that belongs to the visitor, not to the build.
+
+Most pages can be rendered once, at build time, and served as files. Some work
+cannot: a query whose database the build machine cannot reach, or a value that
+has to differ per visitor.
+
+`connection()` marks that work.
+
+```tsx title="src/app/orders/page.tsx"
+import { connection } from '@rsc-kit/core/request'
+
+export default async function OrdersPage() {
+  await connection()
+
+  const rows = await db.query('select * from orders')
+
+  return <ul>{rows.map((r) => <li key={r.id}>{r.reference}</li>)}</ul>
+}
+```
+
+At build time it never resolves, so **nothing after it runs** — the query is not
+made, and the build needs no database. At request time it resolves immediately
+and the component runs normally.
+
+## Call it once
+
+This is the mistake worth avoiding:
+
+```tsx
+await connection()
+
+const orders = await db.orders()
+await connection()          // ← does nothing
+const customers = await db.customers()
+await connection()          // ← does nothing
+```
+
+It is a **barrier, not a wrapper**. Everything after it in that component
+belongs to the request, however many calls that turns out to be. The second and
+third calls are already covered by the first.
+
+One call, as early as the work begins. That is the whole API.
+
+## It needs a boundary above it
+
+The build stores what it *can* paint. If `connection()` is reached before
+anything has painted, there is nothing to store:
+
+```tsx
+export default async function Page() {
+  await connection()        // nothing above it has rendered
+
+  return <h1>{await something()}</h1>
+}
+```
+
+Give it a boundary and the page becomes a shell — the layout and headings are
+stored, and the marked part arrives per request:
+
+```tsx
+export default function Page() {
+  return (
+    <>
+      <h1>Orders</h1>
+      <Suspense fallback={<p>Loading orders…</p>}>
+        <Orders />          {/* calls connection() inside */}
+      </Suspense>
+    </>
+  )
+}
+```
+
+A `loading.tsx` beside the page does the same thing for everything below it.
+Without either, the build refuses the route rather than storing a blank page,
+and tells you which one to add.
+
+## When you do not need it
+
+A query the build **can** run, whose answer is the same for every visitor, wants
+none of this. Let it freeze — that is the whole benefit of prerendering, and
+marking it per-request gives every visitor a render they did not need.
+
+Use it when the build genuinely should not do the work:
+
+- the database or API is not reachable from the build machine
+- the value must differ per visitor
+- the data changes faster than you deploy
+
+## Same as Next.js
+
+Same name and same behaviour as Next's `connection()`, so there is nothing new
+to learn if you have used it.
+
+You will reach for it less often here, though. The build classifies routes by
+rendering them rather than asking you to declare, so most dynamic pages are
+already understood without a marker.

package/guides/edge-caching.md

@@ -0,0 +1,159 @@
+# Serving shells from a CDN
+
+> Putting build-time shells on the edge, and what rsc-kit does not do.
+
+A prerendered page is a file. So is a PPR shell. Both can sit on a CDN and be
+served without touching your origin.
+
+## What the build gives you
+
+```
+build/static/
+  about.html            a whole page, frozen
+  posts/hello.html      likewise
+  posts/[slug].ppr.html a shell — static parts frozen, holes still empty
+  about.flight          the payload for a client-side navigation
+  about.seg1.flight     the same, for a client already holding one layout
+```
+
+`.html` is a finished page. `.ppr.html` is a shell: the layout, nav and
+everything outside a `<Suspense>` boundary, with the fallbacks still in place.
+Neither contains per-visitor data — they were rendered at build time, in no
+request's context, which is what makes them safe for a shared cache.
+
+## Caching them
+
+The host already sends the right header:
+
+```
+Cache-Control: public, max-age=0, must-revalidate
+```
+
+`public` says a shared cache may store it. `max-age=0, must-revalidate` says
+**check with the origin first**. So a CDN in front of this holds the bytes but
+still asks every time — which saves bandwidth and nothing else.
+
+To actually serve from the edge, add a cache rule for the paths you want held,
+and give the CDN an edge TTL. On Cloudflare that is a Cache Rule with *Edge TTL
+→ Override origin*.
+
+**Do not blanket-cache the whole site.** A route with middleware is deliberately
+sent as:
+
+```
+Cache-Control: private, no-store
+```
+
+because middleware runs per visitor — that is a page whose content depends on
+who asked. A zone-wide "cache everything" rule overrides that and serves one
+person's gated page to everyone. Scope the rule to the paths you know are
+static.
+
+Deployments are handled for you: cached responses carry a build version, so a
+new deploy does not leave old shells being served against a new payload.
+
+## Finishing a shell at the edge
+
+A shell has holes in it, and something has to fill them. That happens at your
+origin, into the same response — the shell is written first, then the
+boundaries it could not finish.
+
+You get this with no configuration: request a PPR route and the document you
+receive already contains its dynamic content.
+
+A small inline script from React moves each hole into place as the HTML parses.
+So the content appears without waiting for the app bundle or for hydration — on
+a slow connection, the difference between a spinner and a page. It also means
+the content is in the HTML a crawler reads.
+
+This is not the same as working without JavaScript: with scripting off, the
+fallbacks stay.
+
+To serve the shell itself from a CDN, two endpoints exist for an edge worker:
+
+```
+GET  /_rsc/ppr-shell?url=/dashboard    the build-time shell, cacheable
+POST /_rsc/ppr-resume?url=/dashboard   the holes, for this visitor
+```
+
+There is a complete Cloudflare implementation in
+[`examples/cloudflare-ppr-worker`](https://github.com/rsc-kit/rsc-kit/tree/main/examples/cloudflare-ppr-worker),
+with no KV and no build step. The cache fills itself from the shell endpoint: a
+miss goes to the origin while the shell warms behind it, and a hit streams the
+shell then pipes the resumed holes onto the same response.
+
+### What the response looks like on the wire
+
+Measured on a deployed worker, for a page whose hole takes 2.5 s:
+
+```
+headers          55 ms
+first body byte  56 ms
+shell heading    56 ms      ← the page is on screen here
+fallback markup  56 ms
+hole content   2549 ms      ← same response, no second request
+stream complete 2549 ms
+```
+
+Before this, the same document finished in 2 ms and contained no hole at all —
+the content arrived later, on a separate payload fetch, after React had
+hydrated.
+
+**The trade is that the response stays open until the holes finish.** Previously
+the document closed immediately and `load` fired early; now it fires when the
+slowest boundary resolves. Nothing a visitor sees is slower — the shell paints
+at the same moment either way — but page-level metrics that key on `load` will
+read differently, and a proxy with a short response timeout needs to allow for
+the whole render rather than just the shell.
+
+## Guarded routes are never cached
+
+The shell endpoint answers `404` for any route that declares middleware. Such a
+page is not cacheable by a shared cache at all, so it never becomes a cache
+entry — refused at the source rather than checked at the edge.
+
+The resume endpoint runs that route's middleware against **the caller's own
+cookies**, and refuses before rendering anything. An edge worker must therefore
+forward the visitor's request rather than making one of its own; a resume asked
+for with no cookies is an anonymous visitor and gets an anonymous answer.
+
+## What stays on your origin
+
+Next's PPR protocol hands the postponed blob to the CDN and takes it back on the
+resume, which means the resume endpoint parses something an attacker can write.
+That is the shape of a known denial-of-service against it.
+
+Here the endpoint takes a **url**. The origin reads its own state from disk, and
+a body posted to it is ignored. This is only possible because — unlike a generic
+CDN — the origin already has the artifact, so there is nothing to hand out and
+take back.
+
+## When a CDN owns the response
+
+Everything above rests on one fact: on this host, a per-visitor response head
+can only come from middleware. `responseHeaders()` and `cookies().set()` throw
+outside it, so a route that declares no middleware has no way to acquire one —
+which is why "declares middleware" is a safe answer to "is this cacheable".
+
+An auth proxy in front of the app breaks that, and quietly. One with sliding
+expiry re-issues the session on an ordinary `200`, so the response leaving your
+CDN carries a `Set-Cookie` this host never sent. Marked `public`, that is one
+visitor's session handed to the next.
+
+**Give any path your proxy covers a `middleware.ts`**, even an empty one. That
+is what makes a route covered here, and covered routes are excluded from every
+cache decision: `private, no-store` on the page, and refused outright by the
+shell endpoint.
+
+Two things worth knowing about this failure if you go looking for it.
+
+You cannot detect this by inspecting the response. Nothing added a
+`Vary: Cookie`, and looking for `Set-Cookie` only catches the cookie version —
+an `x-user-id`, a CSRF token or a locale header leaks the same way.
+
+The reliable question is structural: who owns the response head on this route?
+
+It fails both ways. The loud one is a session leaking to the next visitor. The
+quiet one is the reverse — an anonymous response cached first, then served to
+someone who should have had a session, silently signing them out. The first gets
+reported; the second looks like a flaky login.