Skip to content

feat: First-class support for handler-level timeouts#6521

Merged
kibertoad merged 10 commits intomainfrom
feat/handler-timeout
Feb 25, 2026
Merged

feat: First-class support for handler-level timeouts#6521
kibertoad merged 10 commits intomainfrom
feat/handler-timeout

Conversation

@kibertoad
Copy link
Member

Adds a first-class handlerTimeout option, configurable per-server and per-route, backed by an AbortSignal exposed as request.signal. Unlike the existing socket-level timeouts (connectionTimeout, requestTimeout), this is an application-level timeout that works correctly with HTTP keep-alive and can be scoped to individual routes, and used together with flows that support AbortSignal (fetch, DBs etc).

Highlights

  • Zero overhead when disabled: default is 0 (no timeout). No AbortController, setTimeout, or event listeners are
    created, only a single branch check per request
  • Per-route override: works like bodyLimit — routes inherit the server default and can override with a different
    value;
  • Cooperative cancellation: timeout sends a 503 response and aborts request.signal, but does not kill the handler.
    Handlers use request.signal to propagate cancellation to downstream I/O;
  • Unified signal: request.signal aborts on either timeout or client disconnect. signal.reason distinguishes the two
    (FST_ERR_HANDLER_TIMEOUT vs generic AbortError);
  • Full resource cleanup: timer and close listener are cleaned up in every exit path — normal response, error,
    reply.hijack(), timeout, and client disconnect;
  • Customizable error response: the timeout error flows through the route's errorHandler, allowing per-route
    status/body customization;
  • Fail-fast on misconfiguration: accessing request.signal without handlerTimeout configured throws
    FST_ERR_MISSING_HANDLER_TIMEOUT.

Checklist

@kibertoad kibertoad requested a review from a team February 22, 2026 13:49
@github-actions github-actions bot added documentation Improvements or additions to documentation typescript TypeScript related labels Feb 22, 2026
@kibertoad kibertoad mentioned this pull request Feb 22, 2026
2 tasks
@kibertoad
Copy link
Member Author

@metcoder95 @mcollina @gurgunday Any thoughts on this one?

Copy link
Member

@mcollina mcollina left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good substantial feature, thanks!

Copy link
Member

@mcollina mcollina left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@kibertoad kibertoad merged commit f376f60 into main Feb 25, 2026
36 of 37 checks passed
@kibertoad kibertoad deleted the feat/handler-timeout branch February 25, 2026 22:55
Fdawgs added a commit that referenced this pull request Mar 1, 2026
Missed in #6521 

Signed-off-by: Frazer Smith <frazer.dev@icloud.com>
@Fdawgs Fdawgs mentioned this pull request Mar 1, 2026
2 tasks
Fdawgs added a commit that referenced this pull request Mar 1, 2026
* docs(reference/hooks): fix note stlye

Missed in #6521 

Signed-off-by: Frazer Smith <frazer.dev@icloud.com>

* Update docs/Reference/Hooks.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Frazer Smith <frazer.dev@icloud.com>

---------

Signed-off-by: Frazer Smith <frazer.dev@icloud.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation typescript TypeScript related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants