Skip to content

Proposal: Rename Response Extension Points to reflect lifecycle semantics #2078

@LukeAVanDrie

Description

@LukeAVanDrie

What would you like to be added:

We should consider refactoring the naming of the response-phase extension points to better align with their actual runtime behavior and lifecycle semantics.

This discussion stems from PR #2064, where we solidified the behavior of ResponseComplete to ensure it executes symmetrically with PreRequest, regardless of whether the request finished successfully, failed with an error, or was disconnected by the client.

The current naming conventions (specifically ResponseComplete) imply a "happy path" or successful HTTP completion, which is misleading for plugin authors who rely on these hooks for resource cleanup or accounting.

We should discuss and select new names for the following hooks:

  • ResponseReceived (Triggered on headers?)
  • ResponseStreaming (Triggered on chunks)
  • ResponseComplete (Triggered on termination)

Potential naming directions for discussion:

  • ResponseComplete -> PostRequest, RequestTerminated, OnRequestFinish, or RequestFinalized.
  • ResponseReceived -> OnResponseHeaders or ResponseStarted.
  • ResponseStreaming -> OnResponseBodyChunk or StreamChunk.

See also: #1661 (comment) for more suggestions.

Why is this needed:

  1. Clarity & Correctness: The current names are ambiguous. ResponseComplete suggests a successful response generation, but the hook is actually a "finally" block for the request context, handling errors and disconnects as well.
  2. Developer Experience: Plugin authors need to intuitively understand when a hook fires. If a hook is named ResponseComplete, an author might incorrectly assume it won't fire on a client disconnect or internal server error.
  3. Symmetry: As we enforce symmetry with PreRequest for capacity management (e.g., the Concurrency Saturation Detector), the terminology should reflect that these are lifecycle boundaries, not just HTTP protocol events.

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs-triageIndicates an issue or PR lacks a `triage/foo` label and requires one.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions