---
title: "ADR-0011: Retain Vault streaming without falling back to the PHP stream handler"
manual: "HTTP Guard"
version: "main"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-http-guard:adr-0011@main"
source: "Adr/ADR-0011-VaultStreamingAndCancellation.rst"
rendered: "2026-10-18T14:31:38+00:00"
---

# ADR-0011: Retain Vault streaming without falling back to the PHP stream handler {#adr-0011}

-   *Status:* Historical proposal (original status: Proposed)
-   *Date:* 2026-10-08
-   *Original decision makers:*

    Project architecture/security owners; approval
    still pending in the original proposal.

-   *Requirements:* HG-028, HG-029, HG-030, HG-036, HG-037
-   *Original supersession:* None; a new decision for the proposed product.

> [!NOTE]
> This is the full English translation of the historical proposal dated
> 2026-10-08, originally Proposed. Its pending approval is historical and
> creates no additional alpha approval gate. Current
> [Security model and limits](https://docs.typo3.org/permalink/netresearch/nr-http-guard:security@main), [Development and tests](https://docs.typo3.org/permalink/netresearch/nr-http-guard:development@main), [Verification report](https://docs.typo3.org/permalink/netresearch/nr-http-guard:verification-report@main) and
> [Requirements and security invariants](https://docs.typo3.org/permalink/netresearch/nr-http-guard:development-requirements@main) describe the operative scope and evidence.
>
> The later single-package decision is recorded in [ADR-0015: One installable extension](https://docs.typo3.org/permalink/netresearch/nr-http-guard:adr-0015@main).
>
> The proposed Vault adapter below is historical context. Its foreign
> reference overlay is retained outside this extension; this ADR does not
> establish a current Vault integration or deployment.

## Context {#adr-0011-context}

Vault's ADR-039 describes streaming through a pinned curl-multi transfer whose
progress is driven while the response body is read. `stream=true`
would instead select the PHP stream handler and lose the pin. The
credential-bearing API deliberately encapsulates transport, promise and
secrets.

Sources: `[S05, S08]`.

## Decision {#adr-0011-decision}

In v1, global middleware supports ordinary buffered sends and explicitly
rejects Guzzle's `stream=true`. This does not exclude Vault's
separate streaming API. Its adapter uses the same policy/ConnectionPlan logic,
but receives an internally controlled transfer lease for ongoing progress and
cancellation.

A single owner is responsible for the tick loop, settlement and release.
Cancellation before start prevents the transfer; cancellation in flight closes
the active socket. Body close, errors and aborted consumption release
resources idempotently. Errors after partial responses are not presented as
complete EOF success.

Vault retains credential injection, prior secret permissions, audit, buffer
limits, idle/total time semantics and the distinction between proxy and origin
responses in its existing regressions. The new v1 proxy boundary is treated as
an explicit compatibility change rather than hidden. Its public API still
exports no raw security options.

## Rejected alternatives {#adr-0011-rejected-alternatives}

-   **Remove streaming entirely:** unnecessary product loss.
-   **Accept** `stream=true`: selects the wrong transport.
-   **Copy the streaming mechanism anew:** avoidable errors around EOF, buffer
    limits and cancellation.
-   **Expose a raw client:** expands the credential-bearing surface.

## Consequences {#adr-0011-consequences}

The demanding Vault feature is retained. Migration requires real
streaming/cancellation tests and is not complete merely by replacing a
factory. Long streams remain resource-bearing transfers that must be ended
explicitly.

## Evidence and acceptance in the original proposal {#adr-0011-verification-and-acceptance}

`T058, T059, T060, T061, T069, T070, T071, T072`. Details and
expected results are in [Original verification specification](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/specification/specs/06-verification.md). These tests
were specified, not executed as part of the original documentation delivery.

## Reasons to reconsider {#adr-0011-reassessment-trigger}

Global incremental streaming is a later feature. It must satisfy the same pin,
lifecycle and error obligations, rather than merely enabling a different
Guzzle switch.

## Related documents {#adr-0011-related-documents}

[Original ADR](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/specification/adr/ADR-0011-vault-streaming-und-cancellation.md), [Original product requirements](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/specification/specs/01-product-requirements.md), [Original security model](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/specification/specs/02-security-model.md),
[Original architecture](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/specification/specs/03-architecture.md) and [Original source catalogue](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/specification/specs/08-evidence-and-sources.md) (`S01-S23`),
plus the [ADR index](https://docs.typo3.org/permalink/netresearch/nr-http-guard:adr-index@main). [Original sources](https://docs.typo3.org/permalink/netresearch/nr-http-guard:adr-original-sources@main) explains
the immutable source index.