outpunch-rack 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9617779c67e50ea7f710e3145466edecd3c3b704c2a55a4ea756bf17296de711
+  data.tar.gz: 6a061875774d092c30fa955141a8f86f2e8a47d1513424a543177176cd13dbd0
+SHA512:
+  metadata.gz: 806fc1f33092a13861937c08727199e4373c6089ab8db587415667dcbdf6ede285129d1e6e2abddb6af83375358641a05a9380df284138eb6cabe891ab7db9f9
+  data.tar.gz: b20af1219aa6bb14c5fdf570741124b2cd4bccd93590caeefc4bd51cf1722e770bd323f0bd6c7ffc73ef53e8d66343575d4e0cff36cadf91c08320e76d02b799

data/lib/outpunch/rack/connection.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "websocket/driver"
+require "json"
+
+module Outpunch
+  module Rack
+    class Connection
+      def initialize(server)
+        @server = server
+        @service_name = nil
+        @write_mutex = Mutex.new
+        @io = nil
+        @driver = nil
+        @env = nil
+      end
+
+      # Hijack the socket and run the WebSocket loop. Blocks until disconnected.
+      def run(env)
+        @env = env
+        @io = env.fetch("rack.hijack_io")
+        @driver = WebSocket::Driver.rack(self)
+        @driver.on(:message) { |event| on_message(event.data) }
+        @driver.on(:close)   { on_close }
+        @driver.on(:error)   { |e| log_error(e.message) }
+        @driver.start
+
+        while (chunk = @io.readpartial(4096))
+          @driver.parse(chunk)
+        end
+      rescue EOFError, IOError, Errno::ECONNRESET
+        # normal close
+      ensure
+        on_close
+      end
+
+      # Called by Server#handle_request to send a request over the wire.
+      def send_request(payload)
+        msg = payload
+          .merge(type: "request")
+          .transform_keys(&:to_s)
+        transmit(msg)
+      end
+
+      # Called by websocket-driver to write raw bytes to the socket.
+      def write(data)
+        @io.write(data)
+      rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+        nil
+      end
+
+      # websocket-driver requires #env and #url to build the handshake.
+      def env
+        @env || {}
+      end
+
+      def url
+        scheme = env["rack.url_scheme"] == "https" ? "wss" : "ws"
+        host   = env["HTTP_HOST"] || env["SERVER_NAME"] || "localhost"
+        "#{scheme}://#{host}#{env["REQUEST_URI"]}"
+      end
+
+      private
+
+      def on_message(raw)
+        data = JSON.parse(raw)
+        case data["type"]
+        when "auth"     then handle_auth(data)
+        when "response" then @server.complete_request(data["request_id"], data)
+        else
+          # unknown message type — ignore
+        end
+      rescue JSON::ParserError
+        nil
+      end
+
+      def handle_auth(data)
+        if @server.valid_token?(data["token"]) && !data["service"].to_s.empty?
+          @service_name = data["service"]
+          @server.register_connection(@service_name, self)
+          transmit(type: "auth_ok")
+        else
+          transmit(type: "auth_error", message: "invalid token")
+          @driver.close
+        end
+      end
+
+      def on_close
+        return unless @service_name
+
+        @server.unregister_connection(@service_name)
+        @service_name = nil
+      end
+
+      def transmit(data)
+        @write_mutex.synchronize { @driver.text(JSON.generate(data)) }
+      end
+
+      def log_error(message)
+        warn "[Outpunch::Rack] WebSocket error: #{message}"
+      end
+    end
+  end
+end

data/lib/outpunch/rack/hooks.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Outpunch
+  module Rack
+    module Hooks
+      HOOKS = {}
+
+      def self.register(service_name, path_pattern, handler_class)
+        HOOKS[service_name] ||= []
+        HOOKS[service_name] << { pattern: path_pattern, handler_class: handler_class }
+      end
+
+      def self.before_proxy(service_name:, path:, payload:, request:)
+        find_handlers(service_name, path).each do |h|
+          h[:handler_class].new.before_proxy(path: path, payload: payload, request: request)
+        end
+      end
+
+      def self.after_proxy(service_name:, path:, payload:, result:, request:)
+        find_handlers(service_name, path).each do |h|
+          h[:handler_class].new.after_proxy(path: path, payload: payload, result: result, request: request)
+        end
+      end
+
+      def self.clear!
+        HOOKS.clear
+      end
+
+      def self.find_handlers(service_name, path)
+        (HOOKS[service_name] || []).select { |h| path.match?(h[:pattern]) }
+      end
+      private_class_method :find_handlers
+    end
+  end
+end

data/lib/outpunch/rack/middleware.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Outpunch
+  module Rack
+    class Middleware
+      WS_PATH = "/ws"
+
+      def initialize(app, server:)
+        @app    = app
+        @server = server
+      end
+
+      def call(env)
+        if env["PATH_INFO"] == WS_PATH && websocket_upgrade?(env)
+          env["rack.hijack"].call
+          conn = @server.create_connection
+          Thread.new { conn.run(env) }
+          [-1, {}, []]
+        else
+          @app.call(env)
+        end
+      end
+
+      private
+
+      def websocket_upgrade?(env)
+        env["HTTP_UPGRADE"]&.downcase == "websocket" &&
+          env["HTTP_CONNECTION"]&.downcase&.include?("upgrade")
+      end
+    end
+  end
+end

data/lib/outpunch/rack/server.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "concurrent"
+require "securerandom"
+require "timeout"
+require "openssl"
+require "base64"
+require "json"
+
+module Outpunch
+  module Rack
+    class Server
+      HOP_BY_HOP = %w[HOST CONNECTION UPGRADE].freeze
+
+      def initialize(secret:, timeout: 25)
+        @secret = secret
+        @timeout = timeout
+        @connections = Concurrent::Map.new
+        @pending_requests = Concurrent::Map.new
+      end
+
+      def create_connection
+        Connection.new(self)
+      end
+
+      # Register a service connection. Called by Connection after successful auth.
+      def register_connection(service_name, conn)
+        @connections[service_name] = conn
+      end
+
+      # Remove a service connection. Called by Connection on close.
+      def unregister_connection(service_name)
+        @connections.delete(service_name)
+      end
+
+      def connected?(service_name)
+        @connections.key?(service_name)
+      end
+
+      # Send a request through the tunnel and block until response or timeout.
+      def handle_request(service:, method:, path:, query:, headers:, body:)
+        conn = @connections[service]
+        raise "Service '#{service}' not connected" unless conn
+
+        request_id = SecureRandom.uuid
+        queue = Queue.new
+        @pending_requests[request_id] = queue
+
+        conn.send_request(
+          request_id: request_id,
+          service: service,
+          method: method,
+          path: path,
+          query: query,
+          headers: headers,
+          body: body
+        )
+
+        begin
+          Timeout.timeout(@timeout) { queue.pop }
+        ensure
+          @pending_requests.delete(request_id)
+        end
+      end
+
+      # Deliver a response to a waiting handle_request call.
+      def complete_request(request_id, response_data)
+        @pending_requests[request_id]&.push(response_data)
+      end
+
+      # Constant-time token validation.
+      def valid_token?(token)
+        return false if @secret.nil? || @secret.empty? || token.nil? || token.empty?
+        return false if token.bytesize != @secret.bytesize
+
+        OpenSSL.fixed_length_secure_compare(token, @secret)
+      end
+
+      # Build a success result hash from raw tunnel response data.
+      def success_response(data)
+        body = data["body"]
+        headers = (data["headers"] || {}).transform_keys(&:downcase)
+
+        if data["body_encoding"] == "base64" && !body.nil? && !body.empty?
+          body = Base64.decode64(body)
+          body.force_encoding("BINARY")
+        end
+
+        {
+          status: data["status"] || 200,
+          body: body,
+          headers: headers,
+          body_encoding: data["body_encoding"]
+        }
+      end
+
+      # Build an error result hash.
+      def error_response(status, message)
+        {
+          status: status,
+          body: JSON.generate(error: message),
+          headers: { "Content-Type" => "application/json" }
+        }
+      end
+
+      # Extract and normalize HTTP headers from a Rack env hash.
+      def extract_proxy_headers(headers)
+        headers
+          .to_h
+          .select { |k, _| k.to_s.start_with?("HTTP_") }
+          .transform_keys { |k| k.to_s.sub("HTTP_", "").tr("_", "-") }
+          .reject { |k, _| HOP_BY_HOP.include?(k) }
+      end
+
+      # For test isolation — resets all state.
+      def reset!
+        @connections.clear
+        @pending_requests.clear
+      end
+    end
+  end
+end

data/lib/outpunch/rack/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Outpunch
+  module Rack
+    VERSION = "0.1.0"
+  end
+end

data/lib/outpunch/rack.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "rack/version"
+require_relative "rack/hooks"
+require_relative "rack/server"
+require_relative "rack/connection"
+require_relative "rack/middleware"
+
+module Outpunch
+  module Rack
+    class Configuration
+      attr_accessor :secret, :timeout, :base_controller, :authorize_service, :hooks, :route_prefix
+
+      def initialize
+        @timeout = 25
+        @base_controller = "ActionController::API"
+        @hooks = Outpunch::Rack::Hooks
+        @route_prefix = "/outpunch"
+      end
+    end
+
+    class << self
+      def configure
+        yield configuration
+        @server = nil # reset server so it picks up new config
+      end
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def server
+        @server ||= Server.new(
+          secret: configuration.secret,
+          timeout: configuration.timeout
+        )
+      end
+
+      # Delegates — convenience access for application code.
+
+      def connected?(service_name)
+        server.connected?(service_name)
+      end
+
+      def handle_request(**kwargs)
+        server.handle_request(**kwargs)
+      end
+
+      def success_response(data)
+        server.success_response(data)
+      end
+
+      def error_response(status, message)
+        server.error_response(status, message)
+      end
+
+      def extract_proxy_headers(headers)
+        server.extract_proxy_headers(headers)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: outpunch-rack
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- TechyCorp
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: websocket-driver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: websocket-client-simple
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/outpunch/rack.rb
+- lib/outpunch/rack/connection.rb
+- lib/outpunch/rack/hooks.rb
+- lib/outpunch/rack/middleware.rb
+- lib/outpunch/rack/server.rb
+- lib/outpunch/rack/version.rb
+homepage:
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+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: Rack adapter for the outpunch reverse WebSocket tunnel
+test_files: []