tep 0.11.0

data/lib/tep/parallel.rb

@@ -0,0 +1,168 @@
+# Tep::Parallel -- grosser/parallel-shaped process fan-out.
+#
+# Why
+# ---
+# Spinel doesn't ship Ractors, doesn't expose the GVL'd threading
+# story, and the `parallel` gem (heavy use of `Marshal`,
+# `IO.pipe`, dynamic `Proc` invocation) doesn't lower. Fork is
+# however a perfectly cheap C call here, so the smallest useful
+# slice of `parallel` -- "run this worker over a list of items,
+# one child per item, collect the results" -- is implementable
+# directly on top of sphttp's `sphttp_fork` + a tiny file-based
+# IPC channel.
+#
+# API
+# ---
+#   results = Tep::Parallel.map_processes(items, worker)
+#   #=> [String, String, ...]   -- one entry per input, in order
+#
+# `worker.run(item)` must return a String. Each child runs the
+# worker once, writes its return value to a per-index file under
+# /tmp, exits; the parent reaps everyone and reads the files
+# back. The String constraint exists because passing structured
+# data across fork would need Marshal, which spinel doesn't
+# emit -- and HTTP-shaped APIs (the dashboard) round-trip
+# strings naturally.
+#
+# Fire-and-forget shape:
+#
+#   Tep::Parallel.each_process(items, worker)
+#
+# Forks one child per item, doesn't capture results.
+#
+# Scope (v1)
+# ----------
+#   * One child per item -- no fixed-size pool. Fine up to a few
+#     dozen items; for larger fan-outs the caller should chunk
+#     beforehand or write the round-trip into Tep::Job.
+#   * String return values only.
+#   * No thread mode -- spinel doesn't lower MRI's Thread reliably.
+#
+# Closeness to grosser/parallel
+# -----------------------------
+# `parallel`'s top-level API is
+#
+#   Parallel.map(items, in_processes: N) { |x| ... }
+#
+# spinel can't take a block as a value, so we lift the body into
+# a Worker class instead. Spinel also can't auto-cast subclass
+# pointers at cmeth call sites (#429-shaped), which means cmeth
+# args typed as a worker base class widen to poly at the call
+# site and the C compile fails. The fix: store the worker in an
+# instance field of `Tep::Parallel` -- typed-slot imeth dispatch
+# works the same way `@before_filter.before(req, res)` does for
+# `Tep::Filter`. Resulting shape:
+#
+#   p = Tep::Parallel.new(MyWorker.new)
+#   results = p.map_processes(items)
+#
+# Worker base class
+# -----------------
+# Real workers subclass `Tep::ParallelWorker` and override `run(item)`.
+# Two spinel landings made this name viable: matz/spinel#531 (270eceb)
+# narrowed the poly-receiver dispatch table by ivar observed-class set
+# (so `Tep::Server#run` no longer leaks into `@worker.run`'s switch),
+# and matz/spinel#549 (1d561ad) collapsed the dispatch result to a
+# scalar when all reachable arms agree on the return type (so the
+# result lands as `const char *` instead of sp_RbVal).
+module Tep
+  # Base class for Tep::Parallel workers. Override `run(item)` in
+  # subclasses; the default emits "" so a base-class instance used
+  # for seeding stays type-safe.
+  class ParallelWorker
+    def run(item)
+      ""
+    end
+  end
+
+  class Parallel
+    attr_accessor :worker
+
+    def initialize(worker)
+      @worker = worker
+    end
+
+    # Result-collecting fan-out. Returns an Array of Strings in
+    # input order; one fork per item. See module doc for the
+    # constraints (Strings only, no fixed pool).
+    def map_processes(items)
+      job_dir = Parallel.scratch_dir
+      Tep::Shell.run("mkdir -p " + job_dir)
+
+      n = items.length
+      i = 0
+      while i < n
+        # Pull each fork into its own stack frame -- spinel's
+        # codegen for the in-line fork-and-exec pattern was
+        # observed to share locals across the parent loop and
+        # the child body, so all children ended up processing
+        # the same (last) item. Method-call boundary gives each
+        # child a clean local snapshot.
+        spawn_one(items[i], i, job_dir)
+        i += 1
+      end
+
+      reaped = 0
+      while reaped < n
+        Sock.sphttp_wait_any
+        reaped += 1
+      end
+
+      out = [""]
+      out.delete_at(0)
+      k = 0
+      while k < n
+        out.push(Tep::Shell.read(job_dir + "/" + k.to_s))
+        k += 1
+      end
+      Tep::Shell.run("rm -rf " + job_dir)
+      out
+    end
+
+    # Fork one child to process `item`. When `job_dir` is non-empty,
+    # the child writes the worker's String result to `job_dir/idx`
+    # (consumed by map_processes); otherwise the result is discarded
+    # (fire-and-forget shape used by each_process). Returns the child
+    # pid in the parent; the child never returns (exits when done).
+    #
+    # The method-call boundary is load-bearing: an inline fork-and-
+    # exec loop body shared locals across iterations under spinel's
+    # codegen, so every child processed the same (last) item. A
+    # separate def gives each fork a clean local frame.
+    def spawn_one(item, idx, job_dir)
+      pid = Sock.sphttp_fork
+      if pid == 0
+        result = @worker.run(item)
+        if job_dir.length > 0
+          path = job_dir + "/" + idx.to_s
+          File.write(path, result)
+        end
+        Sock.sphttp_exit(0)
+      end
+      pid
+    end
+
+    # Fire-and-forget version. Returns 0 once every child exits.
+    def each_process(items)
+      n = items.length
+      i = 0
+      while i < n
+        spawn_one(items[i], 0, "")
+        i += 1
+      end
+      reaped = 0
+      while reaped < n
+        Sock.sphttp_wait_any
+        reaped += 1
+      end
+      0
+    end
+
+    # Per-invocation scratch directory. Uses pid + monotonic
+    # timestamp so concurrent map_processes calls in different
+    # workers don't trample each other.
+    def self.scratch_dir
+      "/tmp/tep_par_" + Sock.sphttp_getpid.to_s + "_" + Time.now.to_i.to_s
+    end
+  end
+end

