tep 0.11.0

data/test/test_events.rb

@@ -0,0 +1,114 @@
+require_relative "helper"
+require "json"
+
+# Tep::Events -- toy/v1 JSONL emitter. The app emits a full
+# run_start -> inference x2 -> run_end scenario into a file and dumps
+# it back over HTTP, so the test can parse + assert the envelope.
+class TestEvents < TepTest
+  EV_PATH = "/tmp/tep_events_test.jsonl"
+
+  app_source <<~RB
+    require 'sinatra'
+
+    PATH = "#{EV_PATH}"
+
+    # One self-contained scenario: reset the file, emit the full
+    # event sequence, return the raw JSONL.
+    get '/scenario' do
+      File.write(PATH, "")
+      ev = Tep::Events.new(PATH)
+      ev.run_start("testhost", "cpu", "smollm2-135m", "/m.gguf",
+                   "{\\"server\\":\\"tep\\",\\"cap\\":\\"infer\\"}")
+      ev.inference("smollm2-135m", 12, 8, 87000,
+                   "{\\"request_id\\":\\"cmpl-abc\\",\\"principal_id\\":\\"user:42\\"}")
+      ev.inference("smollm2-135m", 5, 3, 40000,
+                   "{\\"request_id\\":\\"cmpl-def\\"}")
+      ev.run_end("ok")
+      File.read(PATH)
+    end
+
+    # Disabled emitter ("" path): enabled? false + no file written.
+    get '/disabled' do
+      File.write(PATH, "SENTINEL")
+      d = Tep::Events.new("")
+      d.run_start("h", "cpu", "m", "/p", "{}")
+      d.inference("m", 1, 1, 1, "{}")
+      d.run_end("ok")
+      # File must still hold the sentinel (disabled wrote nothing).
+      "enabled=" + d.enabled?.to_s + " file=" + File.read(PATH)
+    end
+
+    # ISO-8601 helper directly.
+    get '/iso' do
+      Sock.sphttp_iso8601_utc(0)
+    end
+  RB
+
+  def scenario_lines
+    body = get("/scenario").body
+    body.split("\n").reject(&:empty?).map { |l| JSON.parse(l) }
+  end
+
+  def test_emits_four_events_in_order
+    lines = scenario_lines
+    assert_equal 4, lines.length
+    assert_equal "run_start", lines[0]["kind"]
+    # #136: inference events are kind:"eval"+name:"request".
+    assert_equal "eval",      lines[1]["kind"]
+    assert_equal "request",   lines[1]["name"]
+    assert_equal "eval",      lines[2]["kind"]
+    assert_equal "request",   lines[2]["name"]
+    assert_equal "run_end",   lines[3]["kind"]
+  end
+
+  def test_run_start_envelope
+    rs = scenario_lines[0]
+    assert_equal "toy/v1", rs["schema"]
+    assert_equal 0, rs["t"]
+    # host is {name, os, arch} per toy/v1 (#115).
+    assert_equal "testhost", rs["host"]["name"]
+    assert_kind_of String, rs["host"]["os"]
+    assert_kind_of String, rs["host"]["arch"]
+    refute_empty rs["host"]["os"], "os field should be populated via uname()"
+    refute_empty rs["host"]["arch"], "arch field should be populated via uname()"
+    assert_equal "cpu", rs["backend"]["kind"]
+    assert_equal "smollm2-135m", rs["model"]["name"]
+    assert_equal "/m.gguf", rs["model"]["path"]
+    assert_equal "infer", rs["config"]["cap"]
+    assert_match(/\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z\z/, rs["started_at"])
+  end
+
+  def test_inference_event_fields
+    ev = scenario_lines[1]
+    # #136 spec shape: kind:"eval" + phase:"serve" + name:"request",
+    # with model + tokens + latency_us nested under extra.
+    assert_equal "eval",    ev["kind"]
+    assert_equal "serve",   ev["phase"]
+    assert_equal "request", ev["name"]
+    assert_kind_of Integer, ev["t"]
+    assert_equal "smollm2-135m", ev["extra"]["model"]
+    assert_equal 12,      ev["extra"]["prompt_tokens"]
+    assert_equal 8,       ev["extra"]["completion_tokens"]
+    assert_equal 87000,   ev["extra"]["latency_us"]
+    assert_equal "cmpl-abc", ev["extra"]["request_id"]
+    assert_equal "user:42",  ev["extra"]["principal_id"]
+  end
+
+  def test_run_end_stats_accumulate
+    re = scenario_lines[3]
+    assert_equal "ok", re["reason"]
+    assert_equal 2, re["stats"]["requests"]      # two inference calls
+    assert_equal 11, re["stats"]["tokens_out"]   # 8 + 3
+    assert_equal 0, re["stats"]["errors"]
+    assert_match(/\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z\z/, re["ended_at"])
+  end
+
+  def test_disabled_emitter_writes_nothing
+    res = get("/disabled")
+    assert_equal "enabled=false file=SENTINEL", res.body
+  end
+
+  def test_iso8601_epoch_zero
+    assert_equal "1970-01-01T00:00:00Z", get("/iso").body
+  end
+end

