@rsc-kit/core 0.7.2 → 0.8.0

package/dist/vite.js

@@ -13,6 +13,7 @@
 // the structural config (entries, output dirs, base). @vitejs/plugin-rsc is
 // included here so it always runs before any react() layer the app adds.
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -52,6 +53,10 @@ let routeConfig;
 let prerenderAfterBuild;
 /** True during `vite build --watch`, where re-rendering every route is noise. */
 let isWatch = false;
+/** Whether navigations are wrapped in React's ViewTransition — see options. */
+let viewTransitions = false;
+/** Whether a service worker is generated and registered — see options. */
+let offline = false;
 /** Host functions to generate stubs for — see RscKitOptions.hostActions. */
 let hostActions;
 /**
@@ -193,6 +198,8 @@ function resolvePaths(options) {
     // A host driving the build out of process cannot pass an option, and may
     // prerender itself afterwards with paths only it knows.
     prerenderAfterBuild = options.prerender ?? process.env.RSC_PRERENDER !== '0';
+    viewTransitions = options.viewTransitions === true;
+    offline = options.offline === true;
     hostActions = options.hostActions ?? fileHostActions(projectRoot);
 }
 function log(...args) {
@@ -519,6 +526,200 @@ function reportAllDynamic() {
 
   ${routes.length} dynamic — prerendering is off`);
 }
+/**
+ * The service worker, written into the client output at build time.
+ *
+ * Scoped to the site root because it is served from there, so it sees every
+ * navigation. Three kinds of request, three answers:
+ *
+ * Hashed assets are immutable by construction — the name changes when the
+ * bytes do — so they are answered from the cache and only fetched once ever.
+ *
+ * Documents and payloads go to the network first and fall back to the cache,
+ * because a page whose data moved on should say so while there is a network to
+ * ask. Only the fallback is what makes a reload work with none.
+ *
+ * A document and its payload share a url and differ by header. They do not
+ * collide, because the server sends `Vary: X-RSC, ...` and the Cache API
+ * honours it when a Response is stored whole and matched with its Request.
+ *
+ * Nothing else is touched. An action is a POST and must never be answered from
+ * a cache; anything cross-origin is somebody else's to cache.
+ */
+export const SERVICE_WORKER = (version, precache) => `// GENERATED by rscKit() — do not edit.
+const VERSION = ${JSON.stringify(version)}
+const CACHE = 'rsc-kit-' + VERSION
+const PRECACHE = ${JSON.stringify(precache, null, 2)}
+
+self.addEventListener('install', (event) => {
+  // The new worker takes over rather than waiting for every tab to close.
+  // Safe here because assets are content-hashed: a page already open keeps
+  // asking for the names it was built with, and those are still cached under
+  // their own version until this activates and sweeps.
+  event.waitUntil(caches.open(CACHE).then((cache) => cache.addAll(PRECACHE)).then(() => self.skipWaiting()))
+})
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((keys) => Promise.all(keys.filter((k) => k.startsWith('rsc-kit-') && k !== CACHE).map((k) => caches.delete(k))))
+      .then(() => self.clients.claim()),
+  )
+})
+
+const immutable = (url) => url.pathname.startsWith('/assets/') || /-[A-Za-z0-9_-]{8,}\\.[a-z]+$/.test(url.pathname)
+
+// Whether a response may be kept at all.
+//
+// \`no-store\` is not advice here, it is the answer. A query defaults to
+// \`private, no-store\` precisely because it may read the session, and a worker
+// that files it by url alone would serve one visitor's answer to whoever signs
+// in next — the Cache API has no notion of who asked. A live response is worse
+// again: the clone goes on streaming long after the page that opened it is
+// gone.
+//
+// Checked before every put, rather than only for the paths that happen to reach
+// a query today. A new cacheable route added later must not have to remember
+// this.
+const mayStore = (response) =>
+  response.ok && !(response.headers.get('Cache-Control') || '').includes('no-store')
+
+// What a response is filed under. A payload request carries headers the url
+// does not, so the url is where they have to go.
+const keyFor = (request) => {
+  if (!request.headers.get('X-RSC')) return request
+
+  const url = new URL(request.url)
+  url.searchParams.set('__rsc', request.headers.get('X-RSC-Segments') || '')
+
+  return new Request(url, { headers: request.headers })
+}
+
+self.addEventListener('fetch', (event) => {
+  const request = event.request
+  const url = new URL(request.url)
+
+  if (request.method !== 'GET' || url.origin !== self.location.origin) return
+
+  if (immutable(url)) {
+    event.respondWith(
+      caches.match(request).then(
+        (hit) =>
+          hit ??
+          fetch(request).then((response) => {
+            if (mayStore(response)) {
+              const copy = response.clone()
+              caches.open(CACHE).then((cache) => cache.put(request, copy))
+            }
+
+            return response
+          }),
+      ),
+    )
+
+    return
+  }
+
+  event.respondWith(
+    fetch(request)
+      .then((response) => {
+        if (mayStore(response)) {
+          const copy = response.clone()
+          caches.open(CACHE).then((cache) => cache.put(keyFor(request), copy))
+
+          // A document is not enough to boot from. The client hydrates from a
+          // payload it fetches for itself, and on a first visit that request
+          // happens before this worker controls the page — so it is never
+          // cached, and a reload with no network has the markup and nothing to
+          // hydrate it with.
+          //
+          // \`X-RSC: true\` and no segments header is exactly what a fresh boot
+          // sends, which is what makes this entry the one it finds: the server
+          // varies on those, and the Cache API matches on the same.
+          if (request.mode === 'navigate') {
+            const warm = new Request(request.url, { headers: { 'X-RSC': 'true' } })
+
+            fetch(warm)
+              .then((payload) => {
+                if (mayStore(payload)) {
+                  caches.open(CACHE).then((cache) => cache.put(keyFor(warm), payload))
+                }
+              })
+              .catch(() => {})
+          }
+
+          // And the other way round. Moving between pages fetches payloads and
+          // never documents, so a page reached only by a link had nothing to
+          // serve when someone reloaded its url — it navigated fine and then
+          // died on refresh, which is the half of offline nobody would trust.
+          //
+          // Once per url: the document is fetched only when the cache has none,
+          // so this costs one extra request the first time a page is visited
+          // rather than one on every navigation to it.
+          if (request.headers.get('X-RSC')) {
+            const document = new Request(request.url)
+
+            caches.open(CACHE).then(async (cache) => {
+              if (await cache.match(document)) return
+
+              const fresh = await fetch(document).catch(() => null)
+
+              if (fresh && mayStore(fresh)) await cache.put(document, fresh)
+            })
+          }
+        }
+
+        return response
+      })
+      .catch(async () => {
+        const hit = await caches.match(keyFor(request))
+
+        if (hit) return hit
+
+        // Nothing cached for this url and no network to ask. Falling back to
+        // the cached root was worse than failing: the document IS the page
+        // here, so the visitor got the home page's markup under the address
+        // they asked for, and it did not hydrate — a wrong page pretending to
+        // be the right one. Letting it fail says what is true, and a page
+        // already open is unaffected.
+        return Response.error()
+      }),
+  )
+})
+`;
+/**
+ * Write the worker beside the assets it caches.
+ *
+ * The version is a hash of what is being precached rather than a build id from
+ * the environment. The names are content-hashed already, so a build that
+ * changed nothing produces the same list and leaves the visitor's cache alone,
+ * and a build that changed anything produces a different one — which is the
+ * whole of cache invalidation, without asking anyone to set a variable.
+ */
+function writeServiceWorker(clientDir) {
+    if (!existsSync(clientDir))
+        return;
+    const files = [];
+    const walk = (dir, prefix) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            // Not itself, and not a map: a debugger asks for those, a visitor does
+            // not, and precaching them doubles what an install costs.
+            if (entry.name === 'sw.js' || entry.name.endsWith('.map'))
+                continue;
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(path, `${prefix}${entry.name}/`);
+            else
+                files.push(`${prefix}${entry.name}`);
+        }
+    };
+    walk(clientDir, '');
+    const precache = ['/', ...files.map((file) => `/${file}`)].sort();
+    const version = createHash('sha256').update(precache.join('\n')).digest('hex').slice(0, 12);
+    writeFileSync(join(clientDir, 'sw.js'), SERVICE_WORKER(version, precache));
+    log(`offline: ${precache.length} files precached as rsc-kit-${version}`);
+}
 /**
  * The rsc bundle the build just wrote, whatever it decided to call it.
  *
@@ -990,6 +1191,7 @@ import { createRscHandler } from ${JSON.stringify(join(packageDir, "host"))}
 import { httpHostCalls } from ${JSON.stringify(join(packageDir, 'hostCalls'))}
 import { prerenderedBeside } from ${JSON.stringify(join(packageDir, 'files'))}
 import { renderToReadableStream, decodeReply, loadServerAction } from '@vitejs/plugin-rsc/rsc'
+import { isQuery, queryCacheControl } from ${JSON.stringify(join(packageDir, 'query'))}
 import { Suspense, createElement, Fragment } from 'react'
 import { AsyncLocalStorage } from 'node:async_hooks'
 ${imports.join('\n')}
@@ -1677,6 +1879,44 @@ async function renderRevalidated(target: string, page: PageContext): Promise<unk
   })
 }
 
+/**
+ * Answer one read.
+ *
+ * Only functions declared with query() are reachable. The id comes off the url,
+ * and every registered server action has one — without the mark, this address
+ * would invoke mutations over GET, for anyone who can fetch it.
+ */
+export async function handleQuery(
+  id: string,
+  args: string,
+  report?: (error: unknown) => string,
+): Promise<{ stream: ReadableStream; cacheControl: string } | null> {
+  applyHost()
+
+  let fn: unknown
+
+  try {
+    fn = await loadServerAction(id)
+  } catch {
+    return null
+  }
+
+  // Null for both, deliberately. Saying "that exists but is not a query" tells
+  // whoever is probing this endpoint which ids are real actions, and the ids
+  // are stable across a build.
+  if (!isQuery(fn)) return null
+
+  const decoded = (await decodeReply(args)) as unknown[]
+  const result = await (fn as (...a: unknown[]) => unknown)(...decoded)
+
+  return {
+    stream: renderToReadableStream(result, {
+      onError: (error: unknown) => (report ? report(error) : 'Query failed.'),
+    }),
+    cacheControl: queryCacheControl(fn),
+  }
+}
+
 export async function handleAction(
   actionId: string,
   body: string | FormData | Uint8Array,
@@ -1723,6 +1963,19 @@ export async function handleAction(
 
   const args = (await decodeReply(decodable)) as unknown[]
   const action = await loadServerAction(actionId)
+
+  // A query reached the ACTION endpoint, which means it was called directly
+  // rather than through fetchQuery — so it went out as a POST and none of the
+  // reasons it was marked a read apply to it. It still works, which is the
+  // problem: nothing else would ever mention it. Only in development, and only
+  // a warning, because the call is not wrong, just not what was asked for.
+  if (isQuery(action) && import.meta.env?.DEV) {
+    console.warn(
+      '[rsc-kit] ' + actionId + ' is a query but was called directly, so it was sent as a POST. ' +
+        'Call it through fetchQuery() to send a GET.',
+    )
+  }
+
   const result = await (action as (...a: unknown[]) => unknown)(...args)
 
   // Read after the action has run: what it invalidated is only known once its
@@ -2128,6 +2381,7 @@ export default async function handler(request: Request): Promise<Response> {
       handleRscPprShell,
       handleRscResume,
       handleAction,
+      handleQuery,
       resolveMetadata,
       runRouteMiddleware,
     } as never,
@@ -2302,7 +2556,25 @@ if (import.meta.hot) {
     void refresh('all')
   })
 }
