@rsc-kit/mcp 0.27.1 → 0.28.1

package/guides/sections.md

@@ -68,466 +68,10 @@ slots the calling page does have.
 
 ## Refreshing on a change from outside
 
-An action can say what it changed because it is the thing changing it. A
-webhook, a job finishing in a worker, another visitor's action - none of
-those is in the tab that is showing the data. For those a section says what
-it depends on, by name:
-
-```tsx title="src/app/t/[team]/repos.section.tsx"
-export default section('repos', Repos, {
-  refreshOn: ({ params }) => [`team:${params.team}:repos`],
-})
-```
-
-and whatever changes the data says so, from wherever it is:
-
-```ts title="src/app/api/github/webhook/route.ts"
-import { changed } from '@rsc-kit/core/changed'
-
-export async function POST(request: Request) {
-  const { team, repos } = await request.json()
-  await saveRepos(team, repos)
-  await changed(`team:${team}:repos`)
-  return new Response(null, { status: 204 })
-}
-```
-
-Every open tab showing the section refreshes it - the same refresh as above,
-with nothing polling and no client code. `refreshOn` is a list of names, or a
-function of the section's props - the page's `params` and `searchParams` -
-that makes them. A page can declare its own with `export const refreshOn`,
-and a change refreshes the page as `refresh('page')` does.
-
-The function runs per request, so it can read the request - a name for the
-person signed in is the usual one on a dashboard:
-
-```tsx title="src/app/dashboard/page.tsx"
-import { cookies } from '@rsc-kit/core/request'
-
-export const refreshOn = async () => [`inbox:${(await cookies()).get('agent')?.value}`]
-```
-
-That is the whole feature for an app that is only JavaScript. With a Go or
-Laravel backend the backend says it instead -
-[`reg.Changed(ctx, …)`](/hosts/go#saying-data-changed) or
-[`Rsc::changed(…)`](/hosts/laravel#saying-data-changed) - and the page is the same.
-
-### How a tab finds out
-
-Each name has a version, a number that moves when something says the name
-changed. Nothing else travels - not what changed, not the data.
-
-1. The page renders, reads the version of each name it shows, and hands them
-   to the tab, signed.
-2. The tab opens one stream, `/_rsc/changes`, for every name on the page. Only
-   a page with `refreshOn` opens one, and only while the tab is visible.
-3. The server asks where the versions live - "which of these differ from what
-   I hold?" - once for every open tab it is serving, and again on an interval.
-4. When a version has moved, the stream says so in one line, and the tab asks
-   for exactly the sections showing that name, the way `refresh('repos')` does.
-
-A name belongs to the data, not to a section or a page. Any number of
-sections, on any number of pages, can refresh on the same name: one
-`changed('team:1:repos')` moves its version once, and every open tab showing
-any of them refreshes the ones it has. Section *names* are separate - two
-pages may both have a section called `stats`; each is resolved through its own
-page, and a shared render is never handed from one page to the other.
-
-The data is never pushed: the section is rendered fresh, through its own
-queries and its own guards, as any refresh is. That is also why this runs
-on a Worker - the stream holds no state, and a version is a read.
-
-### Where the versions live
-
-**One server, no backend:** in that server's memory. Nothing to set up - but
-in production rsc-kit says so in its log, once, because the same default
-fails silently the moment there are two instances. If the deploy really is
-one instance, say so and the warning goes:
-
-```ts title="src/instrumentation.ts"
-import { installVersionSource, memoryVersions } from '@rsc-kit/core/changed'
-
-export function register() {
-  installVersionSource(memoryVersions())   // one instance, on purpose
-}
-```
-
-**More than one instance, or a worker process:** this is the case to
-plan for. In-memory versions fail silently the moment a load balancer adds a
-second instance - a change made on one never reaches the tabs held by the
-other - and a job finishes in a process that serves no pages at all. Keep
-the versions somewhere they all share - any database you already have, through
-the client you already use. rsc-kit ships no driver; you hand it yours:
-
-| Your database | The store | Another instance's change arrives |
-| --- | --- | --- |
-| Postgres, with postgres.js or `Bun.sql` | `postgresVersions(sql)` | at once with postgres.js; within a second with `Bun.sql` |
-| Postgres, with another client | `sqlVersions({ query, placeholder: (n) => '$' + n })` | within a second |
-| MySQL, MariaDB | `sqlVersions({ query })` | within a second |
-| SQLite, libSQL, Turso, D1 | `sqlVersions({ query })` | within a second |
-| Redis | `createVersions({ read, bump, listen, notify })` | at once, through pub/sub |
-| An ORM: Drizzle, Prisma, Kysely, Knex | `createVersions` over its query builder, or `sqlVersions` over its raw query | as its database |
-
-`sqlVersions` takes your driver as one function of SQL text and parameters,
-and writes plain SQL every dialect has - a select, an update, an insert:
-
-```ts title="src/versions.ts"
-import { sqlVersions } from '@rsc-kit/core/changed'
-
-// MySQL, mysql2
-export const versions = sqlVersions({ query: async (text, params) => (await pool.query(text, params))[0] })
-
-// SQLite, bun:sqlite or better-sqlite3
-export const versions = sqlVersions({ query: async (text, params) => db.query(text).all(...params) })
-
-// libSQL / Turso
-export const versions = sqlVersions({ query: async (sql, args) => (await client.execute({ sql, args })).rows })
-```
-
-and with postgres.js it is one line:
-
-```ts title="src/versions.ts"
-import postgres from 'postgres'
-import { postgresVersions } from '@rsc-kit/core/changed'
-
-export const sql = postgres(process.env.DATABASE_URL!)
-export const versions = postgresVersions(sql)
-```
-
-A SQLite file is shared by the processes on one machine - a web server and a
-worker on the same box. Instances on several machines need a database they
-all reach over the network. The table every one of these reads is described
-[below](#the-table).
-
-postgres.js can LISTEN, so a change on one instance reaches the tabs on every
-other at once. `Bun.sql` works too, without LISTEN: a waiting server reads the
-table once a second, so a change from another instance takes up to a second -
-unless a second, listening connection wakes it (below).
-
-**Any database, any ORM, or no SQL at all.** rsc-kit needs three things from
-your storage - read some versions, move some versions, and, if it can,
-say the moment one moved - and does the comparing, waiting and waking itself.
-`createVersions` takes exactly those:
-
-With Drizzle, use its query builder rather than raw SQL - the table is one
-more table in your schema:
-
-```ts title="src/db/schema.ts"
-import { bigint, pgTable, text } from 'drizzle-orm/pg-core'
-
-export const rscVersions = pgTable('rsc_versions', {
-  name: text('name').primaryKey(),
-  version: bigint('version', { mode: 'number' }).notNull(),
-})
-```
-
-```ts title="src/versions.ts"
-import { inArray, sql } from 'drizzle-orm'
-import { createVersions } from '@rsc-kit/core/changed'
-import { db } from './db'
-import { rscVersions } from './db/schema'
-
-export const versions = createVersions({
-  read: async (names) =>
-    Object.fromEntries(
-      (await db.select().from(rscVersions).where(inArray(rscVersions.name, names)))
-        .map((row) => [row.name, Number(row.version)]),
-    ),
-  bump: async (names) => {
-    await db.insert(rscVersions)
-      .values(names.map((name) => ({ name, version: 1 })))
-      .onConflictDoUpdate({ target: rscVersions.name, set: { version: sql`${rscVersions.version} + 1` } })
-  },
-})
-```
-
-```ts title="Prisma"
-import { sqlVersions } from '@rsc-kit/core/changed'
-
-// Raw SQL through Prisma; the table is a model in its schema - see "The table" below.
-export const versions = sqlVersions({
-  query: (text, params) => prisma.$queryRawUnsafe(text, ...params),
-  placeholder: (n) => '$' + n,   // Postgres; leave out for MySQL and SQLite
-})
-```
-
-```ts title="Redis"
-import { createVersions } from '@rsc-kit/core/changed'
-
-const key = (name: string) => 'rsc:' + name
-
-export const versions = createVersions({
-  read: async (names) => {
-    const values = await redis.mget(names.map(key))
-    return Object.fromEntries(names.map((name, i) => [name, Number(values[i] ?? 0)]))
-  },
-  bump: async (names) => { await Promise.all(names.map((name) => redis.incr(key(name)))) },
-  // Instant across instances: a subscriber connection hears every bump.
-  listen: (wake) => subscriber.subscribe('rsc:versions', wake),
-  notify: () => redis.publish('rsc:versions', ''),
-})
-```
-
-`sqlVersions({ query })` takes any SQL driver as a function of text and
-parameters - node-postgres, mysql2, Kysely, Knex, D1 - and `createVersions`
-takes anything else.
-
-Install it in every process - the web server once, before the first request.
-`register()` also runs during the build, and that is fine: a store opens no
-connection until a tab is actually waiting on it, and postgres.js connects
-lazily, so a build never holds one open. Keep anything that connects eagerly
-out of `register()`, or the build waits on it and never exits.
-
-
-```ts title="src/instrumentation.ts"
-import { installVersionSource } from '@rsc-kit/core/changed'
-import { versions } from './versions'
-
-export function register() {
-  installVersionSource(versions)
-}
-```
-
-and the worker, which then says what it finished:
-
-```ts title="worker.ts"
-import { changed, installVersionSource } from '@rsc-kit/core/changed'
-import { versions } from './src/versions'
-
-installVersionSource(versions)
-
-queue.on('restoration.done', async (job) => {
-  await changed(`restoration:${job.id}`)
-})
-```
-
-Without `listen` and `notify` - MySQL, SQLite, or a driver that cannot listen -
-a waiting server reads the table every second instead (`poll` changes it).
-
-**From any process, without rsc-kit:** the table is the contract. A cron job,
-a service in another language, a database trigger - anything that can write
-to it can say a name changed:
-
-```sql
--- Postgres
-INSERT INTO rsc_versions (name, version) VALUES ('restoration:42', 1)
-  ON CONFLICT (name) DO UPDATE SET version = rsc_versions.version + 1;
-NOTIFY rsc_versions;   -- optional: wakes the listening servers at once
-
--- MySQL
-INSERT INTO rsc_versions (name, version) VALUES ('restoration:42', 1)
-  ON DUPLICATE KEY UPDATE version = version + 1;
-
--- SQLite
-INSERT INTO rsc_versions (name, version) VALUES ('restoration:42', 1)
-  ON CONFLICT (name) DO UPDATE SET version = version + 1;
-```
-
-A version only has to *change*; the servers compare, they do not count. Go's
-`SQLVersions` uses the same table, so a Go service and a JavaScript app can
-share one.
-
-**Instant across instances on a client that cannot LISTEN** - `Bun.sql`, or
-a Drizzle or Prisma setup over one: keep it for reading and writing, and open
-one postgres.js connection only to listen. It costs one idle connection per
-process:
-
-```ts title="src/versions.ts"
-import postgres from 'postgres'
-
-const listener = postgres(process.env.DATABASE_URL!, { max: 1 })
-
-export const versions = createVersions({
-  read,                                                     // as above, on your own client
-  bump,
-  listen: (wake) => listener.listen('rsc_versions', wake),
-  notify: () => listener.notify('rsc_versions', ''),
-})
-```
-
-### The table
-
-A shared store keeps one row per name. Your app owns the table: rsc-kit never
-creates, alters or migrates it at runtime - make it with your own migrations,
-in your own schema, with whatever your ORM calls these types. (Laravel ships
-one you publish into your own migrations, `--tag=rsc-migrations`; after that
-it is yours too.)
-
-| Column | Type | |
-| --- | --- | --- |
-| `name` | text, `PRIMARY KEY` (or a unique index) | the name a section refreshes on |
-| `version` | `BIGINT NOT NULL` | any integer; it only has to change |
-
-```sql
--- Postgres, SQLite
-CREATE TABLE rsc_versions (name TEXT PRIMARY KEY, version BIGINT NOT NULL);
--- MySQL: an indexed TEXT needs a length
-CREATE TABLE rsc_versions (name VARCHAR(255) PRIMARY KEY, version BIGINT NOT NULL);
-```
-
-- **Extra columns are fine** - an `updated_at`, say - as long as each has a
-  default: rsc-kit and the documented upserts write only `name` and `version`.
-- **Another name is fine:** `sqlVersions({ table })`, `postgresVersions(sql,
-  { table })`, Go's `SQLVersions{Table}`, Laravel's `RSC_VERSIONS_TABLE`.
-- **The NOTIFY channel** is `rsc_versions` whatever the table is called;
-  `postgresVersions(sql, { channel })` changes it.
-- The same table works for Go's `SQLVersions` and Laravel's
-  `RSC_VERSIONS=database`, so a JavaScript app, a Go service and a PHP job
-  can share one.
-
-### Say it after the write commits
-
-A tab that hears a name moved asks for its section at once. If the write
-that changed the data has not committed yet, that render reads the old data -
-and the tab is now at the new version, so it will not ask again until the
-next change. Inside a transaction, say it changed **after** the transaction,
-not inside it:
-
-```ts
-await db.transaction(async (tx) => {
-  await tx.insert(conversations).values(row)
-  // not here: this transaction may still roll back, and has not committed
-})
-
-await changed(`agent:${row.agentId}:conversations`)   // here
-```
-
-The same goes for a worker writing the table directly: in the same
-transaction as the data, or after it - never before. In Laravel,
-`DB::afterCommit(fn () => Rsc::changed(...))` does this inside a transaction.
-
-**With a Go or Laravel backend:** the backend keeps them - a table in Go, the
-cache in Laravel - and you install nothing here. The renderer asks the
-backend which moved: Go holds the question until one does; PHP cannot hold a
-request open, so Laravel is asked again every couple of seconds while any tab
-is watching. To take PHP out of watching altogether, keep Laravel's versions
-in the table (`RSC_VERSIONS=database`) and have the renderer read it itself -
-an app's own store always wins over the backend's:
-
-```ts title="src/instrumentation.ts"
-import { installVersionSource, postgresVersions } from '@rsc-kit/core/changed'
-import postgres from 'postgres'
-
-export function register() {
-  installVersionSource(postgresVersions(postgres(process.env.DATABASE_URL!)))
-}
-```
-
-Watching then costs PHP nothing, and `Rsc::changed()`'s NOTIFY reaches the
-tabs at once.
-
-### The signing secret
-
-The names a page hands the tab are signed, so a tab can only listen for the
-names its page was rendered with - a browser cannot make one up. Every
-instance has to sign with the same key, or a tab served by one is refused by
-the next and never refreshes:
-
-```sh
-RSC_SIGNING_SECRET=… # the same on every instance: openssl rand -base64 32
-```
-
-It is its own secret, with or without a backend - not the backend's
-`RSC_HOST_CALL_SECRET`, which authorises a different thing. In production, an
-app that uses `refreshOn` without it refuses to serve, saying what to set: a
-random key per instance would fail silently.
-
-That refusal comes on the first request, because on some platforms - Workers
-- the environment is only there once a request arrives. Under Kubernetes or
-any orchestrator with a readiness check, that is too late: the pod is already
-taking traffic. Make the deploy itself fail instead, from `register()`, which
-runs before the server takes a request:
-
-```ts title="src/instrumentation.ts"
-import { assertSigningSecret } from '@rsc-kit/core/changed'
-
-export function register() {
-  assertSigningSecret()   // throws in production without RSC_SIGNING_SECRET
-}
-``` In development a random key is
-fine, and is what you get.
-
-How to generate it, where to keep it, and what rotating it does:
-[Secrets](/hosts/deployment#secrets).
-
-Names are signed when the page is served, never at build: a page stored at
-build keeps everything else stored, and the part that carries the names is
-filled per request. So the build does not need the secret.
-
-### When nothing refreshes
-
-In development the browser console says what the page is watching, region
-by region, each time that changes:
-
-```
-[rsc-kit] refreshOn watching, by region:
-  repos: team:1:repos @3
-  page: inbox:ada @0
-```
-
-A region that declared `refreshOn` but is missing from that list rendered no
-names, and the server's log says why, once. And watching **stops while the
-tab is hidden** - a background tab holds no connection - which the console
-also says. Nothing is missed: shown again, the tab reconnects at the versions
-it holds and refreshes whatever moved meanwhile.
-
-### When many tabs show the same thing
-
-When a name moves, every tab showing it asks for its sections again - 500 tabs
-on one team's board are 500 renders. Each tab's render can differ by who is
-looking, so by default each is its own. A section that is the same for
-everyone allowed to see the page can say so:
-
-```tsx title="src/app/status/board.section.tsx"
-export default section('board', Board, { refreshOn: ['board'], shared: true })
-```
-
-Then the tabs asking because of the same change get one render between them:
-the first tab's request renders it, and every other gets the same bytes.
-Each tab's guards still run on its own request - a visitor who may not see
-the page is still refused - and only a refresh a change triggered is shared,
-so `refresh()` by hand, or after an action, always renders afresh.
-
-Never set `shared` on a section that shows anything per visitor - their name,
-their data, what they may do. The first tab's render is what every other tab
-is shown, `rpc()` calls included: they run with the first visitor's session.
-
-### What it costs
-
-- **Per tab:** one open connection while the page is visible, closed when the
-  tab is hidden and reopened when it is seen again. Idle, it carries a
-  keepalive line every eight seconds ([set it lower](/hosts/deployment#streams-and-idle-timeouts)
-  under a shorter idle timeout); a change is one line of about forty
-  bytes.
-- **Per change:** each tab showing the name asks for the sections that show
-  it, once, however many names moved together. That request is the size of
-  the section, not the page. A `shared` section renders once per change for
-  every tab; any other renders once per tab.
-- **On the server:** one ask of wherever the versions live, covering every tab
-  that server holds - a thousand open tabs are one query, not a thousand. The
-  ask may wait up to five seconds for a change: a database with `listen`, or a
-  Go backend, answers the moment a version moves; a table without it is read
-  once a second while the ask waits; Laravel answers at once and is asked again
-  two seconds later. Plus one small read when each tab opens its stream.
-
-Polling a section every two seconds instead costs a full render of it, per
-tab, every two seconds, whether anything changed or not. The trade is the open
-connection: cheap on Bun, Node and Workers; on a host that bills a function
-for every second it is open, it is a second billed for as long as the tab is.
-
-### Coming from Next.js
-
-This is where `revalidateTag` was, and it is not the same thing. Next's tags
-label entries in its Data Cache and `revalidateTag()` throws them away, so the
-*next request* refetches; an open tab learns nothing until it navigates.
-There is no data cache here - every render is fresh - so `refreshOn` names
-what is *on screen*, and `changed()` refreshes every open tab showing it, now.
-A port keeps its names: `tags: ['posts']` on the fetch becomes
-`refreshOn: ['posts']` on the section, and `revalidateTag('posts')` becomes
-`changed('posts')`.
-
-A name's version reveals only that something with that name changed. Do not
-put a secret in a name.
+An action refreshes the sections it changed. For a change made anywhere else -
+a webhook, a job, another visitor - a section can name what it depends on and
+refresh itself in every open tab: `section('repos', Repos, { refreshOn })`.
+That has its own guide: [Live data](/guides/live-data).
 
 ## The name is scoped to the module, not the app
 

package/guides/where-it-runs.md

@@ -44,6 +44,14 @@ change:
 nitro({ preset: 'vercel', serveStatic: 'inline' })
 ```
 
+## Streams on serverless platforms
+
+`events()` routes and `refreshOn` hold a connection open. On Workers and
+serverless functions each isolate or instance watches for its own tabs, a
+platform's request limits cut streams (they reconnect and catch up), and
+versions must live in a shared store. [On Workers and serverless](/guides/live-data#on-workers-and-serverless)
+has the details.
+
 ## Running it
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsc-kit/mcp",
-  "version": "0.27.1",
+  "version": "0.28.1",
   "description": "An MCP server over what an rsc-kit build decided: the routes, why each one is static or not, and what it costs the browser.",
   "type": "module",
   "license": "MIT",