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

POST http://<discovery-svc-host>:8821/register

query

POST http://<discovery-svc-host>:8823/rpc — JSON-RPC 2.0

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"
}

type

What is being registered: STORE or SUBVERSE. This is what a query filters on.

cxn-pt

The connection point being advertised — where consumers reach the participant. A ConnectionPoint: either an object { "protocol", "address", "port" } or a string protocol://host:port. protocol names the transport served there, e.g. ipsme+tcp+l4end for an IPSME reflector or http+json-rpc for a direct json-rpc endpoint. The port must be numeric; the service stores the triple protocol, address, port.

verify

The URL the service POSTs its challenge to. Its host must be exactly the host of cxn-pt; anything else is rejected, and a URL carrying user information (user@host) is rejected outright. Port and path are free; /verify is the convention, and port 80 may be omitted.

method

The verification method. Only nonce-echo is implemented, so the value is fixed.

discovery-svc

The interface version, "2".

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.

  1. The service validates the body against the Registration and ConnectionPoint interfaces.

  2. It checks that the host of cxn-pt equals the host of verify.

  3. It POSTs a NonceEcho, { "nonce": "<fresh hex nonce>" }, to verify — with a 2 second connect timeout and a 5 second total timeout.

  4. The registrant answers 2xx with the same NonceEcho shape, { "nonce": "<the same nonce>" }.

  5. 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>" }:

400

malformed json; not a valid Registration; cxn-pt is not a valid connection-point; cxn-pt: cannot derive protocol/address; host(cxn-pt) != host(verify).

403

verify dial failed (the service could not reach verify); verify response not json; nonce echo mismatch.

502

backend commit failed — also the result of a non-numeric port or an unknown type.

Reference implementations

discovery-svc-reg-cpp

A test rig for one registration: stands up a /verify echo server, POSTs the registration, prints and validates the ack, exits. Run as client-reg http <registry-host> <registry-port> <own-host> <verify-port> <world-port>. Not public yet.

discovered-store

A long-running registrant: discovered-store serves /verify for its lifetime, registers at start-up, and re-registers at half the acknowledged TTL, retrying every two seconds while the service is unreachable.

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 } }" }
}

name

Which curated discovery is being performed. Two are served: subverse-discovery-svc, and curated-lists-discovery — stores offering curated lists, what the Store-of-stores asks for. Any other name is refused.

graphql

A GraphQL-like selection, written by hand — no GraphQL client is needed. discovered(type: T) selects which registration type to list: STORE, SUBVERSE, or NULL for every registration. The selectable fields are type, cxn-pt and ttl_msec. cxn-pt is the interface’s own field name, not legal GraphQL; the service rewrites it for its backend and renames it back on the way out, so the consumer only ever speaks the wire vocabulary.

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:

-32602

invalid_params — an unknown name. The caller’s fault.

-32603

internal_error — the backend round-trip failed, errored, or returned something malformed, or the service built a result that fails its own schema. The service’s side; an attributable line lands in its log.

-32601

method_not_found — any method other than discover. Doubles as a cheap liveness probe: a service that answers this error is up and speaking JSON-RPC.

Reference implementations

discovery-svc-query-cpp

A test rig for the query: calls discover over http+json-rpc, prints the result, validates it as a Discovered and each cxn-pt as a ConnectionPoint. Run as client-query <host> <port> [name] [--concurrent N]; --concurrent N fires N calls on N connections at once. Not public yet.

store-of-stores

A consumer: Store-of-stores asks every configured discovery service for curated-lists-discovery in parallel and takes the first valid Discovered. Off the query path, it probes each configured address with an unknown method and shows the reachable/unreachable result in its settings.