docker-swarm 0.7.2 → 0.9.0

data/lib/docker_swarm/connection.rb

@@ -96,20 +96,29 @@ module DockerSwarm
       Excon.defaults[:middlewares] + [
         Excon::Middleware::RedirectFollower,
         Middleware::RequestEncoder,
+        Middleware::LogStreamDemuxer,
         Middleware::ResponseJSONParser,
         Middleware::ErrorHandler
       ]
     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 loguea request/response pasando por
+      # {LogHelper.sanitize}, que cubre DOS formas: la clave de hash sensible
+      # (headers anidados) y el `"CLAVE=VALOR"` dentro de un String (el `Env` de
+      # un ContainerSpec, que es un array de strings). Lo que NO cubre —y hay que
+      # tenerlo presente antes de sumar un logueo nuevo— es un secreto embebido
+      # en texto libre sin la forma `CLAVE=VALOR`: ahí el nombre de la clave no
+      # aparece y no hay por dónde reconocerlo.
+      #
+      # 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,72 @@ 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]"
+
+    # Un elemento de `Env` de Docker: `"CLAVE=VALOR"`. El `[^=]+` a la izquierda
+    # evita partir en un `=` que pertenezca al valor (los valores base64 y las
+    # URLs los traen), y `/m` cubre un valor multilínea — una clave PEM pasada
+    # por variable de entorno.
+    KV_STRING = /\A([^=]+)=(.+)\z/m
+
+    # Redacta recursivamente los valores sensibles, a cualquier profundidad
+    # (hashes y arrays anidados). No muta la entrada: devuelve copias.
+    #
+    # Cubre DOS formas, porque el nombre de un secreto no siempre es una clave
+    # de hash:
+    #
+    # 1. **Clave de hash sensible** — `headers: { "X-Registry-Auth" => "<cred>" }`.
+    #    Un header sensible puede viajar anidado, y el match por clave de primer
+    #    nivel no lo alcanzaba: el hash interno se interpolaba entero.
+    # 2. **`"CLAVE=VALOR"` dentro de un String** — el `Env` de un `ContainerSpec`
+    #    es un ARRAY DE STRINGS, así que el nombre del secreto vive dentro del
+    #    elemento y no como clave. Sin esto, `Env` no matchea {SENSITIVE_KEYS},
+    #    sus elementos caen al `else`, y **el valor de todo secreto pasado por
+    #    variable de entorno se loguea entero** — en `request_success`, o sea en
+    #    el camino feliz, a nivel INFO.
+    #
+    # @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) }
+      when String
+        redact_kv_string(value)
+      else
+        value
+      end
+    end
+
+    # Redacta el VALOR de un String con forma `"CLAVE=VALOR"` cuando la clave es
+    # sensible, conservando el nombre: saber QUÉ secreto apareció es diagnóstico
+    # útil, su valor no.
+    #
+    # Un String que no tiene esa forma —o cuya clave no es sensible— vuelve tal
+    # cual, así que `"RAILS_LOG_LEVEL=info"` y cualquier mensaje de error quedan
+    # intactos.
+    #
+    # @param str [String]
+    # @return [String] con el valor reemplazado por {FILTERED}, o el original
+    def self.redact_kv_string(str)
+      match = KV_STRING.match(str)
+      return str unless match && match[1].match?(SENSITIVE_KEYS)
+
+      "#{match[1]}=#{FILTERED}"
+    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/middleware/log_stream_demuxer.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module DockerSwarm
+  module Middleware
+    # Demultiplexa el stream de logs del Engine para que +Concerns::Loggable#logs+
+    # devuelva texto limpio en +Container+, +Service+ y +Task+.
+    #
+    # Sin TTY el Engine enmarca cada fragmento con 8 bytes de cabecera: 1 de tipo de
+    # stream, 3 de relleno en cero y 4 de tamaño en big-endian. Ese framing tiene que
+    # morir en un middleware y no en +Loggable+: +Connection#request+ devuelve
+    # +response.body+ y descarta los headers, así que aguas abajo ya no queda
+    # +Content-Type+ con el que decidir. Ver ADR-025 cláusula 3.
+    #
+    # @see https://docs.docker.com/engine/api/v1.41/#tag/Container/operation/ContainerAttach
+    class LogStreamDemuxer < Excon::Middleware::Base
+      # Content-Type que **afirma** el framing. Existe desde la API v1.42.
+      MULTIPLEXED_CONTENT_TYPE = "application/vnd.docker.multiplexed-stream"
+      # Content-Type ambiguo: con TTY no hay framing, pero antes de v1.42 era el único
+      # que existía y también viajaba en streams multiplexados.
+      RAW_CONTENT_TYPE = "application/vnd.docker.raw-stream"
+
+      # Tamaño de la cabecera de frame, en bytes.
+      HEADER_SIZE = 8
+      # Valores válidos del byte 0: stdin, stdout, stderr.
+      STREAM_TYPES = [ 0, 1, 2 ].freeze
+
+      def response_call(env)
+        demux!(env) if env[:response]
+
+        @stack.response_call(env)
+      end
+
+      private
+
+      def demux!(env)
+        body = env[:response][:body]
+        return unless body.is_a?(String)
+        return if body.empty?
+
+        content_type = (env[:response][:headers] || {})["Content-Type"]
+        return if content_type.nil?
+
+        # Sobre +raw-stream+ no alcanza el Content-Type para descartar el framing: la
+        # gema no fija +?version=+ (habla la versión máxima del Engine) y un nodo del
+        # parque puede topar en v1.41, donde un stream multiplexado llega igual con
+        # este Content-Type. Ahí decide la forma del frame, no el header.
+        return unless content_type.include?(MULTIPLEXED_CONTENT_TYPE) ||
+                      content_type.include?(RAW_CONTENT_TYPE)
+
+        demuxed = demux(body)
+        env[:response][:body] = demuxed unless demuxed.nil?
+      end
+
+      # Recorre el body entero como cadena de frames y concatena las cargas en orden.
+      #
+      # Es todo-o-nada a propósito: alcanza **una** inconsistencia —tipo de stream fuera
+      # de rango, relleno distinto de cero, un tamaño que se pasa del buffer, una cola
+      # suelta— para devolver +nil+ y dejar el body intacto. Un log de TTY tendría que
+      # ser una cadena perfecta de frames válidos de punta a punta para confundirse.
+      #
+      # @param body [String] el body crudo tal como vino del Engine
+      # @return [String, nil] el texto sin cabeceras, o +nil+ si el body no está enmarcado
+      def demux(body)
+        bytes = body.b
+        size = bytes.bytesize
+        offset = 0
+        out = +""
+
+        while offset < size
+          return nil if size - offset < HEADER_SIZE
+
+          stream_type, pad_a, pad_b, pad_c, length =
+            bytes.byteslice(offset, HEADER_SIZE).unpack("C4N")
+
+          return nil unless STREAM_TYPES.include?(stream_type)
+          return nil unless pad_a.zero? && pad_b.zero? && pad_c.zero?
+
+          offset += HEADER_SIZE
+          return nil if size - offset < length
+
+          out << bytes.byteslice(offset, length)
+          offset += length
+        end
+
+        out.force_encoding(Encoding::UTF_8)
+      end
+    end
+  end
+end

data/lib/docker_swarm/models/container.rb

@@ -4,9 +4,19 @@ module DockerSwarm
   # Represents a Docker Container
   # @see https://docs.docker.com/engine/api/v1.41/#tag/Container
   class Container < Base
+    include Concerns::Creatable
     include Concerns::Deletable
     include Concerns::Loggable
 
+    # +POST /containers/create+ toma el nombre por query string. En el body Docker lo
+    # **descarta en silencio** y responde +201+: el container nace con nombre aleatorio
+    # y la adopción por nombre determinista en un reintento no encuentra nada, así que
+    # el reintento duplica. Ver ADR-025 cláusula 1.
+    # @return [Array<String>]
+    def self.create_query_params
+      %w[name].freeze
+    end
+
     # Starts the container
     # @return [Boolean] true if successful
     def start

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.2"
+  VERSION = "0.9.0"
 end

data/lib/docker_swarm.rb

@@ -40,10 +40,12 @@ require_relative "docker_swarm/log_helper"
 require_relative "docker_swarm/version"
 require_relative "docker_swarm/errors"
 require_relative "docker_swarm/middleware/request_encoder"
+require_relative "docker_swarm/middleware/log_stream_demuxer"
 require_relative "docker_swarm/middleware/response_json_parser"
 require_relative "docker_swarm/middleware/error_handler"
 require_relative "docker_swarm/connection"
 require_relative "docker_swarm/api"
