http

Documentation

Overview

Package http implements an HTTP binding using net/http module

Index

• Constants
• func NewResult(statusCode int, messageFmt string, args ...interface{}) protocol.Result
• func NewRetriesResult(result protocol.Result, retries int, startTime time.Time, ...) protocol.Result
• func WriteRequest(ctx context.Context, m binding.Message, httpRequest *http.Request, ...) error
• func WriteResponseWriter(ctx context.Context, m binding.Message, status int, rw http.ResponseWriter, ...) error
• type Message
  • func NewMessage(header nethttp.Header, body io.ReadCloser) *Message
  • func NewMessageFromHttpRequest(req *nethttp.Request) *Message
  • func NewMessageFromHttpResponse(resp *nethttp.Response) *Message
  • func (m *Message) Finish(err error) error
  • func (m *Message) GetAttribute(k spec.Kind) (spec.Attribute, interface{})
  • func (m *Message) GetExtension(name string) interface{}
  • func (m *Message) ReadBinary(ctx context.Context, encoder binding.BinaryWriter) (err error)
  • func (m *Message) ReadEncoding() binding.Encoding
  • func (m *Message) ReadStructured(ctx context.Context, encoder binding.StructuredWriter) error
• type Middleware
• type Option
  • func WithClient(client nethttp.Client) Option
  • func WithHeader(key, value string) Option
  • func WithListener(l net.Listener) Option
  • func WithMethod(method string) Option
  • func WithMiddleware(middleware Middleware) Option
  • func WithPath(path string) Option
  • func WithPort(port int) Option
  • func WithRoundTripper(roundTripper nethttp.RoundTripper) Option
  • func WithShutdownTimeout(timeout time.Duration) Option
  • func WithTarget(targetUrl string) Option
• type Protocol
  • func New(opts ...Option) (*Protocol, error)
  • func (p *Protocol) GetPath() string
  • func (p *Protocol) GetPort() int
  • func (p *Protocol) OpenInbound(ctx context.Context) error
  • func (p *Protocol) Receive(ctx context.Context) (binding.Message, error)
  • func (p *Protocol) Request(ctx context.Context, m binding.Message, transformers ...binding.Transformer) (binding.Message, error)
  • func (p *Protocol) Respond(ctx context.Context) (binding.Message, protocol.ResponseFn, error)
  • func (p *Protocol) Send(ctx context.Context, m binding.Message, transformers ...binding.Transformer) error
  • func (p *Protocol) ServeHTTP(rw http.ResponseWriter, req *http.Request)
• type Result
  • func (e *Result) Error() string
  • func (e *Result) Is(target error) bool
• type RetriesResult
  • func (e *RetriesResult) Error() string
  • func (e *RetriesResult) Is(target error) bool

Constants

const ContentLength = "Content-Length"

const ContentType = "Content-Type"

const (
	// DefaultShutdownTimeout defines the default timeout given to the http.Server when calling Shutdown.
	DefaultShutdownTimeout = time.Minute * 1
)

Functions

func NewResult

func NewResult(statusCode int, messageFmt string, args ...interface{}) protocol.Result

NewResult returns a fully populated http Result that should be used as a transport.Result.

func NewRetriesResult

func NewRetriesResult(result protocol.Result, retries int, startTime time.Time, attempts []protocol.Result) protocol.Result

NewRetriesResult returns a http RetriesResult that should be used as a transport.Result without retries

func WriteRequest

func WriteRequest(ctx context.Context, m binding.Message, httpRequest *http.Request, transformers ...binding.Transformer) error

WriteRequest fills the provided httpRequest with the message m. Using context you can tweak the encoding processing (more details on binding.Write documentation).

func WriteResponseWriter

func WriteResponseWriter(ctx context.Context, m binding.Message, status int, rw http.ResponseWriter, transformers ...binding.Transformer) error

WriteResponseWriter writes out to the the provided httpResponseWriter with the message m. Using context you can tweak the encoding processing (more details on binding.Write documentation).

Types

type Message

type Message struct {
	Header     nethttp.Header
	BodyReader io.ReadCloser
	OnFinish   func(error) error
	// contains filtered or unexported fields
}

Message holds the Header and Body of a HTTP Request or Response. The Message instance *must* be constructed from NewMessage function. This message *cannot* be read several times. In order to read it more times, buffer it using binding/buffering methods

func NewMessage

func NewMessage(header nethttp.Header, body io.ReadCloser) *Message

NewMessage returns a binding.Message with header and data. The returned binding.Message *cannot* be read several times. In order to read it more times, buffer it using binding/buffering methods

func NewMessageFromHttpRequest

func NewMessageFromHttpRequest(req *nethttp.Request) *Message

NewMessageFromHttpRequest returns a binding.Message with header and data. The returned binding.Message *cannot* be read several times. In order to read it more times, buffer it using binding/buffering methods

func NewMessageFromHttpResponse

func NewMessageFromHttpResponse(resp *nethttp.Response) *Message

NewMessageFromHttpResponse returns a binding.Message with header and data. The returned binding.Message *cannot* be read several times. In order to read it more times, buffer it using binding/buffering methods

func (*Message) Finish

func (m *Message) Finish(err error) error

func (*Message) GetAttribute

func (m *Message) GetAttribute(k spec.Kind) (spec.Attribute, interface{})

func (*Message) GetExtension

func (m *Message) GetExtension(name string) interface{}

func (*Message) ReadBinary

func (m *Message) ReadBinary(ctx context.Context, encoder binding.BinaryWriter) (err error)

