open-in-editor-bridge 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ec2cde5e04f7296d806dcfeff4926492de642d4b09983478295b3bc45a68f08
-  data.tar.gz: 60e87f9f41f6207bd75bb58fce1c0daa4118af0b3bbbd4cb64030eedd83a3f56
+  metadata.gz: 894d087228ad0690acd8e32f1f2284240055e9b934965fd181556adc7aba116b
+  data.tar.gz: f5fd6f10dc3110132077b781224d9c1e67eb46d9c6c83d85f0f083cca89b1391
 SHA512:
-  metadata.gz: 8e767cca6409335c11dee8e522f1ba6b04e973ec638bad090a089ac2e998544ac347287805f4475a9739cd61448d6dbe3cd13577a95dde1733b4def30b040959
-  data.tar.gz: 5b48df59f4d402e62c3cff453ba6523b4c775c4744c00c48324f0cbb145f258a8d97bae825542fd2b44967614c9dfa880955793a5356545107a5a646c4c7e6b8
+  metadata.gz: 00a3e25e014adfdff6d33fa389e4eb11d75ba364fb89536d83b83128154854322dc367938544d34ccad2ffab7a5487ad3f7a3d4f135c35ec5694ebb15f2c315b
+  data.tar.gz: 1b6a96b2710f51240f152028b49d0b9ac573dc844d7bb6c8177586faaf3c4a59cd18cf6c09aba920fafd688e22350be1403d6ddf102a606a6cb81af2bdb47260

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.2.0 — 2026-10-09
+
+### Added
+
+- Shared host broker with checkout-specific editor sessions and simultaneous-start coordination.
+- `OPEN_IN_EDITOR_BRIDGE_BIND_ADDRESS` for explicit Docker-reachable binding; loopback remains the default.
+- Stable checkout IDs through `OpenInEditorBridge.session_id`, `--session-id`, and the `with_running` block argument.
+- Independent foreground leases and idempotent detached registration for Compose `up -d` / `down`.
+
+### Changed
+
+- Shutdown releases only the calling checkout's detached registration; the last active lease stops the broker.
+- Shared private runtime state replaces checkout-local PID/log files. Stop 0.1.x bridges before upgrading.
+- Multi-checkout editor links require an explicit `session` query parameter; single-checkout links remain valid.
+- Registration/release use nonce-bound HMAC-authenticated requests/responses and verify protocol/PID identity without transmitting the control secret or signaling disk-sourced PIDs.
+
+### Fixed
+
+- Incorrect host-checkout routing and duplicate-port startup failures for concurrent worktrees.
+- Premature detached-session cleanup when using the documented persistent lifecycle.
+- Path-prefix collisions and double decoding of percent-encoded filenames.
+- Relative editor commands now execute in the requesting checkout, not the checkout that first started the broker.
+- Failed health probes preserve live shared-broker credentials instead of orphaning active sessions.
+- Malformed authentication bytes are rejected without terminating other checkout sessions.

data/README.md

@@ -1,49 +1,131 @@
 # OpenInEditorBridge
 
-A small Ruby gem that runs a local HTTP bridge for opening files from a container in the host editor.
+A Ruby gem that runs a shared local HTTP bridge for opening container files in the correct host checkout's editor. Requires Ruby 3.2 or newer; no runtime gem dependencies.
 
 ## Install
 
 ```ruby
-gem "open-in-editor-bridge"
+gem "open-in-editor-bridge", "~> 0.2"
 ```
 
-## Ruby API
+```sh
+gem install open-in-editor-bridge
+```
+
+## Foreground Ruby API
 
-Wrap the local development command that needs the bridge:
+Wrap commands whose lifetime matches the application, such as foreground Compose:
 
 ```ruby
 require "open_in_editor_bridge"
 
-OpenInEditorBridge.with_running do
-  # Run the command that emits open-in-editor links.
+OpenInEditorBridge.with_running do |session_id|
+  ENV["OPEN_IN_EDITOR_SESSION_ID"] = session_id
+  system("docker", "compose", "up", exception: true)
 end
 ```
 
-Use `ensure_running: false` when the wrapped command is responsible for stopping the bridge:
+The block returns its normal result. Its checkout lease is released in `ensure`, including when the block raises; cleanup does not replace the original exception. Overlapping wrappers have independent leases, even in the same checkout. Finishing one wrapper never releases another wrapper or an existing detached registration.
+
+`OpenInEditorBridge.session_id` returns the stable ID for the configured checkout without starting the bridge. `OpenInEditorBridge.new(env: ..., project_root: ...)` supports explicit configuration for library consumers.
+
+## Detached Compose
+
+`up -d` returns before the application stops. Use persistent registration, **not** `with_running` around detached startup:
+
+```ruby
+require "open_in_editor_bridge"
+
+OpenInEditorBridge.call("--ensure-running")
+ENV["OPEN_IN_EDITOR_SESSION_ID"] = OpenInEditorBridge.session_id
+system("docker", "compose", "up", "-d", exception: true)
+```
+
+Release that checkout's persistent registration when taking it down:
 
 ```ruby
-OpenInEditorBridge.with_running(ensure_running: false) { run_down_command }
+OpenInEditorBridge.with_running(ensure_running: false) do
+  system("docker", "compose", "down", exception: true)
+end
 ```
 
-The bridge is stopped in the wrapper's `ensure` path. A block exception remains the raised exception.
+`ensure_running: false` does not register a new lease and releases only the detached registration after the block. You can alternatively call `OpenInEditorBridge.call("--shutdown")` directly. Repeated `--ensure-running` calls are idempotent for a checkout; one `--shutdown` releases its detached registration. Foreground leases and registrations for other checkouts remain active. The listener exits when the last lease is released.
 
 ## CLI
 
+Run lifecycle commands from the host checkout (or set `OPEN_IN_EDITOR_PROJECT_ROOT` explicitly):
+
 ```sh
+export OPEN_IN_EDITOR_COMMAND='code'
+# Explicit opt-in for Docker bridge-network access; read the security section.
+export OPEN_IN_EDITOR_BRIDGE_BIND_ADDRESS=0.0.0.0
+export OPEN_IN_EDITOR_SESSION_ID="$(open-in-editor-bridge --session-id)"
 open-in-editor-bridge --ensure-running
+docker compose up -d
+
+# Later, with the same port, bind address, runtime directory, and project root:
+docker compose down
 open-in-editor-bridge --shutdown
-open-in-editor-bridge --serve
 ```
 
-The server provides `GET /health` and `GET /__open-in-editor?file=...`. Container paths beginning with `/usr/src/web` are mapped to the host `web` directory, preserving optional `:line:column` locations.
+`--serve` runs the broker in the foreground and registers the current checkout. It requires a free port. Prefer the managed lifecycle above for sharing: manually interrupting a foreground broker stops all its sessions.
+
+## Docker and Checkout Routing
+
+All worktrees using one listener must agree on port, bind address, and runtime directory. Each checkout registers its own host-root mapping and editor command. Simultaneous startup is serialized by a shared per-port lock, not by checkout-local pidfiles.
+
+On Linux, make the host accessible from Compose and pass the checkout ID into the web service:
+
+```yaml
+services:
+  web:
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      OPEN_IN_EDITOR_SESSION_ID: "${OPEN_IN_EDITOR_SESSION_ID:?Set the host checkout session ID}"
+```
+
+The container's dev-server proxy must forward editor requests to `http://host.docker.internal:3333` and add its `OPEN_IN_EDITOR_SESSION_ID` as the `session` query parameter. For example:
+
+```text
+GET /__open-in-editor?session=<checkout-id>&file=%2Fusr%2Fsrc%2Fweb%2Fapp.rb%3A12%3A4
+```
+
+`GET /health` reports the broker PID, protocol, bind address, and active checkout IDs. `GET /__open-in-editor` spawns the registered editor with `--goto <translated-target>`, preserving optional `:line:column`. Container paths equal to or below `/usr/src/web` map to that checkout's host `web` directory. Other paths pass through unchanged. Query encoding is decoded exactly once, preserving literal percent sequences in filenames.
+
+With exactly one checkout, existing links without `session` still work. With multiple checkouts, missing `session` returns HTTP 400 rather than guessing a checkout; unknown IDs return HTTP 404. Registering the same checkout with different roots or editor configuration while it is active is rejected; stop its existing leases before changing configuration.
 
 ## Configuration
 
-- `OPEN_IN_EDITOR_BRIDGE_PORT` (default `3333`)
-- `OPEN_IN_EDITOR_PROJECT_ROOT` (default current directory)
-- `OPEN_IN_EDITOR_CONTAINER_WEB_ROOT` (default `/usr/src/web`)
-- `OPEN_IN_EDITOR_HOST_WEB_ROOT` (default `<project-root>/web`)
-- `OPEN_IN_EDITOR_COMMAND` (or `EDITOR`)
+| Variable | Default | Purpose |
+|---|---|---|
+| `OPEN_IN_EDITOR_BRIDGE_PORT` | `3333` | Shared host listener port |
+| `OPEN_IN_EDITOR_BRIDGE_BIND_ADDRESS` | `127.0.0.1` | Listener address; `0.0.0.0` allows Docker IPv4 access |
+| `OPEN_IN_EDITOR_PROJECT_ROOT` | Current directory | Checkout identity and default host mapping |
+| `OPEN_IN_EDITOR_CONTAINER_WEB_ROOT` | `/usr/src/web` | Container directory to translate |
+| `OPEN_IN_EDITOR_HOST_WEB_ROOT` | `<project-root>/web` | Corresponding host directory |
+| `OPEN_IN_EDITOR_COMMAND` | `EDITOR` | Editor command, parsed with `Shellwords` |
+| `OPEN_IN_EDITOR_BRIDGE_RUNTIME_DIR` | `<system-tmp>/open-in-editor-bridge-<uid>` | Shared private host runtime state |
+| `OPEN_IN_EDITOR_BRIDGE_STARTUP_TIMEOUT` | `5` seconds | Startup/shutdown deadline |
+
+The editor command is required when registering a checkout, but not for `--session-id` or `--shutdown`. Editors run in their registered checkout's project root, so relative commands such as `./bin/editor` resolve in the correct checkout. Runtime directories must be owned by the current user and private (`0700`). Broker state and its control token use `0600`; runtime files are keyed by port. Checkout IDs derive from the canonical absolute project root.
+
+## Security and Upgrade Notes
+
+Loopback binding is the default. `0.0.0.0` also exposes the listener to other reachable network peers, not only Docker. Use it only on a trusted development network with host firewall restrictions; a specific Docker-reachable host interface can narrow exposure. Editor requests are intentionally unauthenticated and health exposes checkout IDs: anyone who can reach the listener can invoke configured editors. Do not expose it on an untrusted network or forward it publicly.
+
+Registration and release use nonce-bound HMAC signatures derived from a random control token held in the private host runtime directory; the token is never sent over HTTP. Clients authenticate health and control responses and verify broker protocol/PID against shared state. The broker rejects replayed control requests. Shutdown uses authenticated HTTP control, never signals a PID read from disk. Unknown listeners, old bridge versions, mismatched PIDs, and mismatched bind configurations are not reused.
+
+A failed or timed-out health probe does not discard a still-listening broker's credentials. Lifecycle operations fail explicitly until its identity can be verified; retry after the listener becomes responsive.
+
+Version 0.2 replaces checkout-local PID/log files with shared runtime state. Stop any 0.1.x bridge using its original installed version before upgrading; it cannot share the new protocol. Sessions live in the broker's memory. After a broker crash or deliberate manual stop, rerun `--ensure-running` for detached applications. Abruptly killed foreground clients cannot execute `ensure`; stop that broker manually and re-register surviving checkouts if their leases become orphaned.
+
+## Development and Release
+
+```sh
+bundle install
+bundle exec rake test
+gem build open-in-editor-bridge.gemspec
+```
 
-The editor command is required and is parsed with `Shellwords`.
+Release changes on an issue-linked branch and pull request, including the version and changelog. Self-review and exercise real host/container lifecycle and editor invocation before merging. From synchronized `main`, build and push the gem with the maintainer's RubyGems credentials, then create a matching GitHub tag/release. Install the published version from RubyGems into a clean `GEM_HOME`, confirm `OpenInEditorBridge::VERSION`, and repeat foreground, detached, routing, and Docker-reachability checks. A recorded editor process proves invocation and arguments, not that an editor window rendered.

data/lib/open_in_editor_bridge/authentication.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+class OpenInEditorBridge
+  module Authentication
+    def self.signature(token, direction, nonce, method_or_status, path, body)
+      digest = OpenSSL::HMAC.new(token, "SHA256")
+      [direction, nonce, method_or_status, path, body].each do |part|
+        bytes = part.to_s
+        digest << [bytes.bytesize].pack("Q>") << bytes
+      end
+      digest.hexdigest
+    end
+
+    def self.valid_nonce?(nonce)
+      nonce.is_a?(String) && nonce.ascii_only? && nonce.match?(/\A[0-9a-f]{32}\z/)
+    end
+
+    def self.valid?(provided, token, *message)
+      return false unless provided.is_a?(String) && token.is_a?(String) && !token.empty?
+
+      expected = signature(token, *message)
+      return false unless provided.bytesize == expected.bytesize
+
+      OpenSSL.fixed_length_secure_compare(expected, provided)
+    end
+  end
+end