data/test/test_filters.rb

@@ -0,0 +1,41 @@
+require_relative "helper"
+
+# before / after filters. The translator wraps blocks into Tep::Filter
+# subclasses; spinel restricts a single filter slot per kind, so
+# multi-filter chaining is composed by the user, not registered N
+# times.
+class TestFilters < TepTest
+  app_source <<~RB
+    before do
+      response.headers["X-Before"] = "1"
+    end
+
+    after do
+      response.headers["X-After"] = "2"
+    end
+
+    get '/' do
+      "ok"
+    end
+
+    get '/echo-before' do
+      response.headers["X-Before"]
+    end
+  RB
+
+  def test_before_runs
+    res = get("/")
+    assert_equal "1", res["x-before"]
+  end
+
+  def test_after_runs
+    res = get("/")
+    assert_equal "2", res["x-after"]
+  end
+
+  def test_before_runs_before_handler
+    # The handler can read the X-Before header that the before filter set.
+    res = get("/echo-before")
+    assert_equal "1", res.body
+  end
+end

data/test/test_geohash_example.rb

@@ -0,0 +1,89 @@
+require "minitest/autorun"
+require "net/http"
+require "socket"
+require "tmpdir"
+require "fileutils"
+
+# Proves tep can compile + run an app that uses a REAL, unmodified
+# published Ruby gem (pr_geohash 1.0.0, MIT) vendored next to the app and
+# pulled in with `require_relative`. `bin/tep build` inlines app-local
+# require_relative targets into the AOT binary (no runtime gem loader),
+# so GeoHash.encode runs as native compiled code. Reference outputs below
+# are CRuby's (ruby -I lib + GeoHash.encode) -- the spinel-compiled binary
+# must match them byte-for-byte.
+#
+# Unlike the other suites this builds the real examples/geohash/app.rb in
+# place (not an app_source heredoc in a tmpdir) so the relative
+# require_relative resolves against the vendored gem.
+class TestGeohashExample < Minitest::Test
+  TEP_BIN = File.expand_path("../bin/tep", __dir__)
+  APP     = File.expand_path("../examples/geohash/app.rb", __dir__)
+  EX_DIR  = File.dirname(APP)
+
+  # vendor/spinel is generated from Gemfile.lock by bundler-spinel
+  # (`spinel-compat vendor`), not committed. Regenerate before building;
+  # skip if spinelgems isn't reachable (suite run outside the dev
+  # container, which mounts /spinelgems).
+  def ensure_vendored
+    deps = File.join(EX_DIR, "vendor", "spinel", "deps.rb")
+    return if File.exist?(deps)
+    sg = ENV["SPINELGEMS"] || "/spinelgems"
+    skip "spinelgems not at #{sg}; run `make vendor-examples`" unless File.directory?(File.join(sg, "exe"))
+    out = `cd #{EX_DIR} && ruby -I #{sg}/lib #{sg}/exe/spinel-compat vendor 2>&1`
+    skip "spinel-compat vendor failed (offline?):\n#{out}" unless $?.success? && File.exist?(deps)
+  end
+
+  def setup
+    ensure_vendored
+    @tmp  = Dir.mktmpdir("tep-geohash")
+    @bin  = File.join(@tmp, "geohash")
+    out   = `#{TEP_BIN} build #{APP} -o #{@bin} 2>&1`
+    raise "geohash example build failed:\n#{out}" unless $?.success? && File.executable?(@bin)
+    @port = 4970 + (Process.pid % 80)
+    @log  = File.join(@tmp, "app.log")
+    @pid  = Process.spawn(@bin, "-p", @port.to_s, out: @log, err: [:child, :out], pgroup: true)
+    wait_for_port(@port)
+  end
+
+  def teardown
+    if @pid
+      Process.kill("TERM", -@pid) rescue nil
+      Process.wait(@pid) rescue nil
+    end
+    FileUtils.remove_entry(@tmp) if @tmp && File.directory?(@tmp)
+  end
+
+  def wait_for_port(port, timeout: 10.0)
+    deadline = Time.now + timeout
+    while Time.now < deadline
+      begin
+        TCPSocket.new("127.0.0.1", port).close
+        return
+      rescue
+        sleep 0.05
+      end
+    end
+    raise "geohash app never bound :#{port}\n#{File.read(@log) rescue ''}"
+  end
+
+  def get(path)
+    Net::HTTP.get_response(URI("http://127.0.0.1:#{@port}#{path}")).body
+  end
+
+  # GeoHash.encode reference values (computed under CRuby).
+  def test_encode_paris_precision_8
+    assert_equal "u09tunqu", get("/geohash?lat=48.8584&lon=2.2945&precision=8")
+  end
+
+  def test_encode_tokyo_default_precision
+    assert_equal "xn76urx0zhkz", get("/geohash?lat=35.681&lon=139.767")
+  end
+
+  def test_encode_sydney_precision_6
+    assert_equal "r3gx2f", get("/geohash?lat=-33.8688&lon=151.2093&precision=6")
+  end
+
+  def test_index_mentions_the_gem
+    assert_match(/pr_geohash 1\.0\.0/, get("/"))
+  end
+end

