herd-rb 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84702715cdf7b1c28fe203c5c88a0b0f7a3c0a77bf5bfb237c027a82585be7c0
-  data.tar.gz: d61aa1dcbe955f6ab0bd56c535612cf490891ed2589425af1ac23baf6e085636
+  metadata.gz: ad0f13503109d91f099f4b40a1c208bafd460fd6efbcfe8d15cb92c3d0bad66b
+  data.tar.gz: 2a793b3ff5246eabb9ea55cd67b507786b1226afc40ace46208737176f0bd4df
 SHA512:
-  metadata.gz: c2f6c111802762b7c5e642a1a8f073d9bad60c138f5d607870a4989154777aa2691997ca514ef440237d73b4112107a72dffe17b1c3221aab0d7663440be70bf
-  data.tar.gz: b65a40974cee1729989bfc9c65a95b937e101c71072daa2da4cf70475cd04ce8de65ab4483e1dfbf4301bcc27a4bcbe149a9c07119619190bde82f052c1eee1e
+  metadata.gz: 2a2b263aec47c102e8d60069352b46814032a90b546928bb5a7cb4ed5ee2cae93cfc05e2b153e71a0366249c4e59a8a84903a5f3e6c7efd34de1a2d7771023b0
+  data.tar.gz: 02e6e5e6bd999632457f7521ae443fa55847d8ef9d8a563cc01b5fcf5a9a3f033064e06b869b36962170ba134006decee2e104f73e9dbaeae863d35715b4d2e7

data/.ruby-version

@@ -0,0 +1 @@
+3.4.2

data/README.md

@@ -4,9 +4,15 @@ Fast host configuration tool.
 
 ## TODO
 
-* [ ] Commands with arguments
-* [ ] Reading and writing files
-* [ ] Run with `sudo`
+* [x] Run with `sudo`
+* [x] Commands with arguments
+* [x] Reading and writing files
+* [x] Templates (ERB)
+* [x] Copy dirs
+  * [ ] Compare with Rsync
+* [x] Crontab
+* [ ] Log all commands for all hosts
+* [ ] Add user to group
 
 ## Installation
 
@@ -55,6 +61,89 @@ runner.exec("hostname") # ["alpha001\n", "omega001\n"]
 runner.exec { hostname + uptime } # ["alpha001\n2000 years\n", "omega001\2500 years\n"]
 ```
 
+List of hosts can be loaded from the CSV file:
+
+```ruby
+# hosts.csv
+host,port,user,password,some_param1,some_param2
+alpha.tesla.com,2022,elon,T0pS3kr3t,value1,value2
+omega.tesla.com,2023,elon,T0pS3kr3t2,value3,value4
+```
+
+```ruby
+hosts = Herd::Host.from_csv("hosts.csv")
+runner = Herd::Runner.new(hosts)
+...
+```
+
+### Something more complex
+
+```ruby
+public_key_path = File.expand_path("~/.ssh/id_ed25519.pub")
+my_key = File.read(public_key_path).chomp
+
+result = runner.exec do
+  h = hostname
+  keys = authorized_keys
+
+  if keys.include?(my_key)
+    puts "Key already in authorized_keys on host #{h}"
+  else
+    add_authorized_key my_key
+    puts "Added new key for host #{h}"
+  end
+end
+
+# or even simpler
+my_key2 = "ssh-ed25519 ..."
+
+result = runner.exec do
+  authorized_keys_contains_exactly([my_key, my_key2])
+end
+```
+
+### Files and directories
+
+Following example takes file from the `./files/etc/sudoers.d/50-elon`
+and copy content to the remote host with required permissions.
+
+```ruby
+result = runner.exec do
+  file("/etc/sudoers.d/50-elon", "root", "root", 440)
+
+  # or copy dirs
+  dir("/home/elon/projects", "elon", "elon")
+end
+```
+
+### Templates
+
+Following example takes ERB template from the `./templates/home/elon/.env.erb`
+and renders using additional `Herd::Host` values and copies content to the remote host
+`/home/elon/.env`:
+
+```erb
+# File: ./templates/home/elon/.env.erb
+export ALIAS=<%= alias %>
+```
+
+```ruby
+host = Herd::Host.new("tesla.com", "elon", password: "T0pS3kr3t", alias: "alpha001")
+runner = Runner.new([host])
+runner.exec do |values|
+  # values contain named arguments (except password and public_key_path) 
+  # from the host constructor:
+  # { host: "tesla.com", port: 22, user: "elon", alias: "alpha001" }
+  template("/home/elon/.env", "elon", "wheels", values: values)
+end
+```
+
+### Crontab
+
+```ruby
+crontab("* * * * * /some-script.sh")
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/TODO.md

