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 event.Event) event.Event
• func DefaultTimeToNowIfNotSet(ctx context.Context, event event.Event) event.Event
• func EventTraceAttributes(e event.EventReader) []trace.Attribute
• func TraceSpan(ctx context.Context, e event.Event) (context.Context, *trace.Span)
• type Client
  • func New(obj interface{}, opts ...Option) (Client, error)
  • func NewDefault() (Client, error)
  • func NewObserved(protocol interface{}, opts ...Option) (Client, error)
• type EventDefaulter
  • func NewDefaultDataContentTypeIfNotSet(contentType string) EventDefaulter
• type EventReceiver
  • func NewHTTPReceiveHandler(ctx context.Context, p *thttp.Protocol, fn interface{}) (*EventReceiver, error)
  • func (r *EventReceiver) ServeHTTP(rw http.ResponseWriter, req *http.Request)
• type Invoker
• type Option
  • func WithEventDefaulter(fn EventDefaulter) Option
  • func WithForceBinary() Option
  • func WithForceStructured() Option
  • func WithPollGoroutines(pollGoroutines int) Option
  • func WithTimeNow() Option
  • func WithTracePropagation() Option
  • func WithUUIDs() 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 event.Event) event.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 event.Event) event.Event

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

func EventTraceAttributes

func EventTraceAttributes(e event.EventReader) []trace.Attribute

func TraceSpan

func TraceSpan(ctx context.Context, e event.Event) (context.Context, *trace.Span)

TraceSpan returns context and trace.Span based on event. Caller must call span.End()

Types

type Client

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

	// Request will transmit the given event over the client's configured
	// transport and return any response event.
	Request(ctx context.Context, event event.Event) (*event.Event, protocol.Result)

	// StartReceiver will register the provided function for callback on receipt
	// of a cloudevent. It will also start the underlying protocol as it has
	// been configured.
	// This call is blocking.
	// Valid fn signatures are:
	// * func()
	// * func() error
	// * func(context.Context)
	// * func(context.Context) protocol.Result
	// * func(event.Event)
	// * func(event.Event) protocol.Result
	// * func(context.Context, event.Event)
	// * func(context.Context, event.Event) protocol.Result
	// * func(event.Event) *event.Event
	// * func(event.Event) (*event.Event, protocol.Result)
	// * func(context.Context, event.Event) *event.Event
	// * func(context.Context, event.Event) (*event.Event, protocol.Result)
	StartReceiver(ctx context.Context, fn interface{}) error
}

Client interface defines the runtime contract the CloudEvents client supports.

func New

func New(obj interface{}, 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 Protocol 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, and WithUUIDs client options are also applied to the client, all outbound events will have a time and id set if not already present.

func NewObserved

func NewObserved(protocol interface{}, opts ...Option) (Client, error)

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

type EventDefaulter

type EventDefaulter func(ctx context.Context, event event.Event) event.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 EventReceiver

type EventReceiver struct {
	// contains filtered or unexported fields
}

func NewHTTPReceiveHandler

func NewHTTPReceiveHandler(ctx context.Context, p *thttp.Protocol, fn interface{}) (*EventReceiver, error)

func (*EventReceiver) ServeHTTP

func (r *EventReceiver) ServeHTTP(rw http.ResponseWriter, req *http.Request)

type Invoker

type Invoker interface {
	Invoke(context.Context, binding.Message, protocol.ResponseFn) error
	IsReceiver() bool
	IsResponder() bool
}

type Option

type Option func(interface{}) error

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

func WithEventDefaulter

func WithEventDefaulter(fn EventDefaulter) Option

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

func WithForceBinary

func WithForceBinary() Option

func WithForceStructured

func WithForceStructured() Option

func WithPollGoroutines

func WithPollGoroutines(pollGoroutines int) Option

WithPollGoroutines configures how much goroutines should be used to poll the Receiver/Responder/Protocol implementations. Default value is GOMAXPROCS

func WithTimeNow

func WithTimeNow() Option

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

func WithTracePropagation

func WithTracePropagation() Option

WithTracePropagation enables trace propagation via the distributed tracing extension.

func WithUUIDs

func WithUUIDs() Option

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

type ReceiveFull

type ReceiveFull func(context.Context, event.Event) protocol.Result

ReceiveFull is the signature of a fn to be invoked for incoming cloudevents.