envelope¶

gitlab.com/phpboyscout/go/envelope is the event every service handles, and the seam each wire format implements to write it and read it back.

type Format interface {
    Encode(Event) (Wire, error)
    Recognises(w Wire) bool
    Decode(Wire) (Event, Foreign, error)
}

func Read(w Wire, formats ...Format) (Event, Foreign, Format, error)
func Validate(e Event) error

An Event is CloudEvents' attribute set: id, source, specversion and type, four optional attributes, extensions, and a payload. A Format turns one into a Wire, the content type, headers and body a transport carries, and back. Each format is a module of its own beside this one:

Read asks every format it is given and decodes with the one that claims the message, so a reader can take several formats while writers move between them. A message no format claims, or that two claim, is refused rather than guessed at.

• Reference: the API, and every error it returns.
• Why a format refuses: strictness, and the partial event handed back with every refusal.
• API reference on pkg.go.dev.

CloudEvents¶

• Tutorial: Getting started, an event encoded, sent over NATS and read back.
• How-to: send over NATS, send over HTTP, handle a refused event, add an extension attribute, read more than one format.
• Reference: the wire format, and the CloudEvents sentinels in errors.
• Explanation: why the specification and not the SDK, and what these modules do not do.

URN identifiers such as urn:phpboyscout:schema:orders.created:3 are documented with go/urn.

This module, with its formats, replaces gitlab.com/phpboyscout/go/cloudevents. The design is go/messaging's spec 0014.