README.md

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.