tep 0.11.0

data/examples/chat/app.rb

@@ -0,0 +1,278 @@
+# tep chat -- live multi-user chat with presence + Server-Sent
+# Events streaming. A second flagship demo (alongside examples/blog/)
+# that pushes tep into less-trodden corners:
+#
+#   - Tep::Streamer        long-running SSE pump per client
+#   - polling SSE          while-loop with sleep + sphttp_write_chunk
+#   - SQLite as a fanout   each streamer polls a `messages` table for
+#                          rows newer than its last seen id; the
+#                          single-cursor-per-process rule means each
+#                          worker process holds one streamer + one
+#                          DB cursor at a time, but the prefork model
+#                          (-w N) gives N concurrent listeners
+#   - Presence             heartbeat table refreshed via POST every
+#                          few seconds; `who` query lists rows touched
+#                          in the last 30 s
+#   - Tep::Json            wire format for the SSE event payloads
+#                          and the /who endpoint
+#   - Tep::Logger          per-connection trace
+#   - Tep::Security        CORS + secure-headers
+#   - ERB + @ivar locals   the chat UI page
+#
+# Build + run:
+#
+#     bin/tep build examples/chat/app.rb -o /tmp/chat
+#     /tmp/chat -p 4567 -w 4
+#
+# Open http://localhost:4567/ in two browser windows; watch
+# messages from one show up in the other within ~1 s. The `-w 4`
+# matters: each open SSE connection occupies a worker.
+
+require 'sinatra'
+
+# Concurrency model
+# -----------------
+# tep handlers are blocking inside their worker; a long-running
+# stream pins that worker until it returns. macOS's SO_REUSEPORT
+# does not load-balance new connections across listening
+# processes (only Linux 3.9+ does), so on macOS even with
+# `-w 4` a single SSE connection effectively blocks every other
+# request. Linux behaves correctly.
+#
+# To make this demo work across platforms we ship the polling
+# variant by default (each browser hits `GET /chat/recent` once
+# per second). The SSE streamer survives in the codebase as
+# `ChatStreamer` + `GET /chat/stream`; on Linux you can set
+# TEP_CHAT_USE_SSE=1 in the page's JS layer (see views/index.erb)
+# to switch back to the streaming path with sub-second latency.
+set :workers, 4
+
+DB_PATH      = ENV.fetch("TEP_CHAT_DB", "/tmp/tep_chat.db")
+PRESENCE_TTL = 30   # seconds; users not seen in this window drop
+                    # out of /who
+STREAM_MAX   = 30   # seconds; streamers self-close after this and
+                    # the client reconnects (so we don't pile up
+                    # connection-state forever in any one worker)
+
+LOGGER = Tep::Logger.new
+LOGGER.set_level("info")
+
+CORS = Tep::Security::Cors.new
+CORS.set_origin("*")
+CORS.set_allowed_verbs("GET,POST,OPTIONS")
+CORS.set_allowed_headers("Content-Type")
+Tep.before CORS
+
+HEADERS = Tep::Security::Headers.new
+Tep.after HEADERS
+
+set :views, File.expand_path("views", __dir__)
+
+# -------------------------------------------------------------------
+# Schema
+# -------------------------------------------------------------------
+
+on_start do
+  db = Tep::SQLite.new
+  if db.open(DB_PATH)
+    db.exec("CREATE TABLE IF NOT EXISTS messages (id INTEGER PRIMARY KEY, room TEXT, author TEXT, body TEXT, created_at INTEGER)")
+    db.exec("CREATE TABLE IF NOT EXISTS presence (user TEXT PRIMARY KEY, last_seen INTEGER)")
+    LOGGER.info("chat ready, db at " + DB_PATH)
+    db.close
+  end
+end
+
+before do
+  LOGGER.info(req.verb + " " + req.path)
+end
+
+# -------------------------------------------------------------------
+# Web UI
+# -------------------------------------------------------------------
+
+get '/' do
+  @last_id = current_max_id
+  erb :index
+end
+
+# Helper: read max(messages.id) so the page joins mid-stream.
+def current_max_id
+  db = Tep::SQLite.new
+  db.open(DB_PATH)
+  n = db.first_int("SELECT IFNULL(MAX(id), 0) FROM messages", "")
+  db.close
+  n
+end
+
+# -------------------------------------------------------------------
+# Send / heartbeat / who -- the JSON corners
+# -------------------------------------------------------------------
+
+post '/chat/send' do
+  res.headers["Content-Type"] = "application/json"
+  author = params[:author]
+  body   = params[:body]
+  room   = "main"
+  if author.length == 0 || body.length == 0
+    res.set_status(400)
+    return "{\"error\":\"author and body required\"}"
+  end
+
+  db = Tep::SQLite.new
+  db.open(DB_PATH)
+  db.prepare("INSERT INTO messages (room, author, body, created_at) VALUES (?, ?, ?, ?)")
+  db.bind_str(1, room)
+  db.bind_str(2, author)
+  db.bind_str(3, body)
+  db.bind_int(4, Time.now.to_i)
+  db.step
+  db.finalize
+  id = db.last_rowid
+
+  # Fold the send into the sender's presence too.
+  db.prepare("INSERT OR REPLACE INTO presence (user, last_seen) VALUES (?, ?)")
+  db.bind_str(1, author)
+  db.bind_int(2, Time.now.to_i)
+  db.step
+  db.finalize
+  db.close
+
+  LOGGER.info("send id=" + id.to_s + " by " + author + ": " + body)
+  "{" + Tep::Json.encode_pair_int("id", id) + "}"
+end
+
+post '/chat/heartbeat' do
+  res.headers["Content-Type"] = "application/json"
+  user = params[:user]
+  if user.length == 0
+    res.set_status(400)
+    return "{\"error\":\"user required\"}"
+  end
+  db = Tep::SQLite.new
+  db.open(DB_PATH)
+  db.prepare("INSERT OR REPLACE INTO presence (user, last_seen) VALUES (?, ?)")
+  db.bind_str(1, user)
+  db.bind_int(2, Time.now.to_i)
+  db.step
+  db.finalize
+  db.close
+  "{\"ok\":1}"
+end
+
+get '/chat/who' do
+  res.headers["Content-Type"] = "application/json"
+  cutoff = Time.now.to_i - PRESENCE_TTL
+
+  db = Tep::SQLite.new
+  db.open(DB_PATH)
+  out = "["
+  first = true
+  db.prepare("SELECT user, last_seen FROM presence WHERE last_seen >= ? ORDER BY last_seen DESC")
+  db.bind_int(1, cutoff)
+  while db.step == 1
+    if !first
+      out = out + ","
+    end
+    first = false
+    out = out + "{" +
+      Tep::Json.encode_pair_str("user", db.col_str(0)) + "," +
+      Tep::Json.encode_pair_int("last_seen", db.col_int(1)) + "}"
+  end
+  db.finalize
+  db.close
+  out + "]"
+end
+
+# Non-streaming fallback for clients that don't grok SSE.
+get '/chat/recent' do
+  res.headers["Content-Type"] = "application/json"
+  since = (params[:since].length > 0 ? params[:since] : "0").to_i
+
+  db = Tep::SQLite.new
+  db.open(DB_PATH)
+  out = "["
+  first = true
+  db.prepare("SELECT id, author, body FROM messages WHERE id > ? ORDER BY id LIMIT 200")
+  db.bind_int(1, since)
+  while db.step == 1
+    if !first
+      out = out + ","
+    end
+    first = false
+    out = out + "{" +
+      Tep::Json.encode_pair_int("id", db.col_int(0)) + "," +
+      Tep::Json.encode_pair_str("author", db.col_str(1)) + "," +
+      Tep::Json.encode_pair_str("body",   db.col_str(2)) + "}"
+  end
+  db.finalize
+  db.close
+  out + "]"
+end
+
+# -------------------------------------------------------------------
+# SSE stream
+# -------------------------------------------------------------------
+#
+# Polls the messages table once per second, emits any rows with id
+# greater than the last one we sent, plus an SSE comment keepalive
+# on every tick so an idle connection still proves it's alive.
+# After STREAM_MAX seconds the pump returns; the client reconnects
+# (?since=<last_id>) to keep going.
+#
+# Single-cursor-per-process: each pump tick opens its own SQLite
+# handle, runs the SELECT to completion, and closes the handle
+# before sleeping. That keeps the cursor lifetime short and lets a
+# concurrent /chat/send on the same worker (none, since workers are
+# single-threaded) or a different worker run uncontested.
+
+class ChatStreamer < Tep::Streamer
+  attr_accessor :since_id
+
+  def initialize
+    @since_id = 0
+  end
+
+  def pump(out)
+    last_id = @since_id
+    ticks = 0
+    while ticks < STREAM_MAX
+      db = Tep::SQLite.new
+      db.open(DB_PATH)
+      db.prepare("SELECT id, author, body FROM messages WHERE id > ? ORDER BY id LIMIT 50")
+      db.bind_int(1, last_id)
+      while db.step == 1
+        id     = db.col_int(0)
+        author = db.col_str(1)
+        body   = db.col_str(2)
+        line = "data: {" +
+          Tep::Json.encode_pair_int("id", id) + "," +
+          Tep::Json.encode_pair_str("author", author) + "," +
+          Tep::Json.encode_pair_str("body",   body) + "}\n\n"
+        out.write(line)
+        if id > last_id
+          last_id = id
+        end
+      end
+      db.finalize
+      db.close
+
+      # SSE comment keepalive -- the browser EventSource ignores it
+      # but the byte arriving on the socket is what we use to detect
+      # a half-closed peer (writes start failing once the kernel
+      # learns the other side is gone).
+      out.write(": tick\n\n")
+
+      sleep 1
+      ticks += 1
+    end
+    0
+  end
+end
+
+get '/chat/stream' do
+  res.headers["Content-Type"] = "text/event-stream"
+  res.headers["Cache-Control"] = "no-cache"
+  s = ChatStreamer.new
+  s.since_id = (params[:since].length > 0 ? params[:since] : "0").to_i
+  stream s
+end