@@ -0,0 +1,20 @@
+# TODO
+
+- [x] Load session commands automatically from `lib/herd/session/commands`.
+- [x] Extract existing `Session` command helpers (e.g., `add_authorized_key`) into the commands directory.
+- [x] Ensure new command loading approach is covered by specs.
+- [ ] Add explicit `logger` dependency to address net-ssh warning on Ruby 3.4.2.
+- [ ] Document new command-extension flow with YARD annotations.
+
+# Log
+
+- Initialized planning file and seeded initial task list.
+- Updated project configuration to target Ruby 3.4.2 (Gemfile, gemspec, .ruby-version, lockfile).
+- Synced RuboCop config with Ruby 3.4.2 and confirmed clean lint run.
+- Moved development dependencies from gemspec to Gemfile; bundle, lint, and tests still pass (with net-ssh logger warning).
+- Fixed `Session#method_missing` to avoid extra spaces when building commands; specs now green.
+- Implemented automatic session command loading via prepended modules, moved authorized key helpers, added YARD dependency, and expanded specs accordingly.
+
+# Notes
+
+- Keep command implementations in English and back them with tests.

data/lib/herd/commands/authorized_keys.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Herd
+  module Commands
+    # Commands for inspecting and managing authorized SSH keys.
+    module AuthorizedKeys
+      AUTHORIZED_KEYS_FILE = "~/.ssh/authorized_keys"
+
+      def authorized_keys_contains_exactly(required_keys)
+        required_keys = [required_keys].flatten
+        diff = keys_diff(authorized_keys, required_keys)
+        self.authorized_keys = required_keys
+
+        diff
+      end
+
+      def authorized_keys
+        read_file(AUTHORIZED_KEYS_FILE)&.split(/\r\n|\r|\n/) || []
+      end
+
+      def authorized_keys=(keys)
+        touch(AUTHORIZED_KEYS_FILE)
+        write_to_file(AUTHORIZED_KEYS_FILE, [keys].flatten.join("\n"))
+        file_permissions(AUTHORIZED_KEYS_FILE, 600)
+      end
+
+      def add_authorized_key(key)
+        touch(AUTHORIZED_KEYS_FILE)
+        append_to_file(AUTHORIZED_KEYS_FILE, key)
+        file_permissions(AUTHORIZED_KEYS_FILE, 600)
+      end
+
+      private
+
+      def keys_diff(actual_keys, required_keys)
+        result = Hash.new { |h, k| h[k] = [] }
+        actual_keys.each do |actual_key|
+          if required_keys.include?(actual_key)
+            result[:existing] << actual_key
+          else
+            result[:obsolete] << actual_key
+          end
+        end
+        result.merge({ added: required_keys - actual_keys })
+      end
+    end
+  end
+end

data/lib/herd/commands/crontab.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Herd
+  module Commands
+    # Commands for adding new crontab tasks or replace with given one.
+    module Crontab
+      def add_cron(entry)
+        run(%(crontab -l | { cat; echo "#{entry}"; } | crontab -))
+      end
+
+      def crontab(entry)
+        run(%(echo "#{entry}" | crontab -))
+      end
+    end
+  end
+end

