tep 0.11.0

data/lib/tep/tep_sqlite.c

@@ -0,0 +1,320 @@
+/* tep_sqlite.c - thin libsqlite3 wrapper for spinel-AOT'd tep apps.
+ *
+ * Pattern mirrors sphttp.c: spinel can't load CRuby C extensions
+ * (the `sqlite3` gem ships native code via Ruby's MRI ABI), so we
+ * write a small C shim with stable, str/int-typed entry points and
+ * expose them via spinel's `ffi_func` DSL.
+ *
+ * Scope of v1
+ * -----------
+ *   - `open(path)` / `close(h)`                      -- multiple DB
+ *     handles (up to TEP_SQLITE_MAX_HANDLES) tracked in a static
+ *     slot table so handles fit in spinel's :int FFI return.
+ *   - `exec(h, sql)`                                 -- run a
+ *     statement that returns no rows (CREATE / INSERT / UPDATE /
+ *     DELETE / PRAGMA). No bind in this form; for parameterised
+ *     writes use prepare + bind + step + finalize.
+ *   - `prepare(h, sql)` / `bind_{str,int}(idx, v)` / `step()` /
+ *     `col_{str,int}(idx)` / `col_count()` / `finalize()`
+ *                                                    -- a single
+ *     global cursor (one in-flight statement per process). Spinel
+ *     workers are single-threaded, and the framework never holds
+ *     two cursors at once -- handlers run serially per worker.
+ *   - `last_insert_rowid(h)`                         -- for INSERT
+ *     ... RETURNING-less workflows.
+ *
+ * Out of scope (v1)
+ * -----------------
+ *   - Multi-cursor: nested queries (open one cursor, iterate, run
+ *     another query inside). Document and revisit.
+ *   - Blob / NULL columns: col_str returns "" for NULL, callers
+ *     can't distinguish empty-string from NULL.
+ *   - Transactions: works via `exec("BEGIN")` / `exec("COMMIT")`.
+ *
+ * Errors
+ * ------
+ * Most functions return 0 on success and -1 on error. Detailed
+ * errmsg surfacing isn't wired through (spinel's :str return
+ * lifetime would make it awkward); the C shim could expose
+ * `tep_sqlite_errmsg()` as a static-buffer copy if needed.
+ */
+
+#include <stdlib.h>
+#include <string.h>
+#include <sqlite3.h>
+
+#define TEP_SQLITE_MAX_HANDLES    16
+#define TEP_SQLITE_COL_BUFSIZE    65536
+#define TEP_SQLITE_COL_BUF_SLOTS  16
+#define TEP_SQLITE_CACHE_SLOTS    64       /* prepare-statement cache */
+#define TEP_SQLITE_CACHE_SQL_MAX  512      /* longest cached SQL */
+
+static sqlite3      *tep_sqlite_handles[TEP_SQLITE_MAX_HANDLES] = {0};
+static sqlite3_stmt *tep_sqlite_stmt = NULL;
+/* When the current cursor came from the prepare-statement cache, we
+ * must NOT sqlite3_finalize it on tep_sqlite_finalize -- the slot
+ * stays alive for reuse, and finalize becomes reset+clear_bindings.
+ * Same applies to tep_sqlite_prepare's stmt-swap path. */
+static int           tep_sqlite_stmt_cached = 0;
+
+/* prepare-statement cache (chunk per #75). Linear scan by (h, sql);
+ * n is small so O(n) is fine. Bounded by TEP_SQLITE_CACHE_SLOTS;
+ * if full, prepare_cached falls through to an uncached prepare. */
+typedef struct {
+    int           h;                                 /* db handle index (1-based), 0 = empty */
+    sqlite3_stmt *stmt;
+    char          sql[TEP_SQLITE_CACHE_SQL_MAX];
+} tep_sqlite_cache_entry;
+static tep_sqlite_cache_entry tep_sqlite_cache[TEP_SQLITE_CACHE_SLOTS] = {0};
+/* Rotating return buffers for col_str. spinel's `:str` return type
+ * wants a pointer that stays valid until "the caller is done with
+ * it", but in practice callers stash multiple col_str results into
+ * variables / hashes / array entries before the buffer would
+ * otherwise rotate. A single static buf would alias all those
+ * entries to whatever the most recent call wrote.
+ *
+ * We rotate across SLOTS buffers; each call lands in the next
+ * slot. With 16 slots a typical handler doing
+ *
+ *     a = first_str(...); b = first_str(...); c = first_str(...)
+ *
+ * sees three independent strings.
+ *
+ * The aliasing window only collapses for callers who hold > 16
+ * live col_str references concurrently -- e.g. iterating a query
+ * and pushing every row into an array without copying. Document
+ * that lifetime in `Tep::SQLite#col_str`. */
+static char          tep_sqlite_col_buf[TEP_SQLITE_COL_BUF_SLOTS][TEP_SQLITE_COL_BUFSIZE];
+static int           tep_sqlite_col_slot = 0;
+
+int tep_sqlite_open(const char *path) {
+    int i;
+    for (i = 0; i < TEP_SQLITE_MAX_HANDLES; i++) {
+        if (tep_sqlite_handles[i] == NULL) {
+            sqlite3 *db = NULL;
+            if (sqlite3_open(path, &db) != SQLITE_OK) {
+                if (db) sqlite3_close(db);
+                return -1;
+            }
+            tep_sqlite_handles[i] = db;
+            return i + 1; /* 1-indexed: 0 reserved for "uninitialised" */
+        }
+    }
+    return -1;
+}
+
+int tep_sqlite_close(int h) {
+    if (h < 1 || h > TEP_SQLITE_MAX_HANDLES) return -1;
+    sqlite3 *db = tep_sqlite_handles[h - 1];
+    if (db == NULL) return -1;
+    /* Finalize any cursor that was on this handle to avoid
+     * sqlite_close returning SQLITE_BUSY. */
+    if (tep_sqlite_stmt && sqlite3_db_handle(tep_sqlite_stmt) == db) {
+        if (!tep_sqlite_stmt_cached) {
+            sqlite3_finalize(tep_sqlite_stmt);
+        }
+        /* Cached stmts get finalized below by the cache walk. */
+        tep_sqlite_stmt = NULL;
+        tep_sqlite_stmt_cached = 0;
+    }
+    /* Finalize every cached statement that belongs to this handle
+     * before closing the db. Cache slots are owner-keyed by `h`. */
+    int i;
+    for (i = 0; i < TEP_SQLITE_CACHE_SLOTS; i++) {
+        if (tep_sqlite_cache[i].h == h && tep_sqlite_cache[i].stmt) {
+            sqlite3_finalize(tep_sqlite_cache[i].stmt);
+            tep_sqlite_cache[i].stmt = NULL;
+            tep_sqlite_cache[i].h    = 0;
+            tep_sqlite_cache[i].sql[0] = '\0';
+        }
+    }
+    sqlite3_close(db);
+    tep_sqlite_handles[h - 1] = NULL;
+    return 0;
+}
+
+int tep_sqlite_exec(int h, const char *sql) {
+    if (h < 1 || h > TEP_SQLITE_MAX_HANDLES) return -1;
+    sqlite3 *db = tep_sqlite_handles[h - 1];
+    if (db == NULL) return -1;
+    char *err = NULL;
+    int rc = sqlite3_exec(db, sql, NULL, NULL, &err);
+    if (err) sqlite3_free(err);
+    return rc == SQLITE_OK ? 0 : -1;
+}
+
+/* Drop or reset whatever's currently on the singleton cursor before
+ * we install a new one. Cached stmts get reset+clear_bindings (so
+ * the cached slot stays valid); uncached stmts get finalized. */
+static void tep_sqlite_release_current(void) {
+    if (!tep_sqlite_stmt) return;
+    if (tep_sqlite_stmt_cached) {
+        sqlite3_reset(tep_sqlite_stmt);
+        sqlite3_clear_bindings(tep_sqlite_stmt);
+    } else {
+        sqlite3_finalize(tep_sqlite_stmt);
+    }
+    tep_sqlite_stmt = NULL;
+    tep_sqlite_stmt_cached = 0;
+}
+
+int tep_sqlite_prepare(int h, const char *sql) {
+    if (h < 1 || h > TEP_SQLITE_MAX_HANDLES) return -1;
+    sqlite3 *db = tep_sqlite_handles[h - 1];
+    if (db == NULL) return -1;
+    tep_sqlite_release_current();
+    if (sqlite3_prepare_v2(db, sql, -1, &tep_sqlite_stmt, NULL) != SQLITE_OK) {
+        tep_sqlite_stmt = NULL;
+        return -1;
+    }
+    /* uncached */
+    return 0;
+}
+
+/* Cached variant: looks up `sql` for db handle `h` in the cache;
+ * on hit reuses the prepared statement (with reset + clear_bindings);
+ * on miss prepares + stashes in the first free slot; if the cache is
+ * full, falls back to an uncached prepare so the caller still works.
+ *
+ * SQL is matched literally (no normalization). Apps that generate
+ * SQL with varying whitespace miss the cache; format consistently. */
+int tep_sqlite_prepare_cached(int h, const char *sql) {
+    if (h < 1 || h > TEP_SQLITE_MAX_HANDLES) return -1;
+    sqlite3 *db = tep_sqlite_handles[h - 1];
+    if (db == NULL) return -1;
+    /* SQL longer than the cache's per-slot buffer: just do an
+     * uncached prepare. The caller still gets correct behavior. */
+    size_t sql_len = strlen(sql);
+    if (sql_len >= TEP_SQLITE_CACHE_SQL_MAX) {
+        return tep_sqlite_prepare(h, sql);
+    }
+    tep_sqlite_release_current();
+    /* Cache lookup. */
+    int i;
+    for (i = 0; i < TEP_SQLITE_CACHE_SLOTS; i++) {
+        if (tep_sqlite_cache[i].h == h &&
+            tep_sqlite_cache[i].stmt &&
+            strcmp(tep_sqlite_cache[i].sql, sql) == 0) {
+            tep_sqlite_stmt = tep_sqlite_cache[i].stmt;
+            sqlite3_reset(tep_sqlite_stmt);
+            sqlite3_clear_bindings(tep_sqlite_stmt);
+            tep_sqlite_stmt_cached = 1;
+            return 0;
+        }
+    }
+    /* Cache miss -- find an empty slot. */
+    int empty = -1;
+    for (i = 0; i < TEP_SQLITE_CACHE_SLOTS; i++) {
+        if (tep_sqlite_cache[i].h == 0) { empty = i; break; }
+    }
+    if (empty < 0) {
+        /* Cache full: prepare uncached so the caller works. The
+         * existing tep_sqlite_finalize path will sqlite3_finalize
+         * this one as today. */
+        if (sqlite3_prepare_v2(db, sql, -1, &tep_sqlite_stmt, NULL) != SQLITE_OK) {
+            tep_sqlite_stmt = NULL;
+            return -1;
+        }
+        tep_sqlite_stmt_cached = 0;
+        return 0;
+    }
+    /* Prepare + stash. */
+    sqlite3_stmt *new_stmt = NULL;
+    if (sqlite3_prepare_v2(db, sql, -1, &new_stmt, NULL) != SQLITE_OK) {
+        tep_sqlite_stmt = NULL;
+        return -1;
+    }
+    tep_sqlite_cache[empty].h    = h;
+    tep_sqlite_cache[empty].stmt = new_stmt;
+    memcpy(tep_sqlite_cache[empty].sql, sql, sql_len);
+    tep_sqlite_cache[empty].sql[sql_len] = '\0';
+    tep_sqlite_stmt        = new_stmt;
+    tep_sqlite_stmt_cached = 1;
+    return 0;
+}
+
+int tep_sqlite_bind_str(int idx, const char *value) {
+    if (!tep_sqlite_stmt) return -1;
+    /* SQLITE_TRANSIENT -> sqlite copies the string before returning,
+     * so the caller's pointer doesn't need to outlive the bind. */
+    return sqlite3_bind_text(tep_sqlite_stmt, idx, value, -1, SQLITE_TRANSIENT)
+                == SQLITE_OK ? 0 : -1;
+}
+
+/* 64-bit bind. `long` is the FFI `:long` type (64-bit on the LP64
+ * targets Spinel compiles for); routed through sqlite3_bind_int64 so a
+ * value > 2^31 isn't truncated on the way in (issue #171). */
+int tep_sqlite_bind_int(int idx, long value) {
+    if (!tep_sqlite_stmt) return -1;
+    return sqlite3_bind_int64(tep_sqlite_stmt, idx, (sqlite3_int64)value) == SQLITE_OK ? 0 : -1;
+}
+
+/* 1 -> row available, 0 -> done (no more rows), -1 -> error */
+int tep_sqlite_step(void) {
+    if (!tep_sqlite_stmt) return -1;
+    int rc = sqlite3_step(tep_sqlite_stmt);
+    if (rc == SQLITE_ROW) return 1;
+    if (rc == SQLITE_DONE) return 0;
+    return -1;
+}
+
+const char *tep_sqlite_col_str(int idx) {
+    if (!tep_sqlite_stmt) return "";
+    const unsigned char *t = sqlite3_column_text(tep_sqlite_stmt, idx);
+    if (!t) return "";
+    size_t n = strlen((const char *)t);
+    if (n >= TEP_SQLITE_COL_BUFSIZE) n = TEP_SQLITE_COL_BUFSIZE - 1;
+    char *buf = tep_sqlite_col_buf[tep_sqlite_col_slot];
+    tep_sqlite_col_slot = (tep_sqlite_col_slot + 1) % TEP_SQLITE_COL_BUF_SLOTS;
+    memcpy(buf, t, n);
+    buf[n] = '\0';
+    return buf;
+}
+
+/* 64-bit column read. sqlite3_column_int (32-bit) silently wrapped a
+ * value > 2^31 negative -- e.g. a 3.4e9 download count read back as
+ * -867422609 (issue #171). sqlite3_column_int64 + a `long` (FFI
+ * `:long`, 64-bit) return path preserves the full range; mrb_int is
+ * pointer-width so the Ruby side holds it losslessly. */
+long tep_sqlite_col_int(int idx) {
+    if (!tep_sqlite_stmt) return 0;
+    return (long)sqlite3_column_int64(tep_sqlite_stmt, idx);
+}
+
+int tep_sqlite_col_count(void) {
+    if (!tep_sqlite_stmt) return 0;
+    return sqlite3_column_count(tep_sqlite_stmt);
+}
+
+/* Finalize semantics depend on whether the current stmt came from
+ * the prepare-statement cache. Cached stmts get reset + clear_bindings
+ * and stay alive in their slot (the whole point of the cache); only
+ * uncached stmts actually sqlite3_finalize. The Ruby-side API
+ * (`db.finalize`) is unchanged either way. */
+int tep_sqlite_finalize(void) {
+    if (!tep_sqlite_stmt) return 0;
+    if (tep_sqlite_stmt_cached) {
+        sqlite3_reset(tep_sqlite_stmt);
+        sqlite3_clear_bindings(tep_sqlite_stmt);
+    } else {
+        sqlite3_finalize(tep_sqlite_stmt);
+    }
+    tep_sqlite_stmt = NULL;
+    tep_sqlite_stmt_cached = 0;
+    return 0;
+}
+
+int tep_sqlite_last_insert_rowid(int h) {
+    if (h < 1 || h > TEP_SQLITE_MAX_HANDLES) return -1;
+    sqlite3 *db = tep_sqlite_handles[h - 1];
+    if (db == NULL) return -1;
+    return (int)sqlite3_last_insert_rowid(db);
+}
+
+/* Reset the current statement so it can be re-stepped (e.g. inside
+ * a loop where bound params change between iterations). Returns 0
+ * on success. */
+int tep_sqlite_reset(void) {
+    if (!tep_sqlite_stmt) return -1;
+    return sqlite3_reset(tep_sqlite_stmt) == SQLITE_OK ? 0 : -1;
+}

data/lib/tep/url.rb

@@ -0,0 +1,161 @@
+# Percent-decoding + form-urlencoded query parser.
+module Tep
+  class Url
+    # "%41+b" -> "A b"
+    def self.unescape(s)
+      out = ""
+      i = 0
+      n = s.length
+      while i < n
+        c = s[i]
+        if c == "+"
+          out = out + " "
+          i += 1
+        elsif c == "%" && i + 2 < n
+          hi = Url.hex_nibble(s[i + 1])
+          lo = Url.hex_nibble(s[i + 2])
+          if hi >= 0 && lo >= 0
+            out = out + ((hi * 16 + lo).chr)
+            i += 3
+          else
+            out = out + c
+            i += 1
+          end
+        else
+          out = out + c
+          i += 1
+        end
+      end
+      out
+    end
+
+    # Percent-encode the bytes that are unsafe in cookie values, query
+    # strings, and similar contexts. RFC 3986 unreserved set:
+    # ALPHA / DIGIT / `-._~`. Everything else gets `%XX` (uppercase hex).
+    def self.escape(s)
+      out = ""
+      i = 0
+      while i < s.length
+        c = s[i]
+        if (c >= "a" && c <= "z") || (c >= "A" && c <= "Z") ||
+           (c >= "0" && c <= "9") || c == "-" || c == "." ||
+           c == "_" || c == "~"
+          out = out + c
+        else
+          b = c.getbyte(0)
+          hi = b / 16
+          lo = b % 16
+          out = out + "%" + Url.hex_char(hi) + Url.hex_char(lo)
+        end
+        i += 1
+      end
+      out
+    end
+
+    def self.hex_char(n)
+      if n < 10
+        return ("0".getbyte(0) + n).chr
+      end
+      ("A".getbyte(0) + n - 10).chr
+    end
+
+    def self.hex_nibble(c)
+      if c >= "0" && c <= "9"
+        return c.getbyte(0) - "0".getbyte(0)
+      end
+      if c >= "a" && c <= "f"
+        return c.getbyte(0) - "a".getbyte(0) + 10
+      end
+      if c >= "A" && c <= "F"
+        return c.getbyte(0) - "A".getbyte(0) + 10
+      end
+      -1
+    end
+
+    # Split a URL into a Hash with str=>str entries:
+    #   "scheme" "host" "port" "path" "query"
+    #
+    # Recognises `http://host[:port]/path?query` and the same shape
+    # with `https://`. Without a scheme, the input is treated as a
+    # path (host stays empty); useful for routing relative paths
+    # through the same parser. Default ports follow the scheme:
+    # 80 for http, 443 for https. Path defaults to "/". `query` is
+    # the raw substring after `?`, no further decoding.
+    #
+    # Inlined as one method on purpose: spinel's analyzer widens
+    # Hash-typed parameters when a helper mutates them and the
+    # caller then keeps reading; sticking to a single body keeps
+    # `out` narrowed to StrStrHash throughout.
+    def self.split_url(u)
+      out = Tep.str_hash
+      out["scheme"] = ""
+      out["host"]   = ""
+      out["port"]   = ""
+      out["path"]   = "/"
+      out["query"]  = ""
+
+      rest = u
+      if rest.length >= 7 && rest[0, 7] == "http://"
+        out["scheme"] = "http"
+        out["port"]   = "80"
+        rest = rest[7, rest.length - 7]
+      elsif rest.length >= 8 && rest[0, 8] == "https://"
+        out["scheme"] = "https"
+        out["port"]   = "443"
+        rest = rest[8, rest.length - 8]
+      end
+
+      if out["scheme"].length > 0
+        slash = Tep.str_find(rest, "/", 0)
+        hostport = rest
+        tail     = "/"
+        if slash >= 0
+          hostport = rest[0, slash]
+          tail     = rest[slash, rest.length - slash]
+        end
+        colon = Tep.str_find(hostport, ":", 0)
+        if colon >= 0
+          out["host"] = hostport[0, colon]
+          out["port"] = hostport[colon + 1, hostport.length - colon - 1]
+        else
+          out["host"] = hostport
+        end
+        rest = tail
+      end
+
+      qi = Tep.str_find(rest, "?", 0)
+      if qi >= 0
+        out["path"]  = rest[0, qi]
+        out["query"] = rest[qi + 1, rest.length - qi - 1]
+      else
+        out["path"] = rest
+      end
+      if out["path"].length == 0
+        out["path"] = "/"
+      end
+      out
+    end
+
+    # "a=1&b=2&c" -> Hash {"a"=>"1","b"=>"2","c"=>""}
+    def self.parse_query(s)
+      h = Tep.str_hash
+      if s.length == 0
+        return h
+      end
+      pairs = s.split("&")
+      pairs.each do |pair|
+        if pair.length > 0
+          eq = Tep.str_find(pair, "=", 0)
+          if eq < 0
+            h[Url.unescape(pair)] = ""
+          else
+            k = pair[0, eq]
+            v = pair[eq + 1, pair.length - eq - 1]
+            h[Url.unescape(k)] = Url.unescape(v)
+          end
+        end
+      end
+      h
+    end
+  end
+end

