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    * https://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.netty5.handler.codec.http2;
17  
18  import io.netty5.buffer.api.Buffer;
19  import io.netty5.channel.ChannelHandlerContext;
20  import io.netty5.util.internal.UnstableApi;
21  
22  /**
23   * An listener of HTTP/2 frames.
24   */
25  @UnstableApi
26  public interface Http2FrameListener {
27      /**
28       * Handles an inbound {@code DATA} frame.
29       *
30       * @param ctx the context from the handler where the frame was read.
31       * @param streamId the subject stream for the frame.
32       * @param data payload buffer for the frame. This buffer will be released by the codec.
33       * @param padding additional bytes that should be added to obscure the true content size. Must be between 0 and
34       *                256 (inclusive).
35       * @param endOfStream Indicates whether this is the last frame to be sent from the remote endpoint for this stream.
36       * @return the number of bytes that have been processed by the application. The returned bytes are used by the
37       * inbound flow controller to determine the appropriate time to expand the inbound flow control window (i.e. send
38       * {@code WINDOW_UPDATE}). Returning a value equal to the length of {@code data} + {@code padding} will effectively
39       * opt-out of application-level flow control for this frame. Returning a value less than the length of {@code data}
40       * + {@code padding} will defer the returning of the processed bytes, which the application must later return via
41       * {@link Http2LocalFlowController#consumeBytes(Http2Stream, int)}. The returned value must
42       * be >= {@code 0} and <= {@code data.readableBytes()} + {@code padding}.
43       */
44      int onDataRead(ChannelHandlerContext ctx, int streamId, Buffer data, int padding,
45                     boolean endOfStream) throws Http2Exception;
46  
47      /**
48       * Handles an inbound {@code HEADERS} frame.
49       * <p>
50       * Only one of the following methods will be called for each {@code HEADERS} frame sequence.
51       * One will be called when the {@code END_HEADERS} flag has been received.
52       * <ul>
53       * <li>{@link #onHeadersRead(ChannelHandlerContext, int, Http2Headers, int, boolean)}</li>
54       * <li>{@link #onHeadersRead(ChannelHandlerContext, int, Http2Headers, int, short, boolean, int, boolean)}</li>
55       * <li>{@link #onPushPromiseRead(ChannelHandlerContext, int, int, Http2Headers, int)}</li>
56       * </ul>
57       * <p>
58       * To say it another way; the {@link Http2Headers} will contain all of the headers
59       * for the current message exchange step (additional queuing is not necessary).
60       *
61       * @param ctx the context from the handler where the frame was read.
62       * @param streamId the subject stream for the frame.
63       * @param headers the received headers.
64       * @param padding additional bytes that should be added to obscure the true content size. Must be between 0 and
65       *                256 (inclusive).
66       * @param endOfStream Indicates whether this is the last frame to be sent from the remote endpoint
67       *            for this stream.
68       */
69      void onHeadersRead(ChannelHandlerContext ctx, int streamId, Http2Headers headers, int padding,
70              boolean endOfStream) throws Http2Exception;
71  
72      /**
73       * Handles an inbound {@code HEADERS} frame with priority information specified.
74       * Only called if {@code END_HEADERS} encountered.
75       * <p>
76       * Only one of the following methods will be called for each {@code HEADERS} frame sequence.
77       * One will be called when the {@code END_HEADERS} flag has been received.
78       * <ul>
79       * <li>{@link #onHeadersRead(ChannelHandlerContext, int, Http2Headers, int, boolean)}</li>
80       * <li>{@link #onHeadersRead(ChannelHandlerContext, int, Http2Headers, int, short, boolean, int, boolean)}</li>
81       * <li>{@link #onPushPromiseRead(ChannelHandlerContext, int, int, Http2Headers, int)}</li>
82       * </ul>
83       * <p>
84       * To say it another way; the {@link Http2Headers} will contain all of the headers
85       * for the current message exchange step (additional queuing is not necessary).
86       *
87       * @param ctx the context from the handler where the frame was read.
88       * @param streamId the subject stream for the frame.
89       * @param headers the received headers.
90       * @param streamDependency the stream on which this stream depends, or 0 if dependent on the
91       *            connection.
92       * @param weight the new weight for the stream.
93       * @param exclusive whether or not the stream should be the exclusive dependent of its parent.
94       * @param padding additional bytes that should be added to obscure the true content size. Must be between 0 and
95       *                256 (inclusive).
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 {@code PRIORITY} frame.
105      * <p>
106      * Note that is it possible to have this method called and no stream object exist for either
107      * {@code streamId}, {@code streamDependency}, or both. This is because the {@code PRIORITY} frame can be
108      * sent/received when streams are in the {@code CLOSED} state.
109      *
110      * @param ctx the context from the handler where the frame was read.
111      * @param streamId the subject stream for the frame.
112      * @param streamDependency the stream on which this stream depends, or 0 if dependent on the
113      *            connection.
114      * @param weight the new weight for the stream.
115      * @param exclusive whether or not the stream should be the exclusive dependent of its parent.
116      */
117     void onPriorityRead(ChannelHandlerContext ctx, int streamId, int streamDependency,
118             short weight, boolean exclusive) throws Http2Exception;
119 
120     /**
121      * Handles an inbound {@code RST_STREAM} frame.
122      *
123      * @param ctx the context from the handler where the frame was read.
124      * @param streamId the stream that is terminating.
125      * @param errorCode the error code identifying the type of failure.
126      */
127     void onRstStreamRead(ChannelHandlerContext ctx, int streamId, long errorCode) throws Http2Exception;
128 
129     /**
130      * Handles an inbound {@code SETTINGS} acknowledgment frame.
131      * @param ctx the context from the handler where the frame was read.
132      */
133     void onSettingsAckRead(ChannelHandlerContext ctx) throws Http2Exception;
134 
135     /**
136      * Handles an inbound {@code SETTINGS} frame.
137      *
138      * @param ctx the context from the handler where the frame was read.
139      * @param settings the settings received from the remote endpoint.
140      */
141     void onSettingsRead(ChannelHandlerContext ctx, Http2Settings settings) throws Http2Exception;
142 
143     /**
144      * Handles an inbound {@code PING} frame.
145      *
146      * @param ctx the context from the handler where the frame was read.
147      * @param data the payload of the frame.
148      */
149     void onPingRead(ChannelHandlerContext ctx, long data) throws Http2Exception;
150 
151     /**
152      * Handles an inbound {@code PING} acknowledgment.
153      *
154      * @param ctx the context from the handler where the frame was read.
155      * @param data the payload of the frame.
156      */
157     void onPingAckRead(ChannelHandlerContext ctx, long data) throws Http2Exception;
158 
159     /**
160      * Handles an inbound {@code PUSH_PROMISE} frame. Only called if {@code END_HEADERS} encountered.
161      * <p>
162      * Promised requests MUST be authoritative, cacheable, and safe.
163      * See <a href="https://tools.ietf.org/html/rfc7540#section-8.2">[RFC 7540], Section 8.2</a>.
164      * <p>
165      * Only one of the following methods will be called for each {@code HEADERS} frame sequence.
166      * One will be called when the {@code END_HEADERS} flag has been received.
167      * <ul>
168      * <li>{@link #onHeadersRead(ChannelHandlerContext, int, Http2Headers, int, boolean)}</li>
169      * <li>{@link #onHeadersRead(ChannelHandlerContext, int, Http2Headers, int, short, boolean, int, boolean)}</li>
170      * <li>{@link #onPushPromiseRead(ChannelHandlerContext, int, int, Http2Headers, int)}</li>
171      * </ul>
172      * <p>
173      * To say it another way; the {@link Http2Headers} will contain all of the headers
174      * for the current message exchange step (additional queuing is not necessary).
175      *
176      * @param ctx the context from the handler where the frame was read.
177      * @param streamId the stream the frame was sent on.
178      * @param promisedStreamId the ID of the promised stream.
179      * @param headers the received headers.
180      * @param padding additional bytes that should be added to obscure the true content size. Must be between 0 and
181      *                256 (inclusive).
182      */
183     void onPushPromiseRead(ChannelHandlerContext ctx, int streamId, int promisedStreamId,
184             Http2Headers headers, int padding) throws Http2Exception;
185 
186     /**
187      * Handles an inbound {@code 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, Buffer debugData)
196             throws Http2Exception;
197 
198     /**
199      * Handles an inbound {@code 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, Buffer payload)
219             throws Http2Exception;
220 }