tep 0.11.0

data/lib/tep/websocket/driver.rb

@@ -0,0 +1,169 @@
+# Tep::WebSocket::Driver -- Faye-shape state machine + event dispatch.
+#
+# Constructed AFTER the handshake completes, before the recv loop
+# starts. Holds per-connection state + outbound write methods +
+# the event-callback registry that the handler (or the Phase 3 DSL)
+# populates.
+#
+# Faye-shape API (matches faye/websocket-driver-ruby's surface for
+# the parts tep ships -- single-frame text/binary, ping/pong, close):
+#
+#     drv = Tep::WebSocket::Driver.new(fd)
+#     drv.on_message    do |evt| ... end    # block-based on:open/on:message etc
+#     drv.on_close      do |evt| ... end    #   are syntactic sugar; tep ships
+#     drv.text("hi")                        #   the explicit setters instead
+#     drv.binary(bytes)
+#     drv.ping("")
+#     drv.close(1000, "bye")
+#
+# In Phase 2, callbacks are set via explicit setters (`set_on_message`)
+# rather than `on(:message) { block }` since spinel's block-with-
+# closure-on-locals support is still uneven outside Fiber.new bodies.
+# Phase 3's DSL hides this behind `ws.on(:message) { ... }` once we
+# decide on the lowering shape.
+module Tep
+  module WebSocket
+    class Driver
+      attr_accessor :fd, :max_frame_size, :subprotocol
+      # Callback slots. Each holds a subclass of Tep::WebSocket::Handler
+      # (or the base) that gets `handle_event(event)` called when the
+      # corresponding wire event arrives. Defaults to a no-op base
+      # so the slot is type-safe pre-set.
+      attr_accessor :h_open, :h_message, :h_close, :h_ping, :h_pong, :h_error
+
+      def initialize(fd)
+        @fd             = fd
+        @max_frame_size = Tep::WebSocket::DEFAULT_MAX_FRAME
+        @subprotocol    = ""
+        @h_open    = Tep::WebSocket::Handler.new
+        @h_message = Tep::WebSocket::Handler.new
+        @h_close   = Tep::WebSocket::Handler.new
+        @h_ping    = Tep::WebSocket::Handler.new
+        @h_pong    = Tep::WebSocket::Handler.new
+        @h_error   = Tep::WebSocket::Handler.new
+      end
+
+      def set_max_frame_size(n)
+        @max_frame_size = n
+      end
+
+      # Reassign the underlying fd. Used by the server-side upgrade
+      # path: the user handler builds the Driver with a placeholder
+      # fd (since the client fd isn't visible at handler-dispatch
+      # time), and the write_response branch sets the real fd here
+      # right before constructing the Connection.
+      def set_fd(new_fd)
+        @fd = new_fd
+      end
+
+      def set_subprotocol(name)
+        @subprotocol = name
+      end
+
+      def set_on_open(h);    @h_open = h;    end
+      def set_on_message(h); @h_message = h; end
+      def set_on_close(h);   @h_close = h;   end
+      def set_on_ping(h);    @h_ping = h;    end
+      def set_on_pong(h);    @h_pong = h;    end
+      def set_on_error(h);   @h_error = h;   end
+
+      # Send a text frame.
+      def text(s)
+        Driver.send_frame(@fd, Tep::WebSocket::OPCODE_TEXT, s)
+      end
+
+      # Streamer-shape alias for `text` so a Driver can stand in
+      # anywhere `Tep::Streamer`-style code calls `out.write(s)`.
+      # Used by Tep::Llm.chat_stream to write LLM deltas as WS
+      # frames (one frame per SSE-shaped chunk).
+      def write(s)
+        Driver.send_frame(@fd, Tep::WebSocket::OPCODE_TEXT, s)
+      end
+
+      # Send a binary frame.
+      def binary(bytes)
+        Driver.send_frame(@fd, Tep::WebSocket::OPCODE_BINARY, bytes)
+      end
+
+      # Send a ping with optional payload (<=125 bytes).
+      def ping(payload)
+        Driver.send_frame(@fd, Tep::WebSocket::OPCODE_PING, payload)
+      end
+
+      # Send a pong with the matching ping's payload (per §5.5.3).
+      def pong(payload)
+        Driver.send_frame(@fd, Tep::WebSocket::OPCODE_PONG, payload)
+      end
+
+      # Send a close frame with code + reason. Reason capped at
+      # 123 bytes so the 2-byte code + reason fits in a control
+      # frame's 125-byte payload limit.
+      def close(code, reason)
+        body = Driver.encode_close_payload(code, reason)
+        Driver.send_frame(@fd, Tep::WebSocket::OPCODE_CLOSE, body)
+      end
+
+      # Build the frame bytes (unmasked, server-side) and write via
+      # sphttp_write_bytes (binary-safe, explicit length).
+      def self.send_frame(fd, opcode, payload)
+        frame = Tep::WebSocket::Frame.new(true, opcode, payload)
+        bytes = frame.encode_unmasked
+        Sock.sphttp_write_bytes(fd, bytes, bytes.length)
+      end
+
+      # Close payload: 2-byte big-endian code + UTF-8 reason. Per
+      # §5.5.1 the payload may be omitted (close with no body); if
+      # `code == 0` we emit an empty payload.
+      def self.encode_close_payload(code, reason)
+        if code == 0
+          return ""
+        end
+        out = Tep::WebSocket::Frame.byte_to_chr((code >> 8) & 0xff) +
+              Tep::WebSocket::Frame.byte_to_chr(code & 0xff)
+        if reason.length > 123
+          out + reason[0, 123]
+        else
+          out + reason
+        end
+      end
+    end
+
+    # Event passed to handler callbacks. Holds `data` (the payload
+    # as String for text/binary, raw bytes for ping/pong, or the
+    # close code+reason for close) and a numeric `code` for close.
+    class Event
+      attr_accessor :data, :code, :reason
+
+      def initialize
+        @data   = ""
+        @code   = 0
+        @reason = ""
+      end
+    end
+
+    # Base class for event handlers. Subclass + override
+    # `handle_event(event)`. The Driver stores one Handler instance
+    # per event type and dispatches via `@h_message.handle_event(evt)`.
+    # The explicit-Handler shape (vs faye's block-based `driver.on(:msg)
+    # { ... }`) is chosen because it stays compatible with future
+    # Fiber.storage per-connection state plumbing without re-typing
+    # the callback boundary.
+    #
+    # `req` is set at WS upgrade time by the route handler the
+    # translator emits, giving on_X handler bodies access to the
+    # request that initiated the connection (req.identity,
+    # req.session, headers, ...). It stays the same across every
+    # event on the connection -- there's no per-frame "request".
+    class Handler
+      attr_accessor :req
+
+      def initialize
+        @req = Tep::Request.new
+      end
+
+      def handle_event(event)
+        0
+      end
+    end
+  end
+end

