docker-swarm 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97102c26aff73c5426373e1cfbfb542fd2cf4e82404a3b1de4833b8e82d5d66a
-  data.tar.gz: 3a9288b1dc9eae6d4849503de616561c94af264ec467e9450c2a4e2863e4706f
+  metadata.gz: b46f33638fb88f8c9fca4a85747f67e266525933e4b22d38bb47e2ce1556a552
+  data.tar.gz: b080b742324d91eb1570af605b05539da67284fb76631faae04583f2577edad3
 SHA512:
-  metadata.gz: fb9eea1d60221c643681e50ea18a4a9830967e46ef226543c62df85c26102c9fd60b26a6f77f35f12c6e5ff86ca15ec280175ca656c266587e7737414837f91c
-  data.tar.gz: 0b223dd63b9c69a14a24c07b3be527876d9535c1114f53a507152fd2d28cbf126a387b0b72ddbba18290aa621c49369adaf83f2e80ca68f3d2dad8def9c749bf
+  metadata.gz: 17f03f903b19273e822feb4a389ff9b862d034607f032c3b6112838b1ddf5f38927dabad4001214f6ad9ce6a06f8661939b38fb2fa3dda8a0b1975246da199fa
+  data.tar.gz: 44edbe59ffa431b2cf78735ca138c2fd4c41d0d57dda543509d9de8a417343c525d1a3493d549fa4e2ebfc63948491a2994917df493683c25f8c33e2f795eadf

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.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "docker_swarm"

data/lib/docker_swarm/base.rb

@@ -13,8 +13,19 @@ module DockerSwarm
         Api::ENDPOINTS[resource_name.to_sym]
       end
 
+      # Key in the JSON response that contains the array of items.
+      # Override in subclasses if the API returns a wrapped object (e.g., Volumes).
+      # @return [String, nil]
+      def root_key
+        nil
+      end
+
       def all(filters = {})
-        _fetch_all(filters).map { |data| new(data) }
+        response = _fetch_all(filters)
+        return [] if response.blank?
+
+        data = root_key && response.is_a?(Hash) ? response[root_key] : response
+        Array(data).map { |item| new(item) }
       end
 
       def find(id)

data/lib/docker_swarm/configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module DockerSwarm
+  class Configuration
+    attr_accessor :socket_path, :logger, :log_level,
+                  :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
+      @max_retries = 3
+    end
+  end
+end

data/lib/docker_swarm/connection.rb

@@ -10,29 +10,120 @@ module DockerSwarm
     end
 
     def request(options = {})
-      normalized_path = socket_path.sub(/^unix:\/\//, "")
-      client(normalized_path).request(options).body
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      
+      log_event("request_started", 
+                level: :debug,
+                data: { method: options[:method], 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
+      }.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) 
+                })
+      
+      response.body
     rescue => e
-      if e.is_a?(Excon::Error::Socket)
-        raise Errors::Communication, "Docker socket error: #{e.message}"
+      # 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", 
+                level: :error,
+                data: { 
+                  method: options[:method], 
+                  path: options[:path], 
+                  error: actual_error.class.name,
+                  message: actual_error.message,
+                  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)
+        raise ::DockerSwarm::Error::Communication, "Docker socket error: #{actual_error.message}"
       else
-        raise e
+        raise actual_error
       end
     end
+
     private
 