data/lib/tep/parser.rb

@@ -0,0 +1,81 @@
+# HTTP/1.x request parser. Produces a Tep::Request from the raw
+# byte blob the C helper read off the wire (headers, possibly a
+# prefix of the body).
+module Tep
+  class Parser
+    # Returns a fully-populated Request, or nil if the blob is malformed.
+    def self.parse(blob)
+      # Note: Spinel's String#index returns -1 (not nil) when not found.
+      end_of_headers = Tep.str_find(blob, "\r\n\r\n", 0)
+      if end_of_headers < 0
+        return nil
+      end
+      headers_blob = blob[0, end_of_headers]
+      lines = headers_blob.split("\r\n")
+      if lines.length == 0
+        return nil
+      end
+
+      first = lines[0]
+      first_parts = first.split(" ")
+      if first_parts.length < 3
+        return nil
+      end
+
+      req = Request.new
+      req.verb         = first_parts[0]
+      req.raw_path     = first_parts[1]
+      req.http_version = first_parts[2]
+
+      qmark = Tep.str_find(req.raw_path, "?", 0)
+      if qmark < 0
+        req.path = req.raw_path
+      else
+        req.path  = req.raw_path[0, qmark]
+        qstring   = req.raw_path[qmark + 1, req.raw_path.length - qmark - 1]
+        req.query = Url.parse_query(qstring)
+      end
+
+      i = 1
+      while i < lines.length
+        line = lines[i]
+        colon = Tep.str_find(line, ":", 0)
+        if colon >= 0
+          name  = line[0, colon].downcase
+          value = line[colon + 1, line.length - colon - 1].strip
+          req.req_headers[name] = value
+        end
+        i += 1
+      end
+
+      # Pre-merge query into params; path captures will be folded in
+      # by the router on a successful match.
+      req.query.each do |k, v|
+        req.params[k] = v
+      end
+
+      # Parse Cookie header into req.cookies. Format: "k=v; k2=v2; ...".
+      # Whitespace around `;` is allowed and stripped.
+      cookie_blob = req.req_headers["cookie"]
+      if cookie_blob.length > 0
+        cookie_blob.split(";").each do |pair|
+          eq = Tep.str_find(pair, "=", 0)
+          if eq > 0
+            cname  = pair[0, eq].strip
+            cvalue = pair[eq + 1, pair.length - eq - 1].strip
+            req.cookies[cname] = Url.unescape(cvalue)
+          end
+        end
+      end
+
+      # Carry over any body bytes already in the blob (the C helper
+      # may have read more than just the headers in one recv()).
+      body_start = end_of_headers + 4
+      if body_start < blob.length
+        req.raw_body = blob[body_start, blob.length - body_start]
+      end
+
+      req
+    end
+  end
+end