data/lib/open_in_editor_bridge/client.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "rbconfig"
+require "securerandom"
+
+class OpenInEditorBridge
+  class Client
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def register(lease)
+      session = @configuration.session
+      @configuration.synchronize do
+        state = compatible_state
+        state ||= start_broker
+        payload = control_request("/sessions", state, "session" => session, "lease" => lease)
+        result = payload.fetch("added") ? :started : :reused
+        puts "Editor session #{session.fetch("id")} #{result} on port #{@configuration.port}."
+        result
+      end
+    end
+
+    def release(lease)
+      @configuration.synchronize do
+        state = compatible_state
+        return unless state
+
+        payload = control_request("/release", state, "session_id" => @configuration.session_id, "lease" => lease)
+        wait_until_stopped(state.fetch("pid")) if payload.fetch("stopping")
+      end
+    end
+
+    def serve
+      server = @configuration.synchronize do
+        raise StartupError, "Editor bridge is already running" if compatible_state
+        token = SecureRandom.hex(32)
+        broker = Server.new(@configuration, token: token)
+        broker.start(initial_session: @configuration.session)
+        broker
+      end
+      server.serve
+    end
+
+    private
+
+    def health(state: nil)
+      nonce = SecureRandom.hex(16)
+      request = Net::HTTP::Get.new("/health")
+      request["X-Open-In-Editor-Nonce"] = nonce
+      response = http_request(request)
+      return nil unless response && response.code == "200" && response["X-Open-In-Editor-Bridge"] == Configuration::PROTOCOL.to_s
+      if state
+        return nil unless Authentication.valid?(response["X-Open-In-Editor-Signature"], state["token"],
+          "response", nonce, response.code, "/health", response.body)
+      end
+
+      payload = JSON.parse(response.body)
+      return nil unless payload.is_a?(Hash) && payload["ok"] == true && payload["protocol"] == Configuration::PROTOCOL
+      payload
+    rescue JSON::ParserError
+      nil
+    end
+
+    def compatible_state
+      state = @configuration.read_state
+      current_health = health(state: state)
+      if current_health
+        unless state && state["pid"] == current_health["pid"] && state["protocol"] == Configuration::PROTOCOL &&
+            state["bind_address"] == @configuration.bind_address && current_health["bind_address"] == @configuration.bind_address &&
+            state["token"].is_a?(String) && !state["token"].empty?
+          raise StartupError, "Listener identity or bind address does not match shared runtime state"
+        end
+        return state
+      end
+      if listener_present?
+        raise StartupError, "Port is occupied by an unknown or unresponsive listener; shared state preserved"
+      end
+      if state
+        # Never signal a PID read from disk. Only authenticated broker control can stop it.
+        @configuration.delete_state(expected_pid: state["pid"])
+      end
+      nil
+    end
+
+    def listener_present?
+      Socket.tcp(@configuration.connect_address, @configuration.port, connect_timeout: 0.5) { true }
+    rescue Errno::ECONNREFUSED
+      false
+    rescue SystemCallError, Timeout::Error
+      # An inconclusive connection failure is not proof that shared state is stale.
+      true
+    end
+
+    def start_broker
+      token = SecureRandom.hex(32)
+      library_directory = File.expand_path("..", __dir__)
+      script = "configuration = OpenInEditorBridge::Configuration.new(env: ENV); " \
+        "server = OpenInEditorBridge::Server.new(configuration, token: ENV.fetch('OPEN_IN_EDITOR_BRIDGE_CONTROL_TOKEN')); " \
+        "server.start; server.serve"
+      pid = Process.spawn(@configuration.server_environment(token), RbConfig.ruby, "-I", library_directory,
+        "-ropen_in_editor_bridge", "-e", script, out: @configuration.log_file, err: @configuration.log_file, pgroup: true)
+      # Keep the child waitable until readiness proves we own this live PID.
+      deadline = monotonic_time + @configuration.startup_timeout
+      loop do
+        raise StartupError, "Editor bridge failed to start. See #{@configuration.log_file}." if Process.waitpid(pid, Process::WNOHANG)
+        state = @configuration.read_state
+        current_health = health(state: state)
+        if state && state["pid"] == pid && state["token"] == token && current_health && current_health["pid"] == pid
+          Process.detach(pid)
+          return state
+        end
+        raise StartupError, "Editor bridge did not become ready. See #{@configuration.log_file}." if monotonic_time >= deadline
+        sleep 0.05
+      end
+    rescue StandardError
+      if pid
+        begin
+          unless Process.waitpid(pid, Process::WNOHANG)
+            Process.kill("TERM", pid)
+            Process.waitpid(pid)
+          end
+        rescue Errno::ECHILD, Errno::ESRCH
+          # An exited child is not a PID we still own.
+        end
+        @configuration.delete_state(expected_pid: pid)
+      end
+      raise
+    end
+
+    def control_request(path, state, payload)
+      nonce = SecureRandom.hex(16)
+      request = Net::HTTP::Post.new(path)
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(payload)
+      request["X-Open-In-Editor-Nonce"] = nonce
+      request["X-Open-In-Editor-Signature"] = Authentication.signature(state.fetch("token"),
+        "request", nonce, "POST", path, request.body)
+      response = http_request(request)
+      unless response && Authentication.valid?(response["X-Open-In-Editor-Signature"], state.fetch("token"),
+          "response", nonce, response.code, path, response.body)
+        raise StartupError, "Bridge control response failed authentication"
+      end
+      unless response && response.code == "200"
+        raise StartupError, "Bridge session request failed: #{response&.code} #{response&.body}"
+      end
+      JSON.parse(response.body)
+    end
+
+    def http_request(request)
+      Net::HTTP.start(@configuration.connect_address, @configuration.port, nil,
+        open_timeout: 0.5, read_timeout: 0.5, write_timeout: 0.5) { |http| http.request(request) }
+    rescue IOError, SystemCallError, Timeout::Error
+      nil
+    end
+
+    def wait_until_stopped(pid)
+      deadline = monotonic_time + @configuration.startup_timeout
+      loop do
+        state = @configuration.read_state
+        return unless state && state["pid"] == pid
+        raise StartupError, "Editor bridge did not stop" if monotonic_time >= deadline
+        sleep 0.05
+      end
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/open_in_editor_bridge/configuration.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "shellwords"
+require "tmpdir"
+
+class OpenInEditorBridge
+  class Configuration
+    PROTOCOL = 2
+
+    attr_reader :port, :bind_address, :connect_address, :runtime_directory, :startup_timeout, :session_id
+
+    def initialize(env:, project_root: nil)
+      @env = env
+      @project_root = File.expand_path(project_root || env.fetch("OPEN_IN_EDITOR_PROJECT_ROOT", Dir.pwd))
+      @project_root = File.realpath(@project_root) if File.directory?(@project_root)
+      @port = Integer(env.fetch("OPEN_IN_EDITOR_BRIDGE_PORT", "3333"))
+      @bind_address = env.fetch("OPEN_IN_EDITOR_BRIDGE_BIND_ADDRESS", "127.0.0.1")
+      @connect_address = { "0.0.0.0" => "127.0.0.1", "::" => "::1" }.fetch(@bind_address, @bind_address)
+      @runtime_directory = env.fetch("OPEN_IN_EDITOR_BRIDGE_RUNTIME_DIR", File.join(Dir.tmpdir, "open-in-editor-bridge-#{Process.uid}"))
+      @startup_timeout = Float(env.fetch("OPEN_IN_EDITOR_BRIDGE_STARTUP_TIMEOUT", "5"))
+      @session_id = Digest::SHA256.hexdigest(@project_root)
+    end
+
+    def session
+      command = @env.fetch("OPEN_IN_EDITOR_COMMAND", @env.fetch("EDITOR", "")).to_s
+      raise ArgumentError, "No editor configured. Set OPEN_IN_EDITOR_COMMAND or EDITOR." if Shellwords.split(command).empty?
+
+      {
+        "id" => session_id,
+        "working_directory" => @project_root,
+        "container_root" => @env.fetch("OPEN_IN_EDITOR_CONTAINER_WEB_ROOT", "/usr/src/web").delete_suffix("/"),
+        "host_root" => File.expand_path(@env.fetch("OPEN_IN_EDITOR_HOST_WEB_ROOT", File.join(@project_root, "web"))),
+        "editor_command" => command,
+      }
+    end
+
+    def state_file
+      File.join(runtime_directory, "#{port}.json")
+    end
+
+    def log_file
+      File.join(runtime_directory, "#{port}.log")
+    end
+
+    def synchronize
+      ensure_runtime_directory
+      File.open(File.join(runtime_directory, "#{port}.lock"), File::RDWR | File::CREAT, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        yield
+      ensure
+        lock.flock(File::LOCK_UN)
+      end
+    end
+
+    def ensure_runtime_directory
+      begin
+        Dir.mkdir(runtime_directory, 0o700)
+      rescue Errno::EEXIST
+        # Shared by all checkout clients of this user.
+      end
+      stat = File.lstat(runtime_directory)
+      unless stat.directory? && stat.uid == Process.uid && (stat.mode & 0o077).zero?
+        raise StartupError, "Bridge runtime directory must be owned by this user and private (0700): #{runtime_directory}"
+      end
+    end
+
+    def read_state
+      state = JSON.parse(File.read(state_file))
+      state if state.is_a?(Hash)
+    rescue Errno::ENOENT, JSON::ParserError
+      nil
+    end
+
+    def write_state(token)
+      state = { "pid" => Process.pid, "token" => token, "protocol" => PROTOCOL, "bind_address" => bind_address }
+      File.open(state_file, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |file| file.write(JSON.generate(state)) }
+    end
+
+    def delete_state(expected_pid:)
+      File.delete(state_file) if read_state&.fetch("pid", nil) == expected_pid
+    rescue Errno::ENOENT
+      nil
+    end
+
+    def server_environment(token)
+      {
+        "OPEN_IN_EDITOR_BRIDGE_PORT" => port.to_s,
+        "OPEN_IN_EDITOR_BRIDGE_BIND_ADDRESS" => bind_address,
+        "OPEN_IN_EDITOR_BRIDGE_RUNTIME_DIR" => runtime_directory,
+        "OPEN_IN_EDITOR_BRIDGE_CONTROL_TOKEN" => token,
+      }
+    end
+  end
+end

data/lib/open_in_editor_bridge/server.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "socket"
+require "timeout"
+require "uri"
+
+class OpenInEditorBridge
+  class Server
+    RESPONSE_PHRASES = {
+      200 => "OK", 400 => "Bad Request", 403 => "Forbidden", 404 => "Not Found",
+      405 => "Method Not Allowed", 409 => "Conflict", 500 => "Internal Server Error",
+    }.freeze
+
+    def initialize(configuration, token:)
+      @configuration = configuration
+      @token = token
+      # Only this broker mutates sessions; each lease represents one live client.
+      @sessions = {}
+      # Accepted control nonces cannot be replayed during this broker's lifetime.
+      @used_nonces = {}
+    end
+
+    def start(initial_session: nil)
+      @listener = TCPServer.new(@configuration.bind_address, @configuration.port)
+      @sessions[initial_session.fetch("id")] = initial_session.merge("leases" => ["detached"]) if initial_session
+      @configuration.write_state(@token)
+      @running = true
+    rescue StandardError
+      @listener&.close
+      raise
+    end
+
+    def serve
+      trap("INT") { stop }
+      trap("TERM") { stop }
+      while @running
+        begin
+          socket = @listener.accept
+          handle_request(socket)
+        rescue IOError, Errno::EBADF
+          break unless @running
+          raise
+        end
+      end
+    ensure
+      @listener&.close unless @listener&.closed?
+      @configuration.delete_state(expected_pid: Process.pid)
+    end
+
+    private
+
+    def stop
+      @running = false
+      @listener.close unless @listener.closed?
+    end
+
+    def handle_request(socket)
+      Timeout.timeout(2) do
+        method, target, headers, body = read_request(socket)
+        path, query = target.split("?", 2)
+        params = URI.decode_www_form(query.to_s).to_h
+        case path
+        when "/health"
+          if method == "GET"
+            nonce = headers["x-open-in-editor-nonce"]
+            if nonce && !Authentication.valid_nonce?(nonce)
+              return respond(socket, 400, { "error" => "Invalid health nonce" })
+            end
+            respond(socket, 200, { "ok" => true, "pid" => Process.pid, "protocol" => Configuration::PROTOCOL,
+              "bind_address" => @configuration.bind_address, "sessions" => @sessions.keys },
+              nonce: nonce, path: path)
+          else
+            respond(socket, 405, { "error" => "Method not allowed" })
+          end
+        when "/__open-in-editor"
+          method == "GET" ? open_in_editor(socket, params) : respond(socket, 405, { "error" => "Method not allowed" })
+        when "/sessions", "/release"
+          control_request(socket, method, path, headers, body)
+        else
+          respond(socket, 404, { "error" => "Not found" })
+        end
+      end
+    rescue ArgumentError, JSON::ParserError, EOFError => error
+      respond(socket, 400, { "error" => "Bad request: #{error.message}" })
+    rescue Timeout::Error, Errno::EPIPE, Errno::ECONNRESET
+      nil
+    ensure
+      socket.close unless socket.closed?
+    end
+
+    def read_request(socket)
+      line = socket.gets("\n", 8192)
+      raise EOFError, "Missing request line" unless line
+      method, target, = line.split(" ")
+      raise ArgumentError, "Missing request target" unless target
+
+      headers = {}
+      header_bytes = 0
+      loop do
+        line = socket.gets("\n", 8192)
+        raise EOFError, "Incomplete headers" unless line
+        header_bytes += line.bytesize
+        raise ArgumentError, "Headers too large" if header_bytes > 65_536
+        break if line == "\r\n"
+
+        name, value = line.split(":", 2)
+        raise ArgumentError, "Invalid header" unless value
+        headers[name.downcase] = value.strip
+      end
+      length = Integer(headers.fetch("content-length", "0"))
+      raise ArgumentError, "Invalid content length" unless (0..65_536).cover?(length)
+      body = length.zero? ? "" : socket.read(length)
+      raise EOFError, "Incomplete body" unless body && body.bytesize == length
+      [method, target, headers, body]
+    end
+
+    def control_request(socket, method, path, headers, body)
+      return respond(socket, 405, { "error" => "Method not allowed" }) unless method == "POST"
+      nonce = headers["x-open-in-editor-nonce"]
+      valid_nonce = Authentication.valid_nonce?(nonce) && !@used_nonces.key?(nonce)
+      return respond(socket, 403, { "error" => "Forbidden" }) unless valid_nonce
+
+      valid_signature = Authentication.valid?(headers["x-open-in-editor-signature"], @token,
+        "request", nonce, method, path, body)
+      return respond(socket, 403, { "error" => "Forbidden" }) unless valid_signature
+
+      @used_nonces[nonce] = true
+      payload = JSON.parse(body)
+      path == "/sessions" ? register(socket, payload, nonce) : release(socket, payload, nonce)
+    end
+
+    def register(socket, payload, nonce)
+      session = payload.fetch("session")
+      id = session.fetch("id")
+      lease = payload.fetch("lease")
+      existing = @sessions[id]
+      if existing && existing.reject { |key, _| key == "leases" } != session
+        return respond(socket, 409, { "error" => "Checkout already registered with different editor configuration" },
+          nonce: nonce, path: "/sessions")
+      end
+      existing ||= @sessions[id] = session.merge("leases" => [])
+      added = !existing.fetch("leases").include?(lease)
+      existing.fetch("leases") << lease if added
+      respond(socket, 200, { "ok" => true, "added" => added }, nonce: nonce, path: "/sessions")
+    end
+
+    def release(socket, payload, nonce)
+      id = payload.fetch("session_id")
+      session = @sessions[id]
+      removed = session && session.fetch("leases").delete(payload.fetch("lease"))
+      @sessions.delete(id) if session && session.fetch("leases").empty?
+      stopping = !!removed && @sessions.empty?
+      respond(socket, 200, { "ok" => true, "stopping" => stopping }, nonce: nonce, path: "/release")
+      stop if stopping
+    end
+
+    def open_in_editor(socket, params)
+      file = params["file"]
+      return respond(socket, 400, { "error" => "Missing required query parameter: file" }) if file.nil? || file.empty?
+
+      id = params["session"]
+      if id.nil?
+        return respond(socket, 400, { "error" => "Specify session when multiple checkouts are registered" }) unless @sessions.size == 1
+        id = @sessions.keys.first
+      end
+      session = @sessions[id]
+      return respond(socket, 404, { "error" => "Unknown editor session" }) unless session
+
+      translated_target = translate_target(file, session)
+      editor_command = session.fetch("editor_command")
+      pid = Process.spawn(*Shellwords.split(editor_command), "--goto", translated_target,
+        chdir: session.fetch("working_directory"))
+      Process.detach(pid)
+      respond(socket, 200, { "ok" => true, "requestedFile" => file, "translatedTarget" => translated_target,
+        "editorCommand" => editor_command, "session" => id })
+    rescue StandardError => error
+      respond(socket, 500, { "ok" => false, "error" => "Failed to open editor: #{error.message}",
+        "requestedFile" => file, "translatedTarget" => translated_target, "editorCommand" => editor_command })
+    end
+
+    def translate_target(target, session)
+      # Query parameters have already been decoded; literal percent signs are filenames.
+      match = target.match(/\A(.+?):(\d+)(?::(\d+))?\z/)
+      path = match ? match[1] : target
+      location = match ? ":#{[match[2], match[3]].compact.join(":")}" : ""
+      root = session.fetch("container_root")
+      if path == root || path.start_with?("#{root}/")
+        path = "#{session.fetch("host_root")}#{path.delete_prefix(root)}"
+      end
+      "#{path}#{location}"
+    end
+
+    def respond(socket, status, payload, nonce: nil, path: nil)
+      body = JSON.generate(payload)
+      signature_header = ""
+      if nonce
+        signature = Authentication.signature(@token, "response", nonce, status, path, body)
+        signature_header = "X-Open-In-Editor-Signature: #{signature}\r\n"
+      end
+      socket.write("HTTP/1.1 #{status} #{RESPONSE_PHRASES.fetch(status)}\r\n" \
+        "Content-Type: application/json\r\nAccess-Control-Allow-Origin: *\r\n" \
+        "X-Open-In-Editor-Bridge: #{Configuration::PROTOCOL}\r\n#{signature_header}" \
+        "Content-Length: #{body.bytesize}\r\nConnection: close\r\n\r\n#{body}")
+    rescue Errno::EPIPE, Errno::ECONNRESET
+      # A disconnected HTTP client must not take down other checkout sessions.
+      nil
+    end
+  end
+end

data/lib/open_in_editor_bridge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class OpenInEditorBridge
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/open_in_editor_bridge.rb

@@ -1,26 +1,8 @@
 # frozen_string_literal: true
 
-require "fileutils"
-require "json"
-require "rbconfig"
-require "shellwords"
-require "socket"
-require "timeout"
-require "uri"
 require_relative "open_in_editor_bridge/version"
 
 class OpenInEditorBridge
-  DEFAULT_PORT = 3333
-  HEALTH_PATH = "/health"
-  OPEN_IN_EDITOR_PATH = "/__open-in-editor"
-  RESPONSE_PHRASES = {
-    200 => "OK",
-    400 => "Bad Request",
-    404 => "Not Found",
-    405 => "Method Not Allowed",
-    500 => "Internal Server Error",
-  }.freeze
-
   class StartupError < StandardError
   end
 
@@ -28,324 +10,64 @@ class OpenInEditorBridge
     new.call(*args)
   end
 
+  def self.session_id
+    new.session_id
+  end
+
   def self.with_running(ensure_running: true)
-    owns_server = !ensure_running
-    owns_server = call("--ensure-running") == :started if ensure_running
+    bridge = new
+    lease = SecureRandom.hex(16) if ensure_running
+    bridge.start_session(lease) if ensure_running
 
     begin
-      yield
+      yield bridge.session_id
     ensure
-      if owns_server
-        block_error = $!
-        begin
-          call("--shutdown")
-        rescue StandardError => cleanup_error
-          raise cleanup_error unless block_error
-        end
+      block_error = $!
+      begin
+        ensure_running ? bridge.stop_session(lease) : bridge.call("--shutdown")
+      rescue StandardError => cleanup_error
+        raise cleanup_error unless block_error
       end
     end
   end
 
   def initialize(env: ENV, project_root: nil)
-    @env = env
-    @project_root = project_root
+    @configuration = Configuration.new(env: env, project_root: project_root)
+    @client = Client.new(@configuration)
+  end
+
+  def session_id
+    @configuration.session_id
   end
 
   def call(*args)
     case args.first || "--serve"
     when "--ensure-running"
-      ensure_running
+      start_session("detached")
     when "--shutdown"
-      shutdown
+      stop_session("detached")
+    when "--session-id"
+      puts session_id
+      session_id
     when "--serve"
-      serve
+      @client.serve
     else
-      serve
-    end
-  end
-
-  private
-
-  def ensure_running
-    pid = running_pid(validate_health: true)
-    if pid
-      puts "Editor bridge already running on port #{config[:port]} (pid #{pid})."
-      return :reused
-    end
-
-    ensure_runtime_directory
-    pid = Process.spawn(
-      *server_process_command,
-      out: config[:log_file],
-      err: config[:log_file],
-      pgroup: true
-    )
-    Process.detach(pid)
-
-    wait_until_ready(pid)
-    write_pid_file(pid)
-    puts "Started editor bridge on port #{config[:port]}."
-    :started
-  rescue StandardError
-    if pid && process_running?(pid)
-      begin
-        Process.kill("TERM", -pid)
-      rescue Errno::ESRCH
-      end
+      raise ArgumentError, "Unknown command: #{args.first}"
     end
-    delete_pid_file
-    raise
   end
 
-  def shutdown
-    pid = running_pid(validate_health: true)
-    return unless pid
-
-    Process.kill("TERM", -pid)
-    wait_until_stopped(pid)
-    delete_pid_file
-    puts "Stopped editor bridge."
-  rescue Errno::ESRCH
-    delete_pid_file
+  def start_session(lease)
+    @client.register(lease)
   end
 
-  def serve
-    abort("No editor configured. Set OPEN_IN_EDITOR_COMMAND or EDITOR environment variable.") if editor_command.empty?
-
-    ensure_runtime_directory
-    write_pid_file(Process.pid)
-    @server = TCPServer.new("127.0.0.1", config[:port])
-    @running = true
-    install_signal_handlers
-
-    while @running
-      begin
-        socket = @server.accept
-        handle_request(socket)
-      rescue IOError, Errno::EBADF
-        break
-      end
-    end
-  ensure
-    @server&.close
-    delete_pid_file
-  end
-
-  def handle_request(socket)
-    request = read_request(socket)
-    return if request.nil?
-
-    method = request.fetch(:method)
-    consume_headers(socket)
-    return write_json_response(socket, status: 405, payload: { error: "Method not allowed" }) unless method == "GET"
-
-    respond_to_get_request(socket, request.fetch(:path), request.fetch(:params))
-  ensure
-    socket.close unless socket.closed?
-  end
-
-  def open_in_editor(socket, params)
-    file = params["file"]
-    if file.nil? || file.empty?
-      return write_json_response(
-        socket,
-        status: 400,
-        payload: { error: "Missing required query parameter: file" }
-      )
-    end
-
-    translated_target = translate_target(file)
-    pid = Process.spawn(*editor_command_args, "--goto", translated_target)
-    Process.detach(pid)
-
-    write_json_response(
-      socket,
-      status: 200,
-      payload: {
-        ok: true,
-        requestedFile: file,
-        translatedTarget: translated_target,
-        editorCommand: editor_command,
-      }
-    )
-  rescue StandardError => error
-    write_json_response(
-      socket,
-      status: 500,
-      payload: {
-        ok: false,
-        error: "Failed to open editor: #{error.message}",
-        requestedFile: file,
-        translatedTarget: translated_target,
-        editorCommand: editor_command,
-      }
-    )
-  end
-
-  def write_json_response(socket, status: 200, payload:)
-    body = JSON.generate(payload)
-    socket.write("HTTP/1.1 #{status} #{RESPONSE_PHRASES.fetch(status)}\r\n")
-    socket.write("Content-Type: application/json\r\n")
-    socket.write("Access-Control-Allow-Origin: *\r\n")
-    socket.write("X-Open-In-Editor-Bridge: 1\r\n")
-    socket.write("Content-Length: #{body.bytesize}\r\n")
-    socket.write("Connection: close\r\n")
-    socket.write("\r\n")
-    socket.write(body)
-  end
-
-  def stop_server
-    @running = false
-    @server&.close
-  end
-
-  def ensure_runtime_directory
-    FileUtils.mkdir_p(File.dirname(config[:pid_file]))
-  end
-
-  def write_pid_file(pid)
-    File.write(config[:pid_file], "#{pid}\n")
-  end
-
-  def delete_pid_file
-    File.delete(config[:pid_file]) if File.exist?(config[:pid_file])
-  end
-
-  def server_process_command
-    [RbConfig.ruby, File.expand_path("../exe/open-in-editor-bridge", __dir__), "--serve"]
-  end
-
-  def editor_command
-    @env.fetch("OPEN_IN_EDITOR_COMMAND", @env.fetch("EDITOR", "")).to_s
-  end
-
-  def editor_command_args
-    Shellwords.split(editor_command)
-  end
-
-  def install_signal_handlers
-    trap("INT") { stop_server }
-    trap("TERM") { stop_server }
-  end
-
-  def read_request(socket)
-    request_line = socket.gets
-    return nil if request_line.nil?
-
-    method, raw_target, = request_line.split(" ")
-    return nil if method.nil? || raw_target.nil?
-
-    path, query = raw_target.split("?", 2)
-    params = URI.decode_www_form(query.to_s).to_h
-    { method: method, path: path, params: params }
-  rescue ArgumentError
-    write_json_response(socket, status: 400, payload: { error: "Bad request" })
-    nil
-  end
-
-  def consume_headers(socket)
-    loop do
-      line = socket.gets
-      break if line.nil? || line == "\r\n"
-    end
-  end
-
-  def respond_to_get_request(socket, path, params)
-    case path
-    when HEALTH_PATH
-      write_json_response(socket, payload: { ok: true, pid: Process.pid })
-    when OPEN_IN_EDITOR_PATH
-      open_in_editor(socket, params)
-    else
-      write_json_response(socket, status: 404, payload: { error: "Not found" })
-    end
-  end
-
-  def translate_target(target)
-    path, location = split_target(target)
-    translated_path = path.sub(/\A#{Regexp.escape(config[:container_web_root])}/, config[:host_web_root])
-    return translated_path if location.nil?
-
-    "#{translated_path}:#{location}"
-  end
-
-  def split_target(target)
-    decoded_target = URI.decode_www_form_component(target)
-    match = decoded_target.match(/\A(.+?):(\d+)(?::(\d+))?\z/)
-    return [decoded_target, nil] if match.nil?
-
-    [match[1], [match[2], match[3]].compact.join(":")]
-  end
-
-  def running_pid(validate_health: false)
-    return nil unless File.exist?(config[:pid_file])
-
-    pid = Integer(File.read(config[:pid_file]).strip)
-    return pid if process_running?(pid) && (!validate_health || bridge_healthy?(expected_pid: pid))
-
-    delete_pid_file
-    nil
-  rescue ArgumentError
-    delete_pid_file
-    nil
-  end
-
-  def process_running?(pid)
-    Process.kill(0, pid)
-    true
-  rescue Errno::ESRCH, Errno::EPERM
-    false
-  end
-
-  def wait_until_ready(pid)
-    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + config[:startup_timeout]
-    loop do
-      raise StartupError, "Editor bridge failed to start. See #{config[:log_file]}." unless process_running?(pid)
-      return if bridge_healthy?(expected_pid: pid)
-
-      raise StartupError, "Editor bridge did not become ready." if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
-      sleep 0.05
-    end
-  end
-
-  def wait_until_stopped(pid)
-    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + config[:startup_timeout]
-    until !process_running?(pid) && !bridge_healthy?
-      break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
-
-      sleep 0.05
-    end
-  end
-
-  def bridge_healthy?(expected_pid: nil)
-    socket = TCPSocket.new("127.0.0.1", config[:port])
-    response = Timeout.timeout(0.25) do
-      socket.write("GET /health HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n")
-      socket.read
-    end
-    headers, body = response.split("\r\n\r\n", 2)
-    payload = JSON.parse(body.to_s)
-    headers&.start_with?("HTTP/1.1 200 ") &&
-      headers.lines.any? { |line| line.casecmp("X-Open-In-Editor-Bridge: 1\r\n").zero? } &&
-      payload.fetch("ok") == true &&
-      (expected_pid.nil? || payload.fetch("pid") == expected_pid)
-  rescue Errno::ECONNREFUSED, JSON::ParserError, KeyError, Timeout::Error
-    false
-  ensure
-    socket&.close unless socket&.closed?
-  end
-
-  def config
-    root = @project_root || @env.fetch("OPEN_IN_EDITOR_PROJECT_ROOT", Dir.pwd)
-    {
-      port: Integer(@env.fetch("OPEN_IN_EDITOR_BRIDGE_PORT", DEFAULT_PORT)),
-      pid_file: File.join(root, "tmp", "open-in-editor-bridge.pid"),
-      log_file: File.join(root, "tmp", "open-in-editor-bridge.log"),
-      container_web_root: @env.fetch("OPEN_IN_EDITOR_CONTAINER_WEB_ROOT", "/usr/src/web"),
-      host_web_root: @env.fetch("OPEN_IN_EDITOR_HOST_WEB_ROOT", File.join(root, "web")),
-      startup_timeout: Float(@env.fetch("OPEN_IN_EDITOR_BRIDGE_STARTUP_TIMEOUT", "5")),
-    }
+  def stop_session(lease)
+    @client.release(lease)
   end
 end
 
+require_relative "open_in_editor_bridge/configuration"
+require_relative "open_in_editor_bridge/authentication"
+require_relative "open_in_editor_bridge/server"
+require_relative "open_in_editor_bridge/client"
+
 OpenInEditorBridge.call(*ARGV) if $PROGRAM_NAME == __FILE__

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: open-in-editor-bridge
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Marlen Brunner
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-28 00:00:00.000000000 Z
+date: 2026-10-09 00:00:00.000000000 Z
 dependencies: []
 description: Ruby API and CLI for serving local open-in-editor requests during development.
 email:
@@ -18,16 +18,22 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - exe/open-in-editor-bridge
 - lib/open_in_editor_bridge.rb
+- lib/open_in_editor_bridge/authentication.rb
+- lib/open_in_editor_bridge/client.rb
+- lib/open_in_editor_bridge/configuration.rb
+- lib/open_in_editor_bridge/server.rb
 - lib/open_in_editor_bridge/version.rb
 homepage: https://github.com/klondikemarlen/open-in-editor-bridge
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/klondikemarlen/open-in-editor-bridge/issues
+  changelog_uri: https://github.com/klondikemarlen/open-in-editor-bridge/blob/main/CHANGELOG.md
   source_code_uri: https://github.com/klondikemarlen/open-in-editor-bridge
 post_install_message:
 rdoc_options: []