client

Documentation

Overview

Package client holds the recommended entry points for interacting with the CloudEvents Golang SDK. The client wraps a selected transport. The client adds validation and defaulting for sending events, and flexible receiver method registration. For full details, read the `client.Client` documentation.

Index

• Variables
• func DefaultIDToUUIDIfNotSet(ctx context.Context, event cloudevents.Event) cloudevents.Event
• func DefaultTimeToNowIfNotSet(ctx context.Context, event cloudevents.Event) cloudevents.Event
• type Client
  • func New(t transport.Transport, opts ...Option) (Client, error)
  • func NewDefault() (Client, error)
• type ConvertFn
• type EventDefaulter
  • func NewDefaultDataContentTypeIfNotSet(contentType string) EventDefaulter
• type Option
  • func WithConverterFn(fn ConvertFn) Option
  • func WithDataContentType(contentType string) Option
  • func WithEventDefaulter(fn EventDefaulter) Option
  • func WithTimeNow() Option
  • func WithUUIDs() Option
  • func WithoutTracePropagation() Option
• type ReceiveFull

Variables

var (
	// LatencyMs measures the latency in milliseconds for the CloudEvents
	// client methods.
	LatencyMs = stats.Float64("cloudevents.io/sdk-go/client/latency", "The latency in milliseconds for the CloudEvents client methods.", "ms")
)

var (
	// LatencyView is an OpenCensus view that shows client method latency.
	LatencyView = &view.View{
		Name:        "client/latency",
		Measure:     LatencyMs,
		Description: "The distribution of latency inside of client for CloudEvents.",
		Aggregation: view.Distribution(0, .01, .1, 1, 10, 100, 1000, 10000),
		TagKeys:     observability.LatencyTags(),
	}
)

Functions

func DefaultIDToUUIDIfNotSet

func DefaultIDToUUIDIfNotSet(ctx context.Context, event cloudevents.Event) cloudevents.Event

DefaultIDToUUIDIfNotSet will inspect the provided event and assign a UUID to context.ID if it is found to be empty.

func DefaultTimeToNowIfNotSet

func DefaultTimeToNowIfNotSet(ctx context.Context, event cloudevents.Event) cloudevents.Event

DefaultTimeToNowIfNotSet will inspect the provided event and assign a new Timestamp to context.Time if it is found to be nil or zero.

Types

type Client

type Client interface {
	// Send will transmit the given event over the client's configured transport.
	Send(ctx context.Context, event cloudevents.Event) (context.Context, *cloudevents.Event, error)

	// StartReceiver will register the provided function for callback on receipt
	// of a cloudevent. It will also start the underlying transport as it has
	// been configured.
	// This call is blocking.
	// Valid fn signatures are:
	// * func()
	// * func() error
	// * func(context.Context)
	// * func(context.Context) error
	// * func(cloudevents.Event)
	// * func(cloudevents.Event) error
	// * func(context.Context, cloudevents.Event)
	// * func(context.Context, cloudevents.Event) error
	// * func(cloudevents.Event, *cloudevents.EventResponse)
	// * func(cloudevents.Event, *cloudevents.EventResponse) error
	// * func(context.Context, cloudevents.Event, *cloudevents.EventResponse)
	// * func(context.Context, cloudevents.Event, *cloudevents.EventResponse) error
	// Note: if fn returns an error, it is treated as a critical and
	// EventResponse will not be processed.
	StartReceiver(ctx context.Context, fn interface{}) error
}

Client interface defines the runtime contract the CloudEvents client supports.

func New

func New(t transport.Transport, opts ...Option) (Client, error)

New produces a new client with the provided transport object and applied client options.

func NewDefault

func NewDefault() (Client, error)

NewDefault provides the good defaults for the common case using an HTTP Transport client. The http transport has had WithBinaryEncoding http transport option applied to it. The client will always send Binary encoding but will inspect the outbound event context and match the version. The WithTimeNow, WithUUIDs and WithDataContentType("application/json") client options are also applied to the client, all outbound events will have a time and id set if not already present.

type ConvertFn

type ConvertFn func(context.Context, transport.Message, error) (*cloudevents.Event, error)

ConvertFn defines the signature the client expects to enable conversion delegation.

type EventDefaulter

type EventDefaulter func(ctx context.Context, event cloudevents.Event) cloudevents.Event

EventDefaulter is the function signature for extensions that are able to perform event defaulting.

func NewDefaultDataContentTypeIfNotSet

func NewDefaultDataContentTypeIfNotSet(contentType string) EventDefaulter

NewDefaultDataContentTypeIfNotSet returns a defaulter that will inspect the provided event and set the provided content type if content type is found to be empty.

type Option

type Option func(*ceClient) error

Option is the function signature required to be considered an client.Option.

func WithConverterFn

func WithConverterFn(fn ConvertFn) Option

WithConverterFn defines the function the transport will use to delegate conversion of non-decodable messages.

func WithDataContentType

func WithDataContentType(contentType string) Option

WithDataContentType adds the resulting defaulter from NewDefaultDataContentTypeIfNotSet event defaulter to the end of the defaulter chain.

func WithEventDefaulter

func WithEventDefaulter(fn EventDefaulter) Option

WithEventDefaulter adds an event defaulter to the end of the defaulter chain.

func WithTimeNow

func WithTimeNow() Option

WithTimeNow adds DefaultTimeToNowIfNotSet event defaulter to the end of the defaulter chain.

func WithUUIDs

func WithUUIDs() Option

WithUUIDs adds DefaultIDToUUIDIfNotSet event defaulter to the end of the defaulter chain.

func WithoutTracePropagation

func WithoutTracePropagation() Option

WithoutTracePropagation disables automatic trace propagation via the distributed tracing extension.

type ReceiveFull

type ReceiveFull func(context.Context, cloudevents.Event, *cloudevents.EventResponse) error

Receive is the signature of a fn to be invoked for incoming cloudevents. If fn returns an error, EventResponse will not be considered by the client or or transport. This is just an FYI: