docker-swarm 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b46f33638fb88f8c9fca4a85747f67e266525933e4b22d38bb47e2ce1556a552
-  data.tar.gz: b080b742324d91eb1570af605b05539da67284fb76631faae04583f2577edad3
+  metadata.gz: a5c66a1153f6aa54787f22d1281e4b8d1932a951f70000ff0a3af72e79c9be7b
+  data.tar.gz: 6469d6833f97509511d0bfffda44bbbdc650fa1c928d624efef79b5ba71221ef
 SHA512:
-  metadata.gz: 17f03f903b19273e822feb4a389ff9b862d034607f032c3b6112838b1ddf5f38927dabad4001214f6ad9ce6a06f8661939b38fb2fa3dda8a0b1975246da199fa
-  data.tar.gz: 44edbe59ffa431b2cf78735ca138c2fd4c41d0d57dda543509d9de8a417343c525d1a3493d549fa4e2ebfc63948491a2994917df493683c25f8c33e2f795eadf
+  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/base.rb

@@ -3,12 +3,19 @@
 module DockerSwarm
   class Base
     include ActiveModel::Model
+    include Concerns::Inspectable
 
     class << self
       def resource_name
         name.demodulize.downcase.pluralize
       end
 
+      # Cache of attributes already defined for this class
+      # @return [Set]
+      def defined_attributes
+        @defined_attributes ||= Set.new([ :validation_context, :errors, :context_for_validation ])
+      end
+
       def routes
         Api::ENDPOINTS[resource_name.to_sym]
       end
@@ -156,8 +163,10 @@ module DockerSwarm
     private
 
     def _define_dynamic_accessor(key)
-      return if self.class.method_defined?("#{key}=")
+      return if self.class.defined_attributes.include?(key.to_sym)
+
       self.class.send(:attr_accessor, key)
+      self.class.defined_attributes.add(key.to_sym)
     end
 
     def _valid_attribute_name?(name)

data/lib/docker_swarm/concerns/inspectable.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module DockerSwarm
+  module Concerns
+    module Inspectable
+      extend ActiveSupport::Concern
+
+      def inspect
+        inspection = if respond_to?(:ID) && ID.present?
+                       "ID: #{ID}"
+        else
+                       "not persisted"
+        end
+
+        # Intentar añadir el nombre si existe
+        name_attr = attributes["Name"] || (respond_to?(:Name) ? Name : nil)
+        inspection += ", Name: #{name_attr}" if name_attr.present?
+
+        # Intentar añadir la imagen para servicios/contenedores
+        spec = attributes["Spec"] || (respond_to?(:Spec) ? Spec : nil)
+        image = spec&.dig("TaskTemplate", "ContainerSpec", "Image") || attributes["Image"] || (respond_to?(:Image) ? Image : nil)
+        inspection += ", Image: #{image}" if image.present?
+
+        "#<#{self.class.name} #{inspection}>"
+      end
+    end
+  end
+end

data/lib/docker_swarm/concerns/loggable.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module DockerSwarm
+  module Concerns
+    module Loggable
+      extend ActiveSupport::Concern
+
+      # Fetches logs for the resource
+      # @param query_params [Hash] Query parameters for the logs endpoint (stdout, stderr, follow, etc.)
+      # @return [String] The raw log stream
+      def logs(query_params = { stdout: 1, stderr: 1 })
+        Api.request(action: self.class.routes[:logs], arguments: { id: self.ID }, query_params: query_params)
+      end
+    end
+  end
+end

data/lib/docker_swarm/configuration.rb

@@ -4,18 +4,33 @@ require "logger"
 
 module DockerSwarm
   class Configuration
-    attr_accessor :socket_path, :logger, :log_level,
-                  :read_timeout, :write_timeout, :connect_timeout,
-                  :max_retries
+    attr_accessor :socket_path, :logger, :log_level
+    attr_reader :read_timeout, :write_timeout, :connect_timeout, :max_retries
 
     def initialize
       @socket_path = "unix:///var/run/docker.sock"
       @logger = Logger.new($stdout)
       @log_level = Logger::INFO
-      @read_timeout = 60
-      @write_timeout = 60
-      @connect_timeout = 10
+      @read_timeout = 60.0
+      @write_timeout = 60.0
+      @connect_timeout = 10.0
       @max_retries = 3
     end
+
+    def read_timeout=(val)
+      @read_timeout = val&.to_f
+    end
+
+    def write_timeout=(val)
+      @write_timeout = val&.to_f
+    end
+
+    def connect_timeout=(val)
+      @connect_timeout = val&.to_f
+    end
+
+    def max_retries=(val)
+      @max_retries = val&.to_i
+    end
   end
 end

data/lib/docker_swarm/connection.rb

