anytls 0.1.0

data/lib/anytls/session.rb

@@ -0,0 +1,593 @@
+# frozen_string_literal: true
+
+module AnyTLS
+  # 每条连接由唯一所有者线程推进 TLS、帧处理和流状态。
+  # 其他线程提交受容量限制的操作，并等待本地发送完成。
+  # 所有者线程中的回调不得同步向同一会话提交任务。
+  class Session
+    # 与等待者共享的一次性结果；首次完成的结果生效。
+    class Completion
+      def initialize
+        @mutex = Mutex.new
+        @changed = ConditionVariable.new
+        @done = false
+      end
+
+      def finish(value = nil, error: nil)
+        @mutex.synchronize do
+          return if @done
+
+          @value = value
+          @error = error
+          @done = true
+          @changed.broadcast
+        end
+      end
+
+      def wait(deadline)
+        @mutex.synchronize do
+          deadline.wait(@changed, @mutex) until @done
+          raise @error if @error
+
+          @value
+        end
+      end
+    end
+
+    private_constant :Completion
+
+    attr_reader :sequence
+
+    def initialize(socket, tls:, password_digest:, scheme:, server: false, host: nil, sequence: 0,
+                   handshake_timeout: 5, open_timeout: 5, max_streams: 32, receive_limit: 262_144,
+                   session_receive_limit: 4_194_304, send_limit: 1_048_576, logger: nil,
+                   on_stream: nil, on_idle: nil, on_close: nil, on_padding: nil)
+      @socket = socket
+      @tls = tls
+      @host = host
+      @server = server
+      @password_digest = password_digest
+      @scheme = scheme
+      @sequence = sequence
+      @handshake_timeout = handshake_timeout
+      @open_timeout = open_timeout
+      @max_streams = max_streams
+      @receive_limit = receive_limit
+      @session_receive_limit = session_receive_limit
+      @send_limit = send_limit
+      @logger = logger
+      @on_stream = on_stream
+      @on_idle = on_idle
+      @on_close = on_close
+      @on_padding = on_padding
+      @mutex = Mutex.new
+      @changed = ConditionVariable.new
+      # 分配唤醒 socket 前校验填充方案，避免配置错误留下待 GC 回收的 fd。
+      @padding_writer = Padding::Writer.new(scheme) unless server
+      @wake_reader, @wake_writer = Socket.pair(:UNIX, :STREAM, 0)
+      @operations = []
+      @transmissions = []
+      @streams = {}
+      @pending_open = {}
+      @queued_bytes = 0
+      @control_bytes = 0
+      @last_id = 0
+      @active_count = 0
+      @peer_version = 1
+      @closed = false
+      @stopping = false
+      @settings_received = false
+      @first_open = true
+      @ready = Completion.new
+      @diagnostic_errors = []
+      @decoder = Protocol::Decoder.new
+      begin
+        @thread = Thread.new { run }
+      rescue ThreadError
+        @wake_reader.close
+        @wake_writer.close
+        @socket.close unless @socket.closed?
+        raise
+      end
+      @thread.name = "anytls-session-#{sequence}"
+      @thread.report_on_exception = false
+    end
+
+    # 就绪仅表示本地 TLS 和认证记录处理已完成，
+    # 不证明对端已确认认证或连接出站目标。
+    def wait_ready(timeout: (@handshake_timeout * 2) + 1)
+      @ready.wait(Deadline.new(timeout))
+      self
+    end
+
+    def closed?
+      @mutex.synchronize { @closed || @stopping }
+    end
+
+    def peer_version
+      @mutex.synchronize { @peer_version }
+    end
+
+    def stream_count
+      @mutex.synchronize { @active_count }
+    end
+
+    def open_stream(address, timeout: @open_timeout)
+      submit(:open, address, deadline: Deadline.new(timeout), size: 512)
+    end
+
+    def write_stream(id, bytes, deadline:)
+      submit(:write, [id, bytes], deadline: deadline, size: bytes.bytesize + Protocol::HEADER_SIZE)
+    end
+
+    def close_stream(id)
+      submit(:close, id, deadline: Deadline.new(5), size: Protocol::HEADER_SIZE)
+    rescue Error, IOError
+      close
+      nil
+    end
+
+    def report_connected(id, error: nil)
+      submit(:report, [id, error], deadline: Deadline.new(5), size: 1024)
+    end
+
+    def heartbeat(timeout: 5)
+      submit(:heartbeat, nil, deadline: Deadline.new(timeout), size: Protocol::HEADER_SIZE)
+    end
+
+    def diagnostic_errors
+      @mutex.synchronize { @diagnostic_errors.dup.freeze }
+    end
+
+    def inspect
+      "#<#{self.class} sequence=#{sequence} role=#{@server ? 'server' : 'client'} closed=#{closed?}>"
+    end
+
+    def close(wait: true)
+      @mutex.synchronize do
+        @stopping = true
+        @changed.broadcast
+      end
+      wake
+      @thread.join if wait && Thread.current != @thread
+      nil
+    end
+
+    private
+
+    # 接收操作前，按编码字节数及最大填充预留容量。
+    # 等待队列容量会消耗调用者原有的单调时间预算。
+    def submit(kind, argument, deadline:, size:)
+      completion = Completion.new
+      cost = size + (@server ? 0 : @scheme.max_padding_bytes)
+      @mutex.synchronize do
+        raise BufferLimitExceeded, "write exceeds session queue capacity" if cost > @send_limit
+
+        deadline.wait(@changed, @mutex) while @queued_bytes + cost > @send_limit && !@stopping && !@closed
+        raise ClosedError, "session closed" if @stopping || @closed
+
+        deadline.check!
+        @queued_bytes += cost
+        @operations << { kind: kind, argument: argument, deadline: deadline, completion: completion, cost: cost }
+      end
+      wake
+      begin
+        completion.wait(deadline)
+      rescue TimeoutError
+        # 已接收的操作可能已影响对端；不得自动重放。
+        close(wait: false)
+        raise
+      end
+    end
+
+    def wake
+      @wake_writer.write_nonblock(".", exception: false)
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    def run
+      @transport = Transport::TLSConnection.new(@socket, config: @tls, server: @server, host: @host,
+                                                         cancel_io: @wake_reader, cancelled: -> { closed? })
+      @transport.handshake(timeout: @handshake_timeout)
+      @transport.authenticate(@password_digest, scheme: @scheme, timeout: @handshake_timeout)
+      @ready.finish(self)
+      event_loop
+    rescue StandardError => error
+      @failure = translate_error(error)
+      @ready.finish(error: @failure)
+      log(:debug, "AnyTLS session ended: #{@failure.class}")
+    ensure
+      finalize
+    end
+
+    def translate_error(error)
+      return error if error.is_a?(Error) || error.is_a?(ClosedError)
+
+      TransportError.new("TLS session failed (#{error.class})")
+    end
+
+    def event_loop
+      read_wait = :wait_readable
+      until closed?
+        process_operations
+        expire_opens
+        start_transmission unless @current
+        @current[:deadline].check! if @current
+
+        advance_transmission if @current && @transport.advance_write == :complete
+        break if @reject_after_flush && !@current && @transmissions.empty?
+
+        # SSL_write 返回 WANT_WRITE 后，必须先重试原写入，再进行其他 TLS 操作。
+        unless @current && @transport.write_wait == :wait_writable
+          result = @transport.read_nonblock(16_384)
+          if result.nil?
+            @decoder.finish!
+            raise TransportError, "peer closed TLS session"
+          elsif result.is_a?(String)
+            @decoder.feed(result).each { |frame| dispatch(frame) }
+            next
+          else
+            read_wait = result
+          end
+        end
+        next if !@current && !@transmissions.empty?
+
+        wait_for_work(read_wait)
+      end
+    end
+
+    def wait_for_work(read_wait)
+      readers = [@wake_reader]
+      writers = []
+      if @current && @transport.write_wait == :wait_writable
+        writers << @transport.io
+      else
+        readers << @transport.io if read_wait == :wait_readable || @transport.write_wait == :wait_readable
+        writers << @transport.io if read_wait == :wait_writable || (@current && @transport.write_wait.nil?)
+      end
+      budgets = [@current&.dig(:deadline)&.remaining, @heartbeat&.dig(:deadline)&.remaining,
+                 *@pending_open.values.map(&:remaining)].compact
+      timeout = budgets.min
+      ready = IO.select(readers, writers, nil, timeout)
+      if ready&.first&.include?(@wake_reader)
+        loop do
+          value = @wake_reader.read_nonblock(4096, exception: false)
+          break unless value.is_a?(String)
+        end
+      end
+    end
+
+    def process_operations
+      16.times do
+        operation = @mutex.synchronize { @operations.shift }
+        break unless operation
+
+        begin
+          operation[:deadline].check!
+          case operation[:kind]
+          when :open then open_operation(operation)
+          when :write then write_operation(operation)
+          when :close then close_operation(operation)
+          when :report then report_operation(operation)
+          when :heartbeat then heartbeat_operation(operation)
+          end
+        rescue StandardError => error
+          release_operation(operation, error: error)
+        ensure
+          operation.delete(:argument)
+        end
+      end
+    end
+
+    def open_operation(operation)
+      raise ProtocolError, "only a client can open streams" if @server
+      raise BufferLimitExceeded, "session stream limit reached" if @streams.size >= @max_streams
+      raise ClosedError, "stream identifiers exhausted" if @last_id == Protocol::MAX_STREAM_ID
+
+      @last_id += 1
+      stream = register_stream(@last_id)
+      bytes = String.new(encoding: Encoding::BINARY)
+      if @first_open
+        settings = { "v" => "2", "client" => "anytls-ruby/#{VERSION}", "padding-md5" => @scheme.md5 }
+        bytes << encode(Protocol::SETTINGS, 0, Protocol::Settings.encode(settings))
+        @first_open = false
+      end
+      bytes << encode(Protocol::SYN, stream.id)
+      bytes << encode(Protocol::PSH, stream.id, Protocol::SocksAddress.encode(operation[:argument]))
+      @pending_open[stream.id] = Deadline.new(@open_timeout) if @peer_version >= 2
+      queue_transmission(bytes, operation: operation, value: stream)
+    end
+
+    def write_operation(operation)
+      id, bytes = operation[:argument]
+      raise ClosedError, "stream closed" unless @streams.key?(id)
+
+      queue_transmission(encode(Protocol::PSH, id, bytes), operation: operation, value: bytes.bytesize)
+    end
+
+    def close_operation(operation)
+      id = operation[:argument]
+      stream = remove_stream(id)
+      if stream
+        stream.finish(ClosedError.new("stream closed"), local: true)
+        queue_transmission(encode(Protocol::FIN, id), operation: operation, idle: true)
+      else
+        release_operation(operation)
+      end
+    end
+
+    def report_operation(operation)
+      id, error = operation[:argument]
+      raise ClosedError, "stream closed" unless @streams.key?(id)
+
+      if @peer_version >= 2
+        message = error ? "outbound connection failed (#{error.class})" : "".b
+        queue_transmission(encode(Protocol::SYNACK, id, message), operation: operation)
+      else
+        release_operation(operation)
+      end
+    end
+
+    def heartbeat_operation(operation)
+      raise ProtocolError, "heartbeat requires negotiated v2" if @peer_version < 2
+      raise ProtocolError, "heartbeat already pending" if @heartbeat
+
+      @heartbeat = operation
+      queue_transmission(encode(Protocol::HEART_REQUEST, 0))
+    end
+
+    # 应用操作在完整发送前保留队列计费；对端控制帧响应
+    # 使用独立预算，因为没有应用提交者承担其容量。
+    def queue_transmission(bytes, operation: nil, value: nil, idle: false)
+      unless operation
+        @control_bytes += bytes.bytesize
+        raise BufferLimitExceeded, "control queue limit exceeded" if @control_bytes > 131_072
+      end
+      @transmissions << { bytes: bytes, bytesize: bytes.bytesize, operation: operation, value: value, idle: idle,
+                          deadline: operation ? operation[:deadline] : Deadline.new(5) }
+    end
+
+    def start_transmission
+      @current = @transmissions.shift
+      return unless @current
+
+      @chunks = @padding_writer ? @padding_writer.encode(@current[:bytes]) : [@current[:bytes]]
+      @current.delete(:bytes)
+      @transport.begin_write(@chunks.shift)
+    end
+
+    def advance_transmission
+      unless @chunks.empty?
+        @transport.begin_write(@chunks.shift)
+        return
+      end
+      transmission = @current
+      @current = nil
+      if transmission[:operation]
+        release_operation(transmission[:operation], value: transmission[:value])
+      else
+        @control_bytes -= transmission[:bytesize]
+      end
+      notify_idle if transmission[:idle]
+    end
+
+    def release_operation(operation, value: nil, error: nil)
+      @mutex.synchronize do
+        @queued_bytes -= operation[:cost]
+        @changed.broadcast
+      end
+      operation[:completion].finish(value, error: error)
+    end
+
+    def dispatch(frame)
+      return if @reject_after_flush
+
+      validate_frame!(frame)
+      case frame.command
+      when Protocol::WASTE then nil
+      when Protocol::SETTINGS then receive_settings(frame.payload)
+      when Protocol::SERVER_SETTINGS then receive_server_settings(frame.payload)
+      when Protocol::SYN then receive_syn(frame.stream_id)
+      when Protocol::PSH then receive_data(frame)
+      when Protocol::FIN then finish_remote(frame.stream_id)
+      when Protocol::SYNACK then receive_ack(frame)
+      when Protocol::UPDATE_PADDING_SCHEME then receive_padding(frame.payload)
+      when Protocol::ALERT then raise RemoteError, "server rejected session"
+      when Protocol::HEART_REQUEST then queue_transmission(encode(Protocol::HEART_RESPONSE, frame.stream_id))
+      when Protocol::HEART_RESPONSE
+        if @heartbeat
+          release_operation(@heartbeat)
+          @heartbeat = nil
+        end
+      end
+    end
+
+    def validate_frame!(frame)
+      command = frame.command
+      known = (Protocol::WASTE..Protocol::SERVER_SETTINGS).cover?(command)
+      raise ProtocolError, "unknown command has payload" if !known && !frame.payload.empty?
+      return unless known
+
+      empty_commands = [Protocol::SYN, Protocol::FIN, Protocol::HEART_REQUEST, Protocol::HEART_RESPONSE]
+      if empty_commands.include?(command) && !frame.payload.empty?
+        raise ProtocolError,
+              "command must have empty payload"
+      end
+
+      client_only = [Protocol::SETTINGS, Protocol::SYN]
+      server_only = [Protocol::SERVER_SETTINGS, Protocol::SYNACK, Protocol::ALERT, Protocol::UPDATE_PADDING_SCHEME]
+      if (@server && server_only.include?(command)) || (!@server && client_only.include?(command))
+        raise ProtocolError, "command received in invalid direction"
+      end
+      if [Protocol::SYN, Protocol::PSH, Protocol::FIN, Protocol::SYNACK].include?(command) && frame.stream_id.zero?
+        raise ProtocolError, "stream ID must be positive"
+      end
+      if [Protocol::SYNACK, Protocol::HEART_REQUEST, Protocol::HEART_RESPONSE].include?(command) && @peer_version < 2
+        raise ProtocolError, "command requires negotiated v2"
+      end
+    end
+
+    def parse_version(settings)
+      version = settings["v"]
+      raise ProtocolError, "invalid protocol version" unless version&.match?(/\A[1-9]\d{0,8}\z/)
+
+      [version.to_i, 2].min
+    end
+
+    def receive_settings(payload)
+      raise ProtocolError, "duplicate client settings" if @settings_received
+
+      settings = Protocol::Settings.decode(payload)
+      version = parse_version(settings)
+      digest = settings["padding-md5"]
+      raise ProtocolError, "missing padding digest" unless digest&.match?(/\A[0-9a-f]{32}\z/)
+
+      @settings_received = true
+      @mutex.synchronize { @peer_version = version }
+      queue_transmission(encode(Protocol::UPDATE_PADDING_SCHEME, 0, @scheme.raw)) if digest != @scheme.md5
+      if version >= 2
+        queue_transmission(encode(Protocol::SERVER_SETTINGS, 0,
+                                  Protocol::Settings.encode({ "v" => "2" })))
+      end
+    end
+
+    def receive_server_settings(payload)
+      raise ProtocolError, "duplicate server settings" if @server_settings_received
+
+      @server_settings_received = true
+      version = parse_version(Protocol::Settings.decode(payload))
+      @mutex.synchronize { @peer_version = version }
+      return unless version >= 2
+
+      @streams.each_value do |stream|
+        @pending_open[stream.id] = Deadline.new(@open_timeout) if stream.connection_status == :unconfirmed
+      end
+    end
+
+    def receive_syn(id)
+      unless @settings_received
+        queue_transmission(encode(Protocol::ALERT, 0, "client settings required"))
+        @reject_after_flush = true
+        return
+      end
+      raise ProtocolError, "non-monotonic stream ID" unless id > @last_id
+
+      @last_id = id
+      if @streams.size >= @max_streams
+        queue_transmission(encode(Protocol::SYNACK, id, "stream limit reached")) if @peer_version >= 2
+        queue_transmission(encode(Protocol::FIN, id))
+        return
+      end
+      stream = register_stream(id)
+      if @on_stream&.call(stream, self) == false
+        remove_stream(id)&.finish(BufferLimitExceeded.new("server stream limit reached"))
+        queue_transmission(encode(Protocol::SYNACK, id, "stream limit reached")) if @peer_version >= 2
+        queue_transmission(encode(Protocol::FIN, id))
+      end
+    end
+
+    # 所有者线程不得等待消费者；超出预算时拒绝受影响的流，
+    # 保留其他流及其已缓冲字节。
+    def receive_data(frame)
+      stream = @streams[frame.stream_id]
+      return unless stream
+
+      if @streams.values.sum(&:buffered_bytes) + frame.payload.bytesize > @session_receive_limit
+        raise BufferLimitExceeded, "session receive buffer limit exceeded"
+      end
+
+      stream.receive(frame.payload)
+    rescue BufferLimitExceeded => error
+      remove_stream(frame.stream_id)&.finish(error)
+      queue_transmission(encode(Protocol::FIN, frame.stream_id), idle: true)
+    end
+
+    def receive_ack(frame)
+      @pending_open.delete(frame.stream_id)
+      stream = @streams[frame.stream_id]
+      return unless stream
+
+      if frame.payload.empty?
+        stream.confirm
+      else
+        remove_stream(frame.stream_id)&.finish(RemoteError.new("remote outbound connection failed"))
+        queue_transmission(encode(Protocol::FIN, frame.stream_id), idle: true)
+      end
+    end
+
+    # 发布校验后的快照，供客户端未来的会话使用；当前会话的写入器
+    # 继续使用原方案和包计数。
+    def receive_padding(payload)
+      scheme = Padding::Scheme.new(payload)
+      @on_padding&.call(scheme)
+    rescue ConfigurationError => error
+      log(:warn, "ignored invalid remote padding scheme (#{error.class})")
+    end
+
+    def finish_remote(id)
+      stream = remove_stream(id)
+      stream&.finish
+      notify_idle if stream
+    end
+
+    def register_stream(id)
+      stream = Stream.new(self, id, receive_limit: @receive_limit)
+      @streams[id] = stream
+      @mutex.synchronize { @active_count = @streams.size }
+      stream
+    end
+
+    def remove_stream(id)
+      @pending_open.delete(id)
+      stream = @streams.delete(id)
+      @mutex.synchronize { @active_count = @streams.size }
+      stream
+    end
+
+    def notify_idle
+      @on_idle&.call(self) if @streams.empty? && !closed?
+    end
+
+    def expire_opens
+      @pending_open.each_value(&:check!)
+      @heartbeat&.fetch(:deadline)&.check!
+      @stopping = true if @reject_after_flush && @transmissions.empty? && !@current
+    end
+
+    def encode(command, id, payload = "".b)
+      Protocol::Frame.new(command: command, stream_id: id, payload: payload).encode
+    end
+
+    def log(level, message)
+      error = Log.emit(@logger, level, message)
+      return unless error
+
+      @mutex.synchronize { @diagnostic_errors << error if @diagnostic_errors.size < 16 }
+    end
+
+    def finalize
+      failure = @failure || ClosedError.new("session closed")
+      @transport&.close
+      @socket.close unless @socket.closed?
+      @streams.each_value { |stream| stream.finish(failure) }
+      @streams.clear
+      operations = @mutex.synchronize do
+        @closed = @stopping = true
+        @active_count = 0
+        queued = @operations
+        @operations = []
+        @changed.broadcast
+        queued
+      end
+      operations += @transmissions.filter_map { |entry| entry[:operation] }
+      operations << @current[:operation] if @current && @current[:operation]
+      operations << @heartbeat if @heartbeat
+      operations.each { |operation| operation[:completion].finish(error: failure) }
+      @ready.finish(error: failure)
+      @wake_reader.close
+      @wake_writer.close
+      @on_close&.call(self)
+    end
+  end
+end