open-in-editor-bridge 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b59090b703a55c7194b9898ffc6753cda0df2a3e3b1d1d311c1cd0dcd0fa57d9
+  data.tar.gz: d57211d78ebeb9048b963a853621ba575825115c45fdd2a651d75961b2062ee6
+SHA512:
+  metadata.gz: 86eccd454213ccc64074b85d2eb4a91ddfaec7bb879c0e7e7da0dc53a924ab9d926658d6ece2600ce699e2f5f46b97565d4bd17f1b9dd6358f15fc9bfca78224
+  data.tar.gz: 4be766b7b327ee39aa94f763979ab93b46a9a6c226774a80e3773c303f7f24d58870c6700e2685fc1399afcd8ee8424bfc47f976fffc99f25fb121f40ffb280b

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marlen Brunner
+
+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,49 @@
+# OpenInEditorBridge
+
+A small Ruby gem that runs a local HTTP bridge for opening files from a container in the host editor.
+
+## Install
+
+```ruby
+gem "open-in-editor-bridge"
+```
+
+## Ruby API
+
+Wrap the local development command that needs the bridge:
+
+```ruby
+require "open_in_editor_bridge"
+
+OpenInEditorBridge.with_running do
+  # Run the command that emits open-in-editor links.
+end
+```
+
+Use `ensure_running: false` when the wrapped command is responsible for stopping the bridge:
+
+```ruby
+OpenInEditorBridge.with_running(ensure_running: false) { run_down_command }
+```
+
+The bridge is stopped in the wrapper's `ensure` path. A block exception remains the raised exception.
+
+## CLI
+
+```sh
+open-in-editor-bridge --ensure-running
+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.
+
+## 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`)
+
+The editor command is required and is parsed with `Shellwords`.

data/exe/open-in-editor-bridge

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/open_in_editor_bridge"
+
+OpenInEditorBridge.call(*ARGV)

data/lib/open_in_editor_bridge/version.rb

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

data/lib/open_in_editor_bridge.rb

@@ -0,0 +1,349 @@
+# 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
+
+  def self.call(*args)
+    new.call(*args)
+  end
+
+  def self.with_running(ensure_running: true)
+    owns_server = !ensure_running
+    owns_server = call("--ensure-running") == :started if ensure_running
+
+    begin
+      yield
+    ensure
+      if owns_server
+        block_error = $!
+        begin
+          call("--shutdown")
+        rescue StandardError => cleanup_error
+          raise cleanup_error unless block_error
+        end
+      end
+    end
+  end
+
+  def initialize(env: ENV, project_root: nil)
+    @env = env
+    @project_root = project_root
+  end
+
+  def call(*args)
+    case args.first || "--serve"
+    when "--ensure-running"
+      ensure_running
+    when "--shutdown"
+      shutdown
+    when "--serve"
+      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
+    end
+    delete_pid_file
+    raise
+  end
+
+  def shutdown
+    pid = running_pid
+    return unless pid
+
+    Process.kill("TERM", -pid)
+    wait_until_stopped(pid)
+    delete_pid_file
+    puts "Stopped editor bridge."
+  rescue Errno::ESRCH
+    delete_pid_file
+  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 })
+    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?)
+
+    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?
+
+      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?
+    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)
+    headers&.start_with?("HTTP/1.1 200 ") &&
+      headers.lines.any? { |line| line.casecmp("X-Open-In-Editor-Bridge: 1\r\n").zero? } &&
+      JSON.parse(body.to_s).fetch("ok") == true
+  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")),
+    }
+  end
+end
+
+OpenInEditorBridge.call(*ARGV) if $PROGRAM_NAME == __FILE__

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: open-in-editor-bridge
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Marlen Brunner
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-07-28 00:00:00.000000000 Z
+dependencies: []
+description: Ruby API and CLI for serving local open-in-editor requests during development.
+email:
+- klondikemarlen@gmail.com
+executables:
+- open-in-editor-bridge
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/open-in-editor-bridge
+- lib/open_in_editor_bridge.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
+  source_code_uri: https://github.com/klondikemarlen/open-in-editor-bridge
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Local HTTP bridge for opening container paths in an editor
+test_files: []