snell 0.1.0

data/lib/snell/transport.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Snell
+  # 拥有 socket，处理非阻塞 I/O 的部分读写；期限按 Fiber 保存，
+  # 避免并发上传和下载覆盖彼此的时间预算。
+  class Transport
+    attr_reader :socket
+
+    def initialize(socket, timeout: nil)
+      @socket = socket
+      @timeout = timeout
+      @deadlines = {}
+      @waiters = {}
+      @closed = false
+    end
+
+    # 嵌套范围可以缩短期限，不能延长外层预算。
+    # 期限约束 socket 等待，不能抢占 CPU 或原生加密调用。
+    def with_timeout(seconds)
+      fiber = Fiber.current
+      old = @deadlines[fiber]
+      deadline = monotonic + seconds
+      @deadlines[fiber] = old ? [old, deadline].min : deadline
+      yield
+    ensure
+      old ? @deadlines[fiber] = old : @deadlines.delete(fiber)
+    end
+
+    # 全部碎片共享一个绝对期限；未读到字节时的正常 EOF
+    # 使用 EOFError，读到部分字节后的 EOF 使用 ProtocolError。
+    def read_exactly(length)
+      raise ArgumentError, "length must be nonnegative" unless length.is_a?(Integer) && length >= 0
+
+      deadline = operation_deadline
+      result = +"".b
+      while result.bytesize < length
+        chunk = read_nonblock(length - result.bytesize, deadline)
+        if chunk.nil?
+          raise EOFError, "Transport reached EOF" if result.empty?
+
+          raise ProtocolError, "Truncated transport data"
+        end
+        result << chunk
+      end
+      result
+    end
+
+    def read_some(length = 16_384)
+      raise ArgumentError, "length must be positive" unless length.is_a?(Integer) && length.positive?
+
+      read_nonblock(length, operation_deadline)
+    end
+
+    def write_all(bytes)
+      bytes = String(bytes).b
+      deadline = operation_deadline
+      offset = 0
+      while offset < bytes.bytesize
+        check_open!
+        result = @socket.write_nonblock(bytes.byteslice(offset..), exception: false)
+        case result
+        when :wait_writable then wait(:writable, deadline)
+        when :wait_readable then wait(:readable, deadline)
+        else
+          raise IOError, "Transport write made no progress" unless result&.positive?
+
+          offset += result
+        end
+      end
+      offset
+    end
+
+    def close_write
+      @socket.shutdown(Socket::SHUT_WR) unless closed?
+    rescue Errno::ENOTCONN, Errno::EPIPE, IOError
+      nil
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      # 显式唤醒阻塞的 Fiber，避免依赖关闭 IO 自动唤醒的非通用行为；
+      # 遍历副本，因为恢复执行的等待者会注销自己。
+      @waiters.to_a.each do |fiber, scheduler|
+        scheduler.raise(fiber, ClosedError, "Transport is closed") if scheduler && fiber.alive?
+      end
+      @socket.close unless @socket.closed?
+    rescue IOError, Errno::EBADF
+      nil
+    end
+
+    def closed?
+      @closed || @socket.closed?
+    end
+
+    private
+
+    def read_nonblock(length, deadline)
+      loop do
+        check_open!
+        result = @socket.read_nonblock(length, exception: false)
+        case result
+        when :wait_readable then wait(:readable, deadline)
+        when :wait_writable then wait(:writable, deadline)
+        else return result
+        end
+      end
+    end
+
+    def wait(direction, deadline)
+      remaining = deadline && (deadline - monotonic)
+      raise TimeoutError, "Transport operation timed out" if remaining && remaining <= 0
+
+      @waiters[Fiber.current] = Fiber.scheduler
+      ready = @socket.public_send("wait_#{direction}", remaining)
+      raise TimeoutError, "Transport operation timed out" unless ready
+    ensure
+      @waiters.delete(Fiber.current)
+    end
+
+    def operation_deadline
+      explicit = @deadlines[Fiber.current]
+      default = @timeout && (monotonic + @timeout)
+      return explicit || default unless explicit && default
+
+      [explicit, default].min
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def check_open!
+      raise ClosedError, "Transport is closed" if closed?
+    end
+  end
+end

data/lib/snell/v6/profile.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+module Snell
+  module V6
+    # 整数运算由协议形态定义；Ruby 整数显式截断到协议位宽，
+    # 确保溢出在不同平台上具有一致含义。
+    class Profile
+      MASK = (1 << 64) - 1
+      G = 0x9e3779b97f4a7c15
+      D = 0xd6e8feb86659fd93
+      A = 0xe7037ed1a0b428db
+      SMALL_A = 0x8f3907f7b2b80c35
+      B = 0x589965cc75374cc3
+      SMALL_B = 0x33a213ec50ffe2e9
+      NAMESPACES = {
+        profile: [5, 0xb46c2e7d9a1538f1], prefix: [0, 0x5d9217c083e64ab9],
+        motif: [2, 0xa71f0c54d8396e2b], salt: [3, 0x3e8a91b52740f6cd],
+        mixing: [16, 0xc9f4260b7d1e835a], chunk: [21, 0x62d0b5e19c4a783f],
+        write: [28, 0x917b3c48e6a205d4]
+      }.freeze
+      BIT_ROWS = %w[
+        01020408102040800102040810204080 03050911214181060a122242820c1824
+        070b132343830d193161c10e1c3870e0 0f172747871b3363c31d3971e13c78f0
+        f8f4ecdcbc7cf2e6ce9e3ef1e3c78f1f fcfaf6eedebe7ef9f5edddbd7df3e7db
+        fefdfbf7efdfbf7ffefdfbf7efdfbf7f
+      ].map { |hex| [hex].pack("H*").freeze }.freeze
+
+      attr_reader :salt_prefix_length, :initial_chunk, :maximum_chunk, :chunk_increment, :idle_reset
+
+      def initialize(psk)
+        unless psk.is_a?(String) && psk.bytesize.between?(12, 255)
+          raise ArgumentError, "version 6 psk must contain 12 to 255 bytes"
+        end
+
+        secret = Crypto.blake2b256(["8d41a7135ce209bb702fd6943318c06e4a9125fdb80377ac"].pack("H*") + psk.b)
+        words = secret.unpack("Q<4")
+        @namespaces = NAMESPACES.transform_values do |label, seed|
+          mix((label * D) ^ ((seed + 0xa0761d6478bd642f) & MASK) ^ words[0] ^
+            ((words[1] + G) & MASK) ^ rotate(words[2], 17) ^ rotate(words[3], 53))
+        end.freeze
+        initialize_padding
+        initialize_mixing
+        initialize_sizes
+        @generator = scalar(6, 0) % 4
+        @g = [[24, 128], [16, 96], [16, 96], [0, 9], [1, 8], [7, 23]].each_with_index.map do |bounds, index|
+          select(scalar(6, index + 1), *bounds)
+        end.freeze
+        freeze
+      end
+
+      def inspect
+        "#<#{self.class}>"
+      end
+
+      def prf(label, input_x, input_y, namespace: namespace_for(label))
+        value = mix(@namespaces.fetch(namespace) ^ (((input_y & 0xffff_ffff) * B) + SMALL_B) ^
+          ((label & 0xffff_ffff) * G) ^ (((input_x & 0xffff_ffff) * A) + SMALL_A))
+        (value ^ (value >> 32)) & 0xffff_ffff
+      end
+
+      def bytes(label, sequence, length)
+        seed = @namespaces.fetch(namespace_for(label)) ^
+               (((sequence & 0xffff_ffff) * D) + 0xb57de1f3f82cb33f) ^
+               (label * 0xa24baed4963ee407) ^ ((length * 0x165667b19e3779f9) + 0x0d4cd3e7b14a36d7)
+        result = +"".b
+        ((length + 7) / 8).times { |index| result << [mix(seed + ((index + 1) * G))].pack("Q<") }
+        result.byteslice(0, length)
+      end
+
+      def padding(sequence, length)
+        result = bytes(0, sequence, length)
+        motif = bytes(2, sequence, 32) if @generator == 3
+        percent = select(prf(1, sequence, 0), @bit_min, @bit_max)
+        row = BIT_ROWS[(((percent * 8) + 50) / 100).clamp(1, 7) - 1]
+        result.bytesize.times do |index|
+          value = result.getbyte(index)
+          shaped = case @generator
+                   when 0
+                     source = row.getbyte((((value + index) & 255) ^ value) & 15)
+                     rotation = (((value + index) & 255) ^ (value >> 4)) & 7
+                     ((source << rotation) | (source >> (8 - rotation))) & 255
+                   when 1
+                     bucket = value % (@g[0] + @g[1] + @g[2])
+                     if bucket < @g[0]
+                       32 + (((value + index) & 255) % 95)
+                     elsif bucket < @g[0] + @g[1]
+                       128 + (((value ^ index) & 255) % 64)
+                     else
+                       192 + (((value + (7 * index)) & 255) % 64)
+                     end
+                   when 2
+                     ((value + (16 * (index % 4)) + 48) & 240) | (((value & 15) + @g[3] + (index % 2)) % 10)
+                   when 3
+                     period = [@g[5], 5].max
+                     position = index % period
+                     if position < period - 3
+                       (((@g[4] + 3) * index) & 255) ^ motif.getbyte((index % (4 * @g[4])) % 32)
+                     elsif position < period - 1
+                       48 | (value % 10)
+                     else
+                       value
+                     end
+                   end
+          result.setbyte(index, shaped)
+        end
+        result
+      end
+
+      def prefix_length(sequence)
+        select(prf(33, sequence, 0), @prefix_min, @prefix_max)
+      end
+
+      def salt_block(salt)
+        block = padding(0xffff_ffff, 16 + @salt_prefix_length)
+        salt.bytes.each_with_index { |value, index| block.setbyte(@salt_positions[index], value ^ salt_mask(index)) }
+        block
+      end
+
+      def extract_salt(block)
+        raise ProtocolError, "invalid shaped salt length" unless block.bytesize == 16 + @salt_prefix_length
+
+        (0...16).map { |index| block.getbyte(@salt_positions[index]) ^ salt_mask(index) }.pack("C*")
+      end
+
+      # 有意原地修改两个自有协议缓冲区；交换操作可逆，
+      # 读取器先恢复密文与 padding，再验证 AEAD 标签。
+      def mix!(padding, payload, sequence)
+        overlap = [padding.bytesize, payload.bytesize].min
+        @mix_rounds.times do |round|
+          if @mix_kind == 1
+            start = (round % 2) * @mix_block
+            while start + @mix_block <= overlap
+              (start...(start + @mix_block)).each { |index| exchange(padding, payload, index) }
+              start += @mix_block * 2
+            end
+          else
+            stride = @mix_stride + (round % 3)
+            first = @mix_offset
+            first += prf(3, sequence, round) if @mix_kind == 2
+            (first % stride).step(overlap - 1, stride) { |index| exchange(padding, payload, index) }
+          end
+        end
+        nil
+      end
+
+      # 流量形态的分块限制独立于 uint16 记录载荷容量。
+      # 首块上限为首条记录的额外封装预留空间。
+      def chunk_size(sequence, state)
+        size = case @chunk_kind
+               when 0 then state
+               when 1 then @chunk_choices[prf(38, sequence, state) % 8]
+               when 2 then state + (prf(39, sequence, state) % ((2 * @chunk_jitter) + 1)) - @chunk_jitter
+               end
+        size = size.clamp(64, @maximum_chunk)
+        sequence.zero? ? [size, @first_chunk_cap].min : size
+      end
+
+      def padding_length(sequence, payload_length)
+        padded = sequence < @initial_padded || (payload_length.positive? && payload_length <= @small_payload) ||
+                 (sequence % @padding_interval).zero?
+        base = padded ? select(prf(34, sequence, payload_length), @pad_min, @pad_max) : 0
+        prefix = prefix_length(sequence)
+        salt_length = sequence.zero? ? 16 + @salt_prefix_length : 0
+        frame_length = salt_length + prefix + 23 + base + payload_length + (payload_length.positive? ? 16 : 0)
+        target = write_target(sequence, frame_length)
+        length = base + (target - frame_length).clamp(0, 730)
+        if sequence.zero?
+          minimum = [((payload_length + (payload_length.positive? ? 55 : 39)) + 2) / 3, 192].max
+          length = [length, minimum - @salt_prefix_length - prefix].max
+          length = [length, @pad_max + 730].min
+        end
+        length
+      end
+
+      private
+
+      def initialize_padding
+        @pad_min = field(7, 24, 160)
+        @pad_max = [@pad_min + field(8, 160, 960), 730].min
+        @initial_padded = field(9, 2, 8)
+        @padding_interval = field(10, 2, 11)
+        @small_payload = field(11, 96, 768)
+        @bit_min = field(12, 24, 41)
+        @bit_max = field(13, 58, 76)
+        @prefix_min, @prefix_max = prefix_bounds(0, 8, 80)
+        salt_min, salt_max = prefix_bounds(0x7053, 16, 96)
+        @salt_prefix_length = select(scalar(33, 0x7053), salt_min, salt_max)
+        @salt_stride = field(18, 17, 251, 0x51a7)
+        positions = (0...(16 + @salt_prefix_length)).to_a
+        field(17, 1, 4, 0x51a7).times do |round|
+          positions.each_index do |index|
+            value = mix(((index * B) + SMALL_B) ^ @namespaces.fetch(:salt) ^
+              0xdaa66d2c7ddf743f ^ (((0x51a7 + round) * A) + SMALL_A))
+            other = index + (((value ^ (value >> 32)) & 0xffff_ffff) % (positions.length - index))
+            positions[index], positions[other] = positions[other], positions[index]
+          end
+        end
+        @salt_positions = positions.freeze
+      end
+
+      def initialize_mixing
+        @mix_kind = scalar(16, 0) % 3
+        @mix_rounds = field(17, 1, 3)
+        @mix_stride = field(18, 2, 13)
+        @mix_offset = field(19, 0, 15)
+        @mix_block = field(20, 8, 64)
+      end
+
+      def initialize_sizes
+        @initial_chunk = field(22, 512, 1460)
+        @first_chunk_cap = [field(22, 256, 768, 0xf17c), @initial_chunk, 768].min.clamp(256, 768)
+        @maximum_chunk = [field(23, 8192, 16_383), @initial_chunk].max
+        @chunk_increment = [field(24, 1024, 4096), 2920].min
+        @chunk_jitter = [field(25, 16, 192), 182].min
+        @idle_reset = field(27, 12, 90)
+        @chunk_kind = scalar(21, 0) % 3
+        @write_kind = scalar(28, 0) % 3
+        @initial_targets = field(29, 4, 8)
+        @write_jitter = field(32, 8, 96)
+        @spread_percent = field(28, 8, 48, 0x504c)
+        @chunk_choices = Array.new(8) { |i| field(26, 4096, @maximum_chunk, i) }.freeze
+        @write_choices = Array.new(8) { |i| field(30, 320, 1460, i) }.freeze
+        @initial_choices = Array.new(8) { |i| field(31, 360, 1460, i) }.freeze
+      end
+
+      def write_target(sequence, length)
+        return [length, 65_535].min if length > 1459
+
+        target = if sequence < @initial_targets
+                   @initial_choices[sequence]
+                 else
+                   @write_choices[prf(35, sequence,
+                                      length) % 8]
+                 end
+        if @write_kind == 2
+          target = [target + (prf(36, sequence, 0) % ((2 * @write_jitter) + 1)) - @write_jitter,
+                    1].max
+        end
+        spread = [730, length * @spread_percent / 100].min
+        if prf(35, sequence, spread).even?
+          target = [target + spread, 65_535].min
+        elsif target > spread / 2
+          target -= spread / 2
+        end
+        while target < length
+          candidate = @write_choices[prf(37, sequence, target) % 8]
+          target = candidate > target ? candidate : [target + @pad_max, 65_535].min
+        end
+        target
+      end
+
+      def prefix_bounds(domain, low, high)
+        minimum = field(14, low, high, domain)
+        maximum = [minimum + field(15, 16, 160, domain), 128].min
+        [[minimum, maximum].min, maximum]
+      end
+
+      def salt_mask(index)
+        ((index * @salt_stride) & 255) ^ (prf(2, 0x51a7, index, namespace: :salt) & 255)
+      end
+
+      def field(label, low, high, domain = 0)
+        select(scalar(label, domain), low, high)
+      end
+
+      def scalar(label, domain)
+        prf(label, 0, domain)
+      end
+
+      def select(value, low, high)
+        low + (value % (high - low + 1))
+      end
+
+      def namespace_for(label)
+        case label
+        when 0, 1, 14, 15, 33, 34 then :prefix
+        when 2 then :motif
+        when 3, 16, 17, 18, 19, 20 then :mixing
+        when 21..26, 38, 39 then :chunk
+        when 28..32, 35, 36, 37 then :write
+        else :profile
+        end
+      end
+
+      def mix(value)
+        value &= MASK
+        value = ((value ^ (value >> 30)) * 0xbf58476d1ce4e5b9) & MASK
+        value = ((value ^ (value >> 27)) * 0x94d049bb133111eb) & MASK
+        value ^ (value >> 31)
+      end
+
+      def rotate(value, count)
+        ((value << count) | (value >> (64 - count))) & MASK
+      end
+
+      def exchange(first, second, index)
+        value = first.getbyte(index)
+        first.setbyte(index, second.getbyte(index))
+        second.setbyte(index, value)
+      end
+    end
+  end
+end

