Request

Active contributors: dougwilson, wesleytodd, ulisesgascon

Purpose

lib/request.js defines the prototype that gets attached to incoming req objects. It does not subclass anything itself — it starts from Object.create(http.IncomingMessage.prototype) and adds Express-specific helpers and getters on top.

527 lines, mostly small methods with extensive JSDoc and examples.

Directory layout

lib/
└── request.js   # this file

Key abstractions

Methods

Method	Description
req.get(name) / req.header(name)	Header lookup with Referer/Referrer aliasing.
req.accepts(types)	Best content-type match from the Accept header. Backed by the accepts package.
req.acceptsEncodings(...)	Best Accept-Encoding match.
req.acceptsCharsets(...)	Best Accept-Charset match.
req.acceptsLanguages(...)	Best Accept-Language match.
req.range(size, options)	Parses the Range header; returns undefined, -1 (unsatisfiable), -2 (invalid), or an array of { start, end }. Backed by range-parser.
req.is(types)	Checks the request Content-Type against one or more types (e.g., req.is('json')). Backed by type-is.

Getters (defined via Object.defineProperty)

Getter	What it computes
req.query	Parsed query string, using the 'query parser fn' setting (compiled from 'simple', 'extended', false, or a function).
req.protocol	'http' or 'https'. Honours X-Forwarded-Proto if trust proxy says the socket is trusted.
req.secure	Shorthand for req.protocol === 'https'.
req.ip	Trusted client IP via proxy-addr using the 'trust proxy fn' setting.
req.ips	Array of trusted hop addresses (farthest-to-closest, with the socket address removed).
req.subdomains	Subdomain parts of req.hostname, slicing off the last subdomain offset segments.
req.path	parseurl(req).pathname.
req.host	Host header, or X-Forwarded-Host if trusted; preserves IPv6 brackets.
req.hostname	req.host minus any port (with IPv6 awareness).
req.fresh	true if the response is a cache hit per If-None-Match / If-Modified-Since. Only meaningful for GET/HEAD with 2xx or 304 status.
req.stale	!req.fresh.
req.xhr	true if X-Requested-With === 'XMLHttpRequest' (case-insensitive).

Internal helper

defineGetter(obj, name, fn) — a thin wrapper over Object.defineProperty that sets configurable: true, enumerable: true, and the getter function. Used for every getter listed above.

How it works

graph TD
    Incoming[Incoming HTTP request] --> Wrap[Express app handle]
    Wrap --> SetProto[Object.setPrototypeOf req, app.request]
    SetProto --> Inherits[req now inherits all helpers and getters]
    Inherits --> AccessQuery[user calls req.query]
    AccessQuery --> Lookup[query getter]
    Lookup --> AppGet[this.app.get query parser fn]
    AppGet --> Parse[parse req then queryparse string]

Most getters reach back into the application via this.app.get(...) to read the relevant setting at request time. This means changing a setting after app.listen() is honoured for new requests.

For trust-proxy-aware getters (protocol, ip, ips, host), the trust proxy fn is consulted first. The function takes (remoteAddress, hopIndex) and returns whether to trust the hop.

Integration points

• Imports: accepts, node:net (isIP), type-is, node:http, fresh, range-parser, parseurl, proxy-addr.
• Exposed via: lib/express.js re-exports this module as express.request and uses it as the prototype for each app's app.request.
• Reads from app.settings: query parser fn, trust proxy fn, subdomain offset.
• Used by: All middleware that touches the request — every example app, every test, every consumer.

Entry points for modification

• Adding a request helper → assign to req (the prototype). For methods, req.foo = function () { ... }. For getters, use the local defineGetter helper.
• Changing trust-proxy semantics → edit req.protocol / req.ip / req.host along with compileTrust in lib/utils.js.
• New Accept-* helper → mirror the existing req.acceptsCharsets style: instantiate accepts(this) and delegate.

Key source files

File	Purpose
lib/request.js	The req prototype
lib/utils.js	compileQueryParser, compileTrust consumed via settings

Related pages

• Application — owns the settings (query parser fn, trust proxy fn, ...) that this file reads.
• Response — the symmetric prototype.
• Reference / Configuration — settings table.