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.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 }