package relayproto

Import Path
	github.com/tmc/go-iroh/internal/relayproto (on go.dev)

Dependency Relation
	imports 10 packages, and imported by 2 packages

Involved Source Files

	    datagrams.go
	  d frame.go
		Package relayproto implements the iroh relay wire protocol: the framing,
		datagram, and handshake messages exchanged between a relay client and server.
		
		It is a port of iroh-relay/src/protos. Frames are carried in binary WebSocket
		messages; each frame begins with a QUIC-varint frame type followed by a
		type-specific payload. The encodings here are byte-for-byte compatible with
		the Rust reference (verified by golden snapshot tests).

	    handshake.go
	    messages.go
	    varint.go
Package-Level Type Names (total 12)

	/* sort by: alphabet | popularity */
	 type ClientAuth (struct)
		ClientAuth is the client's authentication response: its public key and a
		signature of the challenge's message-to-sign.

		Fields (total 2)
			PublicKey key.PublicKey
			Signature key.Signature
		Methods (total 2)
			( ClientAuth) AppendTo(dst []byte) []byte
				AppendTo appends the framed wire encoding of a: frame type, the public key's
				32 raw bytes, then the signature as a postcard serde_bytes value (varint
				length 64 followed by the 64 bytes).

			( ClientAuth) Verify(challenge ServerChallenge) error
				Verify checks this client auth against the challenge it answers.

		As Outputs Of (at least one exported)
			func NewClientAuth(secretKey key.SecretKey, challenge ServerChallenge) ClientAuth

	 type ClientToRelayMsg (struct)
		ClientToRelayMsg is a message a client sends to a relay. Exactly one of its
		fields is meaningful, selected by Type.

		Fields (total 4)
			Datagrams Datagrams
			DstEndpointID key.EndpointID
				DstEndpointID / Datagrams for FrameClientToRelayDatagram(Batch).

			Ping [8]byte
				Ping/Pong payload for FramePing/FramePong.

			Type FrameType
		Methods (total 2)
			( ClientToRelayMsg) AppendTo(dst []byte) []byte
				AppendTo appends the wire encoding of m to dst.

			( ClientToRelayMsg) EncodedLen() int
				EncodedLen returns the number of bytes AppendTo writes.

		As Outputs Of (at least 2)
			func ParseClientToRelayMsg(content []byte) (ClientToRelayMsg, error)
			func ParseClientToRelayMsgNoCopy(content []byte) (ClientToRelayMsg, error)
		As Inputs Of (at least one exported)
			func github.com/tmc/go-iroh/internal/relayclient.(*Client).Send(ctx context.Context, msg ClientToRelayMsg) error

	 type Datagrams (struct)
		Datagrams is one or multiple datagrams transferred via the relay, modeled
		after the QUIC transmit structure.

		Fields (total 3)
			Contents []byte
				Contents holds the datagram bytes.

			Ecn EcnCodepoint
				Ecn is the explicit congestion notification codepoint, or 0 for Not-ECT.

			SegmentSize uint16
				SegmentSize is the per-datagram segment size when this transmit carries
				multiple datagrams (a batch); 0 means a single datagram.

		As Outputs Of (at least one exported)
			func DatagramsFromBytes(b []byte) Datagrams

	 type EcnCodepoint uint8 (basic type)
		EcnCodepoint is the QUIC explicit-congestion-notification codepoint carried in
		a relayed datagram (RFC 9000 §13.4 / IP ECN field values).

		As Types Of (total 3)
			const EcnCe
			const EcnEct0
			const EcnEct1

	 type FrameType uint32 (basic type)
		FrameType identifies a relay protocol frame. It is encoded on the wire as a
		QUIC varint.

		Methods (only one)
			( FrameType) String() string
		Implements (at least 2)
			 FrameType : expvar.Var
			 FrameType : fmt.Stringer
		As Types Of (total 14)
			const FrameClientAuth
			const FrameClientToRelayDatagram
			const FrameClientToRelayDatagramBat
			const FrameEndpointGone
			const FrameHealth
			const FramePing
			const FramePong
			const FrameRelayToClientDatagram
			const FrameRelayToClientDatagramBat
			const FrameRestarting
			const FrameServerChallenge
			const FrameServerConfirmsAuth
			const FrameServerDeniesAuth
			const FrameStatus

	 type KeyMaterialClientAuth (struct)
		KeyMaterialClientAuth is the client's 1-RTT relay authentication. It is sent
		in [ClientAuthHeader] as base64url-no-pad postcard bytes.

		Fields (total 3)
			KeyMaterialSuffix [16]byte
			PublicKey key.PublicKey
			Signature key.Signature
		Methods (total 4)
			(*KeyMaterialClientAuth) DecodePostcard(d *postcard.Decoder) error
				DecodePostcard decodes a Rust KeyMaterialClientAuth.

			( KeyMaterialClientAuth) EncodePostcard(e *postcard.Encoder) error
				EncodePostcard encodes a like Rust KeyMaterialClientAuth: raw public key,
				serde_bytes signature, then raw 16-byte suffix.

			( KeyMaterialClientAuth) HeaderValue() (string, error)
				HeaderValue encodes a for [ClientAuthHeader].

			( KeyMaterialClientAuth) Verify(state *tls.ConnectionState) error
				Verify checks this key-material auth against the server's TLS state.

		Implements (at least 2)
			*KeyMaterialClientAuth : github.com/tmc/go-iroh/internal/postcard.DecoderFrom
			 KeyMaterialClientAuth : github.com/tmc/go-iroh/internal/postcard.EncoderTo
		As Outputs Of (at least 2)
			func KeyMaterialClientAuthFromHeader(value string) (KeyMaterialClientAuth, error)
			func NewKeyMaterialClientAuth(secretKey key.SecretKey, state *tls.ConnectionState) (KeyMaterialClientAuth, error)

	 type ProtocolVersion int (basic type)
		ProtocolVersion is the negotiated relay protocol version for a connection.

		Methods (only one)
			( ProtocolVersion) WireString() string
				WireString returns the wire identifier for v.

		As Outputs Of (at least 2)
			func ParseProtocolVersion(s string) (ProtocolVersion, bool)
			func github.com/tmc/go-iroh/internal/relayclient.(*Client).Version() ProtocolVersion
		As Inputs Of (at least 2)
			func ParseRelayToClientMsg(content []byte, version ProtocolVersion) (RelayToClientMsg, error)
			func ParseRelayToClientMsgNoCopy(content []byte, version ProtocolVersion) (RelayToClientMsg, error)
		As Types Of (total 2)
			const ProtocolV1
			const ProtocolV2

	 type RelayToClientMsg (struct)
		RelayToClientMsg is a message a relay sends to a client. Exactly one of its
		fields is meaningful, selected by Type.

		Fields (total 9)
			Datagrams Datagrams
			EndpointGone key.EndpointID
				EndpointGone for FrameEndpointGone.

			Health string
				Health problem text for FrameHealth (deprecated, V1 only).

			Ping [8]byte
				Ping/Pong payload for FramePing/FramePong.

			ReconnectIn time.Duration
				Restarting durations for FrameRestarting.

			RemoteEndpointID key.EndpointID
				Datagrams / RemoteEndpointID for FrameRelayToClientDatagram(Batch).

			Status Status
				Status for FrameStatus.

			TryFor time.Duration
			Type FrameType
		Methods (total 2)
			( RelayToClientMsg) AppendTo(dst []byte) []byte
				AppendTo appends the wire encoding of m to dst.

			( RelayToClientMsg) EncodedLen() int
				EncodedLen returns the number of bytes AppendTo writes.

		As Outputs Of (at least 3)
			func ParseRelayToClientMsg(content []byte, version ProtocolVersion) (RelayToClientMsg, error)
			func ParseRelayToClientMsgNoCopy(content []byte, version ProtocolVersion) (RelayToClientMsg, error)
			func github.com/tmc/go-iroh/internal/relayclient.(*Client).Recv(ctx context.Context) (RelayToClientMsg, error)

	 type ServerChallenge (struct)
		ServerChallenge is the challenge a relay sends a client to sign for endpoint
		authentication.

		Fields (only one)
			Challenge [16]byte
				Challenge is 16 random bytes the client must sign.

		Methods (only one)
			( ServerChallenge) AppendTo(dst []byte) []byte
				AppendTo appends the framed wire encoding (frame type + postcard body) of c.

		As Inputs Of (at least 2)
			func NewClientAuth(secretKey key.SecretKey, challenge ServerChallenge) ClientAuth
			func ClientAuth.Verify(challenge ServerChallenge) error

	 type ServerConfirmsAuth (struct)
		ServerConfirmsAuth confirms a successful connection. Its postcard body is empty.

		Methods (only one)
			( ServerConfirmsAuth) AppendTo(dst []byte) []byte
				AppendTo appends the framed wire encoding of the (empty-bodied) confirmation.


	 type ServerDeniesAuth (struct)
		ServerDeniesAuth denies a connection with a reason.

		Fields (only one)
			Reason string
		Methods (only one)
			( ServerDeniesAuth) AppendTo(dst []byte) []byte
				AppendTo appends the framed wire encoding: frame type then the reason as a
				postcard string (varint byte-length prefix + UTF-8 bytes).


	 type Status uint8 (basic type)
		Status is a one-way relay-to-client message declaring the connection health.

		As Types Of (total 3)
			const StatusHealthy
			const StatusRateLimited
			const StatusSameEndpointIDConnected


Package-Level Functions (total 11)

	 func DatagramsFromBytes(b []byte) Datagrams
		DatagramsFromBytes wraps b as a single (non-batch) datagram.

	 func KeyMaterialClientAuthFromHeader(value string) (KeyMaterialClientAuth, error)
		KeyMaterialClientAuthFromHeader decodes a value from [ClientAuthHeader].

	 func NewClientAuth(secretKey key.SecretKey, challenge ServerChallenge) ClientAuth
		NewClientAuth builds a ClientAuth for challenge using secretKey.

	 func NewKeyMaterialClientAuth(secretKey key.SecretKey, state *tls.ConnectionState) (KeyMaterialClientAuth, error)
		NewKeyMaterialClientAuth builds a client auth header value from exported TLS
		keying material. It returns [ErrNoKeyingMaterial] if state cannot export it.

	 func ParseClientToRelayMsg(content []byte) (ClientToRelayMsg, error)
		ParseClientToRelayMsg decodes a client-to-relay message.

	 func ParseClientToRelayMsgNoCopy(content []byte) (ClientToRelayMsg, error)
		ParseClientToRelayMsgNoCopy decodes a client-to-relay message without
		copying datagram contents. The returned message aliases content.

	 func ParseHandshakeFrame(content []byte) (any, error)
		ParseHandshakeFrame parses one handshake frame from content (frame type +
		postcard body) into the concrete frame value, returning the value as one of
		*ServerChallenge, *ClientAuth, *ServerConfirmsAuth, or *ServerDeniesAuth.

	 func ParseProtocolVersion(s string) (ProtocolVersion, bool)
		ParseProtocolVersion parses a protocol version from its wire identifier.

	 func ParseRelayToClientMsg(content []byte, version ProtocolVersion) (RelayToClientMsg, error)
		ParseRelayToClientMsg decodes a relay-to-client message. version gates the
		deprecated Health (V1 only) and Status (V2+) frames.

	 func ParseRelayToClientMsgNoCopy(content []byte, version ProtocolVersion) (RelayToClientMsg, error)
		ParseRelayToClientMsgNoCopy decodes a relay-to-client message without
		copying datagram contents. The returned message aliases content.

	 func SupportedProtocolVersions() []string
		SupportedProtocolVersions returns the wire identifiers of all supported
		protocol versions, newest first (the order offered to a relay server).


