dockside 0.1.0

data/lib/dockside/readiness.rb

@@ -0,0 +1,120 @@
+require "net/http"
+require "socket"
+
+module Dockside
+  # Probes that tell whether a started container really answers.
+  module Readiness
+    def self.probe_for(dependency, spec)
+      case spec
+      when "auto" then dependency.port ? Tcp.new(dependency.port) : None.new
+      when "none" then None.new
+      when Hash then probe_from_hash(dependency, spec)
+      else raise ConfigError, "#{dependency.name}: ready must be auto, none, {http:}, {log:} or {command:}, got #{spec.inspect}"
+      end
+    end
+
+    def self.probe_from_hash(dependency, spec)
+      if spec.key?("http")
+        Http.new("#{dependency.url}#{spec["http"]}", status: spec["status"])
+      elsif spec.key?("log")
+        Log.new(dependency, spec["log"])
+      elsif spec.key?("command")
+        Command.new(dependency, spec["command"])
+      else
+        probe_for(dependency, "auto")
+      end
+    end
+
+    # Polls the probe until it answers. Raises ReadyTimeout, whose message the caller enriches with logs.
+    def self.wait(probe, timeout:)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      until probe.ready?
+        raise ReadyTimeout if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+        sleep Dockside.poll_interval
+      end
+    end
+
+    class Tcp
+      def initialize(port)
+        @port = port
+      end
+
+      # Docker accepts connections on a published port before the service inside listens and closes
+      # them right away, so a connection only counts when it stays open or the service says something.
+      def ready?
+        Socket.tcp("127.0.0.1", @port, connect_timeout: 1) do |socket|
+          return true unless socket.wait_readable(0.2)
+
+          !socket.read_nonblock(1, exception: false).nil?
+        end
+      rescue SystemCallError, IOError
+        false
+      end
+
+      def to_s
+        "port #{@port} accepts connections"
+      end
+    end
+
+    class Http
+      def initialize(url, status: nil)
+        @uri = URI(url)
+        @status = status
+      end
+
+      def ready?
+        response = Net::HTTP.start(@uri.host, @uri.port, open_timeout: 1, read_timeout: 5) do |http|
+          http.get(@uri.request_uri)
+        end
+        @status.nil? || response.code.to_i == @status
+      rescue SystemCallError, IOError, Net::OpenTimeout, Net::ReadTimeout
+        false
+      end
+
+      def to_s
+        "#{@uri} answers#{" with status #{@status}" if @status}"
+      end
+    end
+
+    class Log
+      def initialize(dependency, pattern)
+        @dependency = dependency
+        @pattern = Regexp.new(pattern)
+      end
+
+      def ready?
+        @dependency.logs(tail: 200).match?(@pattern)
+      end
+
+      def to_s
+        "log matches #{@pattern.source}"
+      end
+    end
+
+    class Command
+      def initialize(dependency, command)
+        @dependency = dependency
+        @command = command
+      end
+
+      def ready?
+        @dependency.exec_succeeds?(@command)
+      end
+
+      def to_s
+        "command #{Array(@command).join(" ")} succeeds"
+      end
+    end
+
+    class None
+      def ready?
+        true
+      end
+
+      def to_s
+        "container is running"
+      end
+    end
+  end
+end

data/lib/dockside/registry.rb

@@ -0,0 +1,55 @@
+module Dockside
+  # All dependencies of the app for one environment, built once from the resolved compose file.
+  class Registry
+    include Enumerable
+
+    def initialize(project)
+      @project = project
+      @dependencies = build
+    end
+
+    def names
+      @dependencies.keys
+    end
+
+    def fetch(name)
+      @dependencies.fetch(name.to_sym) do
+        raise UnknownDependency, "Unknown dependency #{name}. Known: #{names.join(", ")}."
+      end
+    end
+    alias_method :[], :fetch
+
+    def each(&block)
+      @dependencies.each_value(&block)
+    end
+
+    def autostart
+      select(&:autostart?)
+    end
+
+    private
+
+    def build
+      resolved = @project.resolve!
+      @project.service_names.to_h do |service|
+        dependency = Dependency.new(
+          name: service,
+          project: @project,
+          settings: @project.settings(service),
+          config: resolved.fetch(service),
+          shared: shared?(service)
+        )
+        [service.to_sym, dependency]
+      end
+    end
+
+    def shared?(service)
+      port = @project.host_port(service, @project.env)
+      return false if port.nil? || port != @project.host_port(service, @project.other_env)
+
+      Dockside.log "warning: #{service} uses port #{port} in development and test, " \
+        "so both environments share one container and its data"
+      true
+    end
+  end
+end

data/lib/dockside/runner.rb

