cloudevents

package module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 16, 2020 License: Apache-2.0 Imports: 6 Imported by: 461

README

Go SDK for CloudEvents

go-doc Go Report Card CircleCI Releases LICENSE

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).

Documentation

Index

Constants

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

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

	HTTPBinaryV1      = http.BinaryV1
	HTTPStructuredV1  = http.StructuredV1
	HTTPBatchedV1     = http.BatchedV1
	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

View Source
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
	WithDataContentType     = client.WithDataContentType
	WithoutTracePropagation = client.WithoutTracePropagation

	NewEvent = cloudevents.New

	EnableTracing = observability.EnableTracing

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

	ParseTimestamp = types.ParseTimestamp
	ParseURLRef    = types.ParseURLRef
	ParseURIRef    = types.ParseURIRef
	ParseURI       = types.ParseURI

	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
	WithListener             = http.WithListener
	WithHTTPTransport        = http.WithHTTPTransport

	HTTPTransportContextFrom = http.TransportContextFrom
	ContextWithHeader        = http.ContextWithHeader
	SetContextHeaders        = http.SetContextHeaders
)

Functions

This section is empty.

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 EventContextV1 added in v0.10.0

type EventContextV1 = cloudevents.EventContextV1

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

Directories

Path Synopsis
binding
cmd
observability
opencensus Module
opentelemetry Module
pkg
binding
Package binding defines interfaces for protocol bindings.
Package binding defines interfaces for protocol bindings.
binding/format
Package format formats structured events.
Package format formats structured events.
binding/spec
Package spec provides spec-version metadata.
Package spec provides spec-version metadata.
binding/test
Package test contains test data and generic tests for testing bindings.
Package test contains test data and generic tests for testing bindings.
bindings
Package bindings contains packages that implement different protocol bindings.
Package bindings contains packages that implement different protocol bindings.
bindings/amqp
Package amqp implements an AMQP binding.
Package amqp implements an AMQP binding.
bindings/http
Package http implements an HTTP CloudEvents binding.
Package http implements an HTTP CloudEvents binding.
bindings/kafka_sarama
Package kafka implements the Kafka CloudEvents binding.
Package kafka implements the Kafka CloudEvents binding.
cloudevents
Package cloudevents provides primitives to work with CloudEvents specification: https://github.com/cloudevents/spec.
Package cloudevents provides primitives to work with CloudEvents specification: https://github.com/cloudevents/spec.
cloudevents/client
Package client holds the recommended entry points for interacting with the CloudEvents Golang SDK.
Package client holds the recommended entry points for interacting with the CloudEvents Golang SDK.
cloudevents/context
Package context holds the last resort overrides and fyi objects that can be passed to clients and transports added to context.Context objects.
Package context holds the last resort overrides and fyi objects that can be passed to clients and transports added to context.Context objects.
cloudevents/datacodec
Package datacodec holds the data codec registry and adds known encoders and decoders supporting media types such as `application/json` and `application/xml`.
Package datacodec holds the data codec registry and adds known encoders and decoders supporting media types such as `application/json` and `application/xml`.
cloudevents/datacodec/json
Package json holds the encoder/decoder implementation for `application/json`.
Package json holds the encoder/decoder implementation for `application/json`.
cloudevents/datacodec/text
Text codec converts []byte or string to string and vice-versa.
Text codec converts []byte or string to string and vice-versa.
cloudevents/datacodec/xml
Package xml holds the encoder/decoder implementation for `application/xml`.
Package xml holds the encoder/decoder implementation for `application/xml`.
cloudevents/observability
Package observability holds metrics and tracing recording implementations.
Package observability holds metrics and tracing recording implementations.
cloudevents/transport
Package transport defines interfaces to decouple the client package from transport implementations.
Package transport defines interfaces to decouple the client package from transport implementations.
cloudevents/transport/amqp
Package amqp implements the CloudEvent transport implementation using amqp.
Package amqp implements the CloudEvent transport implementation using amqp.
cloudevents/transport/http
Package http implements the CloudEvent transport implementation using HTTP.
Package http implements the CloudEvent transport implementation using HTTP.
cloudevents/transport/nats
Package nats implements the CloudEvent transport implementation using NATS.
Package nats implements the CloudEvent transport implementation using NATS.
cloudevents/transport/pubsub
Package pubsub implements the CloudEvent transport implementation using pubsub.
Package pubsub implements the CloudEvent transport implementation using pubsub.
cloudevents/types
Package types implements the CloudEvents type system.
Package types implements the CloudEvents type system.
protocol
amqp Module
kafka_sarama Module
mqtt_paho Module
nats Module
pubsub Module
stan Module
ws Module
samples
amqp Module
gochan Module
http Module
kafka Module
mqtt Module
nats Module
pubsub Module
stan Module
ws Module
sql module
test
benchmark Module
integration Module
observability Module
tools module
v2
protocol/amqp Module
protocol/nats Module
protocol/stan Module
samples Module
test Module
tools Module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL