cloudevents

README

Go SDK for CloudEvents

NOTE: This SDK is still considered work in progress, things might (and will) break with every update.

Working with CloudEvents

Package cloudevents provides primitives to work with CloudEvents specification: https://github.com/cloudevents/spec.

Import this repo to get the cloudevents package:

import "github.com/cloudevents/sdk-go"

Receiving a cloudevents.Event via the HTTP Transport:

func Receive(event cloudevents.Event) {
	// do something with event.Context and event.Data (via event.DataAs(foo)
}

func main() {
	c, err := cloudevents.NewDefaultClient()
	if err != nil {
		log.Fatalf("failed to create client, %v", err)
	}
	log.Fatal(c.StartReceiver(context.Background(), Receive));
}

Creating a minimal CloudEvent in version 0.2:

event := cloudevents.NewEvent()
event.SetID("ABC-123")
event.SetType("com.cloudevents.readme.sent")
event.SetSource("http://localhost:8080/")
event.SetData(data)

Sending a cloudevents.Event via the HTTP Transport with Binary v0.2 encoding:

t, err := cloudevents.NewHTTPTransport(
	cloudevents.WithTarget("http://localhost:8080/"),
	cloudevents.WithEncoding(cloudevents.HTTPBinaryV02),
)
if err != nil {
	panic("failed to create transport, " + err.Error())
}

c, err := cloudevents.NewClient(t)
if err != nil {
	panic("unable to create cloudevent client: " + err.Error())
}
if err := c.Send(ctx, event); err != nil {
	panic("failed to send cloudevent: " + err.Error())
}

Or, the transport can be set to produce CloudEvents using the selected encoding but not change the provided event version, here the client is set to output structured encoding:

t, err := cloudevents.NewHTTPTransport(
	cloudevents.WithTarget("http://localhost:8080/"),
	cloudevents.WithStructuredEncoding(),
)

If you are using advanced transport features or have implemented your own transport integration, provide it to a client so your integration does not change:

t, err := cloudevents.NewHTTPTransport(
	cloudevents.WithPort(8181),
	cloudevents.WithPath("/events/")
)
// or a custom transport: t := &custom.MyTransport{Cool:opts}

c, err := cloudevents.NewClient(t, opts...)

Checkout the sample sender and receiver applications for working demo.

Documentation

Index

• Constants
• Variables
• type Client
• type ClientOption
• type ConvertFn
• type Event
• type EventContext
• type EventContextV01
• type EventContextV02
• type EventContextV03
• type EventResponse
• type HTTPEncoding
• type HTTPOption
• type HTTPTransport
• type HTTPTransportContext
• type HTTPTransportResponseContext
• type Timestamp
• type URLRef

Constants

const (
	ApplicationXML                  = cloudevents.ApplicationXML
	ApplicationJSON                 = cloudevents.ApplicationJSON
	ApplicationCloudEventsJSON      = cloudevents.ApplicationCloudEventsJSON
	ApplicationCloudEventsBatchJSON = cloudevents.ApplicationCloudEventsBatchJSON
	Base64                          = cloudevents.Base64

	VersionV01 = cloudevents.CloudEventsVersionV01
	VersionV02 = cloudevents.CloudEventsVersionV02
	VersionV03 = cloudevents.CloudEventsVersionV03

	HTTPBinaryV01     = http.BinaryV01
	HTTPStructuredV01 = http.StructuredV01
	HTTPBinaryV02     = http.BinaryV02
	HTTPStructuredV02 = http.StructuredV02
	HTTPBinaryV03     = http.BinaryV03
	HTTPStructuredV03 = http.StructuredV03
	HTTPBatchedV03    = http.BatchedV03

	Binary     = http.Binary
	Structured = http.Structured
)

Variables

var (
	StringOfApplicationJSON                 = cloudevents.StringOfApplicationJSON
	StringOfApplicationXML                  = cloudevents.StringOfApplicationXML
	StringOfApplicationCloudEventsJSON      = cloudevents.StringOfApplicationCloudEventsJSON
	StringOfApplicationCloudEventsBatchJSON = cloudevents.StringOfApplicationCloudEventsBatchJSON
	StringOfBase64                          = cloudevents.StringOfBase64

	NewClient        = client.New
	NewDefaultClient = client.NewDefault

	WithEventDefaulter = client.WithEventDefaulter
	WithUUIDs          = client.WithUUIDs
	WithTimeNow        = client.WithTimeNow
	WithConverterFn    = client.WithConverterFn

	NewEvent = cloudevents.New

	EnableTracing = observability.EnableTracing

	ContextWithTarget   = context.WithTarget
	TargetFromContext   = context.TargetFrom
	ContextWithEncoding = context.WithEncoding
	EncodingFromContext = context.EncodingFrom

	ParseTimestamp = types.ParseTimestamp
	ParseURLRef    = types.ParseURLRef

	NewHTTPTransport = http.New

	WithTarget               = http.WithTarget
	WithMethod               = http.WithMethod
	WitHHeader               = http.WithHeader
	WithShutdownTimeout      = http.WithShutdownTimeout
	WithEncoding             = http.WithEncoding
	WithContextBasedEncoding = http.WithContextBasedEncoding
	WithBinaryEncoding       = http.WithBinaryEncoding
	WithStructuredEncoding   = http.WithStructuredEncoding
	WithPort                 = http.WithPort
	WithPath                 = http.WithPath
	WithMiddleware           = http.WithMiddleware
	WithLongPollTarget       = http.WithLongPollTarget

	HTTPTransportContextFrom = http.TransportContextFrom
	ContextWithHeader        = http.ContextWithHeader
)

Types

type Client

type Client = client.Client

type ClientOption

type ClientOption client.Option

type ConvertFn

type ConvertFn = client.ConvertFn

type Event

type Event = cloudevents.Event

type EventContext

type EventContext = cloudevents.EventContext

type EventContextV01

type EventContextV01 = cloudevents.EventContextV01

type EventContextV02

type EventContextV02 = cloudevents.EventContextV02

type EventContextV03

type EventContextV03 = cloudevents.EventContextV03

type EventResponse

type EventResponse = cloudevents.EventResponse

type HTTPEncoding

type HTTPEncoding = http.Encoding

type HTTPOption

type HTTPOption http.Option

type HTTPTransport

type HTTPTransport = http.Transport

type HTTPTransportContext

type HTTPTransportContext = http.TransportContext

type HTTPTransportResponseContext

type HTTPTransportResponseContext = http.TransportResponseContext

type Timestamp

type Timestamp = types.Timestamp

type URLRef

type URLRef = types.URLRef