Package-Level Variables (total 11)

	  var ErrFrameNotAllowedInVersion error
		Protocol errors.

	  var ErrFrameTooLarge error
		Protocol errors.

	  var ErrFrameTypeUnexpectedEnd error
		Protocol errors.

	  var ErrHandshakeDeserial error
		Handshake errors.

	  var ErrInvalidFrame error
		Protocol errors.

	  var ErrKeyMaterialSuffix error
		Handshake errors.

	  var ErrNoKeyingMaterial error
		Handshake errors.

	  var ErrServerDeniedAuth error
		Handshake errors.

	  var ErrSignatureInvalid error
		Handshake errors.

	  var ErrUnexpectedFrameTag error
		Handshake errors.

	  var ErrUnknownFrameType error
		Protocol errors.


Package-Level Constants (total 25)

	const ClientAuthHeader = "x-iroh-relay-client-auth-v1"
		ClientAuthHeader is the HTTP header carrying TLS key-material relay auth.

	const EcnCe EcnCodepoint = 3
		EcnCe is CE (congestion experienced).

	const EcnEct0 EcnCodepoint = 2
		EcnEct0 is ECT(0).

	const EcnEct1 EcnCodepoint = 1
		EcnEct1 is ECT(1).

	const FrameClientAuth FrameType = 1
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FrameClientToRelayDatagram FrameType = 4
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FrameClientToRelayDatagramBat FrameType = 5
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FrameEndpointGone FrameType = 8
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FrameHealth FrameType = 11
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FramePing FrameType = 9
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FramePong FrameType = 10
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FrameRelayToClientDatagram FrameType = 6
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FrameRelayToClientDatagramBat FrameType = 7
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FrameRestarting FrameType = 12
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FrameServerChallenge FrameType = 0
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FrameServerConfirmsAuth FrameType = 2
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FrameServerDeniesAuth FrameType = 3
		Frame types, matching iroh-relay/src/protos/common.rs.

	const FrameStatus FrameType = 13
		Frame types, matching iroh-relay/src/protos/common.rs.

	const MaxPacketSize = 65536
		MaxPacketSize is the maximum size of a packet sent over the relay, counting
		only the visible data bytes, not the on-wire framing overhead.

	const PerClientSendQueueDepth = 512
		PerClientSendQueueDepth is the number of packets buffered for sending per
		client by a relay server.

	const ProtocolV1 ProtocolVersion = 1
		Relay protocol versions.

	const ProtocolV2 ProtocolVersion = 2
		Relay protocol versions.

	const StatusHealthy Status = 0
		StatusHealthy reports the connection recovered from previous problems.

	const StatusRateLimited Status = 2
		StatusRateLimited reports the relay is throttling this client's
		outbound traffic.

	const StatusSameEndpointIDConnected Status = 1
		StatusSameEndpointIDConnected reports another endpoint connected with the
		same id; no more messages will be received.

The pages are generated with Golds v0.8.4. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.