data/lib/tep/websocket/frame.rb

@@ -0,0 +1,238 @@
+# Tep::WebSocket::Frame -- single-frame codec.
+#
+# Surface:
+#   - Frame.new(fin, opcode, payload)             build for emit
+#   - frame.encode_unmasked -> String             server-side emit bytes
+#   - Frame.parse_from_buf(bytes_at, bytes_len)   parse a recv'd frame
+#       returns a ParseResult (frame + bytes_consumed, OR an error code).
+#
+# Server-side emit: never masks (RFC 6455 §5.3 -- server MUST NOT
+# mask). Client-side emit isn't shipped here; tep is server-shaped.
+#
+# Parse handles three length encodings (7-bit / 16-bit / 64-bit),
+# the 4-byte mask key, and applies the mask to recover the plaintext
+# payload. Returns a structural error code (close-code-shaped) for
+# the family of malformed-frame cases that warrant a 1002 close:
+#   - reserved bits set
+#   - reserved opcode
+#   - client frame not masked
+#   - control frame payload > 125
+#   - control frame fragmented
+module Tep
+  module WebSocket
+    class Frame
+      attr_accessor :fin, :opcode, :payload
+
+      def initialize(fin, opcode, payload)
+        @fin     = fin
+        @opcode  = opcode
+        @payload = payload
+      end
+
+      # Build the unmasked server-side wire bytes. Length-encoding
+      # picks the smallest form that fits the payload. No mask.
+      def encode_unmasked
+        head = ""
+        b0 = (@fin ? 0x80 : 0x00) | (@opcode & 0x0f)
+        head = head + Frame.byte_to_chr(b0)
+
+        plen = @payload.length
+        if plen <= 125
+          head = head + Frame.byte_to_chr(plen)
+        elsif plen <= 65535
+          head = head + Frame.byte_to_chr(126)
+          head = head + Frame.byte_to_chr((plen >> 8) & 0xff)
+          head = head + Frame.byte_to_chr(plen & 0xff)
+        else
+          head = head + Frame.byte_to_chr(127)
+          i = 7
+          while i >= 0
+            head = head + Frame.byte_to_chr((plen >> (i * 8)) & 0xff)
+            i -= 1
+          end
+        end
+        head + @payload
+      end
+
+      # Convert a single byte value (0..255) to a 1-char String.
+      def self.byte_to_chr(n)
+        (n & 0xff).chr
+      end
+
+      # Parse one frame from the sphttp recv frame buffer. `start`
+      # is the byte offset to begin reading; `avail` is the count of
+      # valid bytes in the buffer. Byte reads go through the Ruby
+      # String binding sphttp_recv_frame_buf returns; matz/spinel#657
+      # made slice / bytes[i] survive embedded NULs so binary
+      # payloads parse correctly without the per-byte C accessor we
+      # used before.
+      #
+      # Returns a ParseResult with one of three shapes:
+      #   .status == "ok"      -> .frame populated + .consumed bytes used
+      #   .status == "need"    -> need more bytes (consumed == 0)
+      #   .status == "close"   -> protocol violation; close with .close_code
+      def self.parse_from_buf(start, avail)
+        out = Tep::WebSocket::ParseResult.new
+        if avail - start < 2
+          out.outcome = "need"
+          return out
+        end
+
+        buf = Sock.sphttp_recv_frame_buf
+        bs  = buf.bytes
+        b0 = bs[start]
+        b1 = bs[start + 1]
+        fin    = (b0 & 0x80) != 0
+        rsv    = b0 & 0x70
+        opcode = b0 & 0x0f
+        masked = (b1 & 0x80) != 0
+        len7   = b1 & 0x7f
+
+        if rsv != 0
+          out.outcome = "close"
+          out.close_code = Tep::WebSocket::CLOSE_PROTOCOL_ERROR
+          return out
+        end
+        if Frame.reserved_opcode?(opcode)
+          out.outcome = "close"
+          out.close_code = Tep::WebSocket::CLOSE_PROTOCOL_ERROR
+          return out
+        end
+        if Frame.control_opcode?(opcode)
+          if !fin
+            out.outcome = "close"
+            out.close_code = Tep::WebSocket::CLOSE_PROTOCOL_ERROR
+            return out
+          end
+          if len7 > 125
+            out.outcome = "close"
+            out.close_code = Tep::WebSocket::CLOSE_PROTOCOL_ERROR
+            return out
+          end
+        end
+        if !masked
+          # Server MUST close on unmasked client frame (§5.3).
+          out.outcome = "close"
+          out.close_code = Tep::WebSocket::CLOSE_PROTOCOL_ERROR
+          return out
+        end
+
+        # Decode payload length.
+        pos = start + 2
+        plen = 0
+        if len7 < 126
+          plen = len7
+        elsif len7 == 126
+          if avail - pos < 2
+            out.outcome = "need"
+            return out
+          end
+          h = bs[pos]
+          l = bs[pos + 1]
+          plen = (h << 8) | l
+          pos += 2
+        else
+          # 64-bit length
+          if avail - pos < 8
+            out.outcome = "need"
+            return out
+          end
+          plen = 0
+          i = 0
+          while i < 8
+            plen = (plen << 8) | bs[pos + i]
+            i += 1
+          end
+          pos += 8
+        end
+
+        # 4-byte mask key.
+        if avail - pos < 4
+          out.outcome = "need"
+          return out
+        end
+        m0 = bs[pos]
+        m1 = bs[pos + 1]
+        m2 = bs[pos + 2]
+        m3 = bs[pos + 3]
+        pos += 4
+
+        # Payload bytes.
+        if avail - pos < plen
+          out.outcome = "need"
+          return out
+        end
+
+        # Decode + unmask in one pass.
+        payload = ""
+        i = 0
+        while i < plen
+          b = bs[pos + i]
+          mask_byte = 0
+          if (i & 3) == 0
+            mask_byte = m0
+          elsif (i & 3) == 1
+            mask_byte = m1
+          elsif (i & 3) == 2
+            mask_byte = m2
+          else
+            mask_byte = m3
+          end
+          payload = payload + Frame.byte_to_chr(b ^ mask_byte)
+          i += 1
+        end
+
+        out.outcome   = "ok"
+        out.frame    = Tep::WebSocket::Frame.new(fin, opcode, payload)
+        out.consumed = pos + plen - start
+        out
+      end
+
+      def self.reserved_opcode?(op)
+        if op == Tep::WebSocket::OPCODE_CONTINUATION
+          return false
+        end
+        if op == Tep::WebSocket::OPCODE_TEXT
+          return false
+        end
+        if op == Tep::WebSocket::OPCODE_BINARY
+          return false
+        end
+        if op == Tep::WebSocket::OPCODE_CLOSE
+          return false
+        end
+        if op == Tep::WebSocket::OPCODE_PING
+          return false
+        end
+        if op == Tep::WebSocket::OPCODE_PONG
+          return false
+        end
+        true
+      end
+
+      def self.control_opcode?(op)
+        op == Tep::WebSocket::OPCODE_CLOSE ||
+          op == Tep::WebSocket::OPCODE_PING ||
+          op == Tep::WebSocket::OPCODE_PONG
+      end
+    end
+
+    # ParseResult carries either a parsed frame, a "need more
+    # bytes" signal, or a close-code for a protocol violation.
+    # Field is named `outcome` (not `status`) because attr_accessor
+    # :status collides with Tep::Response.status (Integer) under
+    # spinel's same-name-attr unification family
+    # (matz/spinel#537 / #538), widening Tep.reason(status) to
+    # accept poly and breaking the build.
+    class ParseResult
+      attr_accessor :outcome, :frame, :consumed, :close_code
+
+      def initialize
+        @outcome    = ""
+        @frame      = Tep::WebSocket::Frame.new(true, 0, "")
+        @consumed   = 0
+        @close_code = 0
+      end
+    end
+  end
+end

