class

Hop::Endpoint

Inherits Reference < Object

Receive Hop messages in Crystal 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 FIBER (spawned; the node is thread-safe). Default runtime is single fiber-scheduled thread; a reentrant Mutex still guards the node so #close can free it safely even under -Dpreview_mt.

Constructors

new(secret : Bytes | Nil = nil, db_path : String | Nil = nil, db_key : Bytes | Nil = nil, app_secret : Bytes | Nil = nil, tick_ms : Int32 = 50, cluster : String | Bytes | Nil = nil, quorum : Int | Nil = nil)

Instance methods

accept_service_request(request_id : Bytes) : Bool

address

address_bytes

attach(port : Int32, tls : OpenSSL::SSL::Context::Server, public_url : String, ttl_secs : UInt32 = 3600_u32, host : String = "0.0.0.0")

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 HTTP::Server (already listening).

channel(service : String, buffer : Int32 = 32) : Channel(Tuple(Request, Reply))

The idiomatic Crystal/Go alternative to a block handler: receive verified requests for service on a Channel and reply from your own fiber (a long-running server usually reads it in a loop, or selects over several services). Same delivery, just channels instead of a callback.

orders = hop.channel("acme/orders") spawn do loop do req, reply = orders.receive reply.call(201, req.text) end end

close

cluster(secret_or_passphrase : String | Bytes) : self

Join the endpoint cluster so sibling replicas (same identity, no shared datastore) each handle a given request once. A String is a passphrase (interops with the standalone service's HOP_CLUSTER_SECRET); a 32-byte Bytes is a raw secret. Dedup then applies transparently.

cluster_mark_done(from : Bytes, request_id : Bytes) : Nil

cluster_members

Live replica count (self + peers within the membership TTL); 1 if not clustered.

cluster_quorum(min : Int) : self

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.

cluster_would_drop(from : Bytes, request_id : Bytes) : Bool

deliver(link : UInt64, data : Bytes) : Nil

dial_by_name(base_url : String, insecure_tls : Bool = false) : String

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.

encrypted?

link_down(link : UInt64) : Nil

on(service : String, &block : Request, Reply -> Nil) : self

Register a receiver for a hops:// service. The block gets (req, reply); reply is a callable reply.call(status, body). This is the surface shared with every Hop SDK.

persistent?

register_closer

Register a teardown hook (e.g. a bearer's listening socket). #close runs these before freeing the node so bearer fibers unblock and exit. If already closed, the hook fires immediately.

register_link(link : UInt64, role : Symbol, send_fn : Bytes -> Nil) : Nil

---- bearer seam (called from bearer fibers) ----

reject_service_request(request_id : Bytes) : Bool

relay_add(url : String, configured : Bool = true) : Bool

Offer a relay endpoint to the pool. configured marks an operator/user choice, which a gossiped endpoint can never demote. Returns true if the endpoint is now pooled.

relay_next

The relay to dial right now, or nil when there is nothing dialable. nil with a non-zero relay_pool total is the degraded "every candidate is backed off" state (wait and retry, this endpoint is not offline); nil with a zero total is an empty pool.

relay_pool

{total pooled endpoints, how many are dialable right now}.

relay_report(url : String, ok : Bool) : self

Feed a dial outcome back to the pool. A success clears that endpoint's failure history; failures back it off exponentially and always eventually recover. Returns self.

request(dst : String | Bytes, service : String, method : String, args : String | Bytes = "", timeout : Time::Span = 15.seconds) : Tuple(UInt16, Bytes)

Call a service on a remote endpoint. Blocks the calling fiber until the response returns (delay-tolerant). dst is a base58 address String or the 32 raw bytes.

sign_reach(endpoint : String, ttl_secs : UInt32 = 3600_u32) : Bytes

Sign a self-certifying reachability record for this endpoint's address bound to endpoint.