@rsc-kit/mcp 0.27.0 → 0.28.0

package/guides/api-routes.md

@@ -215,8 +215,10 @@ export const GET = events(async function* ({ params, signal }) {
 
 An ordinary `route.ts`, so everything above applies: it lives beside its
 pages, runs the `middleware.ts` above it, takes the same params. `events()`
-frames each yield as JSON, sends a keepalive so a proxy does not drop an idle
-stream, sets `text/event-stream` and `no-store`, and ends the generator when
+frames each yield as JSON, sends a keepalive every eight seconds so nothing in
+front drops an idle stream ([`RSC_STREAM_KEEPALIVE_MS`](/hosts/deployment#streams-and-idle-timeouts)
+to change it), sets `text/event-stream` and `no-store, no-transform`, is never
+compressed, and ends the generator when
 the browser goes away — that is what `signal` is for. `named(event, data, {
 id })` names a message or gives it an id, for a client that listens by name or
 resumes after a reconnect.

package/guides/deployment.md

@@ -160,6 +160,75 @@ names the stylesheet and the entry. Nothing to configure, and nothing it
 replaces: the stylesheet still blocks paint, and inlining critical CSS
 stacks on top of it.
 
+## Streams and idle timeouts
+
+An `events()` route and the [`refreshOn`](/guides/sections#refreshing-on-a-change-from-outside)
+stream hold a connection open and are quiet most of the time. Anything in
+front that closes a quiet connection - the server's idle timeout, a proxy's
+read timeout - would cut them, so each sends a keepalive line every **eight
+seconds**: under Bun's default ten, and well under nginx's sixty and
+Cloudflare's hundred.
+
+If something in front closes idle connections sooner, set the keepalive
+below it:
+
+```sh
+RSC_STREAM_KEEPALIVE_MS=4000   # under a 5-second idle timeout
+```
+
+Too long a keepalive does not lose anything - the browser reconnects, and a
+tab catches up on whatever moved - but every open tab is cut and reopens each
+time the timeout passes. Both streams are sent with `Cache-Control: no-store,
+no-transform` and are never compressed, so nothing in front buffers them.
+
+## Secrets
+
+rsc-kit reads up to three. Each is its own key for its own job - never reuse
+one as another, so one leaking does not hand out the rest.
+
+| Variable | What it protects | Who needs it | Read by |
+| --- | --- | --- | --- |
+| `RSC_HOST_CALL_SECRET` | calls between the renderer and a Go or Laravel backend | an app with a backend - required | the renderer **and** the backend |
+| `RSC_SIGNING_SECRET` | the names a page hands a tab for [`refreshOn`](/guides/sections#refreshing-on-a-change-from-outside) | an app that uses `refreshOn` - required in production | the renderer |
+| `RSC_ACTION_ENCRYPTION_KEY` | values a server action sends through the browser, [across a deploy](#server-actions-across-a-deploy) | optional | the renderer, from the build |
+
+`bun create rsc-kit` and `rsc-kit init` generate the first two into `.env` for
+an app with a backend, and `php artisan rsc:install` does the same for
+Laravel. That is development. For production, generate each once and keep it
+where you keep secrets - your platform's environment settings, not the repo:
+
+```sh
+openssl rand -base64 32
+```
+
+or, without openssl:
+
+```sh
+node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
+php -r "echo base64_encode(random_bytes(32)), PHP_EOL;"
+```
+
+Three rules apply to all of them:
+
+- **The same value on every instance.** Each is checked by a process that may
+  not be the one that issued it: a tab served by one renderer, a call landing
+  on another backend replica. A value per instance fails for some requests and
+  not others.
+- **At runtime, from the environment.** The built server reads them when it
+  starts, so one build deploys anywhere. `RSC_ACTION_ENCRYPTION_KEY` is the
+  exception: set it at build time too.
+- **Never in git.** The scaffold's `.gitignore` already leaves out `.env`.
+
+**Rotating one** is a deploy, and each says so differently:
+
+- `RSC_HOST_CALL_SECRET` - the renderer and the backend must change together.
+  Between the two, every `rpc()` is refused, so deploy both at once.
+- `RSC_SIGNING_SECRET` - pages already open hold names signed with the old
+  key; their watching is refused and they stop refreshing until reloaded.
+  Nothing else breaks.
+- `RSC_ACTION_ENCRYPTION_KEY` - an action called from a page loaded before the
+  change fails, the same window as a deploy without the key pinned.
+
 ## Pages across a deploy
 
 A page from the previous build asks for a payload from the new one, whose

package/guides/go.md

@@ -34,7 +34,7 @@ server in production:
 
 ```ini title=".env"
 RSC_BACKEND=http://127.0.0.1:8080
-RSC_HOST_CALL_SECRET=a-long-random-string
+RSC_HOST_CALL_SECRET=… # openssl rand -base64 32 - see Secrets under Deployment
 ```
 
 And the endpoint, on whatever mux you already have:
@@ -285,7 +285,8 @@ reg.Names(&rsckit.SQLTags{DB: db, Placeholder: rsckit.Dollar})   // Postgres; ni
 ```
 
 Anything with a `Bump` and a `Versions` fits. Set `RSC_SIGNING_SECRET` for the renderer, the same on every instance:
-it signs the names a page hands the tab, and is not the host-call secret. [Sections](/guides/sections#refreshing-on-a-change-from-outside)
+it signs the names a page hands the tab, and is not the host-call secret.
+Generating and rotating both: [Secrets](/hosts/deployment#secrets). [Sections](/guides/sections#refreshing-on-a-change-from-outside)
 has the whole picture.
 
 ## Production

package/guides/laravel.md

@@ -356,29 +356,42 @@ server's. PHP answers the renderer's ask at once rather than holding it, so
 a change reaches the tab on the renderer's next ask, a couple of seconds
 later. Set `RSC_SIGNING_SECRET` for the renderer, the same on every instance:
 it signs the names a page hands the tab, and is not the host-call secret.
+Generating and rotating both: [Secrets](/hosts/deployment#secrets).
 
-**Watching without PHP.** By default the renderer asks PHP which versions
-moved, every couple of seconds while any tab is watching. Keep the versions in
-the `rsc_versions` table instead and the renderer reads them itself:
+**What watching costs PHP.** The renderer asks Laravel which versions moved
+once for every tab it serves, not once per tab: one request about every two
+seconds per renderer process while any tab is watching, each a cache read.
+Three renderers are one or two small requests a second for the whole fleet.
+That is the default and the recommendation - Laravel stays the only thing
+that talks to its database.
+
+**Keeping versions in a table** (`RSC_VERSIONS=database`) is for when you
+want them in the database rather than the cache: pruned on a schedule with
+`rsc:prune-versions`, or written by something outside Laravel - a Go service,
+a worker in another language - through the [shared table](/guides/sections#the-table).
+Laravel still answers the renderer from it; nothing else changes.
 
 ```sh
 php artisan vendor:publish --tag=rsc-migrations && php artisan migrate
 RSC_VERSIONS=database
 ```
 
-```ts title="src/instrumentation.ts"
-import { installVersionSource, postgresVersions } from '@rsc-kit/core/changed'
-import postgres from 'postgres'
+**Instant, with broadcasting.** If the app has Laravel's broadcasting set up
+(`php artisan install:broadcasting`) with a server that speaks the Pusher
+protocol - Reverb, Pusher, Soketi - each `Rsc::changed()` can announce itself,
+and the renderer asks the moment it hears:
 
-export function register() {
-  installVersionSource(postgresVersions(postgres(process.env.DATABASE_URL!)))
-}
+```sh
+RSC_BROADCAST=true                      # Laravel: announce every change
+RSC_BROADCAST_URL=wss://ws.example.com  # the renderer: where to listen
+RSC_BROADCAST_KEY=your-app-key          # the renderer: the server's app key
 ```
 
-Watching then costs PHP no requests, and on Postgres `Rsc::changed()` sends a
-NOTIFY, so tabs hear it at once. On MySQL use `sqlVersions` with your driver;
-the renderer reads the table once a second. [Sections](/guides/sections#refreshing-on-a-change-from-outside) has the
-whole picture.
+A change then reaches the tabs at once, and between changes the renderer asks
+only every thirty seconds, as a safety net. The announcement carries nothing -
+the channel is public, and names may be one visitor's - so Laravel still
+answers which names moved, and the renderer never touches the database. It is
+sent after the transaction commits.
 
 ## Route middleware