grpchttp2

package
v1.69.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 18, 2024 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package grpchttp2 defines HTTP/2 types and a framer API and implementation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ContinuationFrame 

type ContinuationFrame struct {
	HdrBlock []byte
	// contains filtered or unexported fields
}

ContinuationFrame is the representation of a CONTINUATION Frame. The CONTINUATION frame is used to continue a sequence of header block fragments.

func (*ContinuationFrame) Free 

func (f *ContinuationFrame) Free()

Free frees the buffer containing the header block in this frame.

func (*ContinuationFrame) Header 

func (f *ContinuationFrame) Header() *FrameHeader

Header returns the 9 byte HTTP/2 header for this frame.

type DataFrame 

type DataFrame struct {
	Data []byte
	// contains filtered or unexported fields
}

DataFrame is the representation of a DATA frame. DATA frames convey arbitrary, variable-length sequences of octets associated with a stream.

func (*DataFrame) Free 

func (f *DataFrame) Free()

Free frees the buffer containing the data in this frame.

func (*DataFrame) Header 

func (f *DataFrame) Header() *FrameHeader

Header returns the 9 byte HTTP/2 header for this frame.

type ErrCode 

type ErrCode uint32

ErrCode represents an HTTP/2 Error Code. Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY frames to convey the reasons for the stream or connection error. See HTTP/2 Error Code for definitions of each of the following error codes. 

const (
	ErrCodeNoError            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
)

Error Codes defined by the HTTP/2 Spec.

func (ErrCode) String 

func (err ErrCode) String() string

type Flag 

type Flag uint8

Flag represents one or more flags set on an HTTP/2 Frame. 

const (
	FlagDataEndStream          Flag = 0x1
	FlagDataPadded             Flag = 0x8
	FlagHeadersEndStream       Flag = 0x1
	FlagHeadersEndHeaders      Flag = 0x4
	FlagHeadersPadded          Flag = 0x8
	FlagHeadersPriority        Flag = 0x20
	FlagSettingsAck            Flag = 0x1
	FlagPingAck                Flag = 0x1
	FlagContinuationEndHeaders Flag = 0x4
)

Flags defined in the HTTP/2 Spec.

func (Flag) IsSet 

func (f Flag) IsSet(flag Flag) bool

IsSet returns a boolean indicating whether the passed flag is set on this flag instance.

type Frame 

type Frame interface {
	// Header returns the HTTP/2 9 byte header from the current Frame.
	Header() *FrameHeader
	// Free frees the underlying buffer if present so it can be reused by the
	// framer.
	//
	// TODO: Remove method from the interface once the mem package gets merged.
	// Free will be called on each mem.Buffer individually.
	Free()
}

Frame represents an HTTP/2 Frame. This interface struct is only to be used on the read path of the Framer. The writing path expects the data to be passed individually, not using this type.

Each concrete Frame type defined below implements the Frame interface.

type FrameHeader 

type FrameHeader struct {
	// Size is the size of the frame's payload without the 9 header bytes.
	// As per the HTTP/2 spec, size can be up to 3 bytes, but only frames
	// up to 16KB can be processed without agreement.
	Size uint32
	// Type is a byte that represents the Frame Type.
	Type FrameType
	// Flags is a byte representing the flags set on this Frame.
	Flags Flag
	// StreamID is the ID for the stream which this frame is for. If the
	// frame is connection specific instead of stream specific, the
	// streamID is 0.
	StreamID uint32
}

FrameHeader is the 9 byte header of any HTTP/2 Frame. See Frame Header.

type FrameType 

type FrameType uint8

FrameType represents the type of an HTTP/2 Frame. See Frame Type. 

const (
	FrameTypeData         FrameType = 0x0
	FrameTypeHeaders      FrameType = 0x1
	FrameTypeRSTStream    FrameType = 0x3
	FrameTypeSettings     FrameType = 0x4
	FrameTypePing         FrameType = 0x6
	FrameTypeGoAway       FrameType = 0x7
	FrameTypeWindowUpdate FrameType = 0x8
	FrameTypeContinuation FrameType = 0x9
)

Frame types defined in the HTTP/2 Spec.

type Framer 

