Server Request Lifecycle | blade47/next.js Wiki | doc0

Public

Class / Function	Target Use Case	Key Methods	Sources
`NextServer`	`next start` production server wrapper	`getRequestHandler()`, `getServer()`, `prepare()`	packages/next/src/server/next.ts:183-423
`NextCustomServer`	Custom servers using `import next from 'next'`	`prepare()`, `getRequestHandler()`, `render()`	packages/next/src/server/next.ts:425-612
`startServer`	Standalone server lifecycle runner	`requestListener()`, `server.listen()`	packages/next/src/server/lib/start-server.ts:184-353

async function requestListener(req: IncomingMessage, res: ServerResponse) {
  try {
    if (handlersPromise) {
      await handlersPromise
      handlersPromise = undefined
    }
    await requestHandler(req, res)
  } catch (err) {
    res.statusCode = 500
    res.end('Internal Server Error')
    Log.error(`Failed to handle request for ${req.url}`)
    console.error(err)
  }
}

Abstract Class	Concrete Node.js Class	Concrete Web Class	Destination / Underlying Body Type	Sources
`BaseNextRequest`	`NodeNextRequest`	`WebNextRequest`	Node.js `Readable` stream vs Web `ReadableStream	null`
`BaseNextResponse`	`NodeNextResponse`	`WebNextResponse`	Node.js `Writable` (`ServerResponse`) vs Web `WritableStream` (`TransformStream`)	packages/next/src/server/base-http/index.ts:47-103, packages/next/src/server/base-http/node.ts:75-169, packages/next/src/server/base-http/web.ts:38-140

export class WebNextResponse extends BaseNextResponse<WritableStream> {
  private headers = new Headers()
  private textBody: string | undefined = undefined
  private closeController = new CloseController()
  public statusCode: number | undefined
  public statusMessage: string | undefined
 
  constructor(public transformStream = new TransformStream()) {
    super(transformStream.writable)
  }
 
  setHeader(name: string, value: string | string[]): this {
    this.headers.delete(name)
    for (const val of Array.isArray(value) ? value : [value]) {
      this.headers.append(name, val)
    }
    return this
  }
}

export const NEXT_REQUEST_META = Symbol.for('NextInternalRequestMeta')
 
export type NextIncomingMessage = (
  | BaseNextRequest
  | IncomingMessage
  | NextRequest
) & {
  [NEXT_REQUEST_META]?: RequestMeta
}

export function getRequestMeta(
  req: NextIncomingMessage,
  key?: undefined
): RequestMeta
export function getRequestMeta<K extends keyof RequestMeta>(
  req: NextIncomingMessage,
  key: K
): RequestMeta[K]
export function getRequestMeta<K extends keyof RequestMeta>(
  req: NextIncomingMessage,
  key?: K
): RequestMeta | RequestMeta[K] {
  const meta = req[NEXT_REQUEST_META] || {}
  return typeof key === 'string' ? meta[key] : meta
}
 
export function setRequestMeta(req: NextIncomingMessage, meta: RequestMeta) {
  req[NEXT_REQUEST_META] = meta
  return meta
}
 
export function addRequestMeta<K extends keyof RequestMeta>(
  request: NextIncomingMessage,
  key: K,
  value: RequestMeta[K]
) {
  const meta = getRequestMeta(request)
  meta[key] = value
  return setRequestMeta(request, meta)
}
 
export function removeRequestMeta<K extends keyof RequestMeta>(
  request: NextIncomingMessage,
  key: K
) {
  const meta = getRequestMeta(request)
  delete meta[key]
  return setRequestMeta(request, meta)
}

