docker-swarm 0.7.1 → 0.8.0

data/docs/interface/interface.md

@@ -0,0 +1,118 @@
+# Interfaz — docker-swarm
+
+> meta: artefacto · RFC-004 · generado arch-structure · anclado a `29856f1` · cobertura: API Ruby pública de la gema (`lib/docker_swarm/**`); símbolos internos marcados en §4
+
+## 1. Resumen
+
+API Ruby pública de la gema. Entrypoint `DockerSwarm` (config + cliente HTTP). 11 modelos `ActiveModel`-compatibles heredan de `DockerSwarm::Base` y mezclan concerns (`Creatable`/`Updatable`/`Deletable`/`Loggable`). Atributos vía accessors dinámicos PascalCase (`method_missing`). Jerarquía de errores en `DockerSwarm::Error` (detalle en [`docs/errors/errors.md`](../errors/errors.md)).
+
+## 2. Cuerpo
+
+Proyección RBS-conceptual: `símbolo · tipo · nota` (raíz → profundidad → alfabético). Firmas aplanadas; el wire-schema de los atributos PascalCase no es estático (ver §4).
+
+### Módulo raíz `DockerSwarm`
+
+| símbolo | tipo | nota |
+|---|---|---|
+| `DockerSwarm` | módulo | namespace raíz |
+| `DockerSwarm::VERSION` | constante | `"0.8.0"` (`version.rb`) |
+| `DockerSwarm.configuration` | attr (r/w) | instancia de `Configuration`; lazy-init en `configure`/`connection` |
+| `DockerSwarm.configure { \|config\| ... }` | método de módulo | crea/yields `Configuration`; aplica `log_level` al logger; resetea la conexión memoizada |
+| `DockerSwarm.connection` | método de módulo | `Connection` memoizada (auto-`configure` si falta) |
+| `DockerSwarm.request(options = {})` | método de módulo | delega en `connection.request`; entrypoint de bajo nivel (escape hatch para llamadas crudas) |
+
+### `DockerSwarm::Configuration` (`configuration.rb`)
+
+| símbolo | tipo | nota |
+|---|---|---|
+| `#socket_path` | attr (r/w) | default `"unix:///var/run/docker.sock"` |
+| `#logger` | attr (r/w) | default `Logger.new($stdout)` |
+| `#log_level` | attr (r/w) | default `Logger::INFO` |
+| `#read_timeout` / `#read_timeout=` | attr (r) + setter | default `60.0`; setter castea `to_f` |
+| `#write_timeout` / `#write_timeout=` | attr (r) + setter | default `60.0`; setter castea `to_f` |
+| `#connect_timeout` / `#connect_timeout=` | attr (r) + setter | default `10.0`; setter castea `to_f` |
+| `#max_retries` / `#max_retries=` | attr (r) + setter | default `3`; setter castea `to_i` |
+
+Inventario completo de opciones: [`docs/config/configuracion.md`](../config/configuracion.md).
+
+### `DockerSwarm::Base` (`base.rb`) — base de los modelos
+
+`include ActiveModel::Model`, `include Concerns::Inspectable`.
+
+| símbolo | tipo | nota |
+|---|---|---|
+| `.resource_name` | método de clase | `name.demodulize.downcase.pluralize`; override en `Swarm`/`System` |
+| `.routes` | método de clase | `Api::ENDPOINTS[resource_name.to_sym]` |
+| `.root_key` | método de clase | `nil` por default; override `"Volumes"` en `Volume` |
+| `.defined_attributes` | método de clase | `Set` de accessors ya definidos (interno; cache de `method_missing`) |
+| `.all(filters = {})` | método de clase | `GET index`; mapea a instancias; aplica `root_key`; `[]` si vacío |
+| `.find(id)` | método de clase | `GET show`; `nil` si `Errors::NotFound` |
+| `.where(filters)` | método de clase | alias de `all` |
+| `#initialize(attributes = {})` | método de instancia | `assign_attributes` si presente |
+| `#assign_attributes(new_attributes)` | método de instancia | normaliza `Id`→`ID`; `deep_merge` del campo `Spec`; `ArgumentError` si no es Hash |
+| `#attributes` | método de instancia | `instance_values` sin internos de ActiveModel |
+| `#serializable_hash` / `#as_json` | método de instancia | == `attributes` |
+| `#payload_for_docker` | método de instancia | descarta `ID/Version/CreatedAt/UpdatedAt`; aplana `Spec` al root |
+| `#persisted?` | método de instancia | `ID` presente |
+| `#id` | método de instancia | == `self.ID` |
+| `#reload` | método de instancia | re-`find` por `id` y re-asigna |
+| `#method_missing` / `#respond_to_missing?` | método de instancia | accessors dinámicos PascalCase (atributos del recurso Docker) |
+
+### Concerns (`concerns/*.rb`)
+
+| símbolo | tipo | nota |
+|---|---|---|
+| `Concerns::Creatable.create(attributes = {}, **opts)` | método de clase (mixin) | `new` + `save`; retorna la instancia. `opts` reservado `registry_auth:` (→ header `X-Registry-Auth`); el resto se pliega como atributos |
+| `Concerns::Creatable#save(registry_auth: nil)` | método de instancia | `false` si `!valid?`; `update` si `persisted?`; si no `POST create` + `reload`. `registry_auth` viaja como header, nunca en el payload |
+| `Concerns::Updatable#update(new_attributes = {}, **opts)` | método de instancia | extrae `Version.Index`; `false` si `!valid?`; `POST update` con `?version=`. `opts` reservado `registry_auth:` (header) / `registry_auth_from:` (query `registryAuthFrom`, `spec`\|`previous-spec`, excluyente con `registry_auth`); el resto se pliega como atributos |
+| `Concerns::Deletable.destroy(id)` | método de clase (mixin) | `DELETE destroy`; `nil` si `Errors::NotFound` |
+| `Concerns::Deletable#destroy` | método de instancia | delega en `.destroy(self.ID)` |
+| `Concerns::Loggable#logs(query_params = { stdout: 1, stderr: 1 })` | método de instancia | `GET logs`; retorna el stream raw |
+| `Concerns::Inspectable#inspect` | método de instancia | render legible (ID/Name/Version/Spec) |
+
+### Modelos (`models/*.rb`)
+
+| símbolo | tipo | concerns + métodos propios |
+|---|---|---|
+| `DockerSwarm::Service` | clase < Base | Creatable, Updatable, Deletable, Loggable; `#restart` (incrementa `TaskTemplate.ForceUpdate`); `create`/`update` aceptan `registry_auth:` (+ `update`: `registry_auth_from:`) para auth de registry privado |
+| `DockerSwarm::Node` | clase < Base | Updatable, Deletable (sin `create`: los nodos se unen fuera de la gema) |
+| `DockerSwarm::Task` | clase < Base | Loggable (read-only; generadas por el orquestador) |
+| `DockerSwarm::Container` | clase < Base | Deletable, Loggable; `#start`, `#stop` (sin `create`: gap intencional) |
+| `DockerSwarm::Image` | clase < Base | Deletable + `.pull(image_reference, registry_auth: nil)`. **NO** es Creatable (`Image.create` retirado sin alias). `.pull` = pull explícito síncrono: consume el stream NDJSON hasta EOF, eleva `DockerSwarm::Error` ante frame `error`/`errorDetail`, retorna `{ status: :pulled, image_ref:, digest? }` (sin `find` posterior) |
+| `DockerSwarm::Network` | clase < Base | Creatable, Updatable, Deletable |
+| `DockerSwarm::Volume` | clase < Base | Creatable, Deletable; `.root_key = "Volumes"` (respuesta wrapped) |
+| `DockerSwarm::Config` | clase < Base | Creatable, Deletable (sin `update`: recrear) |
+| `DockerSwarm::Secret` | clase < Base | Creatable, Deletable (sin `update`); `Data` filtrado en logs |
+| `DockerSwarm::Swarm` | clase < Base | `.resource_name = "swarm"`; `.show` (singleton, info del cluster) |
+| `DockerSwarm::System` | clase < Base | `.resource_name = "system"`; `.info`, `.version`, `.up`, `.df` (singleton) |
+
+### Superficie de bajo nivel / soporte
+
+| símbolo | tipo | nota |
+|---|---|---|
+| `DockerSwarm::Api::ENDPOINTS` | constante (frozen Hash) | mapa `recurso → {operación → {method, path}}` |
+| `DockerSwarm::Api.request(action:, arguments: {}, query_params: {}, payload: nil)` | método de clase | formatea el `path` y delega en `DockerSwarm.request` |
+| `DockerSwarm::Connection.new(socket_path, logger)` | clase | cliente Excon (Unix socket o TCP); `#request`, `#socket_path`, `#logger` |
+| `DockerSwarm::Connection::IDEMPOTENT_METHODS` | constante | `%i[get head put delete options]` (los únicos con retry) |
+| `DockerSwarm::LogHelper.format_kv(payload)` | método de módulo | formatea KV + masking de claves sensibles |
+| `DockerSwarm::LogHelper::SENSITIVE_KEYS` | constante (Regexp) | `password\|pass\|...\|\bdata\b` |
+| `DockerSwarm::RegistryAuth.resolve(registry_auth:, registry_auth_from:)` | método de módulo | traduce las opciones de auth a `[headers, query_params]` (`X-Registry-Auth` / `registryAuthFrom`); valida exclusión mutua + enum antes de la request. Usado por `Image.pull` / `#save` / `#update`; la credencial nunca toca payload ni estado del modelo |
+| `DockerSwarm::RegistryAuth::{HEADER, QUERY, FROM_VALUES}` | constantes | `"X-Registry-Auth"` · `:registryAuthFrom` · `%w[spec previous-spec]` |
+| `DockerSwarm::Error` + subclases + aliases + `DockerSwarm::Errors` | clases/módulo | jerarquía de errores — detalle en [`docs/errors/errors.md`](../errors/errors.md) |
+| `DockerSwarm::Middleware::{RequestEncoder, ResponseJSONParser, ErrorHandler}` | clases | middlewares Excon; públicos por require pero de uso interno (ver §4) |
+
+## 3. Inferencias
+
+| afirmación | confidence | a verificar |
+|---|---|---|
+| `Connection`, `Api` y los `Middleware::*` son de uso **interno** (un consumidor normal usa los modelos, no estas clases) | inferred | son `public` en Ruby; no hay marca `@api private`. `DockerSwarm.request`/`Api` son el escape-hatch documentado en `skill/SKILL.md` |
+| `.defined_attributes` es interno (cache de `method_missing`), no superficie de consumo | inferred | público pero sin uso externo plausible |
+| Los atributos PascalCase (`service.Spec`, `service.Version`, …) son la superficie real de datos, pero su set depende de la respuesta del Docker Engine API | declared | `method_missing` define accessors on-demand; el shape lo fija Docker, no la gema |
+
+## 4. Cobertura y fronteras
+
+- **Wire-schema de atributos:** los modelos no declaran atributos estáticos — se materializan dinámicamente desde el JSON de Docker (`method_missing`). El shape de `Spec`/`TaskTemplate`/etc. es el del Docker Engine API v1.41, **fuera de este repo** (doc oficial Docker). `unspecified` acá a propósito.
+- **`interface` vs `operaciones` (RFC-003):** esta gema NO expone superficie HTTP/CLI/eventos propia → `docs/api/operaciones` es `n/a`. Su superficie pública ES esta interfaz Ruby. Lo que la gema *consume* (Docker Engine API) vive en [`docs/consumed/`](../consumed/docker-engine-api.md).
+- **Errores:** la jerarquía `DockerSwarm::Error` se cataloga en [`docs/errors/errors.md`](../errors/errors.md); acá solo se referencia.
+- **Símbolos internos:** `Connection`, `Api`, `Middleware::*`, `Base.defined_attributes` se listan por completitud pero no son API de consumo recomendada; un cambio en ellos no rompe el contrato del consumidor típico (que usa los modelos).
+- **Significado de negocio** de cada modelo/término → [`docs/glossary/glossary.md`](../glossary/glossary.md); secuencias → [`docs/behavior/behavior.md`](../behavior/behavior.md).

data/docs/release/release.md

@@ -0,0 +1,54 @@
+# Release — docker-swarm
+
+> meta: artefacto · RFC-014 · generado arch-structure + enriquecido arch-enrich · anclado a `cccfe63` · cobertura: §a estructura completa (versión · changelog · build-trigger · patrón); §b enrich completa (deploy · rollback · ambientes · dueño)
+
+## 1. Resumen
+
+Gema Ruby publicada en RubyGems. Release por **tag `v*`**: el push del tag dispara el workflow `Publish to RubyGems` que hace `gem build` + `gem push`. Sin deploy de infraestructura (gema, no servicio): no hay `Dockerfile`, ni branches `production`/`staging`, ni ambientes.
+
+## 2. Cuerpo
+
+### §a Estructura (verificable del código)
+
+| campo | valor | fuente |
+|---|---|---|
+| versión actual | `0.7.2` | `lib/docker_swarm/version.rb` (`DockerSwarm::VERSION`) |
+| esquema de versión | SemVer (`MAJOR.MINOR.PATCH`) | `CHANGELOG.md` (breaking/mejoras/correcciones por bump) |
+| artefacto liberado | gema `docker-swarm` a RubyGems | `docker-swarm.gemspec` (`spec.name`), `.github/workflows/release.yml` |
+| changelog | `CHANGELOG.md`, formato Keep a Changelog, entradas fechadas por versión | `CHANGELOG.md` |
+| licencia | MIT | `docker-swarm.gemspec` (`spec.license`) |
+| build-trigger | push de tag `v*` | `.github/workflows/release.yml` (`on.push.tags: ['v*']`) |
+| **patrón de trigger (RFC-014)** | **patrón 1** — publish per-repo-visible en workflow (tag → RubyGems) | `.github/workflows/release.yml` |
+| runner de release | `ubuntu-latest`, Ruby `3.4.4` | `.github/workflows/release.yml` |
+| pasos de publish | `gem build *.gemspec` + `gem push *.gem` | `.github/workflows/release.yml` |
+| credencial de publish | `secrets.RUBYGEMS_API_KEY` (env `RUBYGEMS_API_KEY`) | `.github/workflows/release.yml` |
+| MFA de publish | requerida (`rubygems_mfa_required = "true"`) | `docker-swarm.gemspec` (`spec.metadata`) |
+| Ruby mínimo del release | `>= 3.2.0` | `docker-swarm.gemspec` (`required_ruby_version`) |
+| contenido empaquetado | `lib`, `exe`, `skill`, `docs` + `README.md`, `CHANGELOG.md`, `LICENSE` | `docker-swarm.gemspec` (`spec.files`). Empaquetar `skill/` + `docs/` es **intencional**: la gema shippea su skill version-locked (RFC-008) y los artefactos de arquitectura para consumidores/agentes |
+| CI (no gatea el release) | workflow `Ruby` (`main.yml`) corre en push a `main` / PR: `rspec` (sin `type:integration`) + `rubocop`. **Independiente** de `release.yml` — el tag `v*` publica sin exigir que el CI haya pasado | `.github/workflows/main.yml` |
+| dependencias runtime | `activesupport >= 6.0`, `activemodel >= 6.0`, `excon >= 0.80` | `docker-swarm.gemspec` |
+
+### §b Deploy · rollback · ambientes · dueño (enrich)
+
+| dimensión | valor | nota |
+|---|---|---|
+| deploy | Publicación a RubyGems por `gem push` al pushear el tag `v*`. Los consumidores la reciben vía Bundler (`gem 'docker-swarm'`) tras la propagación del índice de RubyGems (~minutos) | "Deploy" para una gema = disponibilidad en RubyGems; no hay infraestructura que desplegar |
+| rollback | **Bump correctivo (preferido):** publicar un patch nuevo (`X.Y.Z+1`) con el fix. RubyGems **prohíbe** re-pushear el mismo número de versión (restricción técnica). `gem yank -v X.Y.Z` — RubyGems lo permite en cualquier momento (no hay restricción técnica), pero es **política del equipo** reservarlo a casos graves (secreto filtrado, gema rota/ininstalable) | Distinguir: el re-push prohibido es técnico de RubyGems; el yank restringido es decisión del equipo (un yank rompe a quien fijó esa versión → se prefiere avanzar) |
+| ambientes | No aplica: artefacto único publicado en RubyGems, sin staging/producción. El único "ambiente" es la versión instalada por cada consumidor | La matriz de compatibilidad la fija `required_ruby_version` (`>= 3.2.0`), no un ambiente de deploy |
+| dueño del release | Gabriel (mantenedor) — taggea `v*` y publica; @Pablo contribuye fixes | Derivado del historial de `CHANGELOG.md` y confirmado por el equipo |
+
+## 3. Inferencias
+
+| afirmación | confidence | a verificar |
+|---|---|---|
+| Patrón de trigger = 1 (publish per-repo-visible por tag), no patrón 3 (branch `production`/`staging`) | declared | `release.yml` sólo escucha `tags: v*`; no existen branches `production`/`staging` (`git branch -a`) |
+| Esquema de versión = SemVer | inferred | derivado del uso en `CHANGELOG.md` (0.7.0 marcó breaking changes); no hay política SemVer declarada explícita en el repo |
+| No hay deploy de infra | declared | ausencia de `Dockerfile`, `docker-compose.yml`, `helm/`, branches de ambiente — es gema, no servicio |
+| El gem se buildea bajo Ruby `3.4.4` aunque declara floor `>= 3.2.0` | declared | runner fijo en `release.yml` (`3.4.4`) vs `required_ruby_version` del gemspec (`>= 3.2.0`); no es defecto — el build no acopla el floor de compatibilidad |
+
+## 4. Cobertura y fronteras
+
+- **Estructura (§a) y enrich (§b) completas** al ancla `cccfe63`; significado de §b aportado por el mantenedor.
+- **Proceso operativo del release** (quién taggea, checklist, bump de versión) lo ejecuta la skill `gem-release`; este artefacto documenta el contrato, no el paso-a-paso de la skill.
+- **Trade-off conocido:** el release (`release.yml`, tag `v*`) **no exige** que el CI (`main.yml`) haya pasado — un tag publica aunque los tests fallen. Hoy el gate es de facto (el dev corre la suite antes de taggear), no forzado por el pipeline. Endurecerlo (exigir CI verde antes de publicar) es una mejora de proceso pendiente, no documentada como decisión formal.
+- **Fuera de alcance:** la config runtime de la gema vive en `docs/config/configuracion.md`; la suite y su gate CI en `docs/test/testing.md` (este artefacto sólo referencia el gate pre-release, no lo redefine).

