tunnel-rb 0.1.0

data/lib/tunnel_rb/server/public_server.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "socket"
+require "timeout"
+
+require_relative "thread_pool"
+require_relative "http_request"
+require_relative "socket_helpers"
+
+module TunnelRb
+  class Server
+    # Public-facing HTTP edge: accepts browser connections, parses headers,
+    # asks the tunneled client to open a fresh data connection via
+    # PendingConnections, and proxies bytes both ways.
+    class PublicServer
+      POOL_SIZE = 200
+      QUEUE_SIZE = 200
+      READ_TIMEOUT_SEC = 5
+      BIND_WAIT_SEC = 10
+
+      def initialize(port:, registry:, pending_connections:, logger:)
+        @port = port
+        @registry = registry
+        @pending_connections = pending_connections
+        @logger = logger
+
+        @pool = ThreadPool.new(POOL_SIZE, max_queue: QUEUE_SIZE)
+        @stopping = false
+        @server = nil
+      end
+
+      def start
+        @server = TCPServer.new("0.0.0.0", @port)
+        @logger.info "🌍 Public server listening on #{@port}"
+
+        loop do
+          browser_socket = @server.accept
+          @pool.submit { handle_request(browser_socket) }
+        rescue IOError, Errno::EBADF
+          break if @stopping
+
+          raise
+        end
+      end
+
+      def stop
+        @stopping = true
+        @server&.close rescue nil
+        @pool.shutdown
+      end
+
+      private
+
+      def handle_request(browser_socket)
+        conn_id = nil
+        data_socket = nil
+        client_ip = browser_socket.remote_address.ip_address rescue "127.0.0.1"
+        SocketHelpers.enable_tcp_nodelay(browser_socket)
+
+        host, header_buffer = read_headers(browser_socket, client_ip)
+        return unless header_buffer
+
+        subdomain = extract_subdomain(host)
+        client = @registry.lookup(subdomain)
+        unless client
+          send_error(browser_socket, 404, "Tunnel '#{subdomain}' not found or disconnected.")
+          return
+        end
+
+        conn_id = SecureRandom.uuid
+        queue = @pending_connections.register(conn_id)
+
+        begin
+          client.send_message(action: "new_connection", conn_id: conn_id)
+        rescue => _e
+          send_error(browser_socket, 502, "Failed to reach tunnel.")
+          return
+        end
+
+        begin
+          Timeout.timeout(BIND_WAIT_SEC) { data_socket = queue.pop }
+        rescue Timeout::Error
+          send_error(browser_socket, 504, "Timeout: local server did not respond.")
+          return
+        end
+
+        data_socket.write(header_buffer)
+        proxy_stream(browser_socket, data_socket)
+      rescue => e
+        @logger.warn "❌ HTTP routing error: #{e.message}"
+      ensure
+        @pending_connections.close(conn_id) if conn_id
+        data_socket.close rescue nil if data_socket
+        browser_socket.close rescue nil
+      end
+
+      def read_headers(browser_socket, client_ip)
+        HttpRequest.read(browser_socket, client_ip: client_ip, timeout: READ_TIMEOUT_SEC)
+      rescue HttpRequest::Timeout
+        send_error(browser_socket, 408, "Request Timeout")
+        [nil, nil]
+      end
+
+      def extract_subdomain(host_header)
+        return nil if host_header.nil? || host_header.empty?
+
+        host_header.split(":", 2).first.split(".").first
+      end
+
+      def proxy_stream(client, backend)
+        t1 = Thread.new do
+          IO.copy_stream(client, backend) rescue nil
+          backend.close_write rescue nil
+        end
+        t2 = Thread.new do
+          IO.copy_stream(backend, client) rescue nil
+          client.close_write rescue nil
+        end
+        t1.join
+        t2.join
+      end
+
+      STATUS_TEXTS = {
+        404 => "Not Found",
+        408 => "Request Timeout",
+        502 => "Bad Gateway",
+        504 => "Gateway Timeout"
+      }.freeze
+
+      def send_error(socket, code, message)
+        status = STATUS_TEXTS.fetch(code, "Bad Gateway")
+        socket.print(
+          "HTTP/1.1 #{code} #{status}\r\n" \
+          "Connection: close\r\n" \
+          "Content-Length: #{message.bytesize}\r\n" \
+          "Content-Type: text/plain; charset=utf-8\r\n" \
+          "\r\n#{message}"
+        )
+        socket.close rescue nil
+      end
+    end
+  end
+end

data/lib/tunnel_rb/server/socket_helpers.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module TunnelRb
+  class Server
+    module SocketHelpers
+      TCP_KEEPALIVE_IDLE = 60
+      TCP_KEEPALIVE_INTERVAL = 30
+      TCP_KEEPALIVE_PROBES = 3
+
+      module_function
+
+      def enable_tcp_keepalive(socket)
+        # Operate on the raw fd so this works for both plain TCP and TLS
+        # sockets (SSLSocket does not define setsockopt itself).
+        io = socket.respond_to?(:to_io) ? socket.to_io : socket
+        io.setsockopt(:SOCKET, :SO_KEEPALIVE, true)
+        if defined?(Socket::TCP_KEEPIDLE)
+          io.setsockopt(:TCP, :TCP_KEEPIDLE, TCP_KEEPALIVE_IDLE)
+          io.setsockopt(:TCP, :TCP_KEEPINTVL, TCP_KEEPALIVE_INTERVAL)
+          io.setsockopt(:TCP, :TCP_KEEPCNT, TCP_KEEPALIVE_PROBES)
+        elsif defined?(Socket::TCP_KEEPALIVE)
+          io.setsockopt(:TCP, :TCP_KEEPALIVE, TCP_KEEPALIVE_IDLE)
+        end
+      rescue StandardError => e
+        warn "TCP keepalive not configured: #{e.message}"
+      end
+
+      # Disables Nagle's algorithm so small writes (TLS handshake records, short
+      # HTTP responses) go out immediately instead of waiting to coalesce. On the
+      # short-lived data sockets this avoids ~40ms Nagle/delayed-ACK stalls.
+      def enable_tcp_nodelay(socket)
+        io = socket.respond_to?(:to_io) ? socket.to_io : socket
+        io.setsockopt(:TCP, :TCP_NODELAY, true)
+      rescue StandardError => e
+        warn "TCP_NODELAY not configured: #{e.message}"
+      end
+    end
+  end
+end

data/lib/tunnel_rb/server/thread_pool.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module TunnelRb
+  class Server
+    # Bounded worker pool. `submit` blocks the caller when the queue is full,
+    # which propagates backpressure all the way to TCP accept loops.
+    class ThreadPool
+      SHUTDOWN = :shutdown
+
+      def initialize(size, max_queue: size)
+        @size = size
+        @queue = SizedQueue.new(max_queue)
+        @workers = Array.new(size) do
+          Thread.new do
+            loop do
+              job = @queue.pop
+              break if job == SHUTDOWN
+
+              job.call
+            rescue => e
+              warn "ThreadPool job error: #{e.message}"
+            end
+          end
+        end
+      end
+
+      def submit(&block)
+        @queue << block
+      end
+
+      def shutdown
+        @size.times { @queue << SHUTDOWN }
+        @workers.each { |t| t.join(2) }
+      end
+    end
+  end
+end