export function patchSetHeaderWithCookieSupport(
  req: NextIncomingMessage,
  res: PatchableResponse
) {
  if (res[PATCHED_SET_HEADER]) {
    return
  }
 
  const setHeader = res.setHeader.bind(res)
 
  Object.defineProperty(res, PATCHED_SET_HEADER, {
    value: true,
  })
 
  res.setHeader = (
    name: string,
    value: string | string[]
  ): PatchableResponse => {
    if ('headersSent' in res && res.headersSent) {
      return res
    }
 
    if (name.toLowerCase() === 'set-cookie') {
      const middlewareValue = getRequestMeta(req, 'middlewareCookie')
 
      if (
        !middlewareValue ||
        !Array.isArray(value) ||
        !value.every((item, idx) => item === middlewareValue[idx])
      ) {
        value = [
          ...new Set([
            ...(middlewareValue || []),
            ...(typeof value === 'string'
              ? [value]
              : Array.isArray(value)
                ? value
                : []),
          ]),
        ]
      }
    }
 
    return setHeader(name, value)
  }
}

  private normalize = (pathname: string) => {
    const normalizers: Array<PathnameNormalizer> = []
 
    if (this.normalizers.data) {
      normalizers.push(this.normalizers.data)
    }
 
    // We have to put the segment prefetch normalizer before the RSC normalizer
    // because the RSC normalizer will match the prefetch RSC routes too.
    if (this.normalizers.segmentPrefetchRSC) {
      normalizers.push(this.normalizers.segmentPrefetchRSC)
    }
 
    if (this.normalizers.rsc) {
      normalizers.push(this.normalizers.rsc)
    }
 
    for (const normalizer of normalizers) {
      if (!normalizer.match(pathname)) continue
 
      return normalizer.normalize(pathname, true)
    }
 
    return pathname
  }

Design Choice	Benefit	Cost
Sequential normalizer array evaluation	Deterministic matching order for overlapping patterns like RSC and segment prefetches	Linear search overhead across registered normalizers per request
Centralized tracing via `BaseServerSpan`	Detailed OpenTelemetry instrumentation across request lifecycles	Additional wrapper allocation per pipeline phase
Lazy instrumentation loading during `prepare()`	Avoids blocking server startup when instrumentation is absent	Deferred module resolution check until initialization completes

export async function imageOptimizer(
  imageUpstream: ImageUpstream,
  paramsResult: Pick<ImageParamsResult, 'href' | 'width' | 'quality' | 'mimeType'>,
  nextConfig: { ... },
  opts: { isDev?: boolean; silent?: boolean; previousCacheEntry?: IncrementalResponseCacheEntry | null }
) {
  const { href, quality, width, mimeType } = paramsResult
  const { buffer: upstreamBuffer, etag: upstreamEtag } = imageUpstream
  const maxAge = Math.max(nextConfig.images.minimumCacheTTL, getMaxAge(imageUpstream.cacheControl))
  // Detects content type, validates SVG policies, handles animated/bypass types, and optimizes buffer
}

Constant / Array	Values / Types	Purpose
`ANIMATABLE_TYPES`	`['image/webp', 'image/png', 'image/gif']`	Formats checked for animation frames that bypass optimization
`BYPASS_TYPES`	`['image/svg+xml', 'image/x-icon', 'image/x-icns', 'image/bmp', 'image/jxl', 'image/heic']`	Formats returned directly without running the sharp transformer
`CACHE_VERSION`	`4`	Version identifier embedded into image cache key generation hashes
`BLUR_IMG_SIZE`	`8`	Default width assigned to generated blur placeholder images