@@ -0,0 +1,55 @@
+require "open3"
+
+module Dockside
+  # Runs commands given as argv arrays, never as shell strings.
+  class Runner
+    Result = Struct.new(:argv, :stdout, :stderr, :exit_status) do
+      def success?
+        exit_status.zero?
+      end
+    end
+
+    # Returns a Result. With stream: true the output is also printed while the command runs.
+    def run(argv, env: {}, stdin: nil, chdir: nil, stream: false)
+      if stream
+        stream_run(argv, env: env, chdir: chdir)
+      else
+        capture_run(argv, env: env, stdin: stdin, chdir: chdir)
+      end
+    rescue Errno::ENOENT
+      raise DockerMissing, "#{argv.first} was not found. Install Docker with the Compose plugin " \
+        "(https://docs.docker.com/get-docker/) or start with DOCKSIDE_AUTOSTART=0 to skip the containers."
+    end
+
+    def run!(argv, **options)
+      result = run(argv, **options)
+      raise CommandFailed.new(result) unless result.success?
+
+      result
+    end
+
+    private
+
+    def capture_run(argv, env:, stdin:, chdir:)
+      options = {}
+      options[:chdir] = chdir.to_s if chdir
+      options[:stdin_data] = stdin if stdin
+      stdout, stderr, status = Open3.capture3(env, *argv, **options)
+      Result.new(argv: argv, stdout: stdout, stderr: stderr, exit_status: status.exitstatus)
+    end
+
+    def stream_run(argv, env:, chdir:)
+      options = {}
+      options[:chdir] = chdir.to_s if chdir
+      output = +""
+      Open3.popen2e(env, *argv, **options) do |input, combined, wait|
+        input.close
+        combined.each_line do |line|
+          Dockside.output.print(line)
+          output << line
+        end
+        Result.new(argv: argv, stdout: output, stderr: "", exit_status: wait.value.exitstatus)
+      end
+    end
+  end
+end

data/lib/dockside/settings.rb

@@ -0,0 +1,38 @@
+module Dockside
+  # The x-dockside part of a service, merged for one environment.
+  Settings = Struct.new(:ready, :timeout, :after_start, :autostart)
+
+  class Settings
+    KEYS = %w[ready timeout after_start autostart].freeze
+    DEFAULTS = {"ready" => "auto", "timeout" => 300, "after_start" => [], "autostart" => true}.freeze
+
+    def self.for(service, definition, env)
+      extension = definition["x-dockside"] || {}
+      environment_block = extension[env] || {}
+      values = DEFAULTS.merge(extension.slice(*KEYS)).merge(environment_block.slice(*KEYS))
+      new(**values.transform_keys(&:to_sym)).tap do |settings|
+        settings.after_start = Provisioner::Step.parse_all(service, settings.after_start)
+      end
+    end
+
+    def self.validate(service, extension)
+      return if extension.nil?
+
+      unknown = extension.keys - KEYS - Project::ENVIRONMENTS
+      return if unknown.empty?
+
+      raise ConfigError, "Unknown x-dockside key#{"s" if unknown.size > 1} #{unknown.join(", ")} for service #{service}. " \
+        "Allowed: #{(KEYS + Project::ENVIRONMENTS).join(", ")}."
+    end
+
+    # The compose keys of the environment block, the part compose has to merge.
+    def self.compose_overrides(definition, env)
+      block = definition.dig("x-dockside", env) || {}
+      block.except(*KEYS)
+    end
+
+    def autostart?
+      autostart != false
+    end
+  end
+end

data/lib/dockside/version.rb

@@ -0,0 +1,3 @@
+module Dockside
+  VERSION = "0.1.0"
+end

data/lib/dockside.rb

@@ -0,0 +1,101 @@
+require "json"
+require "pathname"
+require "yaml"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/generators")
+loader.ignore("#{__dir__}/tasks")
+loader.ignore("#{__dir__}/dockside/railtie.rb")
+loader.ignore("#{__dir__}/dockside/errors.rb")
+loader.setup
+
+require "dockside/errors"
+
+# Starts the Docker containers an app needs, described in config/dockside.yml.
+module Dockside
+  class << self
+    attr_writer :root, :env, :app_name, :runner, :output
+    attr_accessor :poll_interval
+
+    def root
+      @root ||= Pathname.new((defined?(Rails) && Rails.root) ? Rails.root : Dir.pwd)
+    end
+
+    def env
+      @env ||= (defined?(Rails) && Rails.env.present?) ? Rails.env.to_s : ENV.fetch("RAILS_ENV", "development")
+    end
+
+    def app_name
+      @app_name ||= default_app_name
+    end
+
+    def runner
+      @runner ||= Runner.new
+    end
+
+    def output
+      @output || $stdout
+    end
+
+    def project
+      @project ||= Project.new(root: root, env: env, app_name: app_name, runner: runner)
+    end
+
+    def registry
+      @registry ||= Registry.new(project)
+    end
+
+    def reset!
+      @root = @env = @app_name = @runner = @project = @registry = nil
+    end
+
+    def names
+      registry.names
+    end
+
+    def fetch(name)
+      registry.fetch(name)
+    end
+
+    def ensure_running!(*names)
+      dependencies = names.empty? ? registry.autostart : names.map { |name| fetch(name) }
+      dependencies.each(&:ensure_running!)
+    end
+
+    def down
+      registry.each(&:remove_shared_container)
+      project.compose.down
+    end
+
+    def log(message)
+      output.puts("dockside: #{message}")
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      registry.names.include?(name) || super
+    end
+
+    def method_missing(name, *args)
+      if args.empty? && registry.names.include?(name)
+        fetch(name)
+      else
+        super
+      end
+    end
+
+    private
+
+    def default_app_name
+      if defined?(Rails) && Rails.application
+        Rails.application.class.module_parent_name.underscore.dasherize
+      else
+        root.basename.to_s.downcase.tr("_ ", "--")
+      end
+    end
+  end
+end
+
+Dockside.poll_interval = 1
+
+require "dockside/railtie" if defined?(Rails::Railtie)

