orbitcast 0.3.1-x86_64-linux-gnu

data/lib/generators/orbitcast/install/install_generator.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Orbitcast
+  module Generators
+    # `bin/rails generate orbitcast:install`
+    #
+    # Applies everything an application needs to talk to the relay,
+    # idempotently — a second run changes nothing:
+    #
+    #   1. config/cable.yml                  — `adapter: orbitcast`, namespace, cable DSN
+    #   2. config/initializers/orbitcast.rb  — mode and signing keys
+    #   3. config/environments/{development,production}.rb
+    #                                        — mount_path = nil, url, allowed origins, mode
+    #   4. app/views/layouts/application.html.erb
+    #                                        — `action_cable_meta_tag` in <head>, if missing
+    #   5. Procfile.dev                      — a `cable:` process (created when absent)
+    #   6. db/orbitcast_migrate/             — the overflow relay table, with --overflow
+    #
+    # It touches nothing else: importmap pins, `@rails/actioncable` imports,
+    # Solid Queue/Cache configuration, and any environment setting already
+    # present are left exactly as they are.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Configure Rails to publish through Orbitcast and let the Rust relay serve /cable."
+
+      class_option :overflow,
+                   type: :boolean,
+                   default: false,
+                   desc: "Copy the overflow-payload migration (db/orbitcast_migrate) and enable " \
+                         "the relay for Turbo broadcasts larger than PostgreSQL's 8000-byte " \
+                         "NOTIFY limit"
+
+      # gem/lib/generators/orbitcast/install -> gem/db/orbitcast_migrate
+      MIGRATION_SOURCE_DIR = File.expand_path("../../../../db/orbitcast_migrate", __dir__)
+      MIGRATION_FILENAME = "001_create_orbitcast_payloads.rb"
+
+      PROCFILE = "Procfile.dev"
+      CABLE_PROCESS = "cable: bundle exec orbitcast serve"
+      WEB_PROCESS = "web: bin/rails server"
+
+      LAYOUT = "app/views/layouts/application.html.erb"
+      META_TAG = "<%= action_cable_meta_tag %>"
+
+      ENVIRONMENT_ANCHOR = /^Rails\.application\.configure do[ \t]*\n/
+
+      # The settings injected per environment, keyed by the configuration
+      # attribute they set. A line whose attribute is already assigned in the
+      # file (uncommented) is skipped, so an application's own value wins.
+      ENVIRONMENT_SETTINGS = {
+        "development" => {
+          "config.action_cable.mount_path" => "nil",
+          "config.action_cable.url" => '"ws://localhost:28080/cable"',
+          "config.action_cable.allowed_request_origins" =>
+            '["http://localhost:3000", "http://127.0.0.1:3000"]',
+          "config.orbitcast.mode" => ":signed"
+        },
+        "production" => {
+          "config.action_cable.mount_path" => "nil",
+          "config.action_cable.url" => 'ENV.fetch("ORBITCAST_CABLE_URL") # wss://app.example/cable',
+          "config.action_cable.allowed_request_origins" => '[ENV.fetch("APP_ORIGIN")]',
+          "config.orbitcast.mode" => ":signed"
+        }
+      }.freeze
+
+      def create_cable_yml
+        template "cable.yml.tt", "config/cable.yml"
+      end
+
+      def create_initializer
+        template "orbitcast.rb.tt", "config/initializers/orbitcast.rb"
+      end
+
+      # `mount_path = nil` is what stops Rails serving a second /cable; the
+      # URL and origins are what the relay and `action_cable_meta_tag` agree
+      # on. Applied, not printed — and only for the lines not already there.
+      def configure_environments
+        ENVIRONMENT_SETTINGS.each do |environment, settings|
+          path = "config/environments/#{environment}.rb"
+          absolute = File.join(destination_root, path)
+
+          unless File.file?(absolute)
+            say_status :skip, "#{path} does not exist; add the Orbitcast settings by hand", :yellow
+            next
+          end
+
+          content = File.read(absolute)
+          unless content.match?(ENVIRONMENT_ANCHOR)
+            say_status :skip, "#{path} has no `Rails.application.configure do` block to inject into", :yellow
+            next
+          end
+
+          missing = settings.reject { |attribute, _| content.match?(/^\s*#{Regexp.escape(attribute)}\s*=/) }
+          if missing.empty?
+            say_status :identical, path, :blue
+            next
+          end
+
+          block = +"  # Orbitcast: the Rust relay serves /cable; Rails must not mount a second one.\n"
+          missing.each { |attribute, value| block << "  #{attribute} = #{value}\n" }
+          block << "\n"
+
+          inject_into_file path, block, after: ENVIRONMENT_ANCHOR
+        end
+      end
+
+      # `createConsumer()` reads the cable URL from this tag. Without it the
+      # browser falls back to /cable on the Rails host, which no longer serves
+      # WebSockets.
+      def add_action_cable_meta_tag
+        absolute = File.join(destination_root, LAYOUT)
+
+        unless File.file?(absolute)
+          say_status :skip, "#{LAYOUT} does not exist; add #{META_TAG} to your layout's <head>", :yellow
+          return
+        end
+
+        content = File.read(absolute)
+        if content.include?("action_cable_meta_tag")
+          say_status :identical, "#{LAYOUT} (action_cable_meta_tag)", :blue
+          return
+        end
+
+        unless content.match?(%r{^\s*</head>})
+          say_status :skip, "#{LAYOUT} has no </head> to insert #{META_TAG} before", :yellow
+          return
+        end
+
+        inject_into_file LAYOUT, "    #{META_TAG}\n", before: %r{^\s*</head>}
+      end
+
+      # Development uses the application's existing process manager. Never start
+      # the relay from an engine initializer: that would spawn one per
+      # app-server worker, console, and rake task.
+      def add_cable_process
+        absolute = File.join(destination_root, PROCFILE)
+
+        unless File.file?(absolute)
+          create_file PROCFILE, "#{WEB_PROCESS}\n#{CABLE_PROCESS}\n"
+          return
+        end
+
+        if File.read(absolute).match?(/^cable:/)
+          say_status :skip, "#{PROCFILE} already defines a cable process", :yellow
+          return
+        end
+
+        append_to_file PROCFILE, "#{CABLE_PROCESS}\n"
+      end
+
+      def copy_overflow_migration
+        return unless options[:overflow]
+
+        source = File.join(MIGRATION_SOURCE_DIR, MIGRATION_FILENAME)
+
+        unless File.file?(source)
+          say_status :skip,
+                     "overflow migration is not bundled with this build (#{MIGRATION_FILENAME})",
+                     :yellow
+          return
+        end
+
+        create_file "db/orbitcast_migrate/#{MIGRATION_FILENAME}", File.read(source)
+      end
+
+      def print_post_install_instructions
+        say ""
+        say "Orbitcast installed.", :green
+        say ""
+        say "What was applied:"
+        say "  config/cable.yml, config/initializers/orbitcast.rb,"
+        say "  config/environments/development.rb + production.rb (mount_path = nil, url,"
+        say "  allowed_request_origins, config.orbitcast.mode = :signed; existing values kept),"
+        say "  action_cable_meta_tag in the application layout, and a Procfile.dev cable process."
+        say "  Importmap pins, @rails/actioncable imports, Solid Queue and Solid Cache were not touched."
+        if options[:overflow]
+          say "  db/orbitcast_migrate/#{MIGRATION_FILENAME} (run bin/rails db:migrate) and"
+          say "  overflow_enabled: true in cable.yml and the initializer."
+        end
+        say ""
+        say "Next:"
+        say "  1. Production: set ORBITCAST_CABLE_URL (wss://app.example/cable), APP_ORIGIN,"
+        say "     ORBITCAST_DATABASE_URL and ORBITCAST_LISTEN_ADDR for the relay process."
+        say "  2. Run the relay as a separate, supervised process:"
+        say "       #{CABLE_PROCESS}"
+        say ""
+        say "Signed-mode capability boundary: signed streams only.", :yellow
+        say "In signed mode NO connection or channel callbacks run:"
+        say "ApplicationCable::Connection#connect, Channel#subscribed/#unsubscribed, and"
+        say "`perform` actions are NOT executed by the relay. turbo_stream_from and"
+        say "ActionCable.server.broadcast work; custom channel classes need mode: :dispatch."
+        say ""
+      end
+
+      private
+
+      # Namespace every publication and NOTIFY channel is scoped to. Derived
+      # from the application module name so two applications sharing one
+      # PostgreSQL database never share channels.
+      def application_namespace
+        base =
+          if defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+            ::Rails.application.class.module_parent_name.to_s
+          else
+            File.basename(destination_root.to_s)
+          end
+
+        sanitized = base.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.gsub(/[^a-z0-9_]+/, "_")
+        sanitized = sanitized.sub(/\A[^a-z0-9]+/, "").sub(/_+\z/, "")
+        sanitized = "app" if sanitized.empty?
+        # Configuration::NAMESPACE_PATTERN allows 64 characters; leave room for
+        # the "_development" / "_production" suffix.
+        sanitized[0, 40]
+      end
+
+      def overflow?
+        options[:overflow]
+      end
+    end
+  end
+end

data/lib/generators/orbitcast/install/templates/cable.yml.tt

@@ -0,0 +1,48 @@
+# Orbitcast cable configuration.
+#
+# `adapter: orbitcast` selects a publish-only ActionCable adapter: Rails
+# publishes broadcasts through PostgreSQL NOTIFY and the separately supervised
+# Rust relay serves /cable. A local subscribe raises instead of starting a
+# second WebSocket server.
+#
+#   database_url  DSN of the cable database. It may be a dedicated PostgreSQL
+#                 database even when the application itself runs on SQLite or
+#                 MySQL; nothing here converts your primary database.
+#                 The relay's listener needs a real session (direct connection
+#                 or session pooling) — never PgBouncer transaction pooling.
+#   namespace     Scopes every NOTIFY channel and every publication envelope.
+#                 Two deployments sharing one database MUST use different
+#                 namespaces, and isolated namespaces need distinct Turbo keys.
+#   publish_via   postgres (default). The alternative, http, publishes to
+#                 the relay's private ingress instead of PostgreSQL and
+#                 needs ingress_url + ingress_token.
+#   connection    pool (default): a dedicated pg pool for database_url.
+#                 active_record: publish on the application's Active Record
+#                 connection so a broadcast joins (and rolls back with) the
+#                 surrounding transaction; the cable database must then be
+#                 the application's primary database.
+#   overflow_enabled  Relay payloads above the NOTIFY limit through the
+#                 orbitcast_payloads table (needs the --overflow migration).
+
+development:
+  adapter: orbitcast
+  database_url: <%%= ENV.fetch("ORBITCAST_DATABASE_URL", "postgres://localhost/<%= application_namespace %>_cable_development") %>
+  namespace: "<%= application_namespace %>_development"
+  publish_via: postgres
+<% if overflow? -%>
+  overflow_enabled: true
+<% end -%>
+
+# Rails' in-process test adapter keeps application tests isolated; Orbitcast's
+# real publication path is covered by integration tests against a live database.
+test:
+  adapter: test
+
+production:
+  adapter: orbitcast
+  database_url: <%%= ENV.fetch("ORBITCAST_DATABASE_URL") %>
+  namespace: "<%= application_namespace %>_production"
+  publish_via: postgres
+<% if overflow? -%>
+  overflow_enabled: true
+<% end -%>

data/lib/generators/orbitcast/install/templates/orbitcast.rb.tt

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+# Orbitcast configuration.
+#
+# Precedence is CLI > ORBITCAST_* environment > this file / cable.yml >
+# defaults. `bundle exec orbitcast serve` boots Rails once, reads these values,
+# and exports an allowlisted ORBITCAST_* environment to the relay process.
+# Key material is exported as strict base64 (ORBITCAST_*_SECRET_BASE64) and
+# never as a command-line argument. RAILS_MASTER_KEY and SECRET_KEY_BASE are
+# never exported.
+#
+# namespace, database_url, and publish_via come from config/cable.yml.
+Orbitcast.configure do |config|
+  # The default mode. Signed streams are read capabilities issued by an
+  # authorized Rails request; the relay runs no application Ruby, so
+  # ApplicationCable::Connection#connect, channel #subscribed, and `perform`
+  # actions are NOT executed. See the :dispatch section below for the mode
+  # that does execute them.
+  config.mode = :signed
+
+  # Key for Orbitcast::StreamsChannel tokens (Orbitcast.signed_stream_name).
+  #
+  # Without an explicit key, the gem derives one from the application's key
+  # generator under the purpose "orbitcast/streams/v1/<namespace>" (32 bytes):
+  # stable across restarts, different per namespace, and never the master key
+  # or secret_key_base themselves. Set one explicitly to rotate independently
+  # of secret_key_base, or to share a key between deployments:
+  #
+  #   bin/rails credentials:edit
+  #   orbitcast:
+  #     streams_secret: <32+ random bytes, base64 or hex>
+  streams_secret =
+    Rails.application.credentials.dig(:orbitcast, :streams_secret) ||
+    ENV["ORBITCAST_STREAMS_SECRET"]
+  config.streams_secret = streams_secret if streams_secret.present?
+
+  # Key rotation: retired keys that still VERIFY (never sign) while old
+  # signed names expire. Same for Turbo keys (config.turbo_previous_secrets).
+  # config.streams_previous_secrets = [Rails.application.credentials.dig(:orbitcast, :previous_streams_secret)].compact
+
+  # Overflow relay for broadcasts above PostgreSQL's 8000-byte NOTIFY limit.
+  # Needs db/orbitcast_migrate/001_create_orbitcast_payloads.rb migrated on
+  # the cable database (bin/rails generate orbitcast:install --overflow).
+<% if overflow? -%>
+  config.overflow_enabled = true
+<% else -%>
+  # config.overflow_enabled = true
+<% end -%>
+
+  # --- Relay process ---------------------------------------------------------
+  #
+  # `bundle exec orbitcast serve` exports these to the relay. In development
+  # and test the listener defaults to 127.0.0.1:28080 (matching
+  # config.action_cable.url); production MUST set one here or through
+  # ORBITCAST_LISTEN_ADDR in the relay's environment.
+  # config.listen_addr = "0.0.0.0:28080"
+  # config.listener_database_url = ENV["ORBITCAST_LISTENER_DATABASE_URL"] # session-pooled DSN for LISTEN
+  # config.trusted_proxies = ["10.0.0.0/8"]   # CIDRs allowed to set forwarded headers
+  # config.outbound_queue_messages = 1024     # per-connection outbound ceilings
+  # config.outbound_queue_bytes = 4 * 1024 * 1024
+
+  # Optional tuning.
+  # config.connection = :pool       # or :active_record to join the app transaction
+  # config.pool_size = 5            # dedicated pg publisher connections
+  # config.pool_timeout = 5.0       # seconds to wait for one
+  # config.stream_expires_in = 3600 # default TTL of a signed stream name
+
+  # --- Rails-dispatch mode (opt-in) ----------------------------------------
+  #
+  # In :dispatch mode the relay still holds the socket, but it calls back into
+  # this application over a private HTTP endpoint for every decision:
+  # ApplicationCable::Connection#connect, channel #subscribed / #unsubscribed,
+  # and `perform` actions all run here, as ordinary Rails code. Channels
+  # inherit from Orbitcast::Channel (a real ActionCable::Channel::Base
+  # subclass) and record ordered effects instead of touching pubsub directly.
+  #
+  # Turn it on deliberately: it is a callback surface, and it is authenticated
+  # by a dedicated service credential. Without rpc_token, boot fails rather
+  # than exposing an open endpoint.
+  #
+  #   config.mode = :dispatch
+  #   config.rpc_token = Rails.application.credentials.dig(:orbitcast, :rpc_token)
+  #   config.rpc_endpoint_url = "https://app.internal/_orbitcast/v1/rails"
+  #   config.connection_class = "ApplicationCable::Connection"
+  #   # The channel allowlist. :auto derives it from app/channels; a list is
+  #   # explicit. A client-supplied channel name outside it is never
+  #   # constantized.
+  #   config.channels = :auto
+
+  # --- Recovery (opt-in) ---------------------------------------------------
+  #
+  # A recovery token lets one browser session replay retained history on the
+  # reserved Orbitcast::RecoveryChannel. It is a separate capability with a
+  # separate key: purpose "recover", never "subscribe", and there is no
+  # fallback to streams_secret in either direction. It also needs the relay
+  # running with the broker enabled and the orbitcast_broker migration
+  # installed; without both, nothing here does anything.
+  #
+  #   recovery_secret =
+  #     Rails.application.credentials.dig(:orbitcast, :recovery_secret) ||
+  #     ENV["ORBITCAST_RECOVERY_SECRET"]
+  #   config.recovery_secret = recovery_secret if recovery_secret.present?
+  #
+  # Mint one from the same authorization decision that produced the
+  # subscription, and keep the lifetime short:
+  #
+  #   Orbitcast.recovery_token(
+  #     session_id: "session:#{current_user.id}",
+  #     streams: [Room.find(params[:id]).to_gid_param],
+  #     expires_in: 900
+  #   )
+end
+
+# --- Presence (dispatch mode only) -----------------------------------------
+#
+# Presence needs no transport extension and no client patch: a stock
+# @rails/actioncable subscription speaks it. What it does need is a Rails
+# decision, because identity is never client-chosen — the browser sends an
+# operation and a page window, and nothing else.
+#
+# Grant it from a channel callback, where the application already knows who is
+# asking:
+#
+#   class RoomChannel < ApplicationCable::Channel
+#     def subscribed
+#       room = Room.find(params[:id])
+#       return reject unless current_user.can_read?(room)
+#
+#       stream_for room
+#       grant_presence broadcasting_for(room),
+#                      subject_id: "user:#{current_user.id}",
+#                      metadata: { name: current_user.name },  # public to the room
+#                      ttl: 45,                                # seconds
+#                      operations: %w[join leave snapshot]
+#     end
+#
+#     def kick(data)
+#       revoke_presence broadcasting_for(room), subject_id: "user:#{data["id"]}"
+#     end
+#   end
+#
+# `metadata` is broadcast to every member of the stream, so nothing private
+# belongs in it. A `subject_id` a client sends anyway is an unknown field on
+# the presence command and is ignored — the grant above is the only source.
+
+# Turbo's signed stream names use Turbo's own key, which Rails derives with the
+# key generator (NOT secret_key_base) inside an after_initialize hook. Reading
+# it any earlier raises, so export it from one too: the launcher base64-encodes
+# these exact bytes into ORBITCAST_TURBO_SECRET_BASE64.
+#
+# Remove this block if the application does not use turbo_stream_from.
+Rails.application.config.after_initialize do
+  Orbitcast.configure do |config|
+    config.turbo_secret = Turbo.signed_stream_verifier_key if defined?(Turbo)
+  end
+end

data/lib/orbitcast/binary.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "rbconfig"
+require "rubygems"
+
+require_relative "error"
+require_relative "version"
+
+module Orbitcast
+  # Resolves the vendored Orbitcast executable.
+  #
+  # Resolution is relative to *this* file, i.e. the activated gem, never a
+  # recursive `PATH` search: a native gem ships exactly one binary and that is
+  # the one it must run. `ORBITCAST_BINARY` overrides it for source builds and
+  # for platforms without a published artifact. There is no download, no
+  # compiler invocation, and no architecture guessing.
+  #
+  # An override is *verified* before it is used: `<binary> doctor
+  # --json` must report this gem's
+  # version, envelope version 1, and every feature the configuration needs.
+  # The vendored binary was packaged with this exact gem version and skips the
+  # check.
+  module Binary
+    EXECUTABLE = "orbitcast"
+    OVERRIDE_ENV = "ORBITCAST_BINARY"
+
+    # Envelope version this gem speaks; the binary must list it.
+    ENVELOPE_VERSION = 1
+
+    # Upper bound on `doctor --json`. A binary that cannot describe itself in
+    # this long is not one to hand the listener socket to.
+    DOCTOR_TIMEOUT = 5.0
+
+    class << self
+      # @param env [Hash] process environment (ENV, or a Hash in tests)
+      # @param verify [Boolean] run `doctor --json` on an override
+      # @param require_features [Array<String>] features the override must
+      #   have been built with (e.g. `["postgres"]` for `publish_via: postgres`)
+      # @param timeout [Numeric] seconds to wait for `doctor --json`
+      # @return [String] absolute path to an existing executable file
+      def path(env: ENV, verify: false, require_features: [], timeout: DOCTOR_TIMEOUT)
+        override = env[OVERRIDE_ENV]
+        return vendored_path if override.nil? || override.empty?
+
+        resolved = override_path(override)
+        verify!(resolved, require_features: require_features, timeout: timeout, env: env) if verify
+        resolved
+      end
+
+      # Run `<binary> doctor --json` and check what it reports against this
+      # gem. Public so `orbitcast doctor` style tooling can reuse it.
+      #
+      # @raise [BinaryError] with a message naming the exact mismatch
+      # @return [Hash] the parsed doctor report
+      def verify!(binary, require_features: [], timeout: DOCTOR_TIMEOUT, env: ENV)
+        report = doctor_report(binary, timeout: timeout, env: env)
+
+        version = report["version"].to_s
+        unless version == VERSION
+          raise BinaryError,
+                "#{OVERRIDE_ENV}=#{binary} is orbitcast #{version.empty? ? "(unknown version)" : version}, " \
+                "but this gem is orbitcast #{VERSION}. Build the matching release " \
+                "(git checkout v#{VERSION} && cargo build --release --features postgres) or install " \
+                "the platform gem instead of overriding the binary."
+        end
+
+        envelopes = Array(report["envelope_versions"]).map { |value| Integer(value, exception: false) }
+        unless envelopes.include?(ENVELOPE_VERSION)
+          raise BinaryError,
+                "#{OVERRIDE_ENV}=#{binary} speaks envelope versions " \
+                "#{envelopes.compact.inspect}, but this gem requires version #{ENVELOPE_VERSION}."
+        end
+
+        features = Array(report["features"]).map(&:to_s)
+        missing = Array(require_features).map(&:to_s) - features
+        unless missing.empty?
+          raise BinaryError,
+                "#{OVERRIDE_ENV}=#{binary} was built without the #{missing.join(", ")} " \
+                "feature#{"s" if missing.size > 1} (reported features: #{features.inspect}). " \
+                "Rebuild with: cargo build --release --features #{missing.join(",")}"
+        end
+
+        report
+      end
+
+      # @return [Boolean] whether a binary is available without an override
+      def vendored?
+        File.file?(vendored_binary) && File.executable?(vendored_binary)
+      end
+
+      def vendored_binary(platform = gem_platform)
+        File.join(vendor_root, platform, "bin", EXECUTABLE)
+      end
+
+      def manifest_path(platform = gem_platform)
+        File.join(vendor_root, platform, "manifest.json")
+      end
+
+      # gem/vendor -- `__dir__` is gem/lib/orbitcast.
+      def vendor_root
+        File.expand_path("../../vendor", __dir__)
+      end
+
+      # Gem platform label used for the vendor directory.
+      #
+      # `Gem::Platform.local` carries an OS version we do not build against
+      # (`arm64-darwin-23`), so darwin is truncated to `<cpu>-darwin`. On Linux
+      # the version field is the libc: RubyGems treats a bare `*-linux` as a
+      # libc wildcard that can also match musl, so we resolve it explicitly to
+      # `gnu` here and only use `-musl` for an actual musl build.
+      def gem_platform(platform = Gem::Platform.local)
+        cpu = platform.cpu || "unknown"
+
+        case platform.os
+        when "linux"
+          libc = platform.version.to_s
+          libc = "gnu" if libc.empty? || libc == "linux"
+          "#{cpu}-linux-#{libc}"
+        when "darwin"
+          "#{cpu}-darwin"
+        else
+          [cpu, platform.os, platform.version].compact.reject(&:empty?).join("-")
+        end
+      end
+
+      private
+
+      # `doctor --json` in a minimal environment: it needs no configuration to
+      # report its version and build, and must not see application secrets.
+      def doctor_report(binary, timeout:, env:)
+        child_env = { "PATH" => env["PATH"], "HOME" => env["HOME"], "ORBITCAST_LOG" => "error" }.compact
+        stdout = stderr = ""
+        status = nil
+
+        Open3.popen3(child_env, [binary, binary], "doctor", "--json",
+                     unsetenv_others: true, close_others: true) do |stdin, out, err, waiter|
+          stdin.close
+          out_reader = Thread.new { out.read }
+          err_reader = Thread.new { err.read }
+          # popen3 closes the pipes when this block unwinds; a reader still
+          # blocked in IO#read would then die with IOError and Ruby would print
+          # it. The readers are joined on every exit path below instead.
+          [out_reader, err_reader].each { |thread| thread.report_on_exception = false }
+
+          unless waiter.join(timeout)
+            begin
+              Process.kill("KILL", waiter.pid)
+            rescue SystemCallError
+              nil
+            end
+            waiter.join(1)
+            [out_reader, err_reader].each { |thread| thread.join(1) }
+            raise BinaryError,
+                  "#{OVERRIDE_ENV}=#{binary}: `doctor --json` did not finish within #{timeout}s; " \
+                  "refusing to use a binary that cannot describe itself."
+          end
+
+          status = waiter.value
+          stdout = out_reader.value.to_s
+          stderr = err_reader.value.to_s
+        end
+
+        parse_report(binary, stdout, stderr, status)
+      rescue SystemCallError => e
+        raise BinaryError, "#{OVERRIDE_ENV}=#{binary}: could not run `doctor --json` (#{e.message})"
+      end
+
+      def parse_report(binary, stdout, stderr, status)
+        report = JSON.parse(stdout)
+        raise JSON::ParserError, "not a JSON object" unless report.is_a?(Hash)
+
+        report
+      rescue JSON::ParserError => e
+        detail = stderr.strip.lines.first(3).join.strip
+        raise BinaryError,
+              "#{OVERRIDE_ENV}=#{binary}: `doctor --json` did not print a JSON report " \
+              "(#{e.message}; exit status #{status&.exitstatus.inspect}" \
+              "#{detail.empty? ? "" : "; stderr: #{detail}"}). Is this an orbitcast #{VERSION} build?"
+      end
+
+      def override_path(override)
+        expanded = File.expand_path(override)
+
+        unless File.file?(expanded)
+          raise BinaryNotFoundError,
+                "#{OVERRIDE_ENV}=#{override} does not point at a file " \
+                "(resolved to #{expanded}). Set it to an orbitcast #{VERSION} executable, " \
+                "or unset it to use the binary vendored in this gem."
+        end
+
+        unless File.executable?(expanded)
+          raise BinaryNotFoundError,
+                "#{OVERRIDE_ENV}=#{override} is not executable (resolved to #{expanded}). " \
+                "Run: chmod +x #{expanded}"
+        end
+
+        expanded
+      end
+
+      def vendored_path
+        candidate = vendored_binary
+
+        unless File.file?(candidate)
+          raise BinaryNotFoundError, missing_vendored_message(candidate)
+        end
+
+        unless File.executable?(candidate)
+          raise BinaryNotFoundError,
+                "vendored orbitcast binary at #{candidate} is not executable. " \
+                "Reinstall the gem, or run: chmod +x #{candidate}"
+        end
+
+        candidate
+      end
+
+      def missing_vendored_message(candidate)
+        <<~MESSAGE.strip
+          No orbitcast executable for platform #{gem_platform} (expected #{candidate}).
+
+          This gem installation has no binary for your platform. Either:
+            1. install the platform gem for #{gem_platform}, e.g.
+               bundle lock --add-platform #{gem_platform}
+            2. build orbitcast #{VERSION} from source and point at it:
+               cargo build --release --features postgres
+               export #{OVERRIDE_ENV}=/path/to/target/release/#{EXECUTABLE}
+
+          Orbitcast never downloads or compiles a binary for you.
+        MESSAGE
+      end
+    end
+  end
+end