From ea12d137b2980fcc6a2ef341667fc6167d142b53 Mon Sep 17 00:00:00 2001 From: Manuel Schiller Date: Mon, 16 Mar 2026 19:34:15 +0100 Subject: [PATCH] feat: server function middleware short circuit --- .../server-functions/src/routeTree.gen.ts | 156 ++++++ .../routes/middleware/client-conditional.tsx | 183 +++++++ .../routes/middleware/client-early-return.tsx | 119 +++++ .../client-source-classification.tsx | 205 ++++++++ .../src/routes/middleware/index.tsx | 56 +++ .../routes/middleware/nested-early-return.tsx | 235 +++++++++ .../routes/middleware/server-conditional.tsx | 185 ++++++++ .../server-early-return-headers.tsx | 117 +++++ .../routes/middleware/server-early-return.tsx | 200 ++++++++ .../tests/server-functions.spec.ts | 335 +++++++++++++ .../start-client-core/src/createMiddleware.ts | 2 + .../start-client-core/src/createServerFn.ts | 449 ++++++++++++++---- packages/start-client-core/src/index.tsx | 3 +- .../tests/createServerFn.runtime.test.ts | 95 ++++ .../src/start-compiler-plugin/compiler.ts | 18 +- .../handleCreateMiddleware.ts | 58 ++- .../src/start-compiler-plugin/types.ts | 1 + .../start-plugin-core/tests/compiler.test.ts | 39 +- .../client/createMiddlewareClientOnly.tsx | 21 + .../test-files/createMiddlewareClientOnly.tsx | 17 + .../src/createStartHandler.ts | 22 +- .../src/server-functions-handler.ts | 36 +- 22 files changed, 2421 insertions(+), 131 deletions(-) create mode 100644 e2e/react-start/server-functions/src/routes/middleware/client-conditional.tsx create mode 100644 e2e/react-start/server-functions/src/routes/middleware/client-early-return.tsx create mode 100644 e2e/react-start/server-functions/src/routes/middleware/client-source-classification.tsx create mode 100644 e2e/react-start/server-functions/src/routes/middleware/nested-early-return.tsx create mode 100644 e2e/react-start/server-functions/src/routes/middleware/server-conditional.tsx create mode 100644 e2e/react-start/server-functions/src/routes/middleware/server-early-return-headers.tsx create mode 100644 e2e/react-start/server-functions/src/routes/middleware/server-early-return.tsx create mode 100644 packages/start-client-core/tests/createServerFn.runtime.test.ts create mode 100644 packages/start-plugin-core/tests/createMiddleware/snapshots/client/createMiddlewareClientOnly.tsx create mode 100644 packages/start-plugin-core/tests/createMiddleware/test-files/createMiddlewareClientOnly.tsx diff --git a/e2e/react-start/server-functions/src/routeTree.gen.ts b/e2e/react-start/server-functions/src/routeTree.gen.ts index 249a9c42ce..cd69f5c785 100644 --- a/e2e/react-start/server-functions/src/routeTree.gen.ts +++ b/e2e/react-start/server-functions/src/routeTree.gen.ts @@ -41,11 +41,18 @@ import { Route as RedirectTestTargetRouteImport } from './routes/redirect-test/t import { Route as RedirectTestSsrTargetRouteImport } from './routes/redirect-test-ssr/target' import { Route as MiddlewareUnhandledExceptionRouteImport } from './routes/middleware/unhandled-exception' import { Route as MiddlewareServerImportMiddlewareRouteImport } from './routes/middleware/server-import-middleware' +import { Route as MiddlewareServerEarlyReturnHeadersRouteImport } from './routes/middleware/server-early-return-headers' +import { Route as MiddlewareServerEarlyReturnRouteImport } from './routes/middleware/server-early-return' +import { Route as MiddlewareServerConditionalRouteImport } from './routes/middleware/server-conditional' import { Route as MiddlewareSendServerFnRouteImport } from './routes/middleware/send-serverFn' import { Route as MiddlewareRequestMiddlewareRouteImport } from './routes/middleware/request-middleware' +import { Route as MiddlewareNestedEarlyReturnRouteImport } from './routes/middleware/nested-early-return' import { Route as MiddlewareMiddlewareFactoryRouteImport } from './routes/middleware/middleware-factory' import { Route as MiddlewareFunctionMetadataRouteImport } from './routes/middleware/function-metadata' +import { Route as MiddlewareClientSourceClassificationRouteImport } from './routes/middleware/client-source-classification' import { Route as MiddlewareClientMiddlewareRouterRouteImport } from './routes/middleware/client-middleware-router' +import { Route as MiddlewareClientEarlyReturnRouteImport } from './routes/middleware/client-early-return' +import { Route as MiddlewareClientConditionalRouteImport } from './routes/middleware/client-conditional' import { Route as MiddlewareCatchHandlerErrorRouteImport } from './routes/middleware/catch-handler-error' import { Route as MethodNotAllowedMethodRouteImport } from './routes/method-not-allowed/$method' import { Route as CookiesSetRouteImport } from './routes/cookies/set' @@ -216,6 +223,24 @@ const MiddlewareServerImportMiddlewareRoute = path: '/middleware/server-import-middleware', getParentRoute: () => rootRouteImport, } as any) +const MiddlewareServerEarlyReturnHeadersRoute = + MiddlewareServerEarlyReturnHeadersRouteImport.update({ + id: '/middleware/server-early-return-headers', + path: '/middleware/server-early-return-headers', + getParentRoute: () => rootRouteImport, + } as any) +const MiddlewareServerEarlyReturnRoute = + MiddlewareServerEarlyReturnRouteImport.update({ + id: '/middleware/server-early-return', + path: '/middleware/server-early-return', + getParentRoute: () => rootRouteImport, + } as any) +const MiddlewareServerConditionalRoute = + MiddlewareServerConditionalRouteImport.update({ + id: '/middleware/server-conditional', + path: '/middleware/server-conditional', + getParentRoute: () => rootRouteImport, + } as any) const MiddlewareSendServerFnRoute = MiddlewareSendServerFnRouteImport.update({ id: '/middleware/send-serverFn', path: '/middleware/send-serverFn', @@ -227,6 +252,12 @@ const MiddlewareRequestMiddlewareRoute = path: '/middleware/request-middleware', getParentRoute: () => rootRouteImport, } as any) +const MiddlewareNestedEarlyReturnRoute = + MiddlewareNestedEarlyReturnRouteImport.update({ + id: '/middleware/nested-early-return', + path: '/middleware/nested-early-return', + getParentRoute: () => rootRouteImport, + } as any) const MiddlewareMiddlewareFactoryRoute = MiddlewareMiddlewareFactoryRouteImport.update({ id: '/middleware/middleware-factory', @@ -239,12 +270,30 @@ const MiddlewareFunctionMetadataRoute = path: '/middleware/function-metadata', getParentRoute: () => rootRouteImport, } as any) +const MiddlewareClientSourceClassificationRoute = + MiddlewareClientSourceClassificationRouteImport.update({ + id: '/middleware/client-source-classification', + path: '/middleware/client-source-classification', + getParentRoute: () => rootRouteImport, + } as any) const MiddlewareClientMiddlewareRouterRoute = MiddlewareClientMiddlewareRouterRouteImport.update({ id: '/middleware/client-middleware-router', path: '/middleware/client-middleware-router', getParentRoute: () => rootRouteImport, } as any) +const MiddlewareClientEarlyReturnRoute = + MiddlewareClientEarlyReturnRouteImport.update({ + id: '/middleware/client-early-return', + path: '/middleware/client-early-return', + getParentRoute: () => rootRouteImport, + } as any) +const MiddlewareClientConditionalRoute = + MiddlewareClientConditionalRouteImport.update({ + id: '/middleware/client-conditional', + path: '/middleware/client-conditional', + getParentRoute: () => rootRouteImport, + } as any) const MiddlewareCatchHandlerErrorRoute = MiddlewareCatchHandlerErrorRouteImport.update({ id: '/middleware/catch-handler-error', @@ -307,11 +356,18 @@ export interface FileRoutesByFullPath { '/cookies/set': typeof CookiesSetRoute '/method-not-allowed/$method': typeof MethodNotAllowedMethodRoute '/middleware/catch-handler-error': typeof MiddlewareCatchHandlerErrorRoute + '/middleware/client-conditional': typeof MiddlewareClientConditionalRoute + '/middleware/client-early-return': typeof MiddlewareClientEarlyReturnRoute '/middleware/client-middleware-router': typeof MiddlewareClientMiddlewareRouterRoute + '/middleware/client-source-classification': typeof MiddlewareClientSourceClassificationRoute '/middleware/function-metadata': typeof MiddlewareFunctionMetadataRoute '/middleware/middleware-factory': typeof MiddlewareMiddlewareFactoryRoute + '/middleware/nested-early-return': typeof MiddlewareNestedEarlyReturnRoute '/middleware/request-middleware': typeof MiddlewareRequestMiddlewareRoute '/middleware/send-serverFn': typeof MiddlewareSendServerFnRoute + '/middleware/server-conditional': typeof MiddlewareServerConditionalRoute + '/middleware/server-early-return': typeof MiddlewareServerEarlyReturnRoute + '/middleware/server-early-return-headers': typeof MiddlewareServerEarlyReturnHeadersRoute '/middleware/server-import-middleware': typeof MiddlewareServerImportMiddlewareRoute '/middleware/unhandled-exception': typeof MiddlewareUnhandledExceptionRoute '/redirect-test-ssr/target': typeof RedirectTestSsrTargetRoute @@ -353,11 +409,18 @@ export interface FileRoutesByTo { '/cookies/set': typeof CookiesSetRoute '/method-not-allowed/$method': typeof MethodNotAllowedMethodRoute '/middleware/catch-handler-error': typeof MiddlewareCatchHandlerErrorRoute + '/middleware/client-conditional': typeof MiddlewareClientConditionalRoute + '/middleware/client-early-return': typeof MiddlewareClientEarlyReturnRoute '/middleware/client-middleware-router': typeof MiddlewareClientMiddlewareRouterRoute + '/middleware/client-source-classification': typeof MiddlewareClientSourceClassificationRoute '/middleware/function-metadata': typeof MiddlewareFunctionMetadataRoute '/middleware/middleware-factory': typeof MiddlewareMiddlewareFactoryRoute + '/middleware/nested-early-return': typeof MiddlewareNestedEarlyReturnRoute '/middleware/request-middleware': typeof MiddlewareRequestMiddlewareRoute '/middleware/send-serverFn': typeof MiddlewareSendServerFnRoute + '/middleware/server-conditional': typeof MiddlewareServerConditionalRoute + '/middleware/server-early-return': typeof MiddlewareServerEarlyReturnRoute + '/middleware/server-early-return-headers': typeof MiddlewareServerEarlyReturnHeadersRoute '/middleware/server-import-middleware': typeof MiddlewareServerImportMiddlewareRoute '/middleware/unhandled-exception': typeof MiddlewareUnhandledExceptionRoute '/redirect-test-ssr/target': typeof RedirectTestSsrTargetRoute @@ -400,11 +463,18 @@ export interface FileRoutesById { '/cookies/set': typeof CookiesSetRoute '/method-not-allowed/$method': typeof MethodNotAllowedMethodRoute '/middleware/catch-handler-error': typeof MiddlewareCatchHandlerErrorRoute + '/middleware/client-conditional': typeof MiddlewareClientConditionalRoute + '/middleware/client-early-return': typeof MiddlewareClientEarlyReturnRoute '/middleware/client-middleware-router': typeof MiddlewareClientMiddlewareRouterRoute + '/middleware/client-source-classification': typeof MiddlewareClientSourceClassificationRoute '/middleware/function-metadata': typeof MiddlewareFunctionMetadataRoute '/middleware/middleware-factory': typeof MiddlewareMiddlewareFactoryRoute + '/middleware/nested-early-return': typeof MiddlewareNestedEarlyReturnRoute '/middleware/request-middleware': typeof MiddlewareRequestMiddlewareRoute '/middleware/send-serverFn': typeof MiddlewareSendServerFnRoute + '/middleware/server-conditional': typeof MiddlewareServerConditionalRoute + '/middleware/server-early-return': typeof MiddlewareServerEarlyReturnRoute + '/middleware/server-early-return-headers': typeof MiddlewareServerEarlyReturnHeadersRoute '/middleware/server-import-middleware': typeof MiddlewareServerImportMiddlewareRoute '/middleware/unhandled-exception': typeof MiddlewareUnhandledExceptionRoute '/redirect-test-ssr/target': typeof RedirectTestSsrTargetRoute @@ -448,11 +518,18 @@ export interface FileRouteTypes { | '/cookies/set' | '/method-not-allowed/$method' | '/middleware/catch-handler-error' + | '/middleware/client-conditional' + | '/middleware/client-early-return' | '/middleware/client-middleware-router' + | '/middleware/client-source-classification' | '/middleware/function-metadata' | '/middleware/middleware-factory' + | '/middleware/nested-early-return' | '/middleware/request-middleware' | '/middleware/send-serverFn' + | '/middleware/server-conditional' + | '/middleware/server-early-return' + | '/middleware/server-early-return-headers' | '/middleware/server-import-middleware' | '/middleware/unhandled-exception' | '/redirect-test-ssr/target' @@ -494,11 +571,18 @@ export interface FileRouteTypes { | '/cookies/set' | '/method-not-allowed/$method' | '/middleware/catch-handler-error' + | '/middleware/client-conditional' + | '/middleware/client-early-return' | '/middleware/client-middleware-router' + | '/middleware/client-source-classification' | '/middleware/function-metadata' | '/middleware/middleware-factory' + | '/middleware/nested-early-return' | '/middleware/request-middleware' | '/middleware/send-serverFn' + | '/middleware/server-conditional' + | '/middleware/server-early-return' + | '/middleware/server-early-return-headers' | '/middleware/server-import-middleware' | '/middleware/unhandled-exception' | '/redirect-test-ssr/target' @@ -540,11 +624,18 @@ export interface FileRouteTypes { | '/cookies/set' | '/method-not-allowed/$method' | '/middleware/catch-handler-error' + | '/middleware/client-conditional' + | '/middleware/client-early-return' | '/middleware/client-middleware-router' + | '/middleware/client-source-classification' | '/middleware/function-metadata' | '/middleware/middleware-factory' + | '/middleware/nested-early-return' | '/middleware/request-middleware' | '/middleware/send-serverFn' + | '/middleware/server-conditional' + | '/middleware/server-early-return' + | '/middleware/server-early-return-headers' | '/middleware/server-import-middleware' | '/middleware/unhandled-exception' | '/redirect-test-ssr/target' @@ -587,11 +678,18 @@ export interface RootRouteChildren { CookiesSetRoute: typeof CookiesSetRoute MethodNotAllowedMethodRoute: typeof MethodNotAllowedMethodRoute MiddlewareCatchHandlerErrorRoute: typeof MiddlewareCatchHandlerErrorRoute + MiddlewareClientConditionalRoute: typeof MiddlewareClientConditionalRoute + MiddlewareClientEarlyReturnRoute: typeof MiddlewareClientEarlyReturnRoute MiddlewareClientMiddlewareRouterRoute: typeof MiddlewareClientMiddlewareRouterRoute + MiddlewareClientSourceClassificationRoute: typeof MiddlewareClientSourceClassificationRoute MiddlewareFunctionMetadataRoute: typeof MiddlewareFunctionMetadataRoute MiddlewareMiddlewareFactoryRoute: typeof MiddlewareMiddlewareFactoryRoute + MiddlewareNestedEarlyReturnRoute: typeof MiddlewareNestedEarlyReturnRoute MiddlewareRequestMiddlewareRoute: typeof MiddlewareRequestMiddlewareRoute MiddlewareSendServerFnRoute: typeof MiddlewareSendServerFnRoute + MiddlewareServerConditionalRoute: typeof MiddlewareServerConditionalRoute + MiddlewareServerEarlyReturnRoute: typeof MiddlewareServerEarlyReturnRoute + MiddlewareServerEarlyReturnHeadersRoute: typeof MiddlewareServerEarlyReturnHeadersRoute MiddlewareServerImportMiddlewareRoute: typeof MiddlewareServerImportMiddlewareRoute MiddlewareUnhandledExceptionRoute: typeof MiddlewareUnhandledExceptionRoute RedirectTestSsrTargetRoute: typeof RedirectTestSsrTargetRoute @@ -838,6 +936,27 @@ declare module '@tanstack/react-router' { preLoaderRoute: typeof MiddlewareServerImportMiddlewareRouteImport parentRoute: typeof rootRouteImport } + '/middleware/server-early-return-headers': { + id: '/middleware/server-early-return-headers' + path: '/middleware/server-early-return-headers' + fullPath: '/middleware/server-early-return-headers' + preLoaderRoute: typeof MiddlewareServerEarlyReturnHeadersRouteImport + parentRoute: typeof rootRouteImport + } + '/middleware/server-early-return': { + id: '/middleware/server-early-return' + path: '/middleware/server-early-return' + fullPath: '/middleware/server-early-return' + preLoaderRoute: typeof MiddlewareServerEarlyReturnRouteImport + parentRoute: typeof rootRouteImport + } + '/middleware/server-conditional': { + id: '/middleware/server-conditional' + path: '/middleware/server-conditional' + fullPath: '/middleware/server-conditional' + preLoaderRoute: typeof MiddlewareServerConditionalRouteImport + parentRoute: typeof rootRouteImport + } '/middleware/send-serverFn': { id: '/middleware/send-serverFn' path: '/middleware/send-serverFn' @@ -852,6 +971,13 @@ declare module '@tanstack/react-router' { preLoaderRoute: typeof MiddlewareRequestMiddlewareRouteImport parentRoute: typeof rootRouteImport } + '/middleware/nested-early-return': { + id: '/middleware/nested-early-return' + path: '/middleware/nested-early-return' + fullPath: '/middleware/nested-early-return' + preLoaderRoute: typeof MiddlewareNestedEarlyReturnRouteImport + parentRoute: typeof rootRouteImport + } '/middleware/middleware-factory': { id: '/middleware/middleware-factory' path: '/middleware/middleware-factory' @@ -866,6 +992,13 @@ declare module '@tanstack/react-router' { preLoaderRoute: typeof MiddlewareFunctionMetadataRouteImport parentRoute: typeof rootRouteImport } + '/middleware/client-source-classification': { + id: '/middleware/client-source-classification' + path: '/middleware/client-source-classification' + fullPath: '/middleware/client-source-classification' + preLoaderRoute: typeof MiddlewareClientSourceClassificationRouteImport + parentRoute: typeof rootRouteImport + } '/middleware/client-middleware-router': { id: '/middleware/client-middleware-router' path: '/middleware/client-middleware-router' @@ -873,6 +1006,20 @@ declare module '@tanstack/react-router' { preLoaderRoute: typeof MiddlewareClientMiddlewareRouterRouteImport parentRoute: typeof rootRouteImport } + '/middleware/client-early-return': { + id: '/middleware/client-early-return' + path: '/middleware/client-early-return' + fullPath: '/middleware/client-early-return' + preLoaderRoute: typeof MiddlewareClientEarlyReturnRouteImport + parentRoute: typeof rootRouteImport + } + '/middleware/client-conditional': { + id: '/middleware/client-conditional' + path: '/middleware/client-conditional' + fullPath: '/middleware/client-conditional' + preLoaderRoute: typeof MiddlewareClientConditionalRouteImport + parentRoute: typeof rootRouteImport + } '/middleware/catch-handler-error': { id: '/middleware/catch-handler-error' path: '/middleware/catch-handler-error' @@ -947,11 +1094,20 @@ const rootRouteChildren: RootRouteChildren = { CookiesSetRoute: CookiesSetRoute, MethodNotAllowedMethodRoute: MethodNotAllowedMethodRoute, MiddlewareCatchHandlerErrorRoute: MiddlewareCatchHandlerErrorRoute, + MiddlewareClientConditionalRoute: MiddlewareClientConditionalRoute, + MiddlewareClientEarlyReturnRoute: MiddlewareClientEarlyReturnRoute, MiddlewareClientMiddlewareRouterRoute: MiddlewareClientMiddlewareRouterRoute, + MiddlewareClientSourceClassificationRoute: + MiddlewareClientSourceClassificationRoute, MiddlewareFunctionMetadataRoute: MiddlewareFunctionMetadataRoute, MiddlewareMiddlewareFactoryRoute: MiddlewareMiddlewareFactoryRoute, + MiddlewareNestedEarlyReturnRoute: MiddlewareNestedEarlyReturnRoute, MiddlewareRequestMiddlewareRoute: MiddlewareRequestMiddlewareRoute, MiddlewareSendServerFnRoute: MiddlewareSendServerFnRoute, + MiddlewareServerConditionalRoute: MiddlewareServerConditionalRoute, + MiddlewareServerEarlyReturnRoute: MiddlewareServerEarlyReturnRoute, + MiddlewareServerEarlyReturnHeadersRoute: + MiddlewareServerEarlyReturnHeadersRoute, MiddlewareServerImportMiddlewareRoute: MiddlewareServerImportMiddlewareRoute, MiddlewareUnhandledExceptionRoute: MiddlewareUnhandledExceptionRoute, RedirectTestSsrTargetRoute: RedirectTestSsrTargetRoute, diff --git a/e2e/react-start/server-functions/src/routes/middleware/client-conditional.tsx b/e2e/react-start/server-functions/src/routes/middleware/client-conditional.tsx new file mode 100644 index 0000000000..8f5765ee88 --- /dev/null +++ b/e2e/react-start/server-functions/src/routes/middleware/client-conditional.tsx @@ -0,0 +1,183 @@ +import { createFileRoute } from '@tanstack/react-router' +import { createMiddleware, createServerFn } from '@tanstack/react-start' +import React from 'react' + +/** + * This middleware's .client() conditionally calls next() OR returns a value. + * If `shouldShortCircuit` is true in the data, it returns early on the client. + * Otherwise, it calls next() which proceeds to the server. + */ +const clientConditionalMiddleware = createMiddleware({ + type: 'function', +}) + .inputValidator( + (input: { shouldShortCircuit: boolean; value: string }) => input, + ) + .client(async ({ data, next, result }) => { + if (data.shouldShortCircuit) { + return result({ + data: { + source: 'client-middleware', + message: 'Conditional early return from client middleware', + condition: 'shouldShortCircuit=true', + timestamp: Date.now(), + }, + }) + } + // Proceed to server + return next({ + sendContext: { + clientTimestamp: Date.now(), + }, + }) + }) + +const serverFn = createServerFn() + .middleware([clientConditionalMiddleware]) + .handler(({ data, context }) => { + return { + source: 'handler', + message: 'Handler was called on server', + receivedData: data, + receivedContext: context, + } + }) + +export const Route = createFileRoute('/middleware/client-conditional')({ + loader: async () => { + // In loader (server-side), client middleware may not apply the same way + const result = await serverFn({ + data: { shouldShortCircuit: false, value: 'loader-value' }, + }) + return { loaderResult: result } + }, + component: RouteComponent, +}) + +function RouteComponent() { + const { loaderResult } = Route.useLoaderData() + const [clientShortCircuit, setClientShortCircuit] = React.useState(null) + const [clientNext, setClientNext] = React.useState(null) + + const expectedShortCircuit = { + source: 'client-middleware', + message: 'Conditional early return from client middleware', + condition: 'shouldShortCircuit=true', + } + + const expectedNext = { + source: 'handler', + message: 'Handler was called on server', + } + + return ( +
+

+ Client Middleware Conditional Return +

+

+ Tests that a .client() middleware can conditionally call next() OR + return a value based on input data. Short-circuit avoids network + request. +

+ +
+

Loader Result (SSR):

+
+          {JSON.stringify(loaderResult)}
+        
+
+ +
+
+

+ Short-Circuit Branch (Client-only) +

+ +
+

Expected (partial):

+
+              {JSON.stringify(expectedShortCircuit)}
+            
+
+ + + +
+

Client Result:

+
+              {clientShortCircuit
+                ? JSON.stringify(clientShortCircuit)
+                : 'Not called yet'}
+            
+
+
+ +
+

Next() Branch (Goes to Server)

+ +
+

Expected (partial):

+
+              {JSON.stringify(expectedNext)}
+            
+
+ + + +
+

Client Result:

+
+              {clientNext ? JSON.stringify(clientNext) : 'Not called yet'}
+            
+
+
+
+ +
+

Note:

+

+ Short-circuit branch should NOT make a network request. Next() branch + should make a network request to the server. +

+
+
+ ) +} diff --git a/e2e/react-start/server-functions/src/routes/middleware/client-early-return.tsx b/e2e/react-start/server-functions/src/routes/middleware/client-early-return.tsx new file mode 100644 index 0000000000..b48e3fc3ad --- /dev/null +++ b/e2e/react-start/server-functions/src/routes/middleware/client-early-return.tsx @@ -0,0 +1,119 @@ +import { createFileRoute } from '@tanstack/react-router' +import { createMiddleware, createServerFn } from '@tanstack/react-start' +import React from 'react' + +/** + * This middleware's .client() does NOT call next() at all + * and always returns a value directly. + * + * Expected behavior: The server function should never be called on the server, + * and the middleware's return value should be the result. + * + * Note: This means no network request to the server should happen. + */ +const clientEarlyReturnMiddleware = createMiddleware({ + type: 'function', +}).client(async ({ result }) => { + return result({ + data: { + source: 'client-middleware', + message: 'Early return from client middleware', + timestamp: Date.now(), + }, + }) +}) + +const serverFn = createServerFn() + .middleware([clientEarlyReturnMiddleware]) + .handler(() => { + // This handler should NEVER be called because client middleware returns early + return { + source: 'handler', + message: 'This should not be returned - server was called!', + } + }) + +export const Route = createFileRoute('/middleware/client-early-return')({ + // Note: In SSR context, client middleware may behave differently + // The loader runs on the server, so client middleware doesn't apply the same way + loader: async () => { + const result = await serverFn() + return { loaderResult: result } + }, + component: RouteComponent, +}) + +function RouteComponent() { + const { loaderResult } = Route.useLoaderData() + const [clientResult, setClientResult] = React.useState(null) + + // When called from client, we expect the client middleware to short-circuit + const expectedClientResult = { + source: 'client-middleware', + message: 'Early return from client middleware', + } + + return ( +
+

+ Client Middleware Early Return (No next() call) +

+

+ Tests that a .client() middleware can return a value without calling + next(), effectively short-circuiting before the server is even called. +

+ +
+

+ Expected Client Result (partial match): +

+
+          {JSON.stringify(expectedClientResult)}
+        
+
+ +
+

Loader Result (SSR - may differ):

+
+          {JSON.stringify(loaderResult)}
+        
+
+ + + +
+

Client Result:

+
+          {clientResult ? JSON.stringify(clientResult) : 'Not called yet'}
+        
+
+ +
+

Note:

+

+ When called from client, the middleware should return immediately + without making a network request to the server. The source should be + "client-middleware". +

+
+
+ ) +} diff --git a/e2e/react-start/server-functions/src/routes/middleware/client-source-classification.tsx b/e2e/react-start/server-functions/src/routes/middleware/client-source-classification.tsx new file mode 100644 index 0000000000..73760146d8 --- /dev/null +++ b/e2e/react-start/server-functions/src/routes/middleware/client-source-classification.tsx @@ -0,0 +1,205 @@ +import { createFileRoute } from '@tanstack/react-router' +import { createMiddleware, createServerFn } from '@tanstack/react-start' + +const leafMiddleware = createMiddleware({ type: 'function' }).server( + ({ data, next, result }: any) => { + if (data?.scenario === 'known-leaf') { + return result({ + data: { + tag: 'leaf', + branch: 'known', + }, + }) + } + + return next({ + sendContext: { leaf: true }, + }) + }, +) + +const nestedParentMiddleware = createMiddleware({ type: 'function' }) + .middleware([leafMiddleware]) + .server(({ data, next, result }: any) => { + if (data?.scenario === 'known-parent') { + return result({ + data: { + tag: 'nested-parent', + branch: 'known', + }, + }) + } + + return next({ + sendContext: { nestedParent: true }, + }) + }) + +const siblingMiddleware = createMiddleware({ type: 'function' }).server( + ({ next }) => { + return next({ + sendContext: { sibling: true }, + }) + }, +) + +const groupedMiddleware = createMiddleware({ type: 'function' }) + .middleware([nestedParentMiddleware, siblingMiddleware]) + .server(({ data, next, result }: any) => { + if (data?.scenario === 'known-root') { + return result({ + data: { + tag: 'group-root', + branch: 'known', + }, + }) + } + + return next({ + sendContext: { groupRoot: true }, + }) + }) + +const trailingMiddleware = createMiddleware({ type: 'function' }).server( + ({ data, next, result }: any) => { + if (data?.scenario === 'known-trailing') { + return result({ + data: { + tag: 'trailing-known', + branch: 'known', + }, + }) + } + + if (data?.scenario === 'unknown-trailing') { + return result({ + data: { + tag: 'trailing-unknown', + branch: 'unknown', + }, + }) + } + + return next({ + sendContext: { trailing: true }, + }) + }, +) + +const clientKnownMiddleware = createMiddleware({ type: 'function' }) + .middleware([groupedMiddleware, trailingMiddleware]) + .client((async ({ data, next }: any) => { + const result = await next() + + return { + scenario: data.scenario, + source: result.source, + payload: result.data, + context: result.context, + } + }) as any) + +const clientUnknownMiddleware = createMiddleware({ type: 'function' }) + .middleware([groupedMiddleware]) + .client((async ({ data, next }: any) => { + const result = await next() + + return { + scenario: data.scenario, + source: result.source, + payload: result.data, + context: result.context, + } + }) as any) + +const knownFn = createServerFn() + .middleware([clientKnownMiddleware]) + .inputValidator((input: any) => input) + .handler(({ data, context }: any) => { + return { + tag: 'handler-known', + branch: 'known', + scenario: data.scenario, + context, + } + }) + +const unknownFn = createServerFn() + .middleware([clientUnknownMiddleware, trailingMiddleware]) + .inputValidator((input: any) => input) + .handler(({ data, context }: any) => { + return { + tag: 'handler-unknown', + branch: 'unknown', + scenario: data.scenario, + context, + } + }) + +export const Route = createFileRoute( + '/middleware/client-source-classification' as any, +)({ + loader: async () => { + const loaderResults = { + knownLeaf: await knownFn({ data: { scenario: 'known-leaf' } }), + knownParent: await knownFn({ data: { scenario: 'known-parent' } }), + knownRoot: await knownFn({ data: { scenario: 'known-root' } }), + knownTrailing: await knownFn({ data: { scenario: 'known-trailing' } }), + knownHandler: await knownFn({ data: { scenario: 'known-handler' } }), + unknownTrailing: await unknownFn({ + data: { scenario: 'unknown-trailing' }, + }), + unknownHandler: await unknownFn({ + data: { scenario: 'unknown-handler' }, + }), + } + + return loaderResults + }, + component: RouteComponent, +}) + +function RouteComponent() { + const loaderResults = Route.useLoaderData() + + const cases = [ + ['known-leaf', 'loader-known-leaf'], + ['known-parent', 'loader-known-parent'], + ['known-root', 'loader-known-root'], + ['known-trailing', 'loader-known-trailing'], + ['known-handler', 'loader-known-handler'], + ['unknown-trailing', 'loader-unknown-trailing'], + ['unknown-handler', 'loader-unknown-handler'], + ] as const + + return ( +
+

+ Client Middleware Source Classification +

+

+ Verifies `result.source` inside client middleware across deep and wide + composed server middleware chains during SSR and client-side loader + navigation. +

+ + {cases.map(([scenario, loaderKey]) => ( +
+
{scenario}
+
+            {JSON.stringify(
+              loaderResults[
+                scenario.replace(/-([a-z])/g, (_, char) => char.toUpperCase())
+              ],
+              null,
+              2,
+            )}
+          
+
+ ))} +
+ ) +} diff --git a/e2e/react-start/server-functions/src/routes/middleware/index.tsx b/e2e/react-start/server-functions/src/routes/middleware/index.tsx index 0d4e313912..2aa4e7cdc2 100644 --- a/e2e/react-start/server-functions/src/routes/middleware/index.tsx +++ b/e2e/react-start/server-functions/src/routes/middleware/index.tsx @@ -66,6 +66,62 @@ function RouteComponent() { Function middleware receives functionId and filename +
  • + + Server middleware early return (no next() call) + +
  • +
  • + + Server middleware early return with headers + +
  • +
  • + + Server middleware conditional return (next() OR value) + +
  • +
  • + + Client middleware source classification + +
  • +
  • + + Client middleware early return (no next() call) + +
  • +
  • + + Client middleware conditional return (next() OR value) + +
  • +
  • + + Nested middleware early return + +
  • ) diff --git a/e2e/react-start/server-functions/src/routes/middleware/nested-early-return.tsx b/e2e/react-start/server-functions/src/routes/middleware/nested-early-return.tsx new file mode 100644 index 0000000000..77c9f2f03e --- /dev/null +++ b/e2e/react-start/server-functions/src/routes/middleware/nested-early-return.tsx @@ -0,0 +1,235 @@ +import { createFileRoute } from '@tanstack/react-router' +import { createMiddleware, createServerFn } from '@tanstack/react-start' +import React from 'react' + +/** + * Tests deeply nested middleware chains where inner middleware does early return. + * + * Structure: + * - outerMiddleware + * - uses middleMiddleware + * - uses innerMiddleware (which may return early) + * + * Scenarios: + * 1. innerMiddleware returns early -> outerMiddleware never gets to call next() + * 2. innerMiddleware calls next() -> chain continues normally + */ + +type EarlyReturnInput = { + earlyReturnLevel: 'none' | 'deep' | 'middle' | 'outer' + value: string +} + +// Deepest level - conditionally returns early based on input +const deepMiddleware = createMiddleware({ type: 'function' }) + .inputValidator((input: EarlyReturnInput) => input) + .server(async ({ data, next, result }) => { + if (data.earlyReturnLevel === 'deep') { + return result({ + data: { + returnedFrom: 'deepMiddleware', + message: 'Early return from deepest middleware', + level: 3, + }, + }) + } + return next({ + context: { + deepMiddlewarePassed: true, + }, + }) + }) + +// Middle level - wraps deep middleware, may also return early +const middleMiddleware = createMiddleware({ type: 'function' }) + .middleware([deepMiddleware]) + .server(async ({ data, next, context, result }) => { + if (data.earlyReturnLevel === 'middle') { + return result({ + data: { + returnedFrom: 'middleMiddleware', + message: 'Early return from middle middleware', + level: 2, + deepContext: context, + }, + }) + } + return next({ + context: { + middleMiddlewarePassed: true, + }, + }) + }) + +// Outer level - wraps middle middleware, may also return early +const outerMiddleware = createMiddleware({ type: 'function' }) + .middleware([middleMiddleware]) + .server(async ({ data, next, context, result }) => { + if (data.earlyReturnLevel === 'outer') { + return result({ + data: { + returnedFrom: 'outerMiddleware', + message: 'Early return from outer middleware', + level: 1, + middleContext: context, + }, + }) + } + return next({ + context: { + outerMiddlewarePassed: true, + }, + }) + }) + +const serverFn = createServerFn() + .middleware([outerMiddleware]) + .handler(({ data, context }) => { + return { + returnedFrom: 'handler', + message: 'Handler was called - all middleware passed through', + level: 0, + finalContext: context, + receivedData: data, + } + }) + +export const Route = createFileRoute('/middleware/nested-early-return')({ + loader: async () => { + // Test all branches + const deepReturn = await serverFn({ + data: { earlyReturnLevel: 'deep', value: 'test-deep' }, + }) + const middleReturn = await serverFn({ + data: { earlyReturnLevel: 'middle', value: 'test-middle' }, + }) + const outerReturn = await serverFn({ + data: { earlyReturnLevel: 'outer', value: 'test-outer' }, + }) + const handlerReturn = await serverFn({ + data: { earlyReturnLevel: 'none', value: 'test-handler' }, + }) + return { deepReturn, middleReturn, outerReturn, handlerReturn } + }, + component: RouteComponent, +}) + +function RouteComponent() { + const loaderData = Route.useLoaderData() + const [results, setResults] = React.useState<{ + deep: any + middle: any + outer: any + handler: any + }>({ deep: null, middle: null, outer: null, handler: null }) + + const levels = [ + { + key: 'deep' as const, + level: 'deep', + label: 'Deep Middleware', + color: '#8b5cf6', + }, + { + key: 'middle' as const, + level: 'middle', + label: 'Middle Middleware', + color: '#3b82f6', + }, + { + key: 'outer' as const, + level: 'outer', + label: 'Outer Middleware', + color: '#22c55e', + }, + { + key: 'handler' as const, + level: 'none', + label: 'Handler', + color: '#6b7280', + }, + ] + + return ( +
    +

    Nested Middleware Early Return

    +

    + Tests deeply nested middleware chains where different levels can return + early. Chain: outerMiddleware → middleMiddleware → deepMiddleware → + handler +

    + +
    + {levels.map(({ key, level, label, color }) => ( +
    +

    {label} Returns

    + +
    +

    Expected returnedFrom:

    +
    +                {level === 'none' ? 'handler' : `${level}Middleware`}
    +              
    +
    + +
    +

    Loader Result:

    +
    +                {JSON.stringify(loaderData[`${key}Return`], null, 2)}
    +              
    +
    + + + +
    +

    Client Result:

    +
    +                {results[key]
    +                  ? JSON.stringify(results[key], null, 2)
    +                  : 'Not called yet'}
    +              
    +
    +
    + ))} +
    + +
    +

    Chain Structure:

    +
    +          {`outerMiddleware (level 1)
    +   └─ middleMiddleware (level 2)
    +        └─ deepMiddleware (level 3)
    +             └─ handler (level 0)`}
    +        
    +

    + Each level can short-circuit and return early, preventing deeper + levels from executing. +

    +
    +
    + ) +} diff --git a/e2e/react-start/server-functions/src/routes/middleware/server-conditional.tsx b/e2e/react-start/server-functions/src/routes/middleware/server-conditional.tsx new file mode 100644 index 0000000000..cfed6cdbde --- /dev/null +++ b/e2e/react-start/server-functions/src/routes/middleware/server-conditional.tsx @@ -0,0 +1,185 @@ +import { createFileRoute } from '@tanstack/react-router' +import { createMiddleware, createServerFn } from '@tanstack/react-start' +import React from 'react' + +/** + * This middleware's .server() conditionally calls next() OR returns a value. + * If `shouldShortCircuit` is true in the data, it returns early. + * Otherwise, it calls next() and passes context to the handler. + */ +const serverConditionalMiddleware = createMiddleware({ + type: 'function', +}) + .inputValidator( + (input: { shouldShortCircuit: boolean; value: string }) => input, + ) + .server(async ({ data, next, result }) => { + if (data.shouldShortCircuit) { + return result({ + data: { + source: 'middleware', + message: 'Conditional early return from server middleware', + condition: 'shouldShortCircuit=true', + }, + }) + } + return next({ + context: { + passedThroughMiddleware: true, + }, + }) + }) + +const serverFn = createServerFn() + .middleware([serverConditionalMiddleware]) + .handler(({ data, context }) => { + return { + source: 'handler', + message: 'Handler was called', + receivedData: data, + receivedContext: context, + } + }) + +export const Route = createFileRoute('/middleware/server-conditional')({ + loader: async () => { + // Test both branches in the loader + const shortCircuitResult = await serverFn({ + data: { shouldShortCircuit: true, value: 'loader-short' }, + }) + const nextResult = await serverFn({ + data: { shouldShortCircuit: false, value: 'loader-next' }, + }) + return { shortCircuitResult, nextResult } + }, + component: RouteComponent, +}) + +function RouteComponent() { + const { shortCircuitResult, nextResult } = Route.useLoaderData() + const [clientShortCircuit, setClientShortCircuit] = React.useState(null) + const [clientNext, setClientNext] = React.useState(null) + + const expectedShortCircuit = { + source: 'middleware', + message: 'Conditional early return from server middleware', + condition: 'shouldShortCircuit=true', + } + + const expectedNext = { + source: 'handler', + message: 'Handler was called', + receivedData: { shouldShortCircuit: false, value: 'client-next' }, + receivedContext: { passedThroughMiddleware: true }, + } + + return ( +
    +

    + Server Middleware Conditional Return +

    +

    + Tests that a .server() middleware can conditionally call next() OR + return a value based on input data. +

    + +
    +
    +

    Short-Circuit Branch

    + +
    +

    Expected (client):

    +
    +              {JSON.stringify(expectedShortCircuit)}
    +            
    +
    + +
    +

    Loader Result:

    +
    +              {JSON.stringify(shortCircuitResult)}
    +            
    +
    + + + +
    +

    Client Result:

    +
    +              {clientShortCircuit
    +                ? JSON.stringify(clientShortCircuit)
    +                : 'Not called yet'}
    +            
    +
    +
    + +
    +

    Next() Branch

    + +
    +

    Expected (client):

    +
    +              {JSON.stringify(expectedNext)}
    +            
    +
    + +
    +

    Loader Result:

    +
    +              {JSON.stringify(nextResult)}
    +            
    +
    + + + +
    +

    Client Result:

    +
    +              {clientNext ? JSON.stringify(clientNext) : 'Not called yet'}
    +            
    +
    +
    +
    +
    + ) +} diff --git a/e2e/react-start/server-functions/src/routes/middleware/server-early-return-headers.tsx b/e2e/react-start/server-functions/src/routes/middleware/server-early-return-headers.tsx new file mode 100644 index 0000000000..86184a22f6 --- /dev/null +++ b/e2e/react-start/server-functions/src/routes/middleware/server-early-return-headers.tsx @@ -0,0 +1,117 @@ +import { createFileRoute } from '@tanstack/react-router' +import { createMiddleware, createServerFn } from '@tanstack/react-start' +import React from 'react' + +/** + * Verifies that middleware can short-circuit with result({ headers }). + * + * The e2e assertion for the headers is done in Playwright by + * inspecting the `_serverFn` response headers. + */ +const serverEarlyReturnHeadersMiddleware = createMiddleware({ + type: 'function', +}).server(async ({ result }) => { + return result({ + data: { + source: 'middleware', + message: 'Early return from server middleware with headers', + }, + headers: { + 'x-middleware-early-return': 'true', + 'x-middleware-early-return-value': 'hello', + }, + }) +}) + +const serverFn = createServerFn() + .middleware([serverEarlyReturnHeadersMiddleware]) + .handler(() => { + return { + source: 'handler', + message: 'This should not be returned', + } + }) + +export const Route = createFileRoute('/middleware/server-early-return-headers')( + { + component: RouteComponent, + }, +) + +function RouteComponent() { + const [resultValue, setResultValue] = React.useState(null) + const [capturedResponseHeaders, setCapturedResponseHeaders] = + React.useState | null>(null) + const [error, setError] = React.useState(null) + + return ( +
    +

    + Server Middleware Early Return with Headers +

    +

    + Calls a server function that short-circuits in middleware via result() + and sets response headers. +

    + + + +
    +
    +

    Result Data:

    +
    +            {resultValue
    +              ? JSON.stringify(resultValue, null, 2)
    +              : 'Not called yet'}
    +          
    +
    + +
    +

    Captured Response Headers:

    +
    +            {capturedResponseHeaders
    +              ? JSON.stringify(capturedResponseHeaders, null, 2)
    +              : 'Not captured yet'}
    +          
    +
    + + {error ? ( +
    {error}
    + ) : ( +
    + )} +
    +
    + ) +} diff --git a/e2e/react-start/server-functions/src/routes/middleware/server-early-return.tsx b/e2e/react-start/server-functions/src/routes/middleware/server-early-return.tsx new file mode 100644 index 0000000000..f573a9d802 --- /dev/null +++ b/e2e/react-start/server-functions/src/routes/middleware/server-early-return.tsx @@ -0,0 +1,200 @@ +import { createFileRoute } from '@tanstack/react-router' +import { createMiddleware, createServerFn } from '@tanstack/react-start' +import React from 'react' + +/** + * This middleware's .server() does NOT call next() at all + * and always returns a value directly. + * + * Expected behavior: The handler should never be called, + * and the middleware's return value should be the result. + */ +const serverEarlyReturnMiddleware = createMiddleware({ + type: 'function', +}).server(async ({ result }) => { + return result({ + data: { + source: 'middleware', + message: 'Early return from server middleware', + }, + }) +}) + +const serverFn = createServerFn() + .middleware([serverEarlyReturnMiddleware]) + .handler(() => { + // This handler should NEVER be called because middleware returns early + return { + source: 'handler', + message: 'This should not be returned', + } + }) + +/** + * This middleware returns an object that contains a "method" property. + * This tests that our early return detection uses a Symbol, not duck-typing. + * If we were checking for 'method' in result, this would cause a false positive. + */ +const methodPropertyMiddleware = createMiddleware({ + type: 'function', +}).server(async ({ result }) => { + return result({ + data: { + source: 'middleware', + method: 'GET', + headers: { 'Content-Type': 'application/json' }, + message: 'Early return with method property', + }, + }) +}) + +const serverFnWithMethodProperty = createServerFn() + .middleware([methodPropertyMiddleware]) + .handler(() => { + // This handler should NEVER be called because middleware returns early + return { + source: 'handler', + message: 'This should not be returned', + } + }) + +export const Route = createFileRoute('/middleware/server-early-return')({ + loader: async () => { + const result = await serverFn() + const resultWithMethod = await serverFnWithMethodProperty() + return { loaderResult: result, loaderResultWithMethod: resultWithMethod } + }, + component: RouteComponent, +}) + +function RouteComponent() { + const { loaderResult, loaderResultWithMethod } = Route.useLoaderData() + const [clientResult, setClientResult] = React.useState(null) + const [clientResultWithMethod, setClientResultWithMethod] = + React.useState(null) + + const expectedResult = { + source: 'middleware', + message: 'Early return from server middleware', + } + + const expectedResultWithMethod = { + source: 'middleware', + method: 'GET', + headers: { 'Content-Type': 'application/json' }, + message: 'Early return with method property', + } + + return ( +
    +

    + Server Middleware Early Return (No next() call) +

    +

    + Tests that a .server() middleware can return a value without calling + next(), effectively short-circuiting the middleware chain. +

    + +
    +

    Expected Result:

    +
    +          {JSON.stringify(expectedResult)}
    +        
    +
    + +
    +

    Loader Result (SSR):

    +
    +          {JSON.stringify(loaderResult)}
    +        
    +
    + + + +
    +

    Client Result:

    +
    +          {clientResult ? JSON.stringify(clientResult) : 'Not called yet'}
    +        
    +
    + +
    + +

    + Early Return with 'method' Property +

    +

    + This tests that early return detection uses a Symbol, not duck-typing. +

    + +
    +

    Expected Result (with method):

    +
    +          {JSON.stringify(expectedResultWithMethod)}
    +        
    +
    + +
    +

    Loader Result with method (SSR):

    +
    +          {JSON.stringify(loaderResultWithMethod)}
    +        
    +
    + + + +
    +

    Client Result (with method):

    +
    +          {clientResultWithMethod
    +            ? JSON.stringify(clientResultWithMethod)
    +            : 'Not called yet'}
    +        
    +
    +
    + ) +} diff --git a/e2e/react-start/server-functions/tests/server-functions.spec.ts b/e2e/react-start/server-functions/tests/server-functions.spec.ts index 5eaf8e66cc..a680bc1658 100644 --- a/e2e/react-start/server-functions/tests/server-functions.spec.ts +++ b/e2e/react-start/server-functions/tests/server-functions.spec.ts @@ -6,6 +6,27 @@ import type { Page } from '@playwright/test' const PORT = await getTestServerPort(packageJson.name) +const clientSourceClassificationCases = [ + ['known-leaf', 'middleware', 'leaf'], + ['known-parent', 'middleware', 'nested-parent'], + ['known-root', 'middleware', 'group-root'], + ['known-trailing', 'middleware', 'trailing-known'], + ['known-handler', 'handler', 'handler-known'], + ['unknown-trailing', 'unknown', 'trailing-unknown'], + ['unknown-handler', 'unknown', 'handler-unknown'], +] as const + +async function expectClientSourceClassificationResults(page: Page) { + for (const [scenario, source, tag] of clientSourceClassificationCases) { + await expect(page.getByTestId(`loader-${scenario}`)).toContainText( + `"source": "${source}"`, + ) + await expect(page.getByTestId(`loader-${scenario}`)).toContainText( + `"tag": "${tag}"`, + ) + } +} + test('Server function URLs correctly include explicit ids', async ({ page, }) => { @@ -241,6 +262,29 @@ test('server function correctly passes context when using FormData', async ({ expect(simpleResult.testString).toContain('context-from-middleware') }) +test('server function can short-circuit middleware with result({ headers })', async ({ + page, +}) => { + await page.goto('/middleware/server-early-return-headers') + await page.waitForLoadState('networkidle') + + await page.getByTestId('invoke-btn').click() + + await expect(page.getByTestId('captured-response-headers')).not.toContainText( + 'Not captured yet', + { timeout: 10000 }, + ) + + const capturedHeaders = JSON.parse( + await page.getByTestId('captured-response-headers').innerText(), + ) + + expect(capturedHeaders['x-middleware-early-return']).toBe('true') + expect(capturedHeaders['x-middleware-early-return-value']).toBe('hello') + + await expect(page.getByTestId('result-data')).toContainText('middleware') +}) + test('server function can correctly send and receive headers', async ({ page, }) => { @@ -1049,6 +1093,297 @@ test('middleware can catch errors thrown by server function handlers', async ({ ) }) +// ============================================================================= +// Middleware Early Return Tests +// These tests verify that middleware can return values without calling next() +// ============================================================================= + +test.describe('server middleware early return (no next() call)', () => { + test('middleware returns value instead of calling next()', async ({ + page, + }) => { + await page.goto('/middleware/server-early-return') + await page.waitForLoadState('networkidle') + + // Check that loader result came from middleware, not handler + const loaderResult = await page.getByTestId('loader-result').textContent() + expect(loaderResult).toContain('middleware') + expect(loaderResult).toContain('Early return from server middleware') + expect(loaderResult).not.toContain('handler') + + // Test client-side invocation + await page.getByTestId('invoke-btn').click() + // Wait for the result to appear (not just networkidle) + await expect(page.getByTestId('client-result')).not.toContainText( + 'Not called yet', + { timeout: 10000 }, + ) + + const clientResult = await page.getByTestId('client-result').textContent() + expect(clientResult).toContain('middleware') + expect(clientResult).toContain('Early return from server middleware') + expect(clientResult).not.toContain('handler') + }) + + test('middleware returns object with "method" property (tests Symbol-based detection)', async ({ + page, + }) => { + await page.goto('/middleware/server-early-return') + await page.waitForLoadState('networkidle') + + // Check that loader result with method property came from middleware, not handler + // This tests that we use a Symbol to detect next() results, not duck-typing + const loaderResult = await page + .getByTestId('loader-result-method') + .textContent() + expect(loaderResult).toContain('middleware') + expect(loaderResult).toContain('Early return with method property') + expect(loaderResult).toContain('"method":"GET"') + expect(loaderResult).not.toContain('This should not be returned') + + // Test client-side invocation + await page.getByTestId('invoke-btn-method').click() + await expect(page.getByTestId('client-result-method')).not.toContainText( + 'Not called yet', + { timeout: 10000 }, + ) + + const clientResult = await page + .getByTestId('client-result-method') + .textContent() + expect(clientResult).toContain('middleware') + expect(clientResult).toContain('Early return with method property') + expect(clientResult).toContain('"method":"GET"') + expect(clientResult).not.toContain('This should not be returned') + }) +}) + +test.describe('server middleware conditional return (next() OR value)', () => { + test('middleware returns early when condition is true', async ({ page }) => { + await page.goto('/middleware/server-conditional') + await page.waitForLoadState('networkidle') + + // Check loader short-circuit result + const loaderShortCircuit = await page + .getByTestId('loader-short-circuit') + .textContent() + expect(loaderShortCircuit).toContain('middleware') + expect(loaderShortCircuit).toContain('Conditional early return') + + // Test client-side short-circuit + await page.getByTestId('invoke-short-circuit-btn').click() + // Wait for the result to appear (not just networkidle) + await expect(page.getByTestId('client-short-circuit')).not.toContainText( + 'Not called yet', + { timeout: 10000 }, + ) + + const clientShortCircuit = await page + .getByTestId('client-short-circuit') + .textContent() + expect(clientShortCircuit).toContain('middleware') + expect(clientShortCircuit).toContain('Conditional early return') + }) + + test('middleware calls next() when condition is false', async ({ page }) => { + await page.goto('/middleware/server-conditional') + await page.waitForLoadState('networkidle') + + // Check loader next result + const loaderNext = await page.getByTestId('loader-next').textContent() + expect(loaderNext).toContain('handler') + expect(loaderNext).toContain('Handler was called') + + // Test client-side next() call + await page.getByTestId('invoke-next-btn').click() + // Wait for the result to appear (not just networkidle) + await expect(page.getByTestId('client-next')).not.toContainText( + 'Not called yet', + { timeout: 10000 }, + ) + + const clientNext = await page.getByTestId('client-next').textContent() + expect(clientNext).toContain('handler') + expect(clientNext).toContain('Handler was called') + }) +}) + +test.describe('client middleware early return (no next() call)', () => { + test('client middleware returns value instead of calling next()', async ({ + page, + }) => { + await page.goto('/middleware/client-early-return') + await page.waitForLoadState('networkidle') + + // Test client-side invocation - should return from client middleware + await page.getByTestId('invoke-btn').click() + // Wait for the result to appear (not just networkidle) + await expect(page.getByTestId('client-result')).not.toContainText( + 'Not called yet', + { timeout: 10000 }, + ) + + const clientResult = await page.getByTestId('client-result').textContent() + expect(clientResult).toContain('client-middleware') + expect(clientResult).toContain('Early return from client middleware') + expect(clientResult).not.toContain('handler') + }) +}) + +test.describe('client middleware conditional return (next() OR value)', () => { + test('client middleware returns early when condition is true', async ({ + page, + }) => { + await page.goto('/middleware/client-conditional') + await page.waitForLoadState('networkidle') + + // Test client-side short-circuit + await page.getByTestId('invoke-short-circuit-btn').click() + // Wait for the result to appear (not just networkidle) + await expect(page.getByTestId('client-short-circuit')).not.toContainText( + 'Not called yet', + { timeout: 10000 }, + ) + + const clientShortCircuit = await page + .getByTestId('client-short-circuit') + .textContent() + expect(clientShortCircuit).toContain('client-middleware') + expect(clientShortCircuit).toContain('Conditional early return') + }) + + test('client middleware calls next() when condition is false', async ({ + page, + }) => { + await page.goto('/middleware/client-conditional') + await page.waitForLoadState('networkidle') + + // Test client-side next() call + await page.getByTestId('invoke-next-btn').click() + // Wait for the result to appear (not just networkidle) + await expect(page.getByTestId('client-next')).not.toContainText( + 'Not called yet', + { timeout: 10000 }, + ) + + const clientNext = await page.getByTestId('client-next').textContent() + expect(clientNext).toContain('handler') + expect(clientNext).toContain('Handler was called on server') + }) +}) + +test.describe('nested middleware early return', () => { + test('deep middleware returns early', async ({ page }) => { + await page.goto('/middleware/nested-early-return') + await page.waitForLoadState('networkidle') + + // Check loader result for deep early return + const loaderDeep = await page.getByTestId('loader-deep').textContent() + expect(loaderDeep).toContain('deepMiddleware') + expect(loaderDeep).toContain('Early return from deepest middleware') + + // Test client-side invocation + await page.getByTestId('invoke-deep-btn').click() + // Wait for the result to appear (not just networkidle) + await expect(page.getByTestId('client-deep')).not.toContainText( + 'Not called yet', + { timeout: 10000 }, + ) + + const clientDeep = await page.getByTestId('client-deep').textContent() + expect(clientDeep).toContain('deepMiddleware') + }) + + test('middle middleware returns early', async ({ page }) => { + await page.goto('/middleware/nested-early-return') + await page.waitForLoadState('networkidle') + + // Check loader result for middle early return + const loaderMiddle = await page.getByTestId('loader-middle').textContent() + expect(loaderMiddle).toContain('middleMiddleware') + expect(loaderMiddle).toContain('Early return from middle middleware') + + // Test client-side invocation + await page.getByTestId('invoke-middle-btn').click() + // Wait for the result to appear (not just networkidle) + await expect(page.getByTestId('client-middle')).not.toContainText( + 'Not called yet', + { timeout: 10000 }, + ) + + const clientMiddle = await page.getByTestId('client-middle').textContent() + expect(clientMiddle).toContain('middleMiddleware') + }) + + test('outer middleware returns early', async ({ page }) => { + await page.goto('/middleware/nested-early-return') + await page.waitForLoadState('networkidle') + + // Check loader result for outer early return + const loaderOuter = await page.getByTestId('loader-outer').textContent() + expect(loaderOuter).toContain('outerMiddleware') + expect(loaderOuter).toContain('Early return from outer middleware') + + // Test client-side invocation + await page.getByTestId('invoke-outer-btn').click() + // Wait for the result to appear (not just networkidle) + await expect(page.getByTestId('client-outer')).not.toContainText( + 'Not called yet', + { timeout: 10000 }, + ) + + const clientOuter = await page.getByTestId('client-outer').textContent() + expect(clientOuter).toContain('outerMiddleware') + }) + + test('all middleware passes through to handler', async ({ page }) => { + await page.goto('/middleware/nested-early-return') + await page.waitForLoadState('networkidle') + + // Check loader result for handler + const loaderHandler = await page.getByTestId('loader-handler').textContent() + expect(loaderHandler).toContain('handler') + expect(loaderHandler).toContain('Handler was called') + + // Test client-side invocation + await page.getByTestId('invoke-handler-btn').click() + // Wait for the result to appear (not just networkidle) + await expect(page.getByTestId('client-handler')).not.toContainText( + 'Not called yet', + { timeout: 10000 }, + ) + + const clientHandler = await page.getByTestId('client-handler').textContent() + expect(clientHandler).toContain('handler') + expect(clientHandler).toContain('Handler was called') + }) +}) + +test.describe('client middleware next() source classification', () => { + test('classifies known middleware and handler during SSR', async ({ + page, + }) => { + await page.goto('/middleware/client-source-classification') + await page.waitForLoadState('networkidle') + + await expectClientSourceClassificationResults(page) + }) + + test('classifies known middleware and handler on client-side navigation', async ({ + page, + }) => { + await page.goto('/middleware') + await page.waitForLoadState('networkidle') + + await page.getByTestId('client-source-classification-link').click() + await expect( + page.getByTestId('client-source-classification-route'), + ).toBeVisible() + + await expectClientSourceClassificationResults(page) + }) +}) + test('server function with custom fetch implementation passed directly', async ({ page, }) => { diff --git a/packages/start-client-core/src/createMiddleware.ts b/packages/start-client-core/src/createMiddleware.ts index 9e0a435791..638d0b0355 100644 --- a/packages/start-client-core/src/createMiddleware.ts +++ b/packages/start-client-core/src/createMiddleware.ts @@ -522,6 +522,7 @@ export interface FunctionMiddlewareServerFnOptions< method: Method serverFnMeta: ServerFnMeta signal: AbortSignal + result: any } export type FunctionMiddlewareServerFnResult< @@ -620,6 +621,7 @@ export interface FunctionMiddlewareClientFnOptions< next: FunctionMiddlewareClientNextFn filename: string fetch?: CustomFetch + result: any } export type FunctionMiddlewareClientFnResult< diff --git a/packages/start-client-core/src/createServerFn.ts b/packages/start-client-core/src/createServerFn.ts index 42eef35aec..b2f16c35d5 100644 --- a/packages/start-client-core/src/createServerFn.ts +++ b/packages/start-client-core/src/createServerFn.ts @@ -1,6 +1,7 @@ import { mergeHeaders } from '@tanstack/router-core/ssr/client' import { isRedirect, parseRedirect } from '@tanstack/router-core' +import { isServer } from '@tanstack/router-core/isServer' import { TSS_SERVER_FUNCTION_FACTORY } from './constants' import { getStartOptions } from './getStartOptions' import { getStartContextServerOnly } from './getStartContextServerOnly' @@ -30,7 +31,144 @@ import type { IntersectAllValidatorOutputs, } from './createMiddleware' -type TODO = any +const NEXT_RESULT_SYMBOL = Symbol.for('TSR_SERVER_FN_NEXT_RESULT') +const RESULT_HELPER_SYMBOL = Symbol.for('TSR_SERVER_FN_RESULT_HELPER') +const INTERNAL_RESULT_ORIGIN_SYMBOL = Symbol.for( + 'TSR_SERVER_FN_INTERNAL_RESULT_ORIGIN', +) +const SHORT_CIRCUIT_INDEX_KEY = 'sc' +const MIDDLEWARE_SERVER_MARKER_KEY = 'hasServer' + +// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition +const canRunServerCode = (isServer ?? + typeof document === 'undefined') as boolean + +type MiddlewareResultOriginKind = 'server-middleware' | 'client-middleware' + +type MiddlewareResultOrigin = { + kind: MiddlewareResultOriginKind + index?: number +} + +type MiddlewareScopeSource = 'middleware' | 'handler' | 'unknown' + +export type FlattenedMiddlewareEntry< + T extends AnyFunctionMiddleware | AnyRequestMiddleware, +> = { + middleware: T + position: number + subtreeStartPosition: number + hasServer: boolean + hasServerAfter: boolean + hasClient: boolean + isServerFnBase: boolean +} + +function setInternalResultOrigin( + target: object, + origin: MiddlewareResultOrigin, +) { + ;(target as any)[INTERNAL_RESULT_ORIGIN_SYMBOL] = origin +} + +function getInternalResultOrigin( + value: unknown, +): MiddlewareResultOrigin | undefined { + if (!value || typeof value !== 'object') { + return undefined + } + + const symbolOrigin = (value as any)[INTERNAL_RESULT_ORIGIN_SYMBOL] + if (symbolOrigin) { + return symbolOrigin + } + + const index = (value as any)[SHORT_CIRCUIT_INDEX_KEY] + + if (typeof index !== 'number') { + return undefined + } + + delete (value as any)[SHORT_CIRCUIT_INDEX_KEY] + + const origin = { + kind: 'server-middleware', + index, + } satisfies MiddlewareResultOrigin + + setInternalResultOrigin(value, origin) + + return origin +} + +function createShortCircuitResult( + ctx: ServerFnMiddlewareResult, + result: unknown, + origin: MiddlewareResultOrigin, + headers?: HeadersInit, +): ServerFnMiddlewareResult { + const nextResult = { + ...ctx, + result, + headers: mergeHeaders(ctx.headers, headers), + } + + setInternalResultOrigin(nextResult, origin) + + return nextResult +} + +function getMiddlewareSource( + origin: MiddlewareResultOrigin | undefined, + middlewareEntry: FlattenedMiddlewareEntry< + AnyFunctionMiddleware | AnyRequestMiddleware + >, + flattenedMiddlewareEntries: Array< + FlattenedMiddlewareEntry + >, + executedRequestMiddlewares?: ReadonlySet< + AnyFunctionMiddleware | AnyRequestMiddleware + >, +): MiddlewareScopeSource { + if ( + origin?.kind === 'server-middleware' && + typeof origin.index === 'number' && + origin.index >= middlewareEntry.subtreeStartPosition && + origin.index <= middlewareEntry.position + ) { + return 'middleware' + } + + if (origin) { + return 'unknown' + } + + if ( + canRunServerCode && + middlewareEntry.hasServerAfter && + executedRequestMiddlewares?.size + ) { + for ( + let index = middlewareEntry.position + 1; + index < flattenedMiddlewareEntries.length; + index++ + ) { + const nextEntry = flattenedMiddlewareEntries[index]! + + if (executedRequestMiddlewares.has(nextEntry.middleware)) { + continue + } + + if (nextEntry.hasServer && !nextEntry.isServerFnBase) { + return 'unknown' + } + } + + return 'handler' + } + + return middlewareEntry.hasServerAfter ? 'unknown' : 'handler' +} export type CreateServerFn = < TMethod extends Method, @@ -70,7 +208,7 @@ export const createServerFn: CreateServerFn = (options, __opts) => { // this is primarily useful for letting users create their own abstractions on top of `createServerFn` const newMiddleware = [...(resolvedOptions.middleware || [])] - middleware.map((m) => { + for (const m of middleware) { if (TSS_SERVER_FUNCTION_FACTORY in m) { if (m.options.middleware) { newMiddleware.push(...m.options.middleware) @@ -78,7 +216,7 @@ export const createServerFn: CreateServerFn = (options, __opts) => { } else { newMiddleware.push(m) } - }) + } const newOptions = { ...resolvedOptions, @@ -109,6 +247,26 @@ export const createServerFn: CreateServerFn = (options, __opts) => { ...(newOptions.middleware || []), serverFnBaseToMiddleware(newOptions), ] + let middlewareEntries: + | Array< + FlattenedMiddlewareEntry< + AnyFunctionMiddleware | AnyRequestMiddleware + > + > + | undefined + const getMiddlewareEntries = () => { + if (!middlewareEntries) { + const globalMiddlewares = getStartOptions()?.functionMiddleware || [] + + middlewareEntries = flattenMiddlewaresWithDetails( + globalMiddlewares.length + ? globalMiddlewares.concat(resolvedMiddleware) + : resolvedMiddleware, + ) + } + + return middlewareEntries + } // We want to make sure the new function has the same // properties as the original function @@ -130,6 +288,7 @@ export const createServerFn: CreateServerFn = (options, __opts) => { signal: opts?.signal, fetch: opts?.fetch, context: createNullProtoObject(), + _getMiddlewareEntries: getMiddlewareEntries, }) const redirect = parseRedirect(result.error) @@ -146,41 +305,42 @@ export const createServerFn: CreateServerFn = (options, __opts) => { // Expose the declared HTTP method so the server handler // can reject mismatched methods before parsing payloads method: resolvedOptions.method, - // The extracted function on the server-side calls - // this function - __executeServer: async (opts: any) => { - const startContext = getStartContextServerOnly() - const serverContextAfterGlobalMiddlewares = - startContext.contextAfterGlobalMiddlewares - // Use safeObjectMerge for opts.context which comes from client - const ctx = { - ...extractedFn, - ...opts, - // Ensure we use the full serverFnMeta from the provider file's extractedFn - // (which has id, name, filename) rather than the partial one from SSR/client - // callers (which only has id) - serverFnMeta: extractedFn.serverFnMeta, - // Use safeObjectMerge for opts.context which comes from client - context: safeObjectMerge( - serverContextAfterGlobalMiddlewares, - opts.context, - ), - request: startContext.request, - } + ...(canRunServerCode + ? { + __executeServer: async (opts: any) => { + const startContext = getStartContextServerOnly() - const result = await executeMiddleware( - resolvedMiddleware, - 'server', - ctx, - ).then((d) => ({ - // Only send the result and sendContext back to the client - result: d.result, - error: d.error, - context: d.sendContext, - })) + const result = await executeMiddleware( + resolvedMiddleware, + 'server', + { + ...extractedFn, + ...opts, + serverFnMeta: extractedFn.serverFnMeta, + context: safeObjectMerge( + startContext.contextAfterGlobalMiddlewares, + opts.context, + ), + request: startContext.request, + _getMiddlewareEntries: getMiddlewareEntries, + }, + ) - return result - }, + const origin = getInternalResultOrigin(result) + + return { + result: result.result, + error: result.error, + headers: result.headers, + context: result.sendContext, + ...(origin?.kind === 'server-middleware' && + typeof origin.index === 'number' + ? { [SHORT_CIRCUIT_INDEX_KEY]: origin.index } + : {}), + } + }, + } + : {}), }, ) as any }, @@ -200,32 +360,37 @@ export async function executeMiddleware( env: 'client' | 'server', opts: ServerFnMiddlewareOptions, ): Promise { - const globalMiddlewares = getStartOptions()?.functionMiddleware || [] - let flattenedMiddlewares = flattenMiddlewares([ - ...globalMiddlewares, - ...middlewares, - ]) - - // On server, filter out middlewares that already executed in the request phase - // to prevent duplicate execution (issue #5239) - if (env === 'server') { - const startContext = getStartContextServerOnly({ throwIfNotFound: false }) - if (startContext?.executedRequestMiddlewares) { - flattenedMiddlewares = flattenedMiddlewares.filter( - (m) => !startContext.executedRequestMiddlewares.has(m), - ) - } - } + const executedRequestMiddlewares = canRunServerCode + ? getStartContextServerOnly({ throwIfNotFound: false }) + ?.executedRequestMiddlewares + : undefined + const flattenedMiddlewareEntries = opts._getMiddlewareEntries + ? opts._getMiddlewareEntries() + : flattenMiddlewaresWithDetails(middlewares) + let middlewareIndex = 0 const callNextMiddleware: NextFn = async (ctx) => { - // Get the next middleware - const nextMiddleware = flattenedMiddlewares.shift() + let middlewareEntry: + | FlattenedMiddlewareEntry + | undefined - // If there are no more middlewares, return the context - if (!nextMiddleware) { + while (middlewareIndex < flattenedMiddlewareEntries.length) { + const nextEntry = flattenedMiddlewareEntries[middlewareIndex++]! + + if (executedRequestMiddlewares?.has(nextEntry.middleware)) { + continue + } + + middlewareEntry = nextEntry + break + } + + if (!middlewareEntry) { return ctx } + const nextMiddleware = middlewareEntry.middleware + // Execute the middleware try { if ( @@ -282,6 +447,22 @@ export async function executeMiddleware( throw result.error } + if (env === 'client' && middlewareEntry.hasClient) { + const origin = getInternalResultOrigin(result) + ;(result as any).source = getMiddlewareSource( + origin, + middlewareEntry, + flattenedMiddlewareEntries, + executedRequestMiddlewares, + ) + ;(result as any).data = result.result + ;(result as any)[NEXT_RESULT_SYMBOL] = true + + return result + } + + ;(result as any)[NEXT_RESULT_SYMBOL] = true + return result } @@ -289,6 +470,11 @@ export async function executeMiddleware( const result = await middlewareFn({ ...ctx, next: userNext, + result: ({ data, headers }: any) => ({ + [RESULT_HELPER_SYMBOL]: true, + data, + headers, + }), }) // If result is NOT a ctx object, we need to return it as @@ -307,13 +493,43 @@ export async function executeMiddleware( } } + if ((result as any)[RESULT_HELPER_SYMBOL] === true) { + const origin: MiddlewareResultOrigin = + env === 'server' + ? { + kind: 'server-middleware', + index: middlewareEntry.position, + } + : { kind: 'client-middleware' } + + return createShortCircuitResult( + ctx, + result.data, + origin, + result.headers, + ) + } + if (!(result as any)) { throw new Error( 'User middleware returned undefined. You must call next() or return a result in your middlewares.', ) } - return result + if ((result as any)[NEXT_RESULT_SYMBOL] === true) { + return result + } + + if (env === 'server') { + return createShortCircuitResult(ctx, result, { + kind: 'server-middleware', + index: middlewareEntry.position, + }) + } + + return createShortCircuitResult(ctx, result, { + kind: 'client-middleware', + }) } return callNextMiddleware(ctx) @@ -689,31 +905,83 @@ export interface ServerFnTypes< allOutput: IntersectAllValidatorOutputs } -export function flattenMiddlewares< +export function flattenMiddlewaresWithDetails< T extends AnyFunctionMiddleware | AnyRequestMiddleware, ->(middlewares: Array, maxDepth: number = 100): Array { +>( + middlewares: Array, + maxDepth: number = 100, +): Array> { const seen = new Set() - const flattened: Array = [] + const flattened: Array> = [] + const stack: Array< + [ + middleware: T, + depth: number, + subtreeStartPosition: number, + expanded: 0 | 1, + ] + > = [] + + for (let index = middlewares.length - 1; index >= 0; index--) { + stack.push([middlewares[index]!, 0, 0, 0]) + } + + while (stack.length) { + const [middleware, depth, subtreeStartPosition, expanded] = stack.pop()! - const recurse = (middleware: Array, depth: number) => { if (depth > maxDepth) { throw new Error( `Middleware nesting depth exceeded maximum of ${maxDepth}. Check for circular references.`, ) } - middleware.forEach((m) => { - if (m.options.middleware) { - recurse(m.options.middleware as Array, depth + 1) + + if (expanded === 1) { + if (seen.has(middleware)) { + continue } - if (!seen.has(m)) { - seen.add(m) - flattened.push(m) - } - }) + seen.add(middleware) + + const options = middleware.options as any + + flattened.push({ + middleware, + position: flattened.length, + subtreeStartPosition, + hasServer: + ('server' in middleware.options && !!middleware.options.server) || + (middleware.options as any)[MIDDLEWARE_SERVER_MARKER_KEY] !== false, + hasServerAfter: false, + hasClient: + 'client' in middleware.options && !!middleware.options.client, + isServerFnBase: !!options._isServerFnBase, + }) + + continue + } + + stack.push([middleware, depth, flattened.length, 1]) + + const nestedMiddlewares = middleware.options.middleware as + | Array + | undefined + + if (!nestedMiddlewares?.length) { + continue + } + + for (let index = nestedMiddlewares.length - 1; index >= 0; index--) { + stack.push([nestedMiddlewares[index]!, depth + 1, 0, 0]) + } } - recurse(middlewares, 0) + let hasServerAfter = false + for (let index = flattened.length - 1; index >= 0; index--) { + flattened[index]!.hasServerAfter = hasServerAfter + if (flattened[index]!.hasServer && !flattened[index]!.isServerFnBase) { + hasServerAfter = true + } + } return flattened } @@ -729,6 +997,10 @@ export type ServerFnMiddlewareOptions = { fetch?: CustomFetch /** @internal - Preserves the call-site fetch to ensure it has highest priority over middleware */ _callSiteFetch?: CustomFetch + /** @internal */ + _getMiddlewareEntries?: () => Array< + FlattenedMiddlewareEntry + > } export type ServerFnMiddlewareResult = ServerFnMiddlewareOptions & { @@ -743,6 +1015,7 @@ export type NextFn = ( export type MiddlewareFn = ( ctx: ServerFnMiddlewareOptions & { next: NextFn + result?: (opts: { data: unknown; headers?: HeadersInit }) => unknown }, ) => Promise @@ -778,14 +1051,15 @@ function serverFnBaseToMiddleware( return { '~types': undefined!, options: { + _isServerFnBase: true, inputValidator: options.inputValidator, - client: async ({ next, sendContext, fetch, ...ctx }) => { + client: async ({ next, sendContext, fetch, ...ctx }: any) => { const payload = { ...ctx, // switch the sendContext over to context context: sendContext, fetch, - } as any + } // Execute the extracted function // but not before serializing the context @@ -793,21 +1067,22 @@ function serverFnBaseToMiddleware( return next(res) }, - server: async ({ next, ...ctx }) => { - // Execute the server function - const result = await options.serverFn?.(ctx as TODO) + server: canRunServerCode + ? async ({ next, ...ctx }: any) => { + const result = await options.serverFn?.(ctx) - return next({ - ...ctx, - result, - } as any) as unknown as FunctionMiddlewareServerFnResult< - any, - any, - any, - any, - any - > - }, - }, + return next({ + ...ctx, + result, + }) as unknown as FunctionMiddlewareServerFnResult< + any, + any, + any, + any, + any + > + } + : undefined, + } as any, } } diff --git a/packages/start-client-core/src/index.tsx b/packages/start-client-core/src/index.tsx index 218c984d60..6ce52a2fa9 100644 --- a/packages/start-client-core/src/index.tsx +++ b/packages/start-client-core/src/index.tsx @@ -70,6 +70,7 @@ export type { ServerFnMiddlewareResult, ServerFnBuilder, ServerFnBaseOptions, + FlattenedMiddlewareEntry, NextFn, Method, OptionalFetcher, @@ -77,8 +78,8 @@ export type { } from './createServerFn' export { execValidator, - flattenMiddlewares, executeMiddleware, + flattenMiddlewaresWithDetails, } from './createServerFn' export { diff --git a/packages/start-client-core/tests/createServerFn.runtime.test.ts b/packages/start-client-core/tests/createServerFn.runtime.test.ts new file mode 100644 index 0000000000..b8ef7e605b --- /dev/null +++ b/packages/start-client-core/tests/createServerFn.runtime.test.ts @@ -0,0 +1,95 @@ +/** @vitest-environment node */ + +import { runWithStartContext } from '@tanstack/start-storage-context' +import { describe, expect, it } from 'vitest' + +import { createMiddleware } from '../src/createMiddleware' +import { + executeMiddleware, + flattenMiddlewaresWithDetails, +} from '../src/createServerFn' + +describe('createServerFn runtime metadata', () => { + it('flattens nested middleware with stable subtree positions', () => { + const mw1 = createMiddleware({ type: 'function' }).server((ctx: any) => + ctx.next(), + ) + const mw2 = createMiddleware({ type: 'function' }).server((ctx: any) => + ctx.next(), + ) + const mw3 = createMiddleware({ type: 'function' }) + .middleware([mw1, mw2]) + .server((ctx: any) => ctx.next()) + const mw4 = createMiddleware({ type: 'function' }).server((ctx: any) => + ctx.next(), + ) + const mw5 = createMiddleware({ type: 'function' }) + .middleware([mw3, mw4]) + .server((ctx: any) => ctx.next()) + + const details = flattenMiddlewaresWithDetails([mw5 as any]) + + expect(details.map((d) => d.middleware)).toEqual([mw1, mw2, mw3, mw4, mw5]) + expect(details.map((d) => d.position)).toEqual([0, 1, 2, 3, 4]) + expect(details.map((d) => d.subtreeStartPosition)).toEqual([0, 1, 0, 3, 0]) + }) + + it('dedupes reused middleware while preserving subtree shape', () => { + const leaf = createMiddleware({ type: 'function' }).server((ctx: any) => + ctx.next(), + ) + const left = createMiddleware({ type: 'function' }) + .middleware([leaf]) + .server((ctx: any) => ctx.next()) + const right = createMiddleware({ type: 'function' }) + .middleware([leaf]) + .server((ctx: any) => ctx.next()) + const root = createMiddleware({ type: 'function' }) + .middleware([left, right]) + .server((ctx: any) => ctx.next()) + + const details = flattenMiddlewaresWithDetails([root as any]) + + expect(details.map((d) => d.middleware)).toEqual([leaf, left, right, root]) + expect(details.map((d) => d.subtreeStartPosition)).toEqual([0, 0, 2, 0]) + }) + + it('classifies handler when later server middleware is skipped', async () => { + const sharedServer = createMiddleware({ type: 'function' }).server( + (ctx: any) => ctx.next(), + ) + + const inspect = createMiddleware({ type: 'function' }).client( + async ({ next }: any) => next(), + ) + + const details = flattenMiddlewaresWithDetails([ + inspect as any, + sharedServer as any, + ]) + + const result = await runWithStartContext( + { + getRouter: () => { + throw new Error('not used') + }, + request: new Request('http://example.com'), + startOptions: {}, + contextAfterGlobalMiddlewares: {}, + executedRequestMiddlewares: new Set([sharedServer]), + }, + () => + executeMiddleware([inspect as any, sharedServer as any], 'client', { + method: 'GET', + data: undefined, + headers: {}, + sendContext: {}, + context: {}, + serverFnMeta: { id: 'test' } as any, + _getMiddlewareEntries: () => details as any, + }), + ) + + expect((result as any).source).toBe('handler') + }) +}) diff --git a/packages/start-plugin-core/src/start-compiler-plugin/compiler.ts b/packages/start-plugin-core/src/start-compiler-plugin/compiler.ts index 62f530d510..d1cc2d113e 100644 --- a/packages/start-plugin-core/src/start-compiler-plugin/compiler.ts +++ b/packages/start-plugin-core/src/start-compiler-plugin/compiler.ts @@ -845,6 +845,7 @@ export class StartCompiler { path: babel.NodePath kind: Exclude methodChain: MethodChainPaths + rootPath: babel.NodePath }> = [] for (const { path, kind } of validCandidates) { @@ -862,6 +863,7 @@ export class StartCompiler { // Walk down the call chain using nodes, look up paths from map let currentNode: t.CallExpression = node let currentPath: babel.NodePath = path + let rootPath: babel.NodePath = path // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition while (true) { @@ -896,9 +898,10 @@ export class StartCompiler { break } currentPath = nextPath + rootPath = nextPath } - pathsToRewrite.push({ path, kind, methodChain }) + pathsToRewrite.push({ path, kind, methodChain, rootPath }) } const refIdents = findReferencedIdentifiers(ast) @@ -924,8 +927,17 @@ export class StartCompiler { Array >() - for (const { path: candidatePath, kind, methodChain } of pathsToRewrite) { - const candidate: RewriteCandidate = { path: candidatePath, methodChain } + for (const { + path: candidatePath, + kind, + methodChain, + rootPath, + } of pathsToRewrite) { + const candidate: RewriteCandidate = { + path: candidatePath, + methodChain, + rootPath, + } const existing = candidatesByKind.get(kind) if (existing) { existing.push(candidate) diff --git a/packages/start-plugin-core/src/start-compiler-plugin/handleCreateMiddleware.ts b/packages/start-plugin-core/src/start-compiler-plugin/handleCreateMiddleware.ts index 5428ce1a88..e18f8d85fd 100644 --- a/packages/start-plugin-core/src/start-compiler-plugin/handleCreateMiddleware.ts +++ b/packages/start-plugin-core/src/start-compiler-plugin/handleCreateMiddleware.ts @@ -1,24 +1,22 @@ +import * as t from '@babel/types' import { stripMethodCall } from './utils' import type { CompilationContext, RewriteCandidate } from './types' +const HAS_SERVER_KEY = 'hasServer' + /** - * Handles createMiddleware transformations for a batch of candidates. - * - * @param candidates - All Middleware candidates to process - * @param context - The compilation context + * Handles createMiddleware transformations. + * - client: strips `.server()` and marks client-only middleware with `hasServer: false` + * - server: keeps runtime code unchanged */ export function handleCreateMiddleware( candidates: Array, context: CompilationContext, ): void { - if (context.env === 'server') { - throw new Error('handleCreateMiddleware should not be called on the server') - } - for (const candidate of candidates) { const { inputValidator, server } = candidate.methodChain - if (inputValidator) { + if (inputValidator && context.env === 'client') { const innerInputExpression = inputValidator.callPath.node.arguments[0] if (!innerInputExpression) { @@ -27,13 +25,47 @@ export function handleCreateMiddleware( ) } - // remove the validator call expression stripMethodCall(inputValidator.callPath) } - if (server) { - // remove the server call expression - stripMethodCall(server.callPath) + if (context.env === 'client') { + if (server) { + stripMethodCall(server.callPath) + } else { + const args = + candidate.rootPath?.get('arguments') ?? + candidate.path.get('arguments') + const firstArg = Array.isArray(args) && args.length > 0 ? args[0] : null + + if (firstArg?.isObjectExpression()) { + const hasExistingKey = firstArg.node.properties.some((property) => { + return ( + t.isObjectProperty(property) && + t.isIdentifier(property.key) && + property.key.name === HAS_SERVER_KEY + ) + }) + + if (!hasExistingKey) { + firstArg.node.properties.push( + t.objectProperty( + t.identifier(HAS_SERVER_KEY), + t.booleanLiteral(false), + ), + ) + } + } else { + const targetPath = candidate.rootPath ?? candidate.path + targetPath.node.arguments = [ + t.objectExpression([ + t.objectProperty( + t.identifier(HAS_SERVER_KEY), + t.booleanLiteral(false), + ), + ]), + ] + } + } } } } diff --git a/packages/start-plugin-core/src/start-compiler-plugin/types.ts b/packages/start-plugin-core/src/start-compiler-plugin/types.ts index 141cb4e28f..a48d0faf7f 100644 --- a/packages/start-plugin-core/src/start-compiler-plugin/types.ts +++ b/packages/start-plugin-core/src/start-compiler-plugin/types.ts @@ -70,6 +70,7 @@ export type MethodChainKey = keyof MethodChainPaths export interface RewriteCandidate { path: babel.NodePath methodChain: MethodChainPaths + rootPath?: babel.NodePath } /** diff --git a/packages/start-plugin-core/tests/compiler.test.ts b/packages/start-plugin-core/tests/compiler.test.ts index a063ea3ffe..1ee42be003 100644 --- a/packages/start-plugin-core/tests/compiler.test.ts +++ b/packages/start-plugin-core/tests/compiler.test.ts @@ -86,7 +86,6 @@ describe('detectKindsInCode', () => { import { createMiddleware } from '@tanstack/react-start' const mw = createMiddleware().server(({ next }) => next()) ` - // Middleware is only valid on client expect(detectKindsInCode(code, 'client')).toEqual(new Set(['Middleware'])) expect(detectKindsInCode(code, 'server')).toEqual(new Set()) }) @@ -163,7 +162,7 @@ describe('detectKindsInCode', () => { ) }) - test('detects all valid kinds on server (excludes Middleware)', () => { + test('detects all valid kinds on server', () => { const code = ` import { createServerFn, createMiddleware, createIsomorphicFn, createServerOnlyFn, createClientOnlyFn } from '@tanstack/react-start' const a = createServerFn().handler(() => {}) @@ -172,7 +171,6 @@ describe('detectKindsInCode', () => { const d = createServerOnlyFn(() => {}) const e = createClientOnlyFn(() => {}) ` - // Middleware should NOT be detected on server expect(detectKindsInCode(code, 'server')).toEqual( new Set(['ServerFn', 'IsomorphicFn', 'ServerOnlyFn', 'ClientOnlyFn']), ) @@ -362,7 +360,6 @@ describe('compiler handles multiple files with different kinds', () => { test('server environment excludes Middleware from detected kinds', async () => { const compiler = createFullCompiler('server') - // Even if Middleware is in detectedKinds, server env should ignore it const result = await compiler.compile({ code: ` import { createMiddleware } from '@tanstack/react-start' @@ -370,12 +367,42 @@ describe('compiler handles multiple files with different kinds', () => { `, id: 'middleware.ts', - // Intentionally including Middleware even though it's server env detectedKinds: new Set(['Middleware']), }) - // Should return null since Middleware is not valid on server expect(result).toBeNull() }) + + test('client-only middleware emits hasServer false', async () => { + const compiler = createFullCompiler('client') + + const result = await compiler.compile({ + code: ` + import { createMiddleware } from '@tanstack/react-start' + export const mw = createMiddleware({ id: 'x' }).client(({ next }) => next()) + `, + id: 'client-only-middleware.ts', + detectedKinds: new Set(['Middleware']), + }) + + expect(result).toBeTruthy() + expect(result!.code).toContain('hasServer: false') + }) + + test('server middleware does not emit hasServer false', async () => { + const compiler = createFullCompiler('client') + + const result = await compiler.compile({ + code: ` + import { createMiddleware } from '@tanstack/react-start' + export const mw = createMiddleware({ id: 'x' }).server(({ next }) => next()) + `, + id: 'server-middleware.ts', + detectedKinds: new Set(['Middleware']), + }) + + expect(result).toBeTruthy() + expect(result!.code).not.toContain('hasServer: false') + }) }) describe('edge cases for detectedKinds', () => { diff --git a/packages/start-plugin-core/tests/createMiddleware/snapshots/client/createMiddlewareClientOnly.tsx b/packages/start-plugin-core/tests/createMiddleware/snapshots/client/createMiddlewareClientOnly.tsx new file mode 100644 index 0000000000..22e9cc3628 --- /dev/null +++ b/packages/start-plugin-core/tests/createMiddleware/snapshots/client/createMiddlewareClientOnly.tsx @@ -0,0 +1,21 @@ +import { createMiddleware } from '@tanstack/react-start'; +export const clientOnly = createMiddleware({ + id: 'clientOnly', + hasServer: false +}).client(async ({ + next +}) => { + return next({ + context: { + clientOnly: true + } + }); +}); +export const nestedClientOnly = createMiddleware({ + id: 'nestedClientOnly', + hasServer: false +}).middleware([clientOnly]).client(async ({ + next +}) => { + return next(); +}); \ No newline at end of file diff --git a/packages/start-plugin-core/tests/createMiddleware/test-files/createMiddlewareClientOnly.tsx b/packages/start-plugin-core/tests/createMiddleware/test-files/createMiddlewareClientOnly.tsx new file mode 100644 index 0000000000..30daa7f11c --- /dev/null +++ b/packages/start-plugin-core/tests/createMiddleware/test-files/createMiddlewareClientOnly.tsx @@ -0,0 +1,17 @@ +import { createMiddleware } from '@tanstack/react-start' + +export const clientOnly = createMiddleware({ + id: 'clientOnly', +}).client(async ({ next }) => { + return next({ + context: { clientOnly: true }, + }) +}) + +export const nestedClientOnly = createMiddleware({ + id: 'nestedClientOnly', +}) + .middleware([clientOnly]) + .client(async ({ next }) => { + return next() + }) diff --git a/packages/start-server-core/src/createStartHandler.ts b/packages/start-server-core/src/createStartHandler.ts index 625e9cc487..fafb39098e 100644 --- a/packages/start-server-core/src/createStartHandler.ts +++ b/packages/start-server-core/src/createStartHandler.ts @@ -1,7 +1,7 @@ import { createMemoryHistory } from '@tanstack/history' import { createNullProtoObject, - flattenMiddlewares, + flattenMiddlewaresWithDetails, mergeHeaders, safeObjectMerge, } from '@tanstack/start-client-core' @@ -457,7 +457,9 @@ export function createStartHandler( // Flatten request middlewares once const flattenedRequestMiddlewares = startOptions.requestMiddleware - ? flattenMiddlewares(startOptions.requestMiddleware) + ? flattenMiddlewaresWithDetails(startOptions.requestMiddleware).map( + (entry) => entry.middleware as AnyRequestMiddleware, + ) : [] // Create set for deduplication @@ -527,7 +529,7 @@ export function createStartHandler( } const middlewares = flattenedRequestMiddlewares.map( - (d) => d.options.server, + (d: AnyRequestMiddleware) => d.options.server, ) const ctx = await executeMiddleware([...middlewares, serverFnHandler], { request, @@ -622,7 +624,7 @@ export function createStartHandler( } const middlewares = flattenedRequestMiddlewares.map( - (d) => d.options.server, + (d: AnyRequestMiddleware) => d.options.server, ) const ctx = await executeMiddleware( [...middlewares, requestHandlerMiddleware], @@ -742,10 +744,10 @@ async function handleServerRoutes({ | Array | undefined if (serverMiddleware) { - const flattened = flattenMiddlewares(serverMiddleware) + const flattened = flattenMiddlewaresWithDetails(serverMiddleware) for (const m of flattened) { - if (!executedRequestMiddlewares.has(m)) { - routeMiddlewares.push(m.options.server) + if (!executedRequestMiddlewares.has(m.middleware)) { + routeMiddlewares.push(m.middleware.options.server) } } } @@ -769,9 +771,11 @@ async function handleServerRoutes({ routeMiddlewares.push(handlerToMiddleware(handler, mayDefer)) } else { if (handler.middleware?.length) { - const handlerMiddlewares = flattenMiddlewares(handler.middleware) + const handlerMiddlewares = flattenMiddlewaresWithDetails( + handler.middleware, + ) for (const m of handlerMiddlewares) { - routeMiddlewares.push(m.options.server) + routeMiddlewares.push(m.middleware.options.server) } } if (handler.handler) { diff --git a/packages/start-server-core/src/server-functions-handler.ts b/packages/start-server-core/src/server-functions-handler.ts index 4f5067a7eb..42eded66f0 100644 --- a/packages/start-server-core/src/server-functions-handler.ts +++ b/packages/start-server-core/src/server-functions-handler.ts @@ -3,6 +3,7 @@ import { isNotFound, isRedirect, } from '@tanstack/router-core' +import { mergeHeaders } from '@tanstack/router-core/ssr/client' import invariant from 'tiny-invariant' import { TSS_FORMDATA_CONTEXT, @@ -180,6 +181,8 @@ export const handleServerAction = async ({ let nonStreamingBody: any = undefined const alsResponse = getResponse() + // Normalize any headers from the server function result + const serverFnHeaders = mergeHeaders((res as any)?.headers) if (res !== undefined) { // Collect raw streams encountered during serialization const rawStreams = new Map>() @@ -230,10 +233,13 @@ export const handleServerAction = async ({ { status: alsResponse.status, statusText: alsResponse.statusText, - headers: { - 'Content-Type': 'application/json', - [X_TSS_SERIALIZED]: 'true', - }, + headers: mergeHeaders( + { + 'Content-Type': 'application/json', + [X_TSS_SERIALIZED]: 'true', + }, + serverFnHeaders, + ), }, ) } @@ -270,10 +276,13 @@ export const handleServerAction = async ({ return new Response(multiplexedStream, { status: alsResponse.status, statusText: alsResponse.statusText, - headers: { - 'Content-Type': TSS_CONTENT_TYPE_FRAMED_VERSIONED, - [X_TSS_SERIALIZED]: 'true', - }, + headers: mergeHeaders( + { + 'Content-Type': TSS_CONTENT_TYPE_FRAMED_VERSIONED, + [X_TSS_SERIALIZED]: 'true', + }, + serverFnHeaders, + ), }) } @@ -301,10 +310,13 @@ export const handleServerAction = async ({ return new Response(stream, { status: alsResponse.status, statusText: alsResponse.statusText, - headers: { - 'Content-Type': 'application/x-ndjson', - [X_TSS_SERIALIZED]: 'true', - }, + headers: mergeHeaders( + { + 'Content-Type': 'application/x-ndjson', + [X_TSS_SERIALIZED]: 'true', + }, + serverFnHeaders, + ), }) }