The model is a BAP — Backend-Answered Pages; this page is the wire.
There is no adapter to write on the JavaScript side. The renderer is what
Nitro builds, on every host, and it already knows how to ask a backend for
things: a server component calls rpc(), and the call leaves the process as
an ordinary POST. What a backend implements is that one endpoint. Laravel’s is
about 400 lines of PHP; Go’s is about the same.
This page is the contract, so a Rails, Django, .NET or Elixir application can answer it the same way.
Telling the renderer where you are
Two variables, and the renderer wires itself. Both in development — vite
reads the project’s .env — and in production, where the built server reads
its process environment:
RSC_BACKEND=http://127.0.0.1:8080
RSC_HOST_CALL_SECRET=… # openssl rand -base64 32 - see Secrets under DeploymentAPP_URL is read where RSC_BACKEND is absent, which is what makes a Laravel
app need nothing extra. Optional beside them: RSC_HOST_CALL_PATH (default
/__rsc/host-call) and RSC_HOST_GLOBAL (default rpc, the name server
components call). Both, or neither: a secret without a backend has nowhere to
go, and a backend without a secret is refused at the door — the renderer does
not gate on one of the pair alone.
Both are read when the first request arrives, not when the module loads, so
they work wherever the built server runs: a process with an environment, or a
Worker, where Nitro maps the bindings in wrangler.json — a var for the
address, a secret for the secret — onto process.env per request. On a
Worker the backend has to be reachable from Cloudflare’s network, so it is an
https origin behind the secret rather than a loopback address.
Then the plugin’s hostCall option overrides any of it for a setup that
would rather not use the environment:
rscKit({ hostCall: { endpoint: 'http://127.0.0.1:8080', secret, path: '/__rsc/host-call' } })The request
POST /__rsc/host-call
Content-Type: application/json
X-Rsc-Host-Secret: a-long-random-string
Cookie: <the visitor's, forwarded unchanged>
Authorization: <likewise, if the page request had one>
X-Rsc-Client-Ip: <the visitor's address, as the renderer's server saw it>
X-Rsc-Client-User-Agent: <the visitor's User-Agent>
{ "function": "Orders.recent", "args": [5] }function is whatever the component passed to rpc(); the naming scheme is
yours. args is positional, exactly as passed. Cookie and Authorization
are the only headers copied from the page request — everything else either
describes this POST or is meaningless to you — and they are what let the call
run as the visitor: your session middleware reads the cookie and finds the
same person the page is being rendered for. During a build there is no
visitor and the headers are absent.
X-Rsc-Client-Ip is the visitor’s address, not the renderer’s: the peer
the renderer’s server accepted the page request from, or the first hop of
X-Forwarded-For when the renderer runs with RSC_TRUST_FORWARDED=1 behind a
proxy of its own. Believe it only once the secret matches - before that,
anybody can send it - and then in place of the connection’s address, which is
the renderer’s and the same for every visitor. A throttle keyed on that puts
everyone in one bucket. Absent when there is no visitor: a build, or a page
stored for everyone.
X-Rsc-Client-User-Agent is the visitor’s browser, for whatever you keep
about a request: a log, a list of signed-in devices, an audit entry. The
call’s own User-Agent is the renderer’s runtime, the same for everyone.
Believe it on the same terms as the address, and expect it absent on the same
occasions. Laravel puts it where $request->userAgent() reads; Go’s is
rsckit.ClientUserAgent(ctx).
Arguments that do not fit the function are a failure, not a refusal.
Too few, or a value your language cannot decode into the parameter’s type:
answer 500 with error, as Go and Laravel do. The renderer’s calls are typed
from your own manifest, so a mismatch is a bug in a caller - most often a
manifest older than the code - and a 500 is what makes it show up in your
logs. Extra arguments may be ignored. Values that decode but break your
rules - an email that is not one - are the input being invalid: a 422 with
validationErrors, below.
Check the secret first, in constant time, and refuse before dispatch. This
endpoint runs functions by name with none of your routing in front of it;
hash_equals('', '') is true in PHP and its equivalents elsewhere, so an
unconfigured secret has to be rejected before the comparison rather than
trusted to it. Better still, do not register the endpoint at all when no
secret is configured — absent, not open.
Answer the previous secret too, while RSC_HOST_CALL_SECRET_PREVIOUS is
set. That is how the secret rotates without a refused call: the backend takes
the new one and the old, the renderers move to the new one, then the old is
removed (rotating one). Compare it the same way, unset
matching nothing, and never send it.
The reply
JSON, and the fields keep the outcomes apart so the renderer never reads a message to tell an invalid form from a broken server:
{ "result": [ … ], "revalidate": ["orders"] }| you want to say | status | fields |
|---|---|---|
| here is the answer | 200 | result |
| …and the action made these regions stale | 200 | result, revalidate: ["orders", "page"] |
| the input is invalid | 422 | validationErrors: { "email": ["…"], "address.city": ["…"] }, error |
| there is no session | 401 | unauthenticated: true, error |
| there is one, and still no | 403 | unauthorized: true, error |
| go somewhere else | 200 | redirect: "/login", and redirectStatus when you mean something other than 307 |
| refused, with its own status | that status | error (shown to the visitor), refusalStatus: 429 (any 4xx or 5xx: a 503 while a dependency is down) |
| refused, with something to act on | that status, 409 by default | error (shown to the visitor), refusalStatus, refusalData: { "blockers": [ … ] } |
| the function failed | 500 | error, and in development debug |
What each becomes on the other side: a redirect resolves the browser’s call
with { redirected } after the navigation starts, which is why every generated
stub is typed Promise<T | Redirected>. validationErrors reaches the form
that submitted, each message under its input, dot-joined for a nested field
and under "" for a message about the form itself. unauthenticated and
unauthorized become the engine’s own ServerAuthenticationError and
ServerAuthorizationError, so a page answers 401 or 403 the way it would
have if a JavaScript guard had thrown them; in an action, each is the
result’s serverError with your error as written. A refusalStatus makes
error a message for the visitor, with data or without: the page answers that
status, an action shows it, and a 404 is the not-found page on a page and the
message in an action, a generated stub’s included. Leave it out of
a failure, whose message stays in your logs. redirect travels the path every
other redirect travels — a real 3xx above a Suspense boundary, a digest below
one. revalidate names sections or page, and the answer
to the action carries the re-rendered region with it rather than the browser
being told to ask again.
Two things that are easy to get wrong:
A redirect is a 200. An HTTP client follows a 3xx transparently, so a real
one here would send the host call itself to the destination and hand whatever
it found back to the render as the function’s result. The redirect’s own
status goes in redirectStatus; without it the renderer uses 307, which keeps
the method. Send it whenever your framework says something else - Laravel’s
redirects are 302, so the Laravel package always sends it.
Refusing is not failing. A form filled in wrongly is the ordinary case, and
validationErrors is checked before error — a reply carrying both is read as
a refusal with fields, not a failure with none. Reserve error alone, with a
500, for the thing the visitor did not cause.
Say where it failed, in development only. A 500 may carry debug: the
thrown type, its message, and frames newest first.
{ "error": "boom", "debug": { "type": "RuntimeException", "message": "boom",
"trace": ["app/Rsc/Orders.php:42 App\\Rsc\\Orders->recent()", "…"] } }The renderer puts it on the error the render sees, as its cause and under
its stack, so a failed rpc() points at the line of your backend that failed,
not only at the JavaScript that called it. Send it only when the app is in
development - Laravel’s app.debug, Go’s CallbackHandler.Debug - never in
production, where it would name your files to whoever caused the error, and
never with a refusal, which is an answer and not a bug.
In development, a server action that fails this way opens Vite’s error overlay
in the browser: the type and message as its heading, the first frame not under
vendor/, node_modules/ or pkg/mod/ as its file, and the rest beneath. A
frame is easiest to read as path:line followed by what was running there.
Batches
Calls issued in the same tick of a render — sibling components each awaiting
rpc() — arrive as one POST, so a page’s parallel reads cost you one request
rather than one each:
{ "calls": [ { "function": "Orders.recent", "args": [5] }, { "function": "Me.profile", "args": [] } ] }Answer as each call finishes: Content-Type: application/x-ndjson, one
JSON line per call, carrying its index in the batch, the status it would
have had alone, and the reply — in whatever order the calls complete, flushed
as they do:
{ "index": 1, "status": 401, "unauthenticated": true }
{ "index": 0, "status": 200, "result": [ … ] }That is what keeps a page’s boundaries streaming independently after their
reads travelled together: the renderer resolves each call the moment its
line lands, so a component waiting on a fast read paints while a slow
sibling’s is still running. The Go module runs the calls concurrently and
writes each as it returns; Laravel runs them in order and flushes after each.
Set X-Accel-Buffering: no so a proxy in front does not hold the lines back.
A backend that would rather answer the whole batch at once may: one JSON
object of replies, one per call in order, each with its status:
{ "replies": [ { "status": 200, "result": [ … ] }, { "status": 401, "unauthenticated": true } ] }The renderer reads either. The saving of the batch is the same; with the whole-batch form every call in it waits for the slowest.
Either way, run every call and answer every one — a refusal in the second is
that call’s answer, not a reason to leave the third out. Each call’s
revalidate stays with that call. Batches never mix visitors; every call in
one carried the same forwarded headers.
At most 50 calls. The renderer never sends more in one batch; a page with more is split. Refusing a larger one - 413, before running anything - is a safe limit, and Laravel’s.
Batches are not optional. The renderer always sends calls from the same tick together, and an answer that is neither form - whatever its status - fails every call in the batch with what your backend said. None is sent again one by one: they may have run, and an action run twice is worse than one reported as failed. The conformance suite checks batches, so a backend that passes it takes them.
Route middleware
A middleware.ts beside or above a page may name guards in your vocabulary:
export const middleware = ['auth', 'can:manage-users']Only the names, no default export: the engine’s own guards are a
middleware.ts default export, a function it runs itself, and a file may
carry either or both. (route.ts may carry the names too, from before
middleware.ts could.)
The renderer does not know what those mean. Before anything at or below that directory renders — including a page frozen at build time, before the file is served — it calls the reserved function with the list:
{
"function": "__rsc.middleware",
"args": [
["auth", "can:manage-users"],
{ "url": "https://app.example.com/users/7/edit?tab=roles", "params": { "user": "7" } }
]
}The second argument is the page being asked about, because the call is
not it: a guard run against the POST to /__rsc/host-call checks a signature
on the endpoint’s url, and finds no {user} to authorize against. url is
what the visitor asked for, under the public host and scheme when a proxy
forwarded them, or null during a build. params holds only the values the
route’s own segments bound - never the query, so ?user=8 cannot stand in for
{user} - with a catch-all’s parts joined by /. Run the guards as if that
were the request. A backend that ignores the argument still works for guards
that read only the session.
One request asks once. A page the renderer looks for in its store and then renders is still one visit to the guards, so a throttle counts it once.
Answer { "result": true } to let the render go ahead. Anything else is a
refusal: false, null, a string, an object, a 4xx, a connection error.
The engine reads the literal true and nothing else, so a guard that aborts,
redirects or simply throws keeps the page from rendering rather than being
read as silence. Refuse with the fields above — unauthenticated when there
is no session, redirect to send them to sign in, refusalStatus for a
throttle’s 429 or a 503 during maintenance — and the page answers accordingly,
with the status and the error message. Only a deliberate refusal carries a
refusalStatus: a crash leaves it out and is answered 500.
Run them in order, outermost first, and stop at the first refusal: an outer
guard saying no means the inner one should never have been asked. An empty
list passes - { "result": true }: it is what the renderer’s health check
asks, to prove the backend answers without running anything.
Saying data changed
A section names the data it shows:
export default section('repos', Repos, { refreshOn: ({ params }) => [`team:${params.team}:repos`] })and your backend says when that changed, from a webhook or a job as much as an action. Every open tab showing it refreshes, with nothing polling. Two things to provide:
A way to say a name changed, callable from anywhere in your backend. It moves the name’s version to the larger of one past where it was and the current time in milliseconds - so a version never comes round again, and an old name can be deleted at any time - kept somewhere every instance of your backend shares - a cache, a table - since a webhook lands on whichever instance the balancer picked. A name never changed is at 0.
The reserved function __rsc.changed, asked with what a watcher holds and
how long it would wait:
{ "function": "__rsc.changed", "args": [{ "since": { "team:1:repos": 3, "team:1:members": 0 }, "wait": 5000 }] }Answer { "result": { "versions": { ... } } } with every name in since
whose version differs now, and nothing else - an empty object when none
does. If you can, hold the call up to wait milliseconds for one to move
and answer the moment it does: that is what makes the refresh immediate.
The renderer asks with 5 seconds; hold no longer than wait, and never past
30 seconds, where the renderer gives up on any call. A name you have never
seen is at 0, compared like any other: held while the asker also holds 0,
answered the moment it is changed. If
you cannot - PHP-FPM, a worker that must answer and go - answer at once; the
renderer asks again on its interval, a couple of seconds apart. Both are
conformant, and the page is the same.
The renderer asks once per process for every open tab it holds, never once per tab, so the cost to you is one small call per interval per renderer. A tab may only watch names its page was rendered with: the renderer signs them, so no authorization is needed here beyond the secret.
A purge, when a CDN keeps pages. A revalidate page goes out with the
Cache-Tag of every cache() answer it used, and the names you change are
those tags. A change you make never passes through the renderer, so when
CDN_PURGE_URL is set, your backend tells the CDN itself: after the
version has moved - after the transaction commits, and after the call has
answered if you can - post
{ "tags": ["team:1:repos"] }to that url, Content-Type: application/json, at most 100 tags a call, each
at most 1024 bytes. It needs no token. Only a 202 means it was accepted. A
429 may be tried once more after its Retry-After; anything else is logged
and never fails the change, since the CDN drops its copy at its max-age in CDN-Cache-Control anyway.
Without the variable, do nothing.
Server actions
A "use server" function the browser can call is a name the renderer forwards
to you. Write rsc-host.json at the project root, beside vite.config.ts:
actions maps the JavaScript name to whatever your side dispatches on, and
functions lists every name rpc() may call.
{
"actions": { "ordersCancel": "Orders.cancel", "profileUpdate": "Profile.update" },
"functions": ["Orders.cancel", "Orders.recent", "Profile.update"]
}A function can also carry its types, so the app’s rpc() and the stubs are
typed: types maps a name to its positional params, how many trailing ones
are optional, a variadic rest, and its result, each a JSON Schema;
defs holds the named object types they refer to by "$ref": "#/defs/Name".
"types": { "Orders.recent": { "params": [{ "type": "integer" }], "result": { "type": "array", "items": { "$ref": "#/defs/Order" } } } },
"defs": { "Order": { "type": "object", "properties": { "id": { "type": "integer" } }, "required": ["id"] } }A function taking one object with properties can be a form with no
schema, read from these same
types: required, format (email, date), minLength, maxLength,
minimum, maximum and enum become its fields and browser checks. The
properties are drawn in the order written. If your language’s JSON sorts a map,
say the order with "x-order": ["name", "email"] beside them.
The build writes server-actions.generated.ts in the source directory
exporting each action, so a client component imports ordersCancel and
calls it, and types rpc()’s first argument with the functions. Have Vite
run the command that writes it, rscKit({ hostManifest: { command } }), so
it cannot go stale: a stale one names a method since renamed, and nothing
fails until the browser calls it. Laravel’s rsc:host-manifest is this
step; a Go registry’s WriteManifest writes the same file.
Checking a form before it is submitted
<Form> asks whether a field would pass before the form is sent, and an
action whose validation runs before its body can answer without running.
List those functions in rsc-host.json - a function not listed is never sent
a check, because a backend that has never heard of one would run the call:
"validates": ["Profile.update"]The check is an ordinary call with validate beside its args, never in a
batch: the fields to check, * matching one segment of a dotted name, and an
empty list meaning every field.
{ "function": "Profile.update", "args": [{ "email": "taken@example.com" }], "validate": ["email"] }Run what would refuse the call - authentication, authorization, validation,
limited to those fields - and stop there. Fields that pass answer
{ "result": null }; fields that do not answer the 422 with
validationErrors a submit would. Nothing may be written. Any
other refusal is no verdict on the fields, and the form shows nothing for it.
Laravel does this for a function whose first parameter is a form request, with Precognition’s own rule filtering.
A message for the next page
useFlash() on the page shows what an action leaves for the next one. Your
side leaves one by setting a cookie on the reply, the way a login does: named
rsc-flash, its value a URI-encoded JSON list of { "message", "kind" } -
kind one of success, error, info, warning - with Path=/, a short
Max-Age and SameSite=Lax.
Set-Cookie: rsc-flash=%5B%7B%22message%22%3A%22Saved.%22%2C%22kind%22%3A%22success%22%7D%5D; Path=/; Max-Age=60; SameSite=LaxThe browser reads it, so it is never HttpOnly and never encrypted - Laravel’s
Rsc::flash() exempts it from EncryptCookies. A message the visitor’s cookie
still carries goes first: append to the list, do not replace it.
Urls you own
The renderer forwards any url the route tree does not own — /login, a
webhook, an uploaded file — to RSC_BACKEND, with X-Forwarded-Host and
X-Forwarded-Proto set and the header x-rsc-renderer-fallback: 1. Trust
the renderer as a proxy so your absolute urls come out against the public
origin.
If your application also proxies to the renderer — sitting in front of it,
the way Laravel does with RSC_RENDERER_URL — two things keep a url neither
side owns from bouncing between you forever:
- Set
x-rsc-proxied-by-backend: 1on what you forward. The renderer answers 404 itself instead of handing it back. - When a request arrives carrying
x-rsc-renderer-fallback, answer 404 for anything you do not route. It has already been through the renderer’s table.
Whichever process faces the internet, the host-call endpoint must not: restrict it at the web server, bind the listener to loopback, or serve it on a unix socket. The secret is the layer the protocol guarantees; the network is the one it cannot.
What the renderer expects of you
- Answer within 30 seconds. A render blocked on a host that never answers
is a hung request, and the renderer gives up at 30s (
timeoutMsonhttpHostCalls, for a host that embeds the engine itself). - Starting after the renderer is fine. A refused connection is tried again
for up to 2 seconds, because a refused connection means the call never
reached you, so nothing runs twice. This covers a backend started beside
the renderer in one container, still coming up when the first page renders.
Nothing else is retried: a timeout or a reset may have run the call
(
refusedRetryMsonhttpHostCalls; 0 turns it off). - One process is not enough if you proxy. A server that proxies a page
to the renderer holds a worker for the whole render, and the render calls
back to that same server for its data. With one worker, nobody is left to
answer. Laravel refuses
php artisan servefor exactly this. - A panic is one failed call. Recover it into a 500 with
error; the other renders in flight should survive it. - Serialise what you return as JSON. Where your manifest gives a
function a type, what you send must fit it: an empty list is
[], nevernull; a time is an ISO 8601 string.
Before you ship: the conformance suite
An adapter is ready when it passes rsc-kit’s conformance suite - all of it.
Every bug found at this boundary so far was a difference between how a
backend and the engine read the wire - a nil list sent as null where the
type said a list, a timestamp typed unknown, a refusal that did not arrive
as the error a page checks for - and each is a case in the suite. The Laravel
and Go adapters run it in CI on every change, against rsc-kit’s main.
Register these functions in your backend, written with your adapter’s ordinary API, the way an app would write them:
| Function | Must |
|---|---|
Conformance.echo |
return its one argument unchanged |
Conformance.emptyList |
return an empty list, the way your language says “no rows” |
Conformance.time |
return 2026-01-02T03:04:05Z as your language’s time value |
Conformance.noTime |
return an absent time |
Conformance.unauthenticated |
refuse as not signed in |
Conformance.unauthorized |
refuse as not allowed |
Conformance.notFound |
refuse as not found (404) |
Conformance.refuse |
refuse with 429 and “Slow down.” |
Conformance.invalid |
refuse the input, on the field name |
Conformance.invalidNested |
refuse the input, on address.city and on the form itself, under "" |
Conformance.redirect |
send the visitor to /login |
Conformance.revalidate |
mark orders stale and return "ok" |
Conformance.fail |
fail with an ordinary error |
Conformance.double |
take one integer and return it doubled; anything else fails it |
Conformance.authorization |
return the forwarded Authorization header |
Conformance.cookie |
return the forwarded Cookie header |
Conformance.login |
set a cookie named conformance_login on the response, and return "ok" |
Conformance.flash |
leave the one-time message "Saved." ("success") for the next page, after any the visitor’s rsc-flash cookie still carries, and return "ok" |
Conformance.change |
say conformance:changed changed, as your webhook would, and return "ok" |
Then Conformance.ip, returning the visitor’s address as your request
reports it. And four guards: conformance-allow, which passes,
conformance-deny, which refuses, conformance-redirect, which sends the
visitor to /conformance-login, and conformance-page, which passes only when
the page it is asked about is /conformance/orders/7 with {order} bound to
"7". Then serve them and run:
Start it with CDN_PURGE_URL=http://127.0.0.1:8790/, where the suite
listens for its purges, and RSC_HOST_CALL_SECRET_PREVIOUS=old, then:
npx -y -p @rsc-kit/core rsc-kit-conformance \
--endpoint http://127.0.0.1:8123/__rsc/host-call --secret test \
--previous-secret old --manifest rsc-host.json --purge-port 8790It checks the whole contract on this page:
- values - every JSON shape unchanged,
[]for no rows, ISO 8601 times, arguments decoded to their types, and every value against the type your manifest declares; - outcomes - each refusal as the engine’s own error, field errors with
dotted paths and the form’s under
"", redirects, revalidation staying with its call, a crash staying a failure, and arguments that do not fit failing rather than refusing; - forms - a function taking one object, its fields in order with the hints a browser can check, and a refusal landing on its field;
- the request -
CookieandAuthorizationforwarded, the visitor’s address in place of the renderer’s, a cookie set by a call reaching the page, no secret or the wrong one refused with 403, the previous one answered whileRSC_HOST_CALL_SECRET_PREVIOUSnames it (so a rotation fails no call; without--previous-secretthis fails), an unknown function 404, a malformed body 400; - batches - every call answered, a refusal only its own, and more than 50 refused with 413 before any runs;
- guards - in the order named, stopping at the first that does not pass, a redirect from one, a name nobody registered refusing, and a guard reading the page it is asked about rather than the call;
- live data - a name never changed at 0, a change moving it to a time in
milliseconds that never comes round again, only the names that differ
answered, and a held call bounded by
wait; - purges - a change posted to
CDN_PURGE_URLas its tag, as JSON, only once the version has moved. Without--purge-portthese fail: every adapter purges. - debug - with
--debug, for an adapter started with its debug on, a failure carryingdebugwith a type, a message and at least one frame. Without the flag it is not checked: a backend sends a trace only in development.
It exits non-zero on any failure, so it can gate your CI. The Go adapter’s
cmd/conformance and Laravel’s tests/Conformance are working fixtures to
copy.
The imports for adapter authors
An app never imports these. An adapter written in JavaScript, or a host that embeds the engine, does:
@rsc-kit/core/adapter/host-calls:httpHostCalls, the renderer’s side of this protocol, and theHostCallReplyand batch types it reads.@rsc-kit/core/adapter/conformance:runConformanceandreport, the suite above as a function, for a test runner that drives it itself.@rsc-kit/core/adapter/manifest:RouteManifest, the type of theroutes.jsonthe build writes, for a backend that registers the app’s urls as routes of its own.
Proposing an adapter
rsc-kit standardises on adapters: a backend in a language rsc-kit has none for gets one, rather than a second way to reach it. To propose one, open a discussion or a pull request on rsc-kit/rsc-kit. To be adopted, an adapter:
- passes the whole conformance suite, in its own CI, against rsc-kit’s main on every change - not a subset, and not with cases skipped;
- registers the fixtures with its ordinary API, the way an app would;
- covers everything on this page, live data included -
__rsc.changed, a way to say a name changed, a store every instance shares, and the purge.
Testing it without the renderer
The contract is plain HTTP, so a backend’s own test suite can cover it
without a JavaScript process: POST the request shape, assert the reply
shape. Laravel’s Pest suite does this; the Go adapter’s go test does the
same. The end-to-end proof — a real page rendered with data from your
process — lives with the engine, which is where a rendering regression can be
caught.