cloudevents

Documentation

Index

• Constants
• func Handler(fn interface{}) http.Handler
• func NewRequest(urlString string, data interface{}, context EventContext) (*http.Request, error)
• type EventContext
  • func FromContext(ctx context.Context) *EventContext
  • func FromRequest(data interface{}, r *http.Request) (*EventContext, error)
• type HTTPMarshaller
• type Mux
  • func NewMux() Mux
  • func (m Mux) Handle(eventType string, fn interface{}) error
  • func (m Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

Constants

const (
	// HeaderCloudEventsVersion is the header for the version of Cloud Events
	// used.
	HeaderCloudEventsVersion = "CE-CloudEventsVersion"

	// HeaderEventID is the header for the unique ID of this event.
	HeaderEventID = "CE-EventID"

	// HeaderEventTime is the OPTIONAL header for the time at which an event
	// occurred.
	HeaderEventTime = "CE-EventTime"

	// HeaderEventType is the header for type of event represented. Value SHOULD
	// be in reverse-dns form.
	HeaderEventType = "CE-EventType"

	// HeaderEventTypeVersion is the OPTIONAL header for the version of the
	// scheme for the event type.
	HeaderEventTypeVersion = "CE-EventTypeVersion"

	// HeaderSchemaURL is the OPTIONAL header for the schema of the event data.
	HeaderSchemaURL = "CE-SchemaURL"

	// HeaderSource is the header for the source which emitted this event.
	HeaderSource = "CE-Source"

	// HeaderExtensions is the OPTIONAL header prefix for CloudEvents extensions
	HeaderExtensionsPrefix = "CE-X-"

	// Binary implements Binary encoding/decoding
	Binary binary = 0
)

const (
	// CloudEventsVersion is the version of the CloudEvents spec targeted
	// by this library.
	CloudEventsVersion = "0.1"

	// ContentTypeStructuredJSON is the content-type for "Structured" encoding
	// where an event envelope is written in JSON and the body is arbitrary
	// data which might be an alternate encoding.
	ContentTypeStructuredJSON = "application/cloudevents+json"

	// ContentTypeBinaryJSON is the content-type for "Binary" encoding where
	// the event context is in HTTP headers and the body is a JSON event data.
	ContentTypeBinaryJSON = "application/json"

	// HeaderContentType is the standard HTTP header "Content-Type"
	HeaderContentType = "Content-Type"
)

const (
	// Structured implements the JSON structured encoding/decoding
	Structured structured = 0
)

Functions

func Handler

func Handler(fn interface{}) http.Handler

Handler creates an EventHandler that implements http.Handler If the fn parameter is not a valid type, will produce an http.Handler that also conforms to error and will respond to all HTTP requests with that error. Valid types of fn are:

* func() * func() error * func() (anything, error) * func() (anything, EventContext, error) * func(context.Context) * func(context.Context) error * func(context.Context) (anything, error) * func(context.Context) (anything, EventContext, error) * func(context.Context, anything) * func(context.Context, anything) error * func(context.Context, anything) (anything, error) * func(context.Context, anything) (anything, EventContext, error)

CloudEvent contexts are available from the context.Context parameter CloudEvent data will be deserialized into the "anything" parameter. The library supports native decoding with both XML and JSON encoding. To accept another advanced type, pass an io.Reader as the input parameter.

HTTP responses are generated based on the return value of fn:

• any error return value will cause a StatusInternalServerError response
• a function with no return type or a function returning nil will cause a StatusNoContent response
• a function that returns a value will cause a StatusOK and render the response as JSON, with headers from an EventContext, if appropriate

func NewRequest

func NewRequest(urlString string, data interface{}, context EventContext) (*http.Request, error)

NewRequest craetes an HTTP request for Structured content encoding.

Types

type EventContext

type EventContext struct {
	// The version of the CloudEvents specification used by the event.
	CloudEventsVersion string `json:"cloudEventsVersion,omitempty"`
	// ID of the event; must be non-empty and unique within the scope of the producer.
	EventID string `json:"eventID"`
	// Timestamp when the event happened.
	EventTime time.Time `json:"eventTime,omitempty"`
	// Type of occurrence which has happened.
	EventType string `json:"eventType"`
	// The version of the `eventType`; this is producer-specific.
	EventTypeVersion string `json:"eventTypeVersion,omitempty"`
	// A link to the schema that the `data` attribute adheres to.
	SchemaURL string `json:"schemaURL,omitempty"`
	// A MIME (RFC 2046) string describing the media type of `data`.
	// TODO: Should an empty string assume `application/json`, or auto-detect the content?
	ContentType string `json:"contentType,omitempty"`
	// A URI describing the event producer.
	Source string `json:"source"`
	// Additional metadata without a well-defined structure.
	Extensions map[string]interface{} `json:"extensions,omitempty"`
}

EventContext holds standard metadata about an event. See https://github.com/cloudevents/spec/blob/v0.1/spec.md#context-attributes for details on these fields.

func FromContext

func FromContext(ctx context.Context) *EventContext

FromContext loads an EventContext from a normal context.Context

func FromRequest

func FromRequest(data interface{}, r *http.Request) (*EventContext, error)

FromRequest parses a CloudEvent from any known encoding.

type HTTPMarshaller

type HTTPMarshaller interface {
	FromRequest(data interface{}, r *http.Request) (*EventContext, error)
	NewRequest(urlString string, data interface{}, context EventContext) (*http.Request, error)
}

HTTPMarshaller implements a scheme for decoding CloudEvents over HTTP. Implementations are Binary, Structured, and Any

type Mux

type Mux map[string]*handler

Mux allows developers to handle logically related groups of functionality multiplexed based on the event type. TODO: Consider dropping Mux or figure out how to handle non-JSON encoding.

func NewMux

func NewMux() Mux

NewMux creates a new Mux

func (Mux) Handle

func (m Mux) Handle(eventType string, fn interface{}) error

Handle adds a new handler for a specific event type If the fn parameter is not a valid type, the endpoint will respond to all HTTP requests with that error. Valid types of fn are:

* func() * func() error * func() (anything, error) * func(context.Context) * func(context.Context) error * func(context.Context) (anything, error) * func(context.Context, anything) * func(context.Context, anything) error * func(context.Context, anything) (anything, error)

CloudEvent contexts are available from the context.Context parameter CloudEvent data will be deserialized into the "anything" parameter. The library supports native decoding with both XML and JSON encoding. To accept another advanced type, pass an io.Reader as the input parameter.

HTTP responses are generated based on the return value of fn: * any error return value will cause a StatusInternalServerError response * a function with no return type or a function returning nil will cause a StatusNoContent response * a function that returns a value will cause a StatusOK and render the response as JSON

func (Mux) ServeHTTP

func (m Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler