# ADR-014. The runtime owns its HTTP transport

**Status**: accepted, 8 September 2026. Still in force.

## Context

The Scaleway Python SDK is the collection's dependency, and the generator uses
its `Client` and `Profile` to hold credentials. What remained open was how a
generated module reaches an operation.

The first answer, recorded in the runtime architecture page as "Decision 1", was
`scaleway_core.api.API._request(method, path, ...)`. It kept the contract as the
only source: the generator guesses no SDK method name from an `operationId`, and
the IR already carries `http_method` and `path`. The price was named at the
time, and accepted: a dependency on a method whose name starts with an
underscore, held by a guard that checked its signature.

Two measurements closed that question.

**The SDK passes no timeout.** Read in its source: `API._request` calls
`requests.request()` without one. A connection that opens and never answers
holds a module forever, and `wait_timeout` does not help, because it bounds a
wait loop rather than a single call. No playbook should carry that risk, and no
guard on a signature would have caught it: the signature was correct, the
behaviour was not.

**An underscore is not a contract.** A minor release of the SDK may move
`_request` without promising anything to anyone. The guard on its signature
turned that into a red build instead of a broken playbook, which was the right
mitigation for a dependency that should not have existed.

The migration happened before 0.4.0 and the changelog described it. What did not
happen is the record: the architecture page kept describing the reversed
decision, and it is the page a contributor reads to understand why the runtime
has the shape it has (#131). Worse, the replacement carried the same defect one
floor down: to hand the paginator the `x-total-count` header, the runtime wrote
`requests.Response._content`, a private attribute of a third-party library, in
code written to stop depending on one (#132).

## Decision

**The runtime composes its own HTTP request, and owns every responsibility that
comes with it.** The SDK supplies the profile and the credentials; it does not
execute.

Each responsibility has one place in `plugins/module_utils/scaleway.py`:

| responsibility | where |
|---|---|
| authentication headers, user agent, content type | `ScalewayApi._send` |
| query parameter serialisation, a list becoming repeated pairs | `ScalewayApi._send` |
| timeout, per call, from the `api_timeout` option | `ScalewayApi._send` |
| TLS, and the `api_allow_insecure` escape for an emulator | `ScalewayApi._send` |
| error translation, without ever copying the response body | `_error_from_response` |
| reading the body, and carrying `x-total-count` into it | `ScalewayApi.request`, `_avec_total_count` |
| pagination, and the three conditions that stop it | `paginate` |

**No private attribute of a third-party library is read or written in what is
shipped.** The rule now has a control rather than a paragraph: `mise run
api:privee` reads `plugins/` and refuses an underscored attribute on anything
but `self`. It cannot infer types, so it refuses what it cannot justify; in
shipped code, an underscore on something that is not one's own asks to be
argued, and an argument gets written down.

Carrying `x-total-count` therefore merges into the **body that was read**, never
into the response object. The need was never to change the response: it was to
give its reader what the header knows.

## Consequences

**The collection now maintains an HTTP client.** Retries, connection pooling and
proxy handling are ours to decide rather than inherited. None of them is
implemented today, and that is a deliberate gap rather than an oversight: #91
carries the retry policy, per kind of operation, because retrying a `POST` that
triggers an action is not the same act as retrying a `GET`.

**The SDK stays a dependency, for a narrower purpose.** Its profile resolution,
its configuration file format and its credential validation are used as they
are. A future release that changed `Client` or `Profile` would still reach us;
what no longer reaches us is a change to how it sends requests.

**One dependency was traded for another.** `requests` is now used directly, and
it is what `ansible-core` and the SDK already pull in. It has a public API, and
the control above is what keeps us on it.

## What this record does not decide

Whether an operation should be retried, and under which conditions: #91.

ADR-003 decides what a managing module sends and why a `PUT` reads first; this
record decides how anything is sent at all.