docker-swarm 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78ad878518bedd7c1ac7355efbb6372b49f2721fd7db5a3b0536b0872ed9f3ea
-  data.tar.gz: 6a5b9b06a1c43e8735d111cda5e9eb65820101fe515832fdf64647834310ad12
+  metadata.gz: a5c66a1153f6aa54787f22d1281e4b8d1932a951f70000ff0a3af72e79c9be7b
+  data.tar.gz: 6469d6833f97509511d0bfffda44bbbdc650fa1c928d624efef79b5ba71221ef
 SHA512:
-  metadata.gz: 762b554eb9e1321d1cb2cb82867809b816ba7e7a84ee55e1e34b571b0942aba9e13020d8b7019dc40c70d4457b3307f9d72ca5cc98cd5de26207c9bf9ce70c1b
-  data.tar.gz: e092c1f28b3de38986f3f5e207dd1aafeac8449448e861675aa0be88ee4763f71aa663fc9ee8c1b3bafcfe1997b3917a0924ca9dea777b484b5163bd4b197d45
+  metadata.gz: bc5f0fa14f81cf2d9da225c586458a155e8ac1042d5bc3d190b17a2f4c151d1239f2dd6046e1aa078d15ddea59a322476cdce5827945f8ad74a9fdd9030d79a5
+  data.tar.gz: 3bd4011e41f199280010a1cb716735ef72ba54926c33c36425fb483b75611821a0ce12b07b0c731b88e0bfc63f7cfe66e84fe99c42b60c8f1ecf2745ed86feac

data/README.md

@@ -5,54 +5,135 @@
 
 `docker-swarm` es un ORM ligero y cliente API robusto para interactuar con Docker Swarm desde Ruby. Diseñado para sentirse familiar a los desarrolladores de Rails, utiliza `ActiveModel` para ofrecer una interfaz limpia y potente con estándares de observabilidad de Wispro.
 
-## 🚀 Inicio Rápido
+## Instalacion
+
+Agrega la gema a tu `Gemfile`:
+
+```ruby
+gem 'docker-swarm', '~> 0.5'
+```
+
+Y ejecuta:
+
+```bash
+bundle install
+```
+
+## Quick Start
 
 ```ruby
 require 'docker_swarm'
 
-# Configurar (opcional, usa defaults)
+# Configurar (opcional, usa defaults razonables)
 DockerSwarm.configure do |config|
   config.socket_path = "unix:///var/run/docker.sock"
-  config.log_level = Logger::INFO
-  config.read_timeout = 30
+  config.log_level   = Logger::INFO
   config.max_retries = 3
 end
 
-# Listar servicios (con soporte para Indifferent Access en arrays)
+# Verificar conectividad
+DockerSwarm::System.up  # => "OK"
+
+# Listar servicios
 services = DockerSwarm::Service.all
 services.each { |s| puts "#{s.ID}: #{s.Spec[:Name]}" }
+```
+
+## Uso
 
-# Crear un nuevo servicio
+### Crear un servicio
+
+```ruby
 service = DockerSwarm::Service.create(
   Name: "my-webapp",
-  Spec: {
-    TaskTemplate: {
-      ContainerSpec: { Image: "nginx:latest" }
-    }
+  TaskTemplate: {
+    ContainerSpec: { Image: "nginx:latest" }
   }
 )
+puts service.ID
+```
 
-# Obtener logs (stdout y stderr habilitados por defecto)
-puts service.logs
+### Actualizar (maneja Version.Index automaticamente)
+
+```ruby
+service = DockerSwarm::Service.find("svc-id")
+service.update(Mode: { Replicated: { Replicas: 3 } })
 ```
 
