h2

Documentation

Overview

Package h2 contains basic HTTP/2 handling for Martian.

Index

• type Config
  • func (c *Config) Proxy(closing chan bool, cc io.ReadWriter, url *url.URL) error
• type DataFrameProcessor
• type Direction
• type HeaderProcessor
• type PriorityFrameProcessor
• type Processor
• type Processors
  • func (s *Processors) ForDirection(dir Direction) Processor
• type PushPromiseProcessor
• type RSTStreamProcessor
• type StreamProcessorFactory

Types

type Config

type Config struct {
	// AllowedHostsFilter is a function returning true if the argument is a host for which H2 is
	// permitted.
	AllowedHostsFilter func(string) bool

	// RootCAs is the pool of CA certificates used by the MitM client to authenticate the server.
	RootCAs *x509.CertPool

	// StreamProcessorFactories is a list of factories used to instantiate a chain of HTTP/2 stream
	// processors. A chain is created for every stream.
	StreamProcessorFactories []StreamProcessorFactory

	// EnableDebugLogs turns on fine-grained debug logging for HTTP/2.
	EnableDebugLogs bool
}

Config stores the configuration information needed for HTTP/2 processing.

func (*Config) Proxy

func (c *Config) Proxy(closing chan bool, cc io.ReadWriter, url *url.URL) error

Proxy proxies HTTP/2 traffic between a client connection, `cc`, and the HTTP/2 `url` assuming h2 is being used. Since no browsers use h2c, it's safe to assume all traffic uses TLS.

type DataFrameProcessor

type DataFrameProcessor interface {
	Data(data []byte, streamEnded bool) error
}

DataFrameProcessor processes data frames.

type Direction

type Direction uint8

Direction indicates the direction of the traffic flow.

const (
	// ClientToServer indicates traffic flowing from client-to-server.
	ClientToServer Direction = iota
	// ServerToClient indicates traffic flowing from server-to-client.
	ServerToClient
)

type HeaderProcessor

type HeaderProcessor interface {
	Header(
		headers []hpack.HeaderField,
		streamEnded bool,
		priority http2.PriorityParam,
	) error
}

HeaderProcessor processes headers, abstracting out continuations.

type PriorityFrameProcessor

type PriorityFrameProcessor interface {
	Priority(http2.PriorityParam) error
}

PriorityFrameProcessor processes priority frames.

type Processor

type Processor interface {
	DataFrameProcessor
	HeaderProcessor
	PriorityFrameProcessor
	RSTStreamProcessor
	PushPromiseProcessor
}

Processor accepts the possible stream frames.

This API abstracts away some of the lower level HTTP/2 mechanisms. CONTINUATION frames are appropriately buffered and turned into Header calls and Header or PushPromise calls are split into CONTINUATION frames when needed.

The proxy handles WINDOW_UPDATE frames and flow control, managing it independently for both endpoints.

type Processors

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

Processors encapsulates the two traffic receiving endpoints.

func (*Processors) ForDirection

func (s *Processors) ForDirection(dir Direction) Processor

ForDirection returns the processor receiving traffic in the given direction.

type PushPromiseProcessor

type PushPromiseProcessor interface {
	PushPromise(promiseID uint32, headers []hpack.HeaderField) error
}

PushPromiseProcessor processes push promises, abstracting out continuations.

type RSTStreamProcessor

type RSTStreamProcessor interface {
	RSTStream(http2.ErrCode) error
}

RSTStreamProcessor processes RSTStream frames.

type StreamProcessorFactory

type StreamProcessorFactory func(url *url.URL, sinks *Processors) (Processor, Processor)

StreamProcessorFactory is implemented by clients that wish to observe or edit HTTP/2 frames flowing through the proxy. It creates a pair of processors for the bidirectional stream. A processor consumes frames then calls the corresponding sink methods to forward frames to the destination, modifying the frame if needed.

Returns the client-to-server and server-to-client processors. Nil values are safe to return and no processing occurs in such cases. NOTE: an interface may have a non-nil type with a nil value. Such values are treated as valid processors.

Concurrency: there is a separate client-to-server and server-to-client thread. Calls against the `ClientToServer` sink must be made on the client-to-server thread and calls against the `ServerToClient` sink must be made on the server-to-client thread. Implementors should guard interactions across threads.