@@ -11,47 +11,43 @@ module DockerSwarm
 
     def request(options = {})
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      
-      log_event("request_started", 
+
+      log_event("request_started",
                 level: :debug,
-                data: { method: options[:method], path: options[:path] })
+                data: options.merge(path: options[:path]))
 
       # Combinar opciones por defecto de la gema con las de la petición
       request_options = {
         idempotent: true,
-        retry_errors: [Excon::Error::Socket, Excon::Error::Timeout],
-        read_timeout: DockerSwarm.configuration.read_timeout,
-        write_timeout: DockerSwarm.configuration.write_timeout,
-        connect_timeout: DockerSwarm.configuration.connect_timeout,
-        retries: DockerSwarm.configuration.max_retries
+        retry_errors: [ Excon::Error::Socket, Excon::Error::Timeout ],
+        read_timeout: DockerSwarm.configuration.read_timeout.to_f,
+        write_timeout: DockerSwarm.configuration.write_timeout.to_f,
+        connect_timeout: DockerSwarm.configuration.connect_timeout.to_f,
+        retries: DockerSwarm.configuration.max_retries.to_i
       }.merge(options)
 
       response = client.request(request_options)
-      
-      log_event("request_success", 
-                data: { 
-                  method: request_options[:method], 
-                  path: request_options[:path], 
-                  status: response.status, 
-                  duration_ms: calculate_duration(start_time) 
-                })
-      
+
+      log_event("request_success",
+                data: options.merge(
+                  status: response.status,
+                  duration_ms: calculate_duration(start_time)
+                ))
+
       response.body
     rescue => e
       # Excon suele envolver excepciones de middleware en Excon::Error::Socket.
       # Intentamos recuperar la causa original si es una de nuestras excepciones.
       actual_error = (e.respond_to?(:cause) && e.cause&.class&.name&.include?("DockerSwarm::Error")) ? e.cause : e
-      
-      log_event("request_failure", 
+
+      log_event("request_failure",
                 level: :error,
-                data: { 
-                  method: options[:method], 
-                  path: options[:path], 
+                data: options.merge(
                   error: actual_error.class.name,
                   message: actual_error.message,
-                  duration_ms: calculate_duration(start_time) 
-                })
-                
+                  duration_ms: calculate_duration(start_time)
+                ))
+
       if actual_error.class.name.include?("DockerSwarm::Error")
         raise actual_error
       elsif actual_error.is_a?(Excon::Error::Socket)
@@ -69,20 +65,11 @@ module DockerSwarm
       return if level == :debug && logger.level > Logger::DEBUG
 
       log_block = proc do
-        begin
-          payload = {
-            component: "docker_swarm.connection",
-            event: event,
-            source: "http"
-          }.merge(data)
-
-          payload.map do |k, v|
-            val = k.to_s =~ /password|token|api_key|auth|secret/i ? "[FILTERED]" : v
-            "#{k}=#{val}"
-          end.join(" ")
-        rescue
-          "component=docker_swarm.connection event=logging_error"
-        end
+        LogHelper.format_kv({
+          component: "docker_swarm.connection",
+          event: event,
+          source: "http"
+        }.merge(data))
       end
 
       if level == :debug
@@ -109,9 +96,9 @@ module DockerSwarm
 
     def client
       debug_enabled = logger&.level == Logger::DEBUG
