snell 0.1.0

data/lib/snell/cli.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Snell
+  # 进程边界，负责配置校验、退出码和脱敏诊断。
+  # 信号处理器通过管道与 reactor 任务通信。
+  class CLI
+    USAGE = "Usage: snell {client|server|check} --config FILE\n       snell version\n"
+
+    def self.run(argv = ARGV, out: $stdout, err: $stderr)
+      new(out: out, err: err).run(argv)
+    end
+
+    def initialize(out:, err:)
+      @out = out
+      @err = err
+    end
+
+    def run(arguments)
+      argv = arguments.dup
+      command = argv.shift
+      if %w[--help -h help].include?(command) && argv.empty?
+        @out.write(USAGE)
+        return 0
+      end
+      if %w[version --version -v].include?(command) && argv.empty?
+        @out.puts(Snell::VERSION)
+        return 0
+      end
+      raise Configuration::Error, "a supported command is required" unless %w[client server check].include?(command)
+
+      config_path = nil
+      help = false
+      OptionParser.new do |parser|
+        parser.on("--config FILE") do |path|
+          raise Configuration::Error, "--config may only be specified once" if config_path
+
+          config_path = path
+        end
+        parser.on("-h", "--help") { help = true }
+      end.parse!(argv)
+      raise Configuration::Error, "unexpected command arguments" unless argv.empty?
+
+      if help
+        @out.write(USAGE)
+        return 0
+      end
+      raise Configuration::Error, "--config FILE is required" unless config_path
+
+      config = Configuration.load(config_path, expected_type: command == "check" ? nil : command)
+      if command == "check"
+        @out.puts("Configuration valid (#{config.type}, version #{config.version})")
+        return 0
+      end
+
+      run_service(config)
+    rescue OptionParser::ParseError
+      @err.puts("snell: invalid command options")
+      @err.write(USAGE)
+      2
+    rescue Configuration::Error => e
+      @err.puts("snell: #{e.message}")
+      2
+    rescue Interrupt
+      130
+    rescue StandardError => e
+      @err.puts("snell: operational failure (#{e.class})")
+      1
+    end
+
+    private
+
+    def run_service(config)
+      status = 0
+      failure = nil
+      reader, writer = IO.pipe
+      previous = install_signals(writer)
+      Snell.run do
+        signal_received = false
+        client = Client.new(**config.runtime_options) if config.type == "client"
+        service = client ? SocksServer.new(client: client, limits: config.limits) : Server.new(**config.runtime_options)
+        runner = Async::Task.current.async do
+          service.run(listen: config.listen)
+        rescue StandardError => e
+          failure = e
+        end
+        watcher = Async::Task.current.async do
+          signal = reader.read(1)
+          signal_received = !signal.nil?
+          status = 130 if signal == "I"
+          service.stop(grace: config.limits.fetch(:shutdown_grace)) if signal
+          runner.stop if signal
+        end
+        begin
+          runner.wait
+          watcher.wait if signal_received
+        ensure
+          watcher.stop
+          service.stop(grace: 0)
+          runner.stop
+          client&.close
+          report_shutdown(service)
+        end
+      rescue StandardError => e
+        # 在此接收服务错误，避免 Async 输出自己的异常详情；
+        # 命令边界只输出包含错误类型的一条诊断。
+        failure = e
+      end
+      raise failure if failure
+
+      status
+    ensure
+      previous&.each { |signal, handler| Signal.trap(signal, handler) }
+      reader&.close
+      writer&.close
+    end
+
+    def report_shutdown(service)
+      return unless service.respond_to?(:stats)
+
+      fields = %i[accepted rejected completed failed reused active_connections handshakes udp_associations]
+      counters = service.stats.slice(*fields).select { |_key, value| value.is_a?(Integer) && value >= 0 }
+      @err.puts(JSON.generate(event: "shutdown", stats: counters))
+    end
+
+    # 信号处理器只写一个字节；调度与清理在监听 Fiber 内执行，
+    # 不在 Ruby 信号处理上下文中调用。
+    def install_signals(writer)
+      { "INT" => "I", "TERM" => "T" }.to_h do |signal, byte|
+        previous = Signal.trap(signal) do
+          writer.write_nonblock(byte, exception: false)
+        rescue IOError, SystemCallError
+          nil
+        end
+        [signal, previous]
+      end
+    end
+  end
+end

data/lib/snell/client.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Snell
+  # 由 reactor 管理的协议客户端，拥有 TCP 连接池和专用 UDP/ping
+  # 会话；返回的流与关联由调用者关闭，块形式则自动清理。
+  class Client
+    def initialize(server:, psk:, version: 4, mode: :default, user_key: "", reuse: true,
+                   obfs: :none, obfs_host: nil, obfs_uri: "/", limits: {})
+      @owner = Snell.reactor!
+      raise ArgumentError, "psk must be a nonempty String" unless psk.is_a?(String) && !psk.empty?
+      raise ArgumentError, "user_key must be a String" unless user_key.is_a?(String)
+
+      @server = Snell.address(server)
+      @psk = String(psk).dup.freeze
+      @version = version
+      @mode = Snell.mode(mode)
+      @user_key = String(user_key).b.dup.freeze
+      @reuse = reuse
+      @obfs = Snell.obfs(obfs)
+      @obfs_host = obfs_host
+      @obfs_uri = obfs_uri
+      @limits = limits.is_a?(Limits) ? limits : Limits.new(limits)
+      @pool = SessionPool.new(limits: @limits)
+      @connector = DirectConnector.new
+      @udp_count = 0
+      validate!
+    end
+
+    # 发送请求后返回，不等待目标连接确认。
+    # Stream 首次读取解析回复；块形式无论成功失败都会关闭流。
+    def connect(host, port, early_data: nil)
+      check_owner!
+      destination = Address.new(host: host, port: port)
+      raise ArgumentError, "early_data must be a String" unless early_data.nil? || early_data.is_a?(String)
+
+      request = Protocol.encode_request(command: 5, user_key: @user_key, destination: destination)
+      session = acquire
+      session.transport.with_timeout(@limits[:handshake_timeout]) do
+        session.write_request(request, early_data: early_data || "".b)
+      end
+      stream = Stream.new(session, limits: @limits, reusable: @reuse, release: @pool.method(:release))
+      return stream unless block_given?
+
+      begin
+        yield stream
+      ensure
+        stream.close
+      end
+    ensure
+      @pool.release(session, reusable: false) if session && !stream
+    end
+
+    # 在可能让出执行权的操作前预留关联容量；构造失败回退计数，
+    # 成功返回的 socket 在关闭时释放预留项。
+    def open_udp
+      check_owner!
+      raise CapacityError, "UDP association limit reached" if @udp_count >= @limits[:udp_associations]
+
+      @udp_count += 1
+      counted = true
+      session = acquire(reuse: false)
+      socket = DatagramSocket.new(session, user_key: @user_key, limits: @limits, release: lambda { |owned|
+        @pool.release(owned, reusable: false)
+        @udp_count -= 1 if counted
+      })
+      return socket unless block_given?
+
+      begin
+        yield socket
+      ensure
+        socket.close
+      end
+    ensure
+      unless socket
+        @pool.release(session, reusable: false) if session
+        @udp_count -= 1 if counted
+      end
+    end
+
+    # 仅测量协议可达性，不证明用户授权或目标访问权限。
+    def ping
+      check_owner!
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      session = acquire(reuse: false)
+      session.transport.with_timeout(@limits[:handshake_timeout]) do
+        session.write_record(Protocol.encode_request(command: 0, user_key: ""))
+        reply = Protocol.decode_reply(session.read_record)
+        raise ProtocolError, "Expected pong reply" unless reply.kind == 1
+      end
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+    ensure
+      @pool.release(session, reusable: false) if session
+    end
+
+    def close_idle_connections
+      check_owner!
+      @pool.close_idle_connections
+    end
+
+    def close
+      check_owner!
+      @pool.close
+    end
+
+    def inspect
+      "#<#{self.class} version=#{@version} mode=#{@mode}>"
+    end
+
+    private
+
+    def acquire(reuse: @reuse)
+      @pool.acquire(reuse: reuse) do
+        socket = @connector.connect(@server, timeout: @limits[:dial_timeout])
+        begin
+          transport = Transport.new(socket, timeout: @limits[:idle_timeout])
+          transport = Obfuscation.wrap(transport, mode: @obfs, role: :client, host: @obfs_host, uri: @obfs_uri)
+          session = Session.new(transport, psk: @psk, version: @version, mode: @mode, role: :client, limits: @limits)
+        ensure
+          socket.close unless session
+        end
+      end
+    end
+
+    def check_owner!
+      raise Error, "Client belongs to another reactor" unless Fiber.scheduler.equal?(@owner)
+    end
+
+    def validate!
+      raise ArgumentError, "Client version must be 4 or 6" unless [4, 6].include?(@version)
+      raise ArgumentError, "Invalid mode" unless %i[default unshaped raw].include?(@mode)
+      raise ArgumentError, "Mode requires version 6" unless @version == 6 || @mode == :default
+      raise ArgumentError, "Invalid obfuscation" unless %i[none http tls].include?(@obfs)
+      raise ArgumentError, "Obfuscation is unavailable with version 6" if @version == 6 && @obfs != :none
+      if @version == 6 && !@psk.bytesize.between?(12, 255)
+        raise ArgumentError, "version 6 psk must contain 12 to 255 bytes"
+      end
+      raise ArgumentError, "user_key is too long" if @user_key.bytesize > 255
+      raise ArgumentError, "reuse must be boolean" unless [true, false].include?(@reuse)
+    end
+  end
+end

