feat(plugin-rsc): expose RSC compatibility version

Author: agcty

packages/plugin-rsc/README.md

@@ -442,6 +442,43 @@ export default defineConfig({
 })
 ```
 
+### Framework compatibility version
+
+Frameworks can use `getPluginApi(config)` to access compiler-owned RSC
+compatibility metadata. This is intended for deployment skew protection: a
+framework can include the compatibility version in an RSC response and trigger a
+document reload when a later RSC request comes from an incompatible client.
+
+```js
+import rsc, { getPluginApi } from '@vitejs/plugin-rsc'
+
+let manager
+
+export default defineConfig({
+  plugins: [
+    {
+      name: 'my-rsc-framework',
+      configResolved(config) {
+        manager = getPluginApi(config).manager
+      },
+      generateBundle() {
+        const version = manager.getCompatibilityVersion()
+        // Include `version` in framework RSC payloads or manifests.
+      },
+    },
+    rsc(),
+  ],
+})
+```
+
+`manager.getCompatibilityManifest()` returns the structured data used for the
+hash. It includes the Vite base path, RSC runtime package versions, client
+reference keys with rendered exports, server reference keys with exported
+functions, and a hash of the server-action encryption key when action closure
+encryption is actually emitted. Call this from `generateBundle` or later during
+the real RSC build; earlier scan builds may not have complete `renderedExports`
+metadata.
+
 ## RSC runtime (react-server-dom) API
 
 ### `@vitejs/plugin-rsc/rsc`

packages/plugin-rsc/src/index.ts

@@ -1,6 +1,7 @@
 export {
   default,
   type RscPluginOptions,
+  type RscCompatibilityManifest,
   getPluginApi,
   type PluginApi,
 } from './plugin'

packages/plugin-rsc/src/plugin.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, test } from 'vitest'
+import { vitePluginRscMinimal, type PluginApi } from './plugin'
+
+describe('RscPluginManager compatibility version', () => {
+  test('serializes normalized client and server reference ABI metadata', () => {
+    const manager = createManager({ root: '/workspace/app', base: '/base/' })
+    manager.clientReferenceMetaMap = {
+      '/workspace/app/src/button.tsx': {
+        importId: '/workspace/app/src/button.tsx',
+        referenceKey: 'button',
+        exportNames: ['Button', 'Unused'],
+        renderedExports: ['Button'],
+      },
+    }
+    manager.serverReferenceMetaMap = {
+      '/workspace/app/src/actions.ts': {
+        importId: '/workspace/app/src/actions.ts',
+        referenceKey: 'actions',
+        exportNames: ['save'],
+      },
+    }
+
+    expect(manager.getCompatibilityManifest()).toMatchObject({
+      version: 1,
+      base: '/base/',
+      clientReferences: [
+        {
+          id: 'src/button.tsx',
+          referenceKey: 'button',
+          renderedExports: ['Button'],
+        },
+      ],
+      serverReferences: [
+        {
+          id: 'src/actions.ts',
+          referenceKey: 'actions',
+          exportNames: ['save'],
+        },
+      ],
+    })
+  })
+
+  test('ignores client exports that are not rendered', () => {
+    const manager = createManager()
+    manager.clientReferenceMetaMap = {
+      '/workspace/app/src/button.tsx': {
+        importId: '/workspace/app/src/button.tsx',
+        referenceKey: 'button',
+        exportNames: ['Button'],
+        renderedExports: ['Button'],
+      },
+    }
+    const before = manager.getCompatibilityVersion()
+
+    manager.clientReferenceMetaMap[
+      '/workspace/app/src/button.tsx'
+    ]!.exportNames = ['Button', 'Unused']
+
+    expect(manager.getCompatibilityVersion()).toBe(before)
+  })
+
+  test('changes when the rendered client export ABI changes', () => {
+    const manager = createManager()
+    manager.clientReferenceMetaMap = {
+      '/workspace/app/src/card.tsx': {
+        importId: '/workspace/app/src/card.tsx',
+        referenceKey: 'card',
+        exportNames: ['Card', 'CardHeader'],
+        renderedExports: ['Card'],
+      },
+    }
+    const before = manager.getCompatibilityVersion()
+
+    manager.clientReferenceMetaMap[
+      '/workspace/app/src/card.tsx'
+    ]!.renderedExports = ['Card', 'CardHeader']
+
+    expect(manager.getCompatibilityVersion()).not.toBe(before)
+  })
+
+  test('changes when the server reference ABI changes', () => {
+    const manager = createManager()
+    manager.serverReferenceMetaMap = {
+      '/workspace/app/src/actions.ts': {
+        importId: '/workspace/app/src/actions.ts',
+        referenceKey: 'actions',
+        exportNames: ['save'],
+      },
+    }
+    const before = manager.getCompatibilityVersion()
+
+    manager.serverReferenceMetaMap[
+      '/workspace/app/src/actions.ts'
+    ]!.exportNames = ['delete', 'save']
+
+    expect(manager.getCompatibilityVersion()).not.toBe(before)
+  })
+
+  test('changes when server action encryption key identity changes', () => {
+    const manager = createManager()
+    manager.serverActionEncryptionKeyHash = 'key-a'
+    const before = manager.getCompatibilityVersion()
+
+    manager.serverActionEncryptionKeyHash = 'key-b'
+
+    expect(manager.getCompatibilityVersion()).not.toBe(before)
+  })
+
+  test('is stable across different absolute roots', () => {
+    const first = createManager({ root: '/first/root' })
+    first.clientReferenceMetaMap = {
+      '/first/root/src/button.tsx': {
+        importId: '/first/root/src/button.tsx',
+        referenceKey: 'button',
+        exportNames: ['Button'],
+        renderedExports: ['Button'],
+      },
+    }
+
+    const second = createManager({ root: '/second/root' })
+    second.clientReferenceMetaMap = {
+      '/second/root/src/button.tsx': {
+        importId: '/second/root/src/button.tsx',
+        referenceKey: 'button',
+        exportNames: ['Button'],
+        renderedExports: ['Button'],
+      },
+    }
+
+    expect(second.getCompatibilityVersion()).toBe(
+      first.getCompatibilityVersion(),
+    )
+  })
+})
+
+function createManager({
+  base = '/',
+  root = '/workspace/app',
+}: {
+  base?: string
+  root?: string
+} = {}) {
+  const [plugin] = vitePluginRscMinimal()
+  const manager = (plugin as { api: PluginApi }).api.manager
+  manager.config = { base, root } as any
+  return manager
+}

packages/plugin-rsc/src/plugin.ts

@@ -1,4 +1,5 @@
 import assert from 'node:assert'
+import { createHash } from 'node:crypto'
 import fs from 'node:fs'
 import { createRequire } from 'node:module'
 import path from 'node:path'
@@ -78,6 +79,14 @@ const isRolldownVite = 'rolldownVersion' in vite
 
 const BUILD_ASSETS_MANIFEST_NAME = '__vite_rsc_assets_manifest.js'
 
+const COMPATIBILITY_RUNTIME_PACKAGES = [
+  '@vitejs/plugin-rsc',
+  'react',
+  'react-dom',
+  'react-server-dom-webpack',
+  'vite',
+]
+
 type ClientReferenceMeta = {
   importId: string
   // same as `importId` during dev. hashed id during build.
@@ -97,6 +106,24 @@ type ServerRerferenceMeta = {
   exportNames: string[]
 }
 
+export type RscCompatibilityManifest = {
+  version: 1
+  base: string
+  runtime: Record<string, string>
+  clientReferences: Array<{
+    id: string
+    referenceKey: string
+    packageSource?: string
+    renderedExports: string[]
+  }>
+  serverReferences: Array<{
+    id: string
+    referenceKey: string
+    exportNames: string[]
+  }>
+  serverActionEncryptionKeyHash?: string
+}
+
 const PKG_NAME = '@vitejs/plugin-rsc'
 const REACT_SERVER_DOM_NAME = `${PKG_NAME}/vendor/react-server-dom`
 
@@ -126,6 +153,7 @@ class RscPluginManager {
   clientReferenceGroups: Record</* group name*/ string, ClientReferenceMeta[]> =
     {}
   serverReferenceMetaMap: Record<string, ServerRerferenceMeta> = {}
+  serverActionEncryptionKeyHash: string | undefined
   serverResourcesMetaMap: Record<string, { key: string }> = {}
   environmentImportMetaMap: Record<
     string, // sourceEnv
@@ -166,6 +194,85 @@ class RscPluginManager {
   writeEnvironmentImportsManifest(): void {
     writeEnvironmentImportsManifest(this)
   }
+
+  getCompatibilityManifest(): RscCompatibilityManifest {
+    const manifest: RscCompatibilityManifest = {
+      version: 1,
+      base: this.config.base,
+      runtime: Object.fromEntries(
+        COMPATIBILITY_RUNTIME_PACKAGES.map((packageName) => [
+          packageName,
+          getPackageVersion(packageName),
+        ]),
+      ),
+      clientReferences: Object.values(this.clientReferenceMetaMap)
+        .map((meta) => ({
+          id: this.toCompatibilityId(meta.importId),
+          referenceKey: meta.referenceKey,
+          packageSource: meta.packageSource,
+          renderedExports: [...meta.renderedExports].sort(),
+        }))
+        .sort(compareClientCompatibilityReferences),
+      serverReferences: Object.values(this.serverReferenceMetaMap)
+        .map((meta) => ({
+          id: this.toCompatibilityId(meta.importId),
+          referenceKey: meta.referenceKey,
+          exportNames: [...meta.exportNames].sort(),
+        }))
+        .sort(compareServerCompatibilityReferences),
+    }
+    if (this.serverActionEncryptionKeyHash) {
+      manifest.serverActionEncryptionKeyHash =
+        this.serverActionEncryptionKeyHash
+    }
+    return manifest
+  }
+
+  getCompatibilityVersion(): string {
+    return hashCompatibilityValue(
+      JSON.stringify(this.getCompatibilityManifest()),
+    )
+  }
+
+  private toCompatibilityId(id: string): string {
+    return normalizePath(path.isAbsolute(id) ? this.toRelativeId(id) : id)
+  }
+}
+
+function compareClientCompatibilityReferences(
+  a: RscCompatibilityManifest['clientReferences'][number],
+  b: RscCompatibilityManifest['clientReferences'][number],
+): number {
+  return (
+    a.referenceKey.localeCompare(b.referenceKey) ||
+    a.id.localeCompare(b.id) ||
+    (a.packageSource ?? '').localeCompare(b.packageSource ?? '')
+  )
+}
+
+function compareServerCompatibilityReferences(
+  a: RscCompatibilityManifest['serverReferences'][number],
+  b: RscCompatibilityManifest['serverReferences'][number],
+): number {
+  return (
+    a.referenceKey.localeCompare(b.referenceKey) || a.id.localeCompare(b.id)
+  )
+}
+
+function hashCompatibilityValue(value: string): string {
+  return createHash('sha256').update(value).digest('hex').slice(0, 16)
+}
+
+function getPackageVersion(packageName: string): string {
+  try {
+    const packageJsonPath = require.resolve(`${packageName}/package.json`)
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))
+    return typeof packageJson.version === 'string'
+      ? packageJson.version
+      : 'unknown'
+  } catch {
+    return 'unknown'
+  }
 }
 
 export type RscPluginOptions = {
@@ -338,7 +445,7 @@ export function vitePluginRscMinimal(
     ...vitePluginRscCore(),
     ...vitePluginUseClient(rscPluginOptions, manager),
     ...vitePluginUseServer(rscPluginOptions, manager),
-    ...vitePluginDefineEncryptionKey(rscPluginOptions),
+    ...vitePluginDefineEncryptionKey(rscPluginOptions, manager),
     {
       name: 'rsc:reference-validation',
       apply: 'serve',
@@ -1820,6 +1927,7 @@ function vitePluginDefineEncryptionKey(
     RscPluginOptions,
     'defineEncryptionKey' | 'environment'
   >,
+  manager: RscPluginManager,
 ): Plugin[] {
   let defineEncryptionKey: string
   let emitEncryptionKey = false
@@ -1833,6 +1941,7 @@ function vitePluginDefineEncryptionKey(
       name: 'rsc:encryption-key',
       async configEnvironment(name, _config, env) {
         if (name === serverEnvironmentName && !env.isPreview) {
+          manager.serverActionEncryptionKeyHash = undefined
           defineEncryptionKey =
             useServerPluginOptions.defineEncryptionKey ??
             JSON.stringify(toBase64(await generateEncryptionKey()))
@@ -1863,6 +1972,8 @@ function vitePluginDefineEncryptionKey(
         if (code.includes(KEY_PLACEHOLDER)) {
           assert.equal(this.environment.name, serverEnvironmentName)
           emitEncryptionKey = true
+          manager.serverActionEncryptionKeyHash =
+            hashCompatibilityValue(defineEncryptionKey)
           const normalizedPath = normalizeRelativePath(
             path.relative(path.join(chunk.fileName, '..'), KEY_FILE),
           )