import "golang.org/x/net/http2"
Package http2 implements the HTTP/2 protocol.
This is a work in progress. This package is low-level and intended to be used directly by very few people. Most users will use it indirectly through integration with the net/http package. See ConfigureServer. That ConfigureServer call will likely be automatic or available via an empty import in the future.
buffer.go errors.go flow.go frame.go gotrack.go headermap.go http2.go pipe.go server.go transport.go write.go writesched.go
const (
// ClientPreface is the string that must be sent by new
// connections from clients.
ClientPreface = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
// NextProtoTLS is the NPN/ALPN protocol negotiated during
// HTTP/2's TLS setup.
NextProtoTLS = "h2"
)ErrFrameTooLarge is returned from Framer.ReadFrame when the peer sends a frame that is larger than declared with SetMaxReadFrameSize.
ConfigureServer adds HTTP/2 support to a net/http Server.
The configuration conf may be nil.
ConfigureServer must be called before s begins serving.
ConnectionError is an error that results in the termination of the entire connection.
func (e ConnectionError) Error() string
type ContinuationFrame struct {
FrameHeader
// contains filtered or unexported fields
}A ContinuationFrame is used to continue a sequence of header block fragments. See http://http2.github.io/http2-spec/#rfc.section.6.10
func (f *ContinuationFrame) HeaderBlockFragment() []byte
func (f *ContinuationFrame) HeadersEnded() bool
func (f *ContinuationFrame) StreamEnded() bool
type DataFrame struct {
FrameHeader
// contains filtered or unexported fields
}A DataFrame conveys arbitrary, variable-length sequences of octets associated with a stream. See http://http2.github.io/http2-spec/#rfc.section.6.1
Data returns the frame's data octets, not including any padding size byte or padding suffix bytes. The caller must not retain the returned memory past the next call to ReadFrame.
An ErrCode is an unsigned 32-bit error code as defined in the HTTP/2 spec.
const (
ErrCodeNo ErrCode = 0x0
ErrCodeProtocol ErrCode = 0x1
ErrCodeInternal ErrCode = 0x2
ErrCodeFlowControl ErrCode = 0x3
ErrCodeSettingsTimeout ErrCode = 0x4
ErrCodeStreamClosed ErrCode = 0x5
ErrCodeFrameSize ErrCode = 0x6
ErrCodeRefusedStream ErrCode = 0x7
ErrCodeCancel ErrCode = 0x8
ErrCodeCompression ErrCode = 0x9
ErrCodeConnect ErrCode = 0xa
ErrCodeEnhanceYourCalm ErrCode = 0xb
ErrCodeInadequateSecurity ErrCode = 0xc
ErrCodeHTTP11Required ErrCode = 0xd
)Flags is a bitmask of HTTP/2 flags. The meaning of flags varies depending on the frame type.
const (
// Data Frame
FlagDataEndStream Flags = 0x1
FlagDataPadded Flags = 0x8
// Headers Frame
FlagHeadersEndStream Flags = 0x1
FlagHeadersEndHeaders Flags = 0x4
FlagHeadersPadded Flags = 0x8
FlagHeadersPriority Flags = 0x20
// Settings Frame
FlagSettingsAck Flags = 0x1
// Ping Frame
FlagPingAck Flags = 0x1
// Continuation Frame
FlagContinuationEndHeaders Flags = 0x4
FlagPushPromiseEndHeaders Flags = 0x4
FlagPushPromisePadded Flags = 0x8
)Frame-specific FrameHeader flag bits.
Has reports whether f contains all (0 or more) flags in v.
type Frame interface {
Header() FrameHeader
// contains filtered or unexported methods
}A Frame is the base interface implemented by all frame types. Callers will generally type-assert the specific frame type: *HeadersFrame, *SettingsFrame, *WindowUpdateFrame, etc.
Frames are only valid until the next call to Framer.ReadFrame.
type FrameHeader struct {
// Type is the 1 byte frame type. There are ten standard frame
// types, but extension frame types may be written by WriteRawFrame
// and will be returned by ReadFrame (as UnknownFrame).
Type FrameType
// Flags are the 1 byte of 8 potential bit flags per frame.
// They are specific to the frame type.
Flags Flags
// Length is the length of the frame, not including the 9 byte header.
// The maximum size is one byte less than 16MB (uint24), but only
// frames up to 16KB are allowed without peer agreement.
Length uint32
// StreamID is which stream this frame is for. Certain frames
// are not stream-specific, in which case this field is 0.
StreamID uint32
// contains filtered or unexported fields
}A FrameHeader is the 9 byte header of all HTTP/2 frames.
See http://http2.github.io/http2-spec/#FrameHeader
func ReadFrameHeader(r io.Reader) (FrameHeader, error)
ReadFrameHeader reads 9 bytes from r and returns a FrameHeader. Most users should use Framer.ReadFrame instead.
func (h FrameHeader) Header() FrameHeader
Header returns h. It exists so FrameHeaders can be embedded in other specific frame types and implement the Frame interface.
func (h FrameHeader) String() string
A FrameType is a registered frame type as defined in http://http2.github.io/http2-spec/#rfc.section.11.2
const (
FrameData FrameType = 0x0
FrameHeaders FrameType = 0x1
FramePriority FrameType = 0x2
FrameRSTStream FrameType = 0x3
FrameSettings FrameType = 0x4
FramePushPromise FrameType = 0x5
FramePing FrameType = 0x6
FrameGoAway FrameType = 0x7
FrameWindowUpdate FrameType = 0x8
FrameContinuation FrameType = 0x9
)type Framer struct {
// AllowIllegalWrites permits the Framer's Write methods to
// write frames that do not conform to the HTTP/2 spec. This
// permits using the Framer to test other HTTP/2
// implementations' conformance to the spec.
// If false, the Write methods will prefer to return an error
// rather than comply.
AllowIllegalWrites bool
// contains filtered or unexported fields
}A Framer reads and writes Frames.
NewFramer returns a Framer that writes frames to w and reads them from r.
ReadFrame reads a single frame. The returned Frame is only valid until the next call to ReadFrame. If the frame is larger than previously set with SetMaxReadFrameSize, the returned error is ErrFrameTooLarge.
SetMaxReadFrameSize sets the maximum size of a frame that will be read by a subsequent call to ReadFrame. It is the caller's responsibility to advertise this limit with a SETTINGS frame.
func (f *Framer) WriteContinuation(streamID uint32, endHeaders bool, headerBlockFragment []byte) error
WriteContinuation writes a CONTINUATION frame.
It will perform exactly one Write to the underlying Writer. It is the caller's responsibility to not call other Write methods concurrently.
WriteData writes a DATA frame.
It will perform exactly one Write to the underlying Writer. It is the caller's responsibility to not call other Write methods concurrently.
func (f *Framer) WriteHeaders(p HeadersFrameParam) error
WriteHeaders writes a single HEADERS frame.
This is a low-level header writing method. Encoding headers and splitting them into any necessary CONTINUATION frames is handled elsewhere.
It will perform exactly one Write to the underlying Writer. It is the caller's responsibility to not call other Write methods concurrently.
func (f *Framer) WritePriority(streamID uint32, p PriorityParam) error
WritePriority writes a PRIORITY frame.
It will perform exactly one Write to the underlying Writer. It is the caller's responsibility to not call other Write methods concurrently.
func (f *Framer) WritePushPromise(p PushPromiseParam) error
WritePushPromise writes a single PushPromise Frame.
As with Header Frames, This is the low level call for writing individual frames. Continuation frames are handled elsewhere.
It will perform exactly one Write to the underlying Writer. It is the caller's responsibility to not call other Write methods concurrently.
WriteRSTStream writes a RST_STREAM frame.
It will perform exactly one Write to the underlying Writer. It is the caller's responsibility to not call other Write methods concurrently.
WriteRawFrame writes a raw frame. This can be used to write extension frames unknown to this package.
WriteSettings writes a SETTINGS frame with zero or more settings specified and the ACK bit not set.
It will perform exactly one Write to the underlying Writer. It is the caller's responsibility to not call other Write methods concurrently.
WriteSettings writes an empty SETTINGS frame with the ACK bit set.
It will perform exactly one Write to the underlying Writer. It is the caller's responsibility to not call other Write methods concurrently.
WriteWindowUpdate writes a WINDOW_UPDATE frame. The increment value must be between 1 and 2,147,483,647, inclusive. If the Stream ID is zero, the window update applies to the connection as a whole.
type GoAwayFrame struct {
FrameHeader
LastStreamID uint32
ErrCode ErrCode
// contains filtered or unexported fields
}A GoAwayFrame informs the remote peer to stop creating streams on this connection. See http://http2.github.io/http2-spec/#rfc.section.6.8
func (f *GoAwayFrame) DebugData() []byte
DebugData returns any debug data in the GOAWAY frame. Its contents are not defined. The caller must not retain the returned memory past the next call to ReadFrame.
type HeadersFrame struct {
FrameHeader
// Priority is set if FlagHeadersPriority is set in the FrameHeader.
Priority PriorityParam
// contains filtered or unexported fields
}A HeadersFrame is used to open a stream and additionally carries a header block fragment.
func (f *HeadersFrame) HasPriority() bool
func (f *HeadersFrame) HeaderBlockFragment() []byte
func (f *HeadersFrame) HeadersEnded() bool
func (f *HeadersFrame) StreamEnded() bool
type HeadersFrameParam struct {
// StreamID is the required Stream ID to initiate.
StreamID uint32
// BlockFragment is part (or all) of a Header Block.
BlockFragment []byte
// EndStream indicates that the header block is the last that
// the endpoint will send for the identified stream. Setting
// this flag causes the stream to enter one of "half closed"
// states.
EndStream bool
// EndHeaders indicates that this frame contains an entire
// header block and is not followed by any
// CONTINUATION frames.
EndHeaders bool
// PadLength is the optional number of bytes of zeros to add
// to this frame.
PadLength uint8
// Priority, if non-zero, includes stream priority information
// in the HEADER frame.
Priority PriorityParam
}HeadersFrameParam are the parameters for writing a HEADERS frame.
type PingFrame struct {
FrameHeader
Data [8]byte
}A PingFrame is a mechanism for measuring a minimal round trip time from the sender, as well as determining whether an idle connection is still functional. See http://http2.github.io/http2-spec/#rfc.section.6.7
type PriorityFrame struct {
FrameHeader
PriorityParam
}A PriorityFrame specifies the sender-advised priority of a stream. See http://http2.github.io/http2-spec/#rfc.section.6.3
type PriorityParam struct {
// StreamDep is a 31-bit stream identifier for the
// stream that this stream depends on. Zero means no
// dependency.
StreamDep uint32
// Exclusive is whether the dependency is exclusive.
Exclusive bool
// Weight is the stream's zero-indexed weight. It should be
// set together with StreamDep, or neither should be set. Per
// the spec, "Add one to the value to obtain a weight between
// 1 and 256."
Weight uint8
}PriorityParam are the stream prioritzation parameters.
func (p PriorityParam) IsZero() bool
type PushPromiseFrame struct {
FrameHeader
PromiseID uint32
// contains filtered or unexported fields
}A PushPromiseFrame is used to initiate a server stream. See http://http2.github.io/http2-spec/#rfc.section.6.6
func (f *PushPromiseFrame) HeaderBlockFragment() []byte
func (f *PushPromiseFrame) HeadersEnded() bool
type PushPromiseParam struct {
// StreamID is the required Stream ID to initiate.
StreamID uint32
// PromiseID is the required Stream ID which this
// Push Promises
PromiseID uint32
// BlockFragment is part (or all) of a Header Block.
BlockFragment []byte
// EndHeaders indicates that this frame contains an entire
// header block and is not followed by any
// CONTINUATION frames.
EndHeaders bool
// PadLength is the optional number of bytes of zeros to add
// to this frame.
PadLength uint8
}PushPromiseParam are the parameters for writing a PUSH_PROMISE frame.
type RSTStreamFrame struct {
FrameHeader
ErrCode ErrCode
}A RSTStreamFrame allows for abnormal termination of a stream. See http://http2.github.io/http2-spec/#rfc.section.6.4
type Server struct {
// MaxHandlers limits the number of http.Handler ServeHTTP goroutines
// which may run at a time over all connections.
// Negative or zero no limit.
// TODO: implement
MaxHandlers int
// MaxConcurrentStreams optionally specifies the number of
// concurrent streams that each client may have open at a
// time. This is unrelated to the number of http.Handler goroutines
// which may be active globally, which is MaxHandlers.
// If zero, MaxConcurrentStreams defaults to at least 100, per
// the HTTP/2 spec's recommendations.
MaxConcurrentStreams uint32
// MaxReadFrameSize optionally specifies the largest frame
// this server is willing to read. A valid value is between
// 16k and 16M, inclusive. If zero or otherwise invalid, a
// default value is used.
MaxReadFrameSize uint32
// PermitProhibitedCipherSuites, if true, permits the use of
// cipher suites prohibited by the HTTP/2 spec.
PermitProhibitedCipherSuites bool
}Server is an HTTP/2 server.
type Setting struct {
// ID is which setting is being set.
// See http://http2.github.io/http2-spec/#SettingValues
ID SettingID
// Val is the value.
Val uint32
}Setting is a setting parameter: which setting it is, and its value.
Valid reports whether the setting is valid.
A SettingID is an HTTP/2 setting as defined in http://http2.github.io/http2-spec/#iana-settings
const (
SettingHeaderTableSize SettingID = 0x1
SettingEnablePush SettingID = 0x2
SettingMaxConcurrentStreams SettingID = 0x3
SettingInitialWindowSize SettingID = 0x4
SettingMaxFrameSize SettingID = 0x5
SettingMaxHeaderListSize SettingID = 0x6
)type SettingsFrame struct {
FrameHeader
// contains filtered or unexported fields
}A SettingsFrame conveys configuration parameters that affect how endpoints communicate, such as preferences and constraints on peer behavior.
See http://http2.github.io/http2-spec/#SETTINGS
func (f *SettingsFrame) ForeachSetting(fn func(Setting) error) error
ForeachSetting runs fn for each setting. It stops and returns the first error.
func (f *SettingsFrame) IsAck() bool
func (f *SettingsFrame) Value(s SettingID) (v uint32, ok bool)
StreamError is an error that only affects one stream within an HTTP/2 connection.
func (e StreamError) Error() string
type Transport struct {
Fallback http.RoundTripper
// TODO: remove this and make more general with a TLS dial hook, like http
InsecureTLSDial bool
// contains filtered or unexported fields
}CloseIdleConnections closes any connections which were previously connected from previous requests but are now sitting idle. It does not interrupt any connections currently in use.
type UnknownFrame struct {
FrameHeader
// contains filtered or unexported fields
}An UnknownFrame is the frame type returned when the frame type is unknown or no specific frame type parser exists.
func (f *UnknownFrame) Payload() []byte
Payload returns the frame's payload (after the header). It is not valid to call this method after a subsequent call to Framer.ReadFrame, nor is it valid to retain the returned slice. The memory is owned by the Framer and is invalidated when the next frame is read.
type WindowUpdateFrame struct {
FrameHeader
Increment uint32
}A WindowUpdateFrame is used to implement flow control. See http://http2.github.io/http2-spec/#rfc.section.6.9
| Path | Synopsis |
|---|---|
| h2i | The h2i command is an interactive HTTP/2 console. |
| hpack | Package hpack implements HPACK, a compression format for efficiently representing HTTP header fields in the context of HTTP/2. |
Package http2 imports 18 packages (graph) and is imported by 1 packages. Updated 2015-09-24. Refresh now. Tools for package owners.