protocol-Discovery Specification

Protocols: Discovery protocol

Discovery-Svc

Registration

JSON Schema, Draft-07

https://json-schema.org/specification-links.html#draft-7

{
	"$id": "validate_MsgSvcRegistration",
	"$schema": "http://json-schema.org/draft-07/schema#",
	"type" : "object",
	"required" : ["discovery-svc-registration"],
	"properties" : {
		"discovery-svc-registration" : {
			"type" : "object",
			"required": ["type", "address", "protocol", "api"],
			"properties": {
				"type" : { "type" : "string" },
				"address" : { "type" : "string" },
				"protocol" : { "type" : "string" },
				"api" : { "type" : "string" }
			}
		}
	}
}
JSON example
{
	"discovery-svc-registration": {
		"type": "SUBVERSE",
		"address": "<reflector-server-address>:<port>",
		"protocol": "tcp+l4end",
		"api": "IPSME:reflector-sdbus"
	},

	// ... JSON_Msg format
}

  • discovery-svc-registration

    • type — what type of address are you registering?

    • address — the address you want to register; an IPSME reflector server ready to accept connections.

    • protocol — what protocol does the server expect to be connected with.

    • api — name of the API the address will respond to e.g., the sdbus and NSDNC IPSME implementations differ slightly.

  • …​ JSON_Msg

ACK

JSON example
{
	"registration": {
		"ok": true,
		"expires": "2023-07-17T07:01:49Z"
	}

	// ... JSON_Msg_msg format
	"_msg": { <original registration msg> },
}

  • registration

    • ok — true, on success; note UDP, so a successful ACK could be dropped.

    • expires — when the registration expires, requiring an updated registration.

  • …​ JSON_Msg_msg

Discovery

JSON Schema, Draft-07

https://json-schema.org/specification-links.html#draft-7

{
	"$id": "validate_MsgDiscovery",
	"$schema": "http://json-schema.org/draft-07/schema#",
	"type" : "object",
	"required" : ["discovery"],
	"properties" : {
		"discovery" : {
			"type" : "object",
			"required": [ "name", "graphql", "ttl_msec" ],
			"properties": {
				"name" : {
					"type" : "string"
				},
				"graphql" : {
					"type" : "string"
				},
				"ttl_msec" : {
					"type" : "integer"
				}
			}
		}
	}
}

  • discovery

    • name — 

    • graphql — the discovery query uses GraphQL style queries, because GraphQL is easily extensible. The graphql tag can be replaced by another tag if a different protocol is to be used.

    • ttl_msec — 

Announcement

JSON Schema, Draft-07

https://json-schema.org/specification-links.html#draft-7

{
	"$id": "validate_MsgAnnouncement",
	"$schema": "http://json-schema.org/draft-07/schema#",
	"type" : "object",
	"required" : ["announcement"],
	"properties" : {
		"announcement" : {
			"type" : "object"
		}
	}
}

Discovered

TODO: …​

Subverse/Instances

JSON example
{
	"announcement": {
		"subverse": {
			// ...
		}
	}

	// ... JSON_Msg_msg format
}

  • announcement

    • subverse — the subverse object is equal to the Subverse or the Instance JSON.


Subverse, JSON Schema, Draft-07

https://json-schema.org/specification-links.html#draft-7

{
	"$id": "validate_subverse_subverse",
	"$schema": "http://json-schema.org/draft-07/schema#",
	"type" : "object",
	"required" : [ "name", "map", "logo", "protocols" ],
	"properties" : {
		"name" : {"type" : "string" },
		"map" : {"type" : "string" },
		"logo" : {"type" : "string" },
		"platforms" : {
			"type": "array",
			"items": {
				"type" : "object",
				"required": [ "name" ],
				"properties": {
					"name": { "type": "string" },
					"archs": {
						"type": "array",
						"items": { "type" : "string" }
					},
					"agents": {
						"type": "array",
						"items": { "type" : "string" }
					}
				}
			}
		},
		"protocols" : {
			"type": "array",
			"items": {
				"type" : "object",
				"required": [ "name", "attr" ],
				"properties" : {
					"name": { "type" : "string" },
					"attr": { "type" : "string" }
				}
			}
		}
	}
}

  • protocols

    • name — name of the protocol; optional @version number appended

    • attr

      • 0 — the protocol is native to the subverse; no translator is required

      • r — reading of the protocol is supported; the subverse uses the protocol to speak

      • w — writing of the protocol is supported; the protocol can be used to speak to the subverse


Instances, JSON Schema, Draft-07

https://json-schema.org/specification-links.html#draft-7

{
	"$id": "validate_subverse_instances",
	"$schema": "http://json-schema.org/draft-07/schema#",
	"type" : "object",
	"required" : ["instances", "protocols"],
	"properties" : {
		"instances" : {
			"type" : "array",
			"items": {
				"type" : "object",
				"required": [ "name", "logo", "link" ],
				"properties": {
					"name": { "type" : "string" },
					"logo": { "type" : "string" },
					"link": { "type" : "string" }
				}
			}
		},
		"platforms" : {
			"type": "array",
			"items": {
				"type" : "object",
				"required": [ "name" ],
				"properties": {
					"name": { "type": "string" },
					"archs": {
						"type": "array",
						"items": { "type" : "string" }
					},
					"agents": {
						"type": "array",
						"items": { "type" : "string" }
					}
				}
			}
		},
		"protocols" : {
			"type": "array",
			"items": {
				"type" : "object",
				"required": [ "name", "attr" ],
				"properties" : {
					"name": { "type" : "string" },
					"attr": { "type" : "string" }
				}
			}
		}
	}
}

IOI // better name!

UUI