Class Http2FrameCodec
- All Implemented Interfaces:
ChannelHandler
,ChannelInboundHandler
,ChannelOutboundHandler
,Http2LifecycleManager
- Direct Known Subclasses:
Http2MultiplexCodec
This API is very immature. The Http2Connection-based API is currently preferred over this API.
This API is targeted to eventually replace or reduce the need for the Http2ConnectionHandler
API.
An HTTP/2 handler that maps HTTP/2 frames to Http2Frame
objects and vice versa. For every incoming HTTP/2
frame, an Http2Frame
object is created and propagated via ByteToMessageDecoder.channelRead(io.netty.channel.ChannelHandlerContext, java.lang.Object)
. Outbound Http2Frame
objects received via write(io.netty.channel.ChannelHandlerContext, java.lang.Object, io.netty.channel.ChannelPromise)
are converted to the HTTP/2 wire format. HTTP/2 frames specific to a stream
implement the Http2StreamFrame
interface. The Http2FrameCodec
is instantiated using the
Http2FrameCodecBuilder
. It's recommended for channel handlers to inherit from the
Http2ChannelDuplexHandler
, as it provides additional functionality like iterating over all active streams or
creating outbound streams.
Stream Lifecycle
The frame codec delivers and writes frames for active streams. An active stream is closed when either side sends a
RST_STREAM
frame or both sides send a frame with the END_STREAM
flag set. Each
Http2StreamFrame
has a Http2FrameStream
object attached that uniquely identifies a particular stream.
Http2StreamFrame
s read from the channel always a Http2FrameStream
object set, while when writing a
Http2StreamFrame
the application code needs to set a Http2FrameStream
object using
Http2StreamFrame.stream(Http2FrameStream)
.
Flow control
The frame codec automatically increments stream and connection flow control windows.
Incoming flow controlled frames need to be consumed by writing a Http2WindowUpdateFrame
with the consumed
number of bytes and the corresponding stream identifier set to the frame codec.
The local stream-level flow control window can be changed by writing a Http2SettingsFrame
with the
Http2Settings.initialWindowSize()
set to the targeted value.
The connection-level flow control window can be changed by writing a Http2WindowUpdateFrame
with the
desired window size increment in bytes and the stream identifier set to 0
. By default the initial
connection-level flow control window is the same as initial stream-level flow control window.
New inbound Streams
The first frame of an HTTP/2 stream must be an Http2HeadersFrame
, which will have an Http2FrameStream
object attached.
New outbound Streams
A outbound HTTP/2 stream can be created by first instantiating a new Http2FrameStream
object via
Http2ChannelDuplexHandler.newStream()
, and then writing a Http2HeadersFrame
object with the stream
attached.
final Http2Stream2 stream = handler.newStream(); ctx.write(headersFrame.stream(stream)).addListener(new ChannelFutureListener() {
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate final class
(package private) static class
Http2FrameStream
implementation.private final class
private final class
Nested classes/interfaces inherited from class io.netty.handler.codec.ByteToMessageDecoder
ByteToMessageDecoder.Cumulator
Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler
ChannelHandler.Sharable
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) ChannelHandlerContext
private final IntObjectMap
<Http2FrameCodec.DefaultHttp2FrameStream> private final Integer
private static final InternalLogger
private int
Number of buffered streams if theStreamBufferingEncoder
is used.protected final Http2Connection.PropertyKey
private final Http2Connection.PropertyKey
Fields inherited from class io.netty.handler.codec.ByteToMessageDecoder
COMPOSITE_CUMULATOR, MERGE_CUMULATOR
-
Constructor Summary
ConstructorsConstructorDescriptionHttp2FrameCodec
(Http2ConnectionEncoder encoder, Http2ConnectionDecoder decoder, Http2Settings initialSettings, boolean decoupleCloseAndGoAway, boolean flushPreface) -
Method Summary
Modifier and TypeMethodDescription(package private) final boolean
consumeBytes
(int streamId, int bytes) (package private) final void
forEachActiveStream
(Http2FrameStreamVisitor streamVisitor) Iterates over all active HTTP/2 streams.private void
handleHeaderFuture
(ChannelFuture channelFuture, int streamId) final void
Do nothing by default, sub-classes may override this method.(package private) void
private void
increaseInitialConnectionWindow
(int deltaBytes) private boolean
initializeNewStream
(ChannelHandlerContext ctx, Http2FrameCodec.DefaultHttp2FrameStream http2FrameStream, ChannelPromise promise) protected final boolean
Called by the graceful shutdown logic to determine when it is safe to close the connection.(package private) Http2FrameCodec.DefaultHttp2FrameStream
Creates a new outbound/local stream.(package private) int
Retrieve the number of streams currently in the process of being initialized.protected void
onConnectionError
(ChannelHandlerContext ctx, boolean outbound, Throwable cause, Http2Exception http2Ex) Handler for a connection error.(package private) void
onHttp2Frame
(ChannelHandlerContext ctx, Http2Frame frame) (package private) void
(package private) void
onHttp2StreamStateChanged
(ChannelHandlerContext ctx, Http2FrameCodec.DefaultHttp2FrameStream stream) private void
onHttp2StreamWritabilityChanged
(ChannelHandlerContext ctx, Http2FrameCodec.DefaultHttp2FrameStream stream, boolean writable) private static void
onHttp2UnknownStreamError
(ChannelHandlerContext ctx, Throwable cause, Http2Exception.StreamException streamException) private void
onStreamActive0
(Http2Stream stream) protected final void
onStreamError
(ChannelHandlerContext ctx, boolean outbound, Throwable cause, Http2Exception.StreamException streamException) Exceptions for unknown streams, that is streams that have noHttp2FrameStream
object attached are simply logged and replied to by sending a RST_STREAM frame.private void
(package private) void
onUserEventTriggered
(ChannelHandlerContext ctx, Object evt) private void
tryExpandConnectionFlowControlWindow
(Http2Connection connection) final void
userEventTriggered
(ChannelHandlerContext ctx, Object evt) Handles the cleartext HTTP upgrade event.void
write
(ChannelHandlerContext ctx, Object msg, ChannelPromise promise) Processes allHttp2Frame
s.private void
writeGoAwayFrame
(ChannelHandlerContext ctx, Http2GoAwayFrame frame, ChannelPromise promise) private void
writeHeadersFrame
(ChannelHandlerContext ctx, Http2HeadersFrame headersFrame, ChannelPromise promise) private void
writePushPromise
(ChannelHandlerContext ctx, Http2PushPromiseFrame pushPromiseFrame, ChannelPromise promise) Methods inherited from class io.netty.handler.codec.http2.Http2ConnectionHandler
bind, channelActive, channelInactive, channelReadComplete, channelReadComplete0, channelWritabilityChanged, close, closeStream, closeStreamLocal, closeStreamRemote, connect, connection, decode, decoder, deregister, disconnect, encoder, exceptionCaught, flush, frameWriter, goAway, gracefulShutdownTimeoutMillis, gracefulShutdownTimeoutMillis, handlerRemoved0, handleServerHeaderDecodeSizeError, onError, onHttpClientUpgrade, onHttpServerUpgrade, read, resetStream
Methods inherited from class io.netty.handler.codec.ByteToMessageDecoder
actualReadableBytes, callDecode, channelRead, decodeLast, discardSomeReadBytes, handlerRemoved, internalBuffer, isSingleDecode, setCumulator, setDiscardAfterReads, setSingleDecode
Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter
channelRegistered, channelUnregistered
Methods inherited from class io.netty.channel.ChannelHandlerAdapter
ensureNotSharable, isSharable
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface io.netty.channel.ChannelHandler
handlerRemoved
-
Field Details
-
LOG
-
streamKey
-
upgradeKey
-
initialFlowControlWindowSize
-
ctx
-
numBufferedStreams
private int numBufferedStreamsNumber of buffered streams if theStreamBufferingEncoder
is used. -
frameStreamToInitializeMap
-
-
Constructor Details
-
Http2FrameCodec
Http2FrameCodec(Http2ConnectionEncoder encoder, Http2ConnectionDecoder decoder, Http2Settings initialSettings, boolean decoupleCloseAndGoAway, boolean flushPreface)
-
-
Method Details
-
newStream
Http2FrameCodec.DefaultHttp2FrameStream newStream()Creates a new outbound/local stream. -
forEachActiveStream
Iterates over all active HTTP/2 streams.This method must not be called outside of the event loop.
- Throws:
Http2Exception
-
numInitializingStreams
int numInitializingStreams()Retrieve the number of streams currently in the process of being initialized.This is package-private for testing only.
-
handlerAdded
Description copied from class:ChannelHandlerAdapter
Do nothing by default, sub-classes may override this method.- Specified by:
handlerAdded
in interfaceChannelHandler
- Overrides:
handlerAdded
in classHttp2ConnectionHandler
- Throws:
Exception
-
tryExpandConnectionFlowControlWindow
- Throws:
Http2Exception
-
handlerAdded0
- Throws:
Exception
-
userEventTriggered
Handles the cleartext HTTP upgrade event. If an upgrade occurred, sends a simple response via HTTP/2 on stream 1 (the stream specifically reserved for cleartext HTTP upgrade).- Specified by:
userEventTriggered
in interfaceChannelInboundHandler
- Overrides:
userEventTriggered
in classByteToMessageDecoder
- Throws:
Exception
-
onUserEventTriggered
- Throws:
Exception
-
write
Processes allHttp2Frame
s.Http2StreamFrame
s may only originate in child streams.- Specified by:
write
in interfaceChannelOutboundHandler
- Overrides:
write
in classHttp2ConnectionHandler
- Parameters:
ctx
- theChannelHandlerContext
for which the write operation is mademsg
- the message to writepromise
- theChannelPromise
to notify once the operation completes
-
increaseInitialConnectionWindow
- Throws:
Http2Exception
-
consumeBytes
- Throws:
Http2Exception
-
writeGoAwayFrame
private void writeGoAwayFrame(ChannelHandlerContext ctx, Http2GoAwayFrame frame, ChannelPromise promise) -
writeHeadersFrame
private void writeHeadersFrame(ChannelHandlerContext ctx, Http2HeadersFrame headersFrame, ChannelPromise promise) -
writePushPromise
private void writePushPromise(ChannelHandlerContext ctx, Http2PushPromiseFrame pushPromiseFrame, ChannelPromise promise) -
initializeNewStream
private boolean initializeNewStream(ChannelHandlerContext ctx, Http2FrameCodec.DefaultHttp2FrameStream http2FrameStream, ChannelPromise promise) -
handleHeaderFuture
-
onStreamActive0
-
onConnectionError
protected void onConnectionError(ChannelHandlerContext ctx, boolean outbound, Throwable cause, Http2Exception http2Ex) Description copied from class:Http2ConnectionHandler
Handler for a connection error. Sends a GO_AWAY frame to the remote endpoint. Once all streams are closed, the connection is shut down.- Overrides:
onConnectionError
in classHttp2ConnectionHandler
- Parameters:
ctx
- the channel contextoutbound
-true
if the error was caused by an outbound operation.cause
- the exception that was caughthttp2Ex
- theHttp2Exception
that is embedded in the causality chain. This may benull
if it's an unknown exception.
-
onStreamError
protected final void onStreamError(ChannelHandlerContext ctx, boolean outbound, Throwable cause, Http2Exception.StreamException streamException) Exceptions for unknown streams, that is streams that have noHttp2FrameStream
object attached are simply logged and replied to by sending a RST_STREAM frame.- Overrides:
onStreamError
in classHttp2ConnectionHandler
- Parameters:
ctx
- the channel contextoutbound
-true
if the error was caused by an outbound operation.cause
- the exception that was caughtstreamException
- theHttp2Exception.StreamException
that is embedded in the causality chain.
-
onHttp2UnknownStreamError
private static void onHttp2UnknownStreamError(ChannelHandlerContext ctx, Throwable cause, Http2Exception.StreamException streamException) -
isGracefulShutdownComplete
protected final boolean isGracefulShutdownComplete()Description copied from class:Http2ConnectionHandler
Called by the graceful shutdown logic to determine when it is safe to close the connection. Returnstrue
if the graceful shutdown has completed and the connection can be safely closed. This implementation just guarantees that there are no active streams. Subclasses may override to provide additional checks.- Overrides:
isGracefulShutdownComplete
in classHttp2ConnectionHandler
-
onUpgradeEvent
-
onHttp2StreamWritabilityChanged
private void onHttp2StreamWritabilityChanged(ChannelHandlerContext ctx, Http2FrameCodec.DefaultHttp2FrameStream stream, boolean writable) -
onHttp2StreamStateChanged
void onHttp2StreamStateChanged(ChannelHandlerContext ctx, Http2FrameCodec.DefaultHttp2FrameStream stream) -
onHttp2Frame
-
onHttp2FrameStreamException
-