Developer SDK

Go examples

Install the SDK · View source on GitHub ↗

messages/subprotocol/notes.go

go
// Package subprotocol is the compiled form of the Go snippets in
// SUBPROTOCOLS.md: an application protocol of protobuf messages on its own
// subprotocol id. Every message is one Envelope (notes.proto) holding a Note
// or the Ack that confirms it. device.go sends and receives it through an SDK
// Device; client.go registers it on a connect client.
package subprotocol

//go:generate protoc --go_out=. --go_opt=paths=source_relative notes.proto

import (
	"crypto/rand"
	"encoding/binary"
	"errors"
	"fmt"
	"unicode/utf8"

	"google.golang.org/protobuf/proto"
)

// The application subprotocol id of this protocol. Ids below 1024 belong to
// the network, and the URMS text example uses 4096.
const Id = 4097

// The most UTF-8 bytes in one note's text.
const MaxTextBytes = 4096

// The largest envelope either side sends or parses: a note of MaxTextBytes
// plus room for the envelope, the id and fields that a later version adds.
// The sender checks it before sending and the receiver before it copies or
// parses.
const MaxMessageBytes = 4608

var (
	ErrTooLarge    = errors.New("envelope exceeds MaxMessageBytes")
	ErrNoKind      = errors.New("envelope has no kind this version knows")
	ErrZeroId      = errors.New("message id 0 is invalid")
	ErrTextTooLong = errors.New("note text exceeds MaxTextBytes")
	ErrTextUtf8    = errors.New("note text is not valid UTF-8")
)

// A note to send. messageId is nonzero; see NewMessageId.
func NewNote(messageId uint64, text string) *Envelope {
	return &Envelope{Kind: &Envelope_Note{Note: &Note{MessageId: messageId, Text: text}}}
}

// The acknowledgement of the note with messageId.
func NewAck(messageId uint64) *Envelope {
	return &Envelope{Kind: &Envelope_Ack{Ack: &Ack{MessageId: messageId}}}
}

// A random nonzero message id for a new note.
func NewMessageId() (uint64, error) {
	var b [8]byte
	for {
		if _, err := rand.Read(b[:]); err != nil {
			return 0, err
		}
		if id := binary.BigEndian.Uint64(b[:]); id != 0 {
			return id, nil
		}
	}
}

// Checks the rules the wire format cannot express: exactly one known kind, a
// nonzero message id, and note text within MaxTextBytes and valid UTF-8.
func Validate(envelope *Envelope) error {
	switch {
	case envelope.GetNote() != nil:
		note := envelope.GetNote()
		if note.GetMessageId() == 0 {
			return ErrZeroId
		}
		if MaxTextBytes < len(note.GetText()) {
			return ErrTextTooLong
		}
		if !utf8.ValidString(note.GetText()) {
			return ErrTextUtf8
		}
		return nil
	case envelope.GetAck() != nil:
		if envelope.GetAck().GetMessageId() == 0 {
			return ErrZeroId
		}
		return nil
	default:
		// no kind, or a kind added by a later version (its field is unknown here)
		return ErrNoKind
	}
}

// Validates and encodes one envelope for sending.
func Marshal(envelope *Envelope) ([]byte, error) {
	if err := Validate(envelope); err != nil {
		return nil, err
	}
	messageBytes, err := proto.Marshal(envelope)
	if err != nil {
		return nil, err
	}
	if MaxMessageBytes < len(messageBytes) {
		return nil, ErrTooLarge
	}
	return messageBytes, nil
}

// Decodes and validates one received envelope. It refuses more than
// MaxMessageBytes before decoding, bytes that are not an Envelope (including
// invalid UTF-8 in a string, which proto.Unmarshal rejects) and anything
// Validate refuses. Unknown fields are kept and ignored, so a later version
// can add fields.
func Parse(messageBytes []byte) (*Envelope, error) {
	if MaxMessageBytes < len(messageBytes) {
		return nil, ErrTooLarge
	}
	envelope := &Envelope{}
	if err := proto.Unmarshal(messageBytes, envelope); err != nil {
		return nil, fmt.Errorf("invalid envelope: %w", err)
	}
	if err := Validate(envelope); err != nil {
		return nil, err
	}
	return envelope, nil
}