Documentation
¶
Overview ¶
Package envelope is the seam between an event and the message that carries it: the Event every service handles, and the Format interface each wire format implements to write it and read it back.
The model ¶
An Event is CloudEvents' attribute set: id, source, specversion and type, four optional attributes, any number of extensions, and a payload. Validate is the one description of a well-formed event, and every format runs it on the way out and on the way in, so every format refuses the same events.
Formats ¶
A Format renders an event as a Wire, the content type, headers and body a transport carries, and reads one back. Each format is its own module beside this one, needing nothing else:
- gitlab.com/phpboyscout/go/envelope-cloudevents: CloudEvents binary and structured mode, the default;
- gitlab.com/phpboyscout/go/envelope-masstransit and gitlab.com/phpboyscout/go/envelope-nservicebus: the envelopes those .NET frameworks write.
Read decodes a message with whichever of several formats claims it, and refuses one that two formats claim, so a reader can accept several formats while writers move from one to another. A format returns what arrived but is not part of the event as Foreign, and nothing here ever sends it.
Strictness ¶
A format validates and refuses, and hands back what it managed to read alongside the error. specversion tells a reader how to interpret every other attribute, so parsing leniently past an unrecognised one is guessing rather than tolerance. The partial event is returned because a subscriber that drops a message needs something traceable to log.
The design is go/messaging's spec 0014; D12 is why the model and the seam live here, apart from any one format.
Index ¶
Examples ¶
Constants ¶
const SpecVersion = "1.0"
SpecVersion is the only CloudEvents version this module implements.
Variables ¶
var ( // ErrMissingAttribute is returned when one of the four required attributes // — id, source, specversion, type — is absent or empty. ErrMissingAttribute = errors.NewSentinel("envelope.missing_attribute", "envelope: a required attribute is missing") // ErrUnsupportedSpecVersion is returned for a specversion this module does // not implement. // // This is the refusal the rest of the strictness follows from. specversion // tells a reader how to interpret every other attribute, so continuing past // an unrecognised one is guessing at the shape of what is held rather than // being lenient about it. ErrUnsupportedSpecVersion = errors.NewSentinel("envelope.unsupported_specversion", "envelope: unsupported specversion") // ErrInvalidTime is returned when the time attribute is present and is not // an RFC 3339 timestamp. ErrInvalidTime = errors.NewSentinel("envelope.invalid_time", "envelope: time is not an RFC 3339 timestamp") // ErrDataSchemaNotAbsolute is returned when dataschema is present and is // not an absolute URI. // // The CloudEvents specification types dataschema as URI rather than // URI-reference, so unlike source it must be absolute: there is no base to // resolve a relative one against, and a consumer that received one could // not tell which schema was meant. ErrDataSchemaNotAbsolute = errors.NewSentinel("envelope.dataschema_not_absolute", "envelope: dataschema must be an absolute URI") // ErrInvalidExtensionName is returned when an extension attribute name // breaks the specification's naming MUSTs. ErrInvalidExtensionName = errors.NewSentinel("envelope.invalid_extension_name", "envelope: extension names must be one or more lower-case ASCII letters or digits, and not \"data\"") // ErrInvalidEncoding is returned when an attribute value is not valid // UTF-8, or a format's own encoding of one does not decode. // // A value decoded leniently would be a different string than the sender // wrote, silently. ErrInvalidEncoding = errors.NewSentinel("envelope.invalid_encoding", "envelope: an attribute value is not validly encoded") // ErrControlCharacter is returned when an attribute value contains a // character the specification's String type disallows. // // U+0000-U+001F and U+007F-U+009F. A format's encoding might carry them, // which is precisely why they are refused instead: net/http rewrites a // newline in a header rather than refusing it, so without this check a // receiver gets a different attribute value than the sender set, with no // error anywhere. ErrControlCharacter = errors.NewSentinel("envelope.control_character", "envelope: attribute value contains a control character") // ErrReservedExtensionName is returned when an extension is named after a // specification attribute. // // Without this, Extensions["id"] overwrites the id on the way out in any // format that writes attributes and extensions side by side, and the event // travels with a hijacked identity and no error — a round trip that is green // and wrong. ErrReservedExtensionName = errors.NewSentinel("envelope.reserved_extension_name", "envelope: extension name collides with a specification attribute") // ErrUnrecognised is returned by [Read] when no format claims a message. // It is not malformed: it is not in any format the reader was given. ErrUnrecognised = errors.NewSentinel("envelope.unrecognised", "envelope: no format recognises the message") // ErrAmbiguous is returned by [Read] when more than one format claims a // message. Decoding it with either could produce the wrong event, so it // is decoded with neither. ErrAmbiguous = errors.NewSentinel("envelope.ambiguous", "envelope: more than one format recognises the message") // ErrUnrepresentable is returned by a format asked to encode an event that // is valid CloudEvents but that its envelope cannot carry, such as an ID // that is not a UUID in an envelope that requires one. ErrUnrepresentable = errors.NewSentinel("envelope.unrepresentable", "envelope: the format cannot represent this event") )
Refusals. Every one of them is a case Validate, Read or a format declines to guess at, and each is a sentinel so a consumer can count the kinds of bad event it is being sent rather than counting "parse failed".
Functions ¶
func Read ¶
Read decodes w with the one format that recognises it, and returns that format so a reply can be written in it.
Every format is asked, rather than the first that claims the message, because no order is safe: a binary event whose payload is itself a structured CloudEvent is misread when structured is asked first, and a structured message with a stray ce-specversion header is misread when binary is. A message nobody claims is ErrUnrecognised; one two formats claim is ErrAmbiguous. Neither decodes, because either answer could be the wrong event.
func ValidExtensionName ¶
ValidExtensionName reports whether a name may be used as an extension attribute.
It enforces the specification's naming MUSTs — one or more characters, each a lower-case ASCII letter or a digit, and not the name "data" which some event formats reserve — and deliberately not its SHOULDs. Starting with a letter and staying under twenty characters are recommendations, and refusing a twenty-one character name would reject events the rest of the world accepts, which is the interoperability failure that implementing a standard rather than inventing one exists to avoid.
It also refuses the eight specification attribute names. The specification calls extensions "additional context attributes with distinct names", and without the check an extension named "id" would overwrite the id on the way out — producing an event with a hijacked identity, no error, and a round trip that agrees with itself.
The character constraint is this narrow because some protocols treat metadata as case-sensitive and others do not, and one event may cross several of them in a single delivery.
func Validate ¶
Validate reports whether e is a well-formed event. It is the one description of well-formed, which every format runs on the way out as well as on the way in, so that every format refuses the same events: a producer that would emit something no consumer of ours would accept learns that in its own process, rather than in somebody else's subscriber.
It does not fill in an empty SpecVersion.
Example ¶
ExampleValidate asks whether an event is well formed, which is the question every format asks before it writes one.
package main
import (
"fmt"
"gitlab.com/phpboyscout/go/errors"
"gitlab.com/phpboyscout/go/envelope"
)
func main() {
e := envelope.Event{
ID: "01JQ8Z3F7K2M4N6P8R0T2V4W6X",
Source: "/phpbotscout/ingest",
SpecVersion: envelope.SpecVersion,
Type: "uk.phpboyscout.orders.created",
Extensions: map[string]string{"id": "hijacked"},
}
err := envelope.Validate(e)
fmt.Println("refused:", errors.Is(err, envelope.ErrReservedExtensionName))
delete(e.Extensions, "id")
fmt.Println("now valid:", envelope.Validate(e) == nil)
}
Output: refused: true now valid: true
Types ¶
type Event ¶
type Event struct {
// ID, with Source, uniquely identifies the event. A producer must not reuse
// a pair for two different events.
ID string
// Source identifies the context the event happened in. A URI-reference, so
// unlike DataSchema it may be relative.
Source string
// SpecVersion is the version of the CloudEvents specification the event
// uses. A format fills it in when it is empty; [Validate] refuses any
// value but [SpecVersion].
SpecVersion string
// Type describes the kind of occurrence, and is what consumers usually
// filter on.
Type string
// DataContentType is the media type of Data.
DataContentType string
// DataSchema identifies the schema Data conforms to. In this estate it is a
// URN — see [gitlab.com/phpboyscout/go/urn] — and it must be an
// absolute URI whatever form it takes.
DataSchema string
// Subject names the thing the event is about, within Source.
Subject string
// Time is when the occurrence happened. The zero value means absent.
Time time.Time
// Extensions are attributes outside the specification's set, keyed by
// name.
//
// Every one of them must be safe to log: opaque identifiers only, never a
// display name, a channel name or anything a person chose. Attributes ride
// in headers, headers are logged by default, and nothing routes them
// through a redaction pass the way a payload field is routed. A payload has
// a schema and a review; an attribute has neither, so the bar for adding
// one is higher rather than lower.
Extensions map[string]string
// Data is the payload, carried as the message body and never interpreted
// here.
Data []byte
}
Event is the message every format writes and reads: CloudEvents' attribute set, eight attributes and any number of extensions, and a payload this module never looks inside.
It is a plain struct rather than an interface with accessors because it holds eight fields and a map, and the SDK's equivalent brings a second structured logger, a JSON library and four more indirect dependencies into the graph of every service that sends a message.
type Foreign ¶
type Foreign struct {
Headers map[string][]string
// Conflicts names the keys an envelope set that the transport also carried
// with another value. The envelope's value is in the event; the transport's
// is in Headers. Only envelopes with fields headers can shadow produce one.
Conflicts []string
}
Foreign is what arrived with an event but is not part of it: a broker's own headers, or a foreign envelope's fields with no CloudEvents equivalent. It is for reading, and nothing in this module ever sends it.
type Format ¶
type Format interface {
// Encode renders e. It validates first, so a format never emits an event
// [Validate] refuses.
Encode(e Event) (Wire, error)
// Recognises reports, without decoding, whether w is in this format. It is
// a claim, not a promise: a claimed message that fails to decode is
// malformed rather than somebody else's.
Recognises(w Wire) bool
// Decode reads w. It returns what it managed to read alongside any error,
// so a refused message can still be logged by its ID, and it returns
// whatever arrived that is not part of the event as [Foreign].
Decode(w Wire) (Event, Foreign, error)
}
Format renders an event for a transport and reads one back.
Each format is its own module, needing nothing but this one: gitlab.com/phpboyscout/go/envelope-cloudevents carries CloudEvents binary and structured mode.
type Wire ¶
type Wire struct {
// ContentType is the transport's own content type, which AMQP and RabbitMQ
// carry as a native property. On a transport without one the adapter writes
// it as the content-type header, and a format reads it from either place.
ContentType string
// Headers are everything else the transport carries beside the body.
Headers map[string][]string
Body []byte
}
Wire is a message as a transport carries it. Only adapters build one.