func (*Message) ReadEncoding

func (m *Message) ReadEncoding() binding.Encoding

func (*Message) ReadStructured

func (m *Message) ReadStructured(ctx context.Context, encoder binding.StructuredWriter) error

type Middleware

type Middleware func(next nethttp.Handler) nethttp.Handler

Middleware is a function that takes an existing http.Handler and wraps it in middleware, returning the wrapped http.Handler.

type Option

type Option func(*Protocol) error

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

func WithClient

func WithClient(client nethttp.Client) Option

WithClient sets the protocol client

func WithHeader

func WithHeader(key, value string) Option

WithHeader sets an additional default outbound header for all cloudevents when using an HTTP request.

func WithListener

func WithListener(l net.Listener) Option

WithListener sets the listener for StartReceiver. Only one of WithListener or WithPort is allowed.

func WithMethod

func WithMethod(method string) Option

WithMethod sets the HTTP verb (GET, POST, PUT, etc.) to use when using an HTTP request.

func WithMiddleware

func WithMiddleware(middleware Middleware) Option

WithMiddleware adds an HTTP middleware to the transport. It may be specified multiple times. Middleware is applied to everything before it. For example `NewClient(WithMiddleware(foo), WithMiddleware(bar))` would result in `bar(foo(original))`.

func WithPath

func WithPath(path string) Option

WithPath sets the path to receive cloudevents on for HTTP transports.

func WithPort

func WithPort(port int) Option

WithPort sets the listening port for StartReceiver. Only one of WithListener or WithPort is allowed.

func WithRoundTripper

func WithRoundTripper(roundTripper nethttp.RoundTripper) Option

WithRoundTripper sets the HTTP RoundTripper.

func WithShutdownTimeout

func WithShutdownTimeout(timeout time.Duration) Option

WithShutdownTimeout sets the shutdown timeout when the http server is being shutdown.

func WithTarget

func WithTarget(targetUrl string) Option

WithTarget sets the outbound recipient of cloudevents when using an HTTP request.

type Protocol

type Protocol struct {
	Target          *url.URL
	RequestTemplate *http.Request
	Client          *http.Client

	// ShutdownTimeout defines the timeout given to the http.Server when calling Shutdown.
	// If nil, DefaultShutdownTimeout is used.
	ShutdownTimeout time.Duration

	// Port is the port to bind the receiver to. Defaults to 8080.
	Port *int
	// Path is the path to bind the receiver to. Defaults to "/".
	Path string

	// Handler is the handler the http Server will use. Use this to reuse the
	// http server. If nil, the Protocol will create a one.
	Handler *http.ServeMux
	// contains filtered or unexported fields
}

Protocol acts as both a http client and a http handler.

func New

func New(opts ...Option) (*Protocol, error)

func (*Protocol) GetPath

func (p *Protocol) GetPath() string

GetPath returns the path the transport is hosted on. If the path is '/', the transport will handle requests on any URI. To discover the true path a request was received on, inspect the context from Receive(cxt, ...) with TransportContextFrom(ctx).

func (*Protocol) GetPort

func (p *Protocol) GetPort() int

GetPort returns the listening port. Returns -1 if there is a listening error. Note this will call net.Listen() if the listener is not already started.

func (*Protocol) OpenInbound

func (p *Protocol) OpenInbound(ctx context.Context) error

func (*Protocol) Receive

func (p *Protocol) Receive(ctx context.Context) (binding.Message, error)

Receive the next incoming HTTP request as a CloudEvent. Returns non-nil error if the incoming HTTP request fails to parse as a CloudEvent Returns io.EOF if the receiver is closed.

func (*Protocol) Request

func (p *Protocol) Request(ctx context.Context, m binding.Message, transformers ...binding.Transformer) (binding.Message, error)

Request implements binding.Requester

func (*Protocol) Respond

func (p *Protocol) Respond(ctx context.Context) (binding.Message, protocol.ResponseFn, error)

Respond receives the next incoming HTTP request as a CloudEvent and waits for the response callback to invoked before continuing. Returns non-nil error if the incoming HTTP request fails to parse as a CloudEvent Returns io.EOF if the receiver is closed.

func (*Protocol) Send

func (p *Protocol) Send(ctx context.Context, m binding.Message, transformers ...binding.Transformer) error

Send implements binding.Sender

func (*Protocol) ServeHTTP

func (p *Protocol) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServeHTTP implements http.Handler. Blocks until ResponseFn is invoked.

type Result

type Result struct {
	StatusCode int
	Format     string
	Args       []interface{}
}

Result wraps the fields required to make adjustments for http Responses.

func (*Result) Error

func (e *Result) Error() string

Error returns the string that is formed by using the format string with the provided args.

func (*Result) Is

func (e *Result) Is(target error) bool

Is returns if the target error is a Result type checking target.

type RetriesResult

type RetriesResult struct {
	// The last result
	protocol.Result

	// Retries is the number of times the request was tried
	Retries int

	// Duration records the time spent retrying. Exclude the successful request (if any)
	Duration time.Duration

	// Attempts of all failed requests. Exclude last result.
	Attempts []protocol.Result
}

RetriesResult wraps the fields required to make adjustments for http Responses.

func (*RetriesResult) Error

func (e *RetriesResult) Error() string

Error returns the string that is formed by using the format string with the provided args.

func (*RetriesResult) Is

func (e *RetriesResult) Is(target error) bool

Is returns if the target error is a RetriesResult type checking target.