data/lib/tunnel_rb/server/tls.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module TunnelRb
+  class Server
+    # Builds TLS contexts and wraps the control listener. TLS is optional:
+    # callers pass nil cert/key to run the control plane in plaintext.
+    module TLS
+      module_function
+
+      # Returns an SSLContext configured to present the given cert/key, or
+      # nil when either path is missing (TLS disabled).
+      def server_context(cert_path:, key_path:)
+        return nil if cert_path.nil? || key_path.nil?
+
+        ctx = OpenSSL::SSL::SSLContext.new
+        certs = load_certificates(cert_path)
+        ctx.cert = certs.shift
+        ctx.extra_chain_cert = certs unless certs.empty?
+        ctx.key = OpenSSL::PKey.read(File.read(key_path))
+        ctx.min_version = OpenSSL::SSL::TLS1_3_VERSION
+
+        # Enable session resumption: the server issues TLS 1.3 session tickets so
+        # repeat data-socket handshakes skip the expensive signature/verify step.
+        ctx.session_id_context = "tunnel-rb-server"
+        ctx
+      end
+
+      # Wraps a TCPServer in an SSLServer. The handshake is deferred
+      # (start_immediately = false) so accept() does not block on a slow
+      # client; the worker thread performs the handshake instead.
+      def load_certificates(path)
+        File.read(path).scan(/-----BEGIN CERTIFICATE-----.*?-----END CERTIFICATE-----/m).map do |pem|
+          OpenSSL::X509::Certificate.new(pem)
+        end.tap do |certs|
+          raise "No certificates in #{path}" if certs.empty?
+        end
+      end
+
+      def wrap_listener(tcp_server, ctx)
+        ssl_server = OpenSSL::SSL::SSLServer.new(tcp_server, ctx)
+        ssl_server.start_immediately = false
+        ssl_server
+      end
+    end
+  end
+end

data/lib/tunnel_rb/server/token_store.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "set"
+require "thread"
+
+module TunnelRb
+  class Server
+    # Persistent token <-> subdomain mapping with TTL. Tokens belonging to a
+    # currently-connected client never expire (they're refreshed implicitly).
+    # Tokens of disconnected clients age out after TOKEN_TTL.
+    class TokenStore
+      DEFAULT_PATH = "/tmp/tunnel-rb-server-tokens.json".freeze
+      TOKEN_TTL = 24 * 3600 # seconds
+      CLEANUP_INTERVAL = 600
+
+      # active_subdomains: callable returning a Set/Array of subdomains held
+      # by currently-connected clients. Used to keep their tokens alive and to
+      # avoid colliding when generating new subdomains.
+      def initialize(path: DEFAULT_PATH, active_subdomains:, logger: nil)
+        @path = path
+        @active_subdomains = active_subdomains
+        @logger = logger
+        @mutex = Mutex.new
+        @tokens = load_from_disk
+      end
+
+      def issue(subdomain)
+        @mutex.synchronize do
+          loop do
+            token = SecureRandom.hex(16)
+            next if @tokens.key?(token)
+
+            @tokens[token] = entry(subdomain)
+            persist
+            return token
+          end
+        end
+      end
+
+      def revoke(token)
+        return unless token
+
+        @mutex.synchronize do
+          next unless @tokens.delete(token)
+
+          persist
+        end
+      end
+
+      # Returns the subdomain bound to `token` if the token is valid, or nil.
+      # A token is valid if either (a) its subdomain currently has an active
+      # client, or (b) the token has not expired yet.
+      def resolve(token)
+        @mutex.synchronize do
+          record = @tokens[token]
+          return nil unless record
+
+          sub = subdomain_of(record)
+          return sub if active?(sub)
+          return nil if expired?(record)
+
+          sub
+        end
+      end
+
+      def generate_subdomain
+        @mutex.synchronize do
+          loop do
+            candidate = SecureRandom.hex(4)
+            return candidate unless taken_unlocked?(candidate)
+          end
+        end
+      end
+
+      # Drops tokens whose subdomain has no active client and whose TTL has
+      # elapsed. Called both periodically and on every registration.
+      def cleanup_expired
+        @mutex.synchronize { cleanup_unlocked }
+      end
+
+      def cleanup_loop(interval: CLEANUP_INTERVAL, stop_flag: nil)
+        loop do
+          interval.times do
+            return if stop_flag && stop_flag.call
+
+            sleep 1
+          end
+          return if stop_flag && stop_flag.call
+
+          cleanup_expired
+        end
+      end
+
+      def persist_now
+        @mutex.synchronize { persist }
+      end
+
+      # Snapshot for tests/diagnostics.
+      def to_h
+        @mutex.synchronize { @tokens.dup }
+      end
+
+      private
+
+      def cleanup_unlocked
+        now = Time.now.to_i
+        expired_tokens = @tokens.reject do |_token, record|
+          active?(subdomain_of(record)) || !expired?(record, now)
+        end
+        return if expired_tokens.empty?
+
+        expired_tokens.each_key { |t| @tokens.delete(t) }
+        persist
+      end
+
+      def taken_unlocked?(subdomain)
+        return true if active?(subdomain)
+
+        @tokens.any? { |_token, record| subdomain_of(record) == subdomain }
+      end
+
+      def active?(subdomain)
+        active_set.include?(subdomain)
+      end
+
+      def active_set
+        result = @active_subdomains.call
+        result.is_a?(Set) ? result : result.to_set
+      end
+
+      def entry(subdomain, expires_at: Time.now.to_i + TOKEN_TTL)
+        { "subdomain" => subdomain, "expires_at" => expires_at }
+      end
+
+      def subdomain_of(record)
+        record.is_a?(Hash) ? record["subdomain"] : record
+      end
+
+      def expired?(record, now = Time.now.to_i)
+        expires_at = record.is_a?(Hash) ? record["expires_at"] : nil
+        expires_at.nil? || expires_at <= now
+      end
+
+      def normalize(record, now)
+        if record.is_a?(Hash)
+          entry(record["subdomain"], expires_at: record["expires_at"] || (now + TOKEN_TTL))
+        else
+          entry(record, expires_at: now + TOKEN_TTL)
+        end
+      end
+
+      def load_from_disk
+        return {} unless File.exist?(@path)
+
+        now = Time.now.to_i
+        result = {}
+        JSON.parse(File.read(@path)).each do |token, record|
+          normalized = normalize(record, now)
+          next if expired?(normalized, now)
+
+          result[token] = normalized
+        end
+        result
+      rescue JSON::ParserError, SystemCallError => e
+        log_warn("Failed to load tokens: #{e.message}")
+        {}
+      end
+
+      def persist
+        File.write(@path, JSON.pretty_generate(@tokens))
+      rescue SystemCallError => e
+        log_warn("Failed to save tokens: #{e.message}")
+      end
+
+      def log_warn(msg)
+        @logger ? @logger.warn("⚠️  #{msg}") : warn(msg)
+      end
+    end
+  end
+end

