feat(middleware)!: forbids middleware response body

.gitignore

@@ -29,6 +29,7 @@ test/tmp/**
 # Editors
 **/.idea
 **/.#*
+.nvmrc
 
 # examples
 examples/**/out

docs/advanced-features/middleware.md

@@ -31,10 +31,14 @@ npm install next@latest
 ```jsx
 // middleware.ts
 
-import type { NextFetchEvent, NextRequest } from 'next/server'
-
-export function middleware(req: NextRequest, ev: NextFetchEvent) {
-  return new Response('Hello, world!')
+import type { NextRequest, NextResponse } from 'next/server'
+import { areCredentialsValid } from '../lib'
+
+export function middleware(req: NextRequest) {
+  if (areCredentialsValid(req.headers.get('authorization')) {
+    return NextResponse.next()
+  }
+  return NextResponse.redirect(`/login?from=${req.nextUrl.pathname}`)
 }
 ```
 

docs/api-reference/next/server.md

@@ -105,7 +105,6 @@ The following static methods are available on the `NextResponse` class directly:
 - `redirect()` - Returns a `NextResponse` with a redirect set
 - `rewrite()` - Returns a `NextResponse` with a rewrite set
 - `next()` - Returns a `NextResponse` that will continue the middleware chain
-- `json()` - A convenience method to create a response that encodes the provided JSON data
 
 ```ts
 import { NextResponse } from 'next/server'
@@ -120,7 +119,7 @@ export function middleware(req: NextRequest) {
     return NextResponse.rewrite('/not-home')
   }
 
-  return NextResponse.json({ message: 'Hello World!' })
+  return NextResponse.next()
 }
 ```
 
@@ -183,6 +182,21 @@ console.log(NODE_ENV)
 console.log(process.env)
 ```
 
+### The body limitation
+
+When using middlewares, it is not permitted to change the response body: you can only set responses headers.
+Returning a body from a middleware function will issue an `500` server error with an explicit response message.
+
+The `NextResponse` API (which eventually is tweaking response headers) allows you to:
+
+- redirect the incoming request to a different url
+- rewrite the response by displaying a given url
+- set response cookies
+- set response headers
+
+These are solid tools to implement cases such as A/B testing, authentication, feature flags, bot protection...
+A middleware with the ability to change the response's body would bypass Next.js routing logic.
+
 ## Related
 
 <div class="card">

errors/manifest.json

@@ -657,6 +657,10 @@
         {
           "title": "invalid-script",
           "path": "/errors/invalid-script.md"
+        },
+        {
+          "title": "returning-response-body-in-middleware",
+          "path": "/errors/returning-response-body-in-middleware.md"
         }
       ]
     }

errors/returning-response-body-in-middleware.md

@@ -0,0 +1,84 @@
+# Returning response body in middleware
+
+#### Why This Error Occurred
+
+Your [`middleware`](https://nextjs.org/docs/advanced-features/middleware) function returns a response body, which is not supported.
+
+Letting middleware respond to incoming requests would bypass Next.js routing mechanism, creating an unecessary escape hatch.
+
+#### Possible Ways to Fix It
+
+Next.js middleware gives you a great opportunity to run code and adjust to the requesting user.
+
+It is intended for use cases like:
+
+- A/B testing, where you **_rewrite_** to a different page based on external data (User agent, user location, a custom header or cookie...)
+
+  ```js
+  export function middleware(req: NextRequest) {
+    let res = NextResponse.next()
+    // reuses cookie, or builds a new one.
+    const cookie = req.cookies.get(COOKIE_NAME) ?? buildABTestingCookie()
+
+    // the cookie contains the displayed variant, 0 being default
+    const [, variantId] = cookie.split('.')
+    if (variantId !== '0') {
+      const url = req.nextUrl.clone()
+      url.pathname = url.pathname.replace('/', `/${variantId}/`)
+      // rewrites the response to display desired variant
+      res = NextResponse.rewrite(url)
+    }
+
+    // don't forget to set cookie if not set yet
+    if (!req.cookies.has(COOKIE_NAME)) {
+      res.cookies.set(COOKIE_NAME, cookie)
+    }
+    return res
+  }
+  ```
+
+- authentication, where you **_redirect_** to your log-in/sign-in page any un-authenticated request
+
+  ```js
+  export function middleware(req: NextRequest) {
+    const basicAuth = req.headers.get('authorization')
+
+    if (basicAuth) {
+      const auth = basicAuth.split(' ')[1]
+      const [user, pwd] = atob(auth).split(':')
+      if (areCredentialsValid(user, pwd)) {
+        return NextResponse.next()
+      }
+    }
+
+    return NextResponse.redirect(`/login?from=${req.nextUrl.pathname}`)
+  }
+  ```
+
+- detecting bots and **_rewrite_** response to display to some sink
+
+  ```js
+  export function middleware(req: NextRequest) {
+    if (isABotRequest(req)) {
+      // Bot detected! rewrite to the sink
+      const url = req.nextUrl.clone()
+      url.pathname = '/bot-detected'
+      return NextResponse.rewrite(url)
+    }
+    return NextResponse.next()
+  }
+  ```
+
+- programmatically adding **_headers_** to the response, like cookies.
+
+  ```js
+  export function middleware(req: NextRequest) {
+    const res = NextResponse.next(null, {
+      // sets a custom response header
+      headers: { 'response-greetings': 'Hej!' },
+    })
+    // configures cookies
+    response.cookies.set('hello', 'world')
+    return res
+  }
+  ```

packages/next/build/webpack/loaders/next-middleware-loader.ts

@@ -16,7 +16,7 @@ export default function middlewareLoader(this: any) {
   }
 
   return `