+require_relative "docker_swarm/registry_auth"
 
 # Concerns deben cargarse antes que Base si Base los incluye
 require_relative "docker_swarm/concerns/creatable"

data/skill/SKILL.md

@@ -9,16 +9,19 @@ description: >-
   cuando el caller necesita orquestar Docker desde Ruby — listar/crear/
   actualizar/eliminar recursos del cluster, leer logs de services/tasks/
   containers, hacer health-check del daemon (System.up/info/df), filtrar por
-  labels, o capturar errores tipados de Docker (Conflict/NotFound/
-  Communication). NO activar para builds de imágenes (no implementado), pull
-  con auth de registry privado (no implementado), o flujos que no son
-  Swarm (Docker Compose, raw containers).
+  labels, pullear imágenes (incl. de registries privados vía X-Registry-Auth),
+  o capturar errores tipados de Docker (Conflict/NotFound/Communication).
+  También cubre containers standalone (no Swarm): crear/correr/limpiar un
+  helper container efímero para operar datos on-host. NO activar para builds
+  de imágenes (no implementado) ni para Docker Compose (no parsea
+  `docker-compose.yml`).
 triggers:
   - "DockerSwarm::"
   - "docker-swarm gem"
   - "Docker Engine API desde Ruby"
   - "Service.create / Service.update / Service.restart"
-  - "Container.start / Container.stop"
+  - "Container.create / Container.start / Container.stop"
+  - "helper container efímero"
   - "logs de un servicio Docker"
   - "Version.Index"
 ---
@@ -55,11 +58,11 @@ Defaults son razonables: en local sin TLS, no necesitás bloque `configure`.
 
 | Modelo | Class methods | Instance methods | Notas |
 |---|---|---|---|
-| `Service` | `all(filters)`, `find(id)`, `where(filters)`, `create(attrs)` | `update(attrs)`, `restart`, `destroy`, `logs(query)`, `reload`, `persisted?`, `id` | CRUD completo + force-recreate de tasks |
+| `Service` | `all(filters)`, `find(id)`, `where(filters)`, `create(attrs)` | `update(attrs)`, `restart`, `destroy`, `logs(query)`, `reload`, `persisted?`, `id` | CRUD completo + force-recreate de tasks; `create`/`update` aceptan `registry_auth:` (+ `update`: `registry_auth_from:`) para auth de registry privado |
 | `Node` | `all(filters)`, `find(id)`, `where(filters)` | `update(attrs)`, `destroy` | No `create` (los nodos se unen fuera de la gema) |
 | `Task` | `all(filters)`, `find(id)`, `where(filters)` | `logs(query)`, `reload` | Read-only (generados por orquestador) |
-| `Container` | `all(filters)`, `find(id)`, `where(filters)` | `start`, `stop`, `destroy`, `logs(query)` | **No `create`** (gap conocido, fuera F1) |
-| `Image` | `all(filters)`, `find(id)`, `create(attrs)` | `destroy` | `create` = pull. **No soporta `X-Registry-Auth`** (registries privados con auth no funcionan) |
+| `Container` | `all(filters)`, `find(id)`, `where(filters)`, `create(attrs)` | `start`, `stop`, `destroy`, `logs(query)` | `create` manda `name` por query string (`create_query_params`) — en el body Docker lo descarta en silencio |
+| `Image` | `all(filters)`, `find(id)`, `pull(image_reference, registry_auth:)` | `destroy` | **No `create`** (retirado; `Image` ya no es Creatable). `pull` = pull explícito síncrono → `{status, image_ref, digest?}`; **soporta `X-Registry-Auth`** para registries privados |
 | `Network` | `all(filters)`, `find(id)`, `create(attrs)` | `update(attrs)`, `destroy` | CRUD completo |
 | `Volume` | `all(filters)`, `find(id)`, `create(attrs)` | `destroy` | No `update` (Docker no lo soporta). Respuesta wrapped vía `root_key = "Volumes"` |
 | `Config` | `all(filters)`, `find(id)`, `create(attrs)` | `destroy` | No `update` — recrear |
