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 package io.netty5.handler.codec.http2;
16
17 import io.netty5.buffer.api.Buffer;
18 import io.netty5.channel.ChannelHandlerContext;
19 import io.netty5.util.concurrent.Future;
20 import io.netty5.util.concurrent.Promise;
21 import io.netty5.util.internal.UnstableApi;
22
23 /**
24 * Manager for the life cycle of the HTTP/2 connection. Handles graceful shutdown of the channel,
25 * closing only after all of the streams have closed.
26 */
27 @UnstableApi
28 public interface Http2LifecycleManager {
29
30 /**
31 * Closes the local side of the {@code stream}. Depending on the {@code stream} state this may result in
32 * {@code stream} being closed. See {@link #closeStream(Http2Stream, Future)}.
33 * @param stream the stream to be half closed.
34 * @param future See {@link #closeStream(Http2Stream, Future)}.
35 */
36 void closeStreamLocal(Http2Stream stream, Future<Void> future);
37
38 /**
39 * Closes the remote side of the {@code stream}. Depending on the {@code stream} state this may result in
40 * {@code stream} being closed. See {@link #closeStream(Http2Stream, Future)}.
41 * @param stream the stream to be half closed.
42 * @param future See {@link #closeStream(Http2Stream, Future)}.
43 */
44 void closeStreamRemote(Http2Stream stream, Future<Void> future);
45
46 /**
47 * Closes and deactivates the given {@code stream}. A listener is also attached to {@code future} and upon
48 * completion the underlying channel will be closed if {@link Http2Connection#numActiveStreams()} is 0.
49 * @param stream the stream to be closed and deactivated.
50 * @param future when completed if {@link Http2Connection#numActiveStreams()} is 0 then the underlying channel
51 * will be closed.
52 */
53 void closeStream(Http2Stream stream, Future<Void> future);
54
55 /**
56 * Ensure the stream identified by {@code streamId} is reset. If our local state does not indicate the stream has
57 * been reset yet then a {@code RST_STREAM} will be sent to the peer. If our local state indicates the stream
58 * has already been reset then the return status will indicate success without sending anything to the peer.
59 * @param ctx The context used for communication and buffer allocation if necessary.
60 * @param streamId The identifier of the stream to reset.
61 * @param errorCode Justification as to why this stream is being reset. See {@link Http2Error}.
62 * @return Will be considered successful when the connection and stream state has been updated, and a
63 * {@code RST_STREAM} frame has been sent to the peer. If the stream state has already been updated and a
64 * {@code RST_STREAM} frame has been sent then the return status may indicate success immediately.
65 */
66 Future<Void> resetStream(ChannelHandlerContext ctx, int streamId, long errorCode);
67
68 /**
69 * Prevents the peer from creating streams and close the connection if {@code errorCode} is not
70 * {@link Http2Error#NO_ERROR}. After this call the peer is not allowed to create any new streams and the local
71 * endpoint will be limited to creating streams with {@code stream identifier <= lastStreamId}. This may result in
72 * sending a {@code GO_AWAY} frame (assuming we have not already sent one with
73 * {@code Last-Stream-ID <= lastStreamId}), or may just return success if a {@code GO_AWAY} has previously been
74 * sent.
75 * @param ctx The context used for communication and buffer allocation if necessary.
76 * @param lastStreamId The last stream that the local endpoint is claiming it will accept.
77 * @param errorCode The rational as to why the connection is being closed. See {@link Http2Error}.
78 * @param debugData For diagnostic purposes (carries no semantic value).
79 * @return Will be considered successful when the connection and stream state has been updated, and a
80 * {@code GO_AWAY} frame has been sent to the peer. If the stream state has already been updated and a
81 * {@code GO_AWAY} frame has been sent then the return status may indicate success immediately.
82 */
83 Future<Void> goAway(ChannelHandlerContext ctx, int lastStreamId, long errorCode,
84 Buffer debugData);
85
86 /**
87 * Processes the given error.
88 *
89 * @param ctx The context used for communication and buffer allocation if necessary.
90 * @param outbound {@code true} if the error was caused by an outbound operation and so the corresponding
91 * {@link Promise} was failed as well.
92 * @param cause the error.
93 */
94 void onError(ChannelHandlerContext ctx, boolean outbound, Throwable cause);
95 }