-`;
+${offline
+        ? `
+// Registered after load rather than during it, so fetching and installing the
+// worker competes with nothing the first visit actually needs. The second
+// visit is the one it is for.
+//
+// Not in development: the dev server is the thing you are editing, and a
+// worker answering from a cache in front of it turns every edit into a
+// question about which copy you are looking at.
+if ('serviceWorker' in navigator && import.meta.env.PROD) {
+  window.addEventListener('load', () => {
+    void navigator.serviceWorker.register('/sw.js').catch(() => {
+      // A worker that will not register is not a reason for the page to fail.
+      // The app works; it just will not survive being reloaded offline.
+    })
+  })
+}
+`
+        : ''}`;
 }
 /**
  * Intercepted URL patterns, published by the host before the build.
@@ -2510,6 +2782,10 @@ export function rscKit(options = {}) {
                  */
                 define: {
                     'process.env.NODE_ENV': JSON.stringify(env.mode === 'development' ? 'development' : 'production'),
+                    // A constant, so the boundary and its import fall out of the bundle
+                    // entirely when this is off rather than shipping a branch nobody takes.
+                    __RSC_VIEW_TRANSITIONS__: JSON.stringify(viewTransitions),
+                    __RSC_OFFLINE__: JSON.stringify(offline),
                 },
                 /*
                  * This package's client modules are served as source, never
@@ -2730,6 +3006,8 @@ export function rscKit(options = {}) {
                 ? join(dirname(clientOut), 'server', NITRO_STATIC_DIR)
                 : join(outDir, NITRO_STATIC_DIR);
             await prerenderAfterBundles(bundle, staticDir, clientOut ?? publicAssetsDir);
+            if (offline)
+                writeServiceWorker(clientOut ?? publicAssetsDir);
         },
         configResolved(config) {
             isWatch = config.build?.watch != null;