data/lib/snell/configuration.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "json"
+require "ipaddr"
+
+module Snell
+  # 严格配置边界；诊断不包含密钥或配置原文。
+  class Configuration
+    class Error < ArgumentError; end
+
+    # JSON.parse 逐字段调用 []=，在重复键覆盖角色、密钥或
+    # 资源预算之前拒绝输入。
+    class JSONObject < Hash
+      def []=(key, value)
+        raise Error, "duplicate JSON field" if key?(key)
+
+        super
+      end
+    end
+
+    DEFAULT_LIMITS = {
+      max_connections: 2048, handshake_concurrency: 64, handshake_rate: 100,
+      handshake_burst: 200, udp_associations: 256, buffer_bytes: 131_072,
+      dial_timeout: 10, handshake_timeout: 10, idle_timeout: 300,
+      pool_max_idle: 10, pool_idle_timeout: 180, drain_timeout: 2,
+      drain_max_bytes: 524_288, shutdown_grace: 30
+    }.freeze
+    INTEGER_LIMITS = %i[max_connections handshake_concurrency handshake_burst
+                        udp_associations buffer_bytes pool_max_idle drain_max_bytes].freeze
+    FIELDS = %w[type listen server psk user_key users version mode obfs obfs_host obfs_uri reuse limits].freeze
+
+    attr_reader :type, :listen, :server, :psk, :user_key, :users, :version,
+                :mode, :obfs, :obfs_host, :obfs_uri, :reuse, :limits
+
+    def self.load(path, expected_type: nil)
+      raw = File.read(path, encoding: Encoding::UTF_8)
+      new(JSON.parse(raw, object_class: JSONObject), expected_type: expected_type)
+    rescue JSON::ParserError, EncodingError
+      raise Error, "configuration must contain valid UTF-8 JSON"
+    rescue SystemCallError, IOError
+      raise Error, "cannot read configuration file"
+    end
+
+    def initialize(values, expected_type: nil)
+      object!(values, "configuration", FIELDS)
+      @type = enum!(values.fetch("type", nil), "type", %w[client server])
+      raise Error, "configuration type does not match command" if expected_type && @type != expected_type
+
+      validate_role_fields!(values)
+      @version = values.fetch("version", @type == "client" ? 4 : 5)
+      versions = @type == "client" ? [4, 6] : [5, 6]
+      unless @version.is_a?(Integer) && versions.include?(@version)
+        raise Error,
+              "version is not supported for this type"
+      end
+
+      @mode = enum!(values.fetch("mode", "default"), "mode", %w[default unshaped unsafe-raw])
+      @obfs = enum!(values.fetch("obfs", "none"), "obfs", %w[none http tls])
+      raise Error, "mode requires version 6" if @version != 6 && @mode != "default"
+      raise Error, "obfs is unavailable with version 6" if @version == 6 && @obfs != "none"
+
+      @psk = string!(values.fetch("psk", nil), "psk", min: @version == 6 ? 12 : 1,
+                                                      max: @version == 6 ? 255 : nil)
+      @user_key = values.key?("user_key") ? string!(values["user_key"], "user_key", max: 255) : nil
+      @users = parse_users(values)
+      @listen = endpoint!(values.fetch("listen", @type == "client" ? "127.0.0.1:1080" : nil), "listen")
+      validate_loopback!(@listen.host) if @type == "client"
+      @server = endpoint!(values.fetch("server", nil), "server") if @type == "client"
+      @reuse = values.fetch("reuse", true)
+      raise Error, "reuse must be boolean" unless [true, false].include?(@reuse)
+
+      @obfs_host = if values.key?("obfs_host")
+                     string!(values["obfs_host"], "obfs_host", min: 1, max: 255)
+                   else
+                     "www.example.com"
+                   end
+      @obfs_uri = values.key?("obfs_uri") ? string!(values["obfs_uri"], "obfs_uri", min: 1, max: 2048) : "/"
+      raise Error, "obfs_host contains invalid characters" if @obfs_host.match?(/[\x00-\x20\x7f]/)
+      unless @obfs_uri.start_with?("/") && !@obfs_uri.match?(/[\x00-\x20\x7f]/)
+        raise Error, "obfs_uri must be an absolute request path without whitespace"
+      end
+
+      @limits = parse_limits(values.fetch("limits", {}))
+      freeze
+    end
+
+    # 将已校验的 JSON 角色映射为构造参数，保留 reuse 的 false，
+    # 并区分未配置 users 与非法的空用户数组。
+    def runtime_options
+      options = { psk: @psk, version: @version, mode: @mode, obfs: @obfs,
+                  obfs_host: @obfs_host, obfs_uri: @obfs_uri, limits: @limits }
+      if @type == "client"
+        options.merge(server: @server, user_key: @user_key || "", reuse: @reuse)
+      else
+        options.merge(users: @users)
+      end
+    end
+
+    def inspect
+      "#<#{self.class} type=#{@type.inspect} version=#{@version.inspect} secrets=[REDACTED]>"
+    end
+
+    private
+
+    def object!(value, field, allowed)
+      raise Error, "#{field} must be an object" unless value.is_a?(Hash)
+      raise Error, "#{field} contains unknown fields" unless (value.keys - allowed).empty?
+    end
+
+    def string!(value, field, min: 0, max: nil)
+      unless value.is_a?(String) && value.encoding.ascii_compatible? && value.dup.force_encoding(Encoding::UTF_8).valid_encoding?
+        raise Error, "#{field} must be a UTF-8 string"
+      end
+      raise Error, "#{field} has invalid byte length" if value.bytesize < min || (max && value.bytesize > max)
+
+      value.dup.freeze
+    end
+
+    def enum!(value, field, allowed)
+      raise Error, "#{field} has an unsupported value" unless value.is_a?(String) && allowed.include?(value)
+
+      value.dup.freeze
+    end
+
+    def validate_role_fields!(values)
+      forbidden = @type == "client" ? %w[users] : %w[server user_key reuse]
+      raise Error, "configuration contains fields for the other type" if values.keys.intersect?(forbidden)
+    end
+
+    def endpoint!(value, field)
+      value = string!(value, field, min: 1)
+      match = /\A(?:\[([^\]]+)\]|([^:\s]+)):(\d+)\z/.match(value)
+      raise Error, "#{field} must be host:port (IPv6 requires brackets)" unless match
+
+      host = match[1] || match[2]
+      port = Integer(match[3], 10)
+      raise Error, "#{field} port must be between 1 and 65535" unless (1..65_535).cover?(port)
+
+      if match[1]
+        begin
+          raise Error, "#{field} brackets require IPv6" unless IPAddr.new(host).ipv6?
+        rescue IPAddr::InvalidAddressError
+          raise Error, "#{field} contains invalid IPv6"
+        end
+      end
+      raise Error, "#{field} contains invalid host" if host.match?(%r{[\x00-\x20\x7f/]}) || host.bytesize > 255
+
+      Address.new(host: host, port: port)
+    end
+
+    def validate_loopback!(host)
+      return if host == "localhost"
+
+      raise Error, "client listen must be a loopback address" unless IPAddr.new(host).loopback?
+    rescue IPAddr::InvalidAddressError
+      raise Error, "client listen must be a loopback address"
+    end
+
+    def parse_users(values)
+      return nil unless values.key?("users")
+
+      entries = values["users"]
+      raise Error, "users must be a nonempty array" unless entries.is_a?(Array) && !entries.empty?
+
+      keys = {}
+      entries.map do |entry|
+        object!(entry, "users entry", %w[name user_key])
+        name = string!(entry.fetch("name", nil), "users name", min: 1, max: 255)
+        key = string!(entry.fetch("user_key", nil), "users user_key", min: 1, max: 255)
+        raise Error, "users contains duplicate user keys" if keys[key]
+
+        keys[key] = true
+        { name: name, user_key: key }.freeze
+      end.freeze
+    end
+
+    def parse_limits(values)
+      object!(values, "limits", DEFAULT_LIMITS.keys.map(&:to_s))
+      overrides = values.to_h do |key, value|
+        name = key.to_sym
+        valid_type = INTEGER_LIMITS.include?(name) ? value.is_a?(Integer) : value.is_a?(Numeric)
+        valid = valid_type && value.finite? && (name == :pool_max_idle ? value >= 0 : value.positive?)
+        unless valid
+          raise Error,
+                "limits #{key} must be a valid positive #{INTEGER_LIMITS.include?(name) ? 'integer' : 'number'}"
+        end
+
+        [name, value]
+      end
+      DEFAULT_LIMITS.merge(overrides).freeze
+    end
+  end
+end

