feat(plugin-rsc): expose RSC compatibility version

Author: agcty

packages/plugin-rsc/README.md

@@ -442,6 +442,46 @@ export default defineConfig({
 })
 ```
 
+### Framework compatibility manifest
+
+Frameworks can import `virtual:vite-rsc/compatibility-manifest` from the RSC or
+SSR environment to access compiler-owned deployment compatibility metadata. This
+is intended for deployment skew protection: a framework can include
+`compatibilityManifest.compatibilityVersion` in RSC responses and trigger a
+document reload when a later RSC request comes from an incompatible client.
+
+```js
+import compatibilityManifest from 'virtual:vite-rsc/compatibility-manifest'
+
+export function getRscResponseMetadata() {
+  return {
+    compatibilityVersion: compatibilityManifest.compatibilityVersion,
+  }
+}
+```
+
+The manifest includes the Vite base path, RSC runtime package versions, a hash
+of the final assets manifest, final output bundle hashes, 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.
+
+Frameworks with a custom build pipeline can use `getPluginApi(config).manager`
+after the real RSC and client builds have completed:
+
+```js
+import { getPluginApi } from '@vitejs/plugin-rsc'
+
+const manager = getPluginApi(config).manager
+const manifest = manager.finalizeCompatibilityManifest()
+const version = manifest.compatibilityVersion
+```
+
+`manager.getCompatibilityManifest()` and `manager.getCompatibilityVersion()`
+throw during production builds until the manifest has been finalized. This
+prevents scan builds or incomplete custom pipelines from accidentally emitting a
+partial compatibility version.
+
 ## 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,234 @@
+import { describe, expect, test } from 'vitest'
+import { vitePluginRscMinimal, type PluginApi } from './plugin'
+
+describe('RscPluginManager compatibility version', () => {
+  test('throws during build before finalization', () => {
+    const manager = createManager()
+
+    expect(() => manager.getCompatibilityManifest()).toThrow(
+      /compatibility manifest is not ready/,
+    )
+    expect(() => manager.finalizeCompatibilityManifest()).toThrow(
+      /requires the final assets manifest/,
+    )
+  })
+
+  test('serializes normalized references and final build fingerprints', () => {
+    const manager = createFinalizedManager({
+      root: '/workspace/app',
+      base: '/base/',
+    })
+
+    expect(manager.getCompatibilityManifest()).toMatchObject({
+      version: 1,
+      compatibilityVersion: expect.stringMatching(/^[a-f0-9]{64}$/),
+      base: '/base/',
+      assetsManifestHash: expect.stringMatching(/^[a-f0-9]{64}$/),
+      bundles: {
+        client: expect.stringMatching(/^[a-f0-9]{64}$/),
+        rsc: expect.stringMatching(/^[a-f0-9]{64}$/),
+      },
+      clientReferences: [
+        {
+          id: 'src/button.tsx',
+          referenceKey: 'button',
+          renderedExports: ['Button'],
+        },
+      ],
+      serverReferences: [
+        {
+          id: 'src/actions.ts',
+          referenceKey: 'actions',
+          exportNames: ['save'],
+        },
+      ],
+    })
+    expect(manager.getCompatibilityVersion()).toBe(
+      manager.getCompatibilityManifest().compatibilityVersion,
+    )
+  })
+
+  test('ignores client exports that are not rendered', () => {
+    const manager = createFinalizedManager()
+    const before = manager.getCompatibilityVersion()
+
+    manager.clientReferenceMetaMap[
+      '/workspace/app/src/button.tsx'
+    ]!.exportNames = ['Button', 'Unused']
+    manager.finalizeCompatibilityManifest()
+
+    expect(manager.getCompatibilityVersion()).toBe(before)
+  })
+
+  test('changes when the rendered client export ABI changes', () => {
+    const manager = createFinalizedManager()
+    const before = manager.getCompatibilityVersion()
+
+    manager.clientReferenceMetaMap[
+      '/workspace/app/src/button.tsx'
+    ]!.renderedExports = ['Button', 'ButtonIcon']
+    manager.finalizeCompatibilityManifest()
+
+    expect(manager.getCompatibilityVersion()).not.toBe(before)
+  })
+
+  test('changes when the server reference ABI changes', () => {
+    const manager = createFinalizedManager()
+    const before = manager.getCompatibilityVersion()
+
+    manager.serverReferenceMetaMap[
+      '/workspace/app/src/actions.ts'
+    ]!.exportNames = ['delete', 'save']
+    manager.finalizeCompatibilityManifest()
+
+    expect(manager.getCompatibilityVersion()).not.toBe(before)
+  })
+
+  test('changes when the client assets manifest changes', () => {
+    const manager = createFinalizedManager()
+    const before = manager.getCompatibilityVersion()
+
+    manager.buildAssetsManifest = {
+      ...manager.buildAssetsManifest!,
+      clientReferenceDeps: {
+        button: {
+          js: ['/assets/button.new.js'],
+          css: [],
+        },
+      },
+    }
+    manager.finalizeCompatibilityManifest()
+
+    expect(manager.getCompatibilityVersion()).not.toBe(before)
+  })
+
+  test('changes when final client bundle content changes', () => {
+    const manager = createFinalizedManager()
+    const before = manager.getCompatibilityVersion()
+
+    manager.bundles.client = createBundle({
+      'assets/button.js': 'export const Button = "new"',
+    })
+    manager.finalizeCompatibilityManifest()
+
+    expect(manager.getCompatibilityVersion()).not.toBe(before)
+  })
+
+  test('changes when final rsc bundle content changes', () => {
+    const manager = createFinalizedManager()
+    const before = manager.getCompatibilityVersion()
+
+    manager.bundles.rsc = createBundle({
+      'index.js': 'export const root = "new-rsc"',
+    })
+    manager.finalizeCompatibilityManifest()
+
+    expect(manager.getCompatibilityVersion()).not.toBe(before)
+  })
+
+  test('changes when server action encryption key identity changes', () => {
+    const manager = createFinalizedManager()
+    manager.serverActionEncryptionKeyHash = 'key-a'
+    manager.finalizeCompatibilityManifest()
+    const before = manager.getCompatibilityVersion()
+
+    manager.serverActionEncryptionKeyHash = 'key-b'
+    manager.finalizeCompatibilityManifest()
+
+    expect(manager.getCompatibilityVersion()).not.toBe(before)
+  })
+
+  test('is stable across different absolute roots', () => {
+    const first = createFinalizedManager({ root: '/first/root' })
+    first.clientReferenceMetaMap = {
+      '/first/root/src/button.tsx': {
+        importId: '/first/root/src/button.tsx',
+        referenceKey: 'button',
+        exportNames: ['Button'],
+        renderedExports: ['Button'],
+      },
+    }
+    first.finalizeCompatibilityManifest()
+
+    const second = createFinalizedManager({ root: '/second/root' })
+    second.clientReferenceMetaMap = {
+      '/second/root/src/button.tsx': {
+        importId: '/second/root/src/button.tsx',
+        referenceKey: 'button',
+        exportNames: ['Button'],
+        renderedExports: ['Button'],
+      },
+    }
+    second.finalizeCompatibilityManifest()
+
+    expect(second.getCompatibilityVersion()).toBe(
+      first.getCompatibilityVersion(),
+    )
+  })
+})
+
+type ManagerOptions = {
+  base?: string
+  root?: string
+}
+
+function createFinalizedManager(options: ManagerOptions = {}) {
+  const manager = createManager(options)
+  manager.clientReferenceMetaMap = {
+    [`${options.root ?? '/workspace/app'}/src/button.tsx`]: {
+      importId: `${options.root ?? '/workspace/app'}/src/button.tsx`,
+      referenceKey: 'button',
+      exportNames: ['Button'],
+      renderedExports: ['Button'],
+    },
+  }
+  manager.serverReferenceMetaMap = {
+    [`${options.root ?? '/workspace/app'}/src/actions.ts`]: {
+      importId: `${options.root ?? '/workspace/app'}/src/actions.ts`,
+      referenceKey: 'actions',
+      exportNames: ['save'],
+    },
+  }
+  manager.buildAssetsManifest = {
+    bootstrapScriptContent: 'import("/assets/index.js")',
+    clientReferenceDeps: {
+      button: {
+        js: ['/assets/button.js'],
+        css: [],
+      },
+    },
+  }
+  manager.bundles = {
+    client: createBundle({
+      'assets/button.js': 'export const Button = "old"',
+    }),
+    rsc: createBundle({
+      'index.js': 'export const root = "rsc"',
+    }),
+  }
+  manager.finalizeCompatibilityManifest()
+  return manager
+}
+
+function createManager({
+  base = '/',
+  root = '/workspace/app',
+}: ManagerOptions = {}) {
+  const [plugin] = vitePluginRscMinimal()
+  const manager = (plugin as { api: PluginApi }).api.manager
+  manager.config = { base, command: 'build', root } as any
+  return manager
+}
+
+function createBundle(chunks: Record<string, string>) {
+  return Object.fromEntries(
+    Object.entries(chunks).map(([fileName, code]) => [
+      fileName,
+      {
+        type: 'chunk',
+        fileName,
+        code,
+      },
+    ]),
+  ) as any
+}