companion 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ab5a186cad9e99952e804f33a041b30ca7081bb527469dc9010d8d8349aeb373
+  data.tar.gz: 3069e33d2e3cdd63ded2c08c6ec45757f95da56d9f65a65eaadf3f89b74b2e15
+SHA512:
+  metadata.gz: ba4abd0a3d492ea8219e22ea675a5e89e29cf0b205bef4dfbeebb53d7f324f755d294f81eb6739e21dd5820b6073c5dfe1dc63dd0c2dedb47e89f1c28531333e
+  data.tar.gz: 3104d72f722a21932b301998de14e82c022e68bfc40e4796857db97acf19f1d9678933d89ec9709e93337b2df73080e7ed17626aadb2ee6aa5df5cea339ea116

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright Kevin Sylvestre
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,92 @@
+# Companion
+
+Companion is a mountable Rails engine for running a companion application (e.g. Node, Python, Go, etc.) alongside a Rails application. Companion spawns and supervises the process, then proxies traffic from a mounted path in your Rails routes to the spawned process.
+
+## Usage
+
+### Installation
+
+**Gemfile**
+
+```ruby
+gem "companion"
+```
+
+```bash
+bundle install
+```
+
+### Configuration
+
+Initialize your application via a an initializer (e.g. `config/initializers/companion.rb`):
+
+```ruby
+# config/initializers/companion.rb
+Companion.configure do |config|
+  config.app :dashboard do |app|
+    app.command = -> { |port| "npm run serve -- --port {port}" }
+    app.directory = Rails.root.join("dashboard")
+    app.environment = { "NODE_ENV" => Rails.env.production? ? "production" : "development" }
+  end
+end
+```
+
+### Routing
+
+Mount your application as an engine in `config/routes.rb`:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount Companion::Engine.app(:dashboard), at: "/dashboard"
+end
+```
+
+## Examples
+
+**companions/greeter/Gemfile**
+
+```ruby
+source "https://rubygems.org"
+
+gemspec
+
+gem "rack"
+```
+
+**companions/greeter/config.ru**
+
+```ruby
+# companions/greeter/config.ru
+
+run do |env|
+  [200, { "content-type" => "text/plain" }, ["Greetings!"]]
+end
+```
+
+**config/initializers/companion.rb**
+
+```ruby
+Companion.configure do |config|
+  config.app :greeter do |app|
+    app.command = -> { |port| "rackup --port #{port}" }
+    app.directory = Rails.root.join("companions", "greeter")
+  end
+end
+```
+
+**config/routes.rb**
+
+```ruby
+Rails.application.routes.draw do
+  mount Companion::Engine.app(:greeter), at: "/greeter"
+end
+```
+
+```bash
+rails server
+```
+
+```bash
+curl --verbose https://localhost:3000/greeter
+```

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/controllers/companion/application_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Companion
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/companion/apps_controller.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Companion
+  class AppsController < ApplicationController
+    def index
+      @apps = Companion.config.apps.values
+    end
+
+    def show
+      @app = Companion.config.apps.values.find { |app| app.name.to_s == params[:id] }
+      raise ActionController::RoutingError, "unknown app #{params[:id].inspect}" unless @app
+
+      @sample = @app.sample
+    end
+  end
+end

data/app/helpers/companion/application_helper.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Companion
+  module ApplicationHelper
+    def companion_command(app)
+      app.command.respond_to?(:call) ? String(app.command.call("$PORT")) : String(app.command)
+    end
+
+    def companion_uptime(app)
+      app.started_at ? time_ago_in_words(app.started_at) : "—"
+    end
+
+    def companion_directory(app)
+      return "—" unless app.directory
+
+      Pathname(app.directory).expand_path.relative_path_from(Rails.root).to_s
+    end
+
+    def companion_environment(app)
+      filter = ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
+      filter.filter(app.environment.to_h { |key, value| [String(key), value] })
+    end
+
+    def companion_cpu(value)
+      number_to_percentage(value, precision: 1)
+    end
+
+    def companion_memory(rss, percentage)
+      "#{number_to_human_size(rss)} (#{number_to_percentage(percentage, precision: 1)})"
+    end
+  end
+end

data/app/jobs/companion/application_job.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Companion
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/views/companion/apps/index.html.erb

@@ -0,0 +1,38 @@
+<header>
+  <h1>Companion</h1>
+</header>
+
+<main>
+<% if @apps.empty? %>
+  <p>No apps are registered.</p>
+<% else %>
+  <figure>
+  <table>
+    <thead>
+      <tr>
+        <th>Name</th>
+        <th>Status</th>
+        <th>PID</th>
+        <th>URL</th>
+        <th>Uptime</th>
+        <th>Command</th>
+        <th>Directory</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @apps.each do |app| %>
+        <tr id="app_<%= app.name %>">
+          <td><%= link_to app.name, app_path(app.name) %></td>
+          <td><%= app.status %></td>
+          <td><%= app.pid || "—" %></td>
+          <td><%= app.url || "—" %></td>
+          <td><%= companion_uptime(app) %></td>
+          <td><code><%= companion_command(app) %></code></td>
+          <td><code><%= companion_directory(app) %></code></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+  </figure>
+<% end %>
+</main>

data/app/views/companion/apps/show.html.erb

@@ -0,0 +1,141 @@
+<header>
+  <nav>
+    <ul>
+      <li><%= link_to "Companion", root_path %></li>
+      <li><strong><%= @app.name %></strong></li>
+    </ul>
+  </nav>
+  <h1><%= @app.name %></h1>
+</header>
+
+<main>
+  <section id="resources">
+    <h2>Resources</h2>
+    <% if @sample %>
+      <figure>
+      <table>
+        <tbody>
+          <tr>
+            <th scope="row">CPU</th>
+            <td id="cpu"><%= companion_cpu(@sample.cpu) %></td>
+          </tr>
+          <tr>
+            <th scope="row">Memory</th>
+            <td id="memory"><%= companion_memory(@sample.rss, @sample.memory) %></td>
+          </tr>
+          <tr>
+            <th scope="row">Processes</th>
+            <td><%= @sample.entries.size %></td>
+          </tr>
+          <tr>
+            <th scope="row">Sampled</th>
+            <td><%= @sample.sampled_at.to_fs(:db) %></td>
+          </tr>
+        </tbody>
+      </table>
+      </figure>
+      <small>CPU is a percentage of one core, totalled across the app's process group.</small>
+    <% elsif @app.running? %>
+      <p>Resource usage is unavailable.</p>
+    <% else %>
+      <p>The app is not running.</p>
+    <% end %>
+  </section>
+
+  <section id="details">
+    <h2>Details</h2>
+    <figure>
+    <table>
+      <tbody>
+        <tr>
+          <th scope="row">Status</th>
+          <td><%= @app.status %></td>
+        </tr>
+        <tr>
+          <th scope="row">PID</th>
+          <td><%= @app.pid || "—" %></td>
+        </tr>
+        <tr>
+          <th scope="row">URL</th>
+          <td><%= @app.url ? link_to(@app.url, @app.url) : "—" %></td>
+        </tr>
+        <tr>
+          <th scope="row">Host</th>
+          <td><code><%= @app.host %></code></td>
+        </tr>
+        <tr>
+          <th scope="row">Port</th>
+          <td><%= @app.port || "—" %></td>
+        </tr>
+        <tr>
+          <th scope="row">Started</th>
+          <td><%= @app.started_at ? "#{@app.started_at.to_fs(:db)} (#{companion_uptime(@app)} ago)" : "—" %></td>
+        </tr>
+        <tr>
+          <th scope="row">Boot timeout</th>
+          <td><%= @app.boot_timeout %>s</td>
+        </tr>
+        <tr>
+          <th scope="row">Command</th>
+          <td><code><%= companion_command(@app) %></code></td>
+        </tr>
+        <tr>
+          <th scope="row">Directory</th>
+          <td><code><%= companion_directory(@app) %></code></td>
+        </tr>
+      </tbody>
+    </table>
+    </figure>
+  </section>
+
+  <% if @sample %>
+    <section id="processes">
+      <h2>Processes</h2>
+      <figure>
+      <table>
+        <thead>
+          <tr>
+            <th>PID</th>
+            <th>PPID</th>
+            <th>CPU</th>
+            <th>Memory</th>
+            <th>Command</th>
+          </tr>
+        </thead>
+        <tbody>
+          <% @sample.entries.each do |entry| %>
+            <tr id="process_<%= entry.pid %>">
+              <td><%= entry.pid %></td>
+              <td><%= entry.ppid %></td>
+              <td><%= companion_cpu(entry.cpu) %></td>
+              <td><%= companion_memory(entry.rss, entry.memory) %></td>
+              <td><code><%= entry.command %></code></td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+      </figure>
+    </section>
+  <% end %>
+
+  <section id="environment">
+    <h2>Environment</h2>
+    <% environment = companion_environment(@app) %>
+    <% if environment.empty? %>
+      <p>No extra environment variables are set.</p>
+    <% else %>
+      <figure>
+      <table>
+        <tbody>
+          <% environment.each do |key, value| %>
+            <tr>
+              <th scope="row"><code><%= key %></code></th>
+              <td><code><%= value.nil? ? "(unset)" : value %></code></td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+      </figure>
+    <% end %>
+  </section>
+</main>

data/app/views/layouts/companion/application.html.erb

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Companion</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta http-equiv="refresh" content="5">
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.classless.min.css">
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Companion::Engine.routes.draw do
+  root "apps#index"
+  resources :apps, only: :show
+end

data/lib/companion/app.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "socket"
+require "timeout"
+
+module Companion
+  # A companion web process that is booted on demand on a random local port
+  # and stopped when the host application exits.
+  class App
+    # The interface companion apps bind to unless {#host} is set.
+    DEFAULT_HOST = "127.0.0.1"
+
+    # Wildcard bind addresses mapped to the loopback address used to reach them.
+    WILDCARD_HOSTS = { "0.0.0.0" => "127.0.0.1", "::" => "::1" }.freeze
+
+    # @return [Symbol] the name the app is registered under
+    attr_reader :name
+
+    # @return [Integer, nil] the port the app is listening on, or nil when stopped
+    attr_reader :port
+
+    # @return [Integer, nil] the process group leader's pid, or nil when stopped
+    attr_reader :pid
+
+    # @return [ActiveSupport::TimeWithZone, nil] when the app finished booting, or nil when stopped
+    attr_reader :started_at
+
+    # @return [String, #call, nil] the shell command to run, or a callable that
+    #   receives the assigned port and returns one
+    attr_accessor :command
+
+    # @return [String, Pathname, nil] the working directory for the process;
+    #   defaults to the current directory
+    attr_accessor :directory
+
+    # @return [Hash] extra environment variables for the process
+    attr_accessor :environment
+
+    # @return [Numeric] seconds to wait for the app to accept connections
+    attr_accessor :boot_timeout
+
+    # @return [String] the interface the app binds to, passed to the process as +HOST+;
+    #   defaults to {DEFAULT_HOST}
+    attr_accessor :host
+
+    # @param name [Symbol] the name to register the app under
+    def initialize(name)
+      @name = name
+      @host = DEFAULT_HOST
+      @environment = {}
+      @boot_timeout = 30
+      @mutex = Mutex.new
+    end
+
+    # Checks that the app has everything it needs to boot.
+    #
+    # @raise [ConfigurationError] if no command is set
+    # @return [void]
+    def validate!
+      raise ConfigurationError, "app #{name.inspect} requires a command" if command.nil?
+    end
+
+    # @return [String, nil] the base URL of the running app, or nil when stopped
+    def url
+      return unless port
+
+      address = connect_host
+      address = "[#{address}]" if address.include?(":")
+      "http://#{address}:#{port}"
+    end
+
+    # Reports whether the spawned process is still alive.
+    #
+    # @return [Boolean]
+    def running?
+      return false unless @pid
+
+      Process.waitpid(@pid, Process::WNOHANG).nil?
+    rescue Errno::ECHILD
+      false
+    end
+
+    # @return [Symbol] +:running+ or +:stopped+
+    def status
+      running? ? :running : :stopped
+    end
+
+    # Spawns the app on a free port and blocks until it accepts connections.
+    # Does nothing if the app is already running.
+    #
+    # @raise [BootError] if the process exits or does not listen within {#boot_timeout}
+    # @return [void]
+    def start
+      @mutex.synchronize do
+        return if running?
+
+        @port = available_port
+        @pid = Process.spawn(spawn_environment, resolved_command, chdir: String(directory || Dir.pwd), pgroup: true)
+        wait_until_listening
+        @started_at = Time.current
+      end
+    end
+
+    # Sends TERM to the app's process group and waits for it to exit.
+    # Does nothing if the app was never started.
+    #
+    # @return [void]
+    def stop
+      @mutex.synchronize do
+        return unless @pid
+
+        begin
+          Process.kill("TERM", -@pid)
+          Process.wait(@pid)
+        rescue Errno::ESRCH, Errno::ECHILD
+          # Already gone.
+        end
+        @pid = @port = @started_at = nil
+      end
+    end
+
+    # Samples the CPU and memory usage of the app's process group.
+    #
+    # @return [ProcessSample, nil] nil when stopped or if sampling is unavailable
+    def sample
+      ProcessSample.capture(@pid) if running?
+    end
+
+    # @return [Proxy] a memoized Rack endpoint that forwards requests to this app
+    def proxy
+      @proxy ||= Proxy.new(self)
+    end
+
+  private
+
+    # @return [String] the command to spawn, with callables invoked with the assigned port
+    def resolved_command
+      command.respond_to?(:call) ? command.call(@port) : String(command)
+    end
+
+    # @return [Hash{String => String, nil}] the configured environment with string keys and +HOST+ and +PORT+ set
+    def spawn_environment
+      environment.to_h { |key, value| [String(key), (String(value) unless value.nil?)] }
+        .merge("HOST" => String(host), "PORT" => String(@port))
+    end
+
+    # @return [String] the address to connect to the app on, with wildcard hosts mapped to loopback
+    def connect_host
+      WILDCARD_HOSTS.fetch(String(host), String(host))
+    end
+
+    # Asks the OS for an unused port by briefly binding to port 0.
+    #
+    # @return [Integer]
+    def available_port
+      server = TCPServer.new(String(host), 0)
+      server.addr[1]
+    ensure
+      server&.close
+    end
+
+    # Polls the app's port until it accepts a connection.
+    #
+    # @raise [BootError] if the process exits or the timeout elapses first
+    # @return [void]
+    def wait_until_listening
+      Timeout.timeout(boot_timeout) do
+        loop do
+          raise BootError, "app #{name.inspect} exited during boot" unless running?
+
+          TCPSocket.new(connect_host, @port).close
+          break
+        rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL
+          sleep 0.1
+        end
+      end
+    rescue Timeout::Error
+      raise BootError, "app #{name.inspect} did not listen on port #{@port} within #{boot_timeout}s"
+    end
+  end
+end

data/lib/companion/configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Companion
+  # Holds the set of registered apps.
+  class Configuration
+    # @return [Hash{Symbol => App}] registered apps keyed by name
+    attr_reader :apps
+
+    def initialize
+      @apps = {}
+    end
+
+    # Registers an app, replacing any existing app with the same name.
+    #
+    # @param name [Symbol]
+    # @yieldparam app [App] the new app, for setting its options
+    # @raise [ConfigurationError] if the app is invalid after the block runs
+    # @return [App]
+    def app(name)
+      app = App.new(name)
+      yield(app) if block_given?
+      app.validate!
+      @apps[app.name] = app
+    end
+  end
+end

data/lib/companion/engine.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Companion
+  # Rails integration for Companion.
+  class Engine < ::Rails::Engine
+    isolate_namespace Companion
+
+    # Builds a Rack endpoint for mounting an app in the host's routes. The app
+    # is looked up per request, so it may be registered after routes load.
+    #
+    # @example
+    #   mount Companion::Engine.app(:dashboard), at: "/dashboard"
+    #
+    # @param name [Symbol] the registered app's name
+    # @return [Proc] a Rack endpoint
+    def self.app(name)
+      ->(env) { Companion[name].proxy.call(env) }
+    end
+  end
+end

data/lib/companion/process_sample.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Companion
+  # A point-in-time snapshot of the resource usage of every process in an
+  # app's process group, read from +ps+.
+  class ProcessSample
+    # A single process in the sampled group.
+    #
+    # @!attribute pid [Integer]
+    # @!attribute ppid [Integer] the parent's pid
+    # @!attribute cpu [Float] CPU usage as a percentage of one core, as reported by +ps+
+    # @!attribute memory [Float] resident memory as a percentage of physical memory
+    # @!attribute rss [Integer] resident memory in bytes
+    # @!attribute command [String]
+    Entry = Data.define(:pid, :ppid, :cpu, :memory, :rss, :command)
+
+    # Each column gets its own +-o+ flag so empty headers are not parsed as part of the next column.
+    COLUMNS = %w[pid ppid pgid pcpu pmem rss command].freeze
+
+    # Samples every process whose process group is led by +pgid+.
+    #
+    # @param pgid [Integer] the process group leader's pid
+    # @return [ProcessSample, nil] nil if +ps+ is unavailable or no process is in the group
+    def self.capture(pgid)
+      output, status = Open3.capture2("ps", "-A", "-ww", *COLUMNS.flat_map { |column| ["-o", "#{column}="] })
+      return unless status.success?
+
+      entries = output.each_line.filter_map { |line| parse(line, pgid) }
+      new(pgid, entries, Time.current) unless entries.empty?
+    rescue SystemCallError
+      nil
+    end
+
+    # @param line [String] a row of +ps+ output
+    # @param pgid [Integer]
+    # @return [Entry, nil] nil unless the row belongs to the process group
+    def self.parse(line, pgid)
+      pid, ppid, group, cpu, memory, rss, command = line.strip.split(/\s+/, COLUMNS.size)
+      return unless Integer(group, exception: false) == pgid
+
+      Entry.new(pid: Integer(pid), ppid: Integer(ppid), cpu: Float(cpu), memory: Float(memory),
+        rss: Integer(rss) * 1024, command: String(command))
+    end
+    private_class_method :parse
+
+    # @return [Array<Entry>] the processes in the group, leader first
+    attr_reader :entries
+
+    # @return [ActiveSupport::TimeWithZone] when the sample was taken
+    attr_reader :sampled_at
+
+    # @param pgid [Integer] the process group leader's pid
+    # @param entries [Array<Entry>]
+    # @param sampled_at [ActiveSupport::TimeWithZone]
+    def initialize(pgid, entries, sampled_at)
+      @entries = entries.sort_by { |entry| [entry.pid == pgid ? 0 : 1, entry.pid] }
+      @sampled_at = sampled_at
+    end
+
+    # @return [Float] combined CPU usage across the group, as a percentage of one core
+    def cpu
+      entries.sum(&:cpu)
+    end
+
+    # @return [Float] combined resident memory as a percentage of physical memory
+    def memory
+      entries.sum(&:memory)
+    end
+
+    # @return [Integer] combined resident memory in bytes
+    def rss
+      entries.sum(&:rss)
+    end
+  end
+end

data/lib/companion/proxy.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "http"
+
+module Companion
+  # A Rack endpoint that boots an {App} on first use and forwards requests to it.
+  class Proxy
+    # Connection-scoped headers that must not be forwarded between hops (RFC 9110 §7.6.1).
+    HOP_BY_HOP_HEADERS = %w[
+      connection keep-alive proxy-authenticate proxy-authorization
+      te trailer transfer-encoding upgrade
+    ].freeze
+
+    # @param app [App] the app to forward requests to
+    def initialize(app)
+      @app = app
+    end
+
+    # Forwards a Rack request to the app, starting it if needed.
+    #
+    # @param env [Hash] the Rack environment
+    # @return [Array(Integer, Hash, Array<String>)] a Rack response; 502 if the
+    #   app fails to boot or the upstream request fails
+    def call(env)
+      @app.start unless @app.running?
+
+      request = Rack::Request.new(env)
+      body = request_body(request)
+      headers = request_headers(request)
+      headers["transfer-encoding"] = "chunked" if body && !request.content_length
+
+      response = HTTP.request(request.request_method.downcase.to_sym, url(request), headers:, body:)
+
+      [response.code, response_headers(response), [String(response)]]
+    rescue BootError, HTTP::Error, SystemCallError => e
+      [502, { "content-type" => "text/plain" }, ["Bad Gateway: #{e.message}"]]
+    end
+
+  private
+
+    # @param request [Rack::Request]
+    # @return [String] the upstream URL for the request's path and query string
+    def url(request)
+      path = request.path_info.presence || "/"
+      path += "?#{request.query_string}" if request.query_string.present?
+
+      "#{@app.url}#{path}"
+    end
+
+    # @param request [Rack::Request]
+    # @return [IO, nil] the request body stream, or nil when the request has no body
+    def request_body(request)
+      request.body if request.content_length.to_i.positive? || request.get_header("HTTP_TRANSFER_ENCODING")
+    end
+
+    # Builds the upstream request headers, dropping hop-by-hop headers and
+    # adding the standard +X-Forwarded-*+ headers.
+    #
+    # @param request [Rack::Request]
+    # @return [Hash{String => String}]
+    def request_headers(request)
+      headers = {}
+      request.each_header do |key, value|
+        next unless key.start_with?("HTTP_")
+
+        name = key.delete_prefix("HTTP_").downcase.tr("_", "-")
+        headers[name] = value unless HOP_BY_HOP_HEADERS.include?(name)
+      end
+      headers["content-type"] = request.content_type if request.content_type
+      headers["content-length"] = request.content_length if request.content_length
+      headers["x-forwarded-for"] = [headers["x-forwarded-for"], request.ip].compact.join(", ")
+      headers["x-forwarded-host"] = request.host_with_port
+      headers["x-forwarded-proto"] = request.scheme
+      headers["x-forwarded-prefix"] = request.script_name if request.script_name.present?
+      headers
+    end
+
+    # Converts upstream headers to Rack headers, dropping hop-by-hop headers and
+    # +content-length+ (the body is re-buffered). Repeated headers become arrays.
+    #
+    # @param response [HTTP::Response]
+    # @return [Hash{String => String, Array<String>}]
+    def response_headers(response)
+      headers = {}
+      response.headers.each do |key, value|
+        name = key.downcase
+        next if HOP_BY_HOP_HEADERS.include?(name) || name == "content-length"
+
+        headers[name] = headers.key?(name) ? [*headers[name], value] : value
+      end
+      headers
+    end
+  end
+end

data/lib/companion/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Companion
+  # @return [String] the gem version
+  VERSION = "0.1.0"
+end

data/lib/companion.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "companion/version"
+require "companion/process_sample"
+require "companion/app"
+require "companion/configuration"
+require "companion/proxy"
+require "companion/engine"
+
+# Runs companion web apps alongside a Rails application and proxies requests to them.
+module Companion
+  # Base class for all Companion errors.
+  class Error < StandardError; end
+
+  # Raised when an app is misconfigured or looked up by an unknown name.
+  class ConfigurationError < Error; end
+
+  # Raised when an app exits or fails to listen while booting.
+  class BootError < Error; end
+
+  class << self
+    # @return [Configuration] the memoized global configuration
+    def config
+      @config ||= Configuration.new
+    end
+
+    # @yieldparam config [Configuration]
+    # @return [void]
+    def configure
+      yield(config)
+    end
+
+    # Looks up a registered app.
+    #
+    # @param name [Symbol]
+    # @raise [ConfigurationError] if no app is registered under +name+
+    # @return [App]
+    def [](name)
+      config.apps.fetch(name) { raise ConfigurationError, "unknown app #{name.inspect}" }
+    end
+
+    # Stops every registered app, keeping the configuration.
+    #
+    # @return [void]
+    def stop
+      config.apps.each_value(&:stop)
+    end
+
+    # Stops every app and discards the configuration.
+    #
+    # @return [void]
+    def reset!
+      stop
+      @config = nil
+    end
+  end
+end
+
+at_exit { Companion.stop }

data/lib/tasks/companion_tasks.rake

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# desc "Explaining what the task does"
+# task :companion do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: companion
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kevin Sylvestre
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Companion is a mountable engine that spawns and supervises companion
+  applications.
+email:
+- kevin@ksylvest.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- app/controllers/companion/application_controller.rb
+- app/controllers/companion/apps_controller.rb
+- app/helpers/companion/application_helper.rb
+- app/jobs/companion/application_job.rb
+- app/views/companion/apps/index.html.erb
+- app/views/companion/apps/show.html.erb
+- app/views/layouts/companion/application.html.erb
+- config/routes.rb
+- lib/companion.rb
+- lib/companion/app.rb
+- lib/companion/configuration.rb
+- lib/companion/engine.rb
+- lib/companion/process_sample.rb
+- lib/companion/proxy.rb
+- lib/companion/version.rb
+- lib/tasks/companion_tasks.rake
+homepage: https://github.com/ksylvest/companion
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/ksylvest/companion
+  source_code_uri: https://github.com/ksylvest/companion
+  changelog_uri: https://github.com/ksylvest/companion/releases
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Spawn companion apps and proxy traffic to them.
+test_files: []