@@ -95,7 +98,7 @@ service.restart
 # Destroy graceful (nil si 404)
 service.destroy
 
-# Logs raw
+# Logs (ya demultiplexados: sin cabeceras de frame)
 service.logs(stdout: 1, stderr: 1)
 
 # Health check
@@ -130,8 +133,10 @@ Todas heredan de `DockerSwarm::Error`. Tres formas de acceso equivalentes: `Dock
 - **Retries automáticos sólo en métodos seguros** (GET/HEAD/PUT/DELETE/OPTIONS). POST/PATCH **no** reintentan para evitar duplicados — si el socket se cae durante un `create`, el caller decide qué hacer. Ver §3.5 de `docs/behavior/behavior.md`.
 - **`Spec` se mergea con `deep_merge` en updates**, no se reemplaza. Pasale sólo los campos que cambian: `service.update(Mode: {...})`, no `service.update(Spec: {...completo})`.
 - **`assign_attributes` muta antes de validar.** Si `update` falla por `valid?` o por el API, la instancia local quedó mutada. Hacé `reload` si necesitás estado limpio.
-- **`Container.create` no existe** en la gema (gap intencional F1). Si necesitás crear containers standalone, usá `DockerSwarm.request(method: :post, path: "containers/create", ...)` directo.
-- **Pull con registry privado no soportado.** `Image.create` no inyecta header `X-Registry-Auth`. Para registries privados, fallback a `DockerSwarm.request` con headers manuales.
+- **`Container.create` manda el nombre por query string.** Docker **descarta en silencio** un `name:` en el body y responde `201`: el container nace con nombre aleatorio y un reintento duplica en vez de adoptar. La gema lo resuelve sola vía `Container.create_query_params == %w[name]` — pero si armás el request por afuera (`DockerSwarm.request`), el `?name=` es tuyo. Ver ADR-025 cláusula 1 y §3.11 de `docs/behavior/behavior.md`.
+- **`logs` devuelve texto ya demultiplexado.** Sin TTY el Engine enmarca cada fragmento con 8 bytes de cabecera; `Middleware::LogStreamDemuxer` los saca en `Container`, `Service` y `Task`. Dos consecuencias: **`stdout` y `stderr` vienen intercalados** en un solo String (si necesitás un dato puntual, delimitalo en origen desde el `Cmd`), y **un frame partido entre chunks no se reensambla** — el demux es todo-o-nada, así que ante cualquier inconsistencia te devuelve el body intacto en vez de texto a medias. Con `follow: 1` el body no llega completo, así que no esperes demux ahí.
+- **`Image.create` retirado (breaking).** Ya no existe (`Image` dejó de ser Creatable; el `create` estaba roto y sin consumidores). Usá `Image.pull(image_reference, registry_auth:)`.
+- **Auth de registry privado soportado** vía credencial opaca base64url en `registry_auth:` — `Image.pull(ref, registry_auth:)`, `Service.create(..., registry_auth:)` y `Service#update(..., registry_auth:` / `registry_auth_from:)`. Viaja por header `X-Registry-Auth` (o query `registryAuthFrom`: `spec`\|`previous-spec`, excluyentes); la gema no la mintea ni decodifica. Ver flujos 3.9/3.10 de `docs/behavior/behavior.md`.
 - **`destroy` es graceful con 404** (retorna `nil`), no con 409. Si el recurso está en uso, `Conflict` se propaga.
 - **Logs sensibles enmascarados** automáticamente: keys matching `password|pass|passwd|secret|token|api_key|auth|\bdata\b` → `[FILTERED]`. `\bdata\b` evita filtrar `metadata`/`database`.
 