data/lib/tep/version.rb

@@ -0,0 +1,3 @@
+module Tep
+  VERSION = "0.11.0"
+end

data/lib/tep/websocket/connection.rb

@@ -0,0 +1,171 @@
+# Tep::WebSocket::Connection -- per-connection recv loop.
+#
+# Designed to run inside a Tep::Scheduler-managed fiber spawned by
+# the upgrade route after the 101 response is written. The fiber:
+#   1. Parks on Tep::Scheduler.io_wait(fd, READ, timeout) for bytes.
+#   2. Reads via Sock.sphttp_recv_into_frame into the binary frame buf.
+#   3. Walks the accumulated buffer with Frame.parse_from_buf,
+#      dispatching events to the Driver's handlers.
+#   4. On close (sent OR received), exits cleanly + closes the fd.
+#
+# The recv buffer (sphttp_frame_buf, 64 KiB) is the per-fork static
+# from Phase 0.5; cross-fiber sharing within one worker process is
+# bounded by the worker's cooperative scheduling -- only one fiber
+# parses at a time. A future Phase 2.1 (or whenever multi-fiber WS
+# concurrency-per-worker becomes a goal) replaces this with
+# per-fiber buffers via Fiber.storage (matz/spinel#578).
+module Tep
+  module WebSocket
+    class Connection
+      attr_accessor :driver, :fd, :idle_timeout_seconds
+
+      def initialize(driver)
+        @driver = driver
+        @fd     = driver.fd
+        @idle_timeout_seconds = 300
+      end
+
+      def set_idle_timeout(seconds)
+        @idle_timeout_seconds = seconds
+      end
+
+      # Drive the recv loop. Returns 0 on clean close, -1 on error.
+      # Idempotent across multiple frames per recv: a single
+      # sphttp_recv_into_frame fill may contain several complete
+      # frames; Connection consumes them all before parking again.
+      #
+      # The caller (Tep::Server::Scheduled.write_response) owns the
+      # fd lifecycle -- run() never calls sphttp_close. On clean
+      # close OR error the server's handle_connection closes the fd
+      # via its usual exit path.
+      def run
+        # Synthetic open event before the first recv -- handlers
+        # often want to send a welcome message.
+        Connection.dispatch_open(@driver)
+
+        while true
+          ready = Tep::Scheduler.io_wait(@fd, Tep::Scheduler::READ, @idle_timeout_seconds)
+          if ready == 0
+            # Timeout: close 1001 going-away.
+            @driver.close(Tep::WebSocket::CLOSE_GOING_AWAY, "idle timeout")
+            return 0
+          end
+
+          n = Sock.sphttp_recv_into_frame(@fd)
+          if n <= 0
+            # EOF or error: dispatch close without sending one back
+            # (peer already gone) and exit.
+            Connection.dispatch_close(@driver, Tep::WebSocket::CLOSE_GOING_AWAY, "")
+            if n == 0
+              return 0
+            end
+            return -1
+          end
+
+          # Parse + dispatch as many complete frames as possible
+          # from this recv.
+          state = Tep::WebSocket::ConnectionState.new
+          state.start = 0
+          state.avail = n
+          while true
+            r = Tep::WebSocket::Frame.parse_from_buf(state.start, state.avail)
+            if r.outcome == "need"
+              break
+            end
+            if r.outcome == "close"
+              @driver.close(r.close_code, "protocol error")
+              return 0
+            end
+            Connection.dispatch_frame(@driver, r.frame)
+            state.start = state.start + r.consumed
+            if state.start >= state.avail
+              break
+            end
+          end
+        end
+        0
+      end
+
+      # Route a parsed frame to the right handler.
+      def self.dispatch_frame(driver, frame)
+        op = frame.opcode
+        if op == Tep::WebSocket::OPCODE_TEXT
+          Connection.dispatch_message(driver, frame.payload, true)
+        elsif op == Tep::WebSocket::OPCODE_BINARY
+          Connection.dispatch_message(driver, frame.payload, false)
+        elsif op == Tep::WebSocket::OPCODE_PING
+          # Auto-pong with the ping's payload (§5.5.3).
+          driver.pong(frame.payload)
+          Connection.dispatch_ping(driver, frame.payload)
+        elsif op == Tep::WebSocket::OPCODE_PONG
+          Connection.dispatch_pong(driver, frame.payload)
+        elsif op == Tep::WebSocket::OPCODE_CLOSE
+          code = 0
+          reason = ""
+          if frame.payload.length >= 2
+            code = (frame.payload[0].ord << 8) | frame.payload[1].ord
+            if frame.payload.length > 2
+              reason = frame.payload[2, frame.payload.length - 2]
+            end
+          end
+          # Echo the close back (§5.5.1) then dispatch.
+          driver.close(code == 0 ? Tep::WebSocket::CLOSE_NORMAL : code, reason)
+          Connection.dispatch_close(driver, code, reason)
+        end
+        0
+      end
+
+      def self.dispatch_open(driver)
+        evt = Tep::WebSocket::Event.new
+        driver.h_open.handle_event(evt)
+        0
+      end
+
+      def self.dispatch_message(driver, data, text)
+        evt = Tep::WebSocket::Event.new
+        evt.data = data
+        driver.h_message.handle_event(evt)
+        0
+      end
+
+      def self.dispatch_ping(driver, data)
+        evt = Tep::WebSocket::Event.new
+        evt.data = data
+        driver.h_ping.handle_event(evt)
+        0
+      end
+
+      def self.dispatch_pong(driver, data)
+        evt = Tep::WebSocket::Event.new
+        evt.data = data
+        driver.h_pong.handle_event(evt)
+        0
+      end
+
+      def self.dispatch_close(driver, code, reason)
+        evt = Tep::WebSocket::Event.new
+        evt.code = code
+        evt.reason = reason
+        driver.h_close.handle_event(evt)
+        # Auto-cleanup: any Broadcast subscription or Presence row
+        # keyed on this connection's fd gets dropped. Both calls
+        # are no-op-safe when nothing was tracked (zero matches).
+        # Apps that still call unsubscribe_fd / untrack_by_fd
+        # explicitly stay correct -- the second call finds 0 matches.
+        Tep::Broadcast.unsubscribe_fd(driver.fd)
+        Tep::Presence.untrack_by_fd(driver.fd)
+        0
+      end
+    end
+
+    # Per-recv-loop iteration state. Avoids tuple-returns from
+    # parse_from_buf calls (spinel multi-return support is uneven).
+    class ConnectionState
+      attr_accessor :start, :avail
+      def initialize
+        @start = 0
+        @avail = 0
+      end
+    end
+  end
+end