View Javadoc
1   /*
2    * Copyright 2014 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License, version 2.0 (the
5    * "License"); you may not use this file except in compliance with the License. You may obtain a
6    * copy of the License at:
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software distributed under the License
11   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
12   * or implied. See the License for the specific language governing permissions and limitations under
13   * the License.
14   */
15  
16  package io.netty.handler.codec.http2;
17  
18  import io.netty.buffer.ByteBuf;
19  import io.netty.channel.ChannelHandlerContext;
20  
21  /**
22   * An listener of HTTP/2 frames.
23   */
24  public interface Http2FrameListener {
25  
26      /**
27       * Handles an inbound {@code DATA} frame.
28       *
29       * @param ctx the context from the handler where the frame was read.
30       * @param streamId the subject stream for the frame.
31       * @param data payload buffer for the frame. This buffer will be released by the codec.
32       * @param padding the number of padding bytes found at the end of the frame.
33       * @param endOfStream Indicates whether this is the last frame to be sent from the remote
34       *            endpoint for this stream.
35       * @return the number of bytes that have been processed by the application. The returned bytes
36       *         are used by the inbound flow controller to determine the appropriate time to expand
37       *         the inbound flow control window (i.e. send {@code WINDOW_UPDATE}). Returning a value
38       *         equal to the length of {@code data} + {@code padding} will effectively opt-out of
39       *         application-level flow control for this frame. Returning a value less than the length
40       *         of {@code data} + {@code padding} will defer the returning of the processed bytes,
41       *         which the application must later return via
42       *         {@link Http2InboundFlowState#returnProcessedBytes(ChannelHandlerContext, int)}. The
43       *         returned value must be >= {@code 0} and <= {@code data.readableBytes()} +
44       *         {@code padding}.
45       */
46      int onDataRead(ChannelHandlerContext ctx, int streamId, ByteBuf data, int padding,
47              boolean endOfStream) throws Http2Exception;
48  
49      /**
50       * Handles an inbound HEADERS frame.
51       * <p>
52       * Only one of the following methods will be called for each HEADERS frame sequence.
53       * One will be called when the END_HEADERS flag has been received.
54       * <ul>
55       * <li>{@link #onHeadersRead(ChannelHandlerContext, int, Http2Headers, int, boolean)}</li>
56       * <li>{@link #onHeadersRead(ChannelHandlerContext, int, Http2Headers, int, short, boolean, int, boolean)}</li>
57       * <li>{@link #onPushPromiseRead(ChannelHandlerContext, int, int, Http2Headers, int)}</li>
58       * </ul>
59       * <p>
60       * To say it another way; the {@link Http2Headers} will contain all of the headers
61       * for the current message exchange step (additional queuing is not necessary).
62       *
63       * @param ctx the context from the handler where the frame was read.
64       * @param streamId the subject stream for the frame.
65       * @param headers the received headers.
66       * @param padding the number of padding bytes found at the end of the frame.
67       * @param endOfStream Indicates whether this is the last frame to be sent from the remote endpoint
68       *            for this stream.
69       */
70      void onHeadersRead(ChannelHandlerContext ctx, int streamId, Http2Headers headers, int padding,
71              boolean endOfStream) throws Http2Exception;
72  
73      /**
74       * Handles an inbound HEADERS frame with priority information specified. Only called if END_HEADERS encountered.
75       *
76       * <p>
77       * Only one of the following methods will be called for each HEADERS frame sequence.
78       * One will be called when the END_HEADERS flag has been received.
79       * <ul>
80       * <li>{@link #onHeadersRead(ChannelHandlerContext, int, Http2Headers, int, boolean)}</li>
81       * <li>{@link #onHeadersRead(ChannelHandlerContext, int, Http2Headers, int, short, boolean, int, boolean)}</li>
82       * <li>{@link #onPushPromiseRead(ChannelHandlerContext, int, int, Http2Headers, int)}</li>
83       * </ul>
84       * <p>
85       * To say it another way; the {@link Http2Headers} will contain all of the headers
86       * for the current message exchange step (additional queuing is not necessary).
87       *
88       * @param ctx the context from the handler where the frame was read.
89       * @param streamId the subject stream for the frame.
90       * @param headers the received headers.
91       * @param streamDependency the stream on which this stream depends, or 0 if dependent on the
92       *            connection.
93       * @param weight the new weight for the stream.
94       * @param exclusive whether or not the stream should be the exclusive dependent of its parent.
95       * @param padding the number of padding bytes found at the end of the frame.
96       * @param endOfStream Indicates whether this is the last frame to be sent from the remote endpoint
97       *            for this stream.
98       */
99      void onHeadersRead(ChannelHandlerContext ctx, int streamId, Http2Headers headers,
100             int streamDependency, short weight, boolean exclusive, int padding, boolean endOfStream)
101             throws Http2Exception;
102 
103     /**
104      * Handles an inbound PRIORITY frame.
105      *
106      * @param ctx the context from the handler where the frame was read.
107      * @param streamId the subject stream for the frame.
108      * @param streamDependency the stream on which this stream depends, or 0 if dependent on the
109      *            connection.
110      * @param weight the new weight for the stream.
111      * @param exclusive whether or not the stream should be the exclusive dependent of its parent.
112      */
113     void onPriorityRead(ChannelHandlerContext ctx, int streamId, int streamDependency,
114             short weight, boolean exclusive) throws Http2Exception;
115 
116     /**
117      * Handles an inbound RST_STREAM frame.
118      *
119      * @param ctx the context from the handler where the frame was read.
120      * @param streamId the stream that is terminating.
121      * @param errorCode the error code identifying the type of failure.
122      */
123     void onRstStreamRead(ChannelHandlerContext ctx, int streamId, long errorCode) throws Http2Exception;
124 
125     /**
126      * Handles an inbound SETTINGS acknowledgment frame.
127      * @param ctx the context from the handler where the frame was read.
128      */
129     void onSettingsAckRead(ChannelHandlerContext ctx) throws Http2Exception;
130 
131     /**
132      * Handles an inbound SETTINGS frame.
133      *
134      * @param ctx the context from the handler where the frame was read.
135      * @param settings the settings received from the remote endpoint.
136      */
137     void onSettingsRead(ChannelHandlerContext ctx, Http2Settings settings) throws Http2Exception;
138 
139     /**
140      * Handles an inbound PING frame.
141      *
142      * @param ctx the context from the handler where the frame was read.
143      * @param data the payload of the frame. If this buffer needs to be retained by the listener
144      *            they must make a copy.
145      */
146     void onPingRead(ChannelHandlerContext ctx, ByteBuf data) throws Http2Exception;
147 
148     /**
149      * Handles an inbound PING acknowledgment.
150      *
151      * @param ctx the context from the handler where the frame was read.
152      * @param data the payload of the frame. If this buffer needs to be retained by the listener
153      *            they must make a copy.
154      */
155     void onPingAckRead(ChannelHandlerContext ctx, ByteBuf data) throws Http2Exception;
156 
157     /**
158      * Handles an inbound PUSH_PROMISE frame. Only called if END_HEADERS encountered.
159      * <p>
160      * Promised requests MUST be cacheable
161      * (see <a href="https://tools.ietf.org/html/rfc7231#section-4.2.3">[RFC7231], Section 4.2.3</a>) and
162      * MUST be safe (see <a href="https://tools.ietf.org/html/rfc7231#section-4.2.1">[RFC7231], Section 4.2.1</a>).
163      * If these conditions do not hold the application MUST throw a {@link Http2Exception.StreamException} with
164      * error type {@link Http2Error#PROTOCOL_ERROR}.
165      * <p>
166      * Only one of the following methods will be called for each HEADERS frame sequence.
167      * One will be called when the END_HEADERS flag has been received.
168      * <ul>
169      * <li>{@link #onHeadersRead(ChannelHandlerContext, int, Http2Headers, int, boolean)}</li>
170      * <li>{@link #onHeadersRead(ChannelHandlerContext, int, Http2Headers, int, short, boolean, int, boolean)}</li>
171      * <li>{@link #onPushPromiseRead(ChannelHandlerContext, int, int, Http2Headers, int)}</li>
172      * </ul>
173      * <p>
174      * To say it another way; the {@link Http2Headers} will contain all of the headers
175      * for the current message exchange step (additional queuing is not necessary).
176      *
177      * @param ctx the context from the handler where the frame was read.
178      * @param streamId the stream the frame was sent on.
179      * @param promisedStreamId the ID of the promised stream.
180      * @param headers the received headers.
181      * @param padding the number of padding bytes found at the end of the frame.
182      */
183     void onPushPromiseRead(ChannelHandlerContext ctx, int streamId, int promisedStreamId,
184             Http2Headers headers, int padding) throws Http2Exception;
185 
186     /**
187      * Handles an inbound GO_AWAY frame.
188      *
189      * @param ctx the context from the handler where the frame was read.
190      * @param lastStreamId the last known stream of the remote endpoint.
191      * @param errorCode the error code, if abnormal closure.
192      * @param debugData application-defined debug data. If this buffer needs to be retained by the
193      *            listener they must make a copy.
194      */
195     void onGoAwayRead(ChannelHandlerContext ctx, int lastStreamId, long errorCode, ByteBuf debugData)
196             throws Http2Exception;
197 
198     /**
199      * Handles an inbound WINDOW_UPDATE frame.
200      *
201      * @param ctx the context from the handler where the frame was read.
202      * @param streamId the stream the frame was sent on.
203      * @param windowSizeIncrement the increased number of bytes of the remote endpoint's flow
204      *            control window.
205      */
206     void onWindowUpdateRead(ChannelHandlerContext ctx, int streamId, int windowSizeIncrement)
207             throws Http2Exception;
208 
209     /**
210      * Handler for a frame not defined by the HTTP/2 spec.
211      *
212      * @param ctx the context from the handler where the frame was read.
213      * @param frameType the frame type from the HTTP/2 header.
214      * @param streamId the stream the frame was sent on.
215      * @param flags the flags in the frame header.
216      * @param payload the payload of the frame.
217      */
218     void onUnknownFrame(ChannelHandlerContext ctx, byte frameType, int streamId, Http2Flags flags, ByteBuf payload);
219 }