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
• type Client
  • func New(obj interface{}, opts ...Option) (Client, error)
  • func NewHTTP(opts ...http.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 ObservabilityService
• type Option
  • func WithAckMalformedEvent() Option
  • func WithBlockingCallback() Option
  • func WithEventDefaulter(fn EventDefaulter) Option
  • func WithForceBinary() Option
  • func WithForceStructured() Option
  • func WithInboundContextDecorator(dec func(context.Context, binding.Message) context.Context) Option
  • func WithObservabilityService(service ObservabilityService) Option
  • func WithPollGoroutines(pollGoroutines int) Option
  • func WithTimeNow() Option
  • func WithTracePropagation() Option
  • func WithUUIDs() Option
• type ReceiveFull

Variables

var NewDefault = NewHTTP

NewDefault has been replaced by NewHTTP Deprecated. To get the same as NewDefault provided, please use NewHTTP with the observability service passed as an option, or client.NewClientHTTP from package github.com/cloudevents/sdk-go/observability/opencensus/v2/client

var NewObserved = New

NewObserved produces a new client with the provided transport object and applied client options. Deprecated: This now has the same behaviour of New, and will be removed in future releases. As New, you must provide the observability service to use.

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.

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 NewHTTP

func NewHTTP(opts ...http.Option) (Client, error)

NewHTTP provides the good defaults for the common case using an HTTP Protocol client. 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.

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 ObservabilityService

type ObservabilityService interface {
	// InboundContextDecorators is a method that returns the InboundContextDecorators that must be mounted in the Client to properly propagate some tracing informations.
	InboundContextDecorators() []func(context.Context, binding.Message) context.Context

	// RecordReceivedMalformedEvent is invoked when an event was received but it's malformed or invalid.
	RecordReceivedMalformedEvent(ctx context.Context, err error)
	// RecordCallingInvoker is invoked before the user function is invoked.
	// The returned callback will be invoked after the user finishes to process the event with the eventual processing error
	// The error provided to the callback could be both a processing error, or a result
	RecordCallingInvoker(ctx context.Context, event *event.Event) (context.Context, func(errOrResult error))
	// RecordSendingEvent is invoked before the event is sent.
	// The returned callback will be invoked when the response is received
	// The error provided to the callback could be both a processing error, or a result
	RecordSendingEvent(ctx context.Context, event event.Event) (context.Context, func(errOrResult error))

	// RecordRequestEvent is invoked before the event is requested.
	// The returned callback will be invoked when the response is received
	RecordRequestEvent(ctx context.Context, event event.Event) (context.Context, func(errOrResult error, event *event.Event))
}

ObservabilityService is an interface users can implement to record metrics, create tracing spans, and plug other observability tools in the Client

type Option

type Option func(interface{}) error

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

func WithAckMalformedEvent

func WithAckMalformedEvent() Option

WithAckMalformedevents causes malformed events received within StartReceiver to be acknowledged rather than being permanently not-acknowledged. This can be useful when a protocol does not provide a responder implementation and would otherwise cause the receiver to be partially or fully stuck.

func WithBlockingCallback

func WithBlockingCallback() Option

WithBlockingCallback makes the callback passed into StartReceiver is executed as a blocking call, i.e. in each poll go routine, the next event will not be received until the callback on current event completes. To make event processing serialized (no concurrency), use this option along with WithPollGoroutines(1)

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 WithInboundContextDecorator

func WithInboundContextDecorator(dec func(context.Context, binding.Message) context.Context) Option

WithInboundContextDecorator configures a new inbound context decorator. Inbound context decorators are invoked to wrap additional informations from the binding.Message and propagate these informations in the context passed to the event receiver.

func WithObservabilityService

func WithObservabilityService(service ObservabilityService) Option

WithObservabilityService configures the observability service to use to record traces and metrics

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. Deprecated: this is now noop and will be removed in future releases. Don't use distributed tracing extension to propagate traces: https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md#using-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.