@rsc-kit/mcp 0.26.0 → 0.27.1

package/dist/recipes.js

@@ -1730,6 +1730,39 @@ validates at runtime), move info/servers/security to the option, move a
 route's summary/tags/responses to its openapi export.
 
 Full guide: read_guide({ slug: 'openapi' }).`,
+    },
+    {
+        topic: 'secrets',
+        summary: 'The secrets rsc-kit reads - RSC_HOST_CALL_SECRET, RSC_SIGNING_SECRET, RSC_ACTION_ENCRYPTION_KEY - what each protects, how to generate them, where they go in production, and what rotating one does',
+        body: `Three, each its own key for its own job. Never reuse one as another.
+
+  RSC_HOST_CALL_SECRET       renderer <-> Go/Laravel backend calls. Required with a
+                             backend; read by the renderer AND the backend.
+  RSC_SIGNING_SECRET         signs refreshOn names a page hands the tab. Required in
+                             production when any page/section uses refreshOn (the
+                             server refuses to serve without it). Renderer only.
+                             Never falls back to the host-call secret.
+  RSC_ACTION_ENCRYPTION_KEY  optional: pins the key server actions encrypt with, so
+                             actions survive a deploy. Set at BUILD time too.
+
+GENERATE - once each, a different value each:
+  openssl rand -base64 32
+  node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
+  php -r "echo base64_encode(random_bytes(32)), PHP_EOL;"
+Development: create-rsc-kit / rsc-kit init (with a backend) and
+php artisan rsc:install write the first two into .env already.
+
+PRODUCTION - in the platform's environment settings, never in git:
+- the SAME value on every instance (a tab served by one renderer is checked by
+  another; a call may land on any backend replica);
+- read at runtime, so one build deploys anywhere (except the action key).
+
+ROTATING is a deploy:
+- host-call: change renderer and backend together; between them every rpc() is refused.
+- signing: open pages stop refreshing until reloaded; nothing else breaks.
+- action key: actions from pages loaded before the change fail.
+
+Docs: /hosts/deployment#secrets.`,
     },
     {
         topic: 'env',
@@ -1792,6 +1825,65 @@ SAY IT CHANGED - wherever the change happens, not only in an action:
   Go:      reg.Changed(ctx, "team:"+teamID+":repos")         // the webhook handler, a job
   Laravel: Rsc::changed("team:$teamId:repos");               // a controller, a job, a listener
   JS only: import { changed } from '@rsc-kit/core/changed'; await changed(\`team:\${team}:repos\`)
+ANY DATABASE - rsc-kit ships no driver; hand it yours. Postgres:
+postgresVersions(sql) (postgres.js/Bun.sql). MySQL/MariaDB: sqlVersions({
+query: async (t, p) => (await pool.query(t, p))[0] }) (mysql2). SQLite:
+sqlVersions({ query: async (t, p) => db.query(t).all(...p) }). libSQL/Turso:
+sqlVersions({ query: async (sql, args) => (await client.execute({ sql, args })).rows }).
+Redis/ORM query builders: createVersions({ read, bump, listen?, notify? }).
+Instant across instances: postgres.js LISTEN, Redis pub/sub; others within ~1s.
+NO BACKEND (JS only) - changed() works as-is on one server. With more than
+one instance, or a worker process that finishes jobs, keep versions in a
+table they all share: installVersionSource(postgresVersions(sql)) in
+instrumentation.ts register() AND in the worker (postgres.js LISTENs, so
+cross-instance changes are instant; Bun.sql polls once a second; any SQL
+driver/ORM: sqlVersions({ query }) - Prisma: query: (t, p) =>
+prisma.$queryRawUnsafe(t, ...p); anything else (Drizzle query builder, Redis,
+KV): createVersions({ read(names), bump(names), listen?, notify? }) and
+rsc-kit does the waiting/waking). An app-installed store always wins over a
+backend's. In-memory versions fail with 2+ instances; in production rsc-kit logs a
+warning once when it falls back to them - installVersionSource(memoryVersions())
+says "one instance on purpose" and silences it.
+Table: rsc_versions(name TEXT PRIMARY KEY, version BIGINT NOT NULL) - same as
+Go's SQLVersions. ANY process can bump without rsc-kit: upsert version + 1
+(Postgres: ON CONFLICT (name) DO UPDATE SET version = rsc_versions.version + 1;
+then NOTIFY rsc_versions).
+TABLE - the app owns rsc_versions (rsc-kit never creates/alters it at
+runtime): name TEXT PRIMARY KEY (MySQL: VARCHAR(255)), version BIGINT NOT
+NULL. Extra columns fine if they have defaults. Drizzle: a pgTable in your
+schema + createVersions with the query builder (not raw SQL).
+BUN / no LISTEN - keep Bun.sql (or Drizzle over it) for read/bump and open one
+postgres.js connection ({ max: 1 }) only for listen/notify in createVersions:
+instant across instances.
+AFTER COMMIT - call changed() AFTER the transaction resolves, never inside
+it: a tab refreshes at once and would read the old data, then sit at the new
+version. Laravel: DB::afterCommit(fn () => Rsc::changed(...)).
+SAME NAME - many sections/pages may refresh on one name; one changed() moves
+it once and every tab refreshes what it shows. Section names are per page.
+STARTUP - assertSigningSecret() from @rsc-kit/core/changed in
+instrumentation.ts register() makes a deploy without the secret fail before
+taking traffic (Kubernetes readiness); otherwise it is refused on the first
+request.
+SECRET - set RSC_SIGNING_SECRET, the same on every instance, with or without
+a backend (NOT the host-call secret). In production an app using refreshOn
+refuses to serve without it. Names are signed per request, never at build.
+REQUEST - a refreshOn function runs per request: cookies()/headers() work,
+e.g. a name for the signed-in user.
+SHARED - section(name, C, { refreshOn, shared: true }) for a section that
+renders the same for everyone allowed to see the page: tabs refreshing
+because of the same change share ONE render (guards still run per tab).
+Never on per-visitor content - rpc() runs with the first visitor's session.
+LARAVEL AT SCALE - RSC_VERSIONS=database (publish rsc-migrations) and
+installVersionSource(postgresVersions(sql)) in the renderer: watching costs
+PHP zero requests; Postgres NOTIFY makes it instant.
+DEBUG - dev console lists what each region watches; a region missing there
+rendered no names (server log says why). Hidden tabs stop watching and catch
+up when shown.
+COST - per visible tab one SSE connection (keepalive every 8s - set
+RSC_STREAM_KEEPALIVE_MS lower if a server/proxy drops idle connections sooner;
+~40 bytes
+per change); per change one refresh of just the sections showing the name;
+per server one versions read covering all its tabs.
 HOW - a name has a version, a number that moves when it is said to have
 changed; nothing else travels. The page learns versions at render, one SSE
 stream per tab (only on a page with names) watches them, and a moved version