data/lib/snell/version.rb

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

data/lib/snell.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/semaphore"
+require_relative "snell/version"
+require_relative "snell/errors"
+require_relative "snell/limits"
+require_relative "snell/replay_cache"
+require_relative "snell/transport"
+require_relative "snell/address"
+require_relative "snell/datagram"
+require_relative "snell/protocol"
+require_relative "snell/crypto"
+require_relative "snell/record_reader"
+require_relative "snell/record_writer"
+require_relative "snell/obfuscation"
+require_relative "snell/direct_connector"
+require_relative "snell/session"
+require_relative "snell/session_pool"
+require_relative "snell/stream"
+require_relative "snell/datagram_socket"
+require_relative "snell/client"
+require_relative "snell/server"
+require_relative "snell/configuration"
+require_relative "snell/socks_server"
+require_relative "snell/cli"
+
+# 公开加载入口；require 只定义 API，不建立网络连接。
+module Snell
+  # 复用当前 Async 任务；没有任务时创建 reactor 并等待执行完成。
+  def self.run(&block)
+    raise ArgumentError, "A block is required" unless block
+
+    if Async::Task.current?
+      block.call(Async::Task.current)
+    else
+      Async(&block).wait
+    end
+  end
+
+  def self.reactor!
+    raise Error, "Use Snell.run or an Async task" unless Async::Task.current?
+
+    Fiber.scheduler
+  end
+
+  def self.address(value)
+    case value
+    when Address then value
+    when Array then Address.new(host: value.fetch(0), port: value.fetch(1))
+    when Hash then Address.new(**value.transform_keys(&:to_sym))
+    else raise ArgumentError, "Expected Address, [host, port], or {host:, port:}"
+    end
+  end
+
+  def self.mode(value)
+    raise ArgumentError, "Invalid mode" unless value.is_a?(Symbol) || value.is_a?(String)
+
+    name = value.to_sym
+    name == :"unsafe-raw" ? :raw : name
+  end
+
+  def self.obfs(value)
+    raise ArgumentError, "Invalid obfuscation" unless value.is_a?(Symbol) || value.is_a?(String)
+
+    value.to_sym
+  end
+end

