You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Request helpers (models/Request.bx, new models/Negotiator.bx):
the parts of Express's req that a ported handler reaches for first
and had to be hand-rolled from req.headers until now.
req.accepts() and req.acceptsLanguages() pick from the types or
languages you offer by the client's q weights, returning false
when none is acceptable. req.is() matches the request's own Content-Type, including wildcards, +json-style suffixes and the urlencoded/multipart shorthands. The rules follow the npm negotiator and type-is packages, minus media-type parameters
other than q. req.is() returns false, not null, for a request
with no body.
req.xhr, and req.subdomains with app.set( "subdomain offset", n ).
req.baseUrl (models/Router.bx): the mount path of the router or
path-scoped middleware handling the request. A mounted router had no
way to learn where it was mounted, so it couldn't build a link to
itself without the prefix hard-coded.
No req.fresh/req.stale yet — they only mean something once res.send()/res.json() set an ETag, which they don't.
Response helpers (models/Response.bx):
res.clearCookie(), plus domain and expires options on res.cookie() — without domain a cookie scoped to a parent domain
could be neither set nor cleared.
res.vary() adds to Vary instead of replacing it. boxExpressCors() now uses it, so its Vary: Origin no longer
overwrites a Vary set earlier in the chain. A hand-written fake res passed to the CORS middleware in a unit test needs a vary()
method.
res.format() dispatches on Accept, sets Content-Type and Vary: Accept, and answers 406 when nothing matches. Pass an
ordered struct ([ ... ]): a plain { ... } has no key order to
fall back on when the client has no preference.
res.get(), res.append(), res.location(), res.links(), res.attachment(), res.set( { ... } ) for several headers at once,
and an extension shorthand for res.type( "json" ). res.append()
joins values into one comma-separated line (a line each for Set-Cookie) so res.get() still returns the whole value.
Timeouts and size limits (models/BoxExpress.bx, models/HttpBridge.bx, new models/RequestWatchdog.bx; see docs/limits.md). Until now the only bounds on a
request were the body parsers' own limits and the accept backlog.
app.set( "requestTimeoutMs", n ) answers 503 when a handler
hasn't started its response in time; req.setTimeout( ms ) changes
or removes it for one request. Off by default. The handler's thread
is interrupted and sends the 503 itself — the watchdog never writes
to the response, because Undertow's exchange isn't safe to write from
a second thread while the handler may be using it. The trade-off is
that a handler which never blocks isn't stopped. Error-handling
middleware doesn't run for a timeout; a handler that catches the
interruption can check req.timedOut. A response that has already
started (SSE, a file download) is never cut off.
app.set( "maxBodySize", bytes ) answers 413 before any handler
runs, on Content-Length alone when there is one. Off by default, so
upgrading can't start rejecting uploads. This is enforced in
BoxExpress rather than with Undertow's MAX_ENTITY_SIZE, which was
tried first: it answered an oversized request with a 500, or
dropped the connection with no response for a chunked one, and
printed a stack trace either way. A chunked body is read into memory
up to the cap to measure it.
headerTimeoutMs defaults to 60 s. Before, a client that never
finished sending its headers was held open indefinitely (measured
against 0.2.26: still open after 75 s).
maxHeaderSize defaults to 64 KB, down from Undertow's 1 MB; a
request over it gets a 400. Raise it if you send unusually large
headers.
keepAliveTimeoutMs makes the idle keep-alive timeout configurable.
Its default, 60 s, is what Undertow already did.
Text and raw body parsers (models/middleware/BodyParsers.bx, new bifs/boxExpressText.bx, bifs/boxExpressRaw.bx; see docs/middleware.md):
boxExpressText() puts a text/plain body on req.body as a
string, decoded with the charset the request names (415 for one the
JVM can't decode). boxExpressRaw() puts an application/octet-stream body there as the exact bytes.
All four parsers take a type option — the same patterns as req.is(), an array, or a function — so boxExpressJSON( { type: [ "json", "+json" ] } ) parses application/vnd.api+json. With no type, json() and urlencoded() match exactly as before.
All four take a verify( req, res, bodyBytes ) option, called with
the bytes as received before they're parsed; throwing answers 403.
This is what a webhook signature check needs: the signature covers
the sender's exact bytes, which re-serializing parsed JSON doesn't
reproduce, and before this the only way to see them was to skip the
parser and read req.bodyStream() by hand.
A parser now skips a request an earlier parser, or boxExpressUpload(), already handled. The body stream can only be
read once, so a second parser was reading nothing — harmless while
no two parsers could match the same request, but a catch-all type: "*/*" would have replaced a parsed req.body with an empty
one.
Signed cookies (new models/CookieSigner.bx, models/Request.bx, models/Response.bx): app.set( "cookie secret", secret ), then res.cookie( name, value, { signed: true } ) and req.signedCookies.
A cookie that fails verification reads as false and, like every
signed cookie, is removed from req.cookies, so a forged value can't
be read as a plain one. An array of secrets signs with the first and
verifies with all, for rotation. The format is cookie-parser's, byte
for byte (checked against Node's own HMAC output), so an Express app
with the same secret reads these cookies and vice versa. No j: JSON
cookies. Setting a secret changes nothing for an app that doesn't sign:
only values starting s: are affected.
View layouts and partials (models/Response.bx; see docs/views.md): app.set( "view layout", name ) wraps
every res.render() in a layout view, which gets the rendered view as data.body. The view runs first, so it can set a title or anything
else on data for the layout to read. layout in the render data (or res.locals) picks another layout for one render, or false for none. partial( view, data ) renders another view inline, with the caller's
data plus its own. Until now every view had to include its own header
and footer. layout is now a reserved key in render data.
Access log (models/HttpBridge.bx, new models/AccessLog.bx; see docs/observability.md): app.set( "log", "access" ) or "json" logs each request when it's answered, with
status, duration and bytes sent; a function receives the entry instead.
The default (true) is unchanged — a line on arrival — which can't
say how a request went, and getting status and duration meant writing
logging middleware around res.getStatusCode(). The logged path
leaves out the query string. An invalid "log" value now throws at app.set(). The timeout log line no longer prints the query string
either.
Binary WebSocket sends (models/WebSocketConnection.bx): connection.sendBinary( bytes ), and connection.send() sends a
binary frame when handed a byte[]. A connection could receive binary
messages (onBinary()) but only ever answer in text.
Cron schedules (new models/CronExpression.bx, models/Scheduler.bx; see docs/scheduler.md): app.schedule( "0 2 * * *", callback ) runs a job at clock times.
Five fields or six with seconds, ranges, lists, steps, month and
weekday names, @daily-style shorthands, and options.timezone. An
interval can't say "every night at 2" — the first run lands wherever
the process happened to start. Cron parsing was left out of the first
scheduler on purpose as a separable feature; this is it. A cron job is
driven by a one-shot timer re-armed after each run, since the gap
between fire times isn't constant. A malformed expression, or one that
can never fire, throws at schedule().
Middleware for WebSocket upgrades (models/BoxExpress.bx, new models/adapters/WsUpgradeMiddleware.bx; see docs/websockets.md): app.ws( path, handler, { use: [ ... ] } ) runs ordinary middleware against the upgrade
request. The socket opens only if they all call next(); one that
responds refuses the upgrade. The handler receives the request as a
second argument and as connection.req. Authenticating a socket used
to mean re-reading the session cookie from connection.cookies and
looking the session up by hand. Opt-in per route rather than running
the app.use() chain, which would let an app's catch-all 404 handler
answer every upgrade.
Path patterns (models/Router.bx; see docs/routing.md): a param can carry a regex
constraint (/users/:id(\d+)), share a segment with literal text or
other params (/flights/:from-:to, /api/v:version, /files/:name(.+).json), and a trailing *name captures the rest of
the path. A route that needed a numeric id had to accept anything and
reject it in the handler. A segment that is only :name is parsed as
before, so /:user-id is still one param. A literal colon inside a
path segment (/time/12:30) is now read as the start of a param, and
a segment starting with * is a named wildcard. A wildcard or optional
param is still final-segment only.
Request validation (new models/middleware/Validate.bx, bifs/boxExpressValidate.bx; see docs/validation.md): boxExpressValidate( schema ) checks req.body, req.query and req.params before the
handler runs, converts values to the declared types, fills defaults,
and answers 400 listing every problem. req.valid holds only the
fields the schema names, so it can be passed to a model without a
client slipping extra fields in. Types cover strings, numbers,
booleans, email, URL, UUID, ISO dates, arrays and nested structs, with
a validate function for anything else. A schema with an unknown type
or rule name throws at registration.
One MIME table (new models/MimeTypes.bx): res.sendFile() and boxExpressStatic() each had their own, and they disagreed — sendFile() sent .avif, .ttf, .otf, .ogg, .map and .webmanifest as application/octet-stream, static files did the same
for .csv and .zip. Both now use the union, which also gains .md, .yaml/.yml, .wav and .text.