data/examples/chat/assets/logo.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="64" y2="64" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#6e7df0"/>
+      <stop offset="1" stop-color="#3a4ec9"/>
+    </linearGradient>
+  </defs>
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="url(#g)"/>
+  <path d="M16 22h32a4 4 0 0 1 4 4v14a4 4 0 0 1-4 4H30l-8 8v-8h-6a4 4 0 0 1-4-4V26a4 4 0 0 1 4-4z" fill="#fff" opacity=".95"/>
+  <circle cx="24" cy="33" r="2.5" fill="#3a4ec9"/>
+  <circle cx="32" cy="33" r="2.5" fill="#3a4ec9"/>
+  <circle cx="40" cy="33" r="2.5" fill="#3a4ec9"/>
+</svg>

data/examples/chat/assets/style.css

@@ -0,0 +1,209 @@
+:root {
+  --bg-grad-from: #f5f7fb;
+  --bg-grad-to:   #e8ecf5;
+  --card-bg:      #ffffff;
+  --ink:          #1f2330;
+  --ink-soft:     #5b6479;
+  --ink-faint:    #9aa3b6;
+  --accent:       #4a5fde;
+  --accent-soft:  #e8ebff;
+  --me-bg:        #4a5fde;
+  --me-ink:       #ffffff;
+  --them-bg:      #f1f3f9;
+  --them-ink:     #1f2330;
+  --shadow:       0 8px 30px rgba(31, 35, 48, .06);
+}
+
+* { box-sizing: border-box; }
+
+html, body {
+  height: 100%;
+  margin: 0;
+  font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  color: var(--ink);
+  background: linear-gradient(135deg, var(--bg-grad-from), var(--bg-grad-to));
+}
+
+.shell {
+  max-width: 760px;
+  margin: 0 auto;
+  padding: 24px 16px 16px;
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+}
+
+nav {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding-bottom: 12px;
+  border-bottom: 1px solid rgba(31, 35, 48, .08);
+}
+
+nav h1 {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 20px;
+  font-weight: 600;
+  margin: 0;
+  letter-spacing: -.01em;
+}
+
+nav h1 .logo {
+  width: 28px;
+  height: 28px;
+  display: block;
+}
+
+nav h1 .stripe {
+  font-weight: 500;
+  color: var(--ink-faint);
+  font-size: 13px;
+  margin-left: 8px;
+}
+
+#who {
+  flex: 1;
+  color: var(--ink-soft);
+  font-size: 13px;
+}
+
+#who .pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--accent-soft);
+  color: var(--accent);
+  padding: 3px 10px;
+  border-radius: 999px;
+  font-weight: 500;
+  margin-right: 6px;
+  margin-bottom: 4px;
+}
+
+#who .pill::before {
+  content: "";
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: #2bb673;
+  display: inline-block;
+}
+
+#me {
+  background: var(--card-bg);
+  border: 1px solid rgba(31, 35, 48, .12);
+  padding: 7px 12px;
+  border-radius: 8px;
+  font: inherit;
+  width: 160px;
+  outline: none;
+  transition: border-color .15s;
+}
+
+#me:focus {
+  border-color: var(--accent);
+}
+
+#log {
+  flex: 1;
+  overflow-y: auto;
+  margin: 16px 0;
+  padding: 16px;
+  background: var(--card-bg);
+  border-radius: 12px;
+  box-shadow: var(--shadow);
+}
+
+.msg {
+  display: flex;
+  flex-direction: column;
+  margin: 10px 0;
+  max-width: 78%;
+}
+
+.msg.me {
+  align-self: flex-end;
+  margin-left: auto;
+}
+
+.msg .meta {
+  font-size: 11px;
+  color: var(--ink-faint);
+  letter-spacing: .02em;
+  text-transform: uppercase;
+  margin-bottom: 3px;
+  padding: 0 4px;
+}
+
+.msg.me .meta { text-align: right; }
+
+.msg .body {
+  padding: 9px 14px;
+  border-radius: 14px;
+  background: var(--them-bg);
+  color: var(--them-ink);
+  white-space: pre-wrap;
+  word-wrap: break-word;
+}
+
+.msg.me .body {
+  background: var(--me-bg);
+  color: var(--me-ink);
+  border-bottom-right-radius: 4px;
+}
+
+.msg.them .body {
+  border-bottom-left-radius: 4px;
+}
+
+#log:empty::before {
+  content: "no messages yet -- pick a name and say hi";
+  color: var(--ink-faint);
+  font-style: italic;
+}
+
+.status {
+  color: var(--ink-faint);
+  font-size: 12px;
+  text-align: center;
+  margin: 6px 0 12px;
+}
+
+#f {
+  display: flex;
+  gap: 8px;
+  padding: 10px;
+  background: var(--card-bg);
+  border-radius: 12px;
+  box-shadow: var(--shadow);
+}
+
+#body {
+  flex: 1;
+  padding: 11px 14px;
+  border: none;
+  background: transparent;
+  font: inherit;
+  outline: none;
+  color: var(--ink);
+}
+
+#body::placeholder { color: var(--ink-faint); }
+
+button {
+  padding: 9px 18px;
+  border: none;
+  border-radius: 8px;
+  background: var(--accent);
+  color: white;
+  font: 500 14px/1 -apple-system, sans-serif;
+  cursor: pointer;
+  transition: opacity .12s;
+}
+
+button:hover { opacity: .9; }
+button:active { transform: translateY(1px); }
+button:disabled { opacity: .4; cursor: default; }

data/examples/chat/views/index.erb

@@ -0,0 +1,142 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>tep chat</title>
+  <link rel="icon" type="image/svg+xml" href="/logo.svg">
+  <link rel="stylesheet" href="/style.css">
+</head>
+<body>
+  <div class="shell">
+    <nav>
+      <h1>
+        <img src="/logo.svg" alt="" class="logo">
+        tep chat
+        <span class="stripe">single static binary</span>
+      </h1>
+      <span id="who">connecting...</span>
+      <input id="me" placeholder="your name" autocomplete="off">
+    </nav>
+
+    <div id="log" role="log" aria-live="polite"></div>
+    <p class="status" id="conn">starting...</p>
+
+    <form id="f" autocomplete="off">
+      <input id="body" placeholder="say something..." autocomplete="off">
+      <button>send</button>
+    </form>
+  </div>
+
+  <script>
+    let sinceId = <%= @last_id %>;
+    let me      = localStorage.getItem('tep_chat_user') || '';
+    document.getElementById('me').value = me;
+    document.getElementById('me').addEventListener('change', e => {
+      me = e.target.value.trim();
+      localStorage.setItem('tep_chat_user', me);
+      heartbeat();
+    });
+
+    const log  = document.getElementById('log');
+    const conn = document.getElementById('conn');
+    const who  = document.getElementById('who');
+
+    function escapeHtml(s) {
+      return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+    }
+
+    function append(m) {
+      if (m.id <= sinceId) return;
+      const row = document.createElement('div');
+      row.className = 'msg ' + (m.author === me ? 'me' : 'them');
+      row.innerHTML =
+        '<div class="meta">' + escapeHtml(m.author) + '</div>' +
+        '<div class="body">' + escapeHtml(m.body) + '</div>';
+      log.appendChild(row);
+      log.scrollTop = log.scrollHeight;
+      sinceId = Math.max(sinceId, m.id);
+    }
+
+    // Two transports for the message stream:
+    //   * polling -- /chat/recent?since=N every 1s (default).
+    //     Works everywhere, including macOS where prefork
+    //     workers don't load-balance new connections under a
+    //     long-running SSE.
+    //   * SSE -- /chat/stream?since=N, sub-second latency.
+    //     Set window.USE_SSE = true (or have your deploy template
+    //     flip it) to switch back on Linux where SO_REUSEPORT
+    //     actually distributes accept calls across workers.
+    async function pollOnce() {
+      try {
+        const r = await fetch('/chat/recent?since=' + sinceId);
+        const list = await r.json();
+        list.forEach(append);
+        conn.textContent = 'live (polling, since=' + sinceId + ')';
+      } catch (e) {
+        conn.textContent = 'polling: error -- retrying';
+      }
+    }
+    function startPolling() {
+      pollOnce();
+      setInterval(pollOnce, 1000);
+    }
+    function startSse() {
+      conn.textContent = 'connecting (since=' + sinceId + ')';
+      const es = new EventSource('/chat/stream?since=' + sinceId);
+      es.onopen = () => { conn.textContent = 'live (SSE)'; };
+      es.onmessage = (e) => {
+        try { append(JSON.parse(e.data)); } catch(_) {}
+      };
+      es.onerror = () => {
+        conn.textContent = 'reconnecting...';
+        es.close();
+        setTimeout(startSse, 250);
+      };
+    }
+    function connectStream() {
+      if (window.USE_SSE) startSse(); else startPolling();
+    }
+
+    async function heartbeat() {
+      if (!me) return;
+      const fd = new FormData();
+      fd.set('user', me);
+      try { await fetch('/chat/heartbeat', { method: 'POST', body: fd }); } catch(_) {}
+    }
+
+    async function refreshWho() {
+      try {
+        const r = await fetch('/chat/who');
+        const list = await r.json();
+        if (list.length === 0) {
+          who.innerHTML = '<span style="opacity:.6">no one online</span>';
+        } else {
+          who.innerHTML = list.map(p =>
+            '<span class="pill">' + escapeHtml(p.user) + '</span>'
+          ).join('');
+        }
+      } catch(_) {}
+    }
+
+    document.getElementById('f').addEventListener('submit', async (e) => {
+      e.preventDefault();
+      if (!me) { document.getElementById('me').focus(); return; }
+      const body = document.getElementById('body');
+      const text = body.value.trim();
+      if (!text) return;
+      const fd = new FormData();
+      fd.set('author', me);
+      fd.set('body', text);
+      await fetch('/chat/send', { method: 'POST', body: fd });
+      body.value = '';
+    });
+
+    connectStream();
+    setInterval(heartbeat, 5000);
+    setInterval(refreshWho, 5000);
+    heartbeat();
+    refreshWho();
+  </script>
+</body>
+</html>