data/test/test_http.rb

@@ -0,0 +1,137 @@
+require_relative "helper"
+
+# Tep::Http -- outbound HTTP client tests. Boots a tep app with both
+# "target" endpoints (/ping, /echo, /headers, /404) and a "client"
+# endpoint (/selfcall/:port) that uses Tep::Http to call its own
+# server. The test passes its bound port to the handler via path
+# capture, which side-steps the test harness's lack of "tell the
+# handler its own port" plumbing.
+#
+# Runs under Tep::Server::Scheduled with workers=1. The handlers do
+# outbound HTTP back to the same server -- under cooperative I/O the
+# outer fiber parks on io_wait while the accept fiber accepts the
+# inner connection, which is the only shape that works on macOS
+# (SO_REUSEPORT doesn't load-balance on Darwin). See
+# docs/MACOS-CONCURRENCY.md.
+class TestHttp < TepTest
+  app_source <<~RB
+    require 'sinatra'
+
+    # Cooperative server + single worker. The two-fiber dance is
+    # what unblocks self-calling handlers; see
+    # docs/MACOS-CONCURRENCY.md for the full path.
+    set :scheduler, :scheduled
+    set :workers, 1
+
+    get '/ping' do
+      "pong"
+    end
+
+    get '/echo/:msg' do
+      res.headers["X-Tep-Echo"] = params[:msg]
+      params[:msg]
+    end
+
+    post '/echo_body' do
+      res.headers["Content-Type"] = "text/plain"
+      req.raw_body
+    end
+
+    get '/headers_back' do
+      h = req.req_headers["x-custom"]
+      "x-custom=" + h
+    end
+
+    get '/teapot' do
+      res.set_status(418)
+      "i'm a teapot"
+    end
+
+    # The "client" endpoint -- uses Tep::Http against itself.
+    get '/selfcall/:port' do
+      r = Tep::Http.get("http://127.0.0.1:" + params[:port] + "/ping")
+      "status=" + r.status.to_s + " body=" + r.body
+    end
+
+    # Reusable client with base URL and a default header.
+    get '/instance/:port' do
+      c = Tep::Http.new("http://127.0.0.1:" + params[:port])
+      c.set_header("X-Custom", "hello-from-tep")
+      r = c.do_get("/headers_back")
+      "status=" + r.status.to_s + " body=" + r.body
+    end
+
+    # POST with a body, read it back from the echo endpoint.
+    get '/post_echo/:port' do
+      c = Tep::Http.new("http://127.0.0.1:" + params[:port])
+      r = c.do_post("/echo_body", "round trip body")
+      "status=" + r.status.to_s + " body=" + r.body
+    end
+
+    # Non-2xx round trip.
+    get '/teapot_from/:port' do
+      r = Tep::Http.get("http://127.0.0.1:" + params[:port] + "/teapot")
+      "status=" + r.status.to_s + " body=" + r.body
+    end
+
+    # Verify header parsing on the inbound side: hit /echo/<msg>
+    # which sets an X-Tep-Echo response header, then read it back.
+    get '/header_parse/:port' do
+      r = Tep::Http.get("http://127.0.0.1:" + params[:port] + "/echo/hi")
+      "echo_header=" + r.headers["x-tep-echo"]
+    end
+
+    # Bad URL: scheme not http -- send_req returns Response with status=0.
+    get '/bad_scheme' do
+      r = Tep::Http.get("ftp://127.0.0.1/")
+      "status=" + r.status.to_s
+    end
+
+    # Connect failure: nothing's listening on this port.
+    get '/connect_fail' do
+      r = Tep::Http.get("http://127.0.0.1:1/ping")
+      "status=" + r.status.to_s
+    end
+  RB
+
+  def test_selfcall_returns_pong
+    res = get("/selfcall/#{@port}")
+    assert_equal "200", res.code
+    assert_equal "status=200 body=pong", res.body
+  end
+
+  def test_instance_sends_default_header
+    res = get("/instance/#{@port}")
+    assert_equal "200", res.code
+    # The target's /headers_back echoes the X-Custom header it saw.
+    assert_equal "status=200 body=x-custom=hello-from-tep", res.body
+  end
+
+  def test_post_body_round_trips
+    res = get("/post_echo/#{@port}")
+    assert_equal "200", res.code
+    assert_equal "status=200 body=round trip body", res.body
+  end
+
+  def test_non_2xx_status_propagates
+    res = get("/teapot_from/#{@port}")
+    assert_equal "200", res.code
+    assert_equal "status=418 body=i'm a teapot", res.body
+  end
+
+  def test_response_headers_parsed
+    res = get("/header_parse/#{@port}")
+    assert_equal "200", res.code
+    assert_equal "echo_header=hi", res.body
+  end
+
+  def test_https_or_unknown_scheme_returns_zero
+    res = get("/bad_scheme")
+    assert_equal "status=0", res.body
+  end
+
+  def test_connect_failure_returns_zero
+    res = get("/connect_fail")
+    assert_equal "status=0", res.body
+  end
+end

data/test/test_http_pool.rb

@@ -0,0 +1,122 @@
+require_relative "helper"
+require "json"
+
+# Tep::Http::Pool (chunk 6.7a). The C-side pool primitives + Ruby
+# wrapper, exercised directly. No Tep::Http.send_req integration
+# yet -- that's 6.7b (needs the HTTP/1.1 keep-alive recv-N-bytes
+# path). Tests assert the pool keys, evicts LRU, and surfaces the
+# right stats.
+class TestHttpPool < TepTest
+  app_source <<~RB
+    require 'sinatra'
+
+    # Scheduled server so self-calls (sphttp_connect to our own port
+    # for the /pool/register fd) don't deadlock the single worker.
+    set :scheduler, :scheduled
+    set :workers, 1
+
+    # Reset by closing all idle fds (well past their use). Used to
+    # make per-test state deterministic.
+    post '/pool/reset' do
+      res.headers["Content-Type"] = "text/plain"
+      Tep::Http::Pool.close_idle(-1).to_s   # idle > -1s -> closes all
+    end
+
+    # Open a real socket to ourselves + checkin to the pool. Returns
+    # the fd we just registered. The test treats the fd as opaque +
+    # only asserts on the pool's behaviour.
+    post '/pool/register' do
+      res.headers["Content-Type"] = "text/plain"
+      fd = Sock.sphttp_connect("127.0.0.1", params[:port].to_i)
+      if fd < 0
+        return "connect_failed"
+      end
+      Tep::Http::Pool.release(fd, "127.0.0.1", params[:port].to_i).to_s
+    end
+
+    # Claim and report the fd (>=0 hit, -1 miss). Close on hit so
+    # the test doesn't leak.
+    get '/pool/claim/:port' do
+      res.headers["Content-Type"] = "text/plain"
+      fd = Tep::Http::Pool.claim("127.0.0.1", params[:port].to_i)
+      if fd >= 0
+        Sock.sphttp_close(fd)
+        return "hit"
+      end
+      "miss"
+    end
+
+    # Stats snapshot as JSON.
+    get '/pool/stats' do
+      res.headers["Content-Type"] = "application/json"
+      s = Tep::Http::Pool.stats
+      "{" +
+        Tep::Json.encode_pair_int("checkouts", s["checkouts"].to_i) + "," +
+        Tep::Json.encode_pair_int("checkins",  s["checkins"].to_i) + "," +
+        Tep::Json.encode_pair_int("hits",      s["hits"].to_i) + "," +
+        Tep::Json.encode_pair_int("misses",    s["misses"].to_i) +
+      "}"
+    end
+
+    # Trivial route the pool's TCP open targets -- the connect
+    # itself is what we care about; the response shape is unused.
+    get '/ping' do
+      "pong"
+    end
+  RB
+
+  def setup
+    super
+    # Drain the pool + reset counters via "miss" cycles isn't possible
+    # (stats are monotonic process-wide). Tests assert DELTAS, not
+    # absolute counts.
+    post("/pool/reset", "")
+  end
+
+  def stats_now
+    JSON.parse(get("/pool/stats").body)
+  end
+
+  def test_release_then_claim_is_a_hit
+    s0 = stats_now
+    # Register an fd in the pool.
+    res = post("/pool/register?port=#{@port}", "")
+    assert_equal "200", res.code
+    assert_equal "0", res.body, "release should succeed (returned 0)"
+
+    # First claim should HIT.
+    res = get("/pool/claim/#{@port}")
+    assert_equal "hit", res.body, "expected pool hit for the released fd"
+
+    s1 = stats_now
+    assert_equal s0["hits"] + 1, s1["hits"]
+    assert_equal s0["checkins"] + 1, s1["checkins"]
+  end
+
+  def test_claim_on_empty_pool_is_a_miss
+    s0 = stats_now
+    res = get("/pool/claim/#{@port}")
+    assert_equal "miss", res.body
+    s1 = stats_now
+    assert_equal s0["misses"] + 1, s1["misses"]
+    assert_equal s0["hits"], s1["hits"]
+  end
+
+  def test_second_claim_after_one_release_misses
+    # Register one fd; claim it; second claim should miss.
+    post("/pool/register?port=#{@port}", "")
+    res = get("/pool/claim/#{@port}")
+    assert_equal "hit", res.body
+    res = get("/pool/claim/#{@port}")
+    assert_equal "miss", res.body
+  end
+
+  def test_close_idle_removes_pooled_fds
+    # Register an fd then sweep with idle_seconds=-1 (every fd is
+    # older than -1s from "now") -- subsequent claim should miss.
+    post("/pool/register?port=#{@port}", "")
+    post("/pool/reset", "")
+    res = get("/pool/claim/#{@port}")
+    assert_equal "miss", res.body
+  end
+end

