tep 0.11.0

data/lib/tep/broadcast.rb

@@ -0,0 +1,265 @@
+# Tep::Broadcast -- in-process pub-sub topic broker.
+#
+# Foundation of the Broadcast battery (Battery 2 in
+# docs/BATTERIES-DESIGN.md). Apps + later batteries (Presence,
+# LiveView) layer on top: WebSocket connections subscribe to
+# topics; publish(topic, payload) writes payload to every
+# subscribed fd.
+#
+# Public API:
+#
+#   sub_id = Tep::Broadcast.subscribe(topic, fd)
+#   Tep::Broadcast.publish(topic, payload)
+#   Tep::Broadcast.unsubscribe(sub_id)
+#   Tep::Broadcast.unsubscribe_fd(fd)    # drop ALL subs for an fd
+#
+# Subscription model is fd-based rather than block/callback-based
+# (spinel can't reliably round-trip blocks-as-values across module
+# boundaries, see memory [[spinel_widening_dispatch]]). The
+# concrete v1 use case is "deliver to a WS connection" -- the WS
+# layer keeps its accepted-socket fd, calls subscribe, and
+# Tep::Broadcast.publish writes the payload bytes to that fd.
+# Apps that need a different delivery surface (HTTP SSE, log
+# fan-out) use the same subscribe-fd shape with a different fd.
+#
+# Storage scope is per-process: subscriptions live on Tep::APP,
+# which under prefork is per-worker. Cross-worker pub-sub goes
+# through PG LISTEN/NOTIFY (Tep::Broadcast.enable_pg_backend) --
+# subscribers always register fd-local; publish() additionally
+# NOTIFY's the configured channel so peer workers' local
+# subscribers see the message too.
+#
+# `subscribe` returns an opaque subscription id (the registry
+# index at insertion time). Callers can pass it back to
+# `unsubscribe` for a single-sub drop. For WS connections that
+# subscribe to multiple topics, `unsubscribe_fd(fd)` drops every
+# subscription tied to that fd in one call -- the right shape for
+# the WS on-close hook.
+module Tep
+  module Broadcast
+    # Register a subscription for `fd` on `topic`. Returns an
+    # opaque sub_id for later unsubscribe. The fd receives raw
+    # bytes on publish -- suits SSE / log fan-out / anything that
+    # doesn't need WebSocket framing. For WS connections, prefer
+    # subscribe_ws.
+    def self.subscribe(topic, fd)
+      subs = Tep::APP.broadcast_subs
+      sub = Tep::BroadcastSubscription.new(topic, fd, 0)
+      subs.push(sub)
+      subs.length - 1
+    end
+
+    # WebSocket-bridged variant of subscribe. The fd is expected
+    # to be an established WS connection (typically a
+    # Tep::WebSocket::Connection's #fd). On publish, payload is
+    # wrapped in a WS TEXT frame via Tep::WebSocket::Driver
+    # before delivery -- the peer sees a well-formed WS message,
+    # not raw bytes that would close the connection.
+    #
+    # Cleanup is automatic: when the WS connection closes,
+    # Tep::WebSocket::Connection.dispatch_close runs the user's
+    # on_close handler and then calls unsubscribe_fd(driver.fd),
+    # dropping every subscription tied to the closed connection.
+    # Apps don't need to add their own unsubscribe; if they do,
+    # the second call just finds 0 matches (harmless).
+    def self.subscribe_ws(topic, fd)
+      subs = Tep::APP.broadcast_subs
+      sub = Tep::BroadcastSubscription.new(
+        topic, fd, Tep::WebSocket::OPCODE_TEXT)
+      subs.push(sub)
+      subs.length - 1
+    end
+
+    # Drop the subscription at `sub_id`. Note that ids are
+    # registry indexes; subsequent drops shift everything past it
+    # downward. For multi-sub drop, prefer `unsubscribe_fd`.
+    def self.unsubscribe(sub_id)
+      subs = Tep::APP.broadcast_subs
+      if sub_id < 0 || sub_id >= subs.length
+        return 0
+      end
+      subs.delete_at(sub_id)
+      0
+    end
+
+    # Drop every subscription whose fd matches. Returns the count
+    # dropped. Used by WS on-close to clean up everything a closing
+    # connection had subscribed to. Back-to-front so delete_at
+    # indices stay valid mid-loop.
+    def self.unsubscribe_fd(fd)
+      subs = Tep::APP.broadcast_subs
+      dropped = 0
+      i = subs.length - 1
+      while i >= 0
+        if subs[i].fd == fd
+          subs.delete_at(i)
+          dropped += 1
+        end
+        i -= 1
+      end
+      dropped
+    end
+
+    # Write `payload` to every subscribed fd for `topic`. Returns
+    # the number of subscriptions matched (NOT the number of
+    # successful writes -- a closed / bad fd still counts as
+    # matched; the underlying sphttp_write_str returns -1 silently
+    # on that fd). Apps that need delivery confirmation should
+    # track their own ack channel.
+    #
+    # When the PG backend is enabled (Tep::Broadcast.enable_pg_backend),
+    # publish ALSO NOTIFY's the configured channel so other workers
+    # subscribed via poll_pg_once can deliver to their local
+    # subscribers. Match count returned is the LOCAL match count;
+    # remote deliveries are best-effort and not counted here.
+    def self.publish(topic, payload)
+      matched = Tep::Broadcast.publish_local_only(topic, payload)
+      if Tep::APP.broadcast_pg_enabled != 0
+        wire = Tep::Broadcast.encode_wire(topic, payload)
+        Tep::APP.broadcast_pg_conn.notify(
+          Tep::APP.broadcast_pg_channel, wire)
+      end
+      matched
+    end
+
+    # Total subscription count across all topics. Useful for
+    # diagnostics and the v1 test surface.
+    def self.subscriber_count
+      Tep::APP.broadcast_subs.length
+    end
+
+    # Count of subscribers for one topic. O(n) over the registry;
+    # acceptable for v1 (n is typically small per worker).
+    def self.subscribers_for(topic)
+      subs = Tep::APP.broadcast_subs
+      n = 0
+      i = 0
+      while i < subs.length
+        if subs[i].topic == topic
+          n += 1
+        end
+        i += 1
+      end
+      n
+    end
+
+    # Drop every subscription. Used by tests between fixtures, and
+    # available to apps that need to fully reset (e.g. during
+    # graceful shutdown). Returns the count dropped.
+    def self.clear
+      subs = Tep::APP.broadcast_subs
+      n = subs.length
+      while subs.length > 0
+        subs.delete_at(0)
+      end
+      n
+    end
+
+    # ---- PG backend (cross-worker pub/sub) ----
+    #
+    # Opens a dedicated PG connection and issues `LISTEN <channel>`.
+    # Subsequent publishes NOTIFY this channel too -- other workers
+    # subscribed to the same channel can receive the message via
+    # poll_pg_once.
+    #
+    # `conninfo` is the libpq connect string. `channel` must be a
+    # safe SQL identifier (e.g. "tep_broadcast") since it lands
+    # inside a LISTEN / NOTIFY command unescaped.
+    #
+    # Returns 0 on success, -1 on connection or LISTEN failure.
+    def self.enable_pg_backend(conninfo, channel)
+      conn = PG::Connection.new(conninfo)
+      if conn.pgh < 0
+        return -1
+      end
+      if conn.listen(channel) < 0
+        return -1
+      end
+      Tep::APP.set_broadcast_pg_conn(conn)
+      Tep::APP.set_broadcast_pg_channel(channel)
+      Tep::APP.set_broadcast_pg_enabled(1)
+      0
+    end
+
+    def self.disable_pg_backend
+      if Tep::APP.broadcast_pg_enabled == 0
+        return 0
+      end
+      Tep::APP.broadcast_pg_conn.unlisten(Tep::APP.broadcast_pg_channel)
+      Tep::APP.broadcast_pg_conn.finish
+      Tep::APP.set_broadcast_pg_enabled(0)
+      0
+    end
+
+    # Process one notification from the PG channel: parse the wire
+    # format, dispatch to local subscribers as if `publish` had
+    # been called locally (but WITHOUT re-NOTIFYing -- that would
+    # loop). Returns 1 if a notification was processed, 0 on
+    # timeout, -1 on connection error or unenabled backend.
+    def self.poll_pg_once(timeout_ms)
+      if Tep::APP.broadcast_pg_enabled == 0
+        return -1
+      end
+      r = Tep::APP.broadcast_pg_conn.poll_notification(timeout_ms)
+      if r != 1
+        return r
+      end
+      wire = Tep::APP.broadcast_pg_conn.last_notify_payload
+      Tep::Broadcast.deliver_wire_local(wire)
+      1
+    end
+
+    # Wire format: "<topic_byte_length>:<topic><payload>".
+    # Length-prefixed so topics and payloads with arbitrary chars
+    # (commas, colons, embedded quotes, newlines) round-trip
+    # unambiguously. Encoded by `publish` when the PG backend is
+    # enabled; decoded by `deliver_wire_local`.
+    def self.encode_wire(topic, payload)
+      topic.length.to_s + ":" + topic + payload
+    end
+
+    def self.deliver_wire_local(wire)
+      colon = Tep.str_find(wire, ":", 0)
+      if colon <= 0
+        return -1
+      end
+      len_str = wire[0, colon]
+      tlen    = len_str.to_i
+      if tlen < 0 || colon + 1 + tlen > wire.length
+        return -1
+      end
+      topic   = wire[colon + 1, tlen]
+      payload = wire[colon + 1 + tlen, wire.length - colon - 1 - tlen]
+      Tep::Broadcast.publish_local_only(topic, payload)
+    end
+
+    # Same fan-out as #publish but skips the PG NOTIFY step. Used
+    # internally by poll_pg_once when delivering a cross-worker
+    # message that already came in via PG -- re-NOTIFY would cause
+    # an infinite loop.
+    #
+    # Branches on each subscription's `mode`:
+    #   * mode 0 -> raw bytes via Sock.sphttp_write_str (default,
+    #     for SSE / log fan-out / non-framed consumers).
+    #   * mode != 0 -> WebSocket frame via Tep::WebSocket::Driver.send_frame,
+    #     using the mode value as the WS opcode (1=TEXT, 2=BINARY).
+    def self.publish_local_only(topic, payload)
+      subs = Tep::APP.broadcast_subs
+      matched = 0
+      i = 0
+      while i < subs.length
+        if subs[i].topic == topic
+          if subs[i].mode == 0
+            Sock.sphttp_write_str(subs[i].fd, payload)
+          else
+            Tep::WebSocket::Driver.send_frame(
+              subs[i].fd, subs[i].mode, payload)
+          end
+          matched += 1
+        end
+        i += 1
+      end
+      matched
+    end
+  end
+end

