Redirects, Rewrites & Proxy

async redirects() {
  return [
    // only when the cookie beta=off is present
    {
      source: "/beta",
      has: [{ type: "cookie", key: "beta", value: "off" }],
      destination: "/en",
      permanent: false,
    },
    // only when the header x-no-redirect is absent
    {
      source: "/store",
      missing: [{ type: "header", key: "x-no-redirect" }],
      destination: "https://example.com/store",
      permanent: false,
    },
    // named capture group in a query value, reused in the destination
    {
      source: "/search",
      has: [{ type: "query", key: "term", value: "(?<t>.+)" }],
      destination: "/en?q=:t",
      permanent: false,
    },
    // host matching
    {
      source: "/hostcheck",
      has: [{ type: "host", value: "shop.example.test" }],
      destination: "/en",
      permanent: false,
    },
  ];
},

$ curl -I localhost:3306/beta
location: /en/beta                    # no cookie: rule skipped, the Proxy added the locale

$ curl -I -H 'Cookie: beta=off' localhost:3306/beta
location: /en                         # the has rule applied

$ curl -I "localhost:3306/search?term=dune"
location: /en?term=dune&q=dune        # captured value used, original query kept

$ curl -I -H 'Host: shop.example.test' localhost:3306/hostcheck
location: /en

$ curl -I localhost:3306/shop/catalog/7
location: /shop/en/books/7            # source and destination both prefixed

$ curl -I localhost:3306/outside      # rule with basePath: false, no /shop in the source
location: https://example.com/

import { notFound, permanentRedirect } from "next/navigation";

const renamed: Record<string, string> = { "stanislaw-lem": "lem", "u-le-guin": "le-guin" };
const current = new Set(["lem", "le-guin"]);

export default async function Author({ params }: PageProps<"/[locale]/authors/[slug]">) {
  const { locale, slug } = await params;
  if (slug in renamed) permanentRedirect(`/${locale}/authors/${renamed[slug]}`);
  if (!current.has(slug)) notFound();
  return <h1>Author {slug}</h1>;
}

$ curl -I localhost:3306/en/authors/stanislaw-lem
HTTP/1.1 308 Permanent Redirect
location: /en/authors/lem

$ curl -I localhost:3306/en/authors/lem
HTTP/1.1 200 OK

$ curl -I localhost:3306/en/authors/zzz
HTTP/1.1 404 Not Found

$ curl -s localhost:3306/en/writers/stanislaw-lem | grep -o -E '<meta id="__next-page-redirect"[^>]*>'
<meta id="__next-page-redirect" http-equiv="refresh" content="0;url=/en/writers/lem"/>
# the status line of that response: HTTP/1.1 200 OK

import { Suspense } from "react";
import { notFound, permanentRedirect } from "next/navigation";

const renamed: Record<string, string> = { "stanislaw-lem": "lem", "u-le-guin": "le-guin" };
const current = new Set(["lem", "le-guin"]);

export default function Page(props: PageProps<"/[locale]/authors/[slug]">) {
  return (
    <Suspense fallback={<p>Loading…</p>}>
      <Author params={props.params} />
    </Suspense>
  );
}

async function Author({ params }: { params: PageProps<"/[locale]/authors/[slug]">["params"] }) {
  const { locale, slug } = await params;
  if (slug in renamed) permanentRedirect(`/${locale}/authors/${renamed[slug]}`);
  if (!current.has(slug)) notFound();
  return <h1>Author {slug}</h1>;
}

$ curl -I localhost:3306/en/authors/stanislaw-lem     # Cache Components build
HTTP/1.1 200 OK
$ curl -s localhost:3306/en/authors/stanislaw-lem | grep -o -E '<meta id="__next-page-redirect"[^>]*>'
<meta id="__next-page-redirect" http-equiv="refresh" content="0;url=/en/authors/lem"/>
$ curl -I localhost:3306/en/authors/zzz               # unknown slug, notFound() inside the boundary
HTTP/1.1 200 OK

"use client";

import { redirect, usePathname } from "next/navigation";

export function ClientRedirect({ locale }: { locale: string }) {
  const pathname = usePathname();

  // Called while rendering, not in an event handler (use useRouter().push there).
  if (!pathname.endsWith("/login")) {
    redirect(`/${locale}/login`);
  }

  return <p>Sign in</p>;
}

