# README

Go SDK for CloudEvents

Status

This SDK is still considered work in progress.

For v1 of the SDK, see CloudEvents Go SDK v1.

v2.0.0-preview2:

In preview2 we are focusing on the new Client interface:

type Client interface {
	Send(ctx context.Context, event event.Event) error
	Request(ctx context.Context, event event.Event) (*event.Event, error)
	StartReceiver(ctx context.Context, fn interface{}) error
}

Where a full fn looks like func(context.Context, event.Event) (*event.Event, transport.Result)

For protocols that do not support responses, StartReceiver will throw an error when attempting to set a receiver fn with that capability.

For protocols that do not support responses from send (Requester interface), Client.Request will throw an error.

v2.0.0-preview1:

In preview1 we are focusing on the new interfaces found in pkg/transport (will be renamed to protocol):

Sender, Send an event.
Requester, Send an event and expect a response.
Receiver, Receive an event.
Responder, Receive an event and respond.

Working with CloudEvents

Note: Supported CloudEvents specification: [0.3, 1.0].

Import this repo to get the cloudevents package:

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

To marshal a CloudEvent into JSON, use event.Event directly:

event := cloudevents.NewEvent()
event.SetSource("example/uri")
event.SetType("example.type")
event.SetData(cloudevents.ApplicationJSON, map[string]string{"hello": "world"})

bytes, err := json.Marshal(event)

To unmarshal JSON back into a CloudEvent:

event :=  cloudevents.NewEvent()

err := json.Marshal(bytes, &event)

The aim of CloudEvents Specification is to define how to "bind" an event to a particular protocol and back. This SDK wraps the protocol binding implementations in a client to expose a simple event.Event based API.

An example of sending a cloudevents.Event via HTTP:

func main() {
	// The default client is HTTP.
	c, err := cloudevents.NewDefaultClient()
	if err != nil {
		log.Fatalf("failed to create client, %v", err)
	}

	// Create an Event.
	event :=  cloudevents.NewEvent()
	event.SetSource("example/uri")
	event.SetType("example.type")
	event.SetData(cloudevents.ApplicationJSON, map[string]string{"hello": "world"})

	// Set a target.
	ctx := cloudevents.ContextWithTarget(context.Background(), "http://localhost:8080/")

	// Send that Event.
	if err := c.Send(ctx, event); err != nil {
		log.Fatalf("failed to send, %v", err)}
	}
}

An example of receiving a cloudevents.Event via HTTP:

func receive(event cloudevents.Event) {
	// do something with event.
    fmt.Printf("%s", event)
}

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

Checkout the sample sender and receiver applications for working demo.

It can be more performant to not parse an event all the way to the event.Event. For this the package binding provides primitives convert event.Event to binding.Message, and then bind an them onto a protocol implementation.

For example, to convert an event.Event to a binding.Message and then create an http.Request:

msg := cloudevents.ToMessage(&event)

req, _ = nethttp.NewRequest("POST", "http://localhost", nil)
err = http.WriteRequest(context.TODO(), msg, req, nil)
// ...check error.

// Then use req:
resp, err := http.DefaultClient.Do(req)