outpunch-ruby-rack 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0653aca03868461d7cf634e6304cea2e39e4839fa781c95629fd9624329b5111
+  data.tar.gz: 3088141712a4222697b5d702e7ac7a1d050f035579ccdf9a3351946fa30ed79c
+SHA512:
+  metadata.gz: 742044a6fa94ed852d83c4c2c3eb094826f241f83ad9d8accec681a01f05cf6d48475e6f24ecf115988b7357ddbb275e0952fe728797d1e1e4738c36f05461b8
+  data.tar.gz: 963ab38e87bafa442d4cac21b9567c06c11d3e957a9fb6f2b99c7cf5ba3c5a52a4d733bbe25f2eed9a9614feee878299f9bc4dc310abab3f7f6e85dea6ceab10

data/lib/outpunch/rack/connection.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "websocket/driver"
+
+module Outpunch
+  module Rack
+    # Bridges a hijacked Rack socket to a native outpunch core connection.
+    # Ruby handles socket I/O and WebSocket framing; the core handles auth,
+    # routing and request state.
+    class Connection
+      def initialize(native)
+        @native = native
+        @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| @native.push_message(event.data) }
+        @driver.on(:close)   { @native.close }
+        @driver.on(:error)   { |e| log_error(e.message) }
+        @driver.start
+
+        core = Thread.new { @native.run }
+        writer = Thread.new { write_loop }
+
+        while (chunk = @io.readpartial(4096))
+          @driver.parse(chunk)
+        end
+      rescue EOFError, IOError, Errno::ECONNRESET, Errno::EPIPE
+        # normal close
+      ensure
+        @native.close
+        core&.join
+        writer&.join
+        close_io
+      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
+
+      # Deliver core messages to the client until the core connection ends, then
+      # close the socket so the read loop in #run returns.
+      def write_loop
+        while (msg = @native.next_outgoing)
+          @write_mutex.synchronize { @driver.text(msg) }
+        end
+        @write_mutex.synchronize { @driver.close }
+        close_io
+      end
+
+      def close_io
+        @io.close unless @io.closed?
+      rescue IOError
+        nil
+      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: nil)
+        @app = app
+        @server = server
+      end
+
+      def call(env)
+        if env["PATH_INFO"] == WS_PATH && websocket_upgrade?(env)
+          env["rack.hijack"].call
+          conn = (@server || Outpunch::Rack.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,84 @@
+# frozen_string_literal: true
+
+require "outpunch/outpunch"
+require "base64"
+require "json"
+
+module Outpunch
+  module Rack
+    # Ruby-facing wrapper around the native outpunch core server.
+    class Server
+      HOP_BY_HOP = %w[HOST CONNECTION UPGRADE].freeze
+
+      def initialize(secret:, timeout: 25)
+        raise ArgumentError, "outpunch secret must be set" if secret.nil? || secret.to_s.empty?
+
+        @native = Outpunch::Server.new(secret.to_s, timeout.to_f, nil)
+      end
+
+      def create_connection
+        Connection.new(@native.create_connection)
+      end
+
+      def connected?(service_name)
+        @native.connected?(service_name.to_s)
+      end
+
+      # Send a request through the tunnel and block until response or timeout.
+      # Raises Outpunch::NotConnectedError (a RuntimeError) when no client is connected
+      # and Outpunch::TunnelTimeoutError (a Timeout::Error) on timeout.
+      def handle_request(service:, method:, path:, query:, headers:, body:)
+        @native.handle_request(
+          service.to_s,
+          method.to_s,
+          path.to_s,
+          stringify(query),
+          stringify(headers),
+          body&.to_s
+        )
+      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
+
+      private
+
+      def stringify(hash)
+        (hash || {}).to_h.to_h { |k, v| [k.to_s, v.to_s] }
+      end
+    end
+  end
+end

data/lib/outpunch/rack/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Outpunch
+  module Rack
+    VERSION = "0.5.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

data/lib/outpunch-ruby-rack.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "outpunch/rack"

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: outpunch-ruby-rack
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- TechyCorp
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-28 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: outpunch-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.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-ruby-rack.rb
+- 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: []