type Framer interface {
	// ReadFrame returns grpchttp2.Frame. It is the caller's responsibility to
	// call Frame.Free() once it is done using it. Note that once the mem
	// package gets merged, this API will change in favor of Buffer.Free().
	ReadFrame() (Frame, error)
	// WriteData writes an HTTP/2 DATA frame to the stream.
	// TODO: Once the mem package gets merged, data will change type to
	// mem.BufferSlice.
	WriteData(streamID uint32, endStream bool, data ...[]byte) error
	// WriteData writes an HTTP/2 HEADERS frame to the stream.
	// TODO: Once the mem package gets merged, headerBlock will change type to
	// mem.Buffer.
	WriteHeaders(streamID uint32, endStream, endHeaders bool, headerBlocks []byte) error
	// WriteData writes an HTTP/2 RST_STREAM frame to the stream.
	WriteRSTStream(streamID uint32, code ErrCode) error
	// WriteSettings writes an HTTP/2 SETTINGS frame to the connection.
	WriteSettings(settings ...Setting) error
	// WriteSettingsAck writes an HTTP/2 SETTINGS frame with the ACK flag set.
	WriteSettingsAck() error
	// WritePing writes an HTTP/2 PING frame to the connection.
	WritePing(ack bool, data [8]byte) error
	// WriteGoAway writes an HTTP/2 GOAWAY frame to the connection.
	// TODO: Once the mem package gets merged, debugData will change type to
	// mem.Buffer.
	WriteGoAway(maxStreamID uint32, code ErrCode, debugData []byte) error
	// WriteWindowUpdate writes an HTTP/2 WINDOW_UPDATE frame to the stream.
	WriteWindowUpdate(streamID, inc uint32) error
	// WriteContinuation writes an HTTP/2 CONTINUATION frame to the stream.
	// TODO: Once the mem package gets merged, data will change type to
	// mem.Buffer.
	WriteContinuation(streamID uint32, endHeaders bool, headerBlock []byte) error
}

Framer encapsulates the functionality to read and write HTTP/2 frames.

type FramerBridge 

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

FramerBridge adapts the net/x/http2 Framer to satisfy the grpchttp2.Framer interface.

Note: This allows temporary use of the older framer and will be removed in a future release after the new framer stabilizes.

func NewFramerBridge 

func NewFramerBridge(w io.Writer, r io.Reader, maxHeaderListSize uint32, pool mem.BufferPool) *FramerBridge

NewFramerBridge creates an adaptor that wraps a http2.Framer in a grpchttp2.Framer.

Internally, it creates a http2.Framer that uses the provided io.Reader and io.Writer, and is configured with a maximum header list size of maxHeaderListSize.

Frames returned by a call to the underlying http2.Framer's ReadFrame() method need to be consumed before the next call to it. To overcome this restriction, the data in a Frame returned by the http2.Framer's ReadFrame is copied into a buffer from the given pool. If no pool is provided, a default pool provided by the mem package is used.

func (*FramerBridge) ReadFrame 

func (fr *FramerBridge) ReadFrame() (Frame, error)

ReadFrame reads a frame from the underlying http2.Framer and returns a Frame defined in the grpchttp2 package. This operation copies the data to a buffer from the pool, making it safe to use even after another call to ReadFrame.

func (*FramerBridge) WriteContinuation 

func (fr *FramerBridge) WriteContinuation(streamID uint32, endHeaders bool, headerBlock []byte) error

WriteContinuation writes a Continuation Frame into the underlying writer.

func (*FramerBridge) WriteData 

func (fr *FramerBridge) WriteData(streamID uint32, endStream bool, data ...[]byte) error

WriteData writes a DATA Frame into the underlying writer.

func (*FramerBridge) WriteGoAway 

func (fr *FramerBridge) WriteGoAway(maxStreamID uint32, code ErrCode, debugData []byte) error

WriteGoAway writes a GoAway Frame to the underlying writer.

func (*FramerBridge) WriteHeaders 

func (fr *FramerBridge) WriteHeaders(streamID uint32, endStream, endHeaders bool, headerBlock []byte) error

WriteHeaders writes a Headers Frame into the underlying writer.

func (*FramerBridge) WritePing 

func (fr *FramerBridge) WritePing(ack bool, data [8]byte) error

WritePing writes a Ping frame to the underlying writer.

func (*FramerBridge) WriteRSTStream 

func (fr *FramerBridge) WriteRSTStream(streamID uint32, code ErrCode) error

WriteRSTStream writes a RSTStream Frame into the underlying writer.

func (*FramerBridge) WriteSettings 

func (fr *FramerBridge) WriteSettings(settings ...Setting) error

WriteSettings writes a Settings Frame into the underlying writer.

func (*FramerBridge) WriteSettingsAck 

func (fr *FramerBridge) WriteSettingsAck() error

WriteSettingsAck writes a Settings Frame with the Ack flag set.

func (*FramerBridge) WriteWindowUpdate 

func (fr *FramerBridge) WriteWindowUpdate(streamID, inc uint32) error

WriteWindowUpdate writes a WindowUpdate Frame into the underlying writer.

type GoAwayFrame 

type GoAwayFrame struct {
	LastStreamID uint32
	Code         ErrCode
	DebugData    []byte
	// contains filtered or unexported fields
}

GoAwayFrame is the representation of a GOAWAY Frame. The GOAWAY frame is used to initiate shutdown of a connection or to signal serious error conditions.

func (*GoAwayFrame) Free 

func (f *GoAwayFrame) Free()

Free frees the buffer containing the debug data in this frame.

func (*GoAwayFrame) Header 

func (f *GoAwayFrame) Header() *FrameHeader

Header returns the 9 byte HTTP/2 header for this frame.

type HeadersFrame 

type HeadersFrame struct {
	HdrBlock []byte
	// contains filtered or unexported fields
}

HeadersFrame is the representation of a HEADERS Frame. The HEADERS frame is used to open a stream, and additionally carries a header block fragment.

func (*HeadersFrame) Free 

func (f *HeadersFrame) Free()

Free frees the buffer containing the header block in this frame.

func (*HeadersFrame) Header 

func (f *HeadersFrame) Header() *FrameHeader

Header returns the 9 byte HTTP/2 header for this frame.

type MetaHeadersFrame 

type MetaHeadersFrame struct {
	Fields []hpack.HeaderField
	// Truncated indicates whether the MetaHeadersFrame has been truncated due
	// to being longer than the MaxHeaderListSize.
	Truncated bool
	// contains filtered or unexported fields
}

MetaHeadersFrame is the representation of one HEADERS frame and zero or more contiguous CONTINUATION frames and the decoding of their HPACK-encoded contents. This frame type is not transmitted over the network and is only generated by the ReadFrame() function.

Since there is no underlying buffer in this Frame, Free() is a no-op.

func (*MetaHeadersFrame) Free 

func (f *MetaHeadersFrame) Free()

Free is a no-op for MetaHeadersFrame.

func (*MetaHeadersFrame) Header 

func (f *MetaHeadersFrame) Header() *FrameHeader

Header returns the 9 byte HTTP/2 header for this frame.

type PingFrame 

type PingFrame struct {
	Data []byte
	// contains filtered or unexported fields
}

PingFrame is the representation of a PING Frame. The PING frame is a mechanism for measuring a minimal round-trip time from the sender, as well as determining whether an idle connection is still functional.

func (*PingFrame) Free 

func (f *PingFrame) Free()

Free frees the buffer containing the data in this frame.

func (*PingFrame) Header 

func (f *PingFrame) Header() *FrameHeader

Header returns the 9 byte HTTP/2 header for this frame.

type RSTStreamFrame 

type RSTStreamFrame struct {
	Code ErrCode
	// contains filtered or unexported fields
}

RSTStreamFrame is the representation of a RST_STREAM Frame. There is no underlying byte array in this frame, so Free() is a no-op. The RST_STREAM frame allows for immediate termination of a stream

func (*RSTStreamFrame) Free 

func (f *RSTStreamFrame) Free()

Free is a no-op for RSTStreamFrame.

func (*RSTStreamFrame) Header 

func (f *RSTStreamFrame) Header() *FrameHeader

Header returns the 9 byte HTTP/2 header for this frame.

type Setting 

type Setting struct {
	ID    SettingID
	Value uint32
}

Setting represents the id and value pair of an HTTP/2 setting. See Setting Format.

type SettingID 

type SettingID uint16

SettingID represents the id of an HTTP/2 setting. See Setting Values. 

const (
	SettingsHeaderTableSize      SettingID = 0x1
	SettingsEnablePush           SettingID = 0x2
	SettingsMaxConcurrentStreams SettingID = 0x3
	SettingsInitialWindowSize    SettingID = 0x4
	SettingsMaxFrameSize         SettingID = 0x5
	SettingsMaxHeaderListSize    SettingID = 0x6
)

Setting IDs defined in the HTTP/2 Spec.

type SettingsFrame 

type SettingsFrame struct {
	Settings []Setting
	// contains filtered or unexported fields
}

SettingsFrame is the representation of a SETTINGS Frame. There is no underlying byte array in this frame, so Free() is a no-op.

The SETTINGS frame conveys configuration parameters that affect how endpoints communicate, such as preferences and constraints on peer behavior.

func (*SettingsFrame) Free 

func (f *SettingsFrame) Free()

Free is a no-op for SettingsFrame.

func (*SettingsFrame) Header 

func (f *SettingsFrame) Header() *FrameHeader

Header returns the 9 byte HTTP/2 header for this frame.

type UnknownFrame 

type UnknownFrame struct {
	Payload []byte
	// contains filtered or unexported fields
}

UnknownFrame is a struct that is returned when the framer encounters an unsupported frame.

func (*UnknownFrame) Free 

func (f *UnknownFrame) Free()

Free frees the underlying data in the frame.

func (*UnknownFrame) Header 

func (f *UnknownFrame) Header() *FrameHeader

Header returns the 9 byte HTTP/2 header for this frame.

type WindowUpdateFrame 

type WindowUpdateFrame struct {
	Inc uint32
	// contains filtered or unexported fields
}

WindowUpdateFrame is the representation of a WINDOW_UPDATE Frame. The WINDOW_UPDATE frame is used to implement flow control.

func (*WindowUpdateFrame) Free 

func (f *WindowUpdateFrame) Free()

Free is a no-op for WindowUpdateFrame.

func (*WindowUpdateFrame) Header 

func (f *WindowUpdateFrame) Header() *FrameHeader

Header returns the 9 byte HTTP/2 header for this frame.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.