tep 0.11.0

data/lib/tep/mcp.rb

@@ -0,0 +1,203 @@
+# Tep::MCP -- runtime helpers for the MCP battery (chunk 5.1).
+#
+# Most of the action happens in the bin/tep translator: each
+# `mcp_tool` declaration generates a per-tool dispatch cmeth + a
+# direct HTTP route, and the translator-emitted dispatcher class
+# at POST /mcp routes JSON-RPC 2.0 messages to those cmeths by
+# name. This file holds the runtime helpers the generated code
+# leans on -- nested-key JSON extraction, result builders, and
+# JSON-RPC envelope formatters.
+#
+# Public surface (chunk 5.1):
+#
+#   Tep::MCP.text(s)              -> Result with text content
+#   Tep::MCP.error(s)             -> Result marked isError = true
+#   Tep::MCP.nested_extract(j, k) -> sub-JSON string for a nested key
+#   Tep::MCP.initialize_envelope(id, name, version)
+#   Tep::MCP.tools_list_envelope(id, tools_json)
+#   Tep::MCP.tools_call_envelope(id, result)
+#   Tep::MCP.unknown_tool_envelope(id, name)
+#   Tep::MCP.method_not_found_envelope(id, method)
+#
+# Apps wire the battery via `mcp_tool '...' do ... end` blocks at
+# the top level; bin/tep does the rest. The runtime here stays
+# small + spinel-friendly (no class-hierarchy dispatch, no
+# heterogeneous arrays). See docs/MCP-BATTERY.md for the design.
+module Tep
+  module MCP
+    # MCP protocol version this server claims to speak. Tracks the
+    # 2025-03 ("Streamable HTTP") revision of the spec.
+    PROTOCOL_VERSION = "2025-03-26"
+
+    # Tool result -- carries either a text content block (the only
+    # content type supported in chunk 5.1) or an error marker.
+    class Result
+      attr_accessor :text, :is_error
+
+      def initialize
+        @text     = ""
+        @is_error = 0
+      end
+    end
+
+    def self.text(s)
+      r = Tep::MCP::Result.new
+      r.text     = s
+      r.is_error = 0
+      r
+    end
+
+    def self.error(s)
+      r = Tep::MCP::Result.new
+      r.text     = s
+      r.is_error = 1
+      r
+    end
+
+    # Resource read outcome -- a (uri, mime, text) triple wrapped
+    # in the resources/read response envelope. Kept as a simple
+    # value class (parallel to Result) so spinel tracks the slot
+    # types cleanly across module boundaries.
+    class ResourceContent
+      attr_accessor :uri, :mime, :text
+
+      def initialize
+        @uri  = ""
+        @mime = "text/plain"
+        @text = ""
+      end
+    end
+
+    # Build a text-mime resource content block. URI is the
+    # resource's identifier (echoed back to the client so clients
+    # can correlate the response with the request).
+    def self.resource_text(uri, text)
+      c = Tep::MCP::ResourceContent.new
+      c.uri  = uri
+      c.mime = "text/plain"
+      c.text = text
+      c
+    end
+
+    # Pull a nested JSON value out of `json` by top-level key,
+    # returning the value's JSON-string form. Used by the
+    # translator-emitted dispatcher to dig `params` out of the
+    # JSON-RPC envelope, then `arguments` out of params, before
+    # handing the arguments sub-object to the per-tool cmeth.
+    #
+    # Returns "{}" when the key isn't present (so downstream
+    # Tep::Json.get_str / get_int calls see an empty object that
+    # returns their zero-default cleanly).
+    def self.nested_extract(json, key)
+      pos = Tep::Json.find_value_start(json, key)
+      if pos < 0
+        return "{}"
+      end
+      end_pos = Tep::Json.skip_value(json, pos)
+      if end_pos <= pos
+        return "{}"
+      end
+      json[pos, end_pos - pos]
+    end
+
+    # JSON-RPC 2.0 response envelope for `initialize`. The MCP
+    # client expects serverInfo + capabilities + protocolVersion.
+    # capabilities lists which method groups this server speaks.
+    def self.initialize_envelope(req_id, server_name, server_version)
+      "{\"jsonrpc\":\"2.0\",\"id\":" + req_id.to_s + "," +
+        "\"result\":{" +
+          "\"protocolVersion\":\"" + Tep::MCP::PROTOCOL_VERSION + "\"," +
+          "\"capabilities\":{\"tools\":{},\"resources\":{}}," +
+          "\"serverInfo\":{" +
+            "\"name\":"    + Tep::Json.quote(server_name)    + "," +
+            "\"version\":" + Tep::Json.quote(server_version) +
+          "}" +
+        "}" +
+      "}"
+    end
+
+    # Wrap a pre-built tools-array JSON string into the tools/list
+    # response envelope. tools_array_json is the literal `[{...},
+    # {...}]` the translator emits at compile time.
+    def self.tools_list_envelope(req_id, tools_array_json)
+      "{\"jsonrpc\":\"2.0\",\"id\":" + req_id.to_s + "," +
+        "\"result\":{\"tools\":" + tools_array_json + "}" +
+      "}"
+    end
+
+    # Wrap a tool's text + error-flag into the tools/call response
+    # envelope. content is a one-element array with a text block.
+    # Takes scalars rather than the Result struct directly so spinel
+    # tracks the String param locally through json_quote without
+    # going through attr_accessor return-type inference.
+    def self.tools_call_envelope(req_id, text, is_error)
+      is_err_str = "false"
+      if is_error == 1
+        is_err_str = "true"
+      end
+      "{\"jsonrpc\":\"2.0\",\"id\":" + req_id.to_s + "," +
+        "\"result\":{" +
+          "\"content\":[" +
+            "{\"type\":\"text\",\"text\":" + Tep::Json.quote(text) + "}" +
+          "]," +
+          "\"isError\":" + is_err_str +
+        "}" +
+      "}"
+    end
+
+    # Wrap a pre-built resources-array JSON string into the
+    # resources/list response envelope. Same shape as
+    # tools_list_envelope -- translator emits the array literally
+    # at compile time so spinel doesn't need to walk it at runtime.
+    def self.resources_list_envelope(req_id, resources_array_json)
+      "{\"jsonrpc\":\"2.0\",\"id\":" + req_id.to_s + "," +
+        "\"result\":{\"resources\":" + resources_array_json + "}" +
+      "}"
+    end
+
+    # Wrap a ResourceContent into a resources/read response
+    # envelope. contents is a one-element array per MCP spec; the
+    # uri / mimeType / text fields are read off as scalars (same
+    # spinel-friendly pattern as tools_call_envelope) before being
+    # spliced into the JSON.
+    def self.resources_read_envelope(req_id, uri, mime, text)
+      "{\"jsonrpc\":\"2.0\",\"id\":" + req_id.to_s + "," +
+        "\"result\":{\"contents\":[" +
+          "{\"uri\":" + Tep::Json.quote(uri) + "," +
+           "\"mimeType\":" + Tep::Json.quote(mime) + "," +
+           "\"text\":" + Tep::Json.quote(text) + "}" +
+        "]}" +
+      "}"
+    end
+
+    # Error envelope for resources/read on an unknown URI. Same
+    # JSON-RPC code as unknown_tool (-32602 invalid params).
+    def self.unknown_resource_envelope(req_id, uri)
+      "{\"jsonrpc\":\"2.0\",\"id\":" + req_id.to_s + "," +
+        "\"error\":{\"code\":-32602," +
+          "\"message\":" + Tep::Json.quote("unknown resource: " + uri) +
+        "}" +
+      "}"
+    end
+
+    # Error envelope for tools/call on an unknown tool name. Sent
+    # as a JSON-RPC error (-32602 invalid params) per the spec.
+    def self.unknown_tool_envelope(req_id, tool_name)
+      "{\"jsonrpc\":\"2.0\",\"id\":" + req_id.to_s + "," +
+        "\"error\":{\"code\":-32602," +
+          "\"message\":" + Tep::Json.quote("unknown tool: " + tool_name) +
+        "}" +
+      "}"
+    end
+
+    # Error envelope for an unrecognized JSON-RPC method. Spec
+    # code -32601 (method not found).
+    def self.method_not_found_envelope(req_id, method_name)
+      "{\"jsonrpc\":\"2.0\",\"id\":" + req_id.to_s + "," +
+        "\"error\":{\"code\":-32601," +
+          "\"message\":" + Tep::Json.quote("method not found: " + method_name) +
+        "}" +
+      "}"
+    end
+  end
+end