data/lib/herd/commands/files.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "diff/lcs"
+require "diff/lcs/hunk"
+
+module Herd
+  module Commands
+    FILES = "files"
+
+    # Create, read, write, remove files, check permssions.
+    module Files
+      class PermissionDeniedError < StandardError; end
+
+      def file_exists?(path)
+        run("test -a #{path}; echo $?").chomp == "0"
+      end
+
+      def file_readable?(path)
+        run("test -r #{path}; echo $?").chomp == "0"
+      end
+
+      def file_writable?(path)
+        run("test -w #{path}; echo $?").chomp == "0"
+      end
+
+      def dir(path, user, group, sudo: false)
+        Dir.glob(File.join(FILES, path, "**/*"), File::FNM_DOTMATCH).each do |f|
+          remote_path = f.sub(FILES, "")
+          if File.directory?(f)
+            mkdir_p(remote_path, user, group, sudo: sudo)
+          else
+            file(remote_path, user, group)
+          end
+        end
+      end
+
+      def mkdir_p(path, user, group, sudo: false)
+        if sudo
+          run("sudo mkdir -p #{path}")
+        else
+          run("mkdir -p #{path}")
+        end
+        file_user_and_group(path, user, group)
+      end
+
+      def file(path, user, group, content: nil, mode: nil)
+        required_content = if content.nil?
+                             File.read(File.join(FILES, path))
+                           else
+                             content
+                           end
+
+        expect_file_content_equals(path, required_content)
+
+        file_user_and_group(path, user, group)
+        file_permissions(path, mode) if mode
+      end
+
+      def expect_file_content_equals(path, required_content)
+        if file_exists?(path)
+          actual_content = read_file!(path, sudo: true)
+          unless actual_content.lines(chomp: true) == required_content.lines(chomp: true)
+            # "File has been replaced with diff:\n\n#{diff(actual_content, required_content)}"
+            write_to_file!(path, required_content, sudo: true)
+          end
+        else
+          write_to_file!(path, required_content, sudo: true)
+        end
+      end
+
+      def read_file!(path, sudo: false)
+        if file_readable?(path)
+          read_file(path)
+        elsif sudo
+          read_file(path, sudo: true)
+        else
+          raise PermissionDeniedError, "'#{path}' is not readable"
+        end
+      end
+
+      def read_file(path, sudo: false)
+        command = "cat #{path}"
+        command = "sudo #{command}" if sudo
+
+        result = run(command)&.chomp
+        result = result.sub(/\A(\r\n|\r|\n)/, "") if sudo
+
+        result
+      end
+
+      def write_to_file!(path, content, sudo: false)
+        if file_writable?(path)
+          write_to_file(path, content)
+        elsif sudo
+          write_to_file(path, content, sudo: true)
+        else
+          raise PermissionDeniedError, "'#{path}' is not writable"
+        end
+      end
+
+      def write_to_file(path, content, sudo: false)
+        command = "tee"
+        command = "sudo #{command}" if sudo
+        run(%(#{command} #{path} << EOF
+#{content}
+EOF))
+      end
+
+      def append_to_file(path, content, sudo: false)
+        command = "tee -a"
+        command = "sudo #{command}" if sudo
+        run(%(#{command} #{path} << EOF
+#{content}
+EOF))
+      end
+
+      def file_user_and_group(path, user, group)
+        sudo("chown #{user}:#{group} #{path}")
+      end
+
+      def file_permissions(path, mode)
+        sudo("chmod #{mode} #{path}")
+      end
+
+      def diff(actual, required)
+        actual   = actual.lines(chomp: true)
+        required = required.lines(chomp: true)
+
+        diffs = Diff::LCS.diff actual, required
+        Diff::LCS::Hunk.new(actual, required, diffs[0], 3, 0).diff(:unified)
+      end
+    end
+  end
+end

