tep 0.11.6 → 0.11.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33b663dcc38571d71f8a729f7ed1f8da6ea8a89e1eb6bd49619beac977da2727
-  data.tar.gz: af7b47e7e3440372325744d1274e70e41216db757ac224ca2364c1a422b5064a
+  metadata.gz: f69c2e25a18f0ad96cc6a765e9655cc130c35ecc90fe006715409868c8e69e72
+  data.tar.gz: bfe36187e4d9565b03c58b37ac1e0243f96dbe3b888752983acc6d6f87595fc7
 SHA512:
-  metadata.gz: ed5ce816c591c5464d624e3094798d3ce8c8c03c7128e3881541cf874a0735e62f468d7d4f781e793e6ae02f2bcb642119fdc49157394acb69cb027a014d9b6e
-  data.tar.gz: 484a1cdae65a65cbe5da98d8c2aa22add1b4a562e35ab7cfb38f9137856bcad77ad773b07d191fb425a5e6307fe18a71856d47ad3766e8a03191622314ba2989
+  metadata.gz: 65c8b19acd15c4548a98a3db081e5f0c9d5b73068b8e99744e9064a35f1a4cdc920aa0a447061d708cd889155c5034efc6303532abee38869b193b5a1d10241d
+  data.tar.gz: 6307c6fefde2da3b7a3e67480d1c59ab051527c62796d03971fe25e1596c0fbee7271ea9d9d531b458ec310b99758e9d81b075d1f4c139d9500c25afc677a71a

data/README.md

@@ -22,7 +22,7 @@ SQLite, opt-in PostgreSQL, WebSockets, Broadcast + Presence + LiveView,
 an MCP tool catalog, TLS, a pooled HTTP client, and an OpenAI-compatible
 LLM client + server.
 
-> **Current release:** [v0.11.6](https://github.com/OriPekelman/tep/releases/tag/v0.11.6)
+> **Current release:** [v0.11.7](https://github.com/OriPekelman/tep/releases/tag/v0.11.7)
 > on [RubyGems](https://rubygems.org/gems/tep) — `gem install tep`.
 > Pre-alpha; API still in motion.
 

data/bin/tep

@@ -86,7 +86,14 @@ def fatal(msg)
 end
 
 # Build the translated Ruby source from a Sinatra-style file.
-def translate(input_path)
+#
+# Strict by default (mirror condition 3, docs/mirrors/sinatra.md):
+# any construct the translator would drop -- Rack `use`, `helpers`,
+# unknown `set` keys, on_stop, malformed DSL blocks, missing views --
+# is a fatal error, because building anyway produces a binary that
+# silently diverges from what the same source does under real
+# sinatra. `--lax` (or TEP_LAX=1) restores warn-and-continue.
+def translate(input_path, lax: ENV["TEP_LAX"] == "1")
   raw_source = File.read(input_path)
 
   # Split off `__END__` inline templates. Sinatra's convention is
@@ -909,7 +916,19 @@ def translate(input_path)
   RB
   out << ""
 
-  warnings.each { |w| warn "tep: #{w}" }
+  if warnings.any?
+    if lax
+      warnings.each { |w| warn "tep: #{w}" }
+      warn "tep: --lax: built with #{warnings.length} dropped construct(s); " \
+           "behaviour diverges from real sinatra where they applied"
+    else
+      warnings.each { |w| warn "tep: error: #{w}" }
+      fatal "#{warnings.length} unsupported construct(s) -- refusing to build " \
+            "a binary that silently diverges (docs/mirrors/sinatra.md, " \
+            "condition 3). Re-run with --lax (or TEP_LAX=1) to drop them " \
+            "with a warning instead."
+    end
+  end
 
   out.join("\n")
 end
@@ -1596,8 +1615,12 @@ def rewrite_block(src, force_string: true)
   # `headers["X"] = "y"` -> `res.headers[...]` when not already qualified
   s = s.gsub(/(?<![\w.])headers\[/, "res.headers[")
 
-  # `cookies["k"]` -> `req.cookies["k"]` when not already qualified
-  s = s.gsub(/(?<![\w.])cookies\[/, "req.cookies[")
+  # `cookies["k"] = v` (write) -> direct hash write; `cookies["k"]`
+  # (read) -> Tep.cookie(req, "k"), which nil-guards the miss: the
+  # documented cookies[] contract is ""-on-miss (test_cookies pins
+  # it), but the underlying hash reads nil for a missing key.
+  s = s.gsub(/(?<![\w.])cookies\[([^\]]*)\]\s*=(?![=~])/, 'req.cookies[\1] =')
+  s = s.gsub(/(?<![\w.])cookies\[([^\]]*)\]/, 'Tep.cookie(req, \1)')
 
   # `erb :name`              -> `tep_view_name(Tep.str_hash, req.ivars)`
   # `erb :name, locals: {a: "b", c: "d"}` -> build a String=>String
@@ -1697,6 +1720,12 @@ def rewrite_block(src, force_string: true)
   # to string keys.
   s = s.gsub(/(req\.params)\[:(\w+)\]/, '\1["\2"]')
 
+  # Read form -> Tep.param(req, k), which nil-guards the miss: tep's
+  # documented params[] contract is ""-on-miss (test_params pins it;
+  # ledgered as a sinatra divergence -- sinatra reads nil). Writes
+  # (assignment) stay direct hash writes.
+  s = s.gsub(/req\.params\[([^\]]*)\](?!\s*=[^=~])/, 'Tep.param(req, \1)')
+
   # `"#{params['x']}"` interpolation works fine after the params rewrite.
 
   # String-coerce the last expression of the block body. Spinel's
@@ -2176,23 +2205,25 @@ def cmd_build(args)
   input    = nil
   out_path = nil
   c_only   = false
+  lax      = ENV["TEP_LAX"] == "1"
   i = 0
   while i < args.length
     a = args[i]
     case a
     when "-o" then out_path = args[i + 1]; i += 2
     when "-c" then c_only = true; i += 1
+    when "--lax" then lax = true; i += 1
     when /^-/ then fatal "unknown option: #{a}"
     else
       input ||= a
       i += 1
     end
   end
-  fatal "usage: tep build app.rb [-o out] [-c]" unless input
+  fatal "usage: tep build app.rb [-o out] [-c] [--lax]" unless input
 
   base = File.basename(input, ".rb")
   out_path ||= File.join(File.dirname(input), base)
-  translated = translate(input)
+  translated = translate(input, lax: lax)
 
   # Spinel's require_relative resolves against the source file's
   # directory and chokes on absolute paths. Drop the generated file
@@ -2230,8 +2261,10 @@ def cmd_run(args)
 end
 
 def cmd_translate(args)
-  input = args.first or fatal "usage: tep translate app.rb"
-  puts translate(input)
+  lax = ENV["TEP_LAX"] == "1"
+  lax = true if args.delete("--lax")
+  input = args.first or fatal "usage: tep translate app.rb [--lax]"
+  puts translate(input, lax: lax)
 end
 
 case ARGV.shift
@@ -2243,9 +2276,14 @@ when nil, "-h", "--help"
     tep -- Sinatra-flavoured framework that compiles to a native binary.
 
     Usage:
-      tep build app.rb [-o out] [-c]    translate + spinel-compile
-      tep run   app.rb [-p PORT] [-w N] build then exec
-      tep translate app.rb               print the translated Ruby
+      tep build app.rb [-o out] [-c] [--lax]  translate + spinel-compile
+      tep run   app.rb [-p PORT] [-w N]       build then exec
+      tep translate app.rb [--lax]            print the translated Ruby
+
+    Strict by default: source constructs tep would have to drop
+    (Rack `use`, `helpers do`, unknown `set` keys, ...) fail the
+    build rather than silently diverging from real sinatra.
+    `--lax` (or TEP_LAX=1) downgrades them to warnings.
 
     Source compatibility: top-level `get '/path' do ... end`,
     `post`, `put`, `patch`, `delete`, `before`, `after`, `not_found`,

data/examples/blog/app.rb

@@ -332,6 +332,7 @@ end
 post '/api/posts' do
   res.headers["Content-Type"] = "application/json"
   auth = req.req_headers["authorization"]
+  auth = "" if auth.nil?     # missing header reads as nil (tep#235)
   bearer = ""
   if auth.length > 7 && auth[0, 7] == "Bearer "
     bearer = auth[7, auth.length - 7]

data/examples/experiments/app.rb

@@ -218,7 +218,9 @@ end
 # baked in. Here, accept an X-Demo-Cap-Run header as the
 # capability source so humans can drive the demo with curl.
 before do
-  if req.req_headers["x-demo-cap-run"].length > 0
+  cap = req.req_headers["x-demo-cap-run"]
+  cap = "" if cap.nil?     # missing header reads as nil (tep#235)
+  if cap.length > 0
     req.identity = Tep::Identity.new(
       "user:demo", nil, [:run_experiments])
   end

data/lib/tep/app.rb

@@ -187,6 +187,7 @@ module Tep
       secret = Tep.session_secret
       if secret.length > 0
         cv = req.cookies[Tep::COOKIE_NAME]
+        cv = "" if cv.nil?
         if cv.length > 0
           req.session.load_from(cv, secret)
         end

data/lib/tep/auth_bearer_token.rb

@@ -47,6 +47,7 @@ module Tep
     # signature / expired / malformed payload.
     def self.try(req)
       header = req.req_headers["authorization"]
+      header = "" if header.nil?
       if header.length < 8 || header[0, 7] != "Bearer "
         return nil
       end

data/lib/tep/auth_session_cookie.rb

@@ -84,12 +84,16 @@ module Tep
     # if the session has no identity (no prior #set call, or after
     # #clear) or the stored identity is expired.
     def self.try(req)
+      # Session#get on a missing key reads as nil (sinatra-parity Hash
+      # semantics; same class as tep#235) -- guard before String calls.
       sub = req.session.get("identity_sub")
+      sub = "" if sub.nil?
       if sub.length == 0
         return nil
       end
 
       exp_str = req.session.get("identity_exp")
+      exp_str = "" if exp_str.nil?
       if exp_str.length > 0
         exp = exp_str.to_i
         if exp > 0 && Time.now.to_i >= exp
@@ -98,9 +102,11 @@ module Tep
       end
 
       caps_str = req.session.get("identity_caps")
+      caps_str = "" if caps_str.nil?
       caps = Tep::AuthBearerToken.parse_caps(caps_str)
 
       delegate_str = req.session.get("identity_delegate")
+      delegate_str = "" if delegate_str.nil?
       delegation = Tep::AuthBearerToken.parse_delegate(delegate_str)
 
       Tep::Identity.new(sub, delegation, caps)

data/lib/tep/cache.rb

@@ -18,8 +18,10 @@ module Tep
       # tag is matched as a substring so a comma-separated list of tags
       # in If-None-Match works.
       etag = res.headers["ETag"]
+      etag = "" if etag.nil?
       if etag.length > 0
         inm = req.headers["if-none-match"]
+        inm = "" if inm.nil?
         if inm.length > 0
           if inm == "*"
             return true
@@ -35,6 +37,7 @@ module Tep
       lm = res.lastmod_epoch
       if lm > 0
         ims = req.headers["if-modified-since"]
+        ims = "" if ims.nil?
         if ims.length > 0
           ims_epoch = Sock.sphttp_parse_http_date(ims)
           if ims_epoch >= 0 && lm <= ims_epoch

data/lib/tep/http.rb

@@ -9,10 +9,12 @@
 # plumbing (sphttp_connect, sphttp_set_nonblock, sphttp_recv_*); the
 # missing piece is the HTTP/1.0 client on top.
 #
-# Scope (v1)
-# ----------
-# * **HTTP only** -- no TLS. Talk to internal services, the local
-#   Ollama API, vLLM, your own tep-backed sidecars.
+# Scope
+# -----
+# * **http + https** -- outbound TLS landed in #150
+#   (Sock.sphttp_connect_tls; non-blocking handshake under the
+#   scheduled server). Talk to internal services, the local Ollama
+#   API, vLLM, your own tep-backed sidecars, or external https APIs.
 # * **HTTP/1.0 + Connection: close** -- one socket per request,
 #   read until EOF. No keep-alive, no pipelining.
 # * **No chunked-transfer reading** -- assumes Content-Length or
@@ -24,7 +26,7 @@
 #
 # These limits cover the dashboard's needs (talking to local
 # inference backends) and the bulk of "hit an internal API"
-# workloads. HTTPS + keep-alive + chunked land as a v2 surface.
+# workloads. Keep-alive + chunked reading land as a v2 surface.
 #
 # API shape
 # ---------

data/lib/tep/openai_server.rb

@@ -141,7 +141,10 @@ module Tep
         def self.serve!(events_jsonl = "")
           events = Tep::Events.new(events_jsonl)
           Tep::APP.set_openai_events(events)
+          # ENV[] reads nil for an unset variable (CRuby semantics) --
+          # guard before String calls (same class as tep#235).
           host = ENV["HOSTNAME"]
+          host = "" if host.nil?
           if host.length == 0
             host = "tep"
           end

data/lib/tep/parser.rb

@@ -55,8 +55,11 @@ module Tep
       end
 
       # Parse Cookie header into req.cookies. Format: "k=v; k2=v2; ...".
-      # Whitespace around `;` is allowed and stripped.
+      # Whitespace around `;` is allowed and stripped. A request with no
+      # Cookie header reads as nil (don't call methods on it: spinel's
+      # unresolved-call gate raises NoMethodError, same as CRuby).
       cookie_blob = req.req_headers["cookie"]
+      cookie_blob = "" if cookie_blob.nil?
       if cookie_blob.length > 0
         cookie_blob.split(";").each do |pair|
           eq = Tep.str_find(pair, "=", 0)

data/lib/tep/pg.rb

@@ -190,6 +190,16 @@ module PG
       @last_sqlstate = ""
       @last_error_message = ""
       @last_result_rh = -1
+      # Never-connected sentinel: PG::Connection.new("") is the
+      # type-seeding shape (see the _tep_seed_pg_* block). Exec on a
+      # seed conn returns the empty-Result sentinel instead of
+      # raising -- a REAL failed connect (non-empty conninfo) still
+      # raises PG::UnableToSend on first exec, per the documented
+      # non-raising-connect / raising-exec contract.
+      @seed_conn = false
+      if opts.is_a?(String) && opts.length == 0
+        @seed_conn = true
+      end
       if opts.is_a?(String)
         if Tep::Scheduler.scheduled_context?
           h = Connection.async_connect(opts)
@@ -382,6 +392,9 @@ module PG
       Pg.tep_pg_set_nonblocking(@pgh, 1)
       ok = Pg.tep_pg_send_query(@pgh, sql)
       if ok != 1
+        if @seed_conn
+          return PG::Result.new(-1)
+        end
         Connection.raise_send_failure(self)
       end
       Connection.drain_send(@pgh)
@@ -421,6 +434,9 @@ module PG
       Pg.tep_pg_set_nonblocking(@pgh, 1)
       ok = Pg.tep_pg_send_query_params(@pgh, sql)
       if ok != 1
+        if @seed_conn
+          return PG::Result.new(-1)
+        end
         Connection.raise_send_failure(self)
       end
       Connection.drain_send(@pgh)

data/lib/tep/request.rb

@@ -51,11 +51,16 @@ module Tep
     def headers; @req_headers; end
     def body;    @raw_body;    end
 
-    # Spinel's Hash[k] returns "" for missing string keys, not nil --
-    # so an empty Connection header looks the same as no header at all.
-    # We treat both as "use HTTP/1.1 default behaviour".
+    # A missing header reads as nil (CRuby Hash semantics; spinel's
+    # unresolved-call gate raises NoMethodError on nil receivers, same
+    # as CRuby would). Guard before calling String methods; an empty
+    # header and no header both mean "use HTTP/1.1 default behaviour".
+    # NOTE: guard with `x = "" if x.nil?`, not `x || ""` -- the ||-form
+    # mis-compiles at spinel pin f6d5eef (blanks the hit value).
     def keep_alive?
-      lc = @req_headers["connection"].downcase
+      lc = @req_headers["connection"]
+      lc = "" if lc.nil?
+      lc = lc.downcase
       if lc == "close"
         return false
       end
@@ -70,7 +75,9 @@ module Tep
     end
 
     def form?
-      @req_headers["content-type"].downcase.start_with?("application/x-www-form-urlencoded")
+      ct = @req_headers["content-type"]
+      ct = "" if ct.nil?
+      ct.downcase.start_with?("application/x-www-form-urlencoded")
     end
 
     # True when the request body is a multipart/form-data submission
@@ -78,7 +85,9 @@ module Tep
     # or carrying file inputs). Tep::Multipart.parse handles the
     # text fields; file-upload parts are skipped in v1.
     def multipart?
-      @req_headers["content-type"].downcase.start_with?("multipart/form-data")
+      ct = @req_headers["content-type"]
+      ct = "" if ct.nil?
+      ct.downcase.start_with?("multipart/form-data")
     end
 
     # ---- Rack::Request-style accessors (reads only, no .ip yet) ----
@@ -99,6 +108,7 @@ module Tep
     # proxy sets.
     def scheme
       proto = @req_headers["x-forwarded-proto"]
+      proto = "" if proto.nil?
       if proto.length > 0
         return proto.downcase
       end

data/lib/tep/server.rb

@@ -231,7 +231,11 @@ module Tep
         res.set_body("")
       end
 
-      if res.body.length > 0 && !res.headers.key?("Content-Type")
+      # Default Content-Type even on empty bodies (redirects!) --
+      # sinatra/Rack parity, caught by the differential oracle
+      # (test/differential/runner.rb). 204/304 are the exception:
+      # Rack strips entity headers there, so we don't default one in.
+      if !res.headers.key?("Content-Type") && res.status != 204 && res.status != 304
         res.headers["Content-Type"] = "text/html; charset=utf-8"
       end
       res.headers["Content-Length"] = res.body.length.to_s

data/lib/tep/server_scheduled.rb

@@ -327,11 +327,14 @@ module Tep
           res.file_path = ""
         end
 
-        # Default Content-Type for inline-body responses. Matches
-        # Tep::Server#send; without it, the Security::Headers nosniff
-        # default leaves the browser refusing to interpret an erb
-        # response as HTML.
-        if res.file_path.length == 0 && res.body.length > 0 && !res.headers.key?("Content-Type")
+        # Default Content-Type for inline-body responses -- including
+        # empty ones (redirects), for sinatra/Rack parity (differential
+        # oracle finding; matches Tep::Server). 204/304 excepted: Rack
+        # strips entity headers there. Without a Content-Type, the
+        # Security::Headers nosniff default leaves the browser refusing
+        # to interpret an erb response as HTML.
+        if res.file_path.length == 0 && !res.headers.key?("Content-Type") &&
+           res.status != 204 && res.status != 304
           res.headers["Content-Type"] = "text/html; charset=utf-8"
         end
         reason = Tep.reason(res.status)

data/lib/tep/session.rb

@@ -24,7 +24,15 @@ module Tep
     # exposes only named methods; the translator rewrites
     # `session[k] = v` to `session.set(k, v)` and `session[k]` to
     # `session.get(k)` for source compatibility with Sinatra.
-    def get(k);    @data[k];                          end
+    # A missing key reads as "" -- the documented `session[k]` DSL
+    # contract (test_sessions pins it; a deliberate divergence from
+    # sinatra's nil-on-miss, ledgered in docs/mirrors/sinatra.md).
+    # The raw @data hash reads nil for a miss.
+    def get(k)
+      v = @data[k]
+      v = "" if v.nil?
+      v
+    end
     def set(k, v); @data[k] = v; @dirty = true;       end
     def has?(k);   @data.key?(k);                     end
     def length;    @data.length;                      end

data/lib/tep/version.rb

@@ -1,3 +1,3 @@
 module Tep
-  VERSION = "0.11.6"
+  VERSION = "0.11.7"
 end

data/lib/tep/websocket/handshake.rb

@@ -26,13 +26,16 @@ module Tep
         end
 
         # Upgrade + Connection headers (downcased per Tep::Request).
+        # A missing header reads as nil; treat it as absent ("").
         upgrade = req.headers["upgrade"]
+        upgrade = "" if upgrade.nil?
         if Handshake.icontains(upgrade, "websocket") == false
           out.valid = false
           out.reason = "missing/invalid Upgrade"
           return out
         end
         conn = req.headers["connection"]
+        conn = "" if conn.nil?
         if Handshake.icontains(conn, "upgrade") == false
           out.valid = false
           out.reason = "missing/invalid Connection"
@@ -49,6 +52,7 @@ module Tep
 
         # Sec-WebSocket-Key: 24-char base64 (16-byte nonce).
         key = req.headers["sec-websocket-key"]
+        key = "" if key.nil?
         if key.length == 0
           out.valid = false
           out.reason = "missing Sec-WebSocket-Key"
@@ -60,7 +64,9 @@ module Tep
 
         # 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"])
+        proto_blob = req.headers["sec-websocket-protocol"]
+        proto_blob = "" if proto_blob.nil?
+        out.protocols = Handshake.split_csv(proto_blob)
         out
       end
 

data/lib/tep.rb

@@ -129,6 +129,28 @@ module Tep
     h
   end
 
+  # Read a request cookie. A missing cookie reads as "" -- that is the
+  # documented `cookies["k"]` DSL contract (test_cookies pins it) --
+  # while the underlying hash reads nil for a missing key. bin/tep
+  # rewrites `cookies[k]` reads to this call.
+  def self.cookie(req, k)
+    v = req.cookies[k]
+    v = "" if v.nil?
+    v
+  end
+
+  # Read a request param. A missing param reads as "" -- tep's
+  # documented `params[k]` DSL contract (test_params pins it; a
+  # deliberate divergence from sinatra's nil, ledgered in
+  # docs/mirrors/sinatra.md). bin/tep rewrites `params[k]` reads to
+  # this call; direct `req.params[...]` access keeps raw Hash
+  # semantics (nil on miss).
+  def self.param(req, k)
+    v = req.params[k]
+    v = "" if v.nil?
+    v
+  end
+
   # str_find -- naive substring search returning the int position of
   # `needle` in `s` starting from `start`, or -1 if not found.
   #

data/test/differential/10_semantics.rb

@@ -0,0 +1,56 @@
+# Differential fixture: core routing/response semantics that both real
+# sinatra and tep claim. This file must stay valid under BOTH dialects
+# (docs/mirrors/sinatra.md condition 2) -- no tep extensions
+# (request.headers, cookies[], set_cookie) and no sinatra-contrib.
+require 'sinatra'
+
+get '/hi/:name' do
+  'hi ' + params[:name]
+end
+
+get '/two/:a/:b' do
+  params[:a] + '-' + params[:b]
+end
+
+get '/q' do
+  q = params[:q]
+  q = '' if q.nil?
+  'q=' + q
+end
+
+post '/form' do
+  t = params[:text]
+  t = '' if t.nil?
+  'text=' + t
+end
+
+get '/redir' do
+  redirect '/hi/there'
+end
+
+get '/redir301' do
+  redirect '/hi/there', 301
+end
+
+get '/teapot' do
+  status 418
+  'short and stout'
+end
+
+get '/halted' do
+  halt 401, 'no entry'
+end
+
+get '/hdr' do
+  headers['x-custom'] = 'yes'
+  'ok'
+end
+
+get '/ct' do
+  content_type 'text/plain'
+  'plain body'
+end
+
+not_found do
+  'nope: ' + request.path
+end

data/test/differential/11_matrix.rb

@@ -0,0 +1,63 @@
+# Differential fixture: broader Phase A matrix coverage. Valid under
+# BOTH real sinatra and tep (docs/mirrors/sinatra.md condition 2).
+# Divergent read-APIs (splat value, regex captures, cookies DSL) are
+# deliberately NOT read here -- routes only exercise surface both
+# dialects share; the known divergences are pinned by the runner's
+# ledgered-divergence assertions instead.
+require 'sinatra'
+
+put '/verb' do
+  'put-ok'
+end
+
+patch '/verb' do
+  'patch-ok'
+end
+
+# Splat: single-segment matches in both dialects. The VALUE is not
+# read (sinatra: params['splat'] array; tep: no exposed value) and
+# multi-segment matching diverges -- see runner ledger L5.
+get '/files/*' do
+  'file-route'
+end
+
+# Regex route, no capture reads (sinatra: params['captures']; tep:
+# params["1"] -- runner ledger L6). Unanchored on purpose: sinatra's
+# mustermann raises at boot on ^/$ anchors (it anchors implicitly),
+# while tep accepts them -- anchored regex routes are tep-only (L6).
+get %r{/rx/\d+} do
+  'rx-route'
+end
+
+# after-filter mutating a response header; both dialects claim it.
+after do
+  headers['x-after'] = 'ran'
+end
+
+get '/afterhdr' do
+  'body'
+end
+
+# Query-string URL decoding: %xx and `+` as space.
+get '/dec' do
+  v = params[:v]
+  v = '' if v.nil?
+  'v=[' + v + ']'
+end
+
+# Multipart/form-data: text fields merge into params in both dialects
+# (file parts are tep-ledgered as skipped; not exercised here).
+post '/mp' do
+  f = params[:field]
+  f = '' if f.nil?
+  'field=[' + f + ']'
+end
+
+# Bare halt (status only, empty body).
+get '/gone' do
+  halt 410
+end
+
+not_found do
+  'nf: ' + request.path
+end

data/test/differential/Gemfile

@@ -0,0 +1,14 @@
+# Gems for the differential oracle ONLY (test/differential/runner.rb):
+# real sinatra as the behavioural reference. Deliberately a separate
+# Gemfile so sinatra never becomes a dependency of tep itself -- the
+# main Gemfile stays rake/minitest/base64/rbs.
+#
+#   BUNDLE_GEMFILE=test/differential/Gemfile bundle install
+#   ruby test/differential/runner.rb
+
+source "https://rubygems.org"
+
+gem "sinatra"
+gem "rackup"
+gem "puma"
+gem "minitest"

data/test/differential/runner.rb

@@ -0,0 +1,250 @@
+# Differential oracle: real sinatra vs tep (mirror condition 2,
+# docs/mirrors/sinatra.md). Boots each fixture app twice -- once under
+# CRuby + the real sinatra gem, once as a tep-compiled binary -- fires
+# the same requests at both, and diffs status / body / declared
+# headers. Any divergence not recorded in LEDGER is a failure: new
+# divergences must be either fixed or explicitly ledgered with a
+# reason (which then belongs in docs/mirrors/sinatra.md too).
+#
+# Not part of `rake test` (FileList only globs test/test_*.rb): the
+# sinatra gem must never become a tep dependency. Run explicitly:
+#
+#   gem install sinatra rackup puma       # or bundle with ./Gemfile
+#   ruby test/differential/runner.rb
+#
+# CI runs this as its own job (`differential` in ci.yml).
+
+begin
+  gem "sinatra"
+rescue Gem::LoadError
+  abort "differential runner needs the sinatra gem (gem install sinatra rackup puma)"
+end
+
+require "minitest/autorun"
+require "net/http"
+require "socket"
+require "tmpdir"
+require "fileutils"
+require "shellwords"
+require "rbconfig"
+
+module Differential
+  TEP_BIN   = File.expand_path("../../bin/tep", __dir__)
+  ROOT      = File.expand_path("../..", __dir__)
+  PORT_BASE = 5300 + ($$ % 100)
+
+  @port = PORT_BASE
+  def self.next_port
+    @port += 1
+  end
+
+  # ---- the exclusion ledger, harness-side ----
+  # Divergences we accept, keyed by response facet. Every entry needs a
+  # reason and should be mirrored in docs/mirrors/sinatra.md. The
+  # runner *normalizes* these away before diffing; anything left is a
+  # real, unledgered divergence and fails the run.
+  #
+  # L1 content-type charset: sinatra appends ";charset=utf-8" to text
+  #    types; tep emits the bare type.
+  # L2 protection headers: sinatra ships rack-protection by default
+  #    (x-xss-protection / x-content-type-options / x-frame-options);
+  #    tep's Tep::Security::Headers is opt-in.
+  # L3 server/date/connection/content-length: transport furniture --
+  #    body equality already covers length.
+  # L4 redirect Location absolutization: sinatra expands "/path" to an
+  #    absolute http://host:port/path; tep echoes the path as given.
+  #    Compare path component only.
+  # L5 splat scope: sinatra's `*` spans path segments; tep's matches a
+  #    single trailing segment. Pinned per-request via `diverge:`.
+  # L6 divergent read APIs, not exercised by fixtures: regex captures
+  #    (sinatra params['captures'] / block args vs tep params["1".."9"]),
+  #    splat value (params['splat'] array vs none), request.headers
+  #    (tep extension), bare set_cookie/cookies[] (tep mirrors
+  #    contrib-style helpers), and ^/$-anchored regex routes (tep
+  #    accepts; sinatra's mustermann raises at boot -- anchor-free
+  #    regexes are the portable form). Fixtures avoid these; the
+  #    ledger in docs/mirrors/sinatra.md records them.
+  IGNORED_HEADERS = %w[
+    server date connection content-length x-xss-protection
+    x-content-type-options x-frame-options keep-alive
+  ].freeze
+
+  def self.normalize_content_type(v)
+    v.to_s.split(";").first.to_s.strip.downcase # L1
+  end
+
+  def self.normalize_location(v)
+    return "" if v.nil?
+    v.sub(%r{\Ahttps?://[^/]+}, "") # L4
+  end
+
+  Server = Struct.new(:pid, :port, :log) do
+    def stop
+      return unless pid
+      Process.kill("TERM", -pid) rescue Process.kill("TERM", pid) rescue nil
+      Process.wait(pid) rescue nil
+    end
+  end
+
+  def self.wait_for_port(port, pid, timeout: 15.0)
+    deadline = Time.now + timeout
+    while Time.now < deadline
+      begin
+        TCPSocket.new("127.0.0.1", port).close
+        return true
+      rescue Errno::ECONNREFUSED
+        raise "server died before binding :#{port}" if Process.wait(pid, Process::WNOHANG) rescue nil
+        sleep 0.05
+      end
+    end
+    raise "server on :#{port} didn't come up"
+  end
+
+  def self.boot_sinatra(app_path)
+    port = next_port
+    log  = File.join(Dir.mktmpdir("diff-sin"), "sinatra.log")
+    pid  = Process.spawn(
+      RbConfig.ruby, app_path, "-p", port.to_s, "-o", "127.0.0.1", "-e", "production",
+      out: log, err: [:child, :out], pgroup: true
+    )
+    wait_for_port(port, pid)
+    Server.new(pid, port, log)
+  end
+
+  def self.boot_tep(app_path)
+    tmp = Dir.mktmpdir("diff-tep")
+    bin = File.join(tmp, "app")
+    out = `#{Shellwords.escape(TEP_BIN)} build #{Shellwords.escape(app_path)} -o #{Shellwords.escape(bin)} 2>&1`
+    raise "tep build failed for #{app_path}:\n#{out}" unless $?.success?
+    port = next_port
+    log  = File.join(tmp, "tep.log")
+    pid  = Process.spawn(bin, "-p", port.to_s, "-q",
+                         out: log, err: [:child, :out], pgroup: true)
+    wait_for_port(port, pid)
+    Server.new(pid, port, log)
+  end
+
+  def self.request(port, verb, path, body: nil, headers: {})
+    http = Net::HTTP.new("127.0.0.1", port)
+    http.open_timeout = 5
+    http.read_timeout = 5
+    klass = { "GET" => Net::HTTP::Get, "POST" => Net::HTTP::Post,
+              "PUT" => Net::HTTP::Put, "PATCH" => Net::HTTP::Patch,
+              "DELETE" => Net::HTTP::Delete }.fetch(verb)
+    req = klass.new(path)
+    headers.each { |k, v| req[k] = v }
+    if body
+      req.body = body
+      req["Content-Type"] ||= "application/x-www-form-urlencoded"
+    end
+    http.request(req)
+  end
+end
+
+# One test class per fixture; each boots both servers once and replays
+# the same request script against each.
+class DifferentialCase < Minitest::Test
+  FIXTURES = {
+    File.expand_path("../real_world/01_simple.rb", __dir__) => [
+      ["GET", "/"],
+    ],
+    File.expand_path("../real_world/04_health_api.rb", __dir__) => [
+      ["GET", "/healthz"],
+      ["GET", "/version"],
+      ["GET", "/"],
+      ["GET", "/missing"],          # custom not_found on both
+    ],
+    File.expand_path("../real_world/05_todo_api.rb", __dir__) => [
+      ["GET", "/todos"],
+      ["POST", "/todos", { body: "text=buy-milk" }],
+      ["POST", "/todos", { body: "text=ship-tep" }],
+      ["GET", "/todos"],
+      ["DELETE", "/todos/1"],
+      ["DELETE", "/todos/9999"],
+      ["GET", "/todos"],
+    ],
+    File.expand_path("11_matrix.rb", __dir__) => [
+      ["PUT", "/verb"],
+      ["PATCH", "/verb"],
+      ["GET", "/files/one"],
+      # L5: sinatra's splat spans segments (/files/a/b matches); tep's
+      # splat is last-segment-only (404s). Pinned divergence.
+      ["GET", "/files/a/b", { diverge: { "status" => "L5 splat last-segment-only" } }],
+      ["GET", "/rx/123"],
+      ["GET", "/rx/abc"],               # regex miss -> not_found on both
+      ["GET", "/afterhdr", { expect_headers: ["x-after"] }],
+      ["GET", "/dec?v=a%20b+c"],        # %xx and + decoding
+      ["POST", "/mp", {
+        body: "--XDIFFB\r\nContent-Disposition: form-data; name=\"field\"\r\n\r\nzap-mp\r\n--XDIFFB--\r\n",
+        headers: { "Content-Type" => "multipart/form-data; boundary=XDIFFB" },
+      }],
+      ["GET", "/gone"],                 # bare halt 410
+      ["GET", "/nowhere"],
+    ],
+    File.expand_path("10_semantics.rb", __dir__) => [
+      ["GET", "/hi/tep"],
+      ["GET", "/two/a/b"],
+      ["GET", "/q?q=hello"],
+      ["GET", "/q"],                 # missing param -> ""
+      ["POST", "/form", { body: "text=zap" }],
+      ["GET", "/redir"],
+      ["GET", "/redir301"],
+      ["GET", "/teapot"],
+      ["GET", "/halted"],
+      ["GET", "/hdr", { expect_headers: ["x-custom"] }],
+      ["GET", "/ct"],
+      ["GET", "/hi%20there"],        # url-decoded 404 path via not_found
+    ],
+  }.freeze
+
+  def compare(app, sin, tep, verb, path, opts)
+    body    = opts[:body]
+    headers = opts[:headers] || {}
+    r_sin = Differential.request(sin.port, verb, path, body: body, headers: headers)
+    r_tep = Differential.request(tep.port, verb, path, body: body, headers: headers)
+    ctx = "#{File.basename(app)} #{verb} #{path}"
+
+    # Ledgered per-request divergences (opts[:diverge] = {facet =>
+    # "Ln reason"}): the divergence is EXPECTED and pinned -- if the
+    # two servers ever agree again, the assertion flips, telling us to
+    # clean the ledger entry (and docs/mirrors/sinatra.md). A status
+    # divergence short-circuits the body/content-type diff: different
+    # routes answered, comparing their bodies is meaningless.
+    diverge = opts[:diverge] || {}
+    if diverge.key?("status")
+      refute_equal r_sin.code, r_tep.code,
+                   "#{ctx}: ledgered status divergence (#{diverge["status"]}) healed -- remove from ledger"
+      return
+    end
+
+    assert_equal r_sin.code, r_tep.code, "#{ctx}: status diverged"
+    assert_equal r_sin.body, r_tep.body, "#{ctx}: body diverged"
+    assert_equal Differential.normalize_content_type(r_sin["content-type"]),
+                 Differential.normalize_content_type(r_tep["content-type"]),
+                 "#{ctx}: content-type diverged (post-normalization)"
+    if %w[301 302 303 307 308].include?(r_sin.code)
+      assert_equal Differential.normalize_location(r_sin["location"]),
+                   Differential.normalize_location(r_tep["location"]),
+                   "#{ctx}: redirect Location diverged (path component)"
+    end
+    (opts[:expect_headers] || []).each do |h|
+      assert_equal r_sin[h], r_tep[h], "#{ctx}: declared header #{h} diverged"
+    end
+  end
+
+  FIXTURES.each do |app, script|
+    name = File.basename(app, ".rb")
+    define_method("test_differential_#{name}") do
+      sin = Differential.boot_sinatra(app)
+      tep = Differential.boot_tep(app)
+      begin
+        script.each do |verb, path, opts|
+          compare(app, sin, tep, verb, path, opts || {})
+        end
+      ensure
+        sin.stop
+        tep.stop
+      end
+    end
+  end
+end

data/test/test_broadcast_pg.rb

@@ -111,8 +111,12 @@ class TestBroadcastPg < TepTest
   end
 
   def test_poll_returns_zero_on_timeout
-    # With no preceding publish + no other publisher on the channel,
-    # poll should time out cleanly.
+    # Test order is randomized and the LISTEN channel is shared:
+    # another test's publish can leave an unconsumed NOTIFY queued.
+    # Drain first, then assert a clean timeout.
+    5.times do
+      break if get("/poll?timeout=50").body == "0"
+    end
     res = get("/poll?timeout=100")
     assert_equal "0", res.body
   end

data/test/test_live_view.rb

@@ -18,8 +18,10 @@ class TestLiveView < TepTest
       end
       def mount(req)
         # Pull a seed value from the request's params if present;
-        # otherwise leave at 0.
+        # otherwise leave at 0. A missing param reads as nil
+        # (sinatra-parity) -- guard before String calls.
         seed = req.params["seed"]
+        seed = "" if seed.nil?
         if seed.length > 0
           @count = seed.to_i
         end

data/test/test_mcp.rb

@@ -12,7 +12,9 @@ class TestMCP < TepTest
     # paths -- we just override req.identity with a synthetic one
     # so req.identity.may?(:admin) returns true on demand.
     before do
-      if req.req_headers["x-test-cap-admin"].length > 0
+      cap = req.req_headers["x-test-cap-admin"]
+      cap = "" if cap.nil?
+      if cap.length > 0
         req.identity = Tep::Identity.new(
           "user:42", nil, [:admin])
       end

data/test/test_pg.rb

@@ -268,10 +268,22 @@ class TestPg < TepTest
         r.clear
         out = "raised=no"
       rescue PG::UndefinedTable => e
+        # Hierarchy proof via a nested rescue arm instead of
+        # `e.is_a?(PG::Error)`: is_a? on a rescued local is
+        # unsupported at the current spinel pin (typed-rescue local
+        # widens; tracked in the SPINEL_PIN notes). Re-raising e and
+        # catching it with the PARENT class proves the subclass
+        # relation just as strictly.
+        hier = "no"
+        begin
+          raise e
+        rescue PG::Error
+          hier = "yes"
+        end
         out = "raised=UndefinedTable" +
               " sqlstate=" + c.last_sqlstate +
               " match42P01=" + (c.last_sqlstate == "42P01" ? "yes" : "no") +
-              " is_pg_error=" + (e.is_a?(PG::Error) ? "yes" : "no")
+              " is_pg_error=" + hier
       end
       c.close
       out
@@ -295,9 +307,16 @@ class TestPg < TepTest
         r2.clear
         out = "first_ok=yes second_raised=no"
       rescue PG::UniqueViolation => e
+        # Same nested-rescue hierarchy proof as /missing_table.
+        hier = "no"
+        begin
+          raise e
+        rescue PG::Error
+          hier = "yes"
+        end
         out = "first_ok=yes second_raised=UniqueViolation" +
               " sqlstate=" + c.last_sqlstate +
-              " is_pg_error=" + (e.is_a?(PG::Error) ? "yes" : "no")
+              " is_pg_error=" + hier
       end
       r3 = c.exec_params("DELETE FROM " + TBL + " WHERE id = $1", ["99001"])
       r3.clear

data/test/test_real_world.rb

@@ -30,10 +30,14 @@ class TestRealWorld < TepTest
     PORT_BASE + 100 + @@port_counter
   end
 
-  def with_app(example_filename)
+  # lax: true builds with --lax for fidelity copies of upstream apps
+  # that use out-of-contract DSL on purpose (02_lifecycle's `on_stop`)
+  # -- the strict default (mirror condition 3) would rightly refuse.
+  def with_app(example_filename, lax: false)
     src = File.join(EXAMPLES_DIR, example_filename)
     bin = Dir.mktmpdir + "/app"
-    out = `#{Shellwords.escape(File.expand_path("../bin/tep", __dir__))} build #{Shellwords.escape(src)} -o #{Shellwords.escape(bin)} 2>&1`
+    lax_flag = lax ? " --lax" : ""
+    out = `#{Shellwords.escape(File.expand_path("../bin/tep", __dir__))} build#{lax_flag} #{Shellwords.escape(src)} -o #{Shellwords.escape(bin)} 2>&1`
     raise "build failed:\n#{out}" unless $?.success?
     port = TestRealWorld.next_port
     pid = Process.spawn(bin, "-p", port.to_s, "-q",
@@ -73,7 +77,8 @@ class TestRealWorld < TepTest
   # ---- 02: lifecycle ----
 
   def test_02_lifecycle_root_renders
-    with_app("02_lifecycle.rb") do
+    # upstream example uses `on_stop` (no tep shutdown path) -> --lax
+    with_app("02_lifecycle.rb", lax: true) do
       res = get("/")
       assert_equal "200", res.code
       assert_match(/lifecycle events/, res.body)

data/test/test_request_methods.rb

@@ -24,7 +24,13 @@ class TestRequestMethods < TepTest
     end
 
     get '/accept-and-ct' do
-      "accept=" + request.accept + " ct=" + request.content_type
+      # Absent headers read as nil through the Rack-parity accessors
+      # (sinatra too) -- guard before concatenation.
+      a = request.accept
+      a = "" if a.nil?
+      ct = request.content_type
+      ct = "" if ct.nil?
+      "accept=" + a + " ct=" + ct
     end
   RB
 

data/test/test_unsupported.rb

@@ -29,4 +29,51 @@ class TestUnsupported < TepTest
 
   # send_file, configure, pass, multiple filters, optional segments
   # have all moved into supported and have their own test files.
+
+  # ---- strict-by-default translator (mirror condition 3) ----
+  # Out-of-contract constructs must FAIL the build, not silently
+  # drop (docs/mirrors/sinatra.md). These assert at translate level,
+  # so no spinel compile is needed. `--lax` restores warn-and-continue.
+
+  def translate_out(source, flags: "")
+    tmp = Dir.mktmpdir("tep-strict")
+    src = File.join(tmp, "app.rb")
+    File.write(src, "require 'sinatra'\n" + source + "\nget('/') { 'ok' }\n")
+    out = `#{TepHarness::TEP_BIN} translate #{flags} #{src} 2>&1 >/dev/null`
+    [$?.success?, out]
+  ensure
+    FileUtils.remove_entry(tmp) if tmp
+  end
+
+  def assert_strict_refusal(source, message_fragment)
+    ok, out = translate_out(source)
+    refute ok, "expected strict translate to fail, but it succeeded"
+    assert_match(/error: .*#{Regexp.escape(message_fragment)}/, out)
+    assert_match(/--lax/, out, "refusal should mention the --lax escape hatch")
+  end
+
+  def test_strict_rejects_rack_use
+    assert_strict_refusal(%(use Rack::Session::Cookie, secret: "x"),
+                          "unsupported `use`")
+  end
+
+  def test_strict_rejects_helpers_block
+    assert_strict_refusal(%(helpers do\n  def shout(s); s.upcase; end\nend),
+                          "unsupported `helpers do ... end`")
+  end
+
+  def test_strict_rejects_unknown_set_key
+    assert_strict_refusal(%(set :sessions, true), "unsupported `set :sessions`")
+  end
+
+  def test_strict_rejects_on_stop
+    assert_strict_refusal(%(on_stop do\n  puts "bye"\nend), "on_stop")
+  end
+
+  def test_lax_downgrades_to_warning
+    ok, out = translate_out("use Rack::Head", flags: "--lax")
+    assert ok, "expected --lax translate to succeed, got:\n#{out}"
+    assert_match(/unsupported `use`/, out)
+    refute_match(/error:/, out)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tep
 version: !ruby/object:Gem::Version
-  version: 0.11.6
+  version: 0.11.7
 platform: ruby
 authors:
 - Ori Pekelman
@@ -162,6 +162,10 @@ files:
 - public/hello.txt
 - public/style.css
 - spinel-ext.json
+- test/differential/10_semantics.rb
+- test/differential/11_matrix.rb
+- test/differential/Gemfile
+- test/differential/runner.rb
 - test/helper.rb
 - test/real_world/01_simple.rb
 - test/real_world/02_lifecycle.rb
@@ -273,7 +277,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A Sinatra-flavoured web framework that compiles to a native binary via Spinel
 test_files: []