/sdk-go

Go SDK for CloudEvents (https://github.com/cloudevents/spec)

Primary LanguageGoApache License 2.0Apache-2.0

Go SDK for CloudEvents

go-doc

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.

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() {
	ctx := context.Background()
	_, err := client.StartHTTPReceiver(ctx, Receive)
	if err != nil {
		log.Fatal(err)
	}
	<-ctx.Done()
}

Creating a minimal CloudEvent in version 0.2:

event := cloudevents.Event{
    Context: cloudevents.EventContextV02{
        ID:     uuid.New().String(),
        Type:   "com.cloudevents.readme.sent",
        Source: types.ParseURLRef("http://localhost:8080/"),
    }.AsV02(),
}

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

c, err := client.NewHTTPClient(
	client.WithTarget("http://localhost:8080/"),
	client.WithHTTPEncoding(cloudeventshttp.BinaryV02),
)
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 client 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:

c, err := client.NewHTTPClient(
	client.WithTarget("http://localhost:8080/"),
	client.WithHTTPStructuredEncoding(),
)

Checkout the sample sender and receiver applications for working demo.

TODO list

General

  • Add details to what the samples are showing.
  • Add a sample to show how to use the transport without the client.
  • increase ./pkg code coverage to > 90%. (70% as of Feb 19, 2019)
  • Most tests are happy path, add sad path tests (edge cases).
  • Use contexts to override internal defaults.
  • Fill in Event.Context defaults with values (like ID and time) if nil/empty.
  • Might be nice to have the client have a Receive hook.
  • Might be an issue with zero body length requests.
  • Need a change to the client to make making events easier
  • Implement String() for event context

Webhook

  • Implement Auth in webhook
  • Implement Callback in webhook
  • Implement Allowed Origin
  • Implement Allowed Rate

JSON

  • Support json value as body.

HTTP

  • Support overrides for method.
  • Merge headers from context on send.

NATS

  • Plumb in auth for the nats server.
  • v0.2 and v0.3 are very similar. Combine decode logic?

For v0.3

  • Support batch json

Existing Go for CloudEvents

Existing projects that added support for CloudEvents in Go are listed below. It's our goal to identify existing patterns of using CloudEvents in Go-based project and design the SDK to support these patterns (where it makes sense).