data/lib/tep/multipart.rb

@@ -0,0 +1,98 @@
+# Tep::Multipart -- text-field parsing for multipart/form-data bodies.
+#
+# Browser forms submitted via `new FormData(form)` (or any form
+# carrying file inputs) use `Content-Type: multipart/form-data`
+# instead of urlencoded. tep's request layer treats those bodies
+# as String fields here. File-upload parts (any part with a
+# `filename=` header) are skipped in v1 -- the field's bytes
+# don't land in `req.params`. Supporting file uploads needs a
+# different surface (likely `req.files`) plus an NUL-safe byte
+# array, both follow-ups.
+#
+# Public API mirrors Url.parse_query: pass the raw body + the
+# request's Content-Type header value; get back a string-keyed
+# string-valued hash, ready to merge into `req.params`.
+module Tep
+  module Multipart
+    # Parse `body` against the boundary embedded in `content_type`.
+    # Returns an empty hash when the boundary can't be extracted
+    # (defensive: caller already checked `req.multipart?`).
+    def self.parse(body, content_type)
+      h = Tep.str_hash
+      bnd = Tep::Multipart.extract_boundary(content_type)
+      if bnd.length == 0
+        return h
+      end
+      delim = "--" + bnd
+      parts = body.split(delim)
+      i = 1   # parts[0] is the prologue before the first delimiter
+      while i < parts.length
+        part = parts[i]
+        # Terminator: a part that starts with "--" is the closing
+        # boundary "--<bnd>--<crlf>"; nothing meaningful after it.
+        if part.length >= 2 && part[0, 2] == "--"
+          return h
+        end
+        # Strip the CRLF that follows every interior delimiter.
+        if part.length >= 2 && part[0, 2] == "\r\n"
+          part = part[2, part.length - 2]
+        end
+        # Strip the CRLF that precedes the next delimiter (every
+        # interior part ends with \r\n before the next "--<bnd>").
+        if part.length >= 2 && part[part.length - 2, 2] == "\r\n"
+          part = part[0, part.length - 2]
+        end
+        sep = Tep.str_find(part, "\r\n\r\n", 0)
+        if sep >= 0
+          headers = part[0, sep]
+          value   = part[sep + 4, part.length - sep - 4]
+          name = Tep::Multipart.extract_field_name(headers)
+          has_filename = Tep.str_find(headers, "filename=", 0) >= 0
+          if name.length > 0 && !has_filename
+            h[name] = value
+          end
+        end
+        i += 1
+      end
+      h
+    end
+
+    # Extract `boundary=...` from a Content-Type value. Handles
+    # quoted (`boundary="x"`) and unquoted (`boundary=x;` or
+    # `boundary=x` at end of string).
+    def self.extract_boundary(content_type)
+      at = Tep.str_find(content_type, "boundary=", 0)
+      if at < 0
+        return ""
+      end
+      rest = content_type[at + 9, content_type.length - at - 9]
+      if rest.length > 0 && rest[0, 1] == "\""
+        end_q = Tep.str_find(rest, "\"", 1)
+        if end_q < 0
+          return ""
+        end
+        return rest[1, end_q - 1]
+      end
+      semi = Tep.str_find(rest, ";", 0)
+      if semi >= 0
+        return rest[0, semi]
+      end
+      rest
+    end
+
+    # Extract the `name="..."` value from a part's headers blob.
+    # Returns "" when no name found.
+    def self.extract_field_name(headers)
+      at = Tep.str_find(headers, "name=\"", 0)
+      if at < 0
+        return ""
+      end
+      start = at + 6
+      end_q = Tep.str_find(headers, "\"", start)
+      if end_q < 0
+        return ""
+      end
+      headers[start, end_q - start]
+    end
+  end
+end

data/lib/tep/net.rb

@@ -0,0 +1,155 @@
+# All FFI plumbing lives at the top level so spinel's name resolver
+# finds it from anywhere in the Tep tree (nested modules confuse it).
+#
+# The `@TEP_SPHTTP_O@` placeholder is substituted by `bin/tep` (or
+# the Makefile) with the absolute path to the built sphttp.o on the
+# current host. Spinel doesn't support `__dir__` or `ENV.fetch` in
+# top-level ffi_cflags, so a build-time substitution is the cleanest
+# portable shape.
+module Sock
+  ffi_cflags "@TEP_SPHTTP_O@"
+  # Outbound TLS (sphttp_connect_tls) is backed by the system
+  # libssl/libcrypto. Linked for every app (like sqlite3 elsewhere);
+  # the plaintext path never calls into it, so apps that make no HTTPS
+  # requests pay only the link cost, not runtime. See tep#148.
+  # (When OpenSSL is off the default path -- macOS/Homebrew -- the build
+  # finds it via CPATH/LIBRARY_PATH in the environment, not a cflag
+  # here; spinel's ffi_cflags rejects an empty-string placeholder.)
+  ffi_lib "ssl"
+  ffi_lib "crypto"
+
+  ffi_func :sphttp_listen,        [:int, :int],     :int
+  ffi_func :sphttp_accept,        [:int],           :int
+  # Non-blocking accept variant used by Tep::Server::Scheduled.
+  # Listen fd must be in non-blocking mode (sphttp_set_nonblock).
+  # Returns -1 with errno EAGAIN/EWOULDBLOCK if no pending connection.
+  ffi_func :sphttp_accept_nb,     [:int],           :int
+  ffi_func :sphttp_read_request,  [:int],           :int
+  ffi_func :sphttp_request_buf,   [],               :str
+  ffi_func :sphttp_request_len,   [],               :int
+  ffi_func :sphttp_drain_body,    [:int, :int],     :str
+  ffi_func :sphttp_write_str,     [:int, :str],     :int
+
+  # Binary-safe write + recv pair, used by Tep::WebSocket (and any
+  # other caller that needs to send/receive bytes containing 0x00).
+  # The recv side mirrors the request_buf / _len accessor pattern.
+  # See sphttp.c for the binary-safety contract.
+  ffi_func :sphttp_write_bytes,   [:int, :str, :int], :int
+  ffi_func :sphttp_recv_into_frame, [:int],         :int
+  ffi_func :sphttp_recv_frame_buf, [],              :str
+  ffi_func :sphttp_recv_frame_len, [],              :int
+
+  # Shutdown-on-signal plumbing. Install once at server start;
+  # sphttp_shutdown_requested polls the flag (sigaction sets it on
+  # SIGTERM/SIGINT). The server's accept loop checks the flag after
+  # sphttp_accept returns -1 and runs Tep.on_shutdown before exit.
+  ffi_func :sphttp_install_term_handlers, [], :int
+  ffi_func :sphttp_shutdown_requested,    [], :int
+
+  # Millisecond sleep helper for sub-second pacing. spinel's
+  # Tep::Scheduler.pause is integer-second only; this exposes the
+  # POSIX nanosleep path. Returns 0 on success, -1 on EINTR. Used by
+  # Tep::Proxy's retry-backoff loop.
+  ffi_func :sphttp_sleep_ms,              [:int], :int
+
+  # HTTP/1.1 outbound connection pool (chunk 6.7a). Per-process pool
+  # keyed by (host, port). checkout returns an idle fd or -1; checkin
+  # registers one; close_idle sweeps entries older than idle_seconds.
+  # Stat getters fetch one counter each (avoids a struct-return over
+  # FFI). See Tep::Http::Pool for the Ruby surface.
+  ffi_func :sphttp_pool_checkout,         [:str, :int],     :int
+  ffi_func :sphttp_pool_checkin,          [:int, :str, :int], :int
+  ffi_func :sphttp_pool_close_idle,       [:int],           :int
+  ffi_func :sphttp_pool_stat_checkouts,   [],               :int
+  ffi_func :sphttp_pool_stat_checkins,    [],               :int
+  ffi_func :sphttp_pool_stat_hits,        [],               :int
+  ffi_func :sphttp_pool_stat_misses,      [],               :int
+
+  # uname-based host introspection for the toy/v1 envelope (see
+  # docs/events-schema.md). sphttp_os_kind returns lowercased
+  # uname.sysname ("linux" / "darwin" / ...); sphttp_arch_kind
+  # returns uname.machine as-is ("aarch64" / "x86_64" / ...). Both
+  # return "unknown" on uname() failure.
+  ffi_func :sphttp_os_kind,       [],               :str
+  ffi_func :sphttp_arch_kind,     [],               :str
+
+  # ISO-8601 UTC timestamp for an epoch-seconds value. Used by
+  # Tep::Events (toy/v1 envelope) for run_start/run_end wall-clock
+  # fields -- spinel's Time.now is integer-epoch only.
+  ffi_func :sphttp_iso8601_utc,   [:int],           :str
+  # RFC 1123 GMT date (HTTP Date / Last-Modified / Expires) <-> epoch.
+  # parse returns -1 if the string doesn't parse.
+  ffi_func :sphttp_http_date,       [:int],         :str
+  ffi_func :sphttp_parse_http_date, [:str],         :int
+
+  ffi_func :sphttp_sendfile,      [:int, :str],     :int
+  ffi_func :sphttp_filesize,      [:str],           :int
+  ffi_func :sphttp_file_mtime,    [:str],           :int
+  ffi_func :sphttp_close,         [:int],           :int
+  ffi_func :sphttp_fork,          [],               :int
+  ffi_func :sphttp_exit,          [:int],           :int
+  ffi_func :sphttp_getpid,        [],               :int
+  ffi_func :sphttp_wait_any,      [],               :int
+  ffi_func :sphttp_write_chunk,   [:int, :str],     :int
+  ffi_func :sphttp_write_chunk_end, [:int],         :int
+
+  # Poll-based I/O readiness, used by Tep::Scheduler.io_wait. Mode
+  # bits in/out: 1=READ, 2=WRITE.
+  ffi_func :sphttp_poll_reset,    [],               :int
+  ffi_func :sphttp_poll_add,      [:int, :int],     :int
+  ffi_func :sphttp_poll_run,      [:int],           :int
+  ffi_func :sphttp_poll_ready,    [:int],           :int
+  ffi_func :sphttp_set_nonblock,  [:int],           :int
+  # Bound a blocking recv (SO_RCVTIMEO, ms). Used by the pooled
+  # outbound client so a no-Content-Length keep-alive response can't
+  # hang the worker. 0 clears the timeout.
+  ffi_func :sphttp_set_recv_timeout, [:int, :int],  :int
+
+  # Outbound TCP for clients (Tep::Http, etc.).
+  ffi_func :sphttp_connect,       [:str, :int],     :int
+  # TLS variant: TCP connect + verified TLS handshake (SNI + hostname
+  # + peer cert). Returns an fd whose write/recv/close transparently
+  # route through the SSL*. -1 on connect/handshake/verify failure.
+  ffi_func :sphttp_connect_tls,   [:str, :int],     :int
+  # Inbound (server) TLS (tep#148 phase 2). server_init loads cert+key
+  # once (before prefork); accept_tls wraps an accepted fd in a TLS
+  # handshake (0 ok / -1 fail, caller closes). read/write/close then
+  # route through the SSL* via the same fd registry.
+  ffi_func :sphttp_tls_server_init, [:str, :str],   :int
+  ffi_func :sphttp_accept_tls,      [:int],         :int
+  # Non-blocking TLS (tep#150 outbound coop + scheduled inbound). *_start
+  # sets up the SSL but does NOT run the handshake; handshake_step drives
+  # one SSL_do_handshake (0=done / 1=want-read / 2=want-write / -1=fail)
+  # so a fiber parks on io_wait between steps. io_status reports the last
+  # recv/handshake want-state (0 ok / 1 read / 2 write / 3 eof / -1 err)
+  # so the coop recv loops tell a TLS partial record from a real EOF.
+  ffi_func :sphttp_tls_connect_start,  [:str, :int], :int
+  ffi_func :sphttp_tls_accept_start,   [:int],       :int
+  ffi_func :sphttp_tls_handshake_step, [:int],       :int
+  ffi_func :sphttp_io_status,          [],           :int
+  ffi_func :sphttp_recv_some,     [:int, :int],     :str
+  ffi_func :sphttp_recv_all,      [:int, :int],     :str
+
+  # popen-shaped shell capture used by Tep::Shell.run. File I/O goes
+  # through spinel's built-in File.read / File.write since master
+  # (matz/spinel#505 made File.write binary-safe).
+  ffi_func :sphttp_shell_capture, [:str, :int],     :str
+end
+
+# Crypto FFI -- SHA-256/HMAC/PBKDF2/B64URL/random. Symbols live in
+# spinel's libspinel_rt.a (added upstream as lib/sp_crypto.c via
+# matz/spinel#514), which the spinel driver auto-links into every
+# binary. No ffi_cflags needed; just declare the signatures.
+module Crypto
+  ffi_func :sp_crypto_hmac_sha256_hex,      [:str, :str],       :str
+  ffi_func :sp_crypto_hmac_sha256_b64url,   [:str, :str],       :str
+  ffi_func :sp_crypto_b64url_encode,        [:str],             :str
+  ffi_func :sp_crypto_b64url_decode,        [:str],             :str
+  ffi_func :sp_crypto_pbkdf2_sha256_b64url, [:str, :str, :int], :str
+  ffi_func :sp_crypto_random_b64url,        [:int],             :str
+  # SHA-1 + WebSocket accept-key compute. SHA-1 is shipped only
+  # because RFC 6455 requires it for the Sec-WebSocket-Accept
+  # derivation; do NOT use it for anything else (collision-broken).
+  ffi_func :sp_crypto_sha1_hex,             [:str],             :str
+  ffi_func :sp_crypto_websocket_accept,     [:str],             :str
+end