odysseus-core 0.3.2 → 0.9.0

data/lib/odysseus/caddy/client.rb

@@ -1,13 +1,14 @@
 # lib/odysseus/caddy/client.rb
 
 require 'json'
+require 'shellwords'
 
 module Odysseus
   module Caddy
     class Client
       ADMIN_API_PORT = 2019
-      CONTAINER_NAME = 'odysseus-caddy'
-      CADDY_IMAGE = 'caddy:2-alpine'
+      CONTAINER_NAME = 'odysseus-caddy'.freeze
+      CADDY_IMAGE = 'caddy:2-alpine'.freeze
 
       # @param ssh [Odysseus::Deployer::SSH] SSH connection to server
       # @param docker [Odysseus::Docker::Client] Docker client
@@ -17,10 +18,28 @@ module Odysseus
       end
 
       # Ensure Caddy is running
+      #
+      # There are three states, not two: running, absent, and stopped-but-
+      # present. Docker refuses `docker run --name odysseus-caddy` while a
+      # container by that name already exists, so a stopped Caddy would
+      # otherwise fail every deploy after it, forever.
+      #
+      # A stopped container is removed rather than `docker start`ed. It
+      # carries whatever configuration it was *created* with, including its
+      # volume mount — and this branch changed Caddy's data directory from a
+      # fixed system path to one derived from the deploy user (see
+      # Odysseus::HostPaths#caddy_dir). `docker start` would silently
+      # resurrect a container mounting the old path while everything else
+      # believes it moved. Recreating always applies current configuration.
+      # Nothing is lost: certificates live in the mounted volume, and routes
+      # are re-added by the deploy that follows.
+      #
       # @return [Boolean] true if caddy is running
       def ensure_running
         return true if running?
 
+        @docker.remove(CONTAINER_NAME) if @docker.container_exists?(CONTAINER_NAME)
+
         start_caddy
         running?
       end
@@ -34,21 +53,35 @@ module Odysseus
       # Start Caddy container
       def start_caddy
         # Create network if not exists (with label to protect from prune)
-        @ssh.execute("docker network create --label odysseus.managed=true odysseus 2>/dev/null || true")
+        @ssh.execute('docker network create --label odysseus.managed=true odysseus 2>/dev/null || true')
 
         # Create data directory for certificates
-        @ssh.execute("mkdir -p /var/lib/odysseus/caddy")
+        @ssh.execute("mkdir -p #{Shellwords.escape(host_paths.caddy_dir)}")
 
         # Run Caddy with admin API enabled and persistent storage for certs
+        #
+        # The mkdir above and this mount must name the same directory, or
+        # Caddy starts against an empty one and silently has no certificates.
+        # Docker::Client interpolates `-v` values into its command line
+        # unescaped, so the directory is escaped here rather than there.
+        #
+        # The admin API is published on loopback only: it can rewrite the
+        # proxy config for every service on the host, and #api_request only
+        # ever reaches it via `curl localhost` over SSH, so nothing needs it
+        # exposed beyond the host itself. CADDY_ADMIN must stay bound to
+        # 0.0.0.0 *inside* the container regardless — that is what the
+        # published port maps to, and binding it to 127.0.0.1 there would put
+        # it behind the container's own loopback, unreachable even from the
+        # host.
         @docker.run(
           name: CONTAINER_NAME,
           image: CADDY_IMAGE,
           options: {
             service: 'odysseus-proxy',
-            ports: ['80:80', '443:443', "#{ADMIN_API_PORT}:#{ADMIN_API_PORT}"],
+            ports: ['80:80', '443:443', "127.0.0.1:#{ADMIN_API_PORT}:#{ADMIN_API_PORT}"],
             network: 'odysseus',
             restart: 'unless-stopped',
-            volumes: ['/var/lib/odysseus/caddy:/data'],
+            volumes: ["#{Shellwords.escape(host_paths.caddy_dir)}:/data"],
             env: {
               'CADDY_ADMIN' => "0.0.0.0:#{ADMIN_API_PORT}"
             },
@@ -74,7 +107,7 @@ module Odysseus
         enable_tls_for_hosts(hosts, email: ssl_email) if ssl
 
         # Check if route already exists for this service
-        routes = api_request('GET', "/config/apps/http/servers/srv0/routes") || []
+        routes = api_request('GET', '/config/apps/http/servers/srv0/routes') || []
         existing_idx = routes.find_index { |r| r['@id'] == "route-#{service}" }
 
         if existing_idx
@@ -88,7 +121,8 @@ module Odysseus
           current_upstreams = routes[existing_idx].dig('handle', 0, 'upstreams') || []
           unless current_upstreams.any? { |u| u['dial'] == upstream }
             current_upstreams << { 'dial' => upstream }
-            api_request('PATCH', "/config/apps/http/servers/srv0/routes/#{existing_idx}/handle/0/upstreams", current_upstreams)
+            api_request('PATCH', "/config/apps/http/servers/srv0/routes/#{existing_idx}/handle/0/upstreams",
+                        current_upstreams)
           end
         else
           # Create new route - prepend at index 0 so it matches before default routes
@@ -98,7 +132,7 @@ module Odysseus
             upstreams: [upstream],
             healthcheck: healthcheck
           )
-          api_request('PUT', "/config/apps/http/servers/srv0/routes/0", config)
+          api_request('PUT', '/config/apps/http/servers/srv0/routes/0', config)
         end
       end
 
@@ -107,12 +141,12 @@ module Odysseus
       # @param upstream [String, nil] upstream to remove, or nil to remove entire route
       def remove_upstream(service:, upstream:)
         # Get current config
-        routes = api_request('GET', "/config/apps/http/servers/srv0/routes")
+        routes = api_request('GET', '/config/apps/http/servers/srv0/routes')
         return unless routes
 
         # Find route for this service and remove the upstream
         routes.each_with_index do |route, idx|
-          next unless route.dig('@id') == "route-#{service}"
+          next unless route['@id'] == "route-#{service}"
 
           # If no specific upstream, remove the entire route
           if upstream.nil?
@@ -195,7 +229,7 @@ module Odysseus
             service: service_name,
             hosts: hosts,
             upstreams: upstreams.map { |u| u['dial'] },
-            has_healthcheck: route.dig('handle', 0, 'health_checks').nil? ? false : true
+            has_healthcheck: !route.dig('handle', 0, 'health_checks').nil?
           }
         end
       end
@@ -240,9 +274,11 @@ module Odysseus
       # @param hosts [Array<String>] domain hosts
       # @param email [String] email for Let's Encrypt
       def enable_tls_for_hosts(hosts, email: nil)
-        # Get existing TLS config to merge with
-        existing_tls = api_request('GET', '/config/apps/tls') || {}
-        existing_policies = existing_tls.dig('automation', 'policies') || []
+        # nil means Caddy has no tls app yet, whether it answered with an error or
+        # a null body for the missing path. That distinction picks the verb below.
+        existing_tls = api_request('GET', '/config/apps/tls')
+        existing_automation = existing_tls&.dig('automation') || {}
+        existing_policies = existing_automation['policies'] || []
 
         # Collect all existing subjects
         all_subjects = existing_policies.flat_map { |p| p['subjects'] || [] }
@@ -256,20 +292,23 @@ module Odysseus
         issuer = { 'module' => 'acme' }
         issuer['email'] = email if email
 
-        # Configure TLS automation with Let's Encrypt (single policy for all domains)
-        tls_config = {
-          'automation' => {
-            'policies' => [
-              {
-                'subjects' => all_subjects,
-                'issuers' => [issuer]
-              }
-            ]
-          }
-        }
+        # One policy covering every domain, merged onto whatever else the tls app
+        # holds: writing only our automation block would drop sibling settings
+        # such as explicit certificate loaders or on_demand limits that other
+        # services on this host may depend on.
+        tls_config = (existing_tls || {}).merge(
+          'automation' => existing_automation.merge(
+            'policies' => [{ 'subjects' => all_subjects, 'issuers' => [issuer] }]
+          )
+        )
 
-        # Use PUT to create/replace TLS config
-        api_request('PUT', '/config/apps/tls', tls_config)
+        # Caddy's PUT creates and answers 409 if the key is already there; PATCH
+        # replaces and fails if it is not. Neither one is an upsert on its own.
+        if existing_tls.nil?
+          api_request('PUT', '/config/apps/tls', tls_config)
+        else
+          api_request('PATCH', '/config/apps/tls', tls_config)
+        end
 
         # Ensure HTTPS server exists and listens on 443
         ensure_https_server
@@ -277,18 +316,22 @@ module Odysseus
 
       private
 
+      def host_paths
+        @host_paths ||= Odysseus::HostPaths.new(@ssh)
+      end
+
       def ensure_https_server
         # Check if we have an HTTPS server configured
         servers = api_request('GET', '/config/apps/http/servers') || {}
 
