hop-endpoint 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 28842786d70c3471cfb49cc90b3ed1c611de8b109816235d94328f6b470c0f83
+  data.tar.gz: '08a7c7f9782a88233bdb6064213bb47e44ca73360aa05d736e32fddfbf4bed74'
+SHA512:
+  metadata.gz: 3005f4bfb8aac1a6d5d796a7f39d5d978cd4af34373e3bf9917f1f3733403b74802ff9d21f103da5560eb5d4fa7080334ec14a9285b408720cdd27c4a42164e8
+  data.tar.gz: 82a538d1ea0675abf7e85001c5417abbf556499bf1ff996f3b3731cccb7e45a86a2550ce88d27dae51832e1378f089080b6c7a66a4e64dbb42a01b28cc49b9d3

data/README.md

@@ -0,0 +1,146 @@
+<p align="center">
+  <img alt="Hop" src="https://hopme.sh/hop-mark.svg" width="200">
+</p>
+
+<h1 align="center">hop-endpoint</h1>
+
+<p align="center">
+  <b>Receive Hop messages in your Ruby service.</b><br>
+  A Sinatra/Rails-shaped endpoint on the <a href="https://hopme.sh">Hop</a> mesh, over the <code>libhop</code> C ABI.
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/hop-endpoint"><img src="https://img.shields.io/gem/v/hop-endpoint?color=cc342d&label=gem" alt="gem"></a>
+  <img src="https://img.shields.io/badge/license-Apache--2.0-3ddc84" alt="license">
+  <img src="https://img.shields.io/badge/ruby-%E2%89%A53.0-6ea8fe" alt="ruby >=3.0">
+</p>
+
+---
+
+Hop is a **delay-tolerant mesh**: end-to-end encrypted datagrams that hop device to device, over BLE,
+Wi-Fi, and the internet, until they reach the person or service you meant. Held, never dropped.
+
+`hop-endpoint` is the **server side**: your Ruby service becomes a first-class address on the mesh, so
+senders hand messages straight to it. Self-host is an import, not an ops project. No inbound port to open
+to the world, no bearer tokens to rotate, no message queue to run: the sender identity is authenticated
+by the ratchet, and delivery is durable and store-and-forward. **Zero gems**, `Fiddle` is Ruby's stdlib FFI.
+
+## Install
+
+```sh
+gem install hop-endpoint
+```
+
+You also need `libhop`, the Rust protocol core, as a prebuilt binary or a local build, pointed to with
+`HOP_LIBDIR`. See [libhop](https://github.com/hopmesh/libhop). Ruby 3.0+ (`Fiddle`, `OpenSSL`, `Socket`,
+`Net::HTTP`, `JSON` are all stdlib).
+
+## Quick start
+
+```ruby
+require "hop"
+require "json"
+
+hop = Hop::Endpoint.new
+
+hop.on("acme/orders") do |req, reply|
+  # req.from is a VERIFIED identity (base58), not a spoofable header
+  order = JSON.parse(req.text)
+  reply.call(201, JSON.generate({ ok: true, order: order })) # uint16 status + body
+end
+
+Hop::TcpBearer.listen(hop, 9944) # reachable by any device
+puts hop.address                 # publish this (or its name); senders reach you by it
+```
+
+**The DX looks like HTTP; the semantics are better.** Inbound is a durable, store-and-forward consume; a
+reply is a new addressed message that may arrive later, even after a restart. It works when the peer is
+offline, and there is no auth layer to bolt on, the identity is cryptographic. core is poll-model, so the
+endpoint runs a background pump thread (the node is thread-safe).
+
+## Reachable by name
+
+Make an endpoint reachable at `myaddress.com` with no new port, on a pure-stdlib WebSocket bearer (zero
+gems). `attach` wires the WSS bearer (`/_hop`) and the discovery route (`/.well-known/hop`) in one call:
+
+```ruby
+require "openssl"
+ctx = OpenSSL::SSL::SSLContext.new
+ctx.cert = OpenSSL::X509::Certificate.new(File.read("cert.pem"))
+ctx.key  = OpenSSL::PKey::RSA.new(File.read("key.pem"))
+hop.attach(443, ctx, "wss://myaddress.com/_hop")
+```
+
+A client reaches it by name, verified end to end:
+
+```ruby
+address = client.dial_by_name("https://myaddress.com")
+status, body = client.request(address, "acme/orders", "create", order)
+```
+
+TLS proves the domain, a signed **reach record** proves the address, and the Noise handshake confirms it.
+Spoof the `A` record or MITM the lookup and the attacker still can't forge the cert or complete the
+handshake as the address, and a request sealed to that address is unreadable to anyone else.
+
+## Rails / Rack
+
+The endpoint is just an object with a pump thread, so it drops into a long-running process. In a Rails
+app, build one `Hop::Endpoint` in an initializer, keep it in a constant or a singleton, register your
+`on(...)` handlers there, and call `attach` to serve WSS on the same host. The handler block runs off the
+request cycle (it is the mesh inbox, not a controller action): enqueue a job, write a row, then
+`reply.call`.
+
+## How it maps to the core
+
+The endpoint is a `hop-core` node in host-a-mailbox mode, over the same C ABI every Hop SDK binds (via
+`Fiddle`), with zero core changes:
+
+| Endpoint                   | libhop C ABI                                               |
+| -------------------------- | ---------------------------------------------------------- |
+| `hop.on(svc) { }`          | `hop_subscribe` + `hop_poll_service_requests`              |
+| `reply.call(status, body)` | `hop_send_service_response` (status is a `uint16`)         |
+| `hop.request(...)`         | `hop_send_service_request` + `hop_poll_service_responses`  |
+| the Internet bearer        | `hop_link_up` / `hop_bytes_received` / `hop_drain_outgoing`|
+
+## Examples
+
+Point `HOP_LIBDIR` at a built `libhop`, then:
+
+```sh
+ruby -Ilib test/test_hop.rb    # in-process + reach record + WSS discovery, all pass
+ruby examples/raw_roundtrip.rb # raw C ABI round trip (proves the Fiddle bindings)
+ruby examples/echo.rb          # the hop.on / reply DX in-process
+ruby examples/tcp.rb           # the same round trip over a real TCP bearer
+ruby examples/discovery.rb     # the full reachable-by-name chain (HTTPS + WSS)
+```
+
+Two-process shape (a standalone server plus a client that dials it):
+
+```sh
+ruby examples/server.rb                    # prints its address, listens on tcp://0.0.0.0:9944
+ruby examples/client.rb <address> localhost 9944
+```
+
+## Status
+
+Prototype. Built and working: the `on` block handler and `reply`, the client `request`, the in-process /
+TCP / WSS bearers, base58 addressing, reach-record `attach` / `dial_by_name` discovery, sibling-replica
+clustering, the ABI-version assert, and a use-after-free-safe `close` (bearer threads that fire after
+teardown short-circuit instead of touching a freed node). HNS name publish/resolve and multi-tenant
+hosting are on the roadmap (each an SDK-level follow-up, not a core change).
+
+## The Hop family
+
+`hop-endpoint` is one of several SDKs over the same C ABI. Same surface, your language:
+[node](https://github.com/hopmesh/hop-sdk-node) ·
+[python](https://github.com/hopmesh/hop-sdk-python) ·
+[go](https://github.com/hopmesh/hop-sdk-go) ·
+[ruby](https://github.com/hopmesh/hop-sdk-ruby) ·
+[crystal](https://github.com/hopmesh/hop-sdk-crystal) ·
+[elixir](https://github.com/hopmesh/hop-sdk-elixir).
+The protocol core is [libhop](https://github.com/hopmesh/libhop) / [hop-core](https://github.com/hopmesh/hop-core).
+
+## License
+
+[Apache-2.0](./LICENSE.md), embed it freely. Only the protocol core (`hop-core`) is FSL-1.1-ALv2,
+source-available and converting to Apache-2.0 after two years.

data/lib/hop/dev_tls.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Hop
+  # DEV/TEST ONLY: an in-process self-signed cert for the discovery example + test (no `openssl` CLI,
+  # no gems; OpenSSL ships with Ruby). Never use a self-signed cert in production; there a real WebPKI
+  # cert proves the domain.
+  module DevTls
+    # An SSLContext backed by a fresh in-process self-signed cert (RSA-2048, CN=<cn>, 1h).
+    def self.server_context(cn = "localhost")
+      key = OpenSSL::PKey::RSA.new(2048)
+      cert = OpenSSL::X509::Certificate.new
+      cert.version = 2
+      cert.serial = 1
+      cert.subject = OpenSSL::X509::Name.parse("/CN=#{cn}")
+      cert.issuer = cert.subject
+      cert.public_key = key.public_key
+      cert.not_before = Time.now - 60
+      cert.not_after = Time.now + 3600
+      cert.sign(key, OpenSSL::Digest.new("SHA256"))
+      ctx = OpenSSL::SSL::SSLContext.new
+      ctx.cert = cert
+      ctx.key = key
+      ctx
+    end
+  end
+end

data/lib/hop/discovery.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Discovery: bind a name to a Hop address using the domain's TLS cert (WebPKI) plus a
+# self-certifying reachability record served at /.well-known/hop. See docs/endpoint-sdk.md.
+require "json"
+require "base64"
+require "net/http"
+require "uri"
+require "openssl"
+require "hop/ffi"
+
+module Hop
+  module Discovery
+    WELL_KNOWN_PATH = "/.well-known/hop"
+
+    def self.well_known_body(endpoint, public_url, ttl_secs = 3600)
+      record = endpoint.sign_reach(public_url, ttl_secs)
+      JSON.generate({ "address" => endpoint.address, "endpoint" => public_url, "reach" => Base64.strict_encode64(record) })
+    end
+
+    # Fetch + verify base_url's well-known. Returns {address:, address_bytes:, wss_url:}. Raises on a
+    # missing/malformed/unverified record.
+    def self.resolve(base_url, insecure_tls: false)
+      uri = URI.parse(base_url)
+      http = Net::HTTP.new(uri.host, uri.port || 443)
+      http.use_ssl = true
+      http.verify_mode = insecure_tls ? OpenSSL::SSL::VERIFY_NONE : OpenSSL::SSL::VERIFY_PEER
+      res = http.get(WELL_KNOWN_PATH)
+      raise "well-known fetch failed: HTTP #{res.code}" unless res.code.to_i == 200
+
+      body = JSON.parse(res.body)
+      info = Hop::FFI.verify_reach(Base64.strict_decode64(body["reach"]), Time.now.to_i)
+      raise "reach record failed verification (bad signature or expired)" unless info
+
+      { address: Hop::FFI.to_b58(info[:address]), address_bytes: info[:address], wss_url: info[:endpoint] }
+    end
+  end
+end

data/lib/hop/endpoint.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "timeout"
+require "hop/ffi"
+
+module Hop
+  # An inbound service request. `from` is the cryptographically verified sender identity (base58).
+  Request = Struct.new(:from, :from_bytes, :service, :method, :args) do
+    def text = args
+  end
+
+  # Receive Hop messages in Ruby with a Sinatra/Rails-shaped surface, over the libhop C ABI.
+  #
+  #   hop = Hop::Endpoint.new
+  #   hop.on("acme/orders") { |req, reply| reply.call(201, "ok") }  # req.from is VERIFIED
+  #
+  # Semantics: inbound is a durable store-and-forward consume; a reply is a new addressed message that
+  # may arrive later. The DX is HTTP-shaped; delivery is delay-tolerant. core is poll-model, so the
+  # endpoint runs a background pump thread (the node is thread-safe).
+  class Endpoint
+    # Sentinel pushed to a pending request queue by #close, so a blocked caller fails fast instead of
+    # waiting out its full timeout. A unique object, never equal to a real [status, body] response.
+    CLOSED = Object.new
+
+    def initialize(key: nil, tick_ms: 50, cluster: nil, quorum: nil)
+      Hop::FFI.assert_abi!
+      @node = key ? Hop::FFI.node_with_secret(key) : Hop::FFI.node_new
+      Hop::FFI.tick(@node, now_ms)
+      Hop::FFI.publish_prekey(@node)
+      @handlers = {}
+      @links = {}
+      @pending = {}
+      @closers = []
+      @mutex = Mutex.new         # guards @pending
+      @node_lock = Monitor.new   # serializes every libhop call on @node vs. #close; reentrant so a
+      @closed = false            # reply issued from inside #pump re-enters without deadlocking
+      cluster(cluster) if cluster # dedup across sibling replicas (same identity, no shared store)
+      cluster_quorum(quorum) if quorum # TTL-based visibility threshold; not consensus
+      @thread = Thread.new { pump_loop(tick_ms / 1000.0) }
+    end
+
+    def address = Hop::FFI.to_b58(address_bytes)
+    def address_bytes = with_node { |n| Hop::FFI.address(n) }
+
+    # Join the endpoint cluster so sibling replicas (same identity, no shared datastore) each handle a
+    # given request once. Pass a String passphrase (interops with the service's HOP_CLUSTER_SECRET) or
+    # a 32-byte binary String secret. Dedup then applies transparently. Returns self.
+    def cluster(secret_or_passphrase)
+      if secret_or_passphrase.is_a?(String) && secret_or_passphrase.encoding != Encoding::BINARY
+        with_node { |n| Hop::FFI.cluster_join_passphrase(n, secret_or_passphrase) }
+      else
+        b = secret_or_passphrase.to_str
+        raise ArgumentError, "cluster secret must be 32 bytes or a passphrase string" unless b.bytesize == 32
+        with_node { |n| Hop::FFI.cluster_join(n, b) }
+      end
+      self
+    end
+
+    # Live replica count (self + peers within the membership TTL); 1 if not clustered.
+    def cluster_members = with_node { |n| Hop::FFI.cluster_members(n) }
+
+    # Require at least +min+ live cluster members visible before this replica will process a request
+    # using a TTL-based visibility threshold. This is a conservative failover heuristic, not consensus
+    # or an at-most-once guarantee. 0 or 1 disables it. Returns self.
+    def cluster_quorum(min)
+      with_node { |n| Hop::FFI.cluster_set_quorum(n, min) }
+      self
+    end
+
+    # Register a receiver for a hops:// service. The block gets (req, reply); reply is a callable
+    # reply.call(status, body).
+    def on(service, &block)
+      with_node { |n| Hop::FFI.subscribe(n, service) }
+      @handlers[service] = block
+      self
+    end
+
+    # Call a service on a remote endpoint. Blocks until the response returns (delay-tolerant).
+    def request(dst, service, method, args = "", timeout: 15.0)
+      dst_bytes = dst.is_a?(String) && dst.bytesize == 32 ? dst : Hop::FFI.from_b58(dst)
+      q = Queue.new
+      # Send and register the waiter atomically under @node_lock so #pump (which also holds it) cannot
+      # deliver the response before @pending knows to route it.
+      req_id = with_node do |n|
+        id = Hop::FFI.send_service_request(n, dst_bytes, service, method, to_bytes(args))
+        @mutex.synchronize { @pending[id] = q }
+        id
+      end
+      raise "endpoint is closed" unless req_id
+
+      begin
+        res = Timeout.timeout(timeout) { q.pop } # [status, body], or CLOSED if #close woke us
+        raise "endpoint is closed" if res == CLOSED
+        res
+      rescue Timeout::Error
+        @mutex.synchronize { @pending.delete(req_id) }
+        raise "hops://#{service}/#{method} timed out after #{timeout}s"
+      end
+    end
+
+    # Sign a self-certifying reachability record for this endpoint's address bound to `endpoint`.
+    def sign_reach(endpoint, ttl_secs = 3600) = with_node { |n| Hop::FFI.sign_reach(n, endpoint, ttl_secs) }
+
+    # Start an HTTPS server (WSS bearer at /_hop + /.well-known/hop) IN ONE CALL. `public_url` is where
+    # senders reach it, e.g. "wss://myaddress.com/_hop". Returns the server (call #shutdown to stop).
+    def attach(port, ssl_context, public_url, ttl_secs: 3600)
+      require "hop/wss_bearer"
+      Hop::WssBearer.serve(self, port, ssl_context, public_url, ttl_secs)
+    end
+
+    # Resolve a base HTTPS URL to a verified endpoint, dial its WSS, and return the reachable address
+    # (then use #request). Set insecure_tls: true only for a dev/self-signed cert.
+    def dial_by_name(base_url, insecure_tls: false)
+      require "hop/discovery"
+      require "hop/wss_bearer"
+      info = Hop::Discovery.resolve(base_url, insecure_tls: insecure_tls)
+      Hop::WssBearer.dial(self, info[:wss_url], insecure_tls: insecure_tls)
+      info[:address]
+    end
+
+    # Register a teardown hook (e.g. a bearer's listening socket). #close runs these before freeing the
+    # node so bearer threads unblock and exit. If already closed, the hook fires immediately.
+    def register_closer(&block)
+      run_now = @node_lock.synchronize { @closed ? true : (@closers << block; false) }
+      block.call if run_now
+    end
+
+    # ---- bearer seam (called from bearer threads) ----
+    def register_link(link, role, send_fn)
+      with_node do |n|
+        @links[link] = send_fn
+        Hop::FFI.connected(n, link, role == :dialer)
+      end
+    end
+
+    def deliver(link, data) = with_node { |n| Hop::FFI.received(n, link, data) }
+
+    def link_down(link)
+      with_node do |n|
+        @links.delete(link)
+        Hop::FFI.disconnected(n, link)
+      end
+    end
+
+    def close
+      @node_lock.synchronize do
+        return if @closed
+
+        @closed = true
+      end
+      @closers.each { |c| c.call rescue nil } # unblock bearer accept/read threads so they exit
+      # Wake any in-flight request waiters so they fail fast instead of blocking their full timeout.
+      @mutex.synchronize do
+        @pending.each_value { |q| q.push(CLOSED) }
+        @pending.clear
+      end
+      @thread.join(1) unless Thread.current == @thread
+      # Free only after @closed is set and the pump has stopped: a late bearer-thread call (a WSS
+      # run_link firing #link_down as its socket EOFs) now short-circuits in #with_node instead of
+      # dereferencing a freed node.
+      @node_lock.synchronize do
+        next unless @node
+
+        Hop::FFI.node_free(@node)
+        @node = nil
+      end
+    end
+
+    private
+
+    def now_ms = (Time.now.to_f * 1000).to_i
+    def to_bytes(v) = v.is_a?(String) ? v.b : v.to_s.b
+
+    # Run a libhop call on the node under the reentrant lock, unless the endpoint has been closed (in
+    # which case @node may already be freed, so we must not touch it). Returns nil when closed.
+    def with_node
+      @node_lock.synchronize do
+        return nil if @closed
+
+        yield @node
+      end
+    end
+
+    def pump_loop(dt)
+      until @closed
+        begin
+          pump
+        rescue StandardError => e
+          warn "hop pump error: #{e}"
+        end
+        sleep(dt)
+      end
+    end
+
+    def pump
+      snapshot = with_node do |n|
+        Hop::FFI.tick(n, now_ms)
+        outgoing = Hop::FFI.drain_outgoing(n).map { |link, data| [@links[link], data] }
+        [outgoing, Hop::FFI.take_service_requests(n), Hop::FFI.take_service_responses(n)]
+      end
+      return unless snapshot
+
+      outgoing, requests, responses = snapshot
+      outgoing.each { |fn, data| fn&.call(data) }
+      requests.each do |frm, rid, service, method, args|
+        handler = @handlers[service]
+        next unless handler
+
+        req = Request.new(Hop::FFI.to_b58(frm), frm, service, method, args)
+        reply = ->(status, body = "") { with_node { |n| Hop::FFI.send_service_response(n, frm, rid, status, to_bytes(body)) } }
+        handler.call(req, reply)
+      end
+      responses.each do |_frm, for_id, status, body|
+        q = @mutex.synchronize { @pending.delete(for_id) }
+        q&.push([status, body])
+      end
+    end
+  end
+end

data/lib/hop/ffi.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# Raw Fiddle bindings to libhop (the C ABI, sdk/hop.h). Fiddle is Ruby's stdlib FFI (like ctypes), so
+# this SDK has no native-gem build. Thin and one-to-one; ergonomics live in endpoint.rb.
+require "fiddle"
+
+module Hop
+  module FFI
+    P  = Fiddle::TYPE_VOIDP
+    I  = Fiddle::TYPE_INT
+    LL = Fiddle::TYPE_LONG_LONG
+    SZ = Fiddle::TYPE_SIZE_T
+    CH = Fiddle::TYPE_CHAR
+    V  = Fiddle::TYPE_VOID
+
+    ABI_EXPECTED = 3
+
+    def self.lib_path
+      ext = case RbConfig::CONFIG["host_os"]
+            when /darwin/ then "dylib"
+            when /mswin|mingw/ then "dll"
+            else "so"
+            end
+      repo = File.expand_path("../../../..", __dir__) # sdk/ruby/lib/hop -> repo root
+      candidates = []
+      candidates << File.join(ENV["HOP_LIBDIR"], "libhop.#{ext}") if ENV["HOP_LIBDIR"]
+      candidates << File.join(repo, "target", "debug", "libhop.#{ext}")
+      candidates << File.join(repo, "target", "release", "libhop.#{ext}")
+      found = candidates.find { |c| File.exist?(c) }
+      raise "libhop.#{ext} not found. Build it with `cargo build -p hop` or set HOP_LIBDIR.\n" \
+            "Looked in:\n  #{candidates.join("\n  ")}" unless found
+
+      found
+    end
+
+    LIB = Fiddle.dlopen(lib_path)
+    private_class_method def self.fn(name, args, ret) = Fiddle::Function.new(LIB[name], args, ret)
+
+    ABI_VERSION            = fn("hop_abi_version", [], I)
+    NODE_NEW               = fn("hop_node_new", [], P)
+    NODE_WITH_SECRET       = fn("hop_node_with_secret", [P, SZ], P)
+    NODE_FREE              = fn("hop_node_free", [P], V)
+    NODE_ADDRESS           = fn("hop_node_address", [P, P], CH)
+    NODE_TICK              = fn("hop_node_tick", [P, LL], V)
+    LINK_UP                = fn("hop_link_up", [P, LL, I], V)
+    BYTES_RECEIVED         = fn("hop_bytes_received", [P, LL, P, SZ], V)
+    LINK_DOWN              = fn("hop_link_down", [P, LL], V)
+    DRAIN_OUTGOING         = fn("hop_drain_outgoing", [P, P, P], V)
+    SUBSCRIBE              = fn("hop_subscribe", [P, P], V)
+    PUBLISH_PREKEY         = fn("hop_publish_prekey", [P], CH)
+    SEND_SERVICE_REQUEST   = fn("hop_send_service_request", [P, P, P, P, P, SZ, P], CH)
+    SEND_SERVICE_RESPONSE  = fn("hop_send_service_response", [P, P, P, I, P, SZ], CH)
+    POLL_SERVICE_REQUESTS  = fn("hop_poll_service_requests", [P, P, P], V)
+    POLL_SERVICE_RESPONSES = fn("hop_poll_service_responses", [P, P, P], V)
+    ADDRESS_TO_BASE58      = fn("hop_address_to_base58", [P, P, SZ], SZ)
+    ADDRESS_FROM_BASE58    = fn("hop_address_from_base58", [P, P], CH)
+    SIGN_REACH_RECORD      = fn("hop_sign_reach_record", [P, P, I, P, P], V)
+    VERIFY_REACH_RECORD    = fn("hop_verify_reach_record", [P, SZ, LL, P, P], CH)
+    # Endpoint clustering (DESIGN.md §40).
+    CLUSTER_JOIN            = fn("hop_cluster_join", [P, P], V)
+    CLUSTER_JOIN_PASSPHRASE = fn("hop_cluster_join_passphrase", [P, P, SZ], V)
+    CLUSTER_MEMBERS         = fn("hop_cluster_members", [P], I)
+    CLUSTER_SET_QUORUM      = fn("hop_cluster_set_quorum", [P, I], V)
+
+    Closure = Fiddle::Closure::BlockCaller
+
+    def self.assert_abi!
+      got = ABI_VERSION.call
+      raise "libhop ABI mismatch: wrapper expects #{ABI_EXPECTED}, library reports #{got}" if got != ABI_EXPECTED
+    end
+
+    # ---- helpers: read C memory that is valid only during a call ----
+    def self.read_bytes(ptr, len) = len.zero? ? "".b : Fiddle::Pointer.new(ptr)[0, len].b
+    def self.read_cstr(ptr) = Fiddle::Pointer.new(ptr).to_s
+
+    # ---- thin wrappers ----
+    def self.node_new = NODE_NEW.call
+    def self.node_with_secret(secret) = NODE_WITH_SECRET.call(secret, secret.bytesize)
+    def self.node_free(node) = NODE_FREE.call(node)
+    def self.tick(node, now_ms) = NODE_TICK.call(node, now_ms)
+    def self.connected(node, link, initiator) = LINK_UP.call(node, link, initiator ? 0 : 1)
+    def self.disconnected(node, link) = LINK_DOWN.call(node, link)
+    def self.received(node, link, data) = BYTES_RECEIVED.call(node, link, data, data.bytesize)
+    def self.subscribe(node, topic) = SUBSCRIBE.call(node, topic)
+    def self.cluster_join(node, secret) = CLUSTER_JOIN.call(node, secret)
+    def self.cluster_join_passphrase(node, pass) = CLUSTER_JOIN_PASSPHRASE.call(node, pass, pass.bytesize)
+    def self.cluster_members(node) = CLUSTER_MEMBERS.call(node)
+    def self.cluster_set_quorum(node, min) = CLUSTER_SET_QUORUM.call(node, min)
+    def self.publish_prekey(node) = PUBLISH_PREKEY.call(node) != 0
+
+    def self.address(node)
+      out = Fiddle::Pointer.malloc(32, Fiddle::RUBY_FREE)
+      NODE_ADDRESS.call(node, out)
+      out[0, 32].b
+    end
+
+    def self.drain_outgoing(node)
+      out = []
+      sink = Closure.new(V, [P, LL, P, SZ]) { |_ctx, link, ptr, len| out << [link, read_bytes(ptr, len)] }
+      DRAIN_OUTGOING.call(node, sink, nil)
+      out
+    end
+
+    def self.send_service_request(node, dst, service, method, args)
+      out = Fiddle::Pointer.malloc(32, Fiddle::RUBY_FREE)
+      ok = SEND_SERVICE_REQUEST.call(node, dst, service, method, args, args.bytesize, out) != 0
+      raise "hop_send_service_request failed" unless ok
+
+      out[0, 32].b
+    end
+
+    def self.send_service_response(node, to, for_request_id, status, body)
+      SEND_SERVICE_RESPONSE.call(node, to, for_request_id, status, body, body.bytesize) != 0
+    end
+
+    def self.take_service_requests(node)
+      out = []
+      sink = Closure.new(V, [P, P, P, P, P, P, SZ]) do |_ctx, frm, rid, service, method, args, arglen|
+        out << [read_bytes(frm, 32), read_bytes(rid, 32), read_cstr(service), read_cstr(method), read_bytes(args, arglen)]
+      end
+      POLL_SERVICE_REQUESTS.call(node, sink, nil)
+      out
+    end
+
+    def self.take_service_responses(node)
+      out = []
+      sink = Closure.new(V, [P, P, P, I, P, SZ]) do |_ctx, frm, for_id, status, body, body_len|
+        out << [read_bytes(frm, 32), read_bytes(for_id, 32), status & 0xFFFF, read_bytes(body, body_len)]
+      end
+      POLL_SERVICE_RESPONSES.call(node, sink, nil)
+      out
+    end
+
+    def self.to_b58(addr32)
+      out = Fiddle::Pointer.malloc(64, Fiddle::RUBY_FREE)
+      n = ADDRESS_TO_BASE58.call(addr32, out, 64)
+      out[0, n]
+    end
+
+    def self.from_b58(text)
+      out = Fiddle::Pointer.malloc(32, Fiddle::RUBY_FREE)
+      raise "not a valid Hop address: #{text}" if ADDRESS_FROM_BASE58.call(text, out).zero?
+
+      out[0, 32].b
+    end
+
+    def self.sign_reach(node, endpoint, ttl_secs)
+      result = nil
+      sink = Closure.new(V, [P, P, SZ]) { |_ctx, ptr, len| result = read_bytes(ptr, len) }
+      SIGN_REACH_RECORD.call(node, endpoint, ttl_secs, sink, nil)
+      result
+    end
+
+    def self.verify_reach(record, now_secs)
+      info = nil
+      sink = Closure.new(V, [P, P, P, LL, I]) do |_ctx, addr, endpoint, issued_at, ttl_secs|
+        info = { address: read_bytes(addr, 32), endpoint: read_cstr(endpoint), issued_at: issued_at, ttl_secs: ttl_secs }
+      end
+      ok = VERIFY_REACH_RECORD.call(record, record.bytesize, now_secs, sink, nil) != 0
+      ok ? info : nil
+    end
+  end
+end

data/lib/hop/tcp_bearer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Hop
+  # The raw-TCP Internet bearer: opaque Hop frames over TCP, core does the Noise. TCP is a stream, so
+  # each drained packet is length-prefixed (4-byte big-endian) and reassembled on the far side.
+  module TcpBearer
+    MAX_FRAME_BYTES = 1 << 20
+    @seq = 40_000
+    @seq_mutex = Mutex.new
+    def self.next_link = @seq_mutex.synchronize { @seq += 1 }
+
+    def self.send_framed(sock, buf)
+      sock.write([buf.bytesize].pack("N") + buf)
+    rescue IOError, Errno::EPIPE, Errno::ECONNRESET, Errno::EBADF
+      nil
+    end
+
+    def self.read_exact(sock, n)
+      data = +"".b
+      while data.bytesize < n
+        chunk = sock.read(n - data.bytesize)
+        return nil unless chunk
+
+        data << chunk
+      end
+      data
+    end
+
+    def self.recv_loop(endpoint, sock, link)
+      loop do
+        hdr = read_exact(sock, 4)
+        break unless hdr
+
+        n = hdr.unpack1("N")
+        break if n > MAX_FRAME_BYTES
+        frame = n.zero? ? "".b : read_exact(sock, n)
+        break unless frame
+
+        endpoint.deliver(link, frame)
+      end
+    rescue IOError, Errno::ECONNRESET, Errno::EBADF
+      nil
+    ensure
+      endpoint.link_down(link)
+      begin
+        sock.close
+      rescue StandardError
+        nil
+      end
+    end
+
+    def self.listen(endpoint, port, host: "0.0.0.0")
+      server = TCPServer.new(host, port)
+      sockets = {}
+      sockets_mutex = Mutex.new
+      closing = false
+      endpoint.register_closer do
+        sockets_mutex.synchronize do
+          closing = true
+          server.close rescue nil
+          sockets.each_key { |socket| socket.close rescue nil }
+        end
+      end
+      Thread.new do
+        loop do
+          sock = begin
+            server.accept
+          rescue StandardError
+            break
+          end
+          reject = sockets_mutex.synchronize do
+            if closing
+              true
+            else
+              sockets[sock] = true
+              false
+            end
+          end
+          if reject
+            sock.close rescue nil
+            next
+          end
+          link = next_link
+          endpoint.register_link(link, :acceptor, ->(buf) { send_framed(sock, buf) })
+          Thread.new do
+            recv_loop(endpoint, sock, link)
+            sockets_mutex.synchronize { sockets.delete(sock) }
+          end
+        end
+      end
+      server
+    end
+
+    def self.dial(endpoint, host, port)
+      sock = TCPSocket.new(host, port)
+      link = next_link
+      endpoint.register_link(link, :dialer, ->(buf) { send_framed(sock, buf) })
+      endpoint.register_closer { sock.close rescue nil }
+      Thread.new { recv_loop(endpoint, sock, link) }
+      sock
+    end
+  end
+end

data/lib/hop/wss_bearer.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+# The WSS Internet bearer for a Ruby endpoint, in pure stdlib (no gems): a minimal RFC 6455 WebSocket
+# (Upgrade handshake + binary framing) over the stdlib socket + OpenSSL. The server also answers GET
+# /.well-known/hop on the same port, so attach wires both. core does the Noise + crypto over the frame
+# payloads; one drained packet is one binary WS message. IO buffering (gets then read) cleanly
+# separates the HTTP handshake from the frame stream, so a header read never over-consumes frame bytes.
+require "socket"
+require "openssl"
+require "digest/sha1"
+require "base64"
+require "uri"
+require "hop/discovery"
+
+module Hop
+  module WssBearer
+    GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+    MAX_FRAME_BYTES = 1 << 20
+
+    @seq = 60_000
+    @seq_mutex = Mutex.new
+    def self.next_link = @seq_mutex.synchronize { @seq += 1 }
+
+    def self.accept_key(key) = Base64.strict_encode64(Digest::SHA1.digest(key + GUID))
+
+    def self.encode_frame(payload, mask)
+      n = payload.bytesize
+      header = (+"\x82").b # FIN + binary opcode
+      mb = mask ? 0x80 : 0
+      if n < 126
+        header << (mb | n).chr
+      elsif n < 65_536
+        header << (mb | 126).chr << [n].pack("n")
+      else
+        header << (mb | 127).chr << [n].pack("Q>")
+      end
+      if mask
+        mk = Random.bytes(4)
+        header << mk << apply_mask(payload, mk)
+      else
+        header << payload
+      end
+      header
+    end
+
+    def self.apply_mask(data, mask)
+      out = data.dup.b
+      out.bytesize.times { |i| out.setbyte(i, out.getbyte(i) ^ mask.getbyte(i % 4)) }
+      out
+    end
+
+    def self.read_exact(sock, n)
+      return "".b if n.zero?
+
+      data = sock.read(n)
+      raise EOFError, "closed" unless data && data.bytesize == n
+
+      data
+    end
+
+    def self.read_frame(sock)
+      b0, b1 = read_exact(sock, 2).bytes
+      opcode = b0 & 0x0F
+      masked = (b1 & 0x80) != 0
+      len = b1 & 0x7F
+      len = read_exact(sock, 2).unpack1("n") if len == 126
+      len = read_exact(sock, 8).unpack1("Q>") if len == 127
+      raise IOError, "WebSocket frame exceeds 1 MiB" if len > MAX_FRAME_BYTES
+      mask = masked ? read_exact(sock, 4) : nil
+      payload = read_exact(sock, len)
+      payload = apply_mask(payload, mask) if mask
+      [opcode, payload]
+    end
+
+    def self.run_link(endpoint, sock, role, mask)
+      link = next_link
+      send_fn = lambda do |buf|
+        sock.write(encode_frame(buf, mask))
+      rescue StandardError
+        nil
+      end
+      endpoint.register_link(link, role, send_fn)
+      loop do
+        opcode, payload = read_frame(sock)
+        break if opcode == 0x8
+
+        endpoint.deliver(link, payload) if [0x2, 0x0].include?(opcode)
+      end
+    rescue EOFError, IOError, OpenSSL::SSL::SSLError, Errno::ECONNRESET
+      nil
+    ensure
+      endpoint.link_down(link)
+      begin
+        sock.close
+      rescue StandardError
+        nil
+      end
+    end
+
+    def self.serve(endpoint, port, ssl_context, public_url, ttl_secs = 3600)
+      tcp = TCPServer.new(port)
+      ssl_server = OpenSSL::SSL::SSLServer.new(tcp, ssl_context)
+      # Let endpoint#close stop the listener so this accept loop exits instead of spinning on a closed
+      # socket (accept on a closed server raises immediately, which without the break is a busy loop).
+      endpoint.register_closer { ssl_server.close rescue nil }
+      Thread.new do
+        loop do
+          sock = begin
+            ssl_server.accept
+          rescue StandardError
+            break if tcp.closed?
+
+            next
+          end
+          Thread.new { handle_conn(endpoint, sock, public_url, ttl_secs) }
+        end
+      end
+      ssl_server
+    end
+
+    def self.handle_conn(endpoint, sock, public_url, ttl_secs)
+      request_line = sock.gets
+      return unless request_line
+
+      _method, path, = request_line.split
+      headers = {}
+      while (line = sock.gets) && line != "\r\n"
+        k, v = line.split(":", 2)
+        headers[k.strip.downcase] = v.strip if v
+      end
+
+      if path == "/.well-known/hop"
+        body = Hop::Discovery.well_known_body(endpoint, public_url, ttl_secs)
+        sock.write("HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: #{body.bytesize}\r\nconnection: close\r\n\r\n#{body}")
+        sock.close
+      elsif path == "/_hop" && headers["upgrade"]&.downcase == "websocket"
+        sock.write("HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: #{accept_key(headers["sec-websocket-key"])}\r\n\r\n")
+        run_link(endpoint, sock, :acceptor, false)
+      else
+        sock.write("HTTP/1.1 404 Not Found\r\nconnection: close\r\n\r\n")
+        sock.close
+      end
+    rescue StandardError
+      begin
+        sock.close
+      rescue StandardError
+        nil
+      end
+    end
+
+    def self.dial(endpoint, wss_url, insecure_tls: false)
+      uri = URI.parse(wss_url)
+      ctx = OpenSSL::SSL::SSLContext.new
+      ctx.verify_mode = insecure_tls ? OpenSSL::SSL::VERIFY_NONE : OpenSSL::SSL::VERIFY_PEER
+      sock = OpenSSL::SSL::SSLSocket.new(TCPSocket.new(uri.host, uri.port || 443), ctx)
+      sock.hostname = uri.host
+      sock.connect
+      key = Base64.strict_encode64(Random.bytes(16))
+      path = uri.path.to_s.empty? ? "/_hop" : uri.path
+      sock.write("GET #{path} HTTP/1.1\r\nHost: #{uri.host}\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Key: #{key}\r\nSec-WebSocket-Version: 13\r\n\r\n")
+      status = sock.gets
+      raise "WS upgrade failed: #{status}" unless status&.include?("101")
+
+      nil while (line = sock.gets) && line != "\r\n" # drain response headers
+      endpoint.register_closer { sock.close rescue nil } # so endpoint#close ends run_link's read loop
+      Thread.new { run_link(endpoint, sock, :dialer, true) }
+      sock
+    end
+  end
+end

data/lib/hop.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Receive Hop messages in Ruby: an embeddable endpoint over the libhop C ABI (via Fiddle, zero gems).
+require "hop/ffi"
+require "hop/endpoint"
+require "hop/tcp_bearer"
+
+module Hop
+  # Wire two endpoints directly (in-process bearer), no sockets. Proves the ergonomics end to end.
+  def self.connect_in_process(a, b, la: 11, lb: 22)
+    a.register_link(la, :dialer, ->(buf) { b.deliver(lb, buf) })
+    b.register_link(lb, :acceptor, ->(buf) { a.deliver(la, buf) })
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: hop-endpoint
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Jason Waldrip
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-07-16 00:00:00.000000000 Z
+dependencies: []
+description: Receive Hop messages in Ruby with a hop.on / reply surface, over libhop
+  via Fiddle. Your service becomes directly reachable on the mesh, no relay. Zero
+  gems (stdlib only).
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/hop.rb
+- lib/hop/dev_tls.rb
+- lib/hop/discovery.rb
+- lib/hop/endpoint.rb
+- lib/hop/ffi.rb
+- lib/hop/tcp_bearer.rb
+- lib/hop/wss_bearer.rb
+homepage: https://hopme.sh
+licenses:
+- Apache-2.0
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Embeddable Hop mesh endpoint for Ruby (Sinatra/Rails-shaped) over the libhop
+  C ABI
+test_files: []