data/docs/test/testing.md

@@ -0,0 +1,100 @@
+# Test — docker-swarm
+
+> meta: artefacto · RFC-013 · generado arch-structure + enriquecido arch-enrich · anclado a `8f2e1f7` · cobertura: estructura de la suite (`spec/`, `.github/workflows/main.yml`); §e enriquecida, §f enriquecida, §g `unknown` (sin incidentes registrados), §h enriquecida
+
+## 1. Resumen
+
+Suite RSpec en dos niveles: **unit** (mockean `DockerSwarm::Api`/`Excon`, sin daemon) e **integration** (`type: :integration`, requieren un Docker daemon real). CI corre solo unit + RuboCop; integration es local/opt-in. Sin herramienta de coverage configurada.
+
+## 2. Cuerpo
+
+### a. Suites, frameworks y niveles
+
+Framework: **RSpec** (`~> 3.0`). `verify_partial_doubles = true` (mocks estrictos).
+
+| subdirectorio | propósito | nivel | helper |
+|---|---|---|---|
+| `spec/docker/swarm/*_spec.rb` | api, configuration, connection, log_helper, registry_auth | unit | `spec_helper` |
+| `spec/docker/swarm/middleware/*_spec.rb` | error_handler, request_encoder, response_json_parser | unit | `spec_helper` |
+| `spec/docker/swarm/models/*_spec.rb` | base, container, image, network, node, service, task + `shared_crud_spec` | unit | `spec_helper` |
+| `spec/integration/*_spec.rb` | containers, infra, security, services, system | integration | `integration_helper` |
+
+Tag de nivel: las integration declaran `RSpec.describe "...", type: :integration` (`spec/integration/*_spec.rb:5`). Las unit no llevan tag → se filtran con `~type:integration`.
+
+`shared_crud_spec.rb` = shared examples de CRUD reusados por los specs de modelo.
+
+### b. Comando de corrida
+
+| contexto | comando | qué corre |
+|---|---|---|
+| unit (local) | `bundle exec rspec --tag ~type:integration` | todo menos integration |
+| integration (local) | `bundle exec rspec` | incluye integration (requiere Docker socket; override `DOCKER_URL`) |
+| lint | `bundle exec rubocop` | rubocop-rails-omakase |
+| CI (`.github/workflows/main.yml`) | `bundle exec rspec --tag ~type:integration` + `bundle exec rubocop` | unit + lint, Ruby 3.4.4 |
+
+CI **no** corre integration (no hay daemon en el runner). Se dispara en push a `main` y en `pull_request`.
+
+### c. Fixtures / Factories
+
+- **Sin fixtures YAML ni FactoryBot.** Los datos de prueba se construyen inline en cada spec.
+- **Unit:** mockean `DockerSwarm::Api.request` (o `Excon`) con `and_return`/`and_raise` (stubs de respuesta Docker). `spec_helper` configura `socket_path = "unix:///tmp/docker.sock"` y logger a `/dev/null`.
+- **Integration:** crean recursos reales contra el daemon; helper `random_name(prefix)` (`integration_helper.rb:26`) genera nombres únicos con `SecureRandom.hex(4)` para evitar colisiones.
+
+### d. Configuración de coverage
+
+Ninguna. No hay `SimpleCov`/`.simplecov` ni umbral declarado en el repo (verificado: sin `SimpleCov` en `spec/` ni en `Gemfile.lock`).
+
+### e. Gaps de cobertura (narrado)
+
+> Cobertura declarada — qué flujos de negocio están ejercitados y cuáles no. No es el % de líneas (no hay SimpleCov, §d).
+
+**Cubierto (unit, con mocks):**
+- Mapeo de errores HTTP → excepción: `error_handler_spec` (subset de status verificado: 200, 404, 429, 500 — no los 14).
+- Modelos con métodos propios: `service` (incl. lógica de update/version), `node`, `task`, `container` (start/stop), `network`, `base` (accessors dinámicos, `assign_attributes`/`Spec` merge).
+- CRUD genérico de `config`, `secret`, `volume`: vía `shared_crud_spec` (`it_behaves_like "a crud resource"`) — no tienen spec dedicado pero **sí** están cubiertos (create/find/destroy). `image` salió del CRUD genérico (su `create` era un pull) → tiene spec propio (abajo).
+- `image`: `image_spec` (dedicado) — `Image.pull` (stream NDJSON, extracción de digest del frame `Digest:`, error tipado ante `error`/`errorDetail`, forma polimórfica del body) + `Deletable` y listado.
+- Auth de registry privado: `registry_auth_spec` (helper `RegistryAuth`: exclusión mutua `registry_auth`/`registry_auth_from`, enum del `from`, traducción a header/query) + bloque registry-auth en `service_spec` (create/update, no-exposición de la credencial en logs).
+- Infra de transporte: `api_spec`, `connection_spec`, `configuration_spec`, `log_helper_spec`, los 3 middleware specs.
+- `swarm`, `system` (singletons): `swarm_spec`, `system_spec`.
+
+**Cubierto (integration, daemon real):** lifecycle de containers, services, infra (networks/volumes), system (info/version/up/df), security (config/secret create+find+destroy).
+
+**Gaps declarados:**
+- `error_handler_spec` ejercita **un subset** de los 14 status; 400/401/403/406/408/409/422/502/503/504 y el fallback genérico no tienen aserción dedicada (gap de contrato §f).
+- `Service#restart`, `Loggable#logs` — cobertura unit no confirmada por spec dedicado; verificar.
+- Path de error `Communication` (socket caído) y la política de retry idempotente: no confirmado que haya spec dedicado en `connection_spec` (verificar).
+
+### f. Contract-assessment (¿los tests ejercitan los contratos públicos?)
+
+| contrato | RFC | cubierto | nota |
+|---|---|---|---|
+| Interfaz Ruby pública | RFC-004 | parcial | model specs + `shared_crud` ejercitan `all/find/create/update/destroy/logs`; falta aserción sistemática de toda la superficie |
+| Errores públicos | RFC-020 | parcial | `error_handler_spec` cubre el mapeo status→excepción pero **solo 4 de 14 status** → contrato de errores incompletamente verificado |
+| Docker Engine API consumida | RFC-018 | sí (integration) | los specs `type: :integration` ejercitan el contrato real contra el daemon; unit lo mockea |
+
+### g. Link a incidente
+
+`unknown` — **por ausencia de fuente, no por verificación de que no existan.** No hay un tracker de incidentes vinculado a este repo ni `refs incidente/PR` en los specs o en el historial localizable; por tanto no se puede afirmar ni que haya ni que no haya tests nacidos de un incidente. No es "cero incidentes verificado". Se completará si/cuando un test de regresión se ate explícitamente al bug que previene.
+
+### h. PII / datos sensibles en fixtures
+
+**Sin PII real ni secretos reales.** Clasificación (no valores):
+
+- Nombres de recursos: generados con `random_name(prefix)` → `SecureRandom.hex(4)` (`integration_helper.rb:26`). Sintéticos.
+- `Config`/`Secret` Data en integration: literales de prueba base64 (`Base64.strict_encode64("hello world")`, `"top secret"` — `security_spec.rb`). **No** son credenciales reales; son strings de test.
+- Unit specs: payloads inline mockeados, sin datos reales.
+
+No cruza RFC-026 (no hay PII de personas ni secretos productivos en fixtures).
+
+## 3. Inferencias
+
+| afirmación | confidence | a verificar |
+|---|---|---|
+| Los specs de modelo unit mockean `Api`/`Excon` (no tocan socket) | inferred | `spec_helper` apunta a `/tmp/docker.sock` inexistente → necesariamente stubean; patrón confirmado en `skill/SKILL.md` |
+| Integration requiere daemon Swarm activo | declared | `integration_helper` usa el socket real (`DOCKER_URL` o default) |
+
+## 4. Cobertura y fronteras
+
+- **Contenido de cada test case** individual queda en el código, no acá.
+- **Niveles:** solo unit e integration; no hay system/e2e ni matriz de versiones (`Appraisals`) — Ruby único (3.4.4) en CI.
+- **Coverage real (%)** no medible desde el repo (sin tool); §d declara la ausencia, no un número.

