gjallarhorn 0.1.0.alpha → 0.1.0

data/lib/gjallarhorn/adapter/base.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "logger"
+
+# Base adapter interface for cloud provider implementations
+#
+# The Base class defines the common interface that all cloud provider adapters
+# must implement. It provides the foundation for deploying, managing, and monitoring
+# containerized applications across different cloud platforms.
+#
+# @abstract Subclass and override {#deploy}, {#rollback}, {#status}, {#health_check},
+#   {#scale}, and {#logs} to implement a cloud provider adapter.
+#
+# @example Implementing a custom adapter
+#   class MyCloudAdapter < Gjallarhorn::Adapter::Base
+#     def deploy(image:, environment:, services: [])
+#       # Implementation specific to MyCloud
+#     end
+#   end
+#
+# @since 0.1.0
+module Gjallarhorn
+  module Adapter
+    # Abstract base class for all cloud provider adapters
+    class Base
+      # @return [Hash] Configuration hash for this adapter
+      attr_reader :config
+
+      # @return [Logger] Logger instance for adapter operations
+      attr_reader :logger
+
+      # Initialize a new adapter instance
+      #
+      # @param config [Hash] Configuration hash containing provider-specific settings
+      def initialize(config)
+        @config = config
+        @logger = Logger.new($stdout)
+      end
+
+      # Deploy a container image with the specified services
+      #
+      # @param image [String] Container image tag to deploy
+      # @param environment [String] Target environment name
+      # @param services [Array<Hash>] List of service configurations to deploy
+      # @abstract Subclasses must implement this method
+      # @raise [NotImplementedError] If not implemented by subclass
+      # @return [void]
+      def deploy(image:, environment:, services: [])
+        raise NotImplementedError, "Subclasses must implement deploy"
+      end
+
+      # Rollback services to a previous version
+      #
+      # @param version [String] Version to rollback to
+      # @abstract Subclasses must implement this method
+      # @raise [NotImplementedError] If not implemented by subclass
+      # @return [void]
+      def rollback(version:)
+        raise NotImplementedError, "Subclasses must implement rollback"
+      end
+
+      # Get the current status of all services
+      #
+      # @abstract Subclasses must implement this method
+      # @raise [NotImplementedError] If not implemented by subclass
+      # @return [Array<String>] Status information for all services
+      def status
+        raise NotImplementedError, "Subclasses must implement status"
+      end
+
+      # Check the health status of a specific service
+      #
+      # @param service [String] Service name to check
+      # @abstract Subclasses must implement this method
+      # @raise [NotImplementedError] If not implemented by subclass
+      # @return [Boolean] True if service is healthy, false otherwise
+      def health_check(service:)
+        raise NotImplementedError, "Subclasses must implement health_check"
+      end
+
+      # Scale a service to the specified number of replicas
+      #
+      # @param service [String] Service name to scale
+      # @param replicas [Integer] Target number of replicas
+      # @abstract Subclasses must implement this method
+      # @raise [NotImplementedError] If not implemented by subclass
+      # @return [void]
+      def scale(service:, replicas:)
+        raise NotImplementedError, "Subclasses must implement scale"
+      end
+
+      # Retrieve logs from a specific service
+      #
+      # @param service [String] Service name to get logs from
+      # @param lines [Integer] Number of log lines to retrieve (default: 100)
+      # @abstract Subclasses must implement this method
+      # @raise [NotImplementedError] If not implemented by subclass
+      # @return [String] Service logs
+      def logs(service:, lines: 100)
+        raise NotImplementedError, "Subclasses must implement logs"
+      end
+
+      protected
+
+      # Wait for a service to become healthy with timeout
+      #
+      # @param service [String] Service name to wait for
+      # @param timeout [Integer] Maximum time to wait in seconds (default: 300)
+      # @raise [RuntimeError] If the service doesn't become healthy within timeout
+      # @return [Boolean] True when service becomes healthy
+      # @api private
+      def wait_for_health(service, timeout = 300)
+        start_time = Time.now
+        loop do
+          return true if health_check(service: service)
+
+          raise "Health check timeout for #{service}" if Time.now - start_time > timeout
+
+          sleep 5
+        end
+      end
+    end
+  end
+end

data/lib/gjallarhorn/cli.rb

@@ -3,11 +3,35 @@
 require "thor"
 require_relative "deployer"
 require_relative "configuration"
+require_relative "history"
 
 module Gjallarhorn
+  # Command-line interface for Gjallarhorn deployment operations
+  #
+  # The CLI class provides a Thor-based command-line interface for all deployment
+  # operations including deploy, status checks, rollbacks, and configuration management.
+  # All methods include comprehensive error handling and user-friendly output.
+  #
+  # @example Deploy to production
+  #   gjallarhorn deploy production myapp:v1.2.3
+  #
+  # @example Check status with custom config
+  #   gjallarhorn status staging --config staging-deploy.yml
+  #
+  # @example Rollback to previous version
+  #   gjallarhorn rollback production v1.2.2
+  #
+  # @since 0.1.0
   class CLI < Thor
+    # Default configuration file path
+    DEFAULT_CONFIG_FILE = "config/deploy.yml"
+
     desc "deploy ENVIRONMENT IMAGE", "Deploy an image to the specified environment"
-    option :config, aliases: "-c", default: "deploy.yml", desc: "Configuration file path"
+    option :config, aliases: "-c", default: DEFAULT_CONFIG_FILE, desc: "Configuration file path"
+    # Deploy a container image to the specified environment
+    #
+    # @param environment [String] Target environment name
+    # @param image [String] Container image tag to deploy
     def deploy(environment, image)
       deployer = Deployer.new(options[:config])
       deployer.deploy(environment, image)
@@ -17,7 +41,10 @@ module Gjallarhorn
     end
 
     desc "status ENVIRONMENT", "Check deployment status for an environment"
-    option :config, aliases: "-c", default: "deploy.yml", desc: "Configuration file path"
+    option :config, aliases: "-c", default: DEFAULT_CONFIG_FILE, desc: "Configuration file path"
+    # Check the deployment status for services in an environment
+    #
+    # @param environment [String] Target environment name
     def status(environment)
       deployer = Deployer.new(options[:config])
       result = deployer.status(environment)
@@ -32,7 +59,11 @@ module Gjallarhorn
     end
 
     desc "rollback ENVIRONMENT VERSION", "Rollback to a previous version"
-    option :config, aliases: "-c", default: "deploy.yml", desc: "Configuration file path"
+    option :config, aliases: "-c", default: DEFAULT_CONFIG_FILE, desc: "Configuration file path"
+    # Rollback services in an environment to a previous version
+    #
+    # @param environment [String] Target environment name
+    # @param version [String] Version to rollback to
     def rollback(environment, version)
       deployer = Deployer.new(options[:config])
       deployer.rollback(environment, version)
@@ -42,7 +73,8 @@ module Gjallarhorn
     end
 
     desc "config", "Show current configuration"
-    option :config, aliases: "-c", default: "deploy.yml", desc: "Configuration file path"
+    option :config, aliases: "-c", default: DEFAULT_CONFIG_FILE, desc: "Configuration file path"
+    # Display the current configuration in YAML format
     def config
       configuration = Configuration.new(options[:config])
       puts configuration.to_yaml
@@ -51,9 +83,63 @@ module Gjallarhorn
       exit 1
     end
 
+    desc "history ENVIRONMENT", "Show deployment history for an environment"
+    option :config, aliases: "-c", default: DEFAULT_CONFIG_FILE, desc: "Configuration file path"
+    option :limit, aliases: "-l", type: :numeric, default: 20, desc: "Maximum number of records to show"
+    # Display deployment history for the specified environment
+    #
+    # @param environment [String] Target environment name
+    def history(environment)
+      history_manager = History.new
+      records = history_manager.get_history(environment: environment, limit: options[:limit])
+
+      if records.empty?
+        puts "No deployment history found for #{environment}"
+        return
+      end
+
+      puts "Deployment history for #{environment}:"
+      puts "=" * 60
+
+      records.each do |record|
+        display_deployment_record(record)
+      end
+
+      # Show statistics
+      stats = history_manager.statistics(environment: environment)
+      puts "Statistics:"
+      puts "  Total deployments: #{stats[:total_deployments]}"
+      puts "  Success rate: #{stats[:success_rate]}% (#{stats[:successful_deployments]}/#{stats[:total_deployments]})"
+    rescue StandardError => e
+      puts "Failed to retrieve history: #{e.message}"
+      exit 1
+    end
+
     desc "version", "Show Gjallarhorn version"
+    # Display the current Gjallarhorn version
     def version
       puts Gjallarhorn::VERSION
     end
+
+    private
+
+    # Display a single deployment record with formatting
+    #
+    # @param record [Hash] Deployment record
+    # @return [void]
+    def display_deployment_record(record)
+      timestamp = Time.parse(record["timestamp"]).strftime("%Y-%m-%d %H:%M:%S UTC")
+      status_indicator = case record["status"]
+                         when "success" then "✅"
+                         when "failed" then "❌"
+                         else "🔄"
+                         end
+
+      puts "#{status_indicator} #{timestamp} - #{record["image"]}"
+      puts "   Status: #{record["status"]}"
+      puts "   Strategy: #{record["strategy"]}" if record["strategy"]
+      puts "   Error: #{record["error"]}" if record["error"]
+      puts
+    end
   end
 end

data/lib/gjallarhorn/configuration.rb

@@ -3,14 +3,43 @@
 require "yaml"
 
 module Gjallarhorn
+  # Configuration management class for loading and validating deployment configurations
+  #
+  # The Configuration class handles loading YAML configuration files that define
+  # deployment environments, their providers, and associated services. It provides
+  # validation to ensure all required fields are present and valid.
+  #
+  # @example Loading configuration
+  #   config = Gjallarhorn::Configuration.new('deploy.yml')
+  #   environments = config.environments
+  #   production_config = config.environment('production')
+  #
+  # @example Accessing environment details
+  #   provider = config.provider_for('staging')
+  #   services = config.services_for('production')
+  #
+  # @since 0.1.0
   class Configuration
-    attr_reader :config_file, :data
+    # @return [String] Path to the configuration file
+    attr_reader :config_file
 
+    # @return [Hash] Loaded configuration data
+    attr_reader :data
+
+    # Initialize a new Configuration instance
+    #
+    # @param config_file [String] Path to the YAML configuration file
+    # @raise [ConfigurationError] If the file doesn't exist or contains invalid YAML
     def initialize(config_file = "deploy.yml")
       @config_file = config_file
       load_configuration
     end
 
+    # Get configuration for a specific environment
+    #
+    # @param name [String, Symbol] Environment name
+    # @raise [ConfigurationError] If the environment is not found
+    # @return [Hash] Environment configuration hash
     def environment(name)
       env_config = @data[name.to_s]
       raise ConfigurationError, "Environment '#{name}' not found in #{config_file}" unless env_config
@@ -18,20 +47,34 @@ module Gjallarhorn
       env_config
     end
 
+    # Get all available environment names
+    #
+    # @return [Array<String>] List of environment names
     def environments
       @data.keys
     end
 
+    # Get the provider for a specific environment
+    #
+    # @param environment [String, Symbol] Environment name
+    # @return [String] Provider name (e.g., 'aws', 'gcp')
     def provider_for(environment)
       env_config = environment(environment)
       env_config["provider"]
     end
 
+    # Get the services configuration for a specific environment
+    #
+    # @param environment [String, Symbol] Environment name
+    # @return [Array<Hash>] List of service configurations
     def services_for(environment)
       env_config = environment(environment)
       env_config["services"] || []
     end
 
+    # Convert configuration to YAML string
+    #
+    # @return [String] YAML representation of the configuration
     def to_yaml
       @data.to_yaml
     end
@@ -56,21 +99,34 @@ module Gjallarhorn
     end
 
     def validate_environment(env_name, env_config)
-      raise ConfigurationError, "Environment '#{env_name}' is not a hash" unless env_config.is_a?(Hash)
+      validate_environment_structure(env_name, env_config)
+      validate_provider_field(env_name, env_config)
+      validate_provider_value(env_name, env_config["provider"])
+    end
 
-      unless env_config["provider"]
-        raise ConfigurationError,
-              "Environment '#{env_name}' missing required 'provider' field"
-      end
+    def validate_environment_structure(env_name, env_config)
+      return if env_config.is_a?(Hash)
+
+      raise ConfigurationError, "Environment '#{env_name}' is not a hash"
+    end
+
+    def validate_provider_field(env_name, env_config)
+      return if env_config["provider"]
+
+      raise ConfigurationError,
+            "Environment '#{env_name}' missing required 'provider' field"
+    end
 
+    def validate_provider_value(env_name, provider)
       valid_providers = %w[aws gcp azure docker kubernetes]
-      provider = env_config["provider"]
       return if valid_providers.include?(provider)
 
+      valid_list = valid_providers.join(", ")
       raise ConfigurationError,
-            "Invalid provider '#{provider}' for environment '#{env_name}'. Must be one of: #{valid_providers.join(", ")}"
+            "Invalid provider '#{provider}' for environment '#{env_name}'. Must be one of: #{valid_list}"
     end
   end
 
+  # Raised when configuration loading or validation fails
   class ConfigurationError < Error; end
 end

data/lib/gjallarhorn/deployer.rb

@@ -2,52 +2,181 @@
 
 require "logger"
 require_relative "configuration"
-require_relative "adapters/base"
-require_relative "adapters/aws"
+require_relative "adapter/base"
+require_relative "adapter/aws"
+require_relative "deployment/strategy"
+require_relative "deployment/zero_downtime"
+require_relative "deployment/basic"
+require_relative "deployment/legacy"
+require_relative "proxy/manager"
+require_relative "proxy/nginx_manager"
+require_relative "proxy/traefik_manager"
+require_relative "proxy/kamal_proxy_manager"
+require_relative "history"
 
-# Main Deployer Class
+# Main deployment orchestrator that handles deployments across different cloud providers
+#
+# The Deployer class acts as the central coordinator for all deployment operations,
+# managing configuration loading, adapter selection, and deployment execution across
+# different cloud environments.
+#
+# @example Basic deployment
+#   deployer = Gjallarhorn::Deployer.new('config/deploy.yml')
+#   deployer.deploy('production', 'myapp:v1.2.3')
+#
+# @example Check service status
+#   status = deployer.status('staging')
+#   puts status.inspect
+#
+# @example Rollback to previous version
+#   deployer.rollback('production', 'v1.2.2')
+#
+# @since 0.1.0
 module Gjallarhorn
+  # Main deployment orchestrator class
   class Deployer
+    # Default configuration file path
+    DEFAULT_CONFIG_FILE = "config/deploy.yml"
+    
+    # Mapping of provider names to their corresponding adapter classes
+    # @api private
     ADAPTERS = {
-      "aws" => Adapters::AWSAdapter,
+      "aws" => Adapter::AWSAdapter,
       "gcp" => nil, # TODO: Implement in Phase 2
       "azure" => nil, # TODO: Implement in Phase 2
       "docker" => nil, # TODO: Implement in Phase 2
       "kubernetes" => nil # TODO: Implement in Phase 3
     }.freeze
 
-    attr_reader :configuration, :logger
+    # @return [Configuration] The loaded deployment configuration
+    attr_reader :configuration
 
-    def initialize(config_file = "deploy.yml")
+    # @return [Logger] Logger instance for deployment operations
+    attr_reader :logger
+
+    # Initialize a new Deployer instance
+    #
+    # @param config_file [String] Path to the YAML configuration file
+    # @raise [ConfigurationError] If the configuration file is invalid
+    def initialize(config_file = DEFAULT_CONFIG_FILE)
       @configuration = Configuration.new(config_file)
       @logger = Logger.new($stdout)
+      @history = History.new
     end
 
-    def deploy(environment, image)
+    # Deploy a container image to the specified environment
+    #
+    # @param environment [String] Target environment name (e.g., 'production', 'staging')
+    # @param image [String] Container image tag to deploy (e.g., 'myapp:v1.2.3')
+    # @param strategy [String] Deployment strategy to use ('zero_downtime', 'rolling', 'basic')
+    # @raise [DeploymentError] If the deployment fails or provider is not supported
+    # @return [void]
+    def deploy(environment, image, strategy: "zero_downtime")
+      # Record deployment start
+      @history.record_deployment(
+        environment: environment,
+        image: image,
+        status: "started",
+        strategy: strategy
+      )
+
       adapter = create_adapter(environment)
-      @logger.info "Deploying #{image} to #{environment} using #{adapter.class.name}"
+      deployment_strategy = create_deployment_strategy(strategy, adapter, environment)
+
+      @logger.info "Deploying #{image} to #{environment} using #{adapter.class.name} with #{strategy} strategy"
 
-      adapter.deploy(
+      deployment_strategy.deploy(
         image: image,
         environment: environment,
         services: @configuration.services_for(environment)
       )
 
       @logger.info "Deployment completed successfully"
+
+      # Record successful deployment
+      @history.record_deployment(
+        environment: environment,
+        image: image,
+        status: "success",
+        strategy: strategy
+      )
+    rescue StandardError => e
+      # Record failed deployment
+      @history.record_deployment(
+        environment: environment,
+        image: image,
+        status: "failed",
+        strategy: strategy,
+        error: e.message
+      )
+      raise
+    end
+
+    # Deploy with specific strategy (convenience method)
+    #
+    # @param environment [String] Target environment name
+    # @param image [String] Container image tag to deploy
+    # @param strategy [String] Deployment strategy to use
+    # @return [void]
+    def deploy_with_strategy(environment, image, strategy)
+      deploy(environment, image, strategy: strategy)
     end
 
+    # Get the current status of services in the specified environment
+    #
+    # @param environment [String] Target environment name
+    # @raise [DeploymentError] If the provider is not supported
+    # @return [Hash] Status information for all services in the environment
     def status(environment)
       adapter = create_adapter(environment)
       adapter.status
     end
 
+    # Rollback services in the environment to a previous version
+    #
+    # @param environment [String] Target environment name
+    # @param version [String] Version to rollback to (e.g., 'v1.2.2')
+    # @raise [DeploymentError] If the rollback fails or provider is not supported
+    # @return [void]
     def rollback(environment, version)
+      # Record rollback start
+      @history.record_deployment(
+        environment: environment,
+        image: version,
+        status: "started",
+        strategy: "rollback"
+      )
+
       adapter = create_adapter(environment)
       adapter.rollback(version: version)
+
+      # Record successful rollback
+      @history.record_deployment(
+        environment: environment,
+        image: version,
+        status: "success",
+        strategy: "rollback"
+      )
+    rescue StandardError => e
+      # Record failed rollback
+      @history.record_deployment(
+        environment: environment,
+        image: version,
+        status: "failed",
+        strategy: "rollback",
+        error: e.message
+      )
+      raise
     end
 
     private
 
+    # Create an adapter instance for the specified environment
+    #
+    # @param environment [String] Target environment name
+    # @raise [DeploymentError] If the provider is not supported
+    # @return [Adapter::Base] Configured adapter instance
+    # @api private
     def create_adapter(environment)
       env_config = @configuration.environment(environment)
       provider = env_config["provider"]
@@ -57,7 +186,48 @@ module Gjallarhorn
 
       adapter_class.new(env_config)
     end
+
+    # Create a deployment strategy instance
+    #
+    # @param strategy_name [String] Strategy name ('zero_downtime', 'rolling', 'basic')
+    # @param adapter [Adapter::Base] Adapter instance
+    # @param environment [String] Target environment name
+    # @raise [DeploymentError] If the strategy is not supported
+    # @return [Deployment::Strategy] Deployment strategy instance
+    # @api private
+    def create_deployment_strategy(strategy_name, adapter, environment)
+      proxy_manager = create_proxy_manager(environment) if strategy_name == "zero_downtime"
+
+      case strategy_name
+      when "zero_downtime"
+        Deployment::ZeroDowntime.new(adapter, proxy_manager, @logger)
+      when "basic"
+        Deployment::Basic.new(adapter, proxy_manager, @logger)
+      when "legacy"
+        Deployment::Legacy.new(adapter, proxy_manager, @logger)
+      else
+        raise DeploymentError, "Deployment strategy '#{strategy_name}' not yet implemented"
+      end
+    end
+
+    # Create a proxy manager instance for zero-downtime deployments
+    #
+    # @param environment [String] Target environment name
+    # @return [Proxy::Manager, nil] Proxy manager instance or nil if not configured
+    # @api private
+    def create_proxy_manager(environment)
+      env_config = @configuration.environment(environment)
+      proxy_config = env_config["proxy"]
+
+      return nil unless proxy_config
+
+      Proxy::Manager.create(proxy_config.transform_keys(&:to_sym), @logger)
+    rescue StandardError => e
+      @logger.warn "Failed to create proxy manager: #{e.message}"
+      nil
+    end
   end
 
+  # Raised when deployment operations fail
   class DeploymentError < Error; end
 end