docker-swarm 0.7.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4173c79f1bd808f22729c09eda7b4b70a494c4f080625fff33285a410f1224dc
-  data.tar.gz: a8d0aaa08dc6ed272e16ef3577d59f7571791d793a7a2192afb4b5be762c2578
+  metadata.gz: 8e27b0beec0476baca5222a41e38aa7b11998641c39cc15eeb16390343e8364b
+  data.tar.gz: 61faa29cc088ea4286fb864b0b2237bfd104059236e4b748168344148931ab9e
 SHA512:
-  metadata.gz: 88d788fdd06036b76b6c666f46acfc6880bbb74b8f80feb706a8cfe71aa6e7a62164717de75b5711dc34086218a3feaf5e90323461ab27f76685417d199a07cd
-  data.tar.gz: 44bd8aa057c5b1d9e9e160deed73f13e08d0c441ba4f63a2f0d4142a89c2dc5c3939f732c80adca3c298e7e61b3192506dcf30064c93c9caaf6fa01ee4d4efc9
+  metadata.gz: 01b0508429e58f4878e8aa5bba874e67d57e87bf691c31ebc144da22cbeb86d89dc438f268ab85374009949e28296546747be6e0b03b718ddaa4a2df6f1e521b
+  data.tar.gz: bc02c9d23be1bacc5a8f7bee2e105cf0fdc90a75fa96d4257c41467bff9b7369a031c6c21644ac3cfc84159910bd10657371b2b9407d4c9bb270cf081d52af23

