-
Notifications
You must be signed in to change notification settings - Fork 0
Proposed external functions of holium nodes
Queries available against a holium node parallel the structure of the data a node contains. Whether or not a given result can be shown should depend upon privacy settings, something we don't have implemented or spec'd yet. This document will capture the types of operations and types of returns some other node can receive when querying a node. These functions are only called by other nodes. These functions are prefixed with "your-" to keep them distinct from corresponding and similar internal functions.
your-node-details takes no arguments. When asked of a node, the node responds with a json payload describing the node's ID and listening addresses and ports, as well as the timestamp of the last received response from its underlying urbit instance. In addition to these general details about the node itself, it will also supply an array of 0 to n objects, each corresponding to the spaces it is hosting. A space object will contain
- the space name and description
- the privacy status of the space
- whether or not the current user is a member in the space, and if so, what role they have
- any styles or images required to render a visual selector for the space
- possibly additional metadata like a timestamp of when the space was last active, member count, etc. This is up to the space admins regarding what they choose to expose.
your-space-details takes the name of a space as an argument. When asked of a node, the node responds with a json payload describing the space's details mentioned above, as well as two additional arrays of information:
- members array
-
- ID
-
- status
-
- avatar, nickname, style and other information useful to rendering (actually would this be Passport info?)
- support services array (showing what support services are currently running)
-
- type of service
-
- array of service instances
-
-
- name/ID of instance
-
-
-
- privacy status of the instance
-
-
-
- any styles or images required to render a visual selector for this instance
-
An example would be nice here...
your-space-service-details takes the name of a space and the type of service, optionally taking the identifier for a specific instance of that service. If an instance is supplied, then the response will be a single instance descriptor object. If one isn't supplied, the response will be an array of any running instances of that service type in this space.
An instance descriptor object consists of the name/ID, privacy, and visualization details mentioned above, the other details can potentially be service-specific. For example, many support services (like for chat or realtime collaboration) might share a list of current participants and their statuses. But other support services (like a fileserver) may not. The specifics of the connection details to use the service instance will also likely be service-specific.
your-space-join takes the name of a space as an argument. It indicates to the host that the requesting ship is joining the public space (or a space that it has been invited to if not public)
your-space-leave takes the name of a space as an argument. It indicates to the host that the requesting ship is leaving the named space.
and stuff about roles, requesting to create and or join specific instances, etc. Everything is gonna be public to start with tho. Eventually, we will institute bans, kicks, invites, and join requests