data/docs/topology/topology.md

@@ -0,0 +1,55 @@
+# Topología — docker-swarm
+
+> meta: artefacto · RFC-006 · generado arch-structure · anclado a `15bcd21` · cobertura: dependencias runtime (`.gemspec` + `Gemfile.lock`) y mapa de contexto de la gema
+
+## 1. Resumen
+
+Gema cliente sin servidor propio. Tres dependencias runtime (`activesupport`, `activemodel`, `excon`). Se ubica entre el código Ruby consumidor y el Docker Engine API (vía socket Unix o TCP). No tiene base de datos, colas ni servicios adyacentes propios.
+
+## 2. Cuerpo
+
+### a. Dependencias
+
+Runtime declaradas en `docker-swarm.gemspec`; versiones resueltas en `Gemfile.lock`.
+
+| nombre | versión (constraint) | resuelta | rol |
+|---|---|---|---|
+| `activesupport` | `>= 6.0` | 8.1.3 | core-ext (`HashWithIndifferentAccess`, `deep_merge`, `blank?`, `demodulize`, `pluralize`) |
+| `activemodel` | `>= 6.0` | 8.1.3 | `ActiveModel::Model` (validaciones, API de atributos) en `Base` |
+| `excon` | `>= 0.80` | 1.5.0 | cliente HTTP con soporte nativo de Unix socket + stack de middlewares |
+
+Desarrollo / test (no se empaquetan): `rake ~> 13.0`, `rspec ~> 3.0`, `pry`, `rubocop-rails-omakase`.
+
+### b. Grafo de contexto
+
+```mermaid
+flowchart LR
+  Consumer["App Ruby consumidora"] -->|usa modelos| Gem["docker-swarm (gema)"]
+  Gem -->|ActiveModel / core-ext| AS["activesupport + activemodel"]
+  Gem -->|HTTP via Excon| Daemon["Docker Engine API (dockerd)"]
+  Daemon -.->|unix:///var/run/docker.sock o TCP| Gem
+```
+
+La gema es el centro: arriba la consume una app Ruby; abajo habla con el daemon Docker por Excon. `activesupport`/`activemodel` son librerías embebidas, no servicios.
+
+### c. Modos de ejecución
+
+No aplica: es una librería embebida en el proceso del consumidor (sin web/worker/cron propios). El único "modo" es el transporte hacia el daemon:
+
+| transporte | configuración | default |
+|---|---|---|
+| Unix socket | `socket_path = "unix:///var/run/docker.sock"` | sí |
+| TCP | `socket_path = "http://host:2375"` | no |
+
+## 3. Inferencias
+
+| afirmación | confidence | a verificar |
+|---|---|---|
+| `activesupport`/`activemodel` 8.1.3 son las resueltas hoy, pero el constraint `>= 6.0` admite Rails 6/7/8 | declared | `Gemfile.lock` fija 8.1.3; el `.gemspec` no pone techo |
+| La gema no abre puertos ni corre procesos propios | declared | sin `config/`, sin `bin/` server, sin Railtie/Engine |
+
+## 4. Cobertura y fronteras
+
+- **Dependencias transitivas:** las de `activesupport` (concurrent-ruby, i18n, tzinfo, etc.) y `excon` (logger) están en `Gemfile.lock` pero no son edges del repo → fuera del grafo de contexto.
+- **El daemon Docker** es la única dependencia externa de runtime real; su contrato consumido se detalla en [`docs/consumed/docker-engine-api.md`](../consumed/docker-engine-api.md).
+- **Arquitectura upstream** (cómo está desplegado el cluster Swarm que la gema administra) es del operador, no del repo → fuera de alcance.