data/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.9.0] — 2026-08-03
+
+### Nuevas funcionalidades
+- `Container` pasa a incluir `Concerns::Creatable`: la gema ya puede **crear** containers, no solo operar los existentes. El nombre viaja por **query string** (`POST /containers/create?name=`), que es donde el Engine lo espera — en el body lo descarta en silencio y responde `201`, dejando el container con nombre aleatorio. `Concerns::Creatable` gana `create_query_params` (default `[]`, override por modelo; `Container` declara `%w[name]`) y `query_params_for_docker`; `save` los manda en la URL y los excluye del payload. Implementa ADR-025 cláusula 1 — @gedera
+
+### Breaking changes
+- **`logs` devuelve texto demultiplexado.** Sin TTY el Engine enmarca cada fragmento con 8 bytes de cabecera (tipo de stream · relleno · tamaño big-endian); el nuevo `Middleware::LogStreamDemuxer` los saca, así que `Loggable#logs` entrega texto limpio en `Container`, `Service` y `Task`. **Cambia el valor de retorno** para cualquier consumidor que hoy reciba el body crudo. Un stream sin framing (TTY) pasa intacto. Implementa ADR-025 cláusula 3 — @gedera
+  - El dispatch **no** se decide solo por `Content-Type`: `application/vnd.docker.multiplexed-stream` existe desde la **API v1.42**, y antes un stream multiplexado viajaba igual como `application/vnd.docker.raw-stream`. Como la gema no fija `?version=`, un Engine que tope en v1.41 devuelve `raw-stream` **con** framing. Ante `raw-stream` el middleware valida la **forma del frame** y solo demultiplexa si la cadena cierra de punta a punta; ante cualquier inconsistencia devuelve el body intacto. Registrado en **ADR-027**, que corrige un dato de apoyo del §Alternativas de ADR-025 **sin** superseder su Decisión.
+
+### Seguridad
+- **`LogHelper.sanitize` redacta los secretos que viajan como `"CLAVE=VALOR"` en `Env`** (#24). Antes redactaba solo por **clave de hash**: un String caía al `else` y pasaba intacto, y el `Env` de un `ContainerSpec` es un **array de strings** `"CLAVE=VALOR"` donde el nombre del secreto vive *dentro* del elemento. Como `"Env"` tampoco matchea `SENSITIVE_KEYS`, el valor de todo secreto pasado por variable de entorno **se logueaba entero en `request_success` — camino feliz, nivel INFO** — en cada create/update de un service. Se agrega `redact_kv_string` y una rama `when String`: si la parte izquierda matchea `SENSITIVE_KEYS` se reemplaza el valor y **se conserva el nombre** (saber qué secreto apareció es diagnóstico útil; su valor no). El regex usa `[^=]+` a la izquierda para no partir en un `=` del valor (base64, URLs) y `/m` para valores multilínea. Afecta a **todas** las versiones anteriores — @Pslp
+  - **Hueco declarado, no cubierto por este fix:** `private_key` **no está** en `SENSITIVE_KEYS`, así que un PEM con ese nombre sigue saliendo en claro (hay un spec que lo fija como comportamiento conocido). Ampliar la lista va aparte: cambia la redacción para todos los consumidores.
+
+### Otros cambios
+- `spec.homepage` del gemspec pasa a `https://github.com/sequre/docker-swarm` (#27): el repo se transfirió de la cuenta personal `gedera` a la org `sequre`. De ahí derivan los cuatro metadata URIs (`source_code_uri`, `changelog_uri`, `bug_tracker_uri`, `documentation_uri`), así que desde esta versión apuntan a la ubicación nueva. Las versiones ya publicadas conservan la URL anterior — las salva el redirect de GitHub — @gedera
+
+## [0.8.0] — 2026-07-22
+
+### Nuevas funcionalidades
+- `Service.create`/`Service#update`: soporte de autenticación de registry privado — `registry_auth` viaja en el header `X-Registry-Auth` y `registry_auth_from` (`spec`|`previous-spec`) en la query `registryAuthFrom` del update; mutuamente excluyentes y validados antes del request. La credencial nunca toca el payload ni el estado del modelo (helper `RegistryAuth`) — @Pslp
+- `Image.pull`: pull explícito síncrono (consume el stream NDJSON hasta EOF, eleva error tipado ante `error`/`errorDetail`, devuelve `{status: :pulled, image_ref:, digest?}` sin `find`; el digest sale del frame `Digest: sha256:…`, verificado contra Docker 29.5.3). **Capacidad sin consumidor activo hoy**: el deploy de imágenes privadas se autentica vía `Service.create` (X-Registry-Auth distribuido a los nodos por Swarm), no por pull explícito. `Image.pull` queda disponible para un futuro requerimiento (pre-pull / warm-cache) — @Pslp
+
+### Breaking changes
+- `Image` deja de incluir `Creatable`: se retira `Image.create` (roto y sin consumidores) en favor de `Image.pull`. `Image` conserva `Deletable` y el listado — @Pslp
+
+### Seguridad
+- `LogHelper` sanitiza recursivamente los headers de autenticación (`X-Registry-Auth`, `Authorization`) para no filtrar credenciales en logs de wire-debug — @Pslp
+
 ## [0.7.2] — 2026-06-29
 
 ### Documentación

data/README.md

@@ -42,15 +42,22 @@ Documentación normada (RFC-001) por capa:
 | Capa | Artefacto | Estado |
 |---|---|---|
 | Datos | — | `n/a` (gema sin DB) |
-| Glosario | [`docs/glossary/glossary.md`](docs/glossary/glossary.md) | F1 completo |
-| Comportamiento | [`docs/behavior/behavior.md`](docs/behavior/behavior.md) | F1 backfill on-demand (8 flujos) |
-| Configuración | [`docs/config/configuracion.md`](docs/config/configuracion.md) | F6 inventario base (7 opciones, sin env vars) |
-| API (operaciones) | — | F2 pendiente; contrato resumido inline en `skill/SKILL.md` |
-| Interfaz | — | F2 pendiente; contrato resumido inline en `skill/SKILL.md` |
-| Topología | — | F2 pendiente |
+| Glosario | [`docs/glossary/glossary.md`](docs/glossary/glossary.md) | completo (primitivas + arquitectura interna) |
+| Comportamiento | [`docs/behavior/behavior.md`](docs/behavior/behavior.md) | backfill on-demand + incremental (11 flujos) |
+| Configuración | [`docs/config/configuracion.md`](docs/config/configuracion.md) | inventario base (7 opciones, sin env vars) |
+| Interfaz | [`docs/interface/interface.md`](docs/interface/interface.md) | API Ruby pública (11 modelos + Base + concerns) |
+| Topología | [`docs/topology/topology.md`](docs/topology/topology.md) | 3 deps runtime + grafo de contexto |
+| Errores | [`docs/errors/errors.md`](docs/errors/errors.md) | jerarquía + mapeo HTTP + política §c |
+| Consumidas | [`docs/consumed/docker-engine-api.md`](docs/consumed/docker-engine-api.md) | Docker Engine API + retry/degradación §c/§e |
+| Test | [`docs/test/testing.md`](docs/test/testing.md) | suite RSpec unit+integration + gaps/contract/PII §e-h (§g sin incidentes) |
+| Release | [`docs/release/release.md`](docs/release/release.md) | completo — §a estructura (tag `v*`→RubyGems, patrón 1) + §b enrich (deploy/rollback/ambientes/dueño) |
+| API (operaciones) | — | `n/a` (gema sin superficie HTTP/CLI/eventos; superficie pública = Interfaz) |
 | Eventos | — | `n/a` (la gema no emite eventos) |
+| Seguridad | — | `n/a` (sin authn/authz propios; frontera auth-hacia-Docker en `docs/consumed/docker-engine-api.md` §a) |
+| Multi-tenancy | — | `n/a` (gema stateless sin DB ni scope de tenant) |
+| Data-lifecycle | — | `n/a` (sin persistencia/PII/retención; fixtures sintéticas) |
 
-`n/a` = no aplica al tipo de repo. F2 pendiente = capa declarada en la RFC pero todavía no implementada en `arch-structure`; el contenido relevante vive transitoriamente en `skill/SKILL.md` (RFC-008 §2 coexistencia transitoria).
+`n/a` = no aplica al tipo de repo.
 
 ## Desarrollo
 

data/docs/behavior/behavior.md

@@ -1,6 +1,6 @@
 # Comportamiento — docker-swarm
 
-> meta: artefacto · RFC-007 · generado dev-enrich · anclado a `a4e3129` · cobertura: backfill on-demand inicial (8 flujos load-bearing)
+> meta: artefacto · RFC-007 · generado dev-enrich · anclado a `v0.9.0` · cobertura: 11 flujos load-bearing (8 backfill inicial + 3 nuevos: auth de registry privado, `Image.pull` síncrono, `Container.create`)
 
 ## 1. Resumen
 
@@ -8,7 +8,7 @@ Flujos de ejecución load-bearing de `docker-swarm`: cómo se materializan en ru
 
 ## 2. Cobertura declarada
 
-### Documentados (8)
+### Documentados (11)
 
 1. `Service.create` + reload
 2. `Service.update` con `Version.Index`
@@ -18,13 +18,14 @@ Flujos de ejecución load-bearing de `docker-swarm`: cómo se materializan en ru
 6. Error mapping (HTTP status → excepción tipada)
 7. `Container.start` / `Container.stop`
 8. `Loggable#logs` streaming
+9. Auth de registry privado (`RegistryAuth.resolve` → `X-Registry-Auth` / `registryAuthFrom`)
+10. `Image.pull` síncrono (stream NDJSON → error tipado → resultado explícito)
+11. `Container.create` con nombre por query string (`create_query_params`)
 
 ### No documentados (ausencia ≠ inexistencia, RFC-007)
 
 - Reconexión / reapertura de socket Unix (Excon nativo, fuera de nuestra superficie).
 - Flujo de configuración / boot (`DockerSwarm.configure`) — trivial, sin secuencia de interés.
-- Pull de imágenes con autenticación de registry (`X-Registry-Auth`) — **no implementado** en la gema (gap conocido).
-- `Container.create` — **no implementado** en F1 (intencional, ver glossary).
 
 ## 3. Flujos
 
@@ -211,33 +212,127 @@ Mismo patrón para `stop`. POST sin body → no se reintenta automáticamente (
 
 ### 3.8 `Loggable#logs` streaming
 
-Obtención de logs raw para Service/Task/Container.
+Obtención de logs para Service/Task/Container, ya demultiplexados.
 
 ```mermaid
 sequenceDiagram
     actor Caller
     participant Model as Service/Task/Container
     participant Api
+    participant Demux as LogStreamDemuxer
     participant Docker
 
     Caller->>Model: model.logs(stdout: 1, stderr: 1, follow: 0)
     Model->>Api: request(:logs, id:, query: { stdout:, stderr:, follow: })
     Api->>Docker: GET /services/abc/logs?stdout=1&stderr=1
-    Docker-->>Api: 200 raw stream (text/plain)
-    Api-->>Model: raw body
+    Docker-->>Demux: 200 stream + Content-Type
+    alt cadena de frames cierra de punta a punta
+        Demux->>Demux: saca 8 bytes de cabecera por frame, concatena en orden
+    else body sin framing (TTY) o inconsistente
+        Demux->>Demux: deja el body intacto
+    end
+    Demux-->>Api: texto limpio
+    Api-->>Model: body
     Model-->>Caller: String
 ```
 
 **Notas load-bearing:**
-- El body se devuelve sin parseo (no es JSON; `ResponseJSONParser` lo respeta porque Content-Type no es `application/json`).
-- `follow: 1` mantiene la conexión abierta — el caller debe manejar el stream/timeout.
+- El body no se parsea como JSON (`ResponseJSONParser` lo respeta porque el Content-Type no es `application/json`).
+- **El demux vive en un middleware, no en `Loggable`:** `Connection#request` devuelve `response.body` y descarta los headers, así que aguas abajo ya no hay `Content-Type` con el que decidir (ADR-025 cláusula 3).
+- **`raw-stream` no implica TTY.** Ese `Content-Type` era el único que existía antes de la API v1.42, y la gema no fija `?version=` → un Engine 20.10 devuelve `raw-stream` con framing. El middleware decide por la forma del frame, no por el header (detalle y cita del changelog en [`docs/consumed/docker-engine-api.md`](../consumed/docker-engine-api.md) §b).
+- **Desviación de ADR-025, acotada.** La **Decisión** normativa (`ADR-025:130-131` — *"un middleware que decide por `Content-Type`"*) **se cumple**: el middleware corta si el header falta o no es uno de los dos. Lo que la implementación contradice es el **rationale de §Alternativas** (`ADR-025:106-107`), que da por sentado que `raw-stream` implica TTY. Ese dato de apoyo es falso para Engines que topan en la API v1.41. Asentar la corrección en el reino queda **pendiente**.
+- **El demux limpia los frames, no separa señal de ruido.** `stdout` y `stderr` siguen intercalados en un solo String: quien necesite un dato puntual tiene que delimitarlo en origen.
+- **Un frame partido entre chunks no se reensambla:** el demux es todo-o-nada, así que devuelve el body **intacto** en vez de texto a medias. El comportamiento está definido y cubierto por spec — los cuatro casos que pide `ADR-025:196-198` (cadena de frames, varios en un chunk, tamaño/cola truncados, TTY sin framing) están en `spec/docker/swarm/middleware/log_stream_demuxer_spec.rb`.
+- `follow: 1` mantiene la conexión abierta — el caller debe manejar el stream/timeout. `[inferred]` Con `follow` el body no llega completo, así que el demux no aplica por diseño; no está ejercitado por spec ni contemplado en ADR-025 — es extrapolación de esta capa, no una limitación declarada por la ADR.
+
+### 3.9 Auth de registry privado (`X-Registry-Auth` / `registryAuthFrom`)
+
+El caller pasa una credencial **opaca base64url** (`registry_auth`) y/o la fuente a reusar (`registry_auth_from`). `RegistryAuth.resolve` valida **antes** de la request (exclusión mutua + enum del `from`) y traduce a canales de transporte, sin tocar el payload ni el estado del modelo. La credencial se sanitiza en logs vía `LogHelper`. Aplica a `Service.create`/`#update` e `Image.pull`.
+
+```mermaid
+flowchart TD
+    Start[Caller pasa registry_auth y/o registry_auth_from] --> Resolve[RegistryAuth.resolve valida y traduce]
+    Resolve --> Both{ambos presentes?}
+    Both -->|si| Err1[ArgumentError mutuamente excluyentes]
+    Both -->|no| Enum{registry_auth_from en spec o previous-spec?}
+    Enum -->|invalido| Err2[ArgumentError valor invalido]
+    Enum -->|valido o ausente| Split[arma headers y query_params]
+    Split --> Header[registry_auth va al header X-Registry-Auth]
+    Split --> Query[registry_auth_from va a la query registryAuthFrom]
+    Header --> Req[Api.request en create update o pull]
+    Query --> Req
+```
+
+**Notas load-bearing:**
+- La validación es **fail-fast local**: un caller que pasa ambos, o un `from` fuera de `spec`/`previous-spec`, corta con `ArgumentError` antes de tocar el Engine (no se deriva la ambigüedad a Docker).
+- La credencial viaja **solo** por header/query — nunca en el payload ni en el estado del modelo. `LogHelper::SENSITIVE_KEYS` la enmascara en el wire-debug.
+
+### 3.10 `Image.pull` síncrono (stream NDJSON → error tipado → resultado)
+
+`Image.pull` es síncrono: consume el stream de progreso NDJSON hasta EOF, eleva error tipado ante un frame `error`/`errorDetail` (que Docker manda **con HTTP 200**), y solo tras terminación limpia devuelve un resultado explícito construido desde el stream — sin un `find` posterior.
+
+```mermaid
+sequenceDiagram
+    actor Caller
+    participant Image as DockerSwarm::Image
+    participant RegAuth as RegistryAuth
+    participant Api as DockerSwarm::Api
+    participant Docker as Docker Engine
+
+    Caller->>Image: pull(image_reference, registry_auth)
+    Image->>RegAuth: resolve(registry_auth)
+    RegAuth-->>Image: headers con X-Registry-Auth
+    Image->>Api: request pull con fromImage y headers
+    Api->>Docker: POST /images/create?fromImage=ref
+    Docker-->>Image: stream NDJSON de progreso
+    Image->>Image: parse_progress_stream + raise_on_stream_error!
+    alt frame error o errorDetail
+        Image-->>Caller: raise Error tipado
+    else terminacion limpia
+        Image->>Image: extract_digest desde frame Digest
+        Image-->>Caller: status pulled + image_ref + digest
+    end
+```
+
+**Notas load-bearing:**
+- El middleware entrega el stream como `String` (multi-frame NDJSON) o `Hash` (frame único); `parse_progress_stream` normaliza ambos a lista de frames.
+- El digest sale del frame `Digest: sha256:...` (el stream de pull **no** trae campo `aux` — verificado contra Docker 29.5.3), escaneando desde el final.
+- Es un `POST` → **no** entra en la política de retries (ver flujo 3.5).
+
+### 3.11 `Container.create` con nombre por query string
+
+El Engine toma el nombre del container por query string. En el body lo **descarta en silencio** y responde `201` igual: el container nace con nombre aleatorio, y una lógica de adopción por nombre determinista no lo encuentra → el reintento duplica en vez de adoptar (ADR-025 cláusula 1).
+
+```mermaid
+sequenceDiagram
+    actor Caller
+    participant Container as DockerSwarm::Container
+    participant Api
+    participant Docker
+
+    Caller->>Container: Container.create(name: "acs-seed-helper", Image:, Cmd:)
+    Container->>Container: valid?
+    Container->>Container: query_params_for_docker → { name: "acs-seed-helper" }
+    Container->>Container: payload_for_docker.except("name")
+    Container->>Api: request(:create, query_params:, payload:)
+    Api->>Docker: POST /containers/create?name=acs-seed-helper
+    Docker-->>Api: 201 { Id: "abc" }
+    Api-->>Container: { Id: "abc" }
+    Container->>Container: self.ID = "abc" → reload
+    Container-->>Caller: instancia hidratada
+```
+
+**Notas load-bearing:**
+- El split lo declara el modelo con `.create_query_params` (`%w[name]` en `Container`); el default del concern es `[]`, así que los demás modelos Creatable no cambian de comportamiento.
+- **El atributo se excluye del payload**, no se duplica: mandarlo en los dos lados no da error pero deja el body con una clave que Docker ignora.
+- Hereda el flujo §3.1: `valid?` antes del POST, `reload` después, y **sin retry** por ser `POST` (§3.5). Si el `create` falla por `Communication`, el caller decide — con nombre determinista puede adoptar el existente en el reintento.
 
 ## 4. Cobertura y fronteras
 
-- **Cobertura inicial (RFC-007 backfill on-demand):** 8 flujos load-bearing documentados. Esta gema es chica; el backfill completo es factible y se hace ahora.
+- **Cobertura (RFC-007 backfill on-demand + incremental):** 8 flujos load-bearing en el backfill inicial + 2 agregados con el soporte de auth de registry privado (auth de registry privado, `Image.pull` síncrono) + 1 con el `create` de containers = 11. Esta gema es chica; el backfill completo era factible y se hizo, y a partir de ahí se acreta por PR.
 - **Frontera con glosario:** términos (Service, Spec, Version.Index, etc.) viven en [`docs/glossary/glossary.md`](../glossary/glossary.md). Esta capa documenta secuencias, no significado.
 - **Frontera con configuración:** `DockerSwarm.configure` es boot, no flujo de negocio. No se diagrama.
 - **No localizable / fuera de alcance:**
   - Lógica interna de Excon (retry timing, socket pool) — vive en Excon, no se inventa diagrama.
-  - Flujo de auth registry para `Image.create` — la gema **no implementa** `X-Registry-Auth` (gap, no flujo a documentar).
+  - Nada pendiente por este motivo. (Hasta el 2026-08-03 esta línea decía que la gema no implementaba `X-Registry-Auth` y citaba `Image.create`; las dos cosas quedaron obsoletas — la auth de registry está documentada en §3.9 e `Image.create` fue retirado.)
 - **Cadencia incremental a partir de acá:** sólo se diagrama un flujo cuando un PR lo toca o agrega. No barrido retroactivo de legacy.

data/docs/consumed/docker-engine-api.md

@@ -0,0 +1,126 @@
+# Dependencias consumidas — docker-swarm
+
+> meta: artefacto · RFC-018 · generado arch-structure + enriquecido arch-enrich · anclado a `v0.9.0` · cobertura: superficie del Docker Engine API consumida por la gema (`api.rb` ENDPOINTS + `connection.rb`); §c/§e enriquecidas 1/1
+
+## 1. Resumen
+
+La gema consume **una** dependencia externa: el **Docker Engine API** (HTTP REST sobre Unix socket o TCP). Es el único servicio que invoca; toda la gema es un cliente tipado de esa API. Cliente propio = `DockerSwarm::Connection` (Excon) + `DockerSwarm::Api` (mapa de endpoints).
+
+## 2. Cuerpo
+
+### Docker Engine API
+
+#### a. Identidad
+
+| campo | valor |
+|---|---|
+| proveedor / servicio | Docker Engine API (daemon `dockerd`) |
+| sub-tipo | **externo** (no es repo del fleet) |
+| transporte | HTTP/REST sobre Unix socket (`unix:///var/run/docker.sock`, default) o TCP (`http://host:2375`) |
+| cliente nuestro | `DockerSwarm::Connection` (Excon) + `DockerSwarm::Api` (`api.rb`) |
+| auth | ninguna por default (socket local). TCP/TLS → fuera de alcance del cliente (no inyecta credenciales; 401 si el daemon las exige) |
+| versión de API | v1.41 (referencia en los `@see` de los modelos; no se negocia explícitamente). **La gema no fija `?version=`** → el daemon sirve su versión **máxima**, así que la versión efectiva la decide cada host. Piso relevante: un Engine 20.10 topa en **v1.41**. Techo del parque: `unknown` (no derivable de este repo). Consecuencia en los logs: ver §b |
+| ancla | doc oficial: <https://docs.docker.com/engine/api/v1.41/> |
+
+#### b. Operaciones consumidas
+
+Subset que la gema invoca, derivado de `Api::ENDPOINTS` (`api.rb:5-72`). `destino` = `método HTTP + path` (los `%<id>s` se interpolan en runtime).
+
+| recurso | operación | destino | qué mandamos / esperamos |
+|---|---|---|---|
+| swarm | show | `GET swarm` | — / info del cluster (Hash) |
+| system | info | `GET info` | — / Hash |
+| system | version | `GET version` | — / Hash |
+| system | up | `GET _ping` | — / `"OK"` |
+| system | df | `GET system/df` | — / Hash de uso de disco |
+| nodes | index | `GET nodes` | `?filters=` opcional / array |
+| nodes | show | `GET nodes/%<id>s` | — / Hash |
+| nodes | update | `POST nodes/%<id>s/update` | `?version=` + payload / — |
+| nodes | destroy | `DELETE nodes/%<id>s` | — / — |
+| tasks | index / show | `GET tasks`, `GET tasks/%<id>s` | `?filters=` / array \| Hash |
+| tasks | logs | `GET tasks/%<id>s/logs` | `?stdout/stderr/...` / stream multiplexado (demux en el cliente) |
+| services | index / show | `GET services`, `GET services/%<id>s` | `?filters=` / array \| Hash |
+| services | create | `POST services/create` | payload (Spec aplanado) + header `X-Registry-Auth` (opcional, registry privado) / `{ID}` |
+| services | update | `POST services/%<id>s/update` | `?version=` (+ `?registryAuthFrom=` opcional: `spec`\|`previous-spec`) + payload + header `X-Registry-Auth` (opcional; excluyente con `registryAuthFrom`) / — |
+| services | destroy | `DELETE services/%<id>s` | — / — |
+| services | logs | `GET services/%<id>s/logs` | `?stdout/stderr/...` / stream multiplexado (demux en el cliente) |
+| configs | index / show / create / destroy | `GET configs`, `GET configs/%<id>s`, `POST configs/create`, `DELETE configs/%<id>s` | payload en create / `{ID}` |
+| secrets | index / show / create / destroy | `GET secrets`, `GET secrets/%<id>s`, `POST secrets/create`, `DELETE secrets/%<id>s` | payload en create (`Data` filtrado en logs) / `{ID}` |
+| networks | index / show / create / update / destroy | `GET/POST networks...`, `POST networks/%<id>s/update`, `DELETE networks/%<id>s` | payload / `{ID}` |
+| volumes | index / show / create / destroy | `GET volumes`, `GET volumes/%<id>s`, `POST volumes/create`, `DELETE volumes/%<id>s` | payload / respuesta wrapped en `Volumes` |
+| containers | index | `GET containers/json` | `?filters=` / array |
+| containers | show | `GET containers/%<id>s/json` | — / Hash |
+| containers | create | `POST containers/create` | `?name=` (query, NO en el body) + payload / `{Id}` |
+| containers | start / stop | `POST containers/%<id>s/start`, `POST containers/%<id>s/stop` | — / — |
+| containers | destroy | `DELETE containers/%<id>s` | — / — |
+| containers | logs | `GET containers/%<id>s/logs` | `?stdout/stderr/...` / stream multiplexado (demux en el cliente) |
+| images | index | `GET images/json` | — / array |
+| images | show | `GET images/%<id>s/json` | — / Hash |
+| images | pull | `POST images/create?fromImage=<ref>` | header `X-Registry-Auth` (opcional, registry privado) / stream NDJSON de progreso |
+| images | destroy | `DELETE images/%<id>s` | — / — |
+
+Serialización: request body no-String → JSON (`Content-Type: application/json`) vía `Middleware::RequestEncoder`; response `application/json` → `HashWithIndifferentAccess` recursivo vía `Middleware::ResponseJSONParser`.
+
+**Streams de logs (`containers`/`services`/`tasks` → `logs`).** Sin TTY el Engine multiplexa: 8 bytes de cabecera por frame (1 tipo de stream · 3 de relleno en cero · 4 de tamaño big-endian). `Middleware::LogStreamDemuxer` los saca, así que `Loggable#logs` entrega texto limpio.
+
+El `Content-Type` **no alcanza** para decidir. `application/vnd.docker.multiplexed-stream` existe **desde la API v1.42**; su entrada de changelog dice, textual:
+
+> `GET /containers/{id}/attach`, `GET /exec/{id}/start`, `GET /containers/{id}/logs` `GET /services/{id}/logs` and `GET /tasks/{id}/logs` now set Content-Type header to `application/vnd.docker.multiplexed-stream` when a multiplexed stdout/stderr stream is sent to client, `application/vnd.docker.raw-stream` otherwise.
+
+Antes de v1.42 ese valor no existía y un stream multiplexado viajaba igual como `application/vnd.docker.raw-stream`. Como la gema no fija `?version=`, un Engine 20.10 (tope v1.41) devuelve `raw-stream` **con** framing. Por eso el middleware, ante `raw-stream`, decide por la **forma del frame** —recorre el body entero y solo demultiplexa si la cadena de frames cierra de punta a punta— en vez de confiar en el header. Ante cualquier inconsistencia deja el body intacto.
+
+> Anclaje: <https://docs.docker.com/reference/api/engine/version-history/> (entrada de v1.42).
+
+#### d. Errores del proveedor → excepción nuestra
+
+El daemon responde con status HTTP; `Middleware::ErrorHandler` los mapea a la jerarquía `DockerSwarm::Error`. La tabla completa status→excepción está en [`docs/errors/errors.md`](../errors/errors.md) §b (este artefacto **referencia**, no la redefine).
+
+| condición del proveedor | excepción nuestra |
+|---|---|
+| status 4xx/5xx mapeado | la `DockerSwarm::Error::*` correspondiente (ver `docs/errors` §b) |
+| status no-2xx no mapeado | `DockerSwarm::Error` (`HTTP <status>`) |
+| socket caído / timeout de conexión (`Excon::Error::Socket`) | `DockerSwarm::Error::Communication` (preserva `cause`) |
+
+#### c. Retry / idempotencia (semántica)
+
+**Estructural** (anclado a `connection.rb:24-33`):
+
+| aspecto | valor |
+|---|---|
+| métodos con retry | `get/head/put/delete/options` (`Connection::IDEMPOTENT_METHODS`) |
+| reintentos | `max_retries` (default 3), solo en métodos idempotentes; POST/PATCH = 0 |
+| errores reintentados | `Excon::Error::Socket`, `Excon::Error::Timeout` |
+| backoff | ninguno — reintento inmediato (no se setea `retry_interval`) |
+
+**Semántica:** la frontera idempotente/no-idempotente refleja la del Docker Engine API:
+
+- `GET`/`DELETE`/`PUT` son seguros de reintentar: re-listar, re-borrar (404 → `nil` graceful) o re-actualizar produce el mismo estado final → la gema los reintenta automáticamente ante caída de socket.
+- `POST create` (services/networks/volumes/configs/secrets/containers) **no** se reintenta: un replay tras fallo parcial podría crear un recurso duplicado (el daemon no deduplica por nombre en todos los recursos). El caller decide qué hacer si un `create` falla por `Communication`.
+- `POST update`/`start`/`stop`/`restart` tampoco se reintentan (son POST); `update` además acarrea `?version=` → un replay con versión vieja daría 409 `Conflict`, no un duplicado.
+- **Sin backoff** es aceptable acá: el socket Unix local rara vez está transitoriamente saturado; ante un daemon caído, 3 reintentos inmediatos fallan rápido y se propaga `Communication`.
+
+#### e. Degradación (si la dependencia cae)
+
+| escenario | comportamiento de la gema |
+|---|---|
+| socket caído / daemon no responde | tras `max_retries` (idempotentes) o inmediato (POST), levanta `DockerSwarm::Error::Communication` con el `Excon::Error::Socket` en `cause` |
+| daemon devuelve 5xx | levanta la `Error::*` correspondiente (502/503/504) sin reintento HTTP |
+| fallback / cola / circuit-breaker | **ninguno** — la gema es un cliente fino, fail-fast; no encola ni degrada |
+| responsabilidad del consumidor | decidir reintento con backoff, fallback o propagación; la gema solo provee el error tipado |
+
+- **SLA del proveedor:** n/a — el daemon Docker suele ser local (socket Unix) o de infraestructura propia; no hay SLA externo que documentar.
+- **Sin estado degradado:** la gema no cachea ni mantiene estado entre llamadas; si el daemon cae, cada operación falla independientemente. No hay "modo degradado" que activar/desactivar.
+
+## 3. Inferencias
+
+| afirmación | confidence | a verificar |
+|---|---|---|
+| Versión de API = v1.41 | inferred | tomada de los `@see` de los modelos; la gema no fija `?version=` en la URL base ni negocia versión |
+| `qué mandamos/esperamos` por operación | inferred | derivado del flujo de los concerns (`payload_for_docker`, `reload` tras create); el shape exacto del Spec lo fija Docker |
+
+## 4. Cobertura y fronteras
+
+- **Regla de dependencia directa:** solo se documenta lo que la gema invoca directo contra el daemon. Lo que Docker orqueste por debajo (scheduling de tasks en nodos, overlay networks) es concern del daemon, no de la gema.
+- **Subset, no la API completa:** `Api::ENDPOINTS` cubre el subset que la gema expone; el Docker Engine API tiene endpoints (build, exec, plugins, `POST /auth`) que la gema **no** consume → fuera de alcance. Nota: la gema **sí** manda el header `X-Registry-Auth` (credencial opaca por-request); eso es distinto del endpoint `POST /auth` (login contra un registry), que sigue sin consumirse.
+- **Auth de registry privado:** soportado como credencial opaca por-request — `Service.create`/`#update` (header `X-Registry-Auth`; `#update` además `registryAuthFrom` para reusar la del spec) e `Image.pull` (header `X-Registry-Auth`). La gema no mintea ni valida la credencial: la recibe base64url del caller y la pasa tal cual (`RegistryAuth` traduce a header/query). TLS/TCP para alcanzar el daemon sigue fuera de alcance (ver abajo).
+- **TLS/TCP:** el cliente no gestiona certificados; un endpoint TCP con TLS mutuo queda fuera de alcance (resultará en `Unauthorized`/`Communication`).

data/docs/errors/errors.md

@@ -0,0 +1,103 @@
+# Errores — docker-swarm
+
+> meta: artefacto · RFC-020 · generado arch-structure + enriquecido arch-enrich · anclado a `8f2e1f7` · cobertura: excepciones públicas que la gema emite (`lib/docker_swarm/errors.rb` + `middleware/error_handler.rb` + `Image#raise_on_stream_error!`); política §c 16/16 enriquecida
+
+## 1. Resumen
+
+La gema traduce los status HTTP no-2xx del Docker Engine API a una jerarquía de excepciones Ruby tipadas, todas bajo `DockerSwarm::Error < StandardError`. El mapeo status→excepción vive en `Middleware::ErrorHandler`; los fallos de socket se envuelven en `Communication`. No hay payload propio (no es un servicio HTTP): el "shape" es la excepción Ruby + su `message`.
+
+## 2. Cuerpo
+
+### a. Inventario de excepciones públicas
+
+Todas heredan de `DockerSwarm::Error` (que hereda de `StandardError`). Tres formas de acceso equivalentes: `DockerSwarm::NotFound`, `DockerSwarm::Error::NotFound`, `DockerSwarm::Errors::NotFound` (alias + `Errors.const_missing`).
+
+| excepción | jerarquía base | qué la levanta |
+|---|---|---|
+| `Error` | `StandardError` | base de todas; el fallback `HTTP <status>` para status no mapeado; **y** el fallo de `Image.pull` cuando el stream de progreso reporta un frame `error`/`errorDetail` (Docker lo emite con **HTTP 200** → no lo agarra `ErrorHandler`; lo eleva `Image#raise_on_stream_error!`, `models/image.rb`) |
+| `Error::BadRequest` | `Error` | status 400 (payload malformado) |
+| `Error::Unauthorized` | `Error` | status 401 (TLS sin credenciales) |
+| `Error::Forbidden` | `Error` | status 403 (permisos insuficientes, ej. swarm op en worker) |
+| `Error::NotFound` | `Error` | status 404; capturada por `find`/`destroy` → `nil` |
+| `Error::NotAcceptable` | `Error` | status 406 |
+| `Error::RequestTimeout` | `Error` | status 408 |
+| `Error::Conflict` | `Error` | status 409 (nombre duplicado o `Version.Index` stale) |
+| `Error::UnprocessableEntity` | `Error` | status 422 (raised con el `body` crudo, no el `message`) |
+| `Error::TooManyRequests` | `Error` | status 429 |
+| `Error::InternalServerError` | `Error` | status 500 |
+| `Error::BadGateway` | `Error` | status 502 |
+| `Error::ServiceUnavailable` | `Error` | status 503 |
+| `Error::GatewayTimeout` | `Error` | status 504 |
+| `Error::Communication` | `Error` | socket caído/inalcanzable (`Excon::Error::Socket`); `Connection` la envuelve preservando el mensaje original |
+
+### b. Códigos HTTP → excepción (por `Middleware::ErrorHandler`)
+
+La gema **consume** HTTP, no lo expone. Esta tabla es el mapeo de respuesta-del-daemon → excepción-nuestra (`middleware/error_handler.rb:17-33`). El detalle de qué operación produce cada status está en el productor (Docker Engine API, ver [`docs/consumed/`](../consumed/docker-engine-api.md)).
+
+| status | excepción | mensaje |
+|---|---|---|
+| 200–299 | — | pasa (no levanta) |
+| 400 | `BadRequest` | `error_message(body)` |
+| 401 | `Unauthorized` | `error_message(body)` |
+| 403 | `Forbidden` | `error_message(body)` |
+| 404 | `NotFound` | `error_message(body)` |
+| 406 | `NotAcceptable` | `error_message(body)` |
+| 408 | `RequestTimeout` | `error_message(body)` |
+| 409 | `Conflict` | `error_message(body)` |
+| 422 | `UnprocessableEntity` | `body` (crudo) |
+| 429 | `TooManyRequests` | `error_message(body)` |
+| 500 | `InternalServerError` | `error_message(body)` |
+| 502 | `BadGateway` | `error_message(body)` |
+| 503 | `ServiceUnavailable` | `error_message(body)` |
+| 504 | `GatewayTimeout` | `error_message(body)` |
+| otro no-2xx | `Error` | `"HTTP #{status}: #{error_msg}"` |
+
+`error_message(body)`: si `body` es Hash → `body["message"] \|\| body["error"] \|\| body.to_json`; si no → `body.to_s` (`error_handler.rb:59-65`).
+
+### d. Shape del payload de error
+
+No aplica un shape propio tipo RFC 7807: la gema es un cliente, no un servidor. El "payload" que recibe el consumidor es la **excepción Ruby** con:
+
+- `exception.class` — el tipo tipado (tabla §a).
+- `exception.message` — el `message`/`error` del body de Docker (o el body crudo en 422), o `"Docker socket error: ..."` en `Communication`.
+- `exception.cause` — en `Communication`, el `Excon::Error::Socket` original queda accesible (`connection.rb:47,61`).
+
+### c. Política por error (retriable · backoff · idempotencia · acción)
+
+> **Mecanismo (anclado a `connection.rb:24-33`):** el auto-retry de la gema opera **solo a nivel transporte** — reintenta `Excon::Error::Socket` y `Excon::Error::Timeout` en métodos idempotentes (`get/head/put/delete/options`), `max_retries=3`, **sin backoff** (reintento inmediato, no hay `retry_interval`). Los errores **HTTP 4xx/5xx NO se auto-reintentan**: una vez que llega una respuesta con status, `ErrorHandler` levanta y no hay retry. La columna "retriable" abajo es por tanto **recomendación al consumidor**, no comportamiento automático (salvo `Communication`).
+
+> **Acción:** la gema **siempre loguea** el fallo (`request_failure`, nivel ERROR, `connection.rb:49`) y **propaga** (raise). No hay integración de observabilidad (Sentry/exis_ray) en la gema → `escalate`/`report` quedan al consumidor. Por eso la acción base de todas es **log + propagate**; la columna marca el matiz por error.
+
+| excepción | retriable? (consumidor) | backoff | idempotencia requerida | acción / nota |
+|---|---|---|---|---|
+| `BadRequest` (400) | no | — | — | propagate — corregir payload |
+| `Unauthorized` (401) | no | — | — | propagate — corregir credenciales/TLS |
+| `Forbidden` (403) | no | — | — | propagate — op no permitida en este rol |
+| `NotFound` (404) | no | — | — | `find`/`destroy` la absorben → `nil`; resto propagate |
+| `NotAcceptable` (406) | no | — | — | propagate |
+| `RequestTimeout` (408) | condicional | sí | sí (si POST) | retry solo en op idempotente; subir `read_timeout` |
+| `Conflict` (409) | condicional | — | sí | si `Version.Index` stale → `reload` + reintentar `update`; si nombre duplicado → no retriable, propagate |
+| `UnprocessableEntity` (422) | no | — | — | propagate — payload semánticamente inválido |
+| `TooManyRequests` (429) | sí | sí | no | backoff + retry (rate limit del daemon) |
+| `InternalServerError` (500) | condicional | sí | sí | retry en op idempotente; revisar payload (update sin `version` → 500) |
+| `BadGateway` (502) | sí | sí | sí (si POST) | transitorio (proxy); retry seguro en op idempotente |
+| `ServiceUnavailable` (503) | sí | sí | sí (si POST) | daemon reiniciando; retry con backoff |
+| `GatewayTimeout` (504) | sí | sí | sí (si POST) | transitorio; retry en op idempotente |
+| `Communication` (socket) | sí (auto) | no | sí (si POST) | la gema YA reintteta Socket/Timeout en métodos idempotentes (`max_retries`, sin backoff); en POST no reintenta → el caller decide |
+| `Error` (pull stream, HTTP 200) | sí (consumidor) | sí | sí | `Image.pull` la eleva ante un frame `error`/`errorDetail` del stream; propagate. El pull es idempotente → el caller puede reintentar (ej. fallo transitorio de red/registry). Distinguir de un 404 **pre-stream** (imagen/registry inexistente o acceso denegado → no retriable) |
+
+## 3. Inferencias
+
+| afirmación | confidence | a verificar |
+|---|---|---|
+| El "cuándo" de cada status (ej. 403 = swarm op en worker) refleja el comportamiento de Docker, no lógica de la gema | inferred | el mapeo es status→excepción genérico; la causa la fija el daemon. Notas tomadas de `skill/SKILL.md` |
+| `UnprocessableEntity` recibe el `body` crudo (no `error_message`) a propósito (422 suele traer detalle estructurado) | declared | `error_handler.rb:25` — divergencia explícita del resto |
+| §c columna "retriable" = recomendación al consumidor basada en semántica HTTP/Docker; la gema **no** auto-reintenta status HTTP (solo Socket/Timeout) | inferred | mecanismo anclado a `connection.rb`; la política por-status la confirma el humano contra el comportamiento real del daemon |
+| 409 `Conflict` con `Version.Index` stale → patrón reload+retry | inferred | el `update` extrae `Version.Index` (`updatable.rb:9`); el reload-on-conflict es decisión del consumidor, no automática |
+
+## 4. Cobertura y fronteras
+
+- **Solo errores públicos:** estas excepciones cruzan la frontera de la gema hacia el consumidor. No hay excepciones internas rescatadas-y-tragadas que documentar (salvo `JSON::ParserError` en `ResponseJSONParser`, que se traga y retorna el body crudo — interno, no contrato).
+- **Frontera con consumed (RFC-018):** este catálogo = lo que la gema **emite**. El mapeo "error del proveedor Docker → excepción nuestra" lo referencia [`docs/consumed/docker-engine-api.md`](../consumed/docker-engine-api.md) §d, que apunta acá.
+- **Política §c:** enriquecida (recomendación al consumidor); el matiz por-status lo confirma el humano contra el comportamiento real del daemon (ver §3).
+- **Validación de input del caller (`ArgumentError`, stdlib):** `RegistryAuth.resolve`/`validate!` (exclusión mutua `registry_auth`/`registry_auth_from` + enum del `from`) y `Base#assign_attributes` (no-Hash) elevan `ArgumentError` ante input inválido del caller — fail-fast, antes de tocar el daemon. Es contrato público de esas firmas (documentado en [`docs/interface/interface.md`](../interface/interface.md)), **no** parte de la jerarquía `DockerSwarm::Error` → por eso no está en §a/§c.