data/lib/tep/password.rb

@@ -0,0 +1,102 @@
+# Tep::Password -- password hashing for spinel-AOT'd apps.
+#
+# Uses PBKDF2-HMAC-SHA256 with a 16-byte CSPRNG salt and a default
+# of 200,000 iterations -- sits in the OWASP-recommended ballpark
+# (200k for SHA256 as of 2023). Backed by a small C helper in
+# tep_crypto.c; no libcrypt / OpenSSL / bcrypt-gem dependency.
+#
+# Why PBKDF2 instead of bcrypt?
+# -----------------------------
+# Bcrypt is the textbook choice but its canonical impls are either
+# the system `crypt(3)` (not portable: macOS doesn't ship $2b$, Linux
+# needs libxcrypt) or the bcrypt-ruby gem (a CRuby C extension that
+# spinel can't load). PBKDF2-SHA256 is in NIST SP 800-132 and OWASP
+# acceptable, builds on the HMAC-SHA256 we already ship for the
+# session store, and adds zero new system dependencies.
+#
+# scrypt / argon2 would be stronger but require linking libsodium or
+# vendoring ~2k lines of C. Defer until callers need them.
+#
+# Format
+# ------
+# Stored hash is `pbkdf2-sha256$<iters>$<salt_b64>$<derived_b64>`.
+# All segments are base64url, no padding. Self-describing so a
+# future rotation to higher iter counts (or a different scheme) can
+# coexist with old hashes -- `verify` honours the embedded iter
+# count.
+#
+# Usage
+# -----
+#
+#   stored = Tep::Password.hash("user-input")
+#   # store `stored` in the DB
+#
+#   # On login:
+#   if Tep::Password.verify("user-input", stored)
+#     # session.set("uid", row_id)
+#   end
+module Tep
+  class Password
+    DEFAULT_ITERS = 200000
+    SALT_BYTES    = 16
+
+    # Derive a stored hash from a plain password. Generates a
+    # fresh CSPRNG salt and runs PBKDF2-SHA256 at the default
+    # iter count. Returns the self-describing storage string.
+    # Named `hash` to match the bcrypt-gem-style factory shape.
+    def self.hash(plain)
+      salt = Crypto.sp_crypto_random_b64url(SALT_BYTES)
+      derived = Crypto.sp_crypto_pbkdf2_sha256_b64url(plain, salt, DEFAULT_ITERS)
+      "pbkdf2-sha256$" + DEFAULT_ITERS.to_s + "$" + salt + "$" + derived
+    end
+
+    # Verify `plain` against a stored hash. Re-runs PBKDF2 with the
+    # same salt + iter count embedded in the stored string and
+    # constant-time compares. Rejects malformed stored hashes by
+    # returning false.
+    def self.verify(plain, stored)
+      parts = Password.split4(stored)
+      if parts[0] != "pbkdf2-sha256"
+        return false
+      end
+      iters_s = parts[1]
+      salt    = parts[2]
+      derived = parts[3]
+      if iters_s.length == 0 || salt.length == 0 || derived.length == 0
+        return false
+      end
+      iters = iters_s.to_i
+      if iters < 1
+        return false
+      end
+      candidate = Crypto.sp_crypto_pbkdf2_sha256_b64url(plain, salt, iters)
+      Tep::Jwt.timing_safe_eq(candidate, derived)
+    end
+
+    # Split a 4-segment "$"-delimited stored hash into its four
+    # parts. spinel's `String#split` exists but its behaviour on
+    # complex inputs has tripped us before; the explicit walker
+    # is small and obviously correct.
+    def self.split4(s)
+      out = ["", "", "", ""]
+      n = s.length
+      seg = 0
+      start = 0
+      i = 0
+      while i < n
+        if s[i] == "$"
+          if seg < 4
+            out[seg] = s[start, i - start]
+          end
+          seg += 1
+          start = i + 1
+        end
+        i += 1
+      end
+      if seg < 4
+        out[seg] = s[start, n - start]
+      end
+      out
+    end
+  end
+end