nodeproto

package
v0.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 16 Imported by: 0

README

nodeproto

The contract of the node-to-node request protocols: the protocol identifiers, the request and answer of each, their byte limits and the framing rules. Read ../README.md first for the conventions every contract package follows, and the topic document for the formats and the reasons behind them. This package is pure data: the network layer opens the streams, applies the limits and the framing, and hands the decoded messages to the engine.

Entry points

Name Purpose
ProtocolSend, PreviousProtocolSend, ProtocolPull, ProtocolDirectory, PreviousProtocolDirectory, LegacyProtocolSend, LegacyProtocolPull, LegacyProtocolDirectory, ProtocolDialBack, ProtocolProfile, Protocols() The identifiers (2.0.0, framed; for send 3.0.0, which carries a session's model choice, with 2.0.0 kept as PreviousProtocolSend; for the directory 3.0.0, whose entries name their adapter, with 2.0.0 kept as PreviousProtocolDirectory; the 1.0.0 ones of the nodes before it, kept until no such node is in use; and the dial-back and profile protocols, framed from their first version and with no legacy form), defined here and nowhere else. They are not in the pre-authentication access table, so only members may use them.
Offer(protocol), IsLegacy(protocol) The identifiers a client proposes for a call, newest first and the legacy one last where the protocol has one; whether an identifier is a legacy one, whose streams are not framed.
LimitOf(protocol), Limit The byte limit of the request a server reads and of the answer a client reads, the same under every identifier of a protocol; on a framed stream, the limit of the frame's payload.
Outcome, OutcomeOK, OutcomeRefused, OutcomeFailed How the target handled a request; the first field of every answer.
SendRequest, SendAnswer, DecodeSendRequest, DecodeSendAnswer Send: an envelope as bytes; the receipt.
PullRequest, PullAnswer, DecodePullRequest, DecodePullAnswer Pull: a message and its recipients; reports, no-record endpoints and the control reply.
DirectoryRequest, DirectoryAnswer, DirectoryEntry, DirectoryAdapter, DecodeDirectoryRequest, DecodeDirectoryAnswer, DecodeDirectoryAnswerFor, DirectoryAnswer.EncodeFor Directory: a cursor and a page size; a page of entries, each with the adapter that serves it under 3.0.0. Encode and DecodeDirectoryAnswer are those of 3.0.0; the For forms take the identifier the stream got, and under 2.0.0 or 1.0.0 leave the adapter out and refuse an answer that has one.
DialBackRequest, DialBackAnswer, DialBackResult, DecodeDialBackRequest, DecodeDialBackAnswer, ReasonDialBackBusy, MaxAddressLen Dial-back: an empty request; whether the target could dial the asker back, and the address that connected.
ProfileRequest, ProfileAnswer, DecodeProfileRequest, DecodeProfileAnswer Profile: an empty request; the target's signed node profile, whose shape only is checked here.
ReadMessage(r, max) Reads the one message of a legacy (1.0.0) stream to its end, at most max bytes.
AppendFrame, ReadFrame One frame: an unsigned varint length, then the payload. A 2.0.0 member stream is one frame each way; the pairing protocol's streams are many.

Every message has an Encode method and a Decode… function. Errors wrap ErrInvalid for a rule of the protocol, ErrFrame for the framing, and the errors of record (ErrOversize, ErrMalformed, ErrNotCanonical) for bytes that do not decode.

Rules

  • Strict, canonical, one place. A message is a map with integer keys, decoded with record.UnmarshalStrict, so the bytes of a message that decodes are its one canonical encoding. Encode runs its output through the decoder, so the rules of a message live in its decoder alone.
  • Shape, not verdict. Records are read with record.Decode; nothing here verifies a signature or reads an envelope. Those belong to the engine and envelope.
  • Fields follow the outcome. A reason is present exactly when the outcome is refused; a refused or failed answer carries no records, entries, cursor or dial-back result.
  • Limits come from the rules. The send request is sized from envelope.MaxEncoded(); counts of recipients, records and entries are the bounds of envelope, record and publication.
  • No node in a message. The sender node is the one the connection authenticated, and a directory entry names no node: the asker fills in the one it called.

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

View Source
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.

View Source
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.

View Source
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
)
View Source
const MaxAddressLen = 256

MaxAddressLen is the longest multiaddr, in bytes, a dial-back answer carries.

View Source
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

View Source
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.

View Source
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

func AppendFrame(dst, payload []byte, max int) ([]byte, error)

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

func IsLegacy(protocol string) bool

IsLegacy reports whether the identifier is one of the legacy ones, whose streams are not framed.

func Offer added in v0.13.0

func Offer(protocol string) []string

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

func ReadFrame(r *bufio.Reader, max int) ([]byte, error)

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

func ReadMessage(r io.Reader, max int) ([]byte, error)

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

type Limit struct {
	Request int
	Answer  int
}

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

func LimitOf(protocol string) (Limit, bool)

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.

func (Outcome) String

func (o Outcome) String() string

String returns the name of the 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址