Documentation
¶
Overview ¶
Package nodeproto is the contract of the node-to-node request protocols: the protocol identifiers, the request and answer of each, the byte limit of each message and the framing rules. A message is deterministic CBOR with integer keys, decoded with the strict rules of package record, so two nodes that agree on a message agree on its bytes.
The package carries records and envelopes as opaque bytes or as decoded shapes and never judges them: signatures, the envelope's own rules and authorization belong to the packages that own those rules. It opens no stream; the network layer applies the limits and the framing. See README.md.
Index ¶
- Constants
- Variables
- func AppendFrame(dst, payload []byte, max int) ([]byte, error)
- func IsLegacy(protocol string) bool
- func Offer(protocol string) []string
- func Protocols() []string
- func ReadFrame(r *bufio.Reader, max int) ([]byte, error)
- func ReadMessage(r io.Reader, max int) ([]byte, error)
- type DialBackAnswer
- type DialBackRequest
- type DialBackResult
- type DirectoryAdapter
- type DirectoryAnswer
- type DirectoryEntry
- type DirectoryRequest
- type Limit
- type Outcome
- type ProfileAnswer
- type ProfileRequest
- type PullAnswer
- type PullRequest
- type SendAnswer
- type SendRequest
Constants ¶
const ( // ProtocolSend carries one envelope to a recipient's node. An envelope sent // under it may choose the model and the effort of a new session, and the // answer to a status request lists what each preset allows. ProtocolSend = "/sidera/send/3.0.0" // PreviousProtocolSend is the send protocol before an envelope could choose a // session's model. It is framed as the current one is; its messages are the // same without the choice. A node serves it so that a node that has not been // upgraded can still send, and asks it of a node that serves no newer one. PreviousProtocolSend = "/sidera/send/2.0.0" // ProtocolPull asks for the current reports of the deliveries of one message. ProtocolPull = "/sidera/pull/2.0.0" // ProtocolDirectory asks for a page of the endpoints a node shows the asker, // each with the adapter that serves it. ProtocolDirectory = "/sidera/directory/3.0.0" // PreviousProtocolDirectory is the directory protocol before entries named // their adapter. It is framed as the current one is; its entries are the same // without the adapter. A node serves it so that a node that has not been // upgraded can still ask, and asks it of a node that serves no newer one. PreviousProtocolDirectory = "/sidera/directory/2.0.0" // ProtocolDialBack asks a member whether it can dial the asker back on the // addresses it holds for it. It was framed from its first version and has no // legacy identifier. ProtocolDialBack = "/sidera/dial-back/1.0.0" // ProtocolProfile asks a member for the signed node profile it has issued for // itself. It was framed from its first version and has no legacy identifier. ProtocolProfile = "/sidera/profile/1.0.0" )
The protocol identifiers of the member protocols. Each is one request and one answer on one stream, each a frame of its own (AppendFrame, ReadFrame): the client does not half-close after its request, so the server cannot take the end of the stream for the end of the request, and it keeps the stream until the client has taken the answer and closed. They are defined here and nowhere else; the pre-authentication access table lists no protocol of this package, so each falls under "every other protocol", which only members may use.
const ( LegacyProtocolSend = "/sidera/send/1.0.0" LegacyProtocolPull = "/sidera/pull/1.0.0" LegacyProtocolDirectory = "/sidera/directory/1.0.0" )
The identifiers a node before 2.0.0 speaks, kept so that nodes upgraded one at a time still understand each other. On such a stream the request is everything up to the client's half-close (ReadMessage), the answer everything up to the end of the stream, and the server releases the stream as soon as it has answered. Messages, limits and access are those of the current identifier of the protocol. A node serves both and a client offers the current identifier first (Offer); the legacy ones are dropped once no node that speaks only them remains in use.
const ( // MaxReasonLen is the longest refusal reason name, in bytes. MaxReasonLen = 64 // MaxCursorLen is the longest directory continuation, in bytes. The engine's // own cursors are about 130 bytes; the limit leaves room to grow. MaxCursorLen = 256 // MaxDirectoryPage is the most entries one directory answer lists: a node // has at most this many endpoints. MaxDirectoryPage = publication.MaxEndpointsPerNode // MaxRecipients is the most recipients one request names or one answer // reports on: the bound of the envelope. MaxRecipients = envelope.MaxRecipients )
const MaxAddressLen = 256
MaxAddressLen is the longest multiaddr, in bytes, a dial-back answer carries.
const ReasonDialBackBusy = "busy"
ReasonDialBackBusy is the reason a node refuses a dial-back request with when it is already dialing back for the asker, or for as many nodes as it will at once.
Variables ¶
var ErrFrame = errors.New("invalid frame")
ErrFrame is wrapped by every refusal of the framing: a length prefix that is not the one shortest encoding, a frame that is empty or above the bound. A stream that ends inside a frame is io.ErrUnexpectedEOF.
var ErrInvalid = errors.New("invalid node protocol message")
ErrInvalid is wrapped by every refusal of a message whose bytes decode but break a rule of the protocol: an unknown outcome, a list over its bound, a field that does not belong to the outcome. Bytes that do not decode, are not canonical or exceed the limit wrap the errors of package record.
Functions ¶
func AppendFrame ¶
AppendFrame appends one frame of a multi-frame stream to dst: the length of the payload as an unsigned varint, then the payload. A payload of no bytes or of more than max bytes is refused, because no reader would take it.
func IsLegacy ¶ added in v0.13.0
IsLegacy reports whether the identifier is one of the legacy ones, whose streams are not framed.
func Offer ¶ added in v0.13.0
Offer returns the identifiers a client proposes for a call to a protocol, in the order of preference: the current identifier, then the older ones the protocol has. It is nil for an identifier that is not a current one.
func Protocols ¶
func Protocols() []string
Protocols lists every identifier a node serves, the current ones first, in a stable order.
func ReadFrame ¶
ReadFrame reads one frame written by AppendFrame. It returns io.EOF when the stream ends cleanly before a frame, and wraps ErrFrame for anything else that is wrong with one. The length is checked against max before any byte of the payload is read or allocated, so a hostile length costs nothing. The prefix must be the shortest encoding of its value: an overlong one is refused, so that one payload has one stream form.
func ReadMessage ¶
ReadMessage reads the one message of a single-message protocol: everything up to the end of the stream, which the writer's half-close marks. It reads at most max bytes plus one and refuses more with record.ErrOversize, so a peer cannot make the reader hold more than the limit. The read ends with the reader's own error, a deadline included.
Types ¶
type DialBackAnswer ¶ added in v0.13.0
type DialBackAnswer struct {
Outcome Outcome
Result DialBackResult
// Address is the address of the asker that connected, without a /p2p/ part;
// present exactly when the result is reached.
Address ma.Multiaddr
Reason string
}
DialBackAnswer is the target's answer to a dial-back request. With the outcome ok it holds a result and, for a result of reached, the address that connected. A refused answer carries the reason name and a failed one nothing.
func DecodeDialBackAnswer ¶ added in v0.13.0
func DecodeDialBackAnswer(data []byte) (DialBackAnswer, error)
DecodeDialBackAnswer parses a dial-back answer strictly, within the answer limit of the protocol. A result goes with the outcome ok and with no other, and an address with the result reached and with no other; the address is a binary multiaddr of at most MaxAddressLen bytes in the one form the library writes.
func (DialBackAnswer) Encode ¶ added in v0.13.0
func (a DialBackAnswer) Encode() ([]byte, error)
Encode returns the canonical bytes of the answer. It refuses what DecodeDialBackAnswer would.
type DialBackRequest ¶ added in v0.13.0
type DialBackRequest struct{}
DialBackRequest asks the target to dial the asker back. It carries nothing: the target dials only the addresses it holds for the asking node, which is the asker's own question ("can you reach me the way you would if you had to find me"), and it also means the request cannot be used to make the target dial an address of the asker's choosing. The asking node is the one the connection authenticated.
func DecodeDialBackRequest ¶ added in v0.13.0
func DecodeDialBackRequest(data []byte) (DialBackRequest, error)
DecodeDialBackRequest parses a dial-back request strictly, within the request limit of the protocol: it is the empty map and nothing else.
func (DialBackRequest) Encode ¶ added in v0.13.0
func (DialBackRequest) Encode() ([]byte, error)
Encode returns the canonical bytes of the request, the empty map.
type DialBackResult ¶ added in v0.13.0
type DialBackResult uint8
DialBackResult is what an answered dial-back says. The zero value is not a result.
const ( // DialBackReached: a new connection to the asker was made and its secure // handshake and stream-muxer negotiation completed. DialBackReached DialBackResult = iota + 1 // DialBackNotReached: the target holds addresses for the asker and none of // them connected within the target's connect budget. DialBackNotReached // DialBackNoAddress: the target holds no address for the asker. DialBackNoAddress )
The results of a dial-back that was made.
func (DialBackResult) String ¶ added in v0.13.0
func (r DialBackResult) String() string
String returns the name of the result.
type DirectoryAdapter ¶ added in v0.17.0
type DirectoryAdapter struct {
Instance string
ID string
Version string
Runtime *adapterproto.RuntimeInfo
}
DirectoryAdapter is the adapter instance behind a directory entry: the instance that serves the endpoint on its node, the adapter it runs and, when the target knows them, the adapter's version and the runtime it drives. An instance and an adapter id follow the syntax of an adapter identifier, a version is a Semantic Versioning 2.0.0 version, and the runtime follows the rules of the probe that reports it and, as a text shown to a person, those of a display name.
type DirectoryAnswer ¶
type DirectoryAnswer struct {
Outcome Outcome
Entries []DirectoryEntry
NextCursor string
Reason string
}
DirectoryAnswer is the target's answer to a directory request. With the outcome ok it holds a page of entries and, when more follow, the cursor of the next page. A refused answer carries the reason name and a failed one nothing.
func DecodeDirectoryAnswer ¶
func DecodeDirectoryAnswer(data []byte) (DirectoryAnswer, error)
DecodeDirectoryAnswer parses a directory answer of ProtocolDirectory.
func DecodeDirectoryAnswerFor ¶ added in v0.17.0
func DecodeDirectoryAnswerFor(protocol string, data []byte) (DirectoryAnswer, error)
DecodeDirectoryAnswerFor parses a directory answer strictly, within the answer limit of the protocol, as the directory protocol of that identifier carries it: an entry of an older protocol has no adapter, and an answer that has one is invalid, as it is to a node that speaks only that protocol. An entry names a kind and actions by their names, a display name of at most adapterproto.MaxDisplayName characters holding none of the characters adapterproto.RefusedInPersonText names, a description of at most adapterproto.MaxDescription holding none that adapterproto.RefusedInDescription names, and, under ProtocolDirectory, an adapter that follows the rules of DirectoryAdapter. An entry that breaks a rule makes the whole answer invalid; the text is valid UTF-8, which the decoder guarantees.
func (DirectoryAnswer) Encode ¶
func (a DirectoryAnswer) Encode() ([]byte, error)
Encode returns the canonical bytes of the answer under ProtocolDirectory. It refuses what DecodeDirectoryAnswer would.
func (DirectoryAnswer) EncodeFor ¶ added in v0.17.0
func (a DirectoryAnswer) EncodeFor(protocol string) ([]byte, error)
EncodeFor returns the canonical bytes of the answer as the directory protocol of that identifier carries it. The older protocols have no adapter in an entry, so the adapters of the entries are left out. It refuses what DecodeDirectoryAnswerFor would.
type DirectoryEntry ¶
type DirectoryEntry struct {
Endpoint ident.EndpointID
Kind adapterreg.EndpointKind
DisplayName string
Description string
Actions []authz.Action
// Adapter says which adapter serves the endpoint; nil when the target does not
// say. It exists only under ProtocolDirectory.
Adapter *DirectoryAdapter
}
DirectoryEntry is one open endpoint the target shows. It carries the endpoint's identifier and not its node: the asker knows the node it called and fills it in, and never takes one from the answer.
type DirectoryRequest ¶
type DirectoryRequest struct {
Sender ident.EndpointID
Cursor string
Limit int
}
DirectoryRequest asks for a page of the open endpoints the target shows the asker, after the opaque cursor of a previous page. A zero Limit leaves the page size to the target; a limit that is present is 1 to MaxDirectoryPage. The asking node is the one the connection authenticated.
func DecodeDirectoryRequest ¶
func DecodeDirectoryRequest(data []byte) (DirectoryRequest, error)
DecodeDirectoryRequest parses a directory request strictly, within the request limit of the protocol. A cursor is 1 to MaxCursorLen bytes of visible ASCII when present; its meaning is the target's.
func (DirectoryRequest) Encode ¶
func (r DirectoryRequest) Encode() ([]byte, error)
Encode returns the canonical bytes of the request. It refuses what DecodeDirectoryRequest would, a negative limit included.
type Limit ¶
Limit is the byte limit of the two messages of one protocol: the longest request a server reads and the longest answer a client reads. A reader stops at the limit and refuses more, before it decodes anything.
func LimitOf ¶
LimitOf returns the byte limits of a protocol, the same for its current and its older identifiers, and false for an identifier that is not one of this package's. On a framed stream the limit bounds the payload of the frame.
A send request holds one envelope. A send or pull answer holds a report per recipient and a control reply, each at the most the record limit. A directory answer holds a page of entries.
type Outcome ¶
type Outcome uint8
Outcome says how the target handled a request.
const ( // OutcomeOK: the request was handled and the answer carries the result. OutcomeOK Outcome = iota + 1 // OutcomeRefused: the target refused the request for a reason it names. OutcomeRefused // OutcomeFailed: the target could not handle the request and says nothing // more; no receipt exists. OutcomeFailed )
The outcomes. The zero value is not an outcome.
type ProfileAnswer ¶ added in v0.17.0
type ProfileAnswer struct {
Outcome Outcome
// Profile is present exactly when the outcome is ok. Only its shape is
// checked here: whether it is a profile of the target, its signature and its
// fields are the asker's to verify, with the certificate it holds for the
// target.
Profile *record.Record
Reason string
}
ProfileAnswer is the target's answer to a profile request. With the outcome ok it holds the target's signed node profile, as the target signed it. A refused answer carries the reason name and a failed one nothing.
func DecodeProfileAnswer ¶ added in v0.17.0
func DecodeProfileAnswer(data []byte) (ProfileAnswer, error)
DecodeProfileAnswer parses a profile answer strictly, within the answer limit of the protocol. The profile goes with the outcome ok and with no other, and an ok answer without one is invalid.
func (ProfileAnswer) Encode ¶ added in v0.17.0
func (a ProfileAnswer) Encode() ([]byte, error)
Encode returns the canonical bytes of the answer. It refuses what DecodeProfileAnswer would.
type ProfileRequest ¶ added in v0.17.0
type ProfileRequest struct{}
ProfileRequest asks the target for its current node profile. It carries nothing: the target answers with the profile it has issued for itself, which is the same for every asker the connection lets in, and the asking node is the one the connection authenticated.
func DecodeProfileRequest ¶ added in v0.17.0
func DecodeProfileRequest(data []byte) (ProfileRequest, error)
DecodeProfileRequest parses a profile request strictly, within the request limit of the protocol: it is the empty map and nothing else.
func (ProfileRequest) Encode ¶ added in v0.17.0
func (ProfileRequest) Encode() ([]byte, error)
Encode returns the canonical bytes of the request, the empty map.
type PullAnswer ¶
type PullAnswer struct {
Outcome Outcome
Reports []record.Record
NoRecord []ident.EndpointID
ControlReply *record.Record
Reason string
}
PullAnswer is the target's answer to a pull. With the outcome ok, each recipient of the request is in at most one of Reports (its signed report, in a record the answer does not attribute to a recipient) and NoRecord (the target holds no record of that delivery); a recipient in neither has nothing to report yet. A refused or failed answer carries what the send answer's does.
func DecodePullAnswer ¶
func DecodePullAnswer(data []byte) (PullAnswer, error)
DecodePullAnswer parses a pull answer strictly, within the answer limit of the protocol. Reports and no-record entries together are at most MaxRecipients, the most a request names, and the no-record endpoints are distinct. The records' shape is read, nothing is verified.
func (PullAnswer) Encode ¶
func (a PullAnswer) Encode() ([]byte, error)
Encode returns the canonical bytes of the answer. It refuses what DecodePullAnswer would.
type PullRequest ¶
type PullRequest struct {
Message delivery.MessageID
Recipients []ident.EndpointID
}
PullRequest asks for the current reports of the asker's deliveries of one message to the listed recipients on the target. The asking node is the one the connection authenticated. A request names at least one recipient, and the target answers for each of them and for no other.
func DecodePullRequest ¶
func DecodePullRequest(data []byte) (PullRequest, error)
DecodePullRequest parses a pull request strictly, within the request limit of the protocol. The message identifier follows envelope.ValidMessageID, and the recipients are 1 to MaxRecipients distinct endpoints.
func (PullRequest) Encode ¶
func (r PullRequest) Encode() ([]byte, error)
Encode returns the canonical bytes of the request. It refuses what DecodePullRequest would.
type SendAnswer ¶
type SendAnswer struct {
Outcome Outcome
Reports []record.Record
ControlReply *record.Record
Reason string
}
SendAnswer is the target's answer to a send. With the outcome ok it carries the signed status reports for the recipients on the target and, for a control signal that already has one, the control reply: the receipt. A refused outcome carries the name of the refusal reason and nothing else; a failed one carries nothing: no receipt exists.
func DecodeSendAnswer ¶
func DecodeSendAnswer(data []byte) (SendAnswer, error)
DecodeSendAnswer parses a send answer strictly, within the answer limit of the protocol. It reads the records' shape only; whether a report is for the envelope that was sent, and its signature, are the sender's to check.
func (SendAnswer) Encode ¶
func (a SendAnswer) Encode() ([]byte, error)
Encode returns the canonical bytes of the answer. It refuses what DecodeSendAnswer would.
type SendRequest ¶
type SendRequest struct {
Sender ident.EndpointID
Envelope []byte
}
SendRequest carries one envelope from an endpoint of the sending node. The envelope is the bytes the sender encoded: the target decodes and judges them with package envelope. The sending node is the one the connection authenticated; only the endpoint is in the message.
func DecodeSendRequest ¶
func DecodeSendRequest(data []byte) (SendRequest, error)
DecodeSendRequest parses a send request strictly, within the request limit of the protocol. The envelope must be present and at most envelope.MaxEncoded bytes; its content is not read.
func (SendRequest) Encode ¶
func (r SendRequest) Encode() ([]byte, error)
Encode returns the canonical bytes of the request. It refuses what DecodeSendRequest would.