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