-    def client(path)
-      @client ||= Excon.new(
-        "unix:///",
-        socket: path,
-        middlewares: [
-          Excon::Middleware::ResponseParser,
-          Excon::Middleware::RedirectFollower,
-          Middleware::RequestEncoder,
-          Middleware::ResponseJSONParser,
-          Middleware::ErrorHandler
-        ]
-      )
+    def log_event(event, level: :info, data: {})
+      return unless logger
+      # Respetar el nivel de log antes de procesar nada
+      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
+      end
+
+      if level == :debug
+        logger.debug(&log_block)
+      else
+        logger.send(level, log_block.call)
+      end
+    end
+
+    def calculate_duration(start_time)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+    end
+
+    def common_middlewares
+      # Usamos los middlewares por defecto de Excon para garantizar que todas las llaves internas
+      # (como :retries_remaining o :instrumentor_name) se inicialicen correctamente.
+      Excon.defaults[:middlewares] + [
+        Excon::Middleware::RedirectFollower,
+        Middleware::RequestEncoder,
+        Middleware::ResponseJSONParser,
+        Middleware::ErrorHandler
+      ]
+    end
+
+    def client
+      debug_enabled = logger&.level == Logger::DEBUG
+      
+      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
+      }
+
+      @client ||= if socket_path.start_with?("unix://")
+                    Excon.new("unix:///", options.merge(socket: socket_path.sub(/^unix:\/\//, "")))
+                  else
+                    Excon.new(socket_path, options)
+                  end
     end
   end
 end

data/lib/docker_swarm/errors.rb

@@ -3,7 +3,7 @@
 module DockerSwarm
   class Error < StandardError; end
 
-  module Errors
+  class Error
     class BadRequest < Error; end
     class Unauthorized < Error; end
     class Forbidden < Error; end
@@ -19,4 +19,31 @@ module DockerSwarm
     class TooManyRequests < Error; end
     class Communication < Error; end
   end
+
+  # Aliases para permitir acceso directo DockerSwarm::Conflict
+  BadRequest          = Error::BadRequest
+  Unauthorized        = Error::Unauthorized
+  Forbidden           = Error::Forbidden
+  NotFound            = Error::NotFound
+  NotAcceptable       = Error::NotAcceptable
+  RequestTimeout      = Error::RequestTimeout
+  Conflict            = Error::Conflict
+  UnprocessableEntity = Error::UnprocessableEntity
+  InternalServerError = Error::InternalServerError
+  BadGateway          = Error::BadGateway
+  ServiceUnavailable  = Error::ServiceUnavailable
+  GatewayTimeout      = Error::GatewayTimeout
+  TooManyRequests     = Error::TooManyRequests
+  Communication       = Error::Communication
+
+  # Módulo Errors para compatibilidad adicional
+  module Errors
+    def self.const_missing(name)
+      if ::DockerSwarm::Error.const_defined?(name)
+        ::DockerSwarm::Error.const_get(name)
+      else
+        super
+      end
+    end
+  end
 end

data/lib/docker_swarm/middleware/error_handler.rb

@@ -9,31 +9,58 @@ module DockerSwarm
         status = env[:response][:status]
         body = env[:response][:body]
 
+        return @stack.response_call(env) if (200..299).include?(status)
+
+        error_msg = error_message(body)
+        log_business_error(env, status, error_msg)
+
         case status
-        when 200..299
-          # Continuar normalmente
-        when 400 then raise Errors::BadRequest, error_message(body)
-        when 401 then raise Errors::Unauthorized, error_message(body)
-        when 403 then raise Errors::Forbidden, error_message(body)
-        when 404 then raise Errors::NotFound, error_message(body)
-        when 406 then raise Errors::NotAcceptable, error_message(body)
-        when 408 then raise Errors::RequestTimeout, error_message(body)
-        when 409 then raise Errors::Conflict, error_message(body)
-        when 422 then raise Errors::UnprocessableEntity, body
-        when 429 then raise Errors::TooManyRequests, error_message(body)
-        when 500 then raise Errors::InternalServerError, error_message(body)
-        when 502 then raise Errors::BadGateway, error_message(body)
-        when 503 then raise Errors::ServiceUnavailable, error_message(body)
-        when 504 then raise Errors::GatewayTimeout, error_message(body)
+        when 400 then raise ::DockerSwarm::BadRequest, error_msg
+        when 401 then raise ::DockerSwarm::Unauthorized, error_msg
+        when 403 then raise ::DockerSwarm::Forbidden, error_msg
+        when 404 then raise ::DockerSwarm::NotFound, error_msg
+        when 406 then raise ::DockerSwarm::NotAcceptable, error_msg
+        when 408 then raise ::DockerSwarm::RequestTimeout, error_msg
+        when 409 then raise ::DockerSwarm::Conflict, error_msg
+        when 422 then raise ::DockerSwarm::UnprocessableEntity, body
+        when 429 then raise ::DockerSwarm::TooManyRequests, error_msg
+        when 500 then raise ::DockerSwarm::InternalServerError, error_msg
+        when 502 then raise ::DockerSwarm::BadGateway, error_msg
+        when 503 then raise ::DockerSwarm::ServiceUnavailable, error_msg
+        when 504 then raise ::DockerSwarm::GatewayTimeout, error_msg
         else
-          raise Errors::Error, "HTTP #{status}: #{error_message(body)}"
+          raise ::DockerSwarm::Error, "HTTP #{status}: #{error_msg}"
         end
-
-        @stack.response_call(env)
       end
 
       private
 
+      def log_business_error(env, status, message)
+        logger = env[:logger]
+        return unless logger
+
+        begin
+          payload = {
+            component: "docker_swarm.middleware.error_handler",
+            event: "business_error",
+            source: "http",
+            status: status,
+            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
+          # Resilience: logging should not crash the app
+        end
+      end
+
       def error_message(body)
         if body.is_a?(Hash)
           body["message"] || body["error"] || body.to_json

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/service.rb

@@ -8,20 +8,11 @@ module DockerSwarm
     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
   end
 end

data/lib/docker_swarm/models/volume.rb

@@ -5,12 +5,8 @@ module DockerSwarm
     include Concerns::Creatable
     include Concerns::Deletable
 
-    def self.all(filters = {})
-      response = _fetch_all(filters)
-      return [] if response.blank?
-      
-      data = response.is_a?(Hash) ? response["Volumes"] : response
-      Array(data).map { |item| new(item) }
+    def self.root_key
+      "Volumes"
     end
   end
 end

data/lib/docker_swarm/version.rb

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

data/lib/docker_swarm.rb

@@ -7,6 +7,34 @@ require "excon"
 require "json"
 require "logger"
 
+module DockerSwarm
+  class << self
+    attr_accessor :configuration
+
+    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
+
+    def connection
+      configure unless @configuration
+      @connection ||= Connection.new(@configuration.socket_path, @configuration.logger)
+    end
+
+    def request(options = {})
+      connection.request(options)
+    end
+  end
+end
+
+# Primero cargamos la configuración porque la clase DockerSwarm la usa arriba
+require_relative "docker_swarm/configuration"
 require_relative "docker_swarm/version"
 require_relative "docker_swarm/errors"
 require_relative "docker_swarm/middleware/request_encoder"
@@ -31,32 +59,3 @@ require_relative "docker_swarm/models/network"
 require_relative "docker_swarm/models/config"
 require_relative "docker_swarm/models/secret"
 require_relative "docker_swarm/models/volume"
-
-module DockerSwarm
-  class << self
-    attr_accessor :configuration
-
-    def configure
-      self.configuration ||= Configuration.new
-      yield(configuration) if block_given?
-    end
-
-    def connection
-      configure unless configuration
-      @connection ||= Connection.new(configuration.socket_path, configuration.logger)
-    end
-
-    def request(options = {})
-      connection.request(options)
-    end
-  end
-
-  class Configuration
-    attr_accessor :socket_path, :logger
-
-    def initialize
-      @socket_path = "unix:///var/run/docker.sock"
-      @logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
-    end
-  end
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docker-swarm
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Gabriel
@@ -89,12 +89,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - README.md
+- lib/docker-swarm.rb
 - lib/docker_swarm.rb
 - lib/docker_swarm/api.rb
 - lib/docker_swarm/base.rb
 - lib/docker_swarm/concerns/creatable.rb
 - lib/docker_swarm/concerns/deletable.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/middleware/error_handler.rb