diff --git a/.changeset/start-compiler-yuku.md b/.changeset/start-compiler-yuku.md index 6a66c47ecd..ca12cd2b6c 100644 --- a/.changeset/start-compiler-yuku.md +++ b/.changeset/start-compiler-yuku.md @@ -24,6 +24,7 @@ Start's Vite and Rsbuild plugins run on the new compiler core instead of Babel: - **Production builds answer HTTP calls only for server functions that client code imports.** A function only server code calls (another server function, a server route), or one returned to the client as data, is refused when called over HTTP. The dev server still answers such a call and warns once per function. - `serverFns.generateFunctionId` receives the same `functionName` as before, the generated handler name (`greetUser_createServerFn_handler`, then `_1`, `_2` for a name the file repeats), so custom ids stay the same across the upgrade. Characters of a name outside `A-Z`, `a-z`, `0-9`, `_` and `$` (a non-ASCII variable name) now become `_`, so an id that embeds the name is a valid URL path segment. Server functions that aren't declared as a variable, which the compiler now also supports, take the name they're assigned to (an object property, a class field), `default` for `export default`, and `fn` otherwise. - Default production ids are shorter (22 characters). +- An id a custom `serverFns.generateFunctionId` returns must be one URL path segment: ASCII letters, digits, `-`, `.`, `_`, `~` and `$`, not `.` or `..`. Any other id fails the build with an error naming the file, the function and the id. Most such ids already failed at runtime, since the client puts the id in the URL unencoded: a `#` or `?` ended the path and a `/` cut the id short, so the call silently ran another server function of the file or none, and a space, control or non-ASCII character reached the server percent-encoded and matched no function. Ids with `%` or with other characters URLs allow (such as `:`, `@`, `+`, `=`, `,`, `;`, `!`, `*`, `(`, `)`, `&`) did reach the handler on Node, but proxies and servers may decode or rewrite them, so they now fail the build too: hash the inputs instead (the documented example does). - Server functions are recognised by binding through re-exports, namespaces, aliases, user factories and stored builders, whatever the code formatting (#7280). With SSR as the provider a server function's module evaluates once and server-side callers call it directly (#7213, #8731); the modules only its handlers import still load on the first call, like before, without running the module's code again (a handler that writes state its module reads, or one in a module that awaits at its top level, loads with its module). `createServerOnlyFn(...)` passed to `.handler()` works (#8446). Nested server functions are hoisted on the server when safe, also inside a route option `deleteNodes` removes from the server build (the client keeps the option and calls them). - Client middleware sees only the server function's id during SSR, as in the browser. - A server function defined in code the server erases (`createClientOnlyFn`, an isomorphic function's `.client()`, `` children) works: the server registers it. diff --git a/docs/start/framework/react/guide/server-functions.md b/docs/start/framework/react/guide/server-functions.md index e2f1b4179c..8320cfc801 100644 --- a/docs/start/framework/react/guide/server-functions.md +++ b/docs/start/framework/react/guide/server-functions.md @@ -435,6 +435,8 @@ The generator receives: Return `undefined` to use the default ID. Prefer deterministic inputs (filename + functionName) so IDs remain stable between builds. +The ID becomes one segment of the server function's URL (`/_serverFn/`), unencoded, so it may contain only ASCII letters, digits, `-`, `.`, `_`, `~` and `$`, and may not be `.` or `..`. Any other ID fails the build with an error naming the file, the function and the ID. `filename` contains `/`, so hash it (as in the example below) rather than embedding it as is. + Please note that this customization is **experimental** and subject to change. Example: diff --git a/packages/compiler-test-utils/oracle/SPEC.md b/packages/compiler-test-utils/oracle/SPEC.md index 371699fc46..78947f69ee 100644 --- a/packages/compiler-test-utils/oracle/SPEC.md +++ b/packages/compiler-test-utils/oracle/SPEC.md @@ -532,7 +532,9 @@ dir)` is not a conflict by itself. `serverFns.generateFunctionId({ filename, functionName })` (experimental). The form of `filename` (relative or absolute) is not specified: tests derive the expected id from the arguments received. `functionName` is the generated handler name of earlier versions (`_createServerFn_handler`, `_1`, `_2`… for a name the module - repeats, in source order; C5), so custom ids survive an upgrade, and holds only `[A-Za-z0-9_$]`. Edits change the input, so ids need not survive edits. _Dev_: an + repeats, in source order; C5), so custom ids survive an upgrade, and holds only `[A-Za-z0-9_$]`. An id the generator + returns is one URL path segment no layer rewrites (RFC 3986 unreserved characters and `$`, not `.` or `..`); any + other id fails the build, naming the file. Edits change the input, so ids need not survive edits. _Dev_: an implementation-specific lookup id is allowed; within one dev session every caller and the provider agree on it; ids need not match between dev and build (G13); `generateFunctionId` may or may not apply. A by-id request for a module the running dev server has not compiled yet (a page left open across a restart) compiles that module and is diff --git a/packages/react-start-rsc/tests/integration/rsc-app.ts b/packages/react-start-rsc/tests/integration/rsc-app.ts index a5b911935e..526ce572e2 100644 --- a/packages/react-start-rsc/tests/integration/rsc-app.ts +++ b/packages/react-start-rsc/tests/integration/rsc-app.ts @@ -290,7 +290,8 @@ async function rsbuildApi(): Promise { * as for `startRscRsbuildDevServer`), and serves the build as `rsbuild * preview` does (Start's own middleware runs the built server entry). The * test process runs with `NODE_ENV=production` until the cleanup, as for - * `startRscPreviewServer`. `errors`: what the build reported as errors. + * `startRscPreviewServer`. `errors`: what the build reported as errors + * (a failed build rejects with them, an `AggregateError`). */ export async function startRscRsbuildPreviewServer(options: { files: Record @@ -313,6 +314,29 @@ export async function startRscRsbuildPreviewServer(options: { ]), }) const reported: Array = [] + /** The compilations' errors (a silent Rsbuild prints none). */ + const compileErrors: Array = [] + const compileErrorsPlugin = { + name: 'rsc-preview-harness:compile-errors', + setup(api: { + onAfterEnvironmentCompile: ( + callback: (params: { + stats?: { + toJson: (options: object) => { + errors?: Array<{ message: string }> + } + } + }) => void, + ) => void + }) { + api.onAfterEnvironmentCompile(({ stats }) => { + for (const error of stats?.toJson({ all: false, errors: true }) + .errors ?? []) { + compileErrors.push(error.message) + } + }) + }, + } const cwd = process.cwd() const nodeEnv = process.env.NODE_ENV // In the app's directory, as `rsbuild build` and `rsbuild preview` run @@ -331,6 +355,7 @@ export async function startRscRsbuildPreviewServer(options: { ...options.start, rsc: { enabled: true }, }) as never, + compileErrorsPlugin as never, ], // Start serves the pages, not an HTML template tools: { htmlPlugin: false }, @@ -344,6 +369,19 @@ export async function startRscRsbuildPreviewServer(options: { await withBuildEnvironment('production', reported, async () => { const built = await (await rsbuild()).build() await built.close() + }).catch((error: unknown) => { + // Rsbuild's error says only that the build failed: the errors are + // its compilations' and what it reported meanwhile + throw new AggregateError( + [ + ...compileErrors, + ...reported + .filter(({ severity }) => severity === 'error') + .map(({ text }) => text), + ], + error instanceof Error ? error.message : String(error), + { cause: error }, + ) }) process.env.NODE_ENV = 'production' const { server, urls } = await ( diff --git a/packages/react-start-rsc/tests/integration/rsc-start-build-function-id.test.ts b/packages/react-start-rsc/tests/integration/rsc-start-build-function-id.test.ts new file mode 100644 index 0000000000..e0235958cd --- /dev/null +++ b/packages/react-start-rsc/tests/integration/rsc-start-build-function-id.test.ts @@ -0,0 +1,42 @@ +/** + * With RSC the provider environment builds first and gives the server fns + * their ids (SPEC J4.4): an id a custom `generateFunctionId` returns that is + * not one URL path segment fails the production build there too, with an + * error naming the defining file, on Vite and on Rsbuild. + */ +import { describe, expect, test } from 'vitest' +import { expectDiagnostic } from '@tanstack/compiler-test-utils/diagnostics' +import { startRscPreviewServer, startRscRsbuildPreviewServer } from './rsc-app' + +const files = { + 'src/fns.ts': `import { createServerFn } from '@tanstack/react-start' +export const greet = createServerFn().handler(async () => 'MARK_HANDLER') +`, + 'src/routes/index.tsx': `import { createFileRoute } from '@tanstack/react-router' +import { greet } from '../fns' +export const Route = createFileRoute('/')({ + component: () => , +}) +`, +} + +const start = { + serverFns: { + generateFunctionId: ({ filename }: { filename: string }) => + filename.endsWith('src/fns.ts') ? 'fns/greet' : undefined, + }, +} + +describe.each([ + ['vite', startRscPreviewServer], + ['rsbuild', startRscRsbuildPreviewServer], +] as const)('%s', (_bundler, startServer) => { + test('an id that is not one URL path segment fails the build, naming the file', async () => { + const failure = await startServer({ files, start }).then( + () => undefined, + (error: unknown) => error, + ) + expect(failure, 'the build failed').toBeDefined() + expectDiagnostic(failure, { severity: 'error', file: 'src/fns.ts' }) + }, 60_000) +}) diff --git a/packages/start-plugin-core/src/compiler/session.ts b/packages/start-plugin-core/src/compiler/session.ts index 8b2b3ca33e..dabbf8db83 100644 --- a/packages/start-plugin-core/src/compiler/session.ts +++ b/packages/start-plugin-core/src/compiler/session.ts @@ -475,16 +475,24 @@ export class StartCompilerSession { ) } - /** The id allocator with an environment's rank allocated (a custom generator): a client build's client-referenced functions first, the rest after. */ - allocateIds(envType: 'client' | 'server'): FunctionIdAllocator { + /** + * The id allocator with an environment's rank allocated (a custom + * generator): a client build's client-referenced functions first, the + * rest after. `errors`: the rank's custom ids that are not a URL path + * segment (the host fails the build with them). + */ + allocateIds(envType: 'client' | 'server'): { + allocator: FunctionIdAllocator + errors: Array + } { const allocator = this.allocator! const entries = this.registry.entries() - allocator.allocate( + const errors = allocator.allocate( envType === 'client' ? entries.filter((e) => e.clientReferenced) : entries, ) - return allocator + return { allocator, errors } } /** diff --git a/packages/start-plugin-core/src/rsbuild/host-plugin.ts b/packages/start-plugin-core/src/rsbuild/host-plugin.ts index f986a12c1e..1def9c0d4f 100644 --- a/packages/start-plugin-core/src/rsbuild/host-plugin.ts +++ b/packages/start-plugin-core/src/rsbuild/host-plugin.ts @@ -448,7 +448,12 @@ export function createStartHostPlugin(opts: StartHostPluginOptions): { /** Custom server-fn ids: this environment's rank, patched before minification. */ function patchFunctionIds(compilation: Rspack.Compilation): void { - const allocator = session.start.allocateIds(environment.type) + const { allocator, errors } = session.start.allocateIds( + environment.type, + ) + for (const error of errors) { + compilation.errors.push(new WebpackError(error)) + } for (const asset of compilation.getAssets()) { if (!/\.[cm]?js$/.test(asset.name)) { continue diff --git a/packages/start-plugin-core/src/server-fns/ids.ts b/packages/start-plugin-core/src/server-fns/ids.ts index 2adbc9d3b0..98209c69eb 100644 --- a/packages/start-plugin-core/src/server-fns/ids.ts +++ b/packages/start-plugin-core/src/server-fns/ids.ts @@ -91,6 +91,19 @@ export type GenerateFunctionId = (opts: { functionName: string }) => string | undefined +/** + * An id the URL carries whole as one path segment (`TSS_SERVER_FN_BASE + id` + * unencoded; the server reads the segment back as is): RFC 3986 unreserved + * characters, which no client, proxy or server encodes, decodes or + * normalises, and `$`, which `functionName` can hold; not a dot segment, + * which URL parsing removes. + */ +const URL_SEGMENT_ID = /^[A-Za-z0-9\-._~$]+$/ + +function isUrlSegmentId(id: string): boolean { + return URL_SEGMENT_ID.test(id) && id !== '.' && id !== '..' +} + /** * One immutable allocation of final ids against a global occupied set: * the client rank first (sorted stable keys, frozen; under RSC the provider @@ -101,34 +114,54 @@ export type GenerateFunctionId = (opts: { export class FunctionIdAllocator { private readonly occupied = new Set() private readonly final = new Map() + /** The error of each placeholder token whose custom id is not a URL path segment. */ + private readonly invalid = new Map() constructor(private readonly generate: GenerateFunctionId | undefined) {} - /** Allocates the entries of one rank (those not yet allocated), in sorted key order. */ - allocate(entries: Array): void { + /** + * Allocates the entries of one rank (those not yet allocated), in sorted + * key order. Returns an error for each entry of the rank whose custom id + * is not a URL path segment (also when an earlier call allocated it: a + * rebuild reports it again). + */ + allocate( + entries: Array, + ): Array { const sorted = [...entries].sort( (a, b) => (a.rootRel < b.rootRel ? -1 : a.rootRel > b.rootRel ? 1 : 0) || (a.stableKey < b.stableKey ? -1 : a.stableKey > b.stableKey ? 1 : 0), ) + const errors: Array = [] for (const e of sorted) { const token = placeholderToken(e) - if (this.final.has(token)) { - continue - } - const base = - this.generate?.({ + if (!this.final.has(token)) { + const custom = this.generate?.({ filename: e.rootRel, functionName: e.functionName, - }) ?? defaultFunctionId(e) - let cand = base - let n = 1 - while (this.occupied.has(cand)) { - cand = `${base}_${n++}` + }) + if (custom !== undefined && !isUrlSegmentId(custom)) { + this.invalid.set( + token, + `[tanstack-start] serverFns.generateFunctionId returned ${JSON.stringify(custom)} for the server function ${e.name} (functionName "${e.functionName}") of ${e.rootRel}. A server function id is one path segment of its URL: use only ASCII letters, digits, "-", ".", "_", "~" and "$" (not "." or "..").`, + ) + } + const base = custom ?? defaultFunctionId(e) + let cand = base + let n = 1 + while (this.occupied.has(cand)) { + cand = `${base}_${n++}` + } + this.occupied.add(cand) + this.final.set(token, cand) + } + const error = this.invalid.get(token) + if (error !== undefined) { + errors.push(error) } - this.occupied.add(cand) - this.final.set(token, cand) } + return errors } /** Replaces every placeholder of `code`; unknown tokens are left (a diagnostic for the host). */ diff --git a/packages/start-plugin-core/src/vite/compiler-plugin.ts b/packages/start-plugin-core/src/vite/compiler-plugin.ts index 88bdb758f3..a4ddc211b9 100644 --- a/packages/start-plugin-core/src/vite/compiler-plugin.ts +++ b/packages/start-plugin-core/src/vite/compiler-plugin.ts @@ -1026,7 +1026,11 @@ export function startCompilerPlugin( if (!s.start.allocator || !code.includes('__TSS_FN_ID_')) { return null } - const patched = s.start.allocateIds(env.type).patch(code) + const { allocator, errors } = s.start.allocateIds(env.type) + if (errors.length > 0) { + this.error({ message: errors.join('\n') }) + } + const patched = allocator.patch(code) if (patched.missing.length > 0) { this.error({ message: `Server function ids could not be resolved in ${chunk.fileName}: ${patched.missing.join(', ')}`, diff --git a/packages/start-plugin-core/tests/integration/start-build-function-id-url.test.ts b/packages/start-plugin-core/tests/integration/start-build-function-id-url.test.ts new file mode 100644 index 0000000000..a41e417c30 --- /dev/null +++ b/packages/start-plugin-core/tests/integration/start-build-function-id-url.test.ts @@ -0,0 +1,90 @@ +/** + * A server fn's id is one path segment of its URL (SPEC J4.4): the client + * puts it after the server fn base unencoded and the server reads the + * segment back. An id a custom `generateFunctionId` returns that the URL + * cannot carry whole (a `/` or `#` that splits or ends it, `?`, `%`, + * whitespace, a control or non-ASCII character a client percent-encodes, + * a dot segment) fails the build with an error naming the defining file, + * instead of a client that calls another function or none. An id of + * unreserved characters and `$` builds. + */ +import { describe, expect, test } from 'vitest' +import { + expectDiagnostic, + findDiagnostics, +} from '@tanstack/compiler-test-utils/diagnostics' +import { StartBuildError, buildStart, startBundlers } from '../build-harness' + +const timeout = 60_000 + +/** The id the generator returns for each file. */ +const ids: Record = { + 'src/slash.ts': 'users/get', + 'src/hash.ts': 'users#get', + 'src/query.ts': 'users?get', + 'src/percent.ts': 'users%2Fget', + 'src/space.ts': 'users get', + 'src/control.ts': 'users\u0007get', + 'src/non-ascii.ts': 'utilisateurs-é', + 'src/colon.ts': 'users:get', + 'src/dot.ts': '..', + 'src/fine.ts': 'Users-get.v1_~$', +} + +const fnModule = (file: string) => + `import { createServerFn } from '@tanstack/react-start' +export const fn = createServerFn().handler(async () => ${JSON.stringify(file)}) +` + +describe.each(startBundlers)('%s build', (bundler) => { + test( + 'an id that is not one URL path segment fails the build, naming the file', + async () => { + const files: Record = {} + const entry: Array = [] + Object.keys(ids).forEach((file, index) => { + files[file] = fnModule(file) + entry.push( + `export { fn as fn${index} } from './${file.slice('src/'.length, -'.ts'.length)}'`, + ) + }) + files['src/entry.ts'] = `${entry.join('\n')}\n` + const outcome = await buildStart({ + bundler, + files, + entry: 'src/entry.ts', + start: { + serverFns: { + generateFunctionId: ({ filename }) => + ids[ + Object.keys(ids).find((file) => filename.endsWith(file)) ?? '' + ], + }, + }, + }).then( + () => ({ built: true as const }), + (error: unknown) => { + if (!(error instanceof StartBuildError)) { + throw error + } + return { built: false as const, error } + }, + ) + if (outcome.built) { + expect.fail('the build succeeded') + } + const { diagnostics, root } = outcome.error + for (const file of Object.keys(ids)) { + if (file === 'src/fine.ts') { + expect( + findDiagnostics(diagnostics, { severity: 'error', file, root }), + `errors naming ${file}`, + ).toEqual([]) + } else { + expectDiagnostic(diagnostics, { severity: 'error', file, root }) + } + } + }, + timeout, + ) +}) diff --git a/packages/start-plugin-core/tests/integration/start-compiler-build-custom-ids.test.ts b/packages/start-plugin-core/tests/integration/start-compiler-build-custom-ids.test.ts index 49af75046f..0abd267aab 100644 --- a/packages/start-plugin-core/tests/integration/start-compiler-build-custom-ids.test.ts +++ b/packages/start-plugin-core/tests/integration/start-compiler-build-custom-ids.test.ts @@ -91,9 +91,8 @@ describe('a custom generateFunctionId', () => { }) => { if (filename.includes('custom-ids')) { // URL-safe: the id is a path segment of the server fn's url - // (an id with a '/' is not routed back to its handler by - // Start's runtime: a runtime limitation, not this test's - // subject) + // (any other id fails the build: + // start-build-function-id-url.test.ts) const id = `custom_${Buffer.from(`${filename}:${functionName}`).toString('hex')}` returned.push(id) return id