-        unless servers['srv0']&.dig('listen')&.include?(':443')
-          # Add :443 to listen addresses
-          current_listen = servers.dig('srv0', 'listen') || [':80']
-          unless current_listen.include?(':443')
-            current_listen << ':443'
-            api_request('PATCH', '/config/apps/http/servers/srv0/listen', current_listen)
-          end
-        end
+        return if servers['srv0']&.dig('listen')&.include?(':443')
+
+        # Add :443 to listen addresses
+        current_listen = servers.dig('srv0', 'listen') || [':80']
+        return if current_listen.include?(':443')
+
+        current_listen << ':443'
+        api_request('PATCH', '/config/apps/http/servers/srv0/listen', current_listen)
       end
 
       def build_route_config(service:, hosts:, upstreams:, healthcheck: nil)
@@ -325,19 +368,53 @@ module Odysseus
         route
       end
 
+      # Call Caddy's admin API over SSH.
+      #
+      # curl exits 0 for HTTP errors, so the status code is appended to the
+      # response with -w and split back off here. A rejected write leaves the
+      # proxy in a state the caller must know about, so it raises; a failed read
+      # returns nil, because Caddy answers 500 for config paths that simply do
+      # not exist yet (no tls app on a freshly booted proxy, for instance).
+      #
+      # @raise [Odysseus::ProxyApiError] if a mutating request returns HTTP >= 400
       def api_request(method, path, body = nil)
-        # Build curl command to hit Caddy's admin API
-        cmd = "curl -s -X #{method} "
+        cmd = "curl -s -w '\\n%{http_code}' -X #{method} "
         cmd += "-H 'Content-Type: application/json' "
         cmd += "-d '#{body.to_json}' " if body
         cmd += "http://localhost:#{ADMIN_API_PORT}#{path}"
 
-        output = @ssh.execute(cmd)
-        return nil if output.strip.empty?
+        response_body, status = split_status(@ssh.execute(cmd))
+
+        if status && status >= 400
+          return nil if method == 'GET'
+
+          raise Odysseus::ProxyApiError, api_error_message(method, path, status, response_body)
+        end
+
+        return nil if response_body.strip.empty?
 
-        JSON.parse(output)
+        JSON.parse(response_body)
       rescue JSON::ParserError
-        output
+        response_body
+      end
+
+      # Split curl's trailing '%{http_code}' line off the response body.
+      # Returns a nil status when no status line is present.
+      def split_status(output)
+        text = output.to_s.sub(/\s+\z/, '')
+        newline_idx = text.rindex("\n")
+        trailer = newline_idx ? text[(newline_idx + 1)..] : text
+
+        return [output.to_s, nil] unless trailer&.match?(/\A\d{3}\z/)
+
+        [newline_idx ? text[0...newline_idx] : '', trailer.to_i]
+      end
+
+      def api_error_message(method, path, status, response_body)
+        message = "Caddy admin API #{method} #{path} failed with HTTP #{status}"
+        details = response_body.to_s.strip
+        message += ": #{details}" unless details.empty?
+        message
       end
     end
   end

data/lib/odysseus/command_redaction.rb

