mnet 0.1.0

data/lib/mnet.rb

@@ -0,0 +1,1130 @@
+# frozen_string_literal: true
+
+# Mnet -- a small reliable transport over UDP with connection migration.
+#
+# The idea (inspired by mosh's State Synchronization Protocol, which is what
+# actually gives you the "switch wifi and keep the session" behaviour people
+# attribute to tmux) is:
+#
+#   * a session is identified by a 128-bit random token, NOT by the
+#     (source ip, source port) tuple the way TCP does.
+#   * every datagram carries that token, so the peer can simply update its
+#     record of "where this session now lives" when a packet arrives from a
+#     new address. This is what makes roaming/migration transparent.
+#   * reliability (ordering + retransmit + flow control) is layered on top,
+#     because plain UDP gives you none of that.
+#
+# Design goals here: many concurrent sessions multiplexed over a *single*
+# UDP socket, one reader thread + one timer thread shared by all sessions
+# (not thread-per-connection), blocking read/write with backpressure.
+
+require "socket"
+require "securerandom"
+require "monitor"
+require "openssl"
+require "mnet/version"
+require "kcp"
+
+module Mnet
+  MAGIC          = "MNET".b
+  MAGIC_LEN      = 4
+  SESSION_ID_LEN = 16
+
+  # Conservative MTU for mobile networks / VPN tunnels (mosh uses 1280).
+  IP_MTU       = 1280
+  # IP(20) + UDP(8) + our header + GCM tag(16) leaves ~1190 for a segment.
+  DEFAULT_MSS  = 1200
+
+  # RTO bounds (mosh: MIN_RTO = 50ms, MAX_RTO = 1000ms).
+  MIN_RTO = 0.05
+  MAX_RTO = 1.0
+
+  # How long to keep a superseded (hopped-away-from) socket alive to catch
+  # delayed packets (mosh: MAX_OLD_SOCKET_AGE = 60000ms).
+  MAX_OLD_SOCKET_AGE = 60.0
+
+  # Message types (mirrors the enum-message-types pattern from tmux-protocol.h).
+  TYPE_SYN    = 0x01
+  TYPE_SYNACK = 0x02
+  TYPE_DATA   = 0x03
+  TYPE_ACK    = 0x04
+  TYPE_FIN    = 0x05
+  TYPE_PING   = 0x06
+  TYPE_PONG   = 0x07
+
+  FLAG_NONE    = 0x00
+  FLAG_MIGRATE = 0x01
+  FLAG_KCP     = 0x02 # session uses the KCP (C) engine instead of the Ruby ARQ
+
+  HEADER_LEN   = MAGIC_LEN + SESSION_ID_LEN + 8 + 8 + 1 + 1 + 4
+
+  MAX_RETRIES  = 10
+
+  TYPES = {
+    TYPE_SYN => "SYN", TYPE_SYNACK => "SYNACK", TYPE_DATA => "DATA",
+    TYPE_ACK => "ACK", TYPE_FIN => "FIN", TYPE_PING => "PING",
+    TYPE_PONG => "PONG"
+  }.freeze
+
+  Packet = Struct.new(:session_id, :seq, :ack, :type, :flags, :window, :payload)
+
+  module_function
+
+  def pack(session_id, seq, ack, type, flags, window, payload = "".b)
+    [MAGIC, session_id, seq, ack, type, flags, window, payload]
+      .pack("a4a16Q>Q>CCNa*")
+  end
+
+  def unpack(data)
+    return nil if data.bytesize < HEADER_LEN
+    magic, sid, seq, ack, type, flags, window = data.unpack("a4a16Q>Q>CCN")
+    return nil unless magic == MAGIC
+    Packet.new(sid, seq, ack, type, flags, window,
+               data.byteslice(HEADER_LEN, data.bytesize - HEADER_LEN) || "".b)
+  end
+
+  def type_name(type)
+    TYPES.fetch(type, "UNKNOWN(#{type})")
+  end
+
+  def addr_pair(addr)
+    [addr[3], addr[1]]
+  end
+
+  def fmt(addr)
+    "#{addr[0]}:#{addr[1]}"
+  end
+
+  def now
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  # Session id is derived from the shared session key (mosh-style), so the id
+  # identifies the key and vice versa; without a key it is just random.
+  def session_id_from_key(key)
+    OpenSSL::Digest::SHA256.digest(key)[0, SESSION_ID_LEN]
+  end
+
+  # A connected stream socket pair, portable across Windows/Linux/macOS.
+  # Prefers a UNIX socketpair; falls back to a loopback TCP pair where AF_UNIX
+  # socketpair is unavailable (Windows).
+  def socket_pair
+    Socket.pair(:UNIX, :STREAM, 0)
+  rescue Errno::EAFNOSUPPORT, Errno::EOPNOTSUPP, Errno::EPROTONOSUPPORT, Errno::ENOTSUP, NotImplementedError
+    server = TCPServer.new("127.0.0.1", 0)
+    port   = server.addr[1]
+    client = TCPSocket.new("127.0.0.1", port)
+    accepted = server.accept
+    server.close
+    [accepted, client]
+  end
+
+  # One segment in flight on the send side.
+  Frame = Struct.new(:seq, :len, :payload, :sent_at, :retries)
+
+  # IO-compatible interface so a Session can be passed directly to
+  # OpenSSL::SSL::SSLSocket -- this removes the socketpair bridge (and its two
+  # thread hops per message), which is the main Ruby-side throughput cost.
+  module SessionIO
+    def to_io
+      self
+    end
+
+    def sync
+      true
+    end
+
+    def sync=(_value)
+    end
+
+    # Hook overridden by KcpSession to pull decoded bytes out of the engine.
+    def pump_recv
+    end
+
+    # Hook overridden by Session to advertise a reopened receive window.
+    def after_read
+    end
+
+    def read(length = nil, outbuf = nil)
+      @m.synchronize do
+        loop do
+          pump_recv
+          unless @recv_buf.empty?
+            n = length.nil? ? @recv_buf.bytesize : [length, @recv_buf.bytesize].min
+            out = @recv_buf.byteslice(0, n)
+            @recv_buf = @recv_buf.byteslice(n, @recv_buf.bytesize - n) || "".b
+            after_read
+            return outbuf ? outbuf.replace(out) : out
+          end
+          return nil if @eof || @closed
+          @cv.wait
+        end
+      end
+    end
+
+    def readpartial(maxlen, outbuf = nil)
+      raise ArgumentError, "non-positive maxlen" if maxlen <= 0
+      @m.synchronize do
+        loop do
+          pump_recv
+          unless @recv_buf.empty?
+            n = [maxlen, @recv_buf.bytesize].min
+            out = @recv_buf.byteslice(0, n)
+            @recv_buf = @recv_buf.byteslice(n, @recv_buf.bytesize - n) || "".b
+            after_read
+            return outbuf ? outbuf.replace(out) : out
+          end
+          raise EOFError, "end of file reached" if @eof || @closed
+          @cv.wait
+        end
+      end
+    end
+
+    def read_nonblock(maxlen, outbuf = nil, exception: true)
+      @m.synchronize do
+        pump_recv
+        unless @recv_buf.empty?
+          n = [maxlen, @recv_buf.bytesize].min
+          out = @recv_buf.byteslice(0, n)
+          @recv_buf = @recv_buf.byteslice(n, @recv_buf.bytesize - n) || "".b
+          after_read
+          return outbuf ? outbuf.replace(out) : out
+        end
+        return nil if @eof || @closed
+        raise IO::WaitReadable if exception
+        :wait_readable
+      end
+    end
+
+    def write_nonblock(data, exception: true)
+      write(data)
+    end
+
+    def sysread(maxlen, outbuf = nil)
+      readpartial(maxlen, outbuf)
+    end
+
+    def syswrite(data)
+      write(data)
+    end
+
+    def wait_readable(timeout = nil)
+      @m.synchronize do
+        pump_recv
+        return true unless @recv_buf.empty?
+        return nil if @eof || @closed
+        if timeout
+          @cv.wait(timeout)
+        else
+          @cv.wait
+        end
+        pump_recv # data may have arrived via the engine while we waited
+        !@recv_buf.empty?
+      end
+    end
+
+    def wait_writable(_timeout = nil)
+      true
+    end
+
+    # Close the session-side end of the bridge so the @up pump thread gets EOF.
+    def close_bridge
+      return unless @bridge_transport
+      @bridge_transport.shutdown rescue nil
+      @bridge_transport.close rescue nil
+    end
+
+    # A real kernel IO (socketpair bridge) wrapping this session, for the few
+    # consumers that require a genuine File/IO -- notably OpenSSL::SSL::SSLSocket
+    # (its C init does `Check_Type(io, T_FILE)`). Only used when needed; the
+    # session itself is already IO-compatible via the methods above.
+    def bridge
+      return @bridge_io if @bridge_io
+
+      app, transport = Mnet.socket_pair
+      @bridge_transport = transport
+      [app, transport].each do |s|
+        s.sync = true
+        s.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1) rescue nil
+      end
+
+      @down = Thread.new do
+        begin
+          while (data = read)
+            transport.write(data)
+          end
+        rescue IOError, EOFError, Errno::ECONNRESET, Errno::EPIPE
+        ensure
+          transport.close_write rescue nil
+          close rescue nil
+        end
+      end
+
+      @up = Thread.new do
+        begin
+          while (data = transport.readpartial(65_536))
+            write(data)
+          end
+        rescue EOFError, IOError, Errno::ECONNRESET, Errno::EPIPE
+        ensure
+          close rescue nil
+        end
+      end
+
+      @bridge_io = app
+    end
+  end
+
+  class Session
+    include SessionIO
+
+    attr_reader :id, :state, :peer_addr
+
+    def initialize(endpoint, id, role:, peer_addr: nil, key: nil, logger: nil, **opts)
+      @endpoint = endpoint
+      @id       = id
+      @role     = role
+      @peer_addr = peer_addr
+      @logger   = logger
+      @key      = key  # optional 32-byte session key (AES-256-GCM); nil = plaintext
+
+      @m  = Monitor.new
+      @cv = @m.new_cond
+
+      @mss          = opts.fetch(:mss, Mnet::DEFAULT_MSS)
+      @recv_cap     = opts.fetch(:recv_capacity, 256 * 1024)
+      @max_out      = opts.fetch(:max_outstanding, 4 * 1024 * 1024)
+      @rto          = opts.fetch(:rto, 0.3)
+      @ping_after   = opts.fetch(:ping_after, 15.0)
+      @idle_timeout = opts.fetch(:idle_timeout, 60.0)
+      @syn_retry    = opts.fetch(:syn_retry, 0.25)
+
+      @state = role == :client ? :connecting : :established
+
+      # Send side (byte-offset sequence numbers, like TCP).
+      @next_seq       = 0
+      @send_buf       = "".b          # bytes queued but not yet transmitted
+      @inflight       = []            # ordered list of Frame
+      @inflight_bytes = 0
+      @outstanding    = 0             # queued + inflight bytes (backpressure)
+
+      @peer_window = 0                # last receive window advertised by peer
+
+      # RTT estimation (RFC 6298 SRTT/RTTVAR), driving RTO.
+      @srtt    = nil
+      @rttvar  = nil
+
+      # Receive side.
+      @next_exp    = 0                # next expected byte offset (cumulative ack)
+      @recv_buf    = "".b             # delivered, ordered, not yet read by app
+      @reasm       = {}               # seq => payload (out of order)
+      @reasm_bytes = 0
+      @last_window = 0
+
+      # Liveness.
+      @last_recv = Mnet.now
+      @last_send = Mnet.now
+
+      @eof    = false
+      @closed = false
+      @bridge_io = nil
+    end
+
+    def established?
+      @state == :established
+    end
+
+    def closed?
+      @closed
+    end
+
+    def eof?
+      @eof
+    end
+
+    # ---- Application API -------------------------------------------------
+
+    def write(data)
+      data = data.to_s.b
+      return 0 if data.empty?
+
+      @m.synchronize do
+        @cv.wait_while { !@closed && !@eof && (@outstanding >= @max_out || unsendable?) }
+        return 0 if @closed || @eof
+        @send_buf << data
+        @outstanding += data.bytesize
+      end
+      pump
+      data.bytesize
+    end
+
+    def after_read
+      @cv.broadcast
+      maybe_advertise_window
+    end
+
+    def close
+      @m.synchronize do
+        return if @closed
+        send_packet(Mnet::TYPE_FIN, 0, @next_exp) if @state != :connecting
+        @closed = true
+        @eof    = true
+        @cv.broadcast
+        close_bridge
+      end
+      @endpoint.remove_session(@id)
+    end
+
+    # ---- Internal: called by Endpoint threads ----------------------------
+
+    def handle_packet(pkt, addr)
+      @m.synchronize do
+        return if @closed
+        @last_recv = Mnet.now
+        update_peer(addr)
+
+        if @key
+          header = Mnet.pack(pkt.session_id, pkt.seq, pkt.ack, pkt.type, pkt.flags, pkt.window, "")
+          pkt.payload = decrypt_payload(header, pkt.payload)
+          return if pkt.payload.nil? # failed authentication / wrong key
+        end
+
+        case pkt.type
+        when Mnet::TYPE_SYN    then on_syn(pkt)
+        when Mnet::TYPE_SYNACK then on_synack(pkt)
+        when Mnet::TYPE_DATA   then on_data(pkt)
+        when Mnet::TYPE_ACK    then apply_ack(pkt.ack, pkt.window)
+        when Mnet::TYPE_FIN    then on_fin
+        when Mnet::TYPE_PING   then send_packet(Mnet::TYPE_PONG, 0, @next_exp)
+        when Mnet::TYPE_PONG   then nil
+        end
+      end
+    end
+
+    def tick(now)
+      @m.synchronize do
+        return if @closed
+
+        if @state == :connecting
+          # Handshake is not yet reliable: keep retrying SYN until SYNACK.
+          send_packet(Mnet::TYPE_SYN, 0, 0) if now - @last_send >= @syn_retry
+          return
+        end
+
+        if !@inflight.empty?
+          f = @inflight.first
+          if now - f.sent_at >= @rto
+            if f.retries >= Mnet::MAX_RETRIES
+              log("giving up after #{f.retries} retries")
+              teardown
+              return
+            end
+            @rto      = [@rto * 2, Mnet::MAX_RTO].min
+            f.sent_at = now
+            f.retries += 1
+            send_packet(Mnet::TYPE_DATA, f.seq, @next_exp, f.payload)
+          end
+        elsif now - @last_send >= @ping_after
+          send_packet(Mnet::TYPE_PING, 0, @next_exp)
+        end
+
+        teardown if now - @last_recv >= @idle_timeout
+
+        pump unless @send_buf.empty?
+      end
+    end
+
+    def send_syn
+      @m.synchronize { send_packet(Mnet::TYPE_SYN, 0, 0) }
+    end
+
+    def wait_established(timeout)
+      @m.synchronize { @cv.wait(timeout) if @state == :connecting }
+      raise "connect timed out" unless @state == :established
+      self
+    end
+
+    def reanchor
+      @m.synchronize do
+        send_packet(Mnet::TYPE_PING, 0, @next_exp) if @state == :established
+      end
+    end
+
+    private
+
+    def pump
+      @m.synchronize do
+        return if @state != :established || @closed
+
+        loop do
+          break if @send_buf.empty?
+          limit = @peer_window
+          break if @inflight_bytes >= limit
+          size = [@mss, @send_buf.bytesize, limit - @inflight_bytes].min
+          break if size <= 0
+
+          payload = @send_buf.byteslice(0, size)
+          seq     = @next_seq
+
+          break unless send_packet(Mnet::TYPE_DATA, seq, @next_exp, payload)
+
+          @send_buf = @send_buf.byteslice(size, @send_buf.bytesize - size) || "".b
+          @next_seq += size
+          @inflight << Mnet::Frame.new(seq, size, payload, Mnet.now, 0)
+          @inflight_bytes += size
+        end
+      end
+    end
+
+    def unsendable?
+      !@send_buf.empty? && @inflight_bytes >= @peer_window
+    end
+
+    def apply_ack(ack, window)
+      @peer_window = window if window
+      return if ack <= 0
+
+      before = @inflight_bytes
+      acked  = 0
+      rtt_sample_at = nil
+      @inflight.reject! do |f|
+        next false unless f.seq + f.len <= ack
+        acked += f.len
+        @inflight_bytes -= f.len
+        @outstanding    -= f.len
+        rtt_sample_at ||= f.sent_at
+        true
+      end
+
+      return unless @inflight_bytes < before
+
+      update_rtt(Mnet.now - rtt_sample_at) if rtt_sample_at
+      @cv.broadcast
+      pump
+    end
+
+    # RFC 6298 SRTT/RTTVAR -> RTO (mosh-style: RTT-driven, no congestion window).
+    def update_rtt(sample)
+      if @srtt.nil?
+        @srtt   = sample
+        @rttvar = sample / 2.0
+      else
+        @rttvar = 0.75 * @rttvar + 0.25 * (@srtt - sample).abs
+        @srtt   = 0.875 * @srtt + 0.125 * sample
+      end
+      @rto = @srtt + 4.0 * @rttvar
+      @rto = Mnet::MIN_RTO if @rto < Mnet::MIN_RTO
+      @rto = Mnet::MAX_RTO if @rto > Mnet::MAX_RTO
+    end
+
+    def on_syn(pkt)
+      @peer_window = pkt.window
+      send_packet(Mnet::TYPE_SYNACK, 0, @next_exp)
+      @state = :established
+    end
+
+    def on_synack(pkt)
+      @peer_window = pkt.window
+      @state = :established
+      @cv.broadcast
+      pump
+    end
+
+    def on_data(pkt)
+      apply_ack(pkt.ack, pkt.window) if pkt.ack > 0
+
+      data = pkt.payload
+      return if data.empty?
+
+      seq = pkt.seq
+      if seq == @next_exp
+        @recv_buf << data
+        @next_exp += data.bytesize
+        while (seg = @reasm.delete(@next_exp))
+          @recv_buf << seg
+          @next_exp += seg.bytesize
+          @reasm_bytes -= seg.bytesize
+        end
+        @cv.broadcast
+      elsif seq > @next_exp
+        if (seq - @next_exp) <= @recv_cap && !@reasm.key?(seq)
+          @reasm[seq] = data
+          @reasm_bytes += data.bytesize
+        end
+      end
+      send_packet(Mnet::TYPE_ACK, 0, @next_exp)
+    end
+
+    def on_fin
+      @eof = true
+      send_packet(Mnet::TYPE_FIN, 0, @next_exp)
+      @cv.broadcast
+    end
+
+    def maybe_advertise_window
+      w = recv_window
+      if @state == :established && @peer_addr && w >= @last_window + @mss
+        send_packet(Mnet::TYPE_ACK, 0, @next_exp)
+        @last_window = w
+      end
+    end
+
+    def recv_window
+      [@recv_cap - (@recv_buf.bytesize + @reasm_bytes), 0].max
+    end
+
+    def send_packet(type, seq, ack, payload = "".b, flags = Mnet::FLAG_NONE)
+      if @key
+        header = Mnet.pack(@id, seq, ack, type, flags, recv_window, "")
+        packet = header + encrypt_payload(header, payload)
+      else
+        packet = Mnet.pack(@id, seq, ack, type, flags, recv_window, payload)
+      end
+      sent = @endpoint.send_raw(packet, *@peer_addr)
+      @last_send = Mnet.now if sent
+      sent
+    end
+
+    # AES-256-GCM payload encryption with the cleartext header as AAD, so both
+    # payload confidentiality/integrity and header integrity are enforced.
+    # Returns nil if authenticated decryption fails (drop the packet).
+    def encrypt_payload(header, payload)
+      return payload unless @key
+      nonce = SecureRandom.random_bytes(12)
+      cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      cipher.encrypt
+      cipher.key = @key
+      cipher.iv = nonce
+      cipher.auth_data = header
+      ciphertext = cipher.update(payload) + cipher.final
+      nonce + ciphertext + cipher.auth_tag
+    end
+
+    def decrypt_payload(header, blob)
+      return blob unless @key
+      return nil if blob.bytesize < 28 # 12-byte nonce + 16-byte tag minimum
+
+      nonce = blob.byteslice(0, 12)
+      ct    = blob.byteslice(12, blob.bytesize - 12)
+      return nil if ct.bytesize < 16
+
+      cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      cipher.decrypt
+      cipher.key = @key
+      cipher.iv = nonce
+      cipher.auth_tag = ct.byteslice(ct.bytesize - 16, 16)
+      cipher.auth_data = header
+      cipher.update(ct.byteslice(0, ct.bytesize - 16)) + cipher.final
+    rescue OpenSSL::Cipher::CipherError, OpenSSL::OpenSSLError
+      nil
+    end
+
+    def update_peer(addr)
+      pair = Mnet.addr_pair(addr)
+      if @peer_addr.nil?
+        @peer_addr = pair
+      elsif @peer_addr[0] != pair[0] || @peer_addr[1] != pair[1]
+        log("migrated #{Mnet.fmt(@peer_addr)} -> #{Mnet.fmt(pair)}")
+        @peer_addr = pair
+      end
+    end
+
+    def teardown
+      @closed = true
+      @eof    = true
+      @cv.broadcast
+      @endpoint.remove_session(@id)
+    end
+
+    def log(msg)
+      @logger&.call("[#{short_id}] #{msg}")
+    end
+
+    def short_id
+      @id.unpack1("H*")[0, 8]
+    end
+  end
+
+  # Session with the reliable byte stream provided by the KCP (C) engine
+  # instead of the pure-Ruby ARQ. The migration layer (session token, peer
+  # address update, control handshake, socketpair bridge, optional AES-GCM)
+  # is identical to Session.
+  class KcpSession
+    include SessionIO
+
+    attr_reader :id, :state, :peer_addr
+
+    def initialize(endpoint, id, role:, peer_addr: nil, key: nil, logger: nil, **opts)
+      @endpoint = endpoint
+      @id       = id
+      @role     = role
+      @peer_addr = peer_addr
+      @key      = key
+      @logger   = logger
+
+      @conv   = id.unpack1("N") # KCP conv derived from the session id
+      @engine = Kcp::Engine.new(@conv)
+
+      @m  = Monitor.new
+      @cv = @m.new_cond
+
+      @ping_after   = opts.fetch(:ping_after, 15.0)
+      @idle_timeout = opts.fetch(:idle_timeout, 60.0)
+      @syn_retry    = opts.fetch(:syn_retry, 0.25)
+
+      @state = role == :client ? :connecting : :established
+
+      @recv_buf = "".b
+      @last_recv = Mnet.now
+      @last_send = Mnet.now
+      @eof       = false
+      @closed    = false
+      @bridge_io = nil
+    end
+
+    def established?
+      @state == :established
+    end
+
+    def closed?
+      @closed
+    end
+
+    def eof?
+      @eof
+    end
+
+    def write(data)
+      data = data.to_s.b
+      return 0 if data.empty?
+
+      @m.synchronize do
+        return 0 if @closed || @eof
+        @engine.send(data)
+        pump_output
+      end
+      # 窗口满（有积压）时让出 GVL，避免写线程紧循环饿死处理 ACK 的传输线程。
+      Thread.pass if @engine.waitsnd > 0
+      data.bytesize
+    end
+
+    def pump_recv
+      return if @closed # engine is freed in close
+      while (chunk = @engine.recv)
+        @recv_buf << chunk
+      end
+    end
+
+    def close
+      @m.synchronize do
+        return if @closed
+        send_control(Mnet::TYPE_FIN) if @state != :connecting
+        @closed = true
+        @eof    = true
+        @engine.close # free the C engine while holding @m (no race with read)
+        @cv.broadcast
+        close_bridge
+      end
+      @endpoint.remove_session(@id)
+    end
+
+    def handle_packet(pkt, addr)
+      @m.synchronize do
+        return if @closed
+        @last_recv = Mnet.now
+        update_peer(addr)
+
+        case pkt.type
+        when Mnet::TYPE_SYN    then on_syn(pkt)
+        when Mnet::TYPE_SYNACK then on_synack
+        when Mnet::TYPE_DATA   then on_data(pkt)
+        when Mnet::TYPE_PING   then send_control(Mnet::TYPE_PONG)
+        when Mnet::TYPE_PONG   then nil
+        when Mnet::TYPE_FIN    then on_fin
+        end
+      end
+    end
+
+    def tick(now)
+      @m.synchronize do
+        return if @closed
+        @engine.update(now_ms) # timer-based retransmit
+        pump_output
+
+        if @state == :connecting
+          send_syn if now - @last_send >= @syn_retry
+        elsif now - @last_send >= @ping_after
+          send_control(Mnet::TYPE_PING)
+        end
+
+        teardown if now - @last_recv >= @idle_timeout
+      end
+    end
+
+    def send_syn
+      @m.synchronize { send_control(Mnet::TYPE_SYN) }
+    end
+
+    def wait_established(timeout)
+      @m.synchronize { @cv.wait(timeout) if @state == :connecting }
+      raise "connect timed out" unless @state == :established
+      self
+    end
+
+    def reanchor
+      @m.synchronize do
+        send_control(Mnet::TYPE_PING) if @state == :established
+      end
+    end
+
+    private
+
+    def now_ms
+      (Mnet.now * 1000).to_i & 0xffffffff
+    end
+
+    def pump_output
+      @engine.flush
+      while (pkt = @engine.output)
+        send_data_packet(pkt)
+      end
+    end
+
+    def send_data_packet(kcp_payload)
+      header = Mnet.pack(@id, 0, 0, Mnet::TYPE_DATA, Mnet::FLAG_KCP, 0, "")
+      body   = @key ? encrypt_payload(header, kcp_payload) : kcp_payload
+      @endpoint.send_raw(header + body, *@peer_addr)
+      @last_send = Mnet.now
+    end
+
+    def send_control(type)
+      header = Mnet.pack(@id, 0, 0, type, Mnet::FLAG_KCP, 0, "")
+      body   = @key ? encrypt_payload(header, "") : ""
+      @endpoint.send_raw(header + body, *@peer_addr)
+      @last_send = Mnet.now
+    end
+
+    def on_syn(pkt)
+      @state = :established
+      send_control(Mnet::TYPE_SYNACK)
+    end
+
+    def on_synack
+      @state = :established
+      @cv.broadcast
+    end
+
+    def on_data(pkt)
+      header  = Mnet.pack(pkt.session_id, pkt.seq, pkt.ack, pkt.type, pkt.flags, pkt.window, "")
+      payload = @key ? decrypt_payload(header, pkt.payload) : pkt.payload
+      return if payload.nil?
+      @engine.input(payload)
+      pump_output
+      @cv.broadcast
+    end
+
+    def on_fin
+      @eof = true
+      send_control(Mnet::TYPE_FIN)
+      @cv.broadcast
+    end
+
+    def encrypt_payload(header, payload)
+      return payload unless @key
+      nonce = SecureRandom.random_bytes(12)
+      cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      cipher.encrypt
+      cipher.key = @key
+      cipher.iv = nonce
+      cipher.auth_data = header
+      nonce + cipher.update(payload) + cipher.final + cipher.auth_tag
+    end
+
+    def decrypt_payload(header, blob)
+      return blob unless @key
+      return nil if blob.bytesize < 28
+
+      nonce = blob.byteslice(0, 12)
+      ct    = blob.byteslice(12, blob.bytesize - 12)
+      return nil if ct.bytesize < 16
+
+      cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      cipher.decrypt
+      cipher.key = @key
+      cipher.iv = nonce
+      cipher.auth_tag = ct.byteslice(ct.bytesize - 16, 16)
+      cipher.auth_data = header
+      cipher.update(ct.byteslice(0, ct.bytesize - 16)) + cipher.final
+    rescue OpenSSL::Cipher::CipherError, OpenSSL::OpenSSLError
+      nil
+    end
+
+    def update_peer(addr)
+      pair = Mnet.addr_pair(addr)
+      if @peer_addr.nil?
+        @peer_addr = pair
+      elsif @peer_addr[0] != pair[0] || @peer_addr[1] != pair[1]
+        log("migrated #{Mnet.fmt(@peer_addr)} -> #{Mnet.fmt(pair)}")
+        @peer_addr = pair
+      end
+    end
+
+    def teardown
+      @closed = true
+      @eof    = true
+      @cv.broadcast
+      @endpoint.remove_session(@id)
+    end
+
+    def log(msg)
+      @logger&.call("[#{short_id}] #{msg}")
+    end
+
+    def short_id
+      @id.unpack1("H*")[0, 8]
+    end
+  end
+
+  class Endpoint
+    TICK_INTERVAL = 0.05
+    attr_reader :socket
+
+    def initialize(logger: nil, keys: nil, **opts)
+      @opts   = opts
+      @logger = logger
+      @socks  = []            # [socket, created_at] pairs; newest last
+      @send_mutex     = Mutex.new
+      @sessions       = {}
+      @sessions_mutex = Mutex.new
+      @accept         = Queue.new
+      @running        = false
+      @bound          = false
+
+      # Receive window (flow control): capped dynamically to the kernel's
+      # actual socket buffer size (Linux clamps via net.core.rmem_max).
+      @recv_cap = opts.fetch(:recv_capacity, 256 * 1024)
+
+      # Pre-shared session keys (optional): id -> key, derived like mosh.
+      @key_by_id = {}
+      (keys || []).each { |k| @key_by_id[Mnet.session_id_from_key(k)] = k }
+    end
+
+    def listen(host = "0.0.0.0", port = 0)
+      sock = UDPSocket.new
+      configure_socket(sock)
+      sock.bind(host, port)
+      @socks << [sock, Mnet.now]
+      @bound = true
+      start
+      self
+    end
+
+    def dial(host, port, timeout: 5, key: nil, proto: :mnet)
+      ensure_bound
+      id = key ? Mnet.session_id_from_key(key) : SecureRandom.random_bytes(Mnet::SESSION_ID_LEN)
+      klass = proto == :kcp ? KcpSession : Session
+      sess = klass.new(self, id, role: :client, peer_addr: [host, port],
+                              key: key, logger: @logger, **@opts.merge(recv_capacity: @recv_cap))
+      register(sess)
+      begin
+        sess.send_syn
+        sess.wait_established(timeout)
+      rescue
+        remove_session(id)
+        raise
+      end
+    end
+
+    def accept
+      @accept.pop
+    end
+
+    def local_addr
+      @socks.last[0].addr
+    end
+
+    def close
+      @running = false
+      @socks.each { |s, _| s.close rescue nil }
+    end
+
+    # mosh-style port hop: open a fresh socket (new source address) and switch
+    # to it, keeping the old socket alive briefly to catch delayed packets.
+    # In real life you do NOT need to call this -- bind the client socket to
+    # 0.0.0.0 and the OS re-picks the source address when the route changes;
+    # this is the explicit fallback for testing/deterministic roaming.
+    def hop(local_host = "0.0.0.0")
+      new_sock = nil
+      @send_mutex.synchronize do
+        new_sock = UDPSocket.new
+        configure_socket(new_sock)
+        new_sock.bind(local_host, 0)
+        @socks << [new_sock, Mnet.now]
+      end
+      prune_sockets
+      @sessions_mutex.synchronize { @sessions.each_value(&:reanchor) }
+      new_sock
+    end
+
+    alias rebind hop
+
+    def send_raw(data, ip, port)
+      sock = @socks.last[0]
+      @send_mutex.synchronize do
+        sock.send(data, Socket::MSG_DONTWAIT, ip, port)
+        true
+      rescue IO::EAGAINWaitWritable, Errno::EAGAIN, Errno::EWOULDBLOCK, Errno::ENOBUFS
+        false
+      rescue IOError, Errno::EBADF, Errno::ECONNRESET, Errno::ECONNREFUSED
+        false
+      end
+    end
+
+    def remove_session(id)
+      @sessions_mutex.synchronize { @sessions.delete(id) }
+    end
+
+    private
+
+    def prune_sockets
+      cutoff = Mnet.now - Mnet::MAX_OLD_SOCKET_AGE
+      @send_mutex.synchronize do
+        @socks.reject! do |sock, created|
+          old = created < cutoff && sock != @socks.last[0]
+          sock.close rescue nil if old
+          old
+        end
+      end
+    end
+
+    def configure_socket(sock)
+      sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEADDR, true)
+      # Request buffers sized for the receive window. Linux clamps these to
+      # net.core.rmem_max/wmem_max, so read back the real value and cap the
+      # flow-control window to what the kernel can actually buffer -- otherwise
+      # the sender overruns the socket buffer and the transfer stalls.
+      sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF, @recv_cap * 2)
+      sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVBUF, @recv_cap)
+      rcv = sock.getsockopt(Socket::SOL_SOCKET, Socket::SO_RCVBUF).int
+      @recv_cap = rcv * 3 / 4 if rcv * 3 / 4 < @recv_cap
+    rescue SystemCallError
+      # Buffer sizing is best-effort; ignore if the OS clamps/rejects it.
+    end
+
+    def register(sess)
+      @sessions_mutex.synchronize { @sessions[sess.id] = sess }
+    end
+
+    def ensure_bound
+      return if @bound
+      sock = UDPSocket.new
+      configure_socket(sock)
+      sock.bind("0.0.0.0", 0)
+      @socks << [sock, Mnet.now]
+      @bound = true
+      start
+    end
+
+    def start
+      return if @running
+      @running = true
+      @reader  = Thread.new { reader_loop }
+      @ticker  = Thread.new { ticker_loop }
+    end
+
+    def reader_loop
+      loop do
+        socks = @socks.map(&:first)
+        break if socks.empty?
+        begin
+          ready = IO.select(socks, nil, nil, 0.5)
+        rescue IOError, Errno::EBADF
+          break
+        end
+        next unless ready
+
+        # Drain each ready socket in a batch (up to a cap) instead of one
+        # packet per select wakeup -- fewer syscalls/context switches.
+        ready[0].each do |sock|
+          drain_socket(sock)
+        end
+      end
+    end
+
+    def drain_socket(sock, cap = 256)
+      cap.times do
+        data, addr = sock.recvfrom_nonblock(65_535)
+        dispatch(data, addr)
+      rescue IO::WaitReadable, Errno::EAGAIN, Errno::EWOULDBLOCK
+        break
+      rescue IOError, Errno::EBADF, Errno::ECONNRESET
+        break
+      rescue => e
+        warn "mnet: #{e.class}: #{e.message}"
+        break
+      end
+    end
+
+    def dispatch(data, addr)
+      pkt = Mnet.unpack(data)
+      return unless pkt
+
+      sess = @sessions_mutex.synchronize { @sessions[pkt.session_id] }
+      if sess
+        sess.handle_packet(pkt, addr)
+      elsif pkt.type == Mnet::TYPE_SYN
+        key   = @key_by_id[pkt.session_id]
+        klass = (pkt.flags & Mnet::FLAG_KCP) != 0 ? KcpSession : Session
+        sess  = klass.new(self, pkt.session_id, role: :server, key: key, logger: @logger,
+                                    **@opts.merge(recv_capacity: @recv_cap))
+        register(sess)
+        @accept << sess
+        sess.handle_packet(pkt, addr)
+      end
+    end
+
+    def ticker_loop
+      loop do
+        sleep TICK_INTERVAL
+        now = Mnet.now
+        sessions = @sessions_mutex.synchronize { @sessions.values }
+        sessions.each { |s| s.tick(now) }
+        prune_sockets if @socks.size > 1
+      rescue IOError
+        break
+      end
+    end
+  end
+
+  # A TCPServer-compatible listener over the reliable UDP transport, so
+  # `OpenSSL::SSL::SSLServer.new(server, ctx)` works unchanged. `accept`
+  # returns a plain IO (the app end of the per-connection bridge), which the
+  # SSL layer can wrap directly.
+  class Server
+    def initialize(host = "0.0.0.0", port = 0, **opts)
+      @endpoint = Endpoint.new(**opts)
+      @endpoint.listen(host, port)
+    end
+
+    def accept
+      @endpoint.accept.bridge
+    end
+
+    # Raw session (IO-compatible, no socketpair bridge) for the non-TLS path.
+    def accept_session
+      @endpoint.accept
+    end
+
+    def close
+      @endpoint.close
+    end
+
+    def addr
+      @endpoint.local_addr
+    end
+
+    def endpoint
+      @endpoint
+    end
+  end
+end