consistent-er terminology

[hawkw]

currently, we are a bit "all over the place" with our terminology.

in particular:

• we use the terms "connection", "stream", and "channel" kind of interchangeably in the code and documentation.
• we seem to sometimes use the term "link" inconsistently — sometimes, i think "link" refers to a physical link between two MGNP peers and all connections on that link, and sometimes we seem to use it to refer to the same thing as a "connection"/"stream"/"channel"?
• what the fuck is an "interface"?
• we could probably replace all uses of "outbound" and "inbound" with "send" and "recv"/"receive", for consistency
• sometimes the term "server" refers to a MGNP peer and sometimes it refers to a service instance...
• possibly we could come up with better terms than "service definition/interface" and "service instance" to refer to the thing that has a UUID and the thing that has a name/eventually a pub key...

[hawkw]

here are some of my proposals for terminology. @jamesmunns, what do you think?

---

wires, peers, and interfaces

MGNP operates over a physical point-to-point link between two peers. This physical link is called a wire. The component running on each peer responsible for the MGNP state machine at that end of the wire is called an interface.

Note

The term "link" MAY be used generically to describe what a "wire" is, but the MGNP protocol does not contain an entity called a "link".

connections, clients, servers, and streams

MGNP interfaces multiplex multiple connections over a single wire. Connections are between MGNP clients and MGNP servers. A client is the entity that initiated a connection, while a server is the entity that accepts or rejects it.

MGNP connections are bidirectionally streaming. Each connection consists of two streams. A stream is a sequence of messages received and sent asynchronously.

Note

The term "channel" refers to a data structure in Rust (or another other programming language). This data structure may be used by a MGNP implementation to represent a MGNP stream.

A channel is not a concept that exists in the MGNP protocol, and this term SHOULD NOT be used in descriptions of the protocol.

The term MAY be used in API documentation to refer to the Rust data structure. For example, it is fine to say:

This method takes a pair of pre-allocated bidirectional channels, which are used to represent the MGNP server-to-client and client-to-server streams for the MGNP connection once it is established.

A connection consists of a stream of messages sent by the client to the server, which is called a client-to-server stream, and a stream of messages sent by the server to the client, called a server-to-client stream. The messages sent on the client-to-server stream are called client messages, and the messages sent on the server-to-client stream are called server messages.

Note

The terms "server stream" and "client stream" are ambiguous and SHOULD NOT be used.

frames and messages

MGNP connections transport application layer messages. When an application layer message is sent over the wire, it is sent in a MGNP frame.

A MGNP frame consists of a header and a body. The header contains data used by the MGNP protocol, and identifies the frame type. The body contains the application layer message. Some frames do not have bodies.

the application layer

The application layer consists of clients which initiate MGNP connections and servers which accept connections. The types of messages sent and received by a client is defined by a service. A server implements the application layer interface defined by a service definition.

identity

Services are identified by a UUID. Servers are defined by a server identity. A server identity consists of the UUID of the service implemented by that server, and an instance identifier. An instance identifier uniquely identifies the server. Currently these are strings, but in the future, they may change to ed25519 public keys (see #15).