data/test/test_http_pool_send.rb

@@ -0,0 +1,57 @@
+require_relative "helper"
+require "json"
+
+# 6.7b: Tep::Http.send_req reuses pooled keep-alive connections.
+#
+# Pooling lives in the BLOCKING send path (prefork), and pool state is
+# per-worker -- so the two send_req calls must share one worker. We
+# can't self-call here (blocking + workers=1 would deadlock; multi-
+# worker makes pool hits nondeterministic), so the client makes both
+# calls to a SEPARATE upstream process within one handler. One worker,
+# one pool: the second call reuses the connection the first released.
+class TestHttpPoolSend < TepTest
+  UPSTREAM = <<~UP
+    require 'sinatra'
+    set :workers, 1
+    get '/ping' do
+      "pong"
+    end
+  UP
+
+  app_source <<~RB
+    require 'sinatra'
+    set :workers, 1
+
+    # Two sequential GETs to the same upstream in ONE handler (one
+    # worker -> one pool). Reports the hits delta + both bodies so the
+    # test asserts both reuse and correctness.
+    get '/twocalls/:uport' do
+      res.headers["Content-Type"] = "application/json"
+      base = "http://127.0.0.1:" + params[:uport]
+      h0 = Tep::Http::Pool.stats["hits"].to_i
+      r1 = Tep::Http.get(base + "/ping")
+      r2 = Tep::Http.get(base + "/ping")
+      h1 = Tep::Http::Pool.stats["hits"].to_i
+      "{" +
+        Tep::Json.encode_pair_int("hits_delta", h1 - h0) + "," +
+        Tep::Json.encode_pair_str("b1", r1.body) + "," +
+        Tep::Json.encode_pair_str("b2", r2.body) +
+      "}"
+    end
+  RB
+
+  def setup
+    super
+    @up_port = TepHarness.spawn_app(UPSTREAM, mode: :sinatra, workers: 1)
+  end
+
+  def test_send_req_reuses_pooled_connection
+    res = get("/twocalls/#{@up_port}")
+    assert_equal "200", res.code
+    j = JSON.parse(res.body)
+    assert_equal "pong", j["b1"]
+    assert_equal "pong", j["b2"]
+    assert_equal 1, j["hits_delta"],
+      "second send_req to the same upstream should reuse the pooled connection"
+  end
+end