data/lib/docker_swarm/api.rb

@@ -66,19 +66,23 @@ module DockerSwarm
       images: {
         index: { method: :get, path: "images/json" },
         show: { method: :get, path: "images/%<id>s/json" },
-        create: { method: :post, path: "images/create?fromImage=%<id>s" },
+        pull: { method: :post, path: "images/create" },
         destroy: { method: :delete, path: "images/%<id>s" }
       }
     }.freeze
 
-    def self.request(action:, arguments: {}, query_params: {}, payload: nil)
+    def self.request(action:, arguments: {}, query_params: {}, payload: nil, headers: {})
       path = format(action[:path], arguments)
-      DockerSwarm.request(
+      options = {
         method: action[:method],
         path: path,
         query: query_params,
         body: payload
-      )
+      }
+      # Solo forwardeamos headers cuando hay: sin ellos, la request queda
+      # idéntica a la actual (no pisamos los headers por defecto de Excon).
+      options[:headers] = headers if headers && !headers.empty?
+      DockerSwarm.request(**options)
     end
   end
 end

data/lib/docker_swarm/concerns/creatable.rb

@@ -6,20 +6,27 @@ module DockerSwarm
       extend ActiveSupport::Concern
 
       class_methods do
-        def create(attributes = {})
-          resource = new(attributes)
-          resource.save
+        # @param attributes [Hash] atributos Docker (hash posicional braceado)
+        # @param opts [Hash] keywords: atributos sueltos históricos + opción reservada
+        #   +registry_auth+ (credencial para X-Registry-Auth). El resto se pliega como atributos.
+        def create(attributes = {}, **opts)
+          registry_auth = opts.delete(:registry_auth)
+          resource = new(attributes.merge(opts))
+          resource.save(registry_auth: registry_auth)
           resource
         end
       end
 