data/lib/tunnel_rb/server.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "server/logger"
+require_relative "server/client_registry"
+require_relative "server/token_store"
+require_relative "server/pending_connections"
+require_relative "server/control_server"
+require_relative "server/public_server"
+require_relative "server/tls"
+
+module TunnelRb
+  # Top-level coordinator. Wires the components together, owns the
+  # background threads, and handles graceful shutdown on SIGINT/SIGTERM.
+  class Server
+    def initialize(
+      control_port:,
+      public_port:,
+      domain:,
+      url_port: nil,
+      tokens_path: TokenStore::DEFAULT_PATH,
+      tls_cert: nil,
+      tls_key: nil,
+      logger: Logger.new
+    )
+      @logger = logger
+      @registry = ClientRegistry.new
+      @token_store = TokenStore.new(
+        path: tokens_path,
+        active_subdomains: -> { @registry.active_subdomains },
+        logger: @logger
+      )
+      @pending_connections = PendingConnections.new
+
+      tls_context = TLS.server_context(cert_path: tls_cert, key_path: tls_key)
+
+      @control = ControlServer.new(
+        port: control_port,
+        domain: domain,
+        url_port: url_port,
+        registry: @registry,
+        token_store: @token_store,
+        pending_connections: @pending_connections,
+        tls_context: tls_context,
+        logger: @logger
+      )
+      @public = PublicServer.new(
+        port: public_port,
+        registry: @registry,
+        pending_connections: @pending_connections,
+        logger: @logger
+      )
+
+      @stop_flag = false
+      @threads = []
+      @stop_mutex = Mutex.new
+    end
+
+    def start(install_signals: true)
+      @logger.info "🚀 Starting tunnel server..."
+      @logger.info(@control.tls? ? "🔒 Control plane TLS: enabled" : "🔓 Control plane TLS: disabled")
+      install_signal_handlers if install_signals
+
+      @threads << Thread.new { @control.start }
+      @threads << Thread.new { @public.start }
+      @threads << Thread.new { @control.read_loop }
+      @threads << Thread.new { @control.ping_loop }
+      @threads << Thread.new {
+        @token_store.cleanup_loop(stop_flag: -> { @stop_flag })
+      }
+
+      @threads.each(&:join)
+    end
+
+    def stop
+      @stop_mutex.synchronize do
+        return if @stop_flag
+
+        @stop_flag = true
+      end
+
+      @logger.info "👋 Shutting down..."
+      @control.stop
+      @public.stop
+      @token_store.persist_now
+      @threads.each { |t| t.join(2) }
+    end
+
+    private
+
+    def install_signal_handlers
+      [:INT, :TERM].each do |sig|
+        Signal.trap(sig) { Thread.new { stop } }
+      end
+    end
+  end
+end