-      
-      options = { 
-        middlewares: common_middlewares, 
+
+      options = {
+        middlewares: common_middlewares,
         logger: logger,
         debug_request: debug_enabled,
         debug_response: debug_enabled,
@@ -121,9 +108,9 @@ module DockerSwarm
 
       @client ||= if socket_path.start_with?("unix://")
                     Excon.new("unix:///", options.merge(socket: socket_path.sub(/^unix:\/\//, "")))
-                  else
+      else
                     Excon.new(socket_path, options)
-                  end
+      end
     end
   end
 end

data/lib/docker_swarm/log_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module DockerSwarm
+  # Helper module to centralize logging logic and formatting
+  module LogHelper
+    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
+    # @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}"
+      end.join(" ")
+    rescue
+      "event=logging_error"
+    end
+  end
+end

data/lib/docker_swarm/middleware/error_handler.rb

@@ -40,7 +40,7 @@ module DockerSwarm
         return unless logger
 
         begin
-          payload = {
+          kv_string = LogHelper.format_kv({
             component: "docker_swarm.middleware.error_handler",
             event: "business_error",
             source: "http",
@@ -48,12 +48,7 @@ module DockerSwarm
             message: message,
             method: env[:method],
             path: env[:path]
-          }
-
-          kv_string = payload.map do |k, v|
-            val = k.to_s =~ /password|token|api_key|auth|secret/i ? "[FILTERED]" : v
-            "#{k}=#{val}"
-          end.join(" ")
+          })
 
           logger.error(kv_string)
         rescue

data/lib/docker_swarm/middleware/request_encoder.rb

@@ -7,7 +7,7 @@ module DockerSwarm
         if env[:body] && !env[:body].is_a?(String)
           content_type = (env[:headers]["Content-Type"] || env[:headers][:content_type]).to_s
           env[:body] = serialize_body(env[:body], content_type)
-          
+
           if content_type.blank? || content_type.include?("application/json")
             env[:headers]["Content-Type"] ||= "application/json"
           end

data/lib/docker_swarm/middleware/response_json_parser.rb

@@ -12,7 +12,7 @@ module DockerSwarm
             env[:response][:body] = parse_json(body)
           end
         end
-        
+
         @stack.response_call(env)
       end
 

data/lib/docker_swarm/models/config.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module DockerSwarm
+  # Represents a Docker Swarm Config
+  # @see https://docs.docker.com/engine/api/v1.41/#tag/Config
   class Config < Base
     include Concerns::Creatable
     include Concerns::Deletable

data/lib/docker_swarm/models/container.rb

@@ -1,19 +1,24 @@
 # frozen_string_literal: true
 
 module DockerSwarm
+  # Represents a Docker Container
+  # @see https://docs.docker.com/engine/api/v1.41/#tag/Container
   class Container < Base
     include Concerns::Deletable
+    include Concerns::Loggable
 
+    # Starts the container
+    # @return [Boolean] true if successful
     def start
       Api.request(action: self.class.routes[:start], arguments: { id: self.ID })
+      true
     end
 
+    # Stops the container
+    # @return [Boolean] true if successful
     def stop
       Api.request(action: self.class.routes[:stop], arguments: { id: self.ID })
-    end
-
-    def logs(query_params = { stdout: 1, stderr: 1 })
-      Api.request(action: self.class.routes[:logs], arguments: { id: self.ID }, query_params: query_params)
+      true
     end
   end
 end

data/lib/docker_swarm/models/image.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module DockerSwarm
+  # Represents a Docker Image
+  # @see https://docs.docker.com/engine/api/v1.41/#tag/Image
   class Image < Base
     include Concerns::Creatable
     include Concerns::Deletable

data/lib/docker_swarm/models/network.rb

@@ -5,14 +5,5 @@ module DockerSwarm
     include Concerns::Creatable
     include Concerns::Updatable
     include Concerns::Deletable
-
-    validate :validate_name_presence
-
-    private
-
-    def validate_name_presence
-      name = attributes["Name"] || (respond_to?(:Name) ? Name : nil)
-      errors.add(:Name, "can't be blank") if name.blank?
-    end
   end
 end

data/lib/docker_swarm/models/node.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module DockerSwarm
+  # Represents a Docker Swarm Node
+  # @see https://docs.docker.com/engine/api/v1.41/#tag/Node
   class Node < Base
     include Concerns::Updatable
     include Concerns::Deletable

data/lib/docker_swarm/models/secret.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module DockerSwarm
+  # Represents a Docker Swarm Secret
+  # @see https://docs.docker.com/engine/api/v1.41/#tag/Secret
   class Secret < Base
     include Concerns::Creatable
     include Concerns::Deletable

data/lib/docker_swarm/models/service.rb

@@ -7,12 +7,6 @@ module DockerSwarm
     include Concerns::Creatable
     include Concerns::Updatable
     include Concerns::Deletable
-
-    # Fetches logs for the service
-    # @param query_params [Hash] Query parameters for the logs endpoint (stdout, stderr, follow, etc.)
-    # @return [String] The raw log stream
-    def logs(query_params = { stdout: 1, stderr: 1 })
-      Api.request(action: self.class.routes[:logs], arguments: { id: self.ID }, query_params: query_params)
-    end
+    include Concerns::Loggable
   end
 end

data/lib/docker_swarm/models/swarm.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
 module DockerSwarm
+  # Access point for Docker Swarm cluster information
+  # @see https://docs.docker.com/engine/api/v1.41/#tag/Swarm
   class Swarm < Base
+    # Override resource name to match API endpoint
+    # @return [String]
     def self.resource_name
       "swarm"
     end
 
+    # Returns information about the swarm
+    # @return [Hash] Raw swarm data
     def self.show
       Api.request(action: routes[:show])
     end

data/lib/docker_swarm/models/system.rb

@@ -1,23 +1,35 @@
 # frozen_string_literal: true
 
 module DockerSwarm
+  # Access point for Docker System information and operations
+  # @see https://docs.docker.com/engine/api/v1.41/#tag/System
   class System < Base
+    # Override resource name to match API endpoint
+    # @return [String]
     def self.resource_name
       "system"
     end
 
+    # Returns system information
+    # @return [Hash]
     def self.info
       Api.request(action: routes[:info])
     end
 
+    # Returns Docker version information
+    # @return [Hash]
     def self.version
       Api.request(action: routes[:version])
     end
 
+    # Checks if the Docker daemon is responding
+    # @return [String] "OK" if up
     def self.up
       Api.request(action: routes[:up])
     end
 
+    # Returns system-wide data usage information
+    # @return [Hash]
     def self.df
       Api.request(action: routes[:df])
     end

data/lib/docker_swarm/models/task.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module DockerSwarm
+  # Represents a Docker Swarm Task
+  # @see https://docs.docker.com/engine/api/v1.41/#tag/Task
   class Task < Base
-    def logs(query_params = { stdout: 1, stderr: 1 })
-      Api.request(action: self.class.routes[:logs], arguments: { id: self.ID }, query_params: query_params)
-    end
+    include Concerns::Loggable
   end
 end

data/lib/docker_swarm/version.rb

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