cloudevents

Go SDK for CloudEvents

Status

This SDK is still considered work in progress.

With v1.1.0:

Master will now be the base of the effort for v2.0.0 of this SDK and will contain breaking changes or missing libraries.

Future work on v1.X.Y releases will branch off of release-1.y.z. To add a bugfix to a v1.X.Y release, please make a PR to that branch and we can do releases as needed on the v1 SDK. No date for EOL on v1 support yet, that will be determined by the progress on v2.

The CloudEvents golang team is working hard to bring you v2.0.0 of the SDK.

With v1.0.0:

The API that exists under pkg/cloudevents will follow semver rules. This applies to the root ./alias.go file as well.

Even though pkg/cloudevents is v1.0.0, there could still be minor bugs and performance issues. We will continue to track and fix these issues as they come up. Please file a pull request or issue if you experience problems.

The API that exists under pkg/bindings is a new API that will become SDK v2.x, and will replace pkg/cloudevents. This area is still under heavy development and will not be following the same semver rules as pkg/cloudevents. If a release is required to ship changes to pkg/bindings, a bug fix release will be issued (x.y.z+1).

We will target ~2 months of development to release v2 of this SDK with an end date of March 27, 2020. You can read more about the plan for SDK v2 in the SDK v2 planning doc.

This SDK current supports the following versions of CloudEvents:

• v1.0
• v0.3
• v0.2
• v0.1

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 1.0:

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 v1.0 encoding:

t, err := cloudevents.NewHTTPTransport(
	cloudevents.WithTarget("http://localhost:8080/"),
	cloudevents.WithEncoding(cloudevents.HTTPBinaryV1),
)
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.

Community

• There are bi-weekly calls immediately following the Serverless/CloudEvents call at 9am PT (US Pacific). Which means they will typically start at 10am PT, but if the other call ends early then the SDK call will start early as well. See the CloudEvents meeting minutes to determine which week will have the call.
• Slack: #cloudeventssdk channel under CNCF's Slack workspace.
• Contact for additional information: Scott Nichols (@Scott Nichols on slack).