data/lib/tunnel_rb/version.rb

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

data/lib/tunnel_rb.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "tunnel_rb/version"
+require_relative "tunnel_rb/client"
+require_relative "tunnel_rb/server"
+
+# Backward-compatible alias for scripts that reference the top-level Tunnel class.
+Tunnel = TunnelRb::Client

data/tunnel-rb.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/tunnel_rb/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "tunnel-rb"
+  spec.version = TunnelRb::VERSION
+  spec.authors = ["headmandev"]
+  spec.email = ["headman.dev@gmail.com"]
+
+  spec.summary = "Expose a local HTTP server to the internet through a tunnel server"
+  spec.description = <<~DESC
+    tunnel-rb exposes a local HTTP server (e.g. a Rails app) to the internet through a tunnel server.
+    Includes the tunnel client CLI and tunnel server library — plain Ruby stdlib only, no runtime dependencies.
+  DESC
+  spec.homepage = "https://github.com/headmandev/tunnel-rb"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata = {
+    "source_code_uri" => spec.homepage
+  }
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob("{exe,lib}/**/*").select { |path| File.file?(path) } +
+      %w[tunnel-rb.gemspec README.md LICENSE]
+  end
+
+  spec.bindir = "exe"
+  spec.executables = %w[tunnel]
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: tunnel-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- headmandev
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  tunnel-rb exposes a local HTTP server (e.g. a Rails app) to the internet through a tunnel server.
+  Includes the tunnel client CLI and tunnel server library — plain Ruby stdlib only, no runtime dependencies.
+email:
+- headman.dev@gmail.com
+executables:
+- tunnel
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/tunnel
+- lib/tunnel_rb.rb
+- lib/tunnel_rb/cli.rb
+- lib/tunnel_rb/client.rb
+- lib/tunnel_rb/server.rb
+- lib/tunnel_rb/server/client.rb
+- lib/tunnel_rb/server/client_registry.rb
+- lib/tunnel_rb/server/control_server.rb
+- lib/tunnel_rb/server/http_request.rb
+- lib/tunnel_rb/server/logger.rb
+- lib/tunnel_rb/server/pending_connections.rb
+- lib/tunnel_rb/server/public_server.rb
+- lib/tunnel_rb/server/socket_helpers.rb
+- lib/tunnel_rb/server/thread_pool.rb
+- lib/tunnel_rb/server/tls.rb
+- lib/tunnel_rb/server/token_store.rb
+- lib/tunnel_rb/version.rb
+- tunnel-rb.gemspec
+homepage: https://github.com/headmandev/tunnel-rb
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/headmandev/tunnel-rb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Expose a local HTTP server to the internet through a tunnel server
+test_files: []