data/lib/generators/dockside/install_generator.rb

@@ -0,0 +1,15 @@
+require "rails/generators"
+
+module Dockside
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates config/dockside.yml with a commented example"
+
+      def create_compose_file
+        template "dockside.yml.tt", "config/dockside.yml"
+      end
+    end
+  end
+end

data/lib/generators/dockside/templates/dockside.yml.tt

@@ -0,0 +1,25 @@
+# The containers this app needs in development and test. dockside starts them with `rails server` and
+# before the first test. This is a normal compose file; only the `x-dockside` block belongs to the gem.
+#
+# See https://github.com/renuo/dockside for every option.
+services:
+  # minio:
+  #   image: minio/minio
+  #   command: server /data
+  #   environment:
+  #     MINIO_ROOT_USER: minio
+  #     MINIO_ROOT_PASSWORD: minio-secret
+  #   ports: ["9000:9000"]
+  #   volumes:
+  #     - ./tmp/dockside/${RAILS_ENV}/minio:/data
+  #   x-dockside:
+  #     ready: { http: "/minio/health/live" }   # auto (port answers), none, {http:}, {log:} or {command:}
+  #     timeout: 60                              # seconds to wait until ready, default 300
+  #     after_start:                             # runs once, after the container is ready
+  #       - exec: mc alias set local http://localhost:9000 $MINIO_ROOT_USER $MINIO_ROOT_PASSWORD
+  #       - exec: mc mb --ignore-existing local/uploads
+  #     test:                                    # what differs in the test environment
+  #       ports: ["9010:9000"]
+  #       volumes: []
+  # Remove the {} below when you add your first service.
+  {}

data/lib/tasks/dockside.rake

@@ -0,0 +1,38 @@
+namespace :dockside do
+  names = ->(args) { [args[:names], *args.extras].compact.map(&:strip) }
+
+  desc "Start the containers (BUILD=1 rebuilds, PULL=1 pulls). Names separated by commas."
+  task :up, [:names] => :environment do |_task, args|
+    Dockside::Commands.up(names.call(args), build: ENV["BUILD"] == "1", pull: ENV["PULL"] == "1")
+  end
+
+  desc "Stop the containers, keep the data"
+  task :stop, [:names] => :environment do |_task, args|
+    Dockside::Commands.stop(names.call(args))
+  end
+
+  desc "Remove the containers, keep the data"
+  task down: :environment do
+    Dockside::Commands.down
+  end
+
+  desc "Remove the containers and the data, start again"
+  task :reset, [:names] => :environment do |_task, args|
+    Dockside::Commands.reset(names.call(args))
+  end
+
+  desc "Show every container, its state and URL"
+  task status: :environment do
+    Dockside::Commands.status
+  end
+
+  desc "Show the container log (TAIL=200, FOLLOW=1)"
+  task :logs, [:name] => :environment do |_task, args|
+    Dockside::Commands.logs(args.fetch(:name), tail: ENV.fetch("TAIL", 100).to_i, follow: ENV["FOLLOW"] == "1")
+  end
+
+  desc "Show the compose file the gem really uses"
+  task config: :environment do
+    Dockside::Commands.config
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: dockside
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alessandro Rodi
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: Describe the containers your app needs in a compose file. dockside starts
+  them before the server and the test suite, waits until they are ready, sets them
+  up the first time and keeps development and test apart.
+email:
+- alessandro.rodi@renuo.ch
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/dockside.rb
+- lib/dockside/autostart.rb
+- lib/dockside/commands.rb
+- lib/dockside/compose.rb
+- lib/dockside/dependency.rb
+- lib/dockside/docker.rb
+- lib/dockside/errors.rb
+- lib/dockside/override.rb
+- lib/dockside/project.rb
+- lib/dockside/provisioner.rb
+- lib/dockside/railtie.rb
+- lib/dockside/readiness.rb
+- lib/dockside/registry.rb
+- lib/dockside/runner.rb
+- lib/dockside/settings.rb
+- lib/dockside/version.rb
+- lib/generators/dockside/install_generator.rb
+- lib/generators/dockside/templates/dockside.yml.tt
+- lib/tasks/dockside.rake
+homepage: https://github.com/coorasse/dockside
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/coorasse/dockside
+  source_code_uri: https://github.com/coorasse/dockside
+  changelog_uri: https://github.com/coorasse/dockside/blob/main/CHANGELOG.md
+  funding_uri: https://github.com/sponsors/coorasse
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.8
+specification_version: 4
+summary: Starts the Docker containers your Rails app needs, when your app starts.
+test_files: []