-## 🛠 Características Clave
+### Eliminar
+
+```ruby
+service.destroy  # graceful: retorna nil si ya no existe
+```
+
+### Logs
+
+```ruby
+puts service.logs(stdout: 1, stderr: 1)
+```
+
+### Filtros
+
+```ruby
+DockerSwarm::Service.all(label: ["env=production"])
+DockerSwarm::Node.all(role: ["manager"])
+DockerSwarm::Container.all(status: ["running"])
+```
+
+### Sistema y Cluster
+
+```ruby
+DockerSwarm::System.info     # informacion del daemon
+DockerSwarm::System.version  # version de Docker
+DockerSwarm::System.df       # uso de disco
+DockerSwarm::Swarm.show      # informacion del cluster
+```
+
+### Manejo de errores
+
+```ruby
+begin
+  DockerSwarm::Service.create(Name: "web", TaskTemplate: { ... })
+rescue DockerSwarm::Conflict => e
+  puts "Nombre duplicado"
+rescue DockerSwarm::Communication => e
+  puts "Docker inalcanzable: #{e.message}"
+end
+```
+
+## Configuracion
+
+```ruby
+DockerSwarm.configure do |config|
+  config.socket_path     = "unix:///var/run/docker.sock"  # o http://host:port
+  config.logger          = Logger.new($stdout)
+  config.log_level       = Logger::INFO
+  config.read_timeout    = 60    # segundos
+  config.write_timeout   = 60
+  config.connect_timeout = 10
+  config.max_retries     = 3
+end
+```
+
+Ver [Guia de Configuracion](docs/configuration.md) para opciones avanzadas, Rails integration y observabilidad.
+
+## Documentacion
 
-- **Observabilidad Wispro**: Logging estructurado (KV) con `component`, `event`, `source` y `duration_ms` usando reloj monotónico.
-- **Seguridad**: Enmascaramiento automático de secretos (`password`, `token`, etc.) en los logs.
-- **Deep Indifferent Access**: Acceso a atributos mediante símbolos o strings, incluso en resultados de listados (`.all`).
-- **Resiliencia**: Gestión inteligente de timeouts (`read`, `write`, `connect`) y reintentos automáticos para errores de red.
-- **Mapeo PascalCase**: Mantiene la fidelidad con los atributos de Docker (e.g., `s.ID`, `s.Spec`) evitando transformaciones costosas.
-- **ActiveModel Ready**: Soporta validaciones, serialización JSON y comportamientos estándar de modelos Ruby.
+- [Modelos (ORM)](docs/models.md) — Todos los modelos, concerns y ciclo de vida
+- [Configuracion](docs/configuration.md) — Opciones, observabilidad y seguridad
+- [Manejo de Errores](docs/errors.md) — Jerarquia de excepciones y uso
+- [Cliente API](docs/api.md) — Acceso de bajo nivel y middlewares
+- [Testing](docs/testing.md) — Estrategias de mocking para tus tests
 
-## 🤝 Contribuir
+## Contribuir
 
-Las contribuciones son bienvenidas. Por favor, lee `CLAUDE.md` para las guías de desarrollo y asegúrate de que todos los tests pasen antes de enviar un PR.
+Las contribuciones son bienvenidas. Por favor, lee `CLAUDE.md` para las guias de desarrollo.
 
 ```bash
-bundle exec rspec
+bundle exec rspec       # tests
+bundle exec rubocop -a  # linting
 ```
 
-## 📄 Licencia
+## Licencia
 
-Este proyecto está bajo la licencia MIT.
+Este proyecto esta bajo la licencia MIT.

data/lib/docker_swarm/log_helper.rb

@@ -3,7 +3,7 @@
 module DockerSwarm
   # Helper module to centralize logging logic and formatting
   module LogHelper
-    SENSITIVE_KEYS = /password|token|api_key|auth|secret/i.freeze
+    SENSITIVE_KEYS = /password|token|api_key|auth|secret|data/i.freeze
 
     # Formats a hash into a KV structured string with sensitive data masking
     # @param payload [Hash] The data to format

data/lib/docker_swarm/version.rb

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

data/skill/SKILL.md