function parseRequestHeaders(
  headers: IncomingHttpHeaders,
  options: ParseRequestHeadersOptions
): ParsedRequestHeaders {
  const isPrefetchRequest = headers[NEXT_ROUTER_PREFETCH_HEADER] === '1'
  const isAppShellPrefetchRequest = headers[NEXT_ROUTER_PREFETCH_HEADER] === '3'
  const isRuntimePrefetchRequest =
    headers[NEXT_ROUTER_PREFETCH_HEADER] === '2' || isAppShellPrefetchRequest
  const isHmrRefresh = headers[NEXT_HMR_REFRESH_HEADER] !== undefined
  const isRSCRequest = isRSCRequestHeader(headers[RSC_HEADER])
  // ...

  private async pipeImpl(
    fn: (
      ctx: RequestContext<ServerRequest, ServerResponse>
    ) => Promise<ResponsePayload | null>,
    partialContext: Omit<
      RequestContext<ServerRequest, ServerResponse>,
      'renderOpts'
    >
  ): Promise<void> {
    const ua = partialContext.req.headers['user-agent'] || ''
 
    const ctx: RequestContext<ServerRequest, ServerResponse> = {
      ...partialContext,
      renderOpts: {
        ...this.renderOpts,
        supportsDynamicResponse: !this.renderOpts.botType,
        serveStreamingMetadata: shouldServeStreamingMetadata(
          ua,
          this.nextConfig.htmlLimitedBots
        ),
      },
    }
 
    const payload = await fn(ctx)

Header Constant	Header Name / Value Condition	Purpose
`NEXT_ROUTER_PREFETCH_HEADER`	`'1'`	Identifies standard client-side router prefetch requests
`NEXT_ROUTER_PREFETCH_HEADER`	`'2'`	Identifies runtime prefetch requests
`NEXT_ROUTER_PREFETCH_HEADER`	`'3'`	Identifies App Shell prefetch (omits link data and parameters)
`NEXT_HMR_REFRESH_HEADER`	`undefined` check	Detects HMR refresh events during development rendering
`RSC_HEADER`	Checked via `isRSCRequestHeader()`	Identifies React Server Component payload streams

Design Choice	Benefit	Cost
Separate `renderToHTMLImpl` and Flight stream handlers	Isolates Pages router Fizz/SSR rendering logic from App Router streaming architectures	Duplicates context preparation wiring across different routing paradigms
Strict header-based prefetch classification (`1`, `2`, `3`)	Prevents unnecessary data resolution during shell and runtime prefetches	Requires careful client/server header synchronization
Dynamic stale time tree-walking (`getDynamicStaleTime`)	Avoids full server component rendering when extracting static segment configs	Recursively inspects module definitions prior to handling requests

  public async handleRequest(
    req: NodeNextRequest,
    res: NodeNextResponse,
    parsedUrl?: NextUrlWithParsedQuery
  ): Promise<void> {
    const span = trace('handle-request', undefined, { url: req.url })
    const result = await span.traceAsyncFn(async () => {
      await this.ready?.promise
      addRequestMeta(req, 'PagesErrorDebug', this.renderOpts.ErrorDebug)
      return await super.handleRequest(req, res, parsedUrl)
    })
    const memoryUsage = process.memoryUsage()
    span
      .traceChild('memory-usage', {
        url: req.url,
        'memory.rss': String(memoryUsage.rss),
        'memory.heapUsed': String(memoryUsage.heapUsed),
        'memory.heapTotal': String(memoryUsage.heapTotal),
      })
      .stop()
    return result
  }

  protected async loadInstrumentationModule(): Promise<any> {
    let instrumentationModule: any
    if (
      this.actualInstrumentationHookFile &&
      (await this.ensurePage({
        page: this.actualInstrumentationHookFile!,
        clientOnly: false,
        definition: undefined,
      })
        .then(() => true)
        .catch(() => false))
    ) {
      try {
        instrumentationModule = await getInstrumentationModule(
          this.dir,
          this.nextConfig.distDir
        )
      } catch (err: any) {
        err.message = `An error occurred while loading instrumentation hook: ${err.message}`
        throw err
      }
    }
    return instrumentationModule
  }

Method Name	Return Type	Purpose
`handleRequest`	`Promise<void>`	Traces dev requests, verifies server readiness, and appends memory usage spans
`run`	`Promise<void>`	Strips basePath prefixes, dispatches execution to `super.run`, and catches unhandled render errors
`logErrorWithOriginalStack`	`void`	Delegates stack frame mapping to `this.bundlerService`
`loadInstrumentationModule`	`Promise<any>`	Ensures and loads the user instrumentation file from the distribution directory
`ensureEdgeFunction`	`Promise<void>`	Triggers on-demand compilation for Edge runtime worker targets

Server Request Lifecycle | blade47/next.js Wiki | doc0