odysseus-core 0.3.2 → 0.9.0

data/lib/odysseus/git.rb

@@ -0,0 +1,70 @@
+# lib/odysseus/git.rb
+
+require 'open3'
+
+module Odysseus
+  # Answers questions about a local git work tree. Knows nothing about deploys:
+  # the rules that turn these answers into a version live in VersionResolver.
+  class Git
+    # @param dir [String] directory inside the work tree
+    def initialize(dir)
+      @dir = dir
+    end
+
+    # @return [Boolean] true when dir is inside a git work tree
+    def repository?
+      _, status = capture('rev-parse', '--git-dir')
+      status.success?
+    end
+
+    # @param length [Integer] characters of the object name to return
+    # @return [String, nil] abbreviated commit sha of HEAD
+    def head_sha(length: 12)
+      out, status = capture('rev-parse', "--short=#{length}", 'HEAD')
+      status.success? && !out.empty? ? out : nil
+    end
+
+    # Tracked modifications only. Untracked files are reported separately: they
+    # are usually local noise, and blocking on them would make deploys hostile.
+    # @return [Boolean]
+    def uncommitted_changes?
+      out, status = capture('status', '--porcelain', '--untracked-files=no')
+      status.success? && !out.empty?
+    end
+
+    # @return [Boolean] true when the work tree has files git is not tracking
+    def untracked_files?
+      out, status = capture('ls-files', '--others', '--exclude-standard')
+      status.success? && !out.empty?
+    end
+
+    # @return [String, nil] branch name, or 'HEAD' when detached
+    def ref
+      out, status = capture('rev-parse', '--abbrev-ref', 'HEAD')
+      status.success? && !out.empty? ? out : nil
+    end
+
+    # @return [String, nil] user.email as git resolves it for this repository
+    def committer_email
+      out, status = capture('config', 'user.email')
+      status.success? && !out.empty? ? out : nil
+    end
+
+    private
+
+    def capture(*)
+      stdout, _stderr, status = Open3.capture3('git', *, chdir: @dir)
+      [stdout.strip, status]
+    rescue Errno::ENOENT
+      # git is not installed; treat as "not a repository" rather than crashing.
+      ['', FailedStatus.new]
+    end
+
+    # Stands in for a Process::Status when git could not be executed at all.
+    class FailedStatus
+      def success?
+        false
+      end
+    end
+  end
+end

data/lib/odysseus/host_paths.rb

@@ -0,0 +1,79 @@
+# lib/odysseus/host_paths.rb
+
+module Odysseus
+  # Where odysseus keeps its state on a target host.
+  #
+  # Root writes /var/lib/odysseus, which is where every install has always
+  # written and where existing hosts still have their deploy history. Any other
+  # user cannot create that directory, so their state goes under their own
+  # home. One class answers this so the deploy log, the env files, Caddy's
+  # data directory and — later — the deploy lock cannot disagree about where
+  # they live.
+  class HostPaths
+    SYSTEM_BASE = '/var/lib/odysseus'.freeze
+    USER_DIRNAME = '.odysseus'.freeze
+    ROOT = 'root'.freeze
+
+    # @param ssh [Odysseus::Deployer::SSH] connection whose user decides the base
+    def initialize(ssh)
+      @ssh = ssh
+      @base = nil
+    end
+
+    # @return [String] the directory all odysseus state lives under
+    def base
+      @base ||= @ssh.user == ROOT ? SYSTEM_BASE : File.join(home, USER_DIRNAME)
+    end
+
+    # @param service [String] the service: value from deploy.yml
+    # @return [String] that service's state directory
+    def service_dir(service)
+      File.join(base, service)
+    end
+
+    # @return [String] where env files are written for the length of a docker run
+    def env_dir
+      File.join(base, 'env')
+    end
+
+    # Caddy's /data mount: issued certificates, written by the container as
+    # root. For a root connection this resolves to exactly the path every
+    # install has always used, so existing certificates are found unmoved. A
+    # non-root connection gets a directory it can actually create — the
+    # earlier design left this fixed at the root path to protect those
+    # certificates, but that protection only ever applied to root: deriving it
+    # like every other path here protects root identically while letting a
+    # non-root deploy user create its own directory instead of failing at
+    # `mkdir`.
+    #
+    # Caddy is one container shared by every service on a host, so this only
+    # works cleanly with the one-deploy-user-per-host shape this class already
+    # assumes: two different deploy users on the same host would disagree
+    # about where Caddy's data lives, and whichever one first starts the
+    # container wins, since #ensure_running never recreates one already
+    # running.
+    # @return [String]
+    def caddy_dir
+      File.join(base, 'caddy')
+    end
+
+    # Where a root install wrote, whoever is connected now. Used to read the
+    # deploy history of a host that has since moved to a deploy user.
+    # @return [String]
+    def legacy_base
+      SYSTEM_BASE
+    end
+
+    private
+
+    # Asked once per connection and cached. A host that reports nothing is an
+    # error rather than a path of "/.odysseus", which would be unwritable and
+    # would only be noticed later, as a failed deploy.
+    def home
+      value = @ssh.execute('echo $HOME').to_s.strip
+      raise Odysseus::DeployError, "Could not determine the home directory of #{@ssh.user}" if value.empty?
+
+      value
+    end
+  end
+end

data/lib/odysseus/host_providers/base.rb

@@ -14,7 +14,7 @@ module Odysseus
       # Resolve and return list of hosts
       # @return [Array<String>] list of hostnames or IPs
       def resolve
-        raise NotImplementedError, "Subclasses must implement #resolve"
+        raise NotImplementedError, 'Subclasses must implement #resolve'
       end
 
       # Provider name for display/logging

data/lib/odysseus/host_providers/static.rb

@@ -17,7 +17,7 @@ module Odysseus
       end
 
       def name
-        "static"
+        'static'
       end
     end
   end

data/lib/odysseus/host_providers.rb

@@ -18,7 +18,7 @@ module Odysseus
           providers[:aws_asg].new(role_config[:aws])
         elsif role_config[:aws]
           raise Odysseus::ConfigError,
-                "AWS ASG host provider not available — is the odysseus-sail-aws-asg gem loaded?"
+                'AWS ASG host provider not available — is the odysseus-sail-aws-asg gem loaded?'
         elsif role_config[:hosts]
           Static.new(hosts: role_config[:hosts])
         else
@@ -38,9 +38,8 @@ module Odysseus
       # @param name [Symbol] provider name
       # @param klass [Class] provider class (must inherit from Base)
       def register(name, klass)
-        unless klass < Base
-          raise ArgumentError, "Provider must inherit from Odysseus::HostProviders::Base"
-        end
+        raise ArgumentError, 'Provider must inherit from Odysseus::HostProviders::Base' unless klass < Base
+
         providers[name] = klass
       end
     end

data/lib/odysseus/host_verifier.rb

@@ -0,0 +1,156 @@
+# lib/odysseus/host_verifier.rb
+
+require 'shellwords'
+
+module Odysseus
+  # Read-only diagnosis of whether one host is ready for odysseus to deploy to
+  # it AS THE USER THE CONFIG NAMES.
+  #
+  # That last part is the point. Verifying as root would pass on a host the
+  # deploy user cannot use, which is the failure this exists to catch — a deploy
+  # that dies at the first container start because a directory is not writable.
+  #
+  # Nothing here writes to the host. A check that would need to write in order
+  # to learn something reports that it cannot tell instead.
+  #
+  # Caddy's data directory is deliberately absent from these checks: it does not
+  # exist until the first deploy starts Caddy, so a correctly configured host
+  # that has not deployed yet would be reported broken.
+  class HostVerifier
+    # Named explicitly rather than computed, so supporting a new LTS is a
+    # deliberate edit with a tested host behind it, not something that becomes
+    # true on a date.
+    SUPPORTED_UBUNTU = %w[24.04 26.04].freeze
+    ROOT = 'root'.freeze
+
+    # @param check [Symbol] which check this is
+    # @param status [Symbol] :ok, :warn or :fail
+    # @param detail [String] one line a reader can act on
+    Result = Data.define(:check, :status, :detail)
+
+    def initialize(ssh:, config:)
+      @ssh = ssh
+      @config = config
+    end
+
+    # @return [Array<Result>] one per check, in a stable order
+    def verify
+      [distro, docker, docker_group, state_dir, deploy_log]
+    end
+
+    private
+
+    def root?
+      @ssh.user == ROOT
+    end
+
+    def host_paths
+      @host_paths ||= Odysseus::HostPaths.new(@ssh)
+    end
+
+    def distro
+      os = read_os_release
+      id = os['ID']
+      version = os['VERSION_ID']
+
+      if id == 'ubuntu' && SUPPORTED_UBUNTU.include?(version)
+        Result.new(check: :distro, status: :ok, detail: "ubuntu #{version}")
+      else
+        # A warning, not a failure: odysseus deploys to any host with Docker.
+        # SUPPORTED_UBUNTU is what odysseus is tested against, not a
+        # requirement.
+        Result.new(
+          check: :distro, status: :warn,
+          detail: "#{id || 'unknown'} #{version}".strip +
+                  " — not ubuntu #{SUPPORTED_UBUNTU.join(' or ')}; deploys work anywhere Docker does"
+        )
+      end
+    end
+
+    def docker
+      output = @ssh.execute("docker info --format '{{.ServerVersion}}' 2>&1 || true")
+      version = output.to_s.strip
+
+      if version.match?(/\A\d+\./)
+        Result.new(check: :docker, status: :ok, detail: "docker #{version}")
+      else
+        Result.new(
+          check: :docker, status: :fail,
+          detail: "the docker daemon did not answer as #{@ssh.user}: #{version.lines.first.to_s.strip}"
+        )
+      end
+    end
+
+    def docker_group
+      # root does not need the group, and saying it is missing would be a false
+      # alarm on every root install — still the default.
+      return Result.new(check: :docker_group, status: :ok, detail: 'not needed for root') if root?
+
+      groups = @ssh.execute("id -nG #{Shellwords.escape(@ssh.user)} 2>/dev/null || true").to_s.split
+
+      if groups.include?('docker')
+        Result.new(check: :docker_group, status: :ok, detail: "#{@ssh.user} is in the docker group")
+      else
+        Result.new(
+          check: :docker_group, status: :fail,
+          detail: "#{@ssh.user} is not in the docker group (has: #{groups.join(' ')})"
+        )
+      end
+    end
+
+    def state_dir
+      dir = host_paths.base
+      # Check the nearest existing ancestor: the directory itself may legitimately
+      # not exist yet on a host that has never deployed, and creating it to find
+      # out is exactly what this command must not do.
+      probe = Shellwords.escape(dir)
+      output = @ssh.execute(
+        "d=#{probe}; while [ ! -e \"$d\" ] && [ \"$d\" != / ]; do d=$(dirname \"$d\"); done; " \
+        'if test -w "$d"; then echo writable; else echo "not writable:$d"; fi'
+      ).to_s.strip
+
+      if output == 'writable'
+        Result.new(check: :state_dir, status: :ok, detail: "#{dir} is writable")
+      else
+        Result.new(
+          check: :state_dir, status: :fail,
+          detail: "#{dir} is not writable by #{@ssh.user} (#{output.split(':').last} is not)"
+        )
+      end
+    end
+
+    def deploy_log
+      path = File.join(host_paths.service_dir(@config[:service]), Odysseus::DeployLog::FILENAME)
+      legacy = File.join(host_paths.legacy_base, @config[:service], Odysseus::DeployLog::FILENAME)
+
+      # For root, path and legacy are always the same string: HostPaths#base
+      # resolves to legacy_base for root, so this already covers root without
+      # a separate root? check — one that could never change the outcome.
+      return Result.new(check: :deploy_log, status: :ok, detail: path) if legacy == path
+
+      present = @ssh.execute("test -e #{Shellwords.escape(legacy)} && echo present || echo absent").to_s.strip
+
+      if present == 'present'
+        # Losing this is silent — rollback just offers fewer versions — so it is
+        # worth a warning rather than a note.
+        Result.new(
+          check: :deploy_log, status: :warn,
+          detail: "#{path}; root-era history still at #{legacy}, readable but not writable by #{@ssh.user}"
+        )
+      else
+        Result.new(check: :deploy_log, status: :ok, detail: path)
+      end
+    end
+
+    def read_os_release
+      raw = @ssh.execute('cat /etc/os-release 2>/dev/null || true').to_s
+
+      raw.lines.each_with_object({}) do |line, acc|
+        key, value = line.strip.split('=', 2)
+        next if key.nil? || value.nil?
+
+        acc[key] = value.delete('"')
+      end
+    end
+  end
+end