@@ -164,11 +169,18 @@ Logs salen en formato KV (`component=docker_swarm.connection event=request_succe
 
 ## Índice de artefactos
 
+- [`docs/interface/interface.md`](docs/interface/interface.md) — API Ruby pública (11 modelos + `Base` + concerns + `Api`/`Connection`). La tabla de símbolos de arriba es el resumen; el detalle por símbolo acá.
+- [`docs/errors/errors.md`](docs/errors/errors.md) — jerarquía de excepciones + mapeo status HTTP → excepción. La tabla de errores de arriba es el resumen.
+- [`docs/consumed/docker-engine-api.md`](docs/consumed/docker-engine-api.md) — superficie del Docker Engine API consumida (`Api::ENDPOINTS`) + política de retry estructural.
 - [`docs/glossary/glossary.md`](docs/glossary/glossary.md) — definición de términos (primitivas Docker + conceptos internos).
 - [`docs/behavior/behavior.md`](docs/behavior/behavior.md) — secuencias load-bearing (create+reload, update+Version, retry-policy, error-mapping, etc.).
 - [`docs/config/configuracion.md`](docs/config/configuracion.md) — inventario de configuración runtime (7 opciones del bloque `configure`, sin env vars, ninguna secreta). El bloque de arriba es el resumen; shape/defaults/consumidores en el detalle.
+- [`docs/topology/topology.md`](docs/topology/topology.md) — dependencias runtime (3) + grafo de contexto.
+- [`docs/test/testing.md`](docs/test/testing.md) — estructura de la suite RSpec (unit + integration) y comandos de corrida.
+- [`docs/release/release.md`](docs/release/release.md) — canal de publicación (tag `v*` → RubyGems) + deploy/rollback/ambientes.
 - `docs/data/` — `n/a` (gema sin DB).
-- `docs/api/`, `docs/interface/`, `docs/topology/` — F2 declaradas, **no implementadas**. El contrato resumido de arriba reside **transitoriamente** acá (RFC-008 §2 coexistencia transitoria con destino pendiente).
+- `docs/api/` (operaciones), `docs/events/` — `n/a` (la gema no expone superficie HTTP/CLI/eventos propia; su superficie pública es la interfaz Ruby).
+- `docs/security/`, `docs/multi-tenancy/`, `docs/data-lifecycle/` — `n/a` (sin authn/authz propios —la frontera auth-hacia-Docker está en `docs/consumed` §a—; gema stateless sin scope de tenant; sin persistencia/PII/retención).
 
 ## Versionado del contrato
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docker-swarm
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.9.0
 platform: ruby
 authors:
 - Gabriel
@@ -92,7 +92,13 @@ files:
 - README.md
 - docs/behavior/behavior.md
 - docs/config/configuracion.md
+- docs/consumed/docker-engine-api.md
+- docs/errors/errors.md
 - docs/glossary/glossary.md
+- docs/interface/interface.md
+- docs/release/release.md
+- docs/test/testing.md
+- docs/topology/topology.md
 - lib/docker-swarm.rb
 - lib/docker_swarm.rb
 - lib/docker_swarm/api.rb
@@ -107,6 +113,7 @@ files:
 - lib/docker_swarm/errors.rb
 - lib/docker_swarm/log_helper.rb
 - lib/docker_swarm/middleware/error_handler.rb
+- lib/docker_swarm/middleware/log_stream_demuxer.rb
 - lib/docker_swarm/middleware/request_encoder.rb
 - lib/docker_swarm/middleware/response_json_parser.rb
 - lib/docker_swarm/models/config.rb
@@ -120,17 +127,18 @@ files:
 - lib/docker_swarm/models/system.rb
 - lib/docker_swarm/models/task.rb
 - lib/docker_swarm/models/volume.rb
+- lib/docker_swarm/registry_auth.rb
 - lib/docker_swarm/version.rb
 - skill/SKILL.md
-homepage: https://github.com/gedera/docker-swarm
+homepage: https://github.com/sequre/docker-swarm
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/gedera/docker-swarm
-  source_code_uri: https://github.com/gedera/docker-swarm
-  changelog_uri: https://github.com/gedera/docker-swarm/blob/v0.7.2/CHANGELOG.md
-  bug_tracker_uri: https://github.com/gedera/docker-swarm/issues
-  documentation_uri: https://github.com/gedera/docker-swarm/blob/v0.7.2/skill/SKILL.md
+  homepage_uri: https://github.com/sequre/docker-swarm
+  source_code_uri: https://github.com/sequre/docker-swarm
+  changelog_uri: https://github.com/sequre/docker-swarm/blob/v0.9.0/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sequre/docker-swarm/issues
+  documentation_uri: https://github.com/sequre/docker-swarm/blob/v0.9.0/skill/SKILL.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: