odysseus-core 0.3.2 → 0.9.0

data/lib/odysseus/orchestrator/web_deploy.rb

@@ -6,6 +6,10 @@ module Odysseus
   module Orchestrator
     class WebDeploy
       include Odysseus::Core::VolumeNamespacer
+      include Odysseus::Core::DeployVersioning
+
+      # Probed when a proxy is configured without an explicit healthcheck block.
+      DEFAULT_HEALTHCHECK_PATH = '/'.freeze
 
       # @param ssh [Odysseus::Deployer::SSH] SSH connection
       # @param config [Hash] parsed deploy config
@@ -31,13 +35,22 @@ module Odysseus
         log "Deploying #{service} (role: #{role})"
         log "  Image: #{image}"
 
+        # A web role is proxied by Caddy, which needs a port to route to. Without
+        # one the container gets no health command and the deploy would sit in
+        # health checks until it timed out, so say so up front.
+        unless app_port
+          raise Odysseus::ConfigError,
+                "proxy.app_port is required to deploy the '#{role}' role — " \
+                'set it to the port your app listens on inside the container'
+        end
+
         # Step 1: Ensure Caddy is running
-        log "Ensuring Caddy proxy is running..."
+        log 'Ensuring Caddy proxy is running...'
         if @caddy.running?
-          log "  Caddy already running"
+          log '  Caddy already running'
         else
-          @caddy.ensure_running
-          log "  Caddy started"
+          ensure_caddy!
+          log '  Caddy started'
         end
 
         # Step 2: Find existing containers
@@ -45,7 +58,7 @@ module Odysseus
         log "  Found #{old_containers.size} existing container(s)"
 
         # Step 3: Start new container
-        log "Starting new container..."
+        log 'Starting new container...'
         new_container_id = start_new_container(image: image, role: role)
         log "  Container started: #{new_container_id[0..11]}"
 
@@ -55,21 +68,21 @@ module Odysseus
         unless wait_for_healthy(new_container_id)
           log_health_failure(new_container_id)
           handle_failed_deploy(new_container_id, old_containers)
-          raise Odysseus::DeployError, "Container failed health checks"
+          raise Odysseus::DeployError, 'Container failed health checks'
         end
-        log "  Health check passed"
+        log '  Health check passed'
 
         # Step 5: Add new container to Caddy
         proxy_hosts = @config[:proxy][:hosts]&.join(', ')
         log "Adding to Caddy proxy (hosts: #{proxy_hosts})..."
         add_to_caddy(new_container_id)
-        log "  Caddy routing configured"
+        log '  Caddy routing configured'
 
         # Step 6: Remove old containers from Caddy and stop them
         old_containers.each do |old|
           log "Draining old container #{old['ID'][0..11]}..."
           drain_and_remove(old['ID'])
-          log "  Old container removed"
+          log '  Old container removed'
         end
 
         # Step 7: Cleanup old stopped containers
@@ -96,15 +109,15 @@ module Odysseus
       private
 
       def ensure_caddy!
-        unless @caddy.ensure_running
-          raise Odysseus::DeployError, "Failed to start Caddy proxy"
-        end
+        return if @caddy.ensure_running
+
+        raise Odysseus::DeployError, 'Failed to start Caddy proxy'
       end
 
       def start_new_container(image:, role:)
         service = @config[:service]
-        timestamp = Time.now.strftime('%Y%m%d%H%M%S')
-        container_name = "#{service}-#{timestamp}"
+        timestamp = Time.now.utc.strftime('%Y%m%d%H%M%S')
+        container_name = "#{service}-#{deploy_version_tag(image)}-#{timestamp}"
 
         server_config = @config[:servers][role] || {}
         options = server_config[:options] || {}
@@ -114,9 +127,7 @@ module Odysseus
         log "  Environment: #{env.size} variable(s) injected"
 
         volumes = namespace_volumes(server_config[:volumes], service: service)
-        if volumes&.any?
-          log "  Volumes: #{volumes.join(', ')}"
-        end
+        log "  Volumes: #{volumes.join(', ')}" if volumes&.any?
 
         if options[:memory] || options[:cpus]
           log "  Resources: memory=#{options[:memory] || 'default'}, cpus=#{options[:cpus] || 'default'}"
@@ -127,7 +138,8 @@ module Odysseus
           image: image,
           options: {
             service: service,
-            version: timestamp,
+            version: deploy_version_tag(image),
+            labels: version_labels,
             ports: internal_port_mapping(proxy_config[:app_port]),
             env: env,
             volumes: volumes,
@@ -152,39 +164,27 @@ module Odysseus
         nil
       end
 
+      # Shared with JobDeploy and with the one-off containers the CLI runs, so
+      # every path injects the same environment. Kept private here: it is how
+      # this orchestrator fills in its own container's env, not a service to
+      # call on it from outside.
       def build_environment
-        env = {}
-
-        # Clear env vars (hardcoded values)
-        @config[:env][:clear]&.each do |key, value|
-          env[key.to_s] = value.to_s
-        end
-
-        # Secret env vars - first try encrypted file, then server environment
-        @config[:env][:secret]&.each do |key|
-          # Try encrypted secrets file first
-          if @secrets_loader&.configured?
-            value = @secrets_loader.get(key)
-            if value
-              env[key.to_s] = value.to_s
-              next
-            end
-          end
-
-          # Fall back to server's environment
-          value = @ssh.execute("echo $#{key}").strip
-          env[key.to_s] = value unless value.empty?
-        end
-
-        env
+        Odysseus::Core::Environment.new(config: @config, secrets_loader: @secrets_loader, ssh: @ssh).build
       end
 
+      # Build the container-level health check Docker polls.
+      #
+      # The deploy gates on Docker reporting the container healthy, so a web
+      # container always needs a health command — without one the status stays
+      # 'none' forever and every deploy times out. When no healthcheck block is
+      # configured we probe the app port at DEFAULT_HEALTHCHECK_PATH, matching
+      # the default Config::Parser applies to an empty healthcheck block.
       def build_healthcheck(hc_config)
-        return nil unless hc_config && hc_config[:path]
+        port = app_port
+        return nil unless port
 
-        port = @config[:proxy][:app_port]
-        path = hc_config[:path]
-        expect_status = hc_config[:expect_status]
+        path = (hc_config && hc_config[:path]) || DEFAULT_HEALTHCHECK_PATH
+        expect_status = hc_config && hc_config[:expect_status]
 
         # Build curl command based on expected status
         cmd = if expect_status
@@ -254,7 +254,7 @@ module Odysseus
       end
 
       def handle_failed_deploy(new_container_id, old_containers)
-        log "Rolling back failed deploy...", :warn
+        log 'Rolling back failed deploy...', :warn
 
         # Remove the failed new container
         @docker.stop(new_container_id)
@@ -264,7 +264,7 @@ module Odysseus
         if old_containers.any?
           log "Rollback complete — #{old_containers.size} old container(s) still serving traffic"
         else
-          log "Rollback complete — no previous containers to fall back to", :warn
+          log 'Rollback complete — no previous containers to fall back to', :warn
         end
       end
 
@@ -275,7 +275,7 @@ module Odysseus
         begin
           recent_logs = @docker.logs(container_id, tail: 30)
           unless recent_logs.strip.empty?
-            log "  Container logs (last 30 lines):", :error
+            log '  Container logs (last 30 lines):', :error
             recent_logs.each_line { |line| log "    #{line.rstrip}", :error }
           end
         rescue StandardError => e
@@ -292,17 +292,23 @@ module Odysseus
       end
 
       def describe_healthcheck(hc_config)
-        return "(no health check configured)" unless hc_config && hc_config[:path]
+        port = app_port
+        path = (hc_config && hc_config[:path]) || DEFAULT_HEALTHCHECK_PATH
+        interval = (hc_config && hc_config[:interval]) || 10
 
-        port = @config[:proxy][:app_port]
-        "(GET http://localhost:#{port}#{hc_config[:path]}, interval: #{hc_config[:interval] || 10}s)"
+        "(GET http://localhost:#{port}#{path}, interval: #{interval}s)"
+      end
+
+      # Port the app listens on inside the container, nil when no proxy is configured.
+      def app_port
+        @config[:proxy] && @config[:proxy][:app_port]
       end
 
       def default_logger
         @default_logger ||= Object.new.tap do |l|
-          def l.info(msg); puts msg; end
-          def l.warn(msg); puts "[WARN] #{msg}"; end
-          def l.error(msg); puts "[ERROR] #{msg}"; end
+          def l.info(msg) = puts(msg)
+          def l.warn(msg) = puts("[WARN] #{msg}")
+          def l.error(msg) = puts("[ERROR] #{msg}")
         end
       end
 

data/lib/odysseus/plugins.rb

@@ -0,0 +1,72 @@
+# lib/odysseus/plugins.rb
+
+module Odysseus
+  # Loads the gems named in deploy.yml's `plugins:` (or `sails:`) list, so that
+  # the sail and host-provider registries have something in them.
+  #
+  # Runs before config validation, because the validator is what asks whether a
+  # named strategy is registered. That ordering is why this validates its own
+  # shape rather than leaving it to Validators::Config like every other key.
+  #
+  # Requiring a gem name read from a config file is a real capability, and is
+  # documented as such: deploy.yml already runs arbitrary docker commands as
+  # root on the target hosts, so this widens visibility rather than trust.
+  module Plugins
+    # `sails:` matches the project's own vocabulary; `plugins:` is what someone
+    # guesses without reading the docs. Both work, but not together.
+    KEYS = %w[plugins sails].freeze
+
+    # @param raw_config [Hash] the string-keyed hash straight from YAML
+    # @raise [Odysseus::ConfigError] on an ambiguous pair, a bad shape, or a
+    #   gem that will not load
+    def self.load!(raw_config)
+      key, names = names_from(raw_config)
+      return if key.nil?
+
+      unless names.is_a?(Array) && names.all?(String)
+        raise Odysseus::ConfigError,
+              "`#{key}:` must be a list of gem names, got #{names.inspect}"
+      end
+
+      names.each { |name| require_plugin(name, key) }
+      nil
+    end
+
+    # Returns the key the config actually used alongside its value, so every
+    # diagnostic can quote the key the user wrote rather than whichever of the
+    # two aliases we happen to name first.
+    #
+    # @return [Array(String, Object)] the key and its value, or [nil, nil]
+    def self.names_from(raw_config)
+      present = KEYS.select { |key| raw_config.key?(key) }
+
+      if present.length > 1
+        raise Odysseus::ConfigError,
+              'deploy.yml has both `plugins:` and `sails:` — use one; they name the same thing'
+      end
+
+      present.empty? ? [nil, nil] : [present.first, raw_config[present.first]]
+    end
+
+    def self.require_plugin(name, key)
+      require name
+    rescue LoadError => e
+      raise Odysseus::ConfigError, load_failure_message(name, key, e)
+    end
+
+    # A plugin whose own `require` fails is installed already, so repeating the
+    # install advice sends the user after a gem they have. The two cases read
+    # differently, and both carry the file that was actually missing — without
+    # it, a sail missing its SDK is indistinguishable from a sail missing.
+    def self.load_failure_message(name, key, error)
+      if error.path && error.path != name
+        "The plugin `#{name}` named in deploy.yml is installed but failed to load: #{error.message}."
+      else
+        "Could not load the plugin `#{name}` named in deploy.yml (#{error.message}). Add it to your " \
+          "Gemfile or run `gem install #{name}`, or remove it from `#{key}:`."
+      end
+    end
+
+    private_class_method :names_from, :require_plugin, :load_failure_message
+  end
+end

data/lib/odysseus/retention_plan.rb

@@ -0,0 +1,14 @@
+# lib/odysseus/retention_plan.rb
+
+module Odysseus
+  # What retention decided for one host.
+  #
+  # remove  versions whose images should be deleted, **oldest first**, so a
+  #         partial failure leaves the newest behind
+  # keep    versions retained, newest first — reported so an operator can see
+  #         what the window covers without re-deriving it
+  #
+  # Both hold versions, not image references; the caller pairs them with the
+  # configured image name.
+  RetentionPlan = Data.define(:remove, :keep)
+end

data/lib/odysseus/retention_planner.rb

@@ -0,0 +1,58 @@
+# lib/odysseus/retention_planner.rb
+
+module Odysseus
+  # Chooses which of a service's image tags to delete from one host.
+  #
+  # Pure: handed what the host reports, returns a decision. That matters more
+  # here than anywhere else in odysseus, because the decision deletes data on a
+  # production host — so the rules are testable without a connection, and three
+  # independent things have to agree before anything is removed: the retain
+  # window, the set of versions containers still reference, and (at the caller)
+  # docker's own refusal to remove an image in use.
+  class RetentionPlanner
+    # Never removed automatically: a moving pointer, and pre-0.4.2 deploys were
+    # built from it, so something may still reference it.
+    PROTECTED_TAGS = ['latest'].freeze
+
+    # @param history [Array<Odysseus::DeployLog::Entry>] oldest first
+    # @param available [Array<String>] tags present on the host
+    # @param in_use [Array<String>] versions containers still reference
+    # @param retain [Integer] distinct versions to keep
+    def initialize(history:, available:, in_use:, retain:)
+      @history = history
+      @available = available
+      @in_use = in_use
+      @retain = retain
+    end
+
+    # @return [Odysseus::RetentionPlan]
+    def plan
+      RetentionPlan.new(remove: removable, keep: keep)
+    end
+
+    private
+
+    # Logged versions, newest deploy first, de-duplicated keeping the newest
+    # occurrence. Timestamps are fixed-width UTC ISO 8601, so they sort
+    # lexicographically. Same ordering RollbackPlanner ranks candidates by.
+    def ranked
+      @ranked ||= @history.sort_by(&:at).reverse.map(&:version).uniq
+    end
+
+    def keep
+      ranked.take(@retain)
+    end
+
+    # Oldest first: if the fifth removal fails, the four already gone were the
+    # least likely to be wanted.
+    def removable
+      (ranked - keep).reverse.select { |version| removable?(version) }
+    end
+
+    def removable?(version)
+      @available.include?(version) &&
+        !@in_use.include?(version) &&
+        !PROTECTED_TAGS.include?(version)
+    end
+  end
+end

data/lib/odysseus/rollback_plan.rb

@@ -0,0 +1,20 @@
+# lib/odysseus/rollback_plan.rb
+
+module Odysseus
+  # The decision a rollback acts on, settled before any host is touched.
+  #
+  # version    the tag every host will run
+  # ref        the commit that tag was built from, recovered from the host's
+  #            deploy log; nil when no log recorded it
+  # approximate true when no host had a deploy log and the ordering came from
+  #            image creation time, which is build time rather than deploy time
+  # replacing  host name => the version it is currently running (nil if none),
+  #            so each host's log records what it actually came from
+  RollbackPlan = Data.define(:version, :ref, :approximate, :replacing) do
+    # @param host [String]
+    # @return [String, nil] the version this host is rolling back from
+    def from_for(host)
+      replacing[host]
+    end
+  end
+end

data/lib/odysseus/rollback_planner.rb

@@ -0,0 +1,107 @@
+# lib/odysseus/rollback_planner.rb
+
+module Odysseus
+  # Chooses the version a rollback will deploy, from what the hosts report.
+  #
+  # Pure by design: it is handed surveys and returns a plan or raises. No SSH,
+  # no config, no git — so every rule below is testable with plain values, and
+  # the fleet pre-flight cannot be accidentally bypassed by a caller that
+  # already holds a connection.
+  class RollbackPlanner
+    # @param surveys [Array<Odysseus::HostVersions>] one per host, all roles
+    # @raise [Odysseus::RollbackError] when there are no hosts to act on
+    def initialize(surveys)
+      raise Odysseus::RollbackError, 'No hosts are configured, so there is nothing to roll back' if surveys.empty?
+
+      @surveys = surveys
+    end
+
+    # @param version [String, nil] explicit target, or nil for the previous one
+    # @return [Odysseus::RollbackPlan]
+    # @raise [Odysseus::RollbackError] when no target can be rolled back to
+    def plan(version: nil)
+      target = version || previous_version
+      raise Odysseus::RollbackError, no_candidate_message if target.nil?
+
+      ensure_present_everywhere!(target)
+
+      RollbackPlan.new(
+        version: target,
+        ref: ref_for(target),
+        approximate: logged_versions.empty?,
+        replacing: @surveys.to_h { |survey| [survey.host, survey.current] }
+      )
+    end
+
+    private
+
+    # The newest version every host can run and none is already running.
+    def previous_version
+      candidates.find { |version| present_everywhere?(version) && !serving_anywhere?(version) }
+    end
+
+    # Versions to consider, best first.
+    #
+    # The deploy log is preferred because image creation time is *build* time:
+    # images can reach a host out of order, and a rebuilt host can hold images
+    # it never served. With no log anywhere, docker's newest-first image order
+    # is the only signal available, and the plan is marked approximate.
+    def candidates
+      return logged_versions unless logged_versions.empty?
+
+      # No deploy log exists anywhere to name a specific version, so this is
+      # the fallback path. 'latest' is a moving pointer, not a version — the
+      # image tagged 'latest' today need not be the one that was running
+      # yesterday — so naming it as a rollback target is exactly the
+      # ambiguity this whole design exists to remove. Only excluded here: a
+      # version the log actually recorded is real and stays a candidate even
+      # if, unusually, it is literally tagged 'latest'.
+      @surveys.first.available.reject { |version| version == 'latest' }
+    end
+
+    # Every logged version across all hosts, newest deploy first, de-duplicated.
+    # DeployLog timestamps are fixed-width UTC ISO 8601, so they sort
+    # lexicographically; uniq keeps the newest occurrence of each version.
+    def logged_versions
+      @logged_versions ||= entries.sort_by(&:at).reverse.map(&:version).uniq
+    end
+
+    def entries
+      @entries ||= @surveys.flat_map(&:history)
+    end
+
+    def present_everywhere?(version)
+      @surveys.all? { |survey| survey.available?(version) }
+    end
+
+    def serving_anywhere?(version)
+      @surveys.any? { |survey| survey.current == version }
+    end
+
+    # The commit the target was built from, per the most recent log entry that
+    # mentions it. DeployLog writes '-' for a field it had no value for, which
+    # must read back as absent rather than as a commit called '-'.
+    def ref_for(target)
+      ref = entries.select { |entry| entry.version == target }.max_by(&:at)&.ref
+      ref unless ref.nil? || ref == '-'
+    end
+
+    def ensure_present_everywhere!(target)
+      missing = @surveys.reject { |survey| survey.available?(target) }.map(&:host)
+      return if missing.empty?
+
+      raise Odysseus::RollbackError,
+            "Image #{target} is missing on #{missing.join(', ')}, so rolling back would leave the " \
+            'fleet on mixed versions. Nothing was changed. Run `odysseus rollback --list` to see ' \
+            'what each host has.'
+    end
+
+    def no_candidate_message
+      running = @surveys.map { |survey| "#{survey.host} is running #{survey.current || 'nothing'}" }
+
+      "No version to roll back to (#{running.join('; ')}). A rollback needs a version that every " \
+        'host has an image for and that is not already serving. Run `odysseus rollback --list` to ' \
+        'see each host, or name a version explicitly.'
+    end
+  end
+end

data/lib/odysseus/secrets/encrypted_file.rb

@@ -8,8 +8,8 @@ require 'securerandom'
 module Odysseus
   module Secrets
     class EncryptedFile
-      CIPHER = 'aes-256-gcm'
-      KEY_ENV_VAR = 'ODYSSEUS_MASTER_KEY'
+      CIPHER = 'aes-256-gcm'.freeze
+      KEY_ENV_VAR = 'ODYSSEUS_MASTER_KEY'.freeze
 
       class DecryptionError < Odysseus::Error; end
       class MissingKeyError < Odysseus::Error; end
@@ -56,7 +56,7 @@ module Odysseus
       private
 
       def master_key
-        ENV[KEY_ENV_VAR]
+        ENV.fetch(KEY_ENV_VAR, nil)
       end
 
       def encrypt(data, key)
@@ -76,9 +76,7 @@ module Odysseus
         auth_tag = cipher.auth_tag
 
         # Combine: iv + auth_tag + encrypted_data, all base64 encoded
-        combined = Base64.strict_encode64(iv) + "\n" +
-                   Base64.strict_encode64(auth_tag) + "\n" +
-                   Base64.strict_encode64(encrypted)
+        combined = "#{Base64.strict_encode64(iv)}\n#{Base64.strict_encode64(auth_tag)}\n#{Base64.strict_encode64(encrypted)}"
 
         "# Odysseus encrypted secrets\n# Do not edit this file directly\n\n#{combined}"
       end
@@ -87,7 +85,7 @@ module Odysseus
         # Remove comments and empty lines
         lines = content.lines.reject { |l| l.start_with?('#') || l.strip.empty? }
 
-        raise DecryptionError, "Invalid encrypted file format" if lines.size < 3
+        raise DecryptionError, 'Invalid encrypted file format' if lines.size < 3
 
         iv = Base64.strict_decode64(lines[0].strip)
         auth_tag = Base64.strict_decode64(lines[1].strip)

data/lib/odysseus/secrets/loader.rb

@@ -22,9 +22,7 @@ module Odysseus
         path = resolve_path(secrets_file)
         encrypted = EncryptedFile.new(path)
 
-        unless encrypted.exists?
-          raise Odysseus::ConfigError, "Secrets file not found: #{path}"
-        end
+        raise Odysseus::ConfigError, "Secrets file not found: #{path}" unless encrypted.exists?
 
         @cached_secrets = encrypted.read
       end