@tanstack/start-plugin-core 1.167.35 → 1.169.0

package/src/rsbuild/INTERNALS-import-protection.md

@@ -0,0 +1,169 @@
+# Rsbuild Import Protection - Adapter Internals
+
+## Scope
+
+This document covers the Rsbuild-specific orchestration around the shared
+import-protection core in `src/import-protection/INTERNALS.md`.
+
+Rsbuild owns:
+
+- post-transform enforcement through `api.transform({ order: 'post' })`
+- virtual-module transport through `VirtualModulesPlugin`
+- compilation-truth reporting in `processAssets`
+- final graph reconstruction from Rspack compilation data
+- the small build-only deferred queue for file violations that can disappear
+  from the compiled graph
+
+Shared AST analysis, rewrite logic, source extraction, usage lookup, source
+locations, trace formatting, and mock code generation are described in the
+shared internals doc.
+
+## Mental Model
+
+Vite is primarily `resolveId`-driven. Rsbuild is primarily `transform` +
+`processAssets`-driven.
+
+That difference explains most of the adapter divergence.
+
+Rsbuild does not emulate the Vite pending-queue state machine. It relies more
+directly on post-transform code and final compilation truth.
+
+## Native Hook Shape
+
+Import protection is attached through Rsbuild hooks, not a dedicated mini-plugin
+object:
+
+1. `onBeforeBuild`
+2. `onBeforeDevCompile`
+3. `modifyRspackConfig`
+4. `transform(..., { order: 'post' })`
+5. `processAssets(..., { stage: 'report' })`
+
+## State Model
+
+Per environment, Rsbuild keeps a smaller runtime state than Vite:
+
+- `resolveCache`
+- `seenViolations`
+- `buildTransformResults`
+- `deferredFileViolations`
+- `deferredFileViolationKeys`
+
+Shared state is for virtual module transport and compiler fs access:
+
+- `virtualModules`
+- `vmPlugins`
+- `readyVmPlugins`
+- `inputFileSystems`
+- `pendingWrites`
+
+Notably absent compared to Vite:
+
+- no `pendingViolations`
+- no `postTransformImports`
+- no broad `deferredBuildViolations`
+- no resolve-time dev reachability pipeline
+
+## Transform Phase
+
+Rsbuild enforcement runs after the Start compiler in a `post` transform.
+
+That matters because many compiler-safe imports are already stripped by the time
+import protection runs. This naturally suppresses a large class of false
+positives without a Vite-style pending verification pass.
+
+The transform phase is responsible for:
+
+- self-denial for forbidden files
+- self-denial for marker-protected files in the wrong environment
+- direct specifier rewrites to mock-edge modules
+- build-time transformed/original source preloading for later diagnostics
+- recording build-only deferred file violations when original unsafe usage may
+  outlive a direct compiled graph edge
+
+## Virtual Module Transport
+
+Rsbuild reuses the shared mock generators, but not the Vite id transport.
+
+Instead it writes environment-scoped virtual files under:
+
+```text
+<root>/node_modules/.virtual/import-protection/<env>/
+```
+
+The important forms are:
+
+- `mock-silent.mjs`
+- `mock-runtime-<base64>.mjs`
+- `mock-edge-<base64>.mjs`
+
+Writes may happen before the `VirtualModulesPlugin` instance is ready, so the
+adapter queues them and flushes during compilation setup.
+
+## Reporting Phase
+
+`processAssets({ stage: 'report' })` is the authoritative reporting step.
+
+It reconstructs the final view of the compilation from Rspack data by:
+
+1. building a `TransformResultProvider` from `compilation.modules`
+2. rebuilding the active compilation graph from outgoing connections
+3. reconstructing surviving specifier violations from compiled mock-edge files
+4. reporting live file violations from active edges
+5. reporting live marker violations from active edges plus original source
+6. reporting deferred file violations only when both importer and target truly
+   survived compilation
+
+This is the core Rsbuild-native replacement for Vite's `generateBundle`
+verification plus dev pending-violation flow.
+
+## Why The Deferred Queue Is Narrow
+
+Rsbuild only needs explicit build deferral for file violations whose direct edge
+may disappear after compilation.
+
+Specifier violations are rediscovered from surviving mock-edge virtual files.
+Marker violations are rediscovered from live compiled edges.
+
+Only file violations need extra bookkeeping when the final compiled graph can no
+longer show the original denied edge directly.
+
+## Source And Compilation APIs
+
+The Rsbuild adapter intentionally prefers native Rspack APIs where possible.
+
+Transform-time:
+
+- `ctx.resource`
+- `ctx.context`
+- `ctx.resolve(...)`
+- captured `compiler.inputFileSystem.readFile(...)`
+
+Compilation-time:
+
+- `module.nameForCondition?.()`
+- `module.resourceResolveData?.resource`
+- `module.originalSource().sourceAndMap()`
+- sourcemap `sourcesContent`
+- `compilation.inputFileSystem.readFile(...)`
+
+This keeps the adapter closer to Rsbuild/Rspack truth and avoids falling back to
+Node fs when the compilation already has the needed data.
+
+## Marker Handling
+
+Unlike Vite, Rsbuild does not introduce plugin-owned virtual marker modules for
+normal operation.
+
+The real package marker files are used as source-level markers, and the adapter
+later infers marker kind from original source while reporting compiled edges.
+
+## Practical Maintainer Rule
+
+When changing Rsbuild import protection, ask:
+
+1. Can the change be expressed in shared analysis/rewrite/mock codegen instead?
+2. If it is adapter-specific, is it really about post-transform enforcement,
+   virtual-file transport, or compilation-time reporting?
+3. Can final compilation truth answer the question more simply than adding a new
+   pending state machine?