$ curl -I localhost:3306/en/admin
HTTP/1.1 307 Temporary Redirect
location: /en/login

"use server";

import { redirect } from "next/navigation";
import { revalidatePath } from "next/cache";
import { isLocale, defaultLocale } from "@/lib/i18n";

export async function createBook(formData: FormData) {
  const title = String(formData.get("title") ?? "").trim();
  const requested = String(formData.get("locale") ?? "");
  const locale = isLocale(requested) ? requested : defaultLocale;
  if (!title) redirect(`/${locale}/books/new?error=title`);

  const id = "1"; // pretend we inserted a row and got its id
  revalidatePath(`/${locale}/books`);
  redirect(`/${locale}/books/${id}`); // outside any try/catch: redirect() throws
}

import { createBook } from "./actions";

export default async function NewBook({ params }: PageProps<"/[locale]/books/new">) {
  const { locale } = await params;
  return (
    <form action={createBook}>
      <input type="hidden" name="locale" value={locale} />
      <input name="title" />
      <button>Add</button>
    </form>
  );
}

$ ID=$(curl -s localhost:3306/en/books/new | grep -o 'name="\$ACTION_ID_[0-9a-f]*"' | head -1 | sed 's/name="//;s/"//')
$ curl -si -X POST -F "$ID=" -F locale=en -F "title=Roadside Picnic" localhost:3306/en/books/new | grep -i -E "^HTTP|^location"
HTTP/1.1 303 See Other
Location: /en/books/1

$ curl -si -X POST -F "$ID=" -F locale=es -F "title=" localhost:3306/en/books/new | grep -i -E "^HTTP|^location"
HTTP/1.1 303 See Other
Location: /es/books/new?error=title

$ curl -si -X POST -F "$ID=" -F locale=//evil.example -F "title=x" localhost:3306/en/books/new | grep -i -E "^HTTP|^location"
HTTP/1.1 303 See Other
Location: /en/books/1

// Accept only same-site relative paths from a ?from= parameter.
export function safeNext(from: string | null | undefined, fallback: string): string {
  if (!from) return fallback;
  // must start with a single slash; "//host" and "/\host" are protocol-relative tricks
  if (!from.startsWith("/") || from.startsWith("//") || from.startsWith("/\\")) return fallback;
  try {
    const url = new URL(from, "http://localhost"); // resolves against a dummy origin
    if (url.origin !== "http://localhost") return fallback;
    return url.pathname + url.search;
  } catch {
    return fallback;
  }
}

"/en/account?x=1"      -> /en/account?x=1
"//evil.example/x"     -> /en
"https://evil.example" -> /en
"/\\evil.example"      -> /en
"javascript:alert(1)"  -> /en
null                   -> /en

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|legacy|favicon.ico|.*\\..*).*)"],
};

export const config = {
  matcher: [
    {
      source: "/((?!api|_next/static|_next/image|favicon.ico).*)",
      // skip prefetches
      missing: [
        { type: "header", key: "next-router-prefetch" },
        { type: "header", key: "purpose", value: "prefetch" },
      ],
    },
  ],
};

$ curl -I localhost:3306/en/login
x-proxy-ran: /en/login
$ curl -I -H 'next-router-prefetch: 1' localhost:3306/en/login      # no x-proxy-ran header
$ curl -I -H 'purpose: prefetch' localhost:3306/en/login            # no x-proxy-ran header
$ curl -I localhost:3306/api/health                                 # excluded by the lookahead: no header

import { NextResponse, type NextRequest } from "next/server";
import { locales, defaultLocale, isLocale } from "@/lib/i18n";

function pickLocale(request: NextRequest): string {
  const preferred = request.headers.get("accept-language")?.slice(0, 2) ?? "";
  return isLocale(preferred) ? preferred : defaultLocale;
}

// Clone nextUrl (not `new URL(path, request.url)`) so basePath is re-applied.
function withPath(request: NextRequest, pathname: string, search = request.nextUrl.search) {
  const url = request.nextUrl.clone();
  url.pathname = pathname;
  url.search = search;
  return url;
}