data/lib/herd/commands/packages.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Herd
+  module Commands
+    # Working with package managers, like apt for Ubuntu
+    module Packages
+      def install_packages(packages)
+        packages = [packages].flatten.join(" ")
+        echo %(-e '#{password}\n' | sudo -S apt install -qq -y #{packages})
+      end
+    end
+  end
+end

data/lib/herd/commands/python.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Herd
+  module Commands
+    # Commands for python environment
+    module Python
+      def install_uv
+        run("curl -LsSf https://astral.sh/uv/install.sh | sh")
+      end
+    end
+  end
+end

data/lib/herd/commands/templates.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Herd
+  module Commands
+    TEMPLATES = "templates"
+
+    # Render templates using ERB
+    module Templates
+      def template(path, user, group, mode: nil, values: {})
+        erb = ERB.new(File.read(File.join(TEMPLATES, "#{path}.erb")))
+        content = erb.result_with_hash(values)
+        file(path, user, group, mode: mode, content: content)
+      end
+    end
+  end
+end

data/lib/herd/host.rb

@@ -1,33 +1,60 @@
 # frozen_string_literal: true
 
+require "csv"
+require "json"
 require "net/ssh"
 
 module Herd
   # Target host
   class Host
-    attr_reader :host, :user, :ssh_options
+    include Herd::Log
 
-    def initialize(host, user, port: 22, private_key_path: nil, password: nil)
+    attr_reader :host, :user, :ssh_options, :password, :vars, :log
+
+    # port, private_key_path, password are for the ssh connection
+    def initialize(host, user, options)
       @host = host
       @user = user
 
-      @ssh_options = { port: port, timeout: 10 }
-      if private_key_path
-        @ssh_options[:keys] = [private_key_path]
+      create_ssh_options(options)
+
+      @password = options.delete(:password)
+      @vars = options.merge(host: host, user: user, port: ssh_options[:port])
+
+      open_log
+    end
+
+    def create_ssh_options(options)
+      @ssh_options = { port: options[:port] || 22, timeout: 10 }
+      if options[:private_key_path]
+        @ssh_options[:keys] = [options.delete(:private_key_path)]
       else
-        @ssh_options[:password] = password
+        @ssh_options[:password] = options[:password]
       end
     end
 
-    def exec(command = nil, &block)
+    def exec(command = nil, &)
       Net::SSH.start(host, user, ssh_options) do |ssh|
-        session = Herd::Session.new(ssh)
+        session = Herd::Session.new(ssh, password, log)
 
-        output = nil
         output = session.send(command) if command
-        output = session.instance_exec(&block) if block_given?
+        output = session.instance_exec(vars, &) if block_given?
         output
       end
+    rescue StandardError => e
+      log_connection_error(e)
+    ensure
+      close_log
+    end
+
+    def self.from_csv(file = "hosts.csv")
+      CSV.read(file, headers: true).map do |csv|
+        h = csv.to_h.transform_keys(&:to_sym)
+        host = h.delete(:host)
+        user = h.delete(:user)
+        port = h.delete(:port).to_i
+        new(host, user, h.merge(port: port))
+      end
     end
   end
 end

data/lib/herd/log.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Herd
+  # Methods for logging commands, outputs and errors.
+  module Log
+    def log_file_path
+      dir = "log/#{vars[:host]}_#{vars[:port]}_#{vars[:user]}"
+      FileUtils.mkdir_p(dir)
+      "#{File.join(dir, Time.now.strftime("%Y%m%d_%H%M%S"))}.json"
+    end
+
+    def open_log
+      @log = File.open(log_file_path, "w")
+
+      log.puts "{"
+      log.print({ vars: vars }.to_json)
+    end
+
+    def close_log
+      log.puts "\n}"
+      log.close
+    end
+
+    def log_connection_error(error)
+      puts "#{vars.inspect}: #{error.message}"
+      log.puts ","
+      log.print({ error: error.message, error_trace: error.backtrace }.to_json)
+    end
+
+    def log_command_start(timestamp, command)
+      log.puts(",")
+      log.print({ timestamp: time(timestamp), command: command }.to_json)
+    end
+
+    def log_command_output(command, output, started_at)
+      now = Time.now
+      log.puts(",")
+      log.print({ timestamp: time(now), command: command, output: output, time: now - started_at }.to_json)
+    end
+
+    def log_command_error(command, error, started_at)
+      now = Time.now
+      log.puts(",")
+      log.print({ timestamp: time(now), command: command, error: error, time: now - started_at }.to_json)
+    end
+
+    def time(timestamp = Time.now)
+      timestamp.strftime("%Y-%m-%d %H:%M:%S.%L")
+    end
+  end
+end

data/lib/herd/runner.rb

@@ -9,9 +9,9 @@ module Herd
       @hosts = hosts
     end
 
-    def exec(command = nil, &block)
+    def exec(command = nil, &)
       threads = hosts.map do |host|
-        Thread.new { host.exec(command, &block) }
+        Thread.new { host.exec(command, &) }
       end
 
       threads.each(&:join)

data/lib/herd/session.rb

@@ -3,37 +3,101 @@
 module Herd
   # Session for executing commands on the remote host
   class Session
-    COMMANDS = %i[cat chmod echo hostname touch].freeze
+    include Herd::Log
 
-    attr_reader :ssh
+    OS_COMMANDS = %i[cat chmod echo hostname touch].freeze
+    CUSTOM_COMMANDS_DIR = File.expand_path("commands", __dir__)
 
-    def initialize(ssh)
+    attr_reader :ssh, :password, :log
+
+    def initialize(ssh, password, log)
       @ssh = ssh
+      @password = password
+      @log = log
     end
 
-    def authorized_keys
-      cat("~/.ssh/authorized_keys")&.chomp&.split("\n") || []
+    def method_missing(cmd, *args)
+      command_parts = [cmd.to_s]
+      command_parts.concat(args.map(&:to_s)) if args.any?
+      command = command_parts.join(" ")
+
+      run(command)
     end
 
-    def add_authorized_key(key)
-      touch("~/.ssh/authorized_keys")
-      chmod("600 ~/.ssh/authorized_keys")
-      echo "'#{key}' >> ~/.ssh/authorized_keys"
+    def run(command)
+      result = []
+      ssh.open_channel do |channel|
+        channel.request_pty do |ch, success|
+          raise ::Herd::CommandError, "could not obtain pty" unless success
+
+          channel_run(ch, command, result, Time.now)
+        end
+      end
+      ssh.loop
+      result.join
     end
 
-    def method_missing(cmd, *args)
-      command = cmd.to_s
-      command = "#{command} #{args.join(" ")}" if args
+    def respond_to_missing?(cmd)
+      OS_COMMANDS.include?(cmd) || super
+    end
+
+    class << self
+      def load_command_modules
+        command_files.each { |file| require file }
+
+        command_modules.each do |mod|
+          next if self <= mod
+
+          prepend mod
+        end
+      end
+
+      private
 
-      ssh.exec! command do |_, stream, data|
-        raise ::Herd::CommandError, data if stream == :stderr
+      def command_files
+        Dir[File.join(CUSTOM_COMMANDS_DIR, "*.rb")]
+      end
+
+      def command_modules
+        return [] unless defined?(Herd::Commands)
 
-        return data
+        Herd::Commands.constants
+                      .sort
+                      .map { |const_name| Herd::Commands.const_get(const_name) }
+                      .select { |value| value.is_a?(Module) }
       end
     end
 
-    def respond_to_missing?(cmd)
-      COMMANDS.include?(cmd) || super
+    private
+
+    def channel_run(channel, command, result, started_at)
+      log_command_start(started_at, command)
+
+      channel.exec(command) do |c, _|
+        c.on_data do |_, data|
+          process_output(c, command, started_at, data, result)
+        end
+
+        c.on_extended_data do |_, _, data|
+          process_error(command, started_at, data)
+        end
+      end
+    end
+
+    def process_output(channel, command, started_at, data, result)
+      if data.include?("[sudo] password for")
+        channel.send_data "#{password}\n"
+      else
+        log_command_output(command, data, started_at)
+        result << data
+      end
+    end
+
+    def process_error(command, started_at, data)
+      log_command_error(command, data, started_at)
+      raise ::Herd::CommandError, data
     end
   end
 end
+
+Herd::Session.load_command_modules

data/lib/herd/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Herd
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/herd.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "herd/version"
+require_relative "herd/log"
 require_relative "herd/host"
 require_relative "herd/runner"
 require_relative "herd/session"

metadata

@@ -1,70 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: herd-rb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yury Kotlyarov
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.21'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.21'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
+dependencies: []
 description: |
   Simple ruby DSL for fast host configuration. Supports Ubuntu and requires
   SSH server running on each targets host.
@@ -74,15 +18,25 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".ruby-version"
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- TODO.md
 - lib/herd.rb
+- lib/herd/commands/authorized_keys.rb
+- lib/herd/commands/crontab.rb
+- lib/herd/commands/files.rb
+- lib/herd/commands/packages.rb
+- lib/herd/commands/python.rb
+- lib/herd/commands/templates.rb
 - lib/herd/host.rb
+- lib/herd/log.rb
 - lib/herd/runner.rb
 - lib/herd/session.rb
 - lib/herd/version.rb
+- log/.keep
 - sig/herd.rbs
 homepage: https://github.com/yura/herd
 licenses:
@@ -91,6 +45,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/yura/herd
   source_code_uri: https://github.com/yura/herd
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -98,7 +53,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.4.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="