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.ChannelFuture;
20  import io.netty.channel.ChannelHandlerContext;
21  import io.netty.channel.ChannelPromise;
22  import io.netty.util.internal.UnstableApi;
23  
24  import java.io.Closeable;
25  
26  /**
27   * A writer responsible for marshaling HTTP/2 frames to the channel. All of the write methods in
28   * this interface write to the context, but DO NOT FLUSH. To perform a flush, you must separately
29   * call {@link ChannelHandlerContext#flush()}.
30   */
31  @UnstableApi
32  public interface Http2FrameWriter extends Http2DataWriter, Closeable {
33      /**
34       * Configuration specific to {@link Http2FrameWriter}
35       */
36      interface Configuration {
37          /**
38           * Get the {@link Http2HeadersEncoder.Configuration} for this {@link Http2FrameWriter}
39           */
40          Http2HeadersEncoder.Configuration headersConfiguration();
41  
42          /**
43           * Get the {@link Http2FrameSizePolicy} for this {@link Http2FrameWriter}
44           */
45          Http2FrameSizePolicy frameSizePolicy();
46      }
47  
48      /**
49       * Writes a HEADERS frame to the remote endpoint.
50       *
51       * @param ctx the context to use for writing.
52       * @param streamId the stream for which to send the frame.
53       * @param headers the headers to be sent.
54       * @param padding additional bytes that should be added to obscure the true content size. Must be between 0 and
55       *                256 (inclusive).
56       * @param endStream indicates if this is the last frame to be sent for the stream.
57       * @param promise the promise for the write.
58       * @return the future for the write.
59       * <a href="https://tools.ietf.org/html/rfc7540#section-10.5.1">Section 10.5.1</a> states the following:
60       * <pre>
61       * The header block MUST be processed to ensure a consistent connection state, unless the connection is closed.
62       * </pre>
63       * If this call has modified the HPACK header state you <strong>MUST</strong> throw a connection error.
64       * <p>
65       * If this call has <strong>NOT</strong> modified the HPACK header state you are free to throw a stream error.
66       */
67      ChannelFuture writeHeaders(ChannelHandlerContext ctx, int streamId, Http2Headers headers,
68                                 int padding, boolean endStream, ChannelPromise promise);
69  
70      /**
71       * Writes a HEADERS frame with priority specified to the remote endpoint.
72       *
73       * @param ctx the context to use for writing.
74       * @param streamId the stream for which to send the frame.
75       * @param headers the headers to be sent.
76       * @param streamDependency the stream on which this stream should depend, or 0 if it should
77       *            depend on the connection.
78       * @param weight the weight for this stream.
79       * @param exclusive whether this stream should be the exclusive dependant of its parent.
80       * @param padding additional bytes that should be added to obscure the true content size. Must be between 0 and
81       *                256 (inclusive).
82       * @param endStream indicates if this is the last frame to be sent for the stream.
83       * @param promise the promise for the write.
84       * @return the future for the write.
85       * <a href="https://tools.ietf.org/html/rfc7540#section-10.5.1">Section 10.5.1</a> states the following:
86       * <pre>
87       * The header block MUST be processed to ensure a consistent connection state, unless the connection is closed.
88       * </pre>
89       * If this call has modified the HPACK header state you <strong>MUST</strong> throw a connection error.
90       * <p>
91       * If this call has <strong>NOT</strong> modified the HPACK header state you are free to throw a stream error.
92       */
93      ChannelFuture writeHeaders(ChannelHandlerContext ctx, int streamId, Http2Headers headers,
94                                 int streamDependency, short weight, boolean exclusive, int padding, boolean endStream,
95                                 ChannelPromise promise);
96  
97      /**
98       * Writes a PRIORITY frame to the remote endpoint.
99       *
100      * @param ctx the context to use for writing.
101      * @param streamId the stream for which to send the frame.
102      * @param streamDependency the stream on which this stream should depend, or 0 if it should
103      *            depend on the connection.
104      * @param weight the weight for this stream.
105      * @param exclusive whether this stream should be the exclusive dependant of its parent.
106      * @param promise the promise for the write.
107      * @return the future for the write.
108      */
109     ChannelFuture writePriority(ChannelHandlerContext ctx, int streamId, int streamDependency,
110             short weight, boolean exclusive, ChannelPromise promise);
111 
112     /**
113      * Writes a RST_STREAM frame to the remote endpoint.
114      *
115      * @param ctx the context to use for writing.
116      * @param streamId the stream for which to send the frame.
117      * @param errorCode the error code indicating the nature of the failure.
118      * @param promise the promise for the write.
119      * @return the future for the write.
120      */
121     ChannelFuture writeRstStream(ChannelHandlerContext ctx, int streamId, long errorCode,
122             ChannelPromise promise);
123 
124     /**
125      * Writes a SETTINGS frame to the remote endpoint.
126      *
127      * @param ctx the context to use for writing.
128      * @param settings the settings to be sent.
129      * @param promise the promise for the write.
130      * @return the future for the write.
131      */
132     ChannelFuture writeSettings(ChannelHandlerContext ctx, Http2Settings settings,
133             ChannelPromise promise);
134 
135     /**
136      * Writes a SETTINGS acknowledgment to the remote endpoint.
137      *
138      * @param ctx the context to use for writing.
139      * @param promise the promise for the write.
140      * @return the future for the write.
141      */
142     ChannelFuture writeSettingsAck(ChannelHandlerContext ctx, ChannelPromise promise);
143 
144     /**
145      * Writes a PING frame to the remote endpoint.
146      *
147      * @param ctx the context to use for writing.
148      * @param ack indicates whether this is an ack of a PING frame previously received from the
149      *            remote endpoint.
150      * @param data the payload of the frame.
151      * @param promise the promise for the write.
152      * @return the future for the write.
153      */
154     ChannelFuture writePing(ChannelHandlerContext ctx, boolean ack, long data,
155             ChannelPromise promise);
156 
157     /**
158      * Writes a PUSH_PROMISE frame to the remote endpoint.
159      *
160      * @param ctx the context to use for writing.
161      * @param streamId the stream for which to send the frame.
162      * @param promisedStreamId the ID of the promised stream.
163      * @param headers the headers to be sent.
164      * @param padding additional bytes that should be added to obscure the true content size. Must be between 0 and
165      *                256 (inclusive).
166      * @param promise the promise for the write.
167      * @return the future for the write.
168      * <a href="https://tools.ietf.org/html/rfc7540#section-10.5.1">Section 10.5.1</a> states the following:
169      * <pre>
170      * The header block MUST be processed to ensure a consistent connection state, unless the connection is closed.
171      * </pre>
172      * If this call has modified the HPACK header state you <strong>MUST</strong> throw a connection error.
173      * <p>
174      * If this call has <strong>NOT</strong> modified the HPACK header state you are free to throw a stream error.
175      */
176     ChannelFuture writePushPromise(ChannelHandlerContext ctx, int streamId, int promisedStreamId,
177                                    Http2Headers headers, int padding, ChannelPromise promise);
178 
179     /**
180      * Writes a GO_AWAY frame to the remote endpoint.
181      *
182      * @param ctx the context to use for writing.
183      * @param lastStreamId the last known stream of this endpoint.
184      * @param errorCode the error code, if the connection was abnormally terminated.
185      * @param debugData application-defined debug data. This will be released by this method.
186      * @param promise the promise for the write.
187      * @return the future for the write.
188      */
189     ChannelFuture writeGoAway(ChannelHandlerContext ctx, int lastStreamId, long errorCode,
190             ByteBuf debugData, ChannelPromise promise);
191 
192     /**
193      * Writes a WINDOW_UPDATE frame to the remote endpoint.
194      *
195      * @param ctx the context to use for writing.
196      * @param streamId the stream for which to send the frame.
197      * @param windowSizeIncrement the number of bytes by which the local inbound flow control window
198      *            is increasing.
199      * @param promise the promise for the write.
200      * @return the future for the write.
201      */
202     ChannelFuture writeWindowUpdate(ChannelHandlerContext ctx, int streamId,
203             int windowSizeIncrement, ChannelPromise promise);
204 
205     /**
206      * Generic write method for any HTTP/2 frame. This allows writing of non-standard frames.
207      *
208      * @param ctx the context to use for writing.
209      * @param frameType the frame type identifier.
210      * @param streamId the stream for which to send the frame.
211      * @param flags the flags to write for this frame.
212      * @param payload the payload to write for this frame. This will be released by this method.
213      * @param promise the promise for the write.
214      * @return the future for the write.
215      */
216     ChannelFuture writeFrame(ChannelHandlerContext ctx, byte frameType, int streamId,
217             Http2Flags flags, ByteBuf payload, ChannelPromise promise);
218 
219     /**
220      * Get the configuration related elements for this {@link Http2FrameWriter}
221      */
222     Configuration configuration();
223 
224     /**
225      * Closes this writer and frees any allocated resources.
226      */
227     @Override
228     void close();
229 }