data/lib/tep/websocket/handshake.rb

@@ -0,0 +1,159 @@
+# Tep::WebSocket::Handshake -- RFC 6455 §1.3 server-side handshake.
+#
+# `check(req)`:
+#   Returns a Result with `.valid` true if the request is a proper
+#   WebSocket upgrade, `.accept_key` set to the Sec-WebSocket-Accept
+#   value the server should echo, and `.protocols` parsed from
+#   Sec-WebSocket-Protocol. Invalid uses set `.valid = false` +
+#   `.reason` for logging.
+#
+# `build_response(accept_key, protocol)`:
+#   Returns the raw HTTP/1.1 101 Switching Protocols response bytes,
+#   ready to write to the socket. `protocol` is the subprotocol to
+#   echo (empty string = omit the header per RFC §1.3 -- the safe
+#   default per rubys's pushback on tep#8).
+module Tep
+  module WebSocket
+    class Handshake
+      def self.check(req)
+        out = Tep::WebSocket::Handshake::Result.new
+
+        # Verb must be GET.
+        if req.verb != "GET"
+          out.valid = false
+          out.reason = "bad verb"
+          return out
+        end
+
+        # Upgrade + Connection headers (downcased per Tep::Request).
+        upgrade = req.headers["upgrade"]
+        if Handshake.icontains(upgrade, "websocket") == false
+          out.valid = false
+          out.reason = "missing/invalid Upgrade"
+          return out
+        end
+        conn = req.headers["connection"]
+        if Handshake.icontains(conn, "upgrade") == false
+          out.valid = false
+          out.reason = "missing/invalid Connection"
+          return out
+        end
+
+        # Sec-WebSocket-Version must be 13.
+        ver = req.headers["sec-websocket-version"]
+        if ver != "13"
+          out.valid = false
+          out.reason = "bad/missing Sec-WebSocket-Version"
+          return out
+        end
+
+        # Sec-WebSocket-Key: 24-char base64 (16-byte nonce).
+        key = req.headers["sec-websocket-key"]
+        if key.length == 0
+          out.valid = false
+          out.reason = "missing Sec-WebSocket-Key"
+          return out
+        end
+
+        out.valid = true
+        out.accept_key = Crypto.sp_crypto_websocket_accept(key)
+
+        # Parse Sec-WebSocket-Protocol (comma-separated). Handler
+        # gets the offered list; can opt-in via Driver.accept_protocol.
+        out.protocols = Handshake.split_csv(req.headers["sec-websocket-protocol"])
+        out
+      end
+
+      # Build the 101 Switching Protocols response. `protocol` empty
+      # = omit Sec-WebSocket-Protocol entirely (spec-correct per
+      # RFC 6455 §4.2.2; better than echoing a protocol the server
+      # doesn't actually implement).
+      def self.build_response(accept_key, protocol)
+        out = "HTTP/1.1 101 Switching Protocols\r\n" +
+              "Upgrade: websocket\r\n" +
+              "Connection: Upgrade\r\n" +
+              "Sec-WebSocket-Accept: " + accept_key + "\r\n"
+        if protocol.length > 0
+          out = out + "Sec-WebSocket-Protocol: " + protocol + "\r\n"
+        end
+        out + "\r\n"
+      end
+
+      # Case-insensitive substring contains. Hand-rolled because
+      # Tep::Request normalises header names to lowercase but
+      # leaves values as-is, and clients sometimes send
+      # `Connection: keep-alive, Upgrade` capitalised.
+      def self.icontains(hay, needle)
+        if hay.length == 0 || needle.length == 0
+          return false
+        end
+        hl = Handshake.downcase(hay)
+        nl = Handshake.downcase(needle)
+        Tep.str_find(hl, nl, 0) >= 0
+      end
+
+      def self.downcase(s)
+        out = ""
+        i = 0
+        while i < s.length
+          c = s[i]
+          if c >= "A" && c <= "Z"
+            out = out + (c.ord + 32).chr
+          else
+            out = out + c
+          end
+          i += 1
+        end
+        out
+      end
+
+      # Parse comma-separated header value into an Array<String>.
+      # Trims whitespace around each entry.
+      def self.split_csv(s)
+        out = [""]
+        out.delete_at(0)
+        if s.length == 0
+          return out
+        end
+        pos = 0
+        while pos < s.length
+          comma = Tep.str_find(s, ",", pos)
+          if comma < 0
+            out.push(Handshake.trim(s[pos, s.length - pos]))
+            return out
+          end
+          out.push(Handshake.trim(s[pos, comma - pos]))
+          pos = comma + 1
+        end
+        out
+      end
+
+      def self.trim(s)
+        i = 0
+        while i < s.length && (s[i] == " " || s[i] == "\t")
+          i += 1
+        end
+        j = s.length - 1
+        while j >= i && (s[j] == " " || s[j] == "\t")
+          j -= 1
+        end
+        if j < i
+          return ""
+        end
+        s[i, j - i + 1]
+      end
+
+      class Result
+        attr_accessor :valid, :reason, :accept_key, :protocols
+
+        def initialize
+          @valid      = false
+          @reason     = ""
+          @accept_key = ""
+          @protocols  = [""]
+          @protocols.delete_at(0)
+        end
+      end
+    end
+  end
+end