data/lib/odysseus/host_versions.rb

@@ -0,0 +1,59 @@
+# lib/odysseus/host_versions.rb
+
+module Odysseus
+  # What one host knows about one service's versions: what is serving now, what
+  # it could serve (images present), and what it has served (its deploy log).
+  #
+  # Hosts are authoritative for rollback. A developer's checkout and the git
+  # notes history can both drift from what a host can actually run — a rebuilt
+  # host, a pruned image, a change made by hand — so the target is chosen from
+  # this, never from the repository.
+  HostVersions = Data.define(:host, :current, :available, :history) do
+    # Read one host's state. Caller owns the connection and closes it.
+    #
+    # @param host [String] host name, for reporting
+    # @param ssh [Odysseus::Deployer::SSH] open connection to that host
+    # @param service [String] the service name from deploy.yml
+    # @param image [String] the repository from deploy.yml, without a tag
+    # @param roles [Array<Symbol>] the roles this host serves, in config order.
+    #   current scans them in this order and stops at the first that is
+    #   serving, so a host whose web role is down but whose jobs role is up
+    #   still reports something rather than nil.
+    # @return [HostVersions]
+    def self.read(host:, ssh:, service:, image:, roles:)
+      docker = Odysseus::Docker::Client.new(ssh)
+
+      new(
+        host: host,
+        current: current_version(docker, service, roles),
+        available: docker.image_tags(image),
+        history: Odysseus::DeployLog.new(ssh: ssh, service: service).entries
+      )
+    end
+
+    # The version label of the first running container of the first role, in
+    # role order, that is actually serving. WebDeploy and JobDeploy label
+    # their containers differently (see Docker::Labels.service_for), so each
+    # role must be queried under its own label or a non-web role reports
+    # nothing running.
+    def self.current_version(docker, service, roles)
+      roles.each do |role|
+        label = Odysseus::Docker::Labels.service_for(service: service, role: role)
+        version = docker.list(service: label)
+                        .filter_map { |container| Odysseus::Docker::Labels.version_of(container) }
+                        .first
+        return version if version
+      end
+
+      nil
+    end
+
+    private_class_method :current_version
+
+    # @param version [String]
+    # @return [Boolean] whether this host has an image tagged that way
+    def available?(version)
+      available.include?(version)
+    end
+  end
+end