-      def save
+      # @param registry_auth [String, nil] credencial opaca para el header X-Registry-Auth
+      def save(registry_auth: nil)
         return false unless valid?
-        return update if persisted?
+        return update(registry_auth: registry_auth) if persisted?
 
+        headers, = RegistryAuth.resolve(registry_auth: registry_auth)
         response = Api.request(
           action: self.class.routes[:create],
-          payload: payload_for_docker
+          payload: payload_for_docker,
+          headers: headers
         )
 
         self.ID = response["ID"] || response["Id"] || response["Name"]

data/lib/docker_swarm/concerns/updatable.rb

@@ -5,16 +5,27 @@ module DockerSwarm
     module Updatable
       extend ActiveSupport::Concern
 
-      def update(new_attributes = {})
+      # @param new_attributes [Hash] atributos Docker (hash posicional braceado)
+      # @param opts [Hash] keywords: atributos sueltos históricos + opciones reservadas
+      #   +registry_auth+ (header X-Registry-Auth) / +registry_auth_from+ (query registryAuthFrom,
+      #   excluyente con registry_auth). El resto se pliega como atributos.
+      def update(new_attributes = {}, **opts)
+        registry_auth = opts.delete(:registry_auth)
+        registry_auth_from = opts.delete(:registry_auth_from)
+        # Valida (excluyente + enum) y resuelve los canales ANTES de mutar el objeto.
+        headers, auth_query = RegistryAuth.resolve(registry_auth: registry_auth, registry_auth_from: registry_auth_from)
+
         current_version = self.Version&.dig("Index")
