docker-swarm 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b43832405fbf723559703102c4d84a42c27c677d601625de43c81ceb2db804d0
-  data.tar.gz: 57d9349d4ce67bc9e157c6d235e5cf4925b0af05df53ce0f29fffd2bd888fbb7
+  metadata.gz: 78ad878518bedd7c1ac7355efbb6372b49f2721fd7db5a3b0536b0872ed9f3ea
+  data.tar.gz: 6a5b9b06a1c43e8735d111cda5e9eb65820101fe515832fdf64647834310ad12
 SHA512:
-  metadata.gz: 72c9fa985935caac2386f9b782ac3728f4c5ffbd121db6f5b36a6e1291eafed9bc5500bd0841385caad69ad5430152b5d11d10261c4ad73fbda86bd9cc7053b3
-  data.tar.gz: e841eaa3cad32138f809a40556a2c798fb97e7c92bf40975d2076adbd6650a699eb5635880f6c50d598de2c1017045d61771ff88f7a794f8482a71bdb32b7fe3
+  metadata.gz: 762b554eb9e1321d1cb2cb82867809b816ba7e7a84ee55e1e34b571b0942aba9e13020d8b7019dc40c70d4457b3307f9d72ca5cc98cd5de26207c9bf9ce70c1b
+  data.tar.gz: e092c1f28b3de38986f3f5e207dd1aafeac8449448e861675aa0be88ee4763f71aa663fc9ee8c1b3bafcfe1997b3917a0924ca9dea777b484b5163bd4b197d45

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/docker-swarm.svg)](https://badge.fury.io/rb/docker-swarm)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-`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.
+`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
 
@@ -13,42 +13,37 @@ require 'docker_swarm'
 # Configurar (opcional, usa defaults)
 DockerSwarm.configure do |config|
   config.socket_path = "unix:///var/run/docker.sock"
+  config.log_level = Logger::INFO
+  config.read_timeout = 30
+  config.max_retries = 3
 end
 
-# Listar servicios
+# Listar servicios (con soporte para Indifferent Access en arrays)
 services = DockerSwarm::Service.all
-services.each { |s| puts "#{s.ID}: #{s.Spec['Name']}" }
+services.each { |s| puts "#{s.ID}: #{s.Spec[:Name]}" }
 
 # Crear un nuevo servicio
 service = DockerSwarm::Service.create(
+  Name: "my-webapp",
   Spec: {
-    Name: "my-webapp",
     TaskTemplate: {
       ContainerSpec: { Image: "nginx:latest" }
     }
   }
 )
 
-# Obtener logs
+# Obtener logs (stdout y stderr habilitados por defecto)
 puts service.logs
 ```
 
-## 📖 Documentación Completa
-
-Para profundizar en el uso de la gema, consulta las siguientes guías:
-
-1.  **[Guía de Configuración](docs/configuration.md)**: Cómo configurar el socket, logger y opciones globales.
-2.  **[Uso del ORM (Modelos)](docs/models.md)**: Todo sobre el ciclo de vida de los recursos (`Service`, `Node`, `Task`, etc.).
-3.  **[Cliente de API (Bajo Nivel)](docs/api.md)**: Cómo realizar peticiones personalizadas directamente a la API de Docker.
-4.  **[Manejo de Errores](docs/errors.md)**: Jerarquía de excepciones y mapeo de errores de Docker.
-5.  **[Pruebas y Mocking](docs/testing.md)**: Guía para testear tu aplicación sin depender de un socket de Docker real.
-
 ## 🛠 Características Clave
 
+- **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.
-- **Surgical Updates**: Actualizaciones precisas enviando solo el índice de versión y el payload necesario.
-- **Excon Stack**: Basado en `Excon` con middlewares para encoding de peticiones, parseo de respuestas y gestión de errores.
 
 ## 🤝 Contribuir
 

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

@@ -5,11 +5,32 @@ require "logger"
 module DockerSwarm
   class Configuration
     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.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,37 +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] })
-
-      response = client.request(options)
-      
-      log_event("request_success", 
-                data: { 
-                  method: options[:method], 
-                  path: options[:path], 
-                  status: response.status, 
-                  duration_ms: calculate_duration(start_time) 
-                })
-      
+                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.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: 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)
@@ -59,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
@@ -99,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,
@@ -111,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/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

@@ -4,12 +4,28 @@ module DockerSwarm
   module Middleware
     class RequestEncoder < Excon::Middleware::Base
       def request_call(env)
-        if env[:body] && env[:body].is_a?(Hash)
-          env[:body] = env[:body].to_json
-          env[:headers]["Content-Type"] ||= "application/json"
+        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
         end
         @stack.request_call(env)
       end
+
+      private
+
+      def serialize_body(body, content_type)
+        if content_type.include?("application/x-www-form-urlencoded")
+          URI.encode_www_form(body)
+        elsif content_type.include?("multipart/form-data")
+          body
+        else
+          body.to_json
+        end
+      end
     end
   end
 end

data/lib/docker_swarm/middleware/response_json_parser.rb

@@ -9,17 +9,29 @@ module DockerSwarm
           headers = env[:response][:headers] || {}
 
           if body && !body.empty? && headers["Content-Type"]&.include?("application/json")
-            begin
-              parsed = JSON.parse(body)
-              env[:response][:body] = parsed.is_a?(Hash) ? parsed.with_indifferent_access : parsed
-            rescue JSON::ParserError
-              # Keep original body if parsing fails
-            end
+            env[:response][:body] = parse_json(body)
           end
         end
-        
+
         @stack.response_call(env)
       end
+
+      private
+
+      def parse_json(body)
+        result = body.is_a?(String) ? JSON.parse(body) : body
+
+        case result
+        when Hash
+          result.with_indifferent_access
+        when Array
+          result.map { |item| item.is_a?(Hash) ? item.with_indifferent_access : item }
+        else
+          result
+        end
+      rescue JSON::ParserError
+        body
+      end
     end
   end
 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,21 +7,6 @@ module DockerSwarm
     include Concerns::Creatable
     include Concerns::Updatable
     include Concerns::Deletable
-
-    validate :validate_name_presence
-
-    # 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
-
-    private
-
-    def validate_name_presence
-      name = attributes["Name"] || (respond_to?(:Name) ? Name : nil)
-      errors.add(:Name, "can't be blank") if name.blank?
-    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.2.0"
+  VERSION = "0.4.0"
 end

data/lib/docker_swarm.rb

@@ -6,6 +6,7 @@ require "active_model"
 require "excon"
 require "json"
 require "logger"
+require "set"
 
 module DockerSwarm
   class << self
@@ -14,11 +15,11 @@ module DockerSwarm
     def configure
       @configuration ||= Configuration.new
       yield(@configuration) if block_given?
-      
+
       if @configuration.logger.respond_to?(:level=)
         @configuration.logger.level = @configuration.log_level
       end
-      
+
       @connection = nil
     end
 
@@ -35,6 +36,7 @@ end
 
 # Primero cargamos la configuración porque la clase DockerSwarm la usa arriba
 require_relative "docker_swarm/configuration"
+require_relative "docker_swarm/log_helper"
 require_relative "docker_swarm/version"
 require_relative "docker_swarm/errors"
 require_relative "docker_swarm/middleware/request_encoder"
@@ -42,10 +44,15 @@ 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/base"
+
+# Concerns deben cargarse antes que Base si Base los incluye
 require_relative "docker_swarm/concerns/creatable"
 require_relative "docker_swarm/concerns/updatable"
 require_relative "docker_swarm/concerns/deletable"
+require_relative "docker_swarm/concerns/loggable"
+require_relative "docker_swarm/concerns/inspectable"
+
+require_relative "docker_swarm/base"
 
 # Models
 require_relative "docker_swarm/models/swarm"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docker-swarm
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Gabriel
@@ -95,10 +95,13 @@ files:
 - lib/docker_swarm/base.rb
 - lib/docker_swarm/concerns/creatable.rb
 - lib/docker_swarm/concerns/deletable.rb
+- lib/docker_swarm/concerns/inspectable.rb
+- lib/docker_swarm/concerns/loggable.rb
 - lib/docker_swarm/concerns/updatable.rb
 - lib/docker_swarm/configuration.rb
 - lib/docker_swarm/connection.rb
 - lib/docker_swarm/errors.rb
+- lib/docker_swarm/log_helper.rb
 - lib/docker_swarm/middleware/error_handler.rb
 - lib/docker_swarm/middleware/request_encoder.rb
 - lib/docker_swarm/middleware/response_json_parser.rb