package/src/rsbuild/dev-server.ts

@@ -0,0 +1,129 @@
+import { NodeRequest, sendNodeResponse } from 'srvx/node'
+import { RSBUILD_ENVIRONMENT_NAMES } from './planning'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { RsbuildConfig } from '@rsbuild/core'
+
+type ServerSetupFn = Extract<
+  NonNullable<NonNullable<RsbuildConfig['server']>['setup']>,
+  (...args: Array<any>) => any
+>
+type SSRMiddleware = (
+  req: IncomingMessage & { originalUrl?: string },
+  res: ServerResponse,
+  next: () => void,
+) => Promise<void>
+
+/**
+ * Returns a `server.setup` function for rsbuild v2.
+ *
+ * Two middleware positions are used:
+ *
+ * 1. **Setup body** (BEFORE built-ins): Intercepts `/_serverFn/` URLs so
+ *    they never reach rsbuild's htmlFallback/htmlCompletion middleware,
+ *    which can swallow long base64 function IDs.
+ *
+ * 2. **Returned callback** (AFTER built-ins, BEFORE fallback): Handles
+ *    all remaining SSR requests (page navigations). This position lets
+ *    rsbuild's asset middleware serve compiled JS/CSS first.
+ *
+ * See rsbuild source: devMiddlewares.ts `applyDefaultMiddlewares()`.
+ */
+export function createServerSetup(opts: {
+  serverFnBasePath: string
+}): ServerSetupFn {
+  return (context) => {
+    // Only install SSR middleware in dev mode
+    if (context.action !== 'dev') {
+      return () => {}
+    }
+
+    const serverFnBase = opts.serverFnBasePath
+
+    const handleSSR: SSRMiddleware = async (req, res, next) => {
+      const ssrEnv =
+        context.server.environments[RSBUILD_ENVIRONMENT_NAMES.server]
+
+      if (!ssrEnv) {
+        console.error(
+          `[tanstack-start] SSR environment "${RSBUILD_ENVIRONMENT_NAMES.server}" not found`,
+        )
+        return next()
+      }
+
+      try {
+        const serverEntry = await ssrEnv.loadBundle<{
+          default: { fetch: (req: Request) => Promise<Response> }
+        }>('index')
+
+        // Restore the original URL (rsbuild may rewrite to /index.html)
+        if (req.originalUrl) {
+          req.url = req.originalUrl
+        }
+
+        const webReq = new NodeRequest({ req, res })
+        const webRes = await serverEntry.default.fetch(webReq)
+        return sendNodeResponse(res, webRes)
+      } catch (e) {
+        console.error('[tanstack-start] SSR error:', e)
+
+        const webReq = new NodeRequest({ req, res })
+        if (webReq.headers.get('content-type')?.includes('application/json')) {
+          return sendNodeResponse(
+            res,
+            new Response(
+              JSON.stringify(
+                {
+                  status: 500,
+                  error: 'Internal Server Error',
+                  message:
+                    'An unexpected error occurred. Please try again later.',
+                  timestamp: new Date().toISOString(),
+                },
+                null,
+                2,
+              ),
+              {
+                status: 500,
+                headers: { 'Content-Type': 'application/json' },
+              },
+            ),
+          )
+        }
+
+        return sendNodeResponse(
+          res,
+          new Response(
+            `<!DOCTYPE html>
+<html lang="en">
+  <head><meta charset="UTF-8" /><title>Error</title></head>
+  <body>
+    <h1>Internal Server Error</h1>
+    <pre>${e instanceof Error ? e.message : String(e)}</pre>
+  </body>
+</html>`,
+            {
+              status: 500,
+              headers: { 'Content-Type': 'text/html' },
+            },
+          ),
+        )
+      }
+    }
+
+    // Position 1: BEFORE built-ins — intercept server function calls
+    // early so they are not swallowed by htmlFallback or assetsMiddleware.
+    context.server.middlewares.use(async (req, res, next) => {
+      const url = req.url || '/'
+      if (url.startsWith(serverFnBase)) {
+        return handleSSR(req, res, next)
+      }
+      return next()
+    })
+
+    // Position 2: AFTER built-ins, before fallback — SSR catch-all for
+    // page navigations. Assets are already handled by rsbuild middleware.
+    return () => {
+      context.server.middlewares.use(handleSSR)
+    }
+  }
+}