httpstream

Documentation

Overview

Package httpstream adds multiplexed streaming support to HTTP requests and responses via connection upgrades.

Index

• Constants
• func Handshake(req *http.Request, w http.ResponseWriter, serverProtocols []string) (string, error)
• func IsUpgradeFailure(err error) bool
• func IsUpgradeRequest(req *http.Request) bool
• func NoOpNewStreamHandler(stream Stream, replySent <-chan struct{}) error
• type Connection
• type Dialer
• type NewStreamHandler
• type ResponseUpgrader
• type Stream
• type UpgradeFailureError
  • func (u *UpgradeFailureError) Error() string
• type UpgradeRoundTripper

Constants

const (
	HeaderConnection               = "Connection"
	HeaderUpgrade                  = "Upgrade"
	HeaderProtocolVersion          = "X-Stream-Protocol-Version"
	HeaderAcceptedProtocolVersions = "X-Accepted-Stream-Protocol-Versions"
)

Functions

func Handshake

func Handshake(req *http.Request, w http.ResponseWriter, serverProtocols []string) (string, error)

Handshake performs a subprotocol negotiation. If the client did request a subprotocol, Handshake will select the first common value found in serverProtocols. If a match is found, Handshake adds a response header indicating the chosen subprotocol. If no match is found, HTTP forbidden is returned, along with a response header containing the list of protocols the server can accept.

func IsUpgradeFailure

func IsUpgradeFailure(err error) bool

IsUpgradeFailure returns true if the passed error is (or wrapped error contains) the UpgradeFailureError.

func IsUpgradeRequest

func IsUpgradeRequest(req *http.Request) bool

IsUpgradeRequest returns true if the given request is a connection upgrade request

func NoOpNewStreamHandler

func NoOpNewStreamHandler(stream Stream, replySent <-chan struct{}) error

NoOpNewStreamHandler is a stream handler that accepts a new stream and performs no other logic.

Types

type Connection

type Connection interface {
	// CreateStream creates a new Stream with the supplied headers.
	CreateStream(headers http.Header) (Stream, error)
	// Close resets all streams and closes the connection.
	Close() error
	// CloseChan returns a channel that is closed when the underlying connection is closed.
	CloseChan() <-chan bool
	// SetIdleTimeout sets the amount of time the connection may remain idle before
	// it is automatically closed.
	SetIdleTimeout(timeout time.Duration)
	// RemoveStreams can be used to remove a set of streams from the Connection.
	RemoveStreams(streams ...Stream)
}

Connection represents an upgraded HTTP connection.

type Dialer

type Dialer interface {

	// Dial opens a streaming connection to a server using one of the protocols
	// specified (in order of most preferred to least preferred).
	Dial(protocols ...string) (Connection, string, error)
}

Dialer knows how to open a streaming connection to a server.

type NewStreamHandler

type NewStreamHandler func(stream Stream, replySent <-chan struct{}) error

NewStreamHandler defines a function that is called when a new Stream is received. If no error is returned, the Stream is accepted; otherwise, the stream is rejected. After the reply frame has been sent, replySent is closed.

type ResponseUpgrader

type ResponseUpgrader interface {
	// UpgradeResponse upgrades an HTTP response to one that supports multiplexed
	// streams. newStreamHandler will be called asynchronously whenever the
	// other end of the upgraded connection creates a new stream.
	UpgradeResponse(w http.ResponseWriter, req *http.Request, newStreamHandler NewStreamHandler) Connection
}

ResponseUpgrader knows how to upgrade HTTP requests and responses to add streaming support to them.

type Stream

type Stream interface {
	io.ReadWriteCloser
	// Reset closes both directions of the stream, indicating that neither client
	// or server can use it any more.
	Reset() error
	// Headers returns the headers used to create the stream.
	Headers() http.Header
	// Identifier returns the stream's ID.
	Identifier() uint32
}

Stream represents a bidirectional communications channel that is part of an upgraded connection.

type UpgradeFailureError

type UpgradeFailureError struct {
	Cause error
}

UpgradeFailureError encapsulates the cause for why the streaming upgrade request failed. Implements error interface.

func (*UpgradeFailureError) Error

func (u *UpgradeFailureError) Error() string

type UpgradeRoundTripper

type UpgradeRoundTripper interface {
	http.RoundTripper
	// NewConnection validates the response and creates a new Connection.
	NewConnection(resp *http.Response) (Connection, error)
}

UpgradeRoundTripper is a type of http.RoundTripper that is able to upgrade HTTP requests to support multiplexed bidirectional streams. After RoundTrip() is invoked, if the upgrade is successful, clients may retrieve the upgraded connection by calling UpgradeRoundTripper.Connection().