metadata

@@ -0,0 +1,155 @@
+--- !ruby/object:Gem::Specification
+name: snell
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Snell Ruby contributors
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.46'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.46'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: io-endpoint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.19'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.19'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: rbnacl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+description: A Ruby implementation of Snell TCP streams and UDP associations with
+  bounded asynchronous I/O.
+executables:
+- snell
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/ARCHITECTURE.md
+- docs/COMPATIBILITY.md
+- docs/PROVENANCE.md
+- docs/SECURITY.md
+- exe/snell
+- lib/snell.rb
+- lib/snell/address.rb
+- lib/snell/cli.rb
+- lib/snell/client.rb
+- lib/snell/configuration.rb
+- lib/snell/crypto.rb
+- lib/snell/datagram.rb
+- lib/snell/datagram_socket.rb
+- lib/snell/direct_connector.rb
+- lib/snell/errors.rb
+- lib/snell/limits.rb
+- lib/snell/obfuscation.rb
+- lib/snell/protocol.rb
+- lib/snell/record_reader.rb
+- lib/snell/record_writer.rb
+- lib/snell/replay_cache.rb
+- lib/snell/server.rb
+- lib/snell/session.rb
+- lib/snell/session_pool.rb
+- lib/snell/socks_server.rb
+- lib/snell/stream.rb
+- lib/snell/transport.rb
+- lib/snell/v6/profile.rb
+- lib/snell/version.rb
+homepage: https://github.com/gatework/snell
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/gatework/snell
+  changelog_uri: https://github.com/gatework/snell/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Async Ruby client and server for the Snell proxy protocol
+test_files: []