data/lib/tep/websocket.rb

@@ -0,0 +1,68 @@
+# Tep::WebSocket -- RFC 6455 WebSocket support for spinel-AOT'd apps.
+#
+# Protocol substrate (this file's directory):
+#   - Tep::WebSocket::Frame      single-frame codec (parse + emit)
+#   - Tep::WebSocket::Handshake  server-side handshake check + response
+#   - Tep::WebSocket::Driver     state machine + event dispatch + writers
+#   - Tep::WebSocket::Connection fiber-driven recv loop (one fiber per conn)
+#
+# Sinatra-style DSL (lowered by bin/tep):
+#
+#     set :scheduler, :scheduled
+#     websocket '/chat' do |ws|
+#       on_open    { |evt| ws.text("welcome") }
+#       on_message { |evt| ws.text("echo: " + evt.data) }
+#       on_close   { |evt| ... }
+#     end
+#
+# Requires the scheduled server (the recv loop parks on
+# Tep::Scheduler.io_wait); the blocking server returns 501 on a WS
+# upgrade attempt. See examples/websocket_echo.rb for a full app and
+# test/test_websocket_echo.rb for the end-to-end smoke harness.
+#
+# Compliance posture (per the OriPekelman/tep#8 strict/lenient table):
+#   strict-emit: server NEVER masks; reserved bits 0 on emit
+#   strict-accept (close 1002):
+#     - client frames MUST be masked
+#     - reserved bits RSV1-3 MUST be 0
+#     - reserved opcodes (3-7, B-F) reject
+#     - control frame payload > 125 reject
+#     - control frames MUST NOT fragment
+#     - continuation without prior fragment reject
+#   strict-accept (close 1007): text frames MUST be UTF-8 (deferred to
+#     Phase 2.1 -- the codec ships the structural strictness first;
+#     the UTF-8 validator is its own ~50 LOC).
+#   liberal-accept: close codes, pong payload contents, unsolicited pong.
+module Tep
+  module WebSocket
+    # Standard opcodes.
+    OPCODE_CONTINUATION = 0
+    OPCODE_TEXT         = 1
+    OPCODE_BINARY       = 2
+    OPCODE_CLOSE        = 8
+    OPCODE_PING         = 9
+    OPCODE_PONG         = 10
+
+    # Close codes (RFC 6455 §7.4). Caller-facing ones only -- the
+    # internal-error / protocol-error codes are emitted by the
+    # Driver directly, not exposed.
+    CLOSE_NORMAL          = 1000
+    CLOSE_GOING_AWAY      = 1001
+    CLOSE_PROTOCOL_ERROR  = 1002
+    CLOSE_UNSUPPORTED     = 1003
+    CLOSE_INVALID_UTF8    = 1007
+    CLOSE_POLICY_VIOLATION = 1008
+    CLOSE_MESSAGE_TOO_BIG = 1009
+
+    # Frame-size cap. Configurable via Driver#set_max_frame_size;
+    # default is 16 MiB (large enough for any realistic chat /
+    # Action Cable payload, bounded so an oversized frame can be
+    # closed with 1009 rather than OOM-ing the worker).
+    DEFAULT_MAX_FRAME = 16 * 1024 * 1024
+  end
+end
+
+require_relative "websocket/frame"
+require_relative "websocket/handshake"
+require_relative "websocket/driver"
+require_relative "websocket/connection"