export async function proxy(request: NextRequest) {
  const { pathname, search } = request.nextUrl;

  // Optimistic check only: the real authorisation lives in the Data Access Layer.
  const account = /^\/(en|es)\/account(\/|$)/.exec(pathname);
  if (account && !request.cookies.has("bookshelf_session")) {
    const login = withPath(request, `/${account[1]}/login`, "");
    login.searchParams.set("from", pathname + search);
    return NextResponse.redirect(login);
  }

  // A/B test: sticky bucket in a cookie, rewrite keeps the URL.
  if (/^\/(en|es)\/about$/.test(pathname)) {
    const bucket = request.cookies.get("bucket")?.value ?? (Math.random() < 0.5 ? "a" : "b");
    const response =
      bucket === "b" ? NextResponse.rewrite(withPath(request, `${pathname}-b`)) : NextResponse.next();
    if (!request.cookies.has("bucket")) {
      response.cookies.set("bucket", bucket, { path: "/", maxAge: 60 * 60 * 24 * 30, sameSite: "lax" });
    }
    return response;
  }

  // Locale redirect.
  if (!locales.some((l) => pathname === `/${l}` || pathname.startsWith(`/${l}/`))) {
    return NextResponse.redirect(withPath(request, `/${pickLocale(request)}${pathname}`));
  }

  // Pass data to the app: request headers (upstream only) + a response header for the demo.
  const requestHeaders = new Headers(request.headers);
  requestHeaders.set("x-request-id", crypto.randomUUID());
  requestHeaders.set("x-locale", pathname.split("/")[1]);
  const response = NextResponse.next({ request: { headers: requestHeaders } });
  response.headers.set("x-bookshelf-proxy", "ran");
  return response;
}

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|legacy|favicon.ico|.*\\..*).*)"],
};

$ curl -I localhost:3306/en/account
HTTP/1.1 307 Temporary Redirect
location: /en/login?from=%2Fen%2Faccount

$ curl -I -H 'Cookie: bookshelf_session=x' localhost:3306/en/account
HTTP/1.1 200 OK

$ curl -I -H 'accept-language: es' localhost:3306/books/2
location: /es/books/2

$ curl -I localhost:3306/en/about                           # first visit: bucket assigned
set-cookie: bucket=a; Path=/; Expires=...; Max-Age=2592000; SameSite=lax

$ curl -I -H 'Cookie: bucket=b' localhost:3306/en/about
x-middleware-rewrite: /en/about-b

$ curl -s -H 'Cookie: bucket=b' localhost:3306/en/about | grep -o 'About (variant [AB])'
About (variant B)

import type { NextRequest } from "next/server";

// Only the Bookshelf write API; reads stay public.
export const config = { matcher: "/api/admin/:path*" };

export function proxy(request: NextRequest) {
  const token = request.headers.get("authorization");
  // Optimistic: only checks that a bearer token is present. Verify it in the handler.
  if (!token?.startsWith("Bearer ")) {
    return Response.json({ success: false, message: "authentication required" }, { status: 401 });
  }
}

$ curl -i localhost:3306/api/admin/books
HTTP/1.1 401 Unauthorized
content-type: application/json

{"success":false,"message":"authentication required"}

$ curl -i -H 'Authorization: Bearer test-token' localhost:3306/api/admin/books
HTTP/1.1 200 OK

{"ok":true}

import { NextResponse, type NextFetchEvent, type NextRequest } from "next/server";

export function proxy(request: NextRequest, event: NextFetchEvent) {
  const started = Date.now();
  // runs after the response has been sent; must not block it
  event.waitUntil(
    new Promise<void>((resolve) =>
      setTimeout(() => {
        console.log(`AUDIT ${request.method} ${request.nextUrl.pathname} after ${Date.now() - started}ms`);
        resolve();
      }, 300),
    ),
  );
  return NextResponse.next();
}

export const config = { matcher: "/api/health" };

$ curl -s -o /dev/null -w "response in %{time_total}s\n" localhost:3306/api/health
response in 0.001907s
# server log, a moment later:
AUDIT GET /api/health after 302ms

$ npx @next/codemod@canary middleware-to-proxy .

// middleware.ts -> proxy.ts

- export function middleware() {
+ export function proxy() {