-        import { adapter } from 'next/dist/server/web/adapter'
+        import { adapter, blockUnallowedResponse } from 'next/dist/server/web/adapter'
 
         // The condition is true when the "process" module is provided
         if (process !== global.process) {
@@ -33,11 +33,11 @@ export default function middlewareLoader(this: any) {
         }
 
         export default function (opts) {
-          return adapter({
+          return blockUnallowedResponse(adapter({
               ...opts,
               page: ${JSON.stringify(page)},
               handler,
-          })
+          }))
         }
     `
 }

packages/next/build/webpack/plugins/middleware-plugin.ts

@@ -54,11 +54,14 @@ export default class MiddlewarePlugin {
   apply(compiler: webpack5.Compiler) {
     compiler.hooks.compilation.tap(NAME, (compilation, params) => {
       const { hooks } = params.normalModuleFactory
-
       /**
        * This is the static code analysis phase.
        */
-      const codeAnalyzer = getCodeAnalizer({ dev: this.dev, compiler })
+      const codeAnalyzer = getCodeAnalizer({
+        dev: this.dev,
+        compiler,
+        compilation,
+      })
       hooks.parser.for('javascript/auto').tap(NAME, codeAnalyzer)
       hooks.parser.for('javascript/dynamic').tap(NAME, codeAnalyzer)
       hooks.parser.for('javascript/esm').tap(NAME, codeAnalyzer)
@@ -94,11 +97,13 @@ export default class MiddlewarePlugin {
 function getCodeAnalizer(params: {
   dev: boolean
   compiler: webpack5.Compiler
+  compilation: webpack5.Compilation
 }) {
   return (parser: webpack5.javascript.JavascriptParser) => {
     const {
       dev,
       compiler: { webpack: wp },
+      compilation,
     } = params
     const { hooks } = parser
 
@@ -176,6 +181,31 @@ function getCodeAnalizer(params: {
       }
     }
 
+    /**
+     * A handler for calls to `new Response()` so we can fail if user is setting the response's body.
+     */
+    const handleNewResponseExpression = (node: any) => {
+      const firstParameter = node?.arguments?.[0]
+      if (
+        isUserMiddlewareUserFile(parser.state.current) &&
+        firstParameter &&
+        !isNullLiteral(firstParameter) &&
+        !isUndefinedIdentifier(firstParameter)
+      ) {
+        const error = new wp.WebpackError(
+          `Your middleware is returning a response body (line: ${node.loc.start.line}), which is not supported. Learn more: https://nextjs.org/docs/messages/returning-response-body-in-middleware`
+        )
+        error.name = NAME
+        error.module = parser.state.current
+        error.loc = node.loc
+        if (dev) {
+          compilation.warnings.push(error)
+        } else {
+          compilation.errors.push(error)
+        }
+      }
+    }
+
     /**
      * A noop handler to skip analyzing some cases.
      * Order matters: for it to work, it must be registered first
@@ -192,6 +222,8 @@ function getCodeAnalizer(params: {
       hooks.expression.for(`${prefix}eval`).tap(NAME, handleExpression)
       hooks.expression.for(`${prefix}Function`).tap(NAME, handleExpression)
     }
+    hooks.new.for('Response').tap(NAME, handleNewResponseExpression)
+    hooks.new.for('NextResponse').tap(NAME, handleNewResponseExpression)
     hooks.callMemberChain.for('process').tap(NAME, handleCallMemberChain)
     hooks.expressionMemberChain.for('process').tap(NAME, handleCallMemberChain)
   }
@@ -421,3 +453,17 @@ function getEntryFiles(entryFiles: string[], meta: EntryMetadata) {
   )
   return files
 }
+
+function isUserMiddlewareUserFile(module: any) {
+  return (
+    module.layer === 'middleware' && /middleware\.\w+$/.test(module.rawRequest)
+  )
+}
+
+function isNullLiteral(expr: any) {
+  return expr.value === null
+}
+
+function isUndefinedIdentifier(expr: any) {
+  return expr.name === 'undefined'
+}

packages/next/server/web/adapter.ts

@@ -27,14 +27,36 @@ export async function adapter(params: {
   })
 
   const event = new NextFetchEvent({ request, page: params.page })
-  const original = await params.handler(request, event)
+  const response = await params.handler(request, event)
 
   return {
-    response: original || NextResponse.next(),
+    response: response || NextResponse.next(),
     waitUntil: Promise.all(event[waitUntilSymbol]),
   }
 }
 
+export function blockUnallowedResponse(
+  promise: Promise<FetchEventResult>
+): Promise<FetchEventResult> {
+  return promise.then((result) => {
+    if (result.response?.body) {
+      console.error(
+        new Error(
+          `A middleware can not alter response's body. Learn more: https://nextjs.org/docs/messages/returning-response-body-in-middleware`
+        )
+      )
+      return {
+        ...result,
+        response: new Response('Internal Server Error', {
+          status: 500,
+          statusText: 'Internal Server Error',
+        }),
+      }
+    }
+    return result
+  })
+}
+
 class NextRequestHint extends NextRequest {
   sourcePage: string
 

packages/next/server/web/error.ts

@@ -3,7 +3,7 @@ export class DeprecationError extends Error {
     super(`The middleware "${page}" accepts an async API directly with the form:
 
   export function middleware(request, event) {
-    return new Response("Hello " + request.url)
+    return NextResponse.redirect('/new-location')
   }
 
   Read more: https://nextjs.org/docs/messages/middleware-new-signature

packages/next/server/web/spec-compliant/response.ts

@@ -46,8 +46,8 @@ class BaseResponse extends Body implements Response {
       )
     }
 
-    return new Response(validateURL(url), {
-      headers: { Location: url },
+    return new Response(null, {
+      headers: { Location: validateURL(url) },
       status,
     })
   }

packages/next/server/web/spec-extension/response.ts

@@ -51,26 +51,21 @@ export class NextResponse extends Response {
       )
     }
 
-    const destination = validateURL(url)
-    return new NextResponse(destination, {
-      headers: { Location: destination },
+    return new NextResponse(null, {
+      headers: { Location: validateURL(url) },
       status,
     })
   }
 
   static rewrite(destination: string | NextURL | URL) {
     return new NextResponse(null, {
-      headers: {
-        'x-middleware-rewrite': validateURL(destination),
-      },
+      headers: { 'x-middleware-rewrite': validateURL(destination) },
     })
   }
 
   static next() {
     return new NextResponse(null, {
-      headers: {
-        'x-middleware-next': '1',
-      },
+      headers: { 'x-middleware-next': '1' },
     })
   }
 }