@@ -0,0 +1,227 @@
+# DockerSwarm Expert
+
+Skill de conocimiento completo sobre DockerSwarm. Consultame para cualquier pregunta sobre integración, arquitectura, API, errores y antipatrones.
+
+## Glosario
+
+**Base** — Clase ORM base que hereda de ActiveModel::Model. Provee accessors dinámicos PascalCase, `find`, `all`, `where`, `reload`, `payload_for_docker`. Todos los modelos heredan de ella.
+
+**Concern** — Mixin ActiveSupport::Concern que agrega comportamiento CRUD a un modelo: Creatable (POST), Updatable (POST con Version.Index), Deletable (DELETE), Loggable (logs streaming), Inspectable (#inspect legible).
+
+**Middleware** — Capa Excon que procesa request/response: RequestEncoder (serialización body), ResponseJSONParser (parsing + indifferent access), ErrorHandler (status HTTP → excepción).
+
+**Deep Indifferent Access** — Toda respuesta JSON se convierte recursivamente a `HashWithIndifferentAccess`, permitiendo acceso por symbol o string en cualquier nivel de anidamiento.
+
+**Dynamic Accessor** — Cuando Docker devuelve un atributo nuevo (ej: `Spec`, `Status`), Base crea `attr_accessor` dinámicamente via `method_missing`. Se cachea en `defined_attributes` (Set) para no redefinir.
+
+**Version.Index** — Mecanismo de Docker para updates atómicos. Updatable extrae `Version["Index"]` y lo envía como query param para evitar race conditions.
+
+**LogHelper** — Módulo que formatea logs en KV (`key=value`) y enmascara campos sensibles matching `/password|token|api_key|auth|secret|data/i` → `[FILTERED]`.
+
+## Arquitectura
+
+### Responsabilidad core
+
+ORM ligero compatible con ActiveModel para Docker Engine API. Comunica via Excon sobre Unix socket (default) o TCP. Todos los requests pasan por una cadena de middlewares.
+
+### Mapa de componentes
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│   Modelo     │────>│   Api        │────>│  Connection   │
+│  (Service,   │     │  (ENDPOINTS  │     │  (Excon +     │
+│   Node...)   │     │   + request) │     │   Timeouts)   │
+└──────────────┘     └──────────────┘     └──────────────┘
+                                                │
+                                                ▼
+                                    ┌───────────────────────┐
+                                    │   Middleware Stack     │
+                                    │  RequestEncoder       │
+                                    │  ResponseJSONParser   │
+                                    │  ErrorHandler         │
+                                    └───────────────────────┘
+```
+
+### Flujo en runtime
+
+1. Modelo invoca `Api.request(action:, arguments:, query_params:, payload:)`.
+2. Api formatea el path con `format()` y delega a `DockerSwarm.request`.
+3. Connection crea/reutiliza cliente Excon singleton con middlewares.
+4. RequestEncoder serializa body (JSON default, form-urlencoded, multipart).
+5. Excon envía al Docker daemon (socket o TCP).
+6. ResponseJSONParser parsea JSON y aplica `with_indifferent_access` recursivo.
+7. ErrorHandler mapea status 4xx/5xx a excepciones tipadas.
+8. Connection mide duración con `CLOCK_MONOTONIC` y loguea en KV.
+
+### Decisiones de diseño
+
+- **PascalCase fiel**: Los atributos mantienen el naming de Docker (`Spec`, `TaskTemplate`, `ContainerSpec`). No se transforman a snake_case.
+- **Spec merging**: `assign_attributes` hace `deep_merge` cuando el atributo es `Spec` para no perder campos anidados en updates.
+- **Singleton connection**: `@client ||= Excon.new(...)` — se reutiliza, se resetea al cambiar configuración.
+- **Retries en Excon**: `idempotent: true` + `retry_errors: [Socket, Timeout]` con `max_retries` configurable.
+
+## API Pública (resumen)
+
+### Configuración
+
+```ruby
+DockerSwarm.configure do |config|
+  config.socket_path     = "unix:///var/run/docker.sock"  # o http://host:port
+  config.logger          = Logger.new($stdout)
+  config.log_level       = Logger::INFO
+  config.read_timeout    = 60.0    # segundos
+  config.write_timeout   = 60.0
+  config.connect_timeout = 10.0
+  config.max_retries     = 3
+end
+```
+
+### Operaciones comunes
+
+```ruby
+# Listar
+DockerSwarm::Service.all
+DockerSwarm::Service.all(label: ["app=web"])
+
+# Buscar
+service = DockerSwarm::Service.find("service_id")  # nil si no existe
+
+# Crear
+svc = DockerSwarm::Service.create(Name: "web", TaskTemplate: { ... })
+
+# Actualizar (maneja Version.Index automáticamente)
+service.update(Spec: { Replicas: 3 })
+
+# Eliminar (graceful con 404)
+service.destroy
+
+# Logs
+service.logs(stdout: 1, stderr: 1)
+
+# Sistema
+DockerSwarm::System.up       # ping
+DockerSwarm::System.info     # daemon info
+DockerSwarm::System.version  # versión Docker
+DockerSwarm::System.df       # disk usage
+DockerSwarm::Swarm.show      # info del cluster
+```
+
+Ver [API Detallada](references/api-detallada.md) para la referencia completa de todos los modelos.
+
+## FAQ
+
+### Como conecto a un Docker remoto por TCP?
+
+```ruby
+DockerSwarm.configure do |config|
+  config.socket_path = "http://192.168.1.100:2375"
+end
+```
+Connection detecta si empieza con `unix://` (socket) o no (TCP) y configura Excon.
+
+### Por qué los atributos son PascalCase y no snake_case?
+
+Docker Engine API usa PascalCase en todos sus JSON. La gema mantiene fidelidad 1:1 para evitar confusión al leer la documentación de Docker. Se accede igual: `service.Spec`, `node.Status`.
+
+### Como filtro recursos con labels?
+
+```ruby
+DockerSwarm::Service.all(label: ["env=production", "app=web"])
+DockerSwarm::Node.all(role: ["manager"])
+```
+Los filtros se serializan como JSON en el query param `filters` del Docker API.
+
+### Como manejo errores de conexión?
+
+```ruby
+begin
+  DockerSwarm::System.up
+rescue DockerSwarm::Communication => e
+  # Socket caído o inalcanzable
+end
+```
+`Communication` envuelve errores de `Excon::Error::Socket`. Los retries se aplican automáticamente (`max_retries`).
+
+### Puedo usar validaciones de ActiveModel?
+
+Sí. Todos los modelos heredan de `ActiveModel::Model`. Podés agregar validaciones custom:
+
+```ruby
+service = DockerSwarm::Service.new(Name: "")
+service.valid?  # usa validaciones ActiveModel
+service.save    # retorna false si invalid?
+```
+
+## Antipatrones
+
+### Transformar atributos a snake_case
+
+```ruby
+# MAL
+service.task_template["container_spec"]
+
+# BIEN
+service.TaskTemplate["ContainerSpec"]
+```
+**Razón:** Docker API usa PascalCase. La gema mantiene fidelidad. Con indifferent access, podés usar strings o symbols, pero siempre PascalCase.
+
+### Reemplazar Spec en vez de mergear
+
+```ruby
+# MAL — pierde campos existentes del Spec
+service.update(Spec: { Mode: { Replicated: { Replicas: 5 } } })
+
+# BIEN — mergear solo lo que cambia
+service.update(Mode: { Replicated: { Replicas: 5 } })
+```
+**Razón:** `payload_for_docker` extrae contenido de Spec al root. Si pasás Spec completo, `assign_attributes` hace deep_merge, pero es más limpio pasar los campos directamente.
+
+### Ignorar Version.Index en updates
+
+```ruby
+# MAL — update manual sin version
+DockerSwarm.request(method: :post, path: "services/#{id}/update", body: payload)
+
+# BIEN — usar el modelo, maneja version automáticamente
+service.update(new_attrs)
+```
+**Razón:** Docker requiere `version` query param para updates atómicos. Updatable lo extrae de `self.Version["Index"]` automáticamente.
+
+### No capturar errores específicos
+
+```ruby
+# MAL
+begin
+  service.destroy
+rescue StandardError
+  # tragarse todo
+end
+
+# BIEN
+begin
+  service.destroy
+rescue DockerSwarm::NotFound
+  # ya fue eliminado, ok
+rescue DockerSwarm::Conflict => e
+  # servicio en uso
+end
+```
+**Razón:** La jerarquía de errores mapea cada status HTTP. Capturar errores específicos permite manejar cada caso.
+
+## Errores
+
+Los errores más comunes. Ver [Catálogo de Errores](references/errores.md) para la referencia completa.
+
+| Excepción | Status | Causa típica |
+|-----------|--------|--------------|
+| `NotFound` | 404 | Recurso eliminado o ID incorrecto |
+| `Conflict` | 409 | Nombre duplicado o recurso en uso |
+| `Communication` | — | Socket caído o inalcanzable |
+| `ServiceUnavailable` | 503 | Docker daemon reiniciando |
+
+Todas heredan de `DockerSwarm::Error`. Se acceden como `DockerSwarm::NotFound` (alias) o `DockerSwarm::Error::NotFound`.
+
+## Referencias
+
+- [API Detallada](references/api-detallada.md) — Referencia completa de modelos, concerns y métodos
+- [Catálogo de Errores](references/errores.md) — Todas las excepciones con causa y resolución

data/skill/references/api-detallada.md

@@ -0,0 +1,246 @@
+# API Detallada
+
+Referencia completa de modelos, concerns, middleware y métodos públicos de DockerSwarm.
+
+## Modelos — Tabla de capacidades
+
+| Modelo | Creatable | Updatable | Deletable | Loggable | Extra |
+|--------|-----------|-----------|-----------|----------|-------|
+| Service | x | x | x | x | Ciclo de vida completo |
+| Node | | x | x | | Miembros del cluster, no se crean |
+| Task | | | | x | Read-only, generados por services |
+| Container | | | x | x | `#start`, `#stop` |
+| Network | x | x | x | | CRUD completo |
+| Volume | x | | x | | `root_key = "Volumes"` |
+| Config | x | | x | | Configuración del cluster |
+| Secret | x | | x | | Datos sensibles |
+| Image | x | | x | | Pull/removal |
+| Swarm | | | | | `.show` (estático) |
+| System | | | | | `.info`, `.version`, `.up`, `.df` |
+
+## Base — Métodos de clase
+
+```ruby
+# Listar todos (con filtros opcionales)
+# @param filters [Hash] Filtros Docker (label:, name:, id:, role:, etc.)
+# @return [Array<Model>]
+Model.all(filters = {})
+
+# Alias de .all
+Model.where(filters)
+
+# Buscar por ID (retorna nil si 404)
+# @param id [String]
+# @return [Model, nil]
+Model.find(id)
+
+# Nombre del recurso pluralizado (ej: "services", "nodes")
+Model.resource_name
+
+# Endpoints del modelo desde Api::ENDPOINTS
+Model.routes
+```
+
+### Filtros soportados
+
+```ruby
+# Filtros Docker se serializan como JSON en query param `filters`
+DockerSwarm::Service.all(label: ["app=web"], name: ["my-service"])
+DockerSwarm::Container.all(status: ["running"])
+DockerSwarm::Node.all(role: ["manager"])
+
+# Parámetros globales (no van en filters)
+DockerSwarm::Image.all(all: true)         # incluir intermedias
+DockerSwarm::Container.all(limit: 10)     # limitar resultados
+```
+
+## Base — Métodos de instancia
+
+```ruby
+# ID del recurso
+# @return [String]
+model.id
+
+# Hash de atributos (excluye internos de ActiveModel)
+# @return [Hash]
+model.attributes
+
+# Recarga desde Docker API
+# @return [self]
+model.reload
+
+# Prepara payload para Docker (excluye ID, Version, CreatedAt, extrae Spec)
+# @return [Hash]
+model.payload_for_docker
+
+# Persistido? (tiene ID)
+# @return [Boolean]
+model.persisted?
+
+# Inspección legible: #<DockerSwarm::Service ID: abc, Name: web, Image: nginx>
+model.inspect
+
+# Serialización
+model.as_json
+model.serializable_hash
+```
+
+## Concern: Creatable
+
+Incluido en: Service, Network, Volume, Config, Secret, Image.
+
+```ruby
+# Crear y persistir
+# @param attributes [Hash] Atributos PascalCase
+# @return [Model] instancia (con ID si exitoso)
+Model.create(attributes)
+
+# Persistir instancia nueva (o delegar a update si persisted?)
+# @return [Boolean] false si validación falla
+model.save
+```
+
+Flujo interno de `save`: `valid?` → `Api.request(:create, payload_for_docker)` → asigna ID de response → `reload`.
+
+## Concern: Updatable
+
+Incluido en: Service, Node, Network.
+
+```ruby
+# Actualizar recurso persistido
+# @param new_attributes [Hash] Atributos a mergear
+# @return [Boolean] false si validación falla
+model.update(new_attributes = {})
+```
+
+Flujo interno: `assign_attributes` (deep_merge en Spec) → `valid?` → `Api.request(:update, id:, version: Version["Index"], payload:)`.
+
+**Importante:** El query param `version` se extrae automáticamente de `self.Version["Index"]`. Sin esto, Docker rechaza el update con 500.
+
+## Concern: Deletable
+
+Incluido en: Service, Node, Container, Network, Volume, Config, Secret, Image.
+
+```ruby
+# Eliminar por instancia
+# @return [true, nil] nil si ya no existía (404 graceful)
+model.destroy
+
+# Eliminar por ID (class method)
+# @return [true, nil]
+Model.destroy(id)
+```
+
+## Concern: Loggable
+
+Incluido en: Service, Task, Container.
+
+```ruby
+# Obtener logs del recurso
+# @param query_params [Hash] stdout:, stderr:, follow:, tail:, since:, timestamps:
+# @return [String] Raw log stream
+model.logs(query_params = { stdout: 1, stderr: 1 })
+```
+
+## Container — Métodos específicos
+
+```ruby
+container = DockerSwarm::Container.find("container_id")
+
+# Iniciar contenedor detenido
+# @return [Boolean]
+container.start
+
+# Detener contenedor en ejecución
+# @return [Boolean]
+container.stop
+```
+
+## System — Métodos estáticos
+
+```ruby
+# Ping al daemon
+# @return [String] "OK"
+DockerSwarm::System.up
+
+# Información del daemon
+# @return [Hash] (Containers, Images, Driver, MemoryLimit, etc.)
+DockerSwarm::System.info
+
+# Versión de Docker
+# @return [Hash] (Version, ApiVersion, Os, Arch, etc.)
+DockerSwarm::System.version
+
+# Uso de disco
+# @return [Hash] (LayersSize, Images, Containers, Volumes)
+DockerSwarm::System.df
+```
+
+## Swarm — Método estático
+
+```ruby
+# Información del cluster Swarm
+# @return [Hash] (ID, Version, Spec, JoinTokens, etc.)
+DockerSwarm::Swarm.show
+```
+
+## Volume — Particularidad
+
+Volume sobreescribe `root_key` porque Docker envuelve la respuesta en `{"Volumes": [...]}`:
+
+```ruby
+class Volume < Base
+  def self.root_key = "Volumes"
+end
+```
+
+## Api — Bajo nivel
+
+```ruby
+# Request directo al Docker API
+# @param action [Hash] {method:, path:} desde ENDPOINTS
+# @param arguments [Hash] Interpolación en path (id:)
+# @param query_params [Hash] Query string
+# @param payload [Hash, nil] Body del request
+DockerSwarm::Api.request(action:, arguments: {}, query_params: {}, payload: nil)
+```
+
+### Endpoints registrados
+
+Todos definidos en `Api::ENDPOINTS` como Hash frozen:
+
+| Recurso | Acciones |
+|---------|----------|
+| swarm | show |
+| system | info, version, up, df |
+| nodes | index, show, update, destroy |
+| tasks | index, show, logs |
+| services | index, show, create, update, destroy, logs |
+| configs | index, show, create, destroy |
+| secrets | index, show, create, destroy |
+| networks | index, show, create, update, destroy |
+| volumes | index, show, create, destroy |
+| containers | index, show, create, start, stop, destroy, logs |
+| images | index, show, create, destroy |
+
+## Middleware Stack
+
+Orden de ejecución en Excon:
+
+1. **Excon defaults** (Retry, Instrumentor, etc.)
+2. **Excon::Middleware::RedirectFollower**
+3. **RequestEncoder** — Serializa body: JSON (default), form-urlencoded, multipart. Detecta por Content-Type header.
+4. **ResponseJSONParser** — Parsea JSON si Content-Type incluye `application/json`. Aplica `with_indifferent_access` recursivo (Hash y Array de Hashes).
+5. **ErrorHandler** — Status 4xx/5xx → excepción tipada. Loguea `business_error` antes de raise.
+
+## Configuración
+
+| Opción | Tipo | Default | Descripción |
+|--------|------|---------|-------------|
+| `socket_path` | String | `unix:///var/run/docker.sock` | Socket Unix o URL TCP |
+| `logger` | Logger | `Logger.new($stdout)` | Logger para KV output |
+| `log_level` | Integer | `Logger::INFO` | Nivel de log (se aplica al logger) |
+| `read_timeout` | Float | `60.0` | Timeout lectura (segundos) |
+| `write_timeout` | Float | `60.0` | Timeout escritura (segundos) |
+| `connect_timeout` | Float | `10.0` | Timeout conexión (segundos) |
+| `max_retries` | Integer | `3` | Reintentos en Socket/Timeout errors |

data/skill/references/errores.md

@@ -0,0 +1,157 @@
+# Catálogo de Errores
+
+Referencia completa de excepciones de DockerSwarm. Todas heredan de `DockerSwarm::Error`.
+
+## Jerarquía
+
+```
+DockerSwarm::Error (base)
+├── BadRequest (400)
+├── Unauthorized (401)
+├── Forbidden (403)
+├── NotFound (404)
+├── NotAcceptable (406)
+├── RequestTimeout (408)
+├── Conflict (409)
+├── UnprocessableEntity (422)
+├── TooManyRequests (429)
+├── InternalServerError (500)
+├── BadGateway (502)
+├── ServiceUnavailable (503)
+├── GatewayTimeout (504)
+└── Communication (socket/red)
+```
+
+## Acceso
+
+Cada excepción tiene 3 formas de acceso equivalentes:
+
+```ruby
+DockerSwarm::NotFound              # alias directo (recomendado)
+DockerSwarm::Error::NotFound       # acceso via clase Error
+DockerSwarm::Errors::NotFound      # módulo Errors (const_missing dinámico)
+```
+
+## Catálogo completo
+
+### BadRequest (400)
+
+**Causa:** Payload malformado o parámetros inválidos.
+**Reproducción:** Enviar JSON con campos incorrectos (ej: `Replicas: "abc"` en vez de integer).
+**Resolución:** Validar payload contra la documentación de Docker API. Verificar tipos de datos.
+
+### Unauthorized (401)
+
+**Causa:** Credenciales inválidas o ausentes para Docker daemon con TLS.
+**Reproducción:** Conectar a daemon protegido sin certificados.
+**Resolución:** Configurar TLS client certificates en Excon o en la URL de conexión.
+
+### Forbidden (403)
+
+**Causa:** Permisos insuficientes para la operación.
+**Reproducción:** Intentar operación de swarm en un nodo worker.
+**Resolución:** Verificar que el nodo es manager y que el usuario tiene permisos sobre el socket.
+
+### NotFound (404)
+
+**Causa:** Recurso no existe o fue eliminado.
+**Reproducción:** `Service.find("id_inexistente")`.
+**Resolución:** `Base.find` retorna `nil` automáticamente. `Deletable#destroy` también es graceful (retorna `nil` en 404). No requiere rescue manual en estos casos.
+
+### NotAcceptable (406)
+
+**Causa:** El servidor no puede producir una respuesta aceptable.
+**Reproducción:** Raro en Docker API.
+**Resolución:** Verificar headers Accept del request.
+
+### RequestTimeout (408)
+
+**Causa:** Docker daemon tardó demasiado en responder.
+**Reproducción:** Operación en un cluster sobrecargado.
+**Resolución:** Incrementar `read_timeout` en configuración. Verificar estado del cluster.
+
+### Conflict (409)
+
+**Causa:** Nombre duplicado, recurso en uso, o versión desactualizada.
+**Reproducción:** `Service.create(Name: "nombre_existente")` o update con `Version.Index` stale.
+**Resolución:** Para nombres: verificar existencia antes de crear. Para versiones: hacer `reload` y reintentar el update.
+
+### UnprocessableEntity (422)
+
+**Causa:** Payload semánticamente inválido.
+**Reproducción:** Crear servicio con imagen inexistente y restricciones de scheduling imposibles.
+**Resolución:** Verificar que la imagen existe y que las constraints del servicio son alcanzables.
+
+### TooManyRequests (429)
+
+**Causa:** Rate limiting del Docker daemon o registry.
+**Reproducción:** Burst de requests al API.
+**Resolución:** Implementar backoff. Los retries de Excon cubren errores de socket/timeout pero no 429.
+
+### InternalServerError (500)
+
+**Causa:** Error interno del Docker daemon.
+**Reproducción:** Bug en Docker, operación sobre estado inconsistente, o update sin `version` query param.
+**Resolución:** Verificar logs del Docker daemon (`journalctl -u docker`). Si es por version faltante, usar el modelo (Updatable lo maneja).
+
+### BadGateway (502)
+
+**Causa:** Proxy o load balancer entre cliente y daemon devuelve error.
+**Reproducción:** Docker daemon detrás de reverse proxy caído.
+**Resolución:** Verificar infraestructura de red y proxy.
+
+### ServiceUnavailable (503)
+
+**Causa:** Docker daemon reiniciando o en mantenimiento.
+**Reproducción:** Request durante restart del servicio Docker.
+**Resolución:** Reintentar después de esperar. `max_retries` cubre errores de socket pero no 503.
+
+### GatewayTimeout (504)
+
+**Causa:** Proxy entre cliente y daemon timeout.
+**Reproducción:** Operación larga detrás de proxy con timeout corto.
+**Resolución:** Incrementar timeout del proxy. Verificar que `read_timeout` de la gema es menor que el del proxy.
+
+### Communication
+
+**Causa:** Error de socket o red — daemon caído, socket inexistente, permisos insuficientes.
+**Reproducción:** `DockerSwarm::System.up` con daemon apagado.
+**Resolución:** Verificar que Docker está corriendo (`systemctl status docker`), que el socket existe y que el usuario tiene permisos de lectura.
+
+## Manejo recomendado
+
+```ruby
+begin
+  DockerSwarm::Service.create(Name: "web", TaskTemplate: { ... })
+rescue DockerSwarm::Conflict => e
+  # Nombre duplicado — buscar existente
+  existing = DockerSwarm::Service.all(name: ["web"]).first
+rescue DockerSwarm::Communication => e
+  # Docker caído
+  logger.error("Docker unreachable: #{e.message}")
+rescue DockerSwarm::Error => e
+  # Cualquier otro error de Docker
+  logger.error("Docker error: #{e.class} #{e.message}")
+end
+```
+
+## Logging automático
+
+El middleware ErrorHandler loguea automáticamente antes de raise:
+
+```
+component=docker_swarm.middleware.error_handler event=business_error source=http status=409 message="name conflicts" method=post path=/services/create
+```
+
+Formato KV con masking de datos sensibles via LogHelper.
+
+## Causa original (Excon wrapping)
+
+Excon puede envolver excepciones del middleware en `Excon::Error::Socket`. Connection detecta esto y re-raise la excepción original:
+
+```ruby
+# Connection#request internamente:
+actual_error = e.cause&.class&.name&.include?("DockerSwarm::Error") ? e.cause : e
+```
+
+La excepción original mantiene la causa via `Exception#cause` de Ruby para trazabilidad completa.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: docker-swarm
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Gabriel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -117,6 +117,9 @@ files:
 - lib/docker_swarm/models/task.rb
 - lib/docker_swarm/models/volume.rb
 - lib/docker_swarm/version.rb
+- skill/SKILL.md
+- skill/references/api-detallada.md
+- skill/references/errores.md
 homepage: https://github.com/wispro/docker-swarm
 licenses:
 - MIT