-        assign_attributes(new_attributes) if new_attributes.present?
+        attributes = new_attributes.merge(opts)
+        assign_attributes(attributes) if attributes.present?
         return false unless valid?
 
         Api.request(
           action: self.class.routes[:update],
           arguments: { id: self.ID },
-          query_params: { version: current_version },
-          payload: payload_for_docker
+          query_params: { version: current_version }.merge(auth_query),
+          payload: payload_for_docker,
+          headers: headers
         )
 
         true

data/lib/docker_swarm/connection.rb

@@ -102,14 +102,14 @@ module DockerSwarm
     end
 
     def client
-      debug_enabled = logger&.level == Logger::DEBUG
-
+      # NO habilitamos el debug de Excon ni le pasamos el logger. El instrumentor
+      # de Excon redacta solo Authorization/Proxy-Authorization, NUNCA headers de
+      # autenticación custom (p. ej. X-Registry-Auth) → filtraría esa credencial.
+      # Nuestro #log_event ya loguea request/response con redacción recursiva
+      # (LogHelper.sanitize). Para wire-debug explícito y consciente del riesgo queda
+      # EXCON_DEBUG (mecanismo nativo de Excon, off por defecto).
       options = {
         middlewares: common_middlewares,
-        logger: logger,
-        debug_request: debug_enabled,
-        debug_response: debug_enabled,
-        # Si debug_enabled es true, Excon usará su lógica interna de debug con el logger proporcionado
         retry_limit: 0
       }
 

data/lib/docker_swarm/log_helper.rb

@@ -5,15 +5,38 @@ module DockerSwarm
   module LogHelper
     # `data` se matchea con \b para que `Data` (Secret/Config) se filtre
     # pero `metadata` u otras claves no caigan en falso positivo.
+    # `auth` cubre headers de autenticación (`X-Registry-Auth`, `Authorization`), case-insensitive.
     SENSITIVE_KEYS = /password|pass|passwd|secret|token|api_key|auth|\bdata\b/i.freeze
+    FILTERED = "[FILTERED]"
+
+    # Redacta recursivamente los valores cuya CLAVE es sensible, a cualquier
+    # profundidad (hashes y arrays anidados). No muta la entrada: devuelve copias.
+    #
+    # Un header sensible puede viajar anidado (`headers: { "X-Registry-Auth" => "<cred>" }`)
+    # y el match por clave de primer nivel no lo alcanzaba — el hash interno se
+    # interpolaba entero.
+    #
+    # @param value [Object] hash, array o escalar
+    # @return [Object] copia con los valores sensibles reemplazados por [FILTERED]
+    def self.sanitize(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(k, v), acc|
+          acc[k] = k.to_s.match?(SENSITIVE_KEYS) ? FILTERED : sanitize(v)
+        end
+      when Array
+        value.map { |v| sanitize(v) }
+      else
+        value
+      end
+    end
 
     # Formats a hash into a KV structured string with sensitive data masking
     # @param payload [Hash] The data to format
     # @return [String] KV formatted string
     def self.format_kv(payload)
-      payload.map do |k, v|
-        val = k.to_s =~ SENSITIVE_KEYS ? "[FILTERED]" : v
-        "#{k}=#{val}"
+      sanitize(payload).map do |k, v|
+        "#{k}=#{v}"
       end.join(" ")
     rescue
       "event=logging_error"

data/lib/docker_swarm/models/image.rb

@@ -3,8 +3,92 @@
 module DockerSwarm
   # Represents a Docker Image
   # @see https://docs.docker.com/engine/api/v1.41/#tag/Image
+  #
+  # No incluye Creatable: el "create" del Docker API sobre imágenes es un PULL
+  # (stream de progreso), no la construcción de un recurso CRUD. Se expone como
+  # `.pull` con contrato propio.
   class Image < Base
-    include Concerns::Creatable
     include Concerns::Deletable
+
+    # Docker emite el digest del pull en un frame de status "Digest: sha256:..."
+    # (verificado empíricamente contra Docker 29.5.3; el stream de pull NO trae campo `aux`).
+    DIGEST_STATUS = /\bDigest:\s*(sha256:[0-9a-f]+)/
+
+    class << self
+      # Pull explícito de una imagen (POST /images/create).
+      #
+      # Operación SÍNCRONA: consume el stream NDJSON de progreso 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 que reintroduciría el problema referencia-vs-ID.
+      #
+      # @param image_reference [String] referencia completa (registry/repo:tag o @sha256:...)
+      # @param registry_auth [String, nil] credencial opaca base64url → header X-Registry-Auth
+      # @return [Hash] { status: :pulled, image_ref: String, digest: String (si Docker lo emite) }
+      # @raise [DockerSwarm::Error] si el stream reporta error/errorDetail
+      def pull(image_reference, registry_auth: nil)
+        headers, = RegistryAuth.resolve(registry_auth: registry_auth)
+
+        body = Api.request(
+          action: routes[:pull],
+          query_params: { fromImage: image_reference },
+          headers: headers
+        )
+
+        frames = parse_progress_stream(body)
+        raise_on_stream_error!(frames)
+        pull_result(image_reference, frames)
+      end
+
+      private
+
+      # El middleware entrega el stream como String (multi-frame NDJSON: el JSON.parse
+      # global falló y devolvió el cuerpo crudo) o como Hash (un único objeto JSON, p. ej.
+      # algunos errores). Normalizamos a una lista de frames-Hash en ambos casos.
+      def parse_progress_stream(body)
+        case body
+        when Hash
+          [ body ]
+        when String
+          body.each_line.filter_map { |line| parse_frame(line) }
+        else
+          []
+        end
+      end
+
+      def parse_frame(line)
+        line = line.strip
+        return if line.empty?
+
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def raise_on_stream_error!(frames)
+        error_frame = frames.find { |frame| frame["error"] || frame["errorDetail"] }
+        return unless error_frame
+
+        detail = error_frame.dig("errorDetail", "message") || error_frame["error"]
+        raise DockerSwarm::Error, "image pull failed: #{detail}"
+      end
+
+      def pull_result(image_reference, frames)
+        digest = extract_digest(frames)
+
+        result = { status: :pulled, image_ref: image_reference }
+        result[:digest] = digest if digest
+        result
+      end
+
+      # Escaneamos desde el final para quedarnos con el frame "Digest:" más reciente.
+      def extract_digest(frames)
+        frames.reverse_each do |frame|
+          match = DIGEST_STATUS.match(frame["status"].to_s)
+          return match[1] if match
+        end
+        nil
+      end
+    end
   end
 end

data/lib/docker_swarm/registry_auth.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module DockerSwarm
+  # Traduce las opciones de autenticación de registry privado a los canales de
+  # transporte de la Docker Engine API, sin tocar el payload ni el estado del modelo:
+  #
+  # - +registry_auth+      -> header +X-Registry-Auth+ (credencial opaca base64url).
+  # - +registry_auth_from+ -> query +registryAuthFrom+ (+spec+ | +previous-spec+),
+  #   fuente de credencial a reusar en un update cuando el header NO está presente.
+  #
+  # Son mutuamente excluyentes: Docker define +registryAuthFrom+ como la fuente a usar
+  # solo si +X-Registry-Auth+ no viaja. Si el caller pasa ambos, se corta con un error
+  # local claro antes de la request, en vez de derivar la ambigüedad al Engine.
+  #
+  # @see https://docs.docker.com/engine/api/v1.41/#tag/Service/operation/ServiceUpdate
+  module RegistryAuth
+    HEADER = "X-Registry-Auth"
+    QUERY = :registryAuthFrom
+    FROM_VALUES = %w[spec previous-spec].freeze
+
+    module_function
+
+    # @param registry_auth [String, nil] credencial opaca para el header X-Registry-Auth
+    # @param registry_auth_from [String, nil] "spec" | "previous-spec"; excluyente con registry_auth
+    # @return [Array(Hash, Hash)] par [headers, query_params] a mergear en la request
+    #   (cada uno vacío cuando su opción no vino)
+    # @raise [ArgumentError] si vienen ambos juntos o si registry_auth_from es inválido
+    def resolve(registry_auth: nil, registry_auth_from: nil)
+      validate!(registry_auth, registry_auth_from)
+
+      headers = registry_auth ? { HEADER => registry_auth } : {}
+      query = registry_auth_from ? { QUERY => registry_auth_from } : {}
+
+      [ headers, query ]
+    end
+
+    def validate!(registry_auth, registry_auth_from)
+      if registry_auth && registry_auth_from
+        raise ArgumentError, "registry_auth y registry_auth_from son mutuamente excluyentes: pasá uno u otro"
+      end
+
+      return if registry_auth_from.nil? || FROM_VALUES.include?(registry_auth_from)
+
+      raise ArgumentError,
+            "registry_auth_from inválido: #{registry_auth_from.inspect} (válidos: #{FROM_VALUES.join(', ')})"
+    end
+  end
+end

data/lib/docker_swarm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DockerSwarm
-  VERSION = "0.7.1"
+  VERSION = "0.8.0"
 end