data/lib/tep/broadcast_subscription.rb

@@ -0,0 +1,42 @@
+# Tep::BroadcastSubscription -- one entry in the Tep::Broadcast
+# subscriber registry. Pairs a topic name with an output fd. When a
+# publish matches the topic, the fd gets the payload bytes via
+# Sock.sphttp_write_str.
+#
+# fd is just an integer file descriptor: typically a WebSocket
+# connection's accepted socket fd, but the registry doesn't care
+# about the protocol on top -- it'll write to any open fd. Apps
+# integrating with WS (via Tep::WebSocket) subscribe their
+# connection fds; non-WS use cases (server-sent events, log
+# fan-out, etc.) work the same way.
+#
+# Each subscription lives in a single worker's registry. Cross-
+# worker pub-sub goes through PG LISTEN/NOTIFY (see
+# Tep::Broadcast.enable_pg_backend) which fans publishes out
+# without moving subscription state; subscribers always register
+# fd-local. See docs/BATTERIES-DESIGN.md for the broader Broadcast
+# battery design.
+module Tep
+  class BroadcastSubscription
+    attr_reader :topic   # String
+    attr_reader :fd      # Integer file descriptor
+    # Delivery mode controls how Tep::Broadcast.publish writes
+    # `payload` to `fd`:
+    #
+    #   0 = raw bytes (Sock.sphttp_write_str). The default; suits
+    #       SSE / log fan-out / anything that doesn't need framing.
+    #   1 = WebSocket TEXT frame (Tep::WebSocket::OPCODE_TEXT).
+    #   2 = WebSocket BINARY frame (Tep::WebSocket::OPCODE_BINARY).
+    #
+    # Modes 1 and 2 route through Tep::WebSocket::Driver.send_frame,
+    # so payloads land as proper WS frames the peer will accept.
+    # Apps register mode-1 subscriptions via subscribe_ws.
+    attr_reader :mode
+
+    def initialize(topic, fd, mode)
+      @topic = topic
+      @fd    = fd
+      @mode  = mode
+    end
+  end
+end

data/lib/tep/cache.rb

@@ -0,0 +1,49 @@
+# Tep::Cache -- HTTP conditional-GET evaluation (issue #152).
+#
+# A response opts in by setting a validator (res.etag / res.last_modified).
+# The server then short-circuits to 304 Not Modified (no body) when the
+# request carries a matching precondition, so the client reuses its
+# cached copy. Responses that set no validator are unaffected.
+module Tep
+  module Cache
+    # True iff `req`'s precondition says the client's cached copy of
+    # `res` is still fresh (=> answer 304). Safe methods (GET/HEAD) only.
+    def self.not_modified?(req, res)
+      v = req.verb
+      if v != "GET" && v != "HEAD"
+        return false
+      end
+
+      # ETag / If-None-Match. `*` matches anything; otherwise the quoted
+      # tag is matched as a substring so a comma-separated list of tags
+      # in If-None-Match works.
+      etag = res.headers["ETag"]
+      if etag.length > 0
+        inm = req.headers["if-none-match"]
+        if inm.length > 0
+          if inm == "*"
+            return true
+          end
+          if Tep.str_find(inm, etag, 0) >= 0
+            return true
+          end
+        end
+      end
+
+      # Last-Modified / If-Modified-Since: fresh if our copy is no newer
+      # than the client's cached date.
+      lm = res.lastmod_epoch
+      if lm > 0
+        ims = req.headers["if-modified-since"]
+        if ims.length > 0
+          ims_epoch = Sock.sphttp_parse_http_date(ims)
+          if ims_epoch >= 0 && lm <= ims_epoch
+            return true
+          end
+        end
+      end
+
+      false
+    end
+  end
+end

data/lib/tep/events.rb

@@ -0,0 +1,257 @@
+# Tep::Events -- toy/v1 event-stream emitter.
+#
+# Appends newline-delimited JSON (JSONL) in the toy/v1 envelope
+# (`docs/events-schema.md` in the toy project): one `run_start` at
+# boot, one serving event (`kind:"eval"`, `phase:"serve"`,
+# `name:"request"`) per served request, one `run_end` at shutdown.
+# The serving stream is structurally indistinguishable from a
+# training stream, so a single downstream ingest (the research-lab
+# orchestrator) consumes both.
+#
+# Standalone on purpose: any tep handler can emit (the chatbot's
+# existing OpenAI-compat endpoint, a future Tep::Llm::OpenAI::Server,
+# a Tep::Proxy gateway via on_stream_end). The full server battery
+# (Battery 7) builds on this rather than reimplementing it.
+#
+#   EVENTS = Tep::Events.new(ENV["EVENTS_JSONL"])   # "" => disabled
+#   EVENTS.run_start("gx10", "cpu", "smollm2-135m",
+#                    "/srv/models/smollm2-135m.gguf",
+#                    "{\"server\":\"tep\",\"cap\":\"infer\"}")
+#   # ... per request, after generation completes:
+#   EVENTS.inference("smollm2-135m", 12, 8, 87000,
+#     "{\"request_id\":\"cmpl-abc\",\"principal_id\":\"user:42\"," +
+#     "\"sampling\":{\"temperature\":0.7,\"max_tokens\":256}}")
+#   # ... at shutdown:
+#   EVENTS.run_end("ok")
+#
+# Schema (supersedes #79): per-request serving telemetry is
+# `kind:"eval", phase:"serve", name:"request"`. The original #79
+# decision used a distinct `kind:"inference"` to avoid overloading
+# toy/v1's `eval` (held-out training evaluation: loss/ppl/samples);
+# that disambiguator moved onto `phase`/`name` instead -- a served
+# completion is `eval`+`phase:"serve"`+`name:"request"`, training eval
+# is `eval`+`phase:"eval"`, so tao keys on the (kind, phase, name)
+# triple rather than `kind` alone. `inference` is retired. See
+# `#inference` below for the emitted shape.
+#
+# Integer-only number fields by design (a tep choice, NOT a spinel
+# constraint -- spinel supports Float fully; this module deliberately
+# avoids it for serving telemetry):
+#   * `t` is integer seconds since run_start (a JSON number; consumers
+#     reading it as float get N.0). Sub-second ordering isn't needed
+#     for serving telemetry -- per-request latency rides in wall_us.
+#   * `wall_us` (microsecond latency) is caller-measured + passed in
+#     as an int.
+#   * Floats that the schema does carry (sampling.temperature) live in
+#     the caller-built `extra` JSON string, which tep emits verbatim.
+#     Apps that want native Float support in extra can build their
+#     own JSON encoder around the float values.
+#
+# `started_at` / `ended_at` are ISO-8601 UTC via Sock.sphttp_iso8601_utc
+# (spinel's Time.now exposes only integer epoch seconds).
+module Tep
+  class Events
+    def initialize(path)
+      @path        = path   # "" disables emission (zero I/O, zero alloc)
+      @run_started = 0       # epoch seconds at run_start; basis for relative t
+      @req_count   = 0
+      @err_count   = 0
+      @tok_out     = 0
+    end
+
+    # True when a non-empty path was configured. Apps that build the
+    # emitter unconditionally can cheaply skip work when disabled.
+    def enabled?
+      @path.length > 0
+    end
+
+    # Emit `run_start` once, before any request. Establishes the
+    # relative-t origin even when emission is disabled (so a later
+    # enable mid-run wouldn't be needed; cheap either way). host /
+    # backend_kind / model_name / model_path are plain strings;
+    # config_json is a caller-built JSON object emitted verbatim.
+    def run_start(host, backend_kind, model_name, model_path, config_json)
+      @run_started = Time.now.to_i
+      if @path.length == 0
+        return 0
+      end
+      started = Sock.sphttp_iso8601_utc(@run_started)
+      # toy/v1 says host is {name, os, arch} (docs/events-schema.md);
+      # was a bare string before #115. os + arch come from uname() via
+      # Sock.sphttp_os_kind / sphttp_arch_kind.
+      line = "{" +
+        Json.encode_pair_str("kind", "run_start") + "," +
+        Json.encode_pair_str("schema", "toy/v1") + "," +
+        Json.encode_pair_int("t", 0) + "," +
+        Json.encode_pair_str("started_at", started) + "," +
+        "\"host\":{" +
+          Json.encode_pair_str("name", host) + "," +
+          Json.encode_pair_str("os",   Sock.sphttp_os_kind) + "," +
+          Json.encode_pair_str("arch", Sock.sphttp_arch_kind) +
+        "}," +
+        "\"backend\":{" + Json.encode_pair_str("kind", backend_kind) + "}," +
+        "\"model\":{" +
+          Json.encode_pair_str("name", model_name) + "," +
+          Json.encode_pair_str("path", model_path) +
+        "}," +
+        "\"config\":" + config_json +
+      "}"
+      append_line(line)
+    end
+
+    # Emit one inference-time telemetry event in the toy/v1 spec
+    # shape (#136): kind:"eval", phase:"serve", name:"request",
+    # with model + token counts + latency_us nested inside `extra`
+    # alongside whatever the caller passed in extra_json. The
+    # producer-facing API stays the same (callers pass
+    # prompt_tokens, completion_tokens, wall_us); we rename
+    # wall_us -> latency_us at the wire level.
+    #
+    # extra_json is a caller-built JSON object ("{}" if none)
+    # carrying sampling / request_id / principal_id. We strip its
+    # outer braces and merge with the spec's per-completion fields
+    # to produce the final extra object.
+    def inference(model, prompt_tokens, completion_tokens, wall_us, extra_json)
+      @req_count = @req_count + 1
+      @tok_out   = @tok_out + completion_tokens
+      if @path.length == 0
+        return 0
+      end
+      # Build the merged extra: spec fields first, then caller's
+      # fields appended (if non-empty).
+      extra = "{" +
+        Json.encode_pair_str("model", model) + "," +
+        Json.encode_pair_int("prompt_tokens", prompt_tokens) + "," +
+        Json.encode_pair_int("completion_tokens", completion_tokens) + "," +
+        Json.encode_pair_int("latency_us", wall_us)
+      caller_inner = ""
+      if extra_json.length > 2
+        # Strip the outer braces -- "{...}" -> "...".
+        caller_inner = extra_json[1, extra_json.length - 2]
+      end
+      if caller_inner.length > 0
+        extra = extra + "," + caller_inner
+      end
+      extra = extra + "}"
+      line = "{" +
+        Json.encode_pair_str("kind", "eval") + "," +
+        Json.encode_pair_str("phase", "serve") + "," +
+        Json.encode_pair_int("t", rel_t) + "," +
+        Json.encode_pair_str("name", "request") + "," +
+        "\"extra\":" + extra +
+      "}"
+      append_line(line)
+    end
+
+    # Count one server-side error (surfaced in run_end.stats.errors).
+    # Separate from emission so the counter advances even when
+    # emission is disabled.
+    def record_error
+      @err_count = @err_count + 1
+      0
+    end
+
+    # Emit `run_end` once at shutdown using LOCAL counters. reason is
+    # "completed" (clean) or "errored" (uncaught failure) -- per
+    # toy/v1, quality verdicts on the run are downstream decisions,
+    # not encoded here. Used for single-process / workers=1 deployments
+    # where the writer is the same process that handled the inferences.
+    # For workers>1, see run_end_aggregated below.
+    def run_end(reason)
+      if @path.length == 0
+        return 0
+      end
+      ended = Sock.sphttp_iso8601_utc(Time.now.to_i)
+      line = "{" +
+        Json.encode_pair_str("kind", "run_end") + "," +
+        Json.encode_pair_int("t", rel_t) + "," +
+        Json.encode_pair_str("ended_at", ended) + "," +
+        Json.encode_pair_str("reason", reason) + "," +
+        "\"stats\":{" +
+          Json.encode_pair_int("requests", @req_count) + "," +
+          Json.encode_pair_int("errors", @err_count) + "," +
+          Json.encode_pair_int("tokens_out", @tok_out) +
+        "}" +
+      "}"
+      append_line(line)
+    end
+
+    # Cross-worker run_end: re-read the JSONL + sum inference events
+    # so the emitted stats cover every worker's contribution, then
+    # emit ONE run_end with aggregated counters. Used by Tep.on_shutdown
+    # in the prefork parent (workers>1) -- worker children stop calling
+    # run_end at all; only the parent emits, after all workers have
+    # exited. Avoids cross-worker IPC entirely.
+    def run_end_aggregated(reason)
+      if @path.length == 0
+        return 0
+      end
+      reqs = 0
+      toks = 0
+      # errors aren't yet event-encoded (record_error only bumps a
+      # local counter), so cross-worker errors aren't visible here.
+      # If a future chunk emits "error" events, sum them too. For
+      # now: 0 in aggregated mode.
+      errs = 0
+      content = File.read(@path)
+      lines = content.split("\n")
+      i = 0
+      while i < lines.length
+        line_s = lines[i]
+        # #136: inference events are kind:"eval" + phase:"serve" +
+        # name:"request". Match the joint shape to avoid counting
+        # future non-request eval events (e.g. training-time eval).
+        if Tep.str_find(line_s, "\"kind\":\"eval\"", 0) >= 0 &&
+           Tep.str_find(line_s, "\"name\":\"request\"", 0) >= 0
+          reqs += 1
+          # completion_tokens now lives nested inside the `extra`
+          # object. Tep::Json.find_value_start walks only the
+          # top-level keys (it skips over nested objects), so we
+          # have to extract extra first, then get_int within it.
+          extra_pos = Json.find_value_start(line_s, "extra")
+          if extra_pos >= 0
+            obj_end = Json.skip_container(line_s, extra_pos)
+            extra_obj = line_s[extra_pos, obj_end - extra_pos]
+            toks += Json.get_int(extra_obj, "completion_tokens")
+          end
+        end
+        i += 1
+      end
+      ended = Sock.sphttp_iso8601_utc(Time.now.to_i)
+      out = "{" +
+        Json.encode_pair_str("kind", "run_end") + "," +
+        Json.encode_pair_int("t", rel_t) + "," +
+        Json.encode_pair_str("ended_at", ended) + "," +
+        Json.encode_pair_str("reason", reason) + "," +
+        "\"stats\":{" +
+          Json.encode_pair_int("requests", reqs) + "," +
+          Json.encode_pair_int("errors", errs) + "," +
+          Json.encode_pair_int("tokens_out", toks) +
+        "}" +
+      "}"
+      append_line(out)
+    end
+
+    # Seconds since run_start, clamped at 0 (a clock that goes
+    # backwards, or events before run_start, read as t=0).
+    def rel_t
+      d = Time.now.to_i - @run_started
+      if d < 0
+        d = 0
+      end
+      d
+    end
+
+    # Append one JSON line. Best-effort, append mode -- mirrors
+    # Tep::Logger's file sink. Telemetry must never fail a request, so
+    # a malformed/unwritable path degrades to a dropped line rather
+    # than a raised error reaching the handler. Callers gate on a
+    # non-empty @path before reaching here.
+    def append_line(line)
+      File.open(@path, "a") do |f|
+        f.puts(line)
+      end
+      0
+    end
+  end
+end

data/lib/tep/filter.rb

@@ -0,0 +1,21 @@
+# Tep::Filter -- before/after hooks. Override #before(req, res) and/or
+# #after(req, res). The default base methods are non-empty (they touch
+# their parameters) so Spinel correctly registers them as the dispatch
+# fallback; an empty base method body confuses the codegen and causes
+# overrides to be silently dropped.
+#
+#   class TimerFilter < Tep::Filter
+#     def after(req, res); res.headers["X-Took"] = "ok"; end
+#   end
+#   Tep.before TimerFilter.new
+module Tep
+  class Filter
+    def before(req, res)
+      0   # explicit no-op return; non-empty body keeps spinel happy
+    end
+
+    def after(req, res)
+      0
+    end
+  end
+end

data/lib/tep/handler.rb

@@ -0,0 +1,35 @@
+# Tep::Handler -- subclass and override #handle(req, res). Return a
+# string to set the body, or mutate `res` directly.
+#
+# Sinatra-style block syntax (`get '/' do ... end`) is supported via
+# the `bin/tep` build-time translator, which rewrites the block body
+# textually and wraps each block in a Handler subclass.
+#
+# Regex routes (`get %r{...} do ... end`) also live as Handler
+# subclasses: the translator emits `is_regex?` returning true plus
+# `re_match?(path)` / `re_capture(path)` baking the literal regex
+# into both methods. The literal is required because spinel can't
+# build a Regexp from a string at runtime.
+module Tep
+  class Handler
+    def handle(req, res)
+      ""
+    end
+
+    def is_regex?
+      false
+    end
+
+    def re_match?(path)
+      false
+    end
+
+    # Default returns an empty str_array. Subclasses for regex routes
+    # return up to 9 capture strings.
+    def re_capture(path)
+      empty = [""]
+      empty.delete_at(0)
+      empty
+    end
+  end
+end