discovery-svc
Participants in IPSME can be self reporting — they answer a Discovery query themselves — but there has to be a way to find them before each can be queried. discovery-svc is that registry: a participant registers a connection point, proves that it controls the host it advertises, and is listed until its registration lapses. The service is HTTP only.
registration |
|
|---|---|
query |
|
The messages follow the Discovery-svc interface, version 2: Registration, RegistrationAck and NonceEcho for registering, Discover and Discovered for querying. A connection point follows the shared ConnectionPoint interface. The Discovery-svc interface has no published page yet; its shapes are given below.
Register with discovery-svc
Registering is one HTTP request, POST /register, during which the service dials back to the registrant to verify it. The registrant therefore has to be an HTTP server as well as a client, and its verify endpoint has to be listening before the request is sent.
The registration
{
"registration": {
"type": "STORE",
"cxn-pt": { "protocol": "ipsme+tcp+l4end", "address": "store.example.com", "port": 4998 },
"verify": "http://store.example.com/verify",
"method": "nonce-echo"
},
"discovery-svc": "2"
}
|
What is being registered: |
|---|---|
|
The connection point being advertised — where consumers reach the participant. A ConnectionPoint: either an object |
|
The URL the service POSTs its challenge to. Its host must be exactly the host of |
|
The verification method. Only |
|
The interface version, |
Verification: nonce-echo
The security is topological. The service does not trust the request; it dials out to the host the registrant claims and reads the answer on its own connection, so a forged request proves nothing on its own.
-
The service validates the body against the
RegistrationandConnectionPointinterfaces. -
It checks that the host of
cxn-ptequals the host ofverify. -
It POSTs a
NonceEcho,{ "nonce": "<fresh hex nonce>" }, toverify— with a 2 second connect timeout and a 5 second total timeout. -
The registrant answers 2xx with the same
NonceEchoshape,{ "nonce": "<the same nonce>" }. -
The service commits the registration and replies with the
RegistrationAck.
The verify endpoint therefore has to be reachable from the service (a public address, with the firewall open on its port), listening before the registration is sent, and kept up for the lifetime of the participant, since every re-registration is verified again.
The ack, and how often to re-register
{
"ack": { "ttl_msec": 43200000 },
"_cause": {
// the Registration as sent
}
}
ack.ttl_msec is how long the registration is valid. The record expires on its own after that time; a successful re-registration resets it. Read the value from the ack rather than assume it: the service default is 12 hours (43,200,000 ms), and a deployment can shorten it through the REG_TTL_MSEC environment variable, e.g. for a re-registration test.
Re-register with the same body at half the TTL, so the record never lapses, and retry after a couple of seconds on a failure. A registration is keyed on type and the cxn-pt triple (protocol, address, port), so re-sending the same body refreshes the one record; changing any of these registers a different one. _cause carries the original request, for audit.
Errors
A rejected registration answers { "error": "<reason>" }:
|
|
|---|---|
|
|
|
|
Reference implementations
discovery-svc-reg-cpp |
A test rig for one registration: stands up a |
|---|---|
discovered-store |
A long-running registrant: |
Query discovery-svc
Querying is one JSON-RPC 2.0 call, discover, POSTed to /rpc. Any HTTP client that can send JSON will do: there is no framing to implement and, unlike registering, nothing to verify.
The request
{
"jsonrpc": "2.0", "id": 1,
"method": "discover",
"params": { "name": "curated-lists-discovery", "graphql": "{ discovered(type: STORE) { type cxn-pt ttl_msec } }" }
}
|
Which curated discovery is being performed. Two are served: |
|---|---|
|
A GraphQL-like selection, written by hand — no GraphQL client is needed. |
params may also be positional, [ "<name>", "<graphql>" ]. A request without an id is a notification and answers 204 No Content.
The result
The result is a Discovered:
{
"jsonrpc": "2.0", "id": 1,
"result": {
"discovered": [
{ "type": "STORE", "cxn-pt": { "protocol": "ipsme+tcp+l4end", "address": "store.example.com", "port": 4998 }, "ttl_msec": 43200000 }
],
"discovery-svc": "2"
}
}
Each entry is one live registration, with cxn-pt as the connection-point object that was registered. ttl_msec is the TTL the registration was acknowledged with, not the time remaining; a registrant that stops re-registering simply drops out of the list when its record expires. An empty registry answers an empty discovered array — still a full round-trip through the backend, not an error.
Validate the result against the Discovered interface, and each cxn-pt against ConnectionPoint, before dialing anything. A consumer with more than one discovery service configured can fan the call out and take the first valid answer.
Errors
A failed call answers a JSON-RPC error instead of a result:
|
|
|---|---|
|
|
|
|
Reference implementations
discovery-svc-query-cpp |
A test rig for the query: calls |
|---|---|
store-of-stores |
A consumer: Store-of-stores asks every configured discovery service for |