data/lib/snell/crypto.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "rbnacl"
+
+module Snell
+  # 协议加密原语；KDF 参数是互通所需的固定值，
+  # 不作为通用密码存储策略；调用者应提供高熵 PSK。
+  module Crypto
+    SALT_BYTES = 16
+    TAG_BYTES = 16
+    NONCE_BYTES = 12
+
+    module_function
+
+    def derive_key(psk, salt)
+      raise ArgumentError, "psk must be a nonempty String" unless psk.is_a?(String) && !psk.empty?
+      raise ArgumentError, "salt must contain 16 bytes" unless salt.is_a?(String) && salt.bytesize == SALT_BYTES
+
+      RbNaCl::PasswordHash::Argon2.new(3, 8192, 32).digest(psk.b, salt.b, :argon2id).byteslice(0, 16)
+    end
+
+    def blake2b256(bytes)
+      raise ArgumentError, "input must be a String" unless bytes.is_a?(String)
+
+      RbNaCl::Hash.blake2b(bytes.b, digest_size: 32)
+    end
+
+    # 同一实例在物理连接的整个生命周期内只用于一个加密方向。
+    class Cipher
+      def initialize(key)
+        @key = key.b.freeze
+        @counter = 0
+      end
+
+      def encrypt(plaintext, aad: "".b)
+        cipher = build(:encrypt, aad)
+        result = (plaintext.empty? ? +"".b : cipher.update(plaintext)) + cipher.final
+        result + cipher.auth_tag(TAG_BYTES)
+      end
+
+      # 只有 final 验证认证标签后才返回明文。
+      # 失败的尝试也会消耗 nonce，记录层因此必须停用该读取器。
+      def decrypt(ciphertext, aad: "".b)
+        raise AuthenticationError, "truncated authentication tag" if ciphertext.bytesize < TAG_BYTES
+
+        cipher = build(:decrypt, aad)
+        cipher.auth_tag = ciphertext.byteslice(-TAG_BYTES, TAG_BYTES)
+        body = ciphertext.byteslice(0, ciphertext.bytesize - TAG_BYTES)
+        result = body.empty? ? +"".b : cipher.update(body)
+        result + cipher.final
+      rescue OpenSSL::Cipher::CipherError
+        raise AuthenticationError, "record authentication failed", cause: nil
+      end
+
+      def inspect
+        "#<#{self.class}>"
+      end
+
+      private
+
+      def build(operation, aad)
+        raise ProtocolError, "nonce space exhausted" if @counter >= (1 << 96)
+
+        # 96 位协议 nonce 显式采用小端序，不依赖宿主字节序。
+        nonce = [@counter & 0xffff_ffff_ffff_ffff, @counter >> 64].pack("Q<V")
+        @counter += 1
+        cipher = OpenSSL::Cipher.new("aes-128-gcm")
+        cipher.public_send(operation)
+        cipher.key = @key
+        cipher.iv = nonce
+        cipher.auth_data = aad
+        cipher
+      end
+    end
+  end
+end

data/lib/snell/datagram.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Snell
+  # 持有不可变的载荷副本及经过校验的目的地址或来源地址。
+  # Data 默认 inspect 包含载荷字节，不应直接用于流量日志。
+  Datagram = Data.define(:payload, :address) do
+    def initialize(payload:, address:)
+      raise ArgumentError, "payload must be a String" unless payload.is_a?(String)
+      raise ArgumentError, "address must be a Snell::Address" unless address.is_a?(Address)
+
+      super(payload: payload.b.freeze, address: address)
+    end
+  end
+end

data/lib/snell/datagram_socket.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Snell
+  # 专用的 UDP over TCP 关联，不参与 TCP 空闲连接复用。
+  # 构造时等待远端确认，每个报文占用一条记录。
+  # 空 UDP 载荷仍合法，因为地址头使协议记录保持非空。
+  class DatagramSocket
+    def initialize(session, user_key:, limits:, release:)
+      @session = session
+      @release = release
+      @owner = Fiber.scheduler
+      @read_lock = Async::Semaphore.new(1)
+      @write_lock = Async::Semaphore.new(1)
+      @closed = false
+      @session.transport.with_timeout(limits[:handshake_timeout]) do
+        @session.write_record(Protocol.encode_request(command: 6, user_key: user_key))
+        response = Protocol.decode_reply(@session.read_record)
+        raise RemoteError.new(response.message.to_s, code: response.code) if response.kind == 2
+        raise ProtocolError, "Expected UDP tunnel reply" unless response.kind.zero? && response.payload.empty?
+      end
+    end
+
+    def send_packet(payload, to:)
+      check_open!
+      packet = Protocol.encode_packet(payload, Snell.address(to), role: :client)
+      raise ArgumentError, "Datagram exceeds record capacity" if packet.bytesize > @session.writer.max_payload
+
+      @write_lock.acquire { @session.write_record(packet) }
+      payload.bytesize
+    rescue Error, IOError, SystemCallError
+      close
+      raise
+    end
+
+    def receive_packet
+      check_open!
+      @read_lock.acquire { Protocol.decode_packet(@session.read_record, role: :client) }
+    rescue Error, IOError, SystemCallError
+      close
+      raise
+    end
+
+    def close
+      check_owner!
+      return if @closed
+
+      @closed = true
+      @session.close
+      @release.call(@session)
+      nil
+    end
+
+    def closed?
+      @closed || @session.closed?
+    end
+
+    private
+
+    def check_open!
+      check_owner!
+      raise ClosedError, "UDP association is closed" if closed?
+    end
+
+    def check_owner!
+      raise Error, "UDP association belongs to another reactor" unless Fiber.scheduler.equal?(@owner)
+    end
+  end
+end

data/lib/snell/direct_connector.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "io/endpoint/host_endpoint"
+
+module Snell
+  # 默认网络边界，可通过 Server#initialize 注入替代策略。
+  # connect 将 socket 所有权交给调用者；udp 只解析 Addrinfo。
+  # 目标访问策略由注入的连接器或部署网络负责。
+  class DirectConnector
+    def connect(address, timeout: 10)
+      task = Async::Task.current
+      task.with_timeout(timeout) do
+        IO::Endpoint.tcp(address.host, address.port).connect
+      end
+    rescue Async::TimeoutError
+      raise TimeoutError, "Connection attempt timed out"
+    end
+
+    # 选择一个已解析的监听地址，绑定后的 socket 由调用者负责关闭。
+    def bind(address)
+      IO::Endpoint.tcp(address.host, address.port).each.first.bind.first
+    end
+
+    def udp(address)
+      Addrinfo.getaddrinfo(address.host, address.port, nil, :DGRAM).first
+    end
+  end
+end

data/lib/snell/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Snell
+  # 运行时与协议错误归入 Error；Ruby API 参数非法时使用
+  # ArgumentError，物理连接的正常读结束保留标准 EOFError 契约。
+  class Error < StandardError; end
+  class ProtocolError < Error; end
+  class AuthenticationError < ProtocolError; end
+  class TimeoutError < Error; end
+  class ClosedError < Error; end
+  class CapacityError < Error; end
+
+  # 分别保留远端协议错误码与可读消息，便于调用者判断失败原因。
+  class RemoteError < Error
+    attr_reader :code
+
+    def initialize(message = "Remote operation failed", code: nil)
+      @code = code
+      super(message)
+    end
+  end
+end