@@ -0,0 +1,38 @@
+# lib/odysseus/command_redaction.rb
+
+module Odysseus
+  # Hides secrets in a command string before it is printed.
+  #
+  # This runs on the way to the terminal only -- the command executed is always
+  # the real one. It lives in core rather than in the CLI's UI because the layer
+  # that echoes commands under --debug/-v is SSH#execute, and it echoes every
+  # command, not the handful the CLI wraps in its own redacting IO.
+  #
+  # The case that prompted it: registry login builds
+  # `echo '<password>' | docker login <server> -u <user> --password-stdin`
+  # (builder/client.rb). --password-stdin exists to keep a password off the
+  # argv, and interpolating it into `echo '...'` puts it straight back into the
+  # command string -- with no -p and no --password, so every pattern written to
+  # catch those misses it entirely.
+  module CommandRedaction
+    PLACEHOLDER = '[REDACTED]'.freeze
+
+    # Anything piped into a command that reads a secret from stdin. Matched by
+    # what the pipe FEEDS rather than by the flag, since the flag's whole point
+    # is that the secret is not one of its arguments.
+    STDIN_PIPE = /(echo\s+)(['"]).*?\2(\s*\|\s*\S*(?:docker\s+login|--password-stdin))/m
+    SHORT_FLAG = /(\s-p\s+)\S+/
+    LONG_FLAG = /(--password[= ])\S+/
+    ASSIGNMENT = /((?:KEY|TOKEN|SECRET|PASSWORD|MASTER_KEY|API_KEY|CREDENTIALS)\s*=\s*)\S+/i
+
+    # @param command [String] the command as it would be sent
+    # @return [String] the command as it is safe to print
+    def self.redact(command)
+      command.to_s
+             .gsub(STDIN_PIPE) { "#{Regexp.last_match(1)}'#{PLACEHOLDER}'#{Regexp.last_match(3)}" }
+             .gsub(SHORT_FLAG, "\\1#{PLACEHOLDER}")
+             .gsub(LONG_FLAG, "\\1#{PLACEHOLDER}")
+             .gsub(ASSIGNMENT, "\\1#{PLACEHOLDER}")
+    end
+  end
+end

data/lib/odysseus/config/parser.rb

@@ -5,6 +5,11 @@ require 'yaml'
 module Odysseus
   module Config
     class Parser
+      # Distinct versions of a service's image kept on each host. Five is enough
+      # to roll back through a bad week; the images share layers, so the cost of
+      # keeping a few is small.
+      DEFAULT_RETAIN_VERSIONS = 5
+
       # @param config_path [String] Path to deploy.yml
       def initialize(config_path)
         @config_path = config_path
@@ -15,6 +20,7 @@ module Odysseus
       # @raise [Odysseus::ConfigError] if invalid
       def parse
         raw_config = load_yaml
+        Odysseus::Plugins.load!(raw_config)
         validate!(raw_config)
         normalize(raw_config)
       rescue Psych::SyntaxError => e
@@ -46,9 +52,10 @@ module Odysseus
           env: parse_env(config['env']),
           secrets_file: config['secrets_file'],
           ssh: parse_ssh(config['ssh']),
-          accessories: parse_accessories(config['accessories']),
+          dependencies: parse_dependencies(dependencies_config(config)),
           builder: parse_builder(config['builder']),
-          registry: parse_registry(config['registry'])
+          registry: parse_registry(config['registry']),
+          retain_versions: config['retain_versions'] || DEFAULT_RETAIN_VERSIONS
         }
       end
 
@@ -96,14 +103,14 @@ module Odysseus
       end
 
       # Parse deploy-level health check (HTTP polling with threshold)
-      def parse_deploy_health_check(hc)
-        return nil unless hc
+      def parse_deploy_health_check(health_check)
+        return nil unless health_check
 
         {
-          path: hc['path'] || '/up',
-          interval: hc['interval'] || 2,
-          threshold: hc['threshold'] || 3,
-          timeout: hc['timeout'] || 5
+          path: health_check['path'] || '/up',
+          interval: health_check['interval'] || 2,
+          threshold: health_check['threshold'] || 3,
+          timeout: health_check['timeout'] || 5
         }
       end
 
@@ -179,11 +186,29 @@ module Odysseus
         }
       end
 
-      # Parse accessories config
-      def parse_accessories(accessories)
-        return {} unless accessories
+      # `accessories:` is the former name, still accepted. Both present is an
+      # error rather than a silent preference: a config with two contradictory
+      # lists should say so.
+      def dependencies_config(config)
+        if config.key?('dependencies') && config.key?('accessories')
+          raise Odysseus::ConfigError,
+                'deploy.yml has both `dependencies:` and `accessories:` — use one; ' \
+                '`accessories:` is the former name'
+        end
+
+        config['dependencies'] || config['accessories']
+      end
+
+      # Parse dependencies config — the supporting services a deploy needs
+      # (a database, a cache, a search index).
+      #
+      # Accepts the former `accessories:` key as well; the caller resolves
+      # which one was present. Kept because renaming a deploy.yml key should
+      # not be a flag day for every app repository.
+      def parse_dependencies(dependencies)
+        return {} unless dependencies
 
-        accessories.each_with_object({}) do |(name, config), acc|
+        dependencies.each_with_object({}) do |(name, config), acc|
           acc[name.to_sym] = {
             image: config['image'],
             hosts: config['hosts'],
@@ -191,14 +216,14 @@ module Odysseus
             ports: config['ports'],
             volumes: config['volumes'],
             env: parse_env(config['env']),
-            healthcheck: parse_accessory_healthcheck(config['healthcheck']),
-            proxy: parse_accessory_proxy(config['proxy'])
+            healthcheck: parse_dependency_healthcheck(config['healthcheck']),
+            proxy: parse_dependency_proxy(config['proxy'])
           }
         end
       end
 
-      # Parse accessory healthcheck
-      def parse_accessory_healthcheck(healthcheck)
+      # Parse dependency healthcheck
+      def parse_dependency_healthcheck(healthcheck)
         return nil unless healthcheck
 
         {
@@ -209,8 +234,8 @@ module Odysseus
         }
       end
 
-      # Parse accessory proxy config
-      def parse_accessory_proxy(proxy)
+      # Parse dependency proxy config
+      def parse_dependency_proxy(proxy)
         return nil unless proxy
 
         {

data/lib/odysseus/core/deploy_versioning.rb

@@ -0,0 +1,42 @@
+# lib/odysseus/core/deploy_versioning.rb
+
+module Odysseus
+  module Core
+    # The identity a deployed container carries: which version it is, which
+    # commit it came from, and when it was deployed.
+    #
+    # Shared rather than duplicated because `status`, `rollback` and image
+    # retention all read these labels, so an orchestrator that invents its own
+    # scheme becomes invisible to them. odysseus-sail-rolling did exactly that
+    # — it stamped odysseus.version with a timestamp, which meant retention's
+    # in-use guard could never match a version from the deploy log.
+    #
+    # The including class must expose @config.
+    #
+    # Both helpers are private, as they were before the extraction: they are
+    # how an orchestrator labels its own containers, not something to call on
+    # one from outside. VolumeNamespacer keeps its internals private the same
+    # way.
+    module DeployVersioning
+      private
+
+      # The version this deploy identifies. Falls back to the tag in the image
+      # reference so a caller passing --image still gets a self-describing name.
+      def deploy_version_tag(image)
+        resolved = @config[:deploy_version]
+        return resolved.version if resolved
+
+        image.to_s.split(':').last
+      end
+
+      # deployed_at replaces the timestamp odysseus.version used to hold;
+      # git_ref is only known when the version came from a commit.
+      def version_labels
+        labels = { 'odysseus.deployed_at' => Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ') }
+        resolved = @config[:deploy_version]
+        labels['odysseus.git_ref'] = resolved.ref if resolved&.ref
+        labels
+      end
+    end
+  end
+end

data/lib/odysseus/core/environment.rb

@@ -0,0 +1,63 @@
+# lib/odysseus/core/environment.rb
+
+module Odysseus
+  module Core
+    # The environment a container starts with: the clear values from deploy.yml
+    # merged with the secret ones, each read from the encrypted secrets file
+    # when one is configured and from the deploy target's own environment
+    # otherwise. A secret that is set in neither place is left out rather than
+    # injected empty.
+    #
+    # A class, where the neighbouring DeployVersioning and VolumeNamespacer are
+    # mixins. Those are only ever included by orchestrators, which all carry
+    # @config, @ssh and @secrets_loader, so a mixin costs them nothing. This one
+    # has a third caller: the CLI's one-off commands (`app exec`, `shell`,
+    # `console`) need the same environment, and the CLI is not an orchestrator —
+    # it has none of those ivars. Passing the collaborators in is what makes the
+    # code reusable from there; a mixin would make the CLI grow state it has no
+    # other use for just to satisfy this module's expectations.
+    class Environment
+      # @param config [Hash] parsed deploy config; only config[:env] is read
+      # @param secrets_loader [Odysseus::Secrets::Loader, nil] encrypted secrets, when configured
+      # @param ssh [Odysseus::Deployer::SSH] connection used to read the host's own environment
+      def initialize(config:, secrets_loader:, ssh:)
+        @config = config
+        @secrets_loader = secrets_loader
+        @ssh = ssh
+      end
+
+      # @return [Hash{String => String}] variables to inject into the container
+      def build
+        env_config = @config[:env] || {}
+        env = {}
+
+        # Clear env vars (hardcoded values)
+        env_config[:clear]&.each do |key, value|
+          env[key.to_s] = value.to_s
+        end
+
+        # Secret env vars - first try encrypted file, then server environment
+        env_config[:secret]&.each do |key|
+          value = secret_value(key)
+          env[key.to_s] = value if value
+        end
+
+        env
+      end
+
+      private
+
+      # @return [String, nil] the secret's value, nil when it is set nowhere
+      def secret_value(key)
+        if @secrets_loader&.configured?
+          value = @secrets_loader.get(key)
+          return value.to_s if value
+        end
+
+        # Fall back to server's environment
+        value = @ssh.execute("echo $#{key}").strip
+        value unless value.empty?
+      end
+    end
+  end
+end

data/lib/odysseus/core/version.rb

@@ -2,6 +2,6 @@
 
 module Odysseus
   module Core
-    VERSION = "0.3.2"
+    VERSION = '0.9.0'
   end
 end

data/lib/odysseus/core.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "core/version"
-require_relative "core/volume_namespacer"
+require_relative 'core/version'
+require_relative 'core/volume_namespacer'
 
 module Odysseus
   module Core