2015-01-20 01:48:11 +01:00
|
|
|
/*
|
|
|
|
* Copyright 2014 The Netty Project
|
|
|
|
*
|
|
|
|
* The Netty Project licenses this file to you under the Apache License, version 2.0 (the
|
|
|
|
* "License"); you may not use this file except in compliance with the License. You may obtain a
|
|
|
|
* copy of the License at:
|
|
|
|
*
|
|
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
*
|
|
|
|
* Unless required by applicable law or agreed to in writing, software distributed under the License
|
|
|
|
* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
|
|
|
|
* or implied. See the License for the specific language governing permissions and limitations under
|
|
|
|
* the License.
|
|
|
|
*/
|
|
|
|
|
|
|
|
package io.netty.handler.codec.http2;
|
|
|
|
|
2015-03-20 18:04:38 +01:00
|
|
|
import io.netty.buffer.ByteBuf;
|
|
|
|
|
2015-01-20 01:48:11 +01:00
|
|
|
/**
|
|
|
|
* Manager for the state of an HTTP/2 connection with the remote end-point.
|
|
|
|
*/
|
|
|
|
public interface Http2Connection {
|
|
|
|
/**
|
|
|
|
* Listener for life-cycle events for streams in this connection.
|
|
|
|
*/
|
|
|
|
interface Listener {
|
|
|
|
/**
|
|
|
|
* Notifies the listener that the given stream was added to the connection. This stream may
|
2015-03-15 02:38:35 +01:00
|
|
|
* not yet be active (i.e. {@code OPEN} or {@code HALF CLOSED}).
|
2015-04-09 21:30:16 +02:00
|
|
|
* <p>
|
|
|
|
* If a {@link RuntimeException} is thrown it will be logged and <strong>not propagated</strong>.
|
|
|
|
* Throwing from this method is not supported and is considered a programming error.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
2015-03-20 18:04:38 +01:00
|
|
|
void onStreamAdded(Http2Stream stream);
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
2015-03-15 02:38:35 +01:00
|
|
|
* Notifies the listener that the given stream was made active (i.e. {@code OPEN} or {@code HALF CLOSED}).
|
2015-04-09 21:30:16 +02:00
|
|
|
* <p>
|
|
|
|
* If a {@link RuntimeException} is thrown it will be logged and <strong>not propagated</strong>.
|
|
|
|
* Throwing from this method is not supported and is considered a programming error.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
2015-03-20 18:04:38 +01:00
|
|
|
void onStreamActive(Http2Stream stream);
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
2015-03-15 02:38:35 +01:00
|
|
|
* Notifies the listener that the given stream is now {@code HALF CLOSED}. The stream can be
|
|
|
|
* inspected to determine which side is {@code CLOSED}.
|
2015-04-09 21:30:16 +02:00
|
|
|
* <p>
|
|
|
|
* If a {@link RuntimeException} is thrown it will be logged and <strong>not propagated</strong>.
|
|
|
|
* Throwing from this method is not supported and is considered a programming error.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
2015-03-20 18:04:38 +01:00
|
|
|
void onStreamHalfClosed(Http2Stream stream);
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
2015-03-15 02:38:35 +01:00
|
|
|
* Notifies the listener that the given stream is now {@code CLOSED} in both directions and will no longer
|
2015-04-09 18:48:58 +02:00
|
|
|
* be accessible via {@link #forEachActiveStream(Http2StreamVisitor)}.
|
2015-04-09 21:30:16 +02:00
|
|
|
* <p>
|
|
|
|
* If a {@link RuntimeException} is thrown it will be logged and <strong>not propagated</strong>.
|
|
|
|
* Throwing from this method is not supported and is considered a programming error.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
2015-03-20 18:04:38 +01:00
|
|
|
void onStreamClosed(Http2Stream stream);
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Notifies the listener that the given stream has now been removed from the connection and
|
|
|
|
* will no longer be returned via {@link Http2Connection#stream(int)}. The connection may
|
|
|
|
* maintain inactive streams for some time before removing them.
|
2015-04-09 21:30:16 +02:00
|
|
|
* <p>
|
|
|
|
* If a {@link RuntimeException} is thrown it will be logged and <strong>not propagated</strong>.
|
|
|
|
* Throwing from this method is not supported and is considered a programming error.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
2015-03-20 18:04:38 +01:00
|
|
|
void onStreamRemoved(Http2Stream stream);
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Notifies the listener that a priority tree parent change has occurred. This method will be invoked
|
|
|
|
* in a top down order relative to the priority tree. This method will also be invoked after all tree
|
|
|
|
* structure changes have been made and the tree is in steady state relative to the priority change
|
|
|
|
* which caused the tree structure to change.
|
2015-04-09 21:30:16 +02:00
|
|
|
* <p>
|
|
|
|
* If a {@link RuntimeException} is thrown it will be logged and <strong>not propagated</strong>.
|
|
|
|
* Throwing from this method is not supported and is considered a programming error.
|
2015-01-20 01:48:11 +01:00
|
|
|
* @param stream The stream which had a parent change (new parent and children will be steady state)
|
|
|
|
* @param oldParent The old parent which {@code stream} used to be a child of (may be {@code null})
|
|
|
|
*/
|
2015-03-20 18:04:38 +01:00
|
|
|
void onPriorityTreeParentChanged(Http2Stream stream, Http2Stream oldParent);
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Notifies the listener that a parent dependency is about to change
|
|
|
|
* This is called while the tree is being restructured and so the tree
|
|
|
|
* structure is not necessarily steady state.
|
2015-04-09 21:30:16 +02:00
|
|
|
* <p>
|
|
|
|
* If a {@link RuntimeException} is thrown it will be logged and <strong>not propagated</strong>.
|
|
|
|
* Throwing from this method is not supported and is considered a programming error.
|
2015-01-20 01:48:11 +01:00
|
|
|
* @param stream The stream which the parent is about to change to {@code newParent}
|
|
|
|
* @param newParent The stream which will be the parent of {@code stream}
|
|
|
|
*/
|
2015-03-20 18:04:38 +01:00
|
|
|
void onPriorityTreeParentChanging(Http2Stream stream, Http2Stream newParent);
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
2015-04-09 21:30:16 +02:00
|
|
|
* Notifies the listener that the weight has changed for {@code stream}.
|
|
|
|
* <p>
|
|
|
|
* If a {@link RuntimeException} is thrown it will be logged and <strong>not propagated</strong>.
|
|
|
|
* Throwing from this method is not supported and is considered a programming error.
|
2015-01-20 01:48:11 +01:00
|
|
|
* @param stream The stream which the weight has changed
|
|
|
|
* @param oldWeight The old weight for {@code stream}
|
|
|
|
*/
|
|
|
|
void onWeightChanged(Http2Stream stream, short oldWeight);
|
|
|
|
|
|
|
|
/**
|
2015-03-20 18:04:38 +01:00
|
|
|
* Called when a {@code GOAWAY} frame was sent for the connection.
|
2015-04-09 21:30:16 +02:00
|
|
|
* <p>
|
|
|
|
* If a {@link RuntimeException} is thrown it will be logged and <strong>not propagated</strong>.
|
|
|
|
* Throwing from this method is not supported and is considered a programming error.
|
2015-03-20 18:04:38 +01:00
|
|
|
* @param lastStreamId the last known stream of the remote endpoint.
|
|
|
|
* @param errorCode the error code, if abnormal closure.
|
|
|
|
* @param debugData application-defined debug data.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
2015-03-20 18:04:38 +01:00
|
|
|
void onGoAwaySent(int lastStreamId, long errorCode, ByteBuf debugData);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Called when a {@code GOAWAY} was received from the remote endpoint. This event handler duplicates {@link
|
|
|
|
* Http2FrameListener#onGoAwayRead(io.netty.channel.ChannelHandlerContext, int, long, io.netty.buffer.ByteBuf)}
|
|
|
|
* but is added here in order to simplify application logic for handling {@code GOAWAY} in a uniform way. An
|
2015-03-20 02:36:24 +01:00
|
|
|
* application should generally not handle both events, but if it does this method is called second, after
|
2015-03-20 18:04:38 +01:00
|
|
|
* notifying the {@link Http2FrameListener}.
|
2015-04-09 21:30:16 +02:00
|
|
|
* <p>
|
|
|
|
* If a {@link RuntimeException} is thrown it will be logged and <strong>not propagated</strong>.
|
|
|
|
* Throwing from this method is not supported and is considered a programming error.
|
2015-03-20 18:04:38 +01:00
|
|
|
* @param lastStreamId the last known stream of the remote endpoint.
|
|
|
|
* @param errorCode the error code, if abnormal closure.
|
|
|
|
* @param debugData application-defined debug data.
|
|
|
|
*/
|
|
|
|
void onGoAwayReceived(int lastStreamId, long errorCode, ByteBuf debugData);
|
2015-01-20 01:48:11 +01:00
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* A view of the connection from one endpoint (local or remote).
|
|
|
|
*/
|
|
|
|
interface Endpoint<F extends Http2FlowController> {
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the next valid streamId for this endpoint. If negative, the stream IDs are
|
|
|
|
* exhausted for this endpoint an no further streams may be created.
|
|
|
|
*/
|
|
|
|
int nextStreamId();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Indicates whether the given streamId is from the set of IDs used by this endpoint to
|
|
|
|
* create new streams.
|
|
|
|
*/
|
|
|
|
boolean createdStreamId(int streamId);
|
|
|
|
|
|
|
|
/**
|
2015-03-15 02:38:35 +01:00
|
|
|
* Indicates whether or not this endpoint is currently allowed to create new streams. This will be
|
|
|
|
* be false if {@link #numActiveStreams()} + 1 >= {@link #maxActiveStreams()} or if the stream IDs
|
2015-01-20 01:48:11 +01:00
|
|
|
* for this endpoint have been exhausted (i.e. {@link #nextStreamId()} < 0).
|
|
|
|
*/
|
2015-03-15 02:38:35 +01:00
|
|
|
boolean canCreateStream();
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Creates a stream initiated by this endpoint. This could fail for the following reasons:
|
|
|
|
* <ul>
|
|
|
|
* <li>The requested stream ID is not the next sequential ID for this endpoint.</li>
|
|
|
|
* <li>The stream already exists.</li>
|
2015-03-15 02:38:35 +01:00
|
|
|
* <li>{@link #canCreateStream()} is {@code false}.</li>
|
2015-01-20 01:48:11 +01:00
|
|
|
* <li>The connection is marked as going away.</li>
|
|
|
|
* </ul>
|
|
|
|
* <p>
|
2015-02-02 19:20:56 +01:00
|
|
|
* The caller is expected to {@link Http2Stream#open(boolean)} the stream.
|
2015-01-20 01:48:11 +01:00
|
|
|
* @param streamId The ID of the stream
|
|
|
|
* @see Http2Stream#open(boolean)
|
|
|
|
*/
|
|
|
|
Http2Stream createStream(int streamId) throws Http2Exception;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Creates a push stream in the reserved state for this endpoint and notifies all listeners.
|
|
|
|
* This could fail for the following reasons:
|
|
|
|
* <ul>
|
|
|
|
* <li>Server push is not allowed to the opposite endpoint.</li>
|
|
|
|
* <li>The requested stream ID is not the next sequential stream ID for this endpoint.</li>
|
|
|
|
* <li>The number of concurrent streams is above the allowed threshold for this endpoint.</li>
|
|
|
|
* <li>The connection is marked as going away.</li>
|
2015-03-15 02:38:35 +01:00
|
|
|
* <li>The parent stream ID does not exist or is not {@code OPEN} from the side sending the push
|
2015-01-20 01:48:11 +01:00
|
|
|
* promise.</li>
|
|
|
|
* <li>Could not set a valid priority for the new stream.</li>
|
|
|
|
* </ul>
|
|
|
|
*
|
|
|
|
* @param streamId the ID of the push stream
|
|
|
|
* @param parent the parent stream used to initiate the push stream.
|
|
|
|
*/
|
|
|
|
Http2Stream reservePushStream(int streamId, Http2Stream parent) throws Http2Exception;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Indicates whether or not this endpoint is the server-side of the connection.
|
|
|
|
*/
|
|
|
|
boolean isServer();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets whether server push is allowed to this endpoint.
|
|
|
|
*/
|
|
|
|
void allowPushTo(boolean allow);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets whether or not server push is allowed to this endpoint. This is always false
|
|
|
|
* for a server endpoint.
|
|
|
|
*/
|
|
|
|
boolean allowPushTo();
|
|
|
|
|
|
|
|
/**
|
2015-03-15 02:38:35 +01:00
|
|
|
* Gets the number of active streams (i.e. {@code OPEN} or {@code HALF CLOSED}) that were created by this
|
|
|
|
* endpoint.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
|
|
|
int numActiveStreams();
|
|
|
|
|
|
|
|
/**
|
2015-03-15 02:38:35 +01:00
|
|
|
* Gets the maximum number of streams (created by this endpoint) that are allowed to be active at
|
|
|
|
* the same time. This is the {@code SETTINGS_MAX_CONCURRENT_STREAMS} value sent from the opposite endpoint to
|
|
|
|
* restrict stream creation by this endpoint.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
2015-03-15 02:38:35 +01:00
|
|
|
int maxActiveStreams();
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
2015-03-15 02:38:35 +01:00
|
|
|
* Sets the maximum number of streams (created by this endpoint) that are allowed to be active at once.
|
|
|
|
* This is the {@code SETTINGS_MAX_CONCURRENT_STREAMS} value sent from the opposite endpoint to
|
|
|
|
* restrict stream creation by this endpoint.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
2015-03-15 02:38:35 +01:00
|
|
|
void maxActiveStreams(int maxActiveStreams);
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the ID of the stream last successfully created by this endpoint.
|
|
|
|
*/
|
|
|
|
int lastStreamCreated();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* If a GOAWAY was received for this endpoint, this will be the last stream ID from the
|
2015-03-20 02:36:24 +01:00
|
|
|
* GOAWAY frame. Otherwise, this will be {@code -1}.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
|
|
|
int lastKnownStream();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the flow controller for this endpoint.
|
|
|
|
*/
|
|
|
|
F flowController();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets the flow controller for this endpoint.
|
|
|
|
*/
|
|
|
|
void flowController(F flowController);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the {@link Endpoint} opposite this one.
|
|
|
|
*/
|
|
|
|
Endpoint<? extends Http2FlowController> opposite();
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
2015-04-03 05:28:28 +02:00
|
|
|
* Adds a listener of stream life-cycle events.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
|
|
|
void addListener(Listener listener);
|
|
|
|
|
|
|
|
/**
|
2015-04-03 05:28:28 +02:00
|
|
|
* Removes a listener of stream life-cycle events. If the same listener was added multiple times
|
|
|
|
* then only the first occurence gets removed.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
|
|
|
void removeListener(Listener listener);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Attempts to get the stream for the given ID. If it doesn't exist, throws.
|
|
|
|
*/
|
|
|
|
Http2Stream requireStream(int streamId) throws Http2Exception;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the stream if it exists. If not, returns {@code null}.
|
|
|
|
*/
|
|
|
|
Http2Stream stream(int streamId);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the stream object representing the connection, itself (i.e. stream zero). This object
|
|
|
|
* always exists.
|
|
|
|
*/
|
|
|
|
Http2Stream connectionStream();
|
|
|
|
|
|
|
|
/**
|
2015-03-15 02:38:35 +01:00
|
|
|
* Gets the number of streams that are actively in use (i.e. {@code OPEN} or {@code HALF CLOSED}).
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
|
|
|
int numActiveStreams();
|
|
|
|
|
|
|
|
/**
|
2015-03-28 21:32:19 +01:00
|
|
|
* Provide a means of iterating over the collection of active streams.
|
|
|
|
*
|
|
|
|
* @param visitor The visitor which will visit each active stream.
|
|
|
|
* @return The stream before iteration stopped or {@code null} if iteration went past the end.
|
|
|
|
*/
|
2015-04-09 18:48:58 +02:00
|
|
|
Http2Stream forEachActiveStream(Http2StreamVisitor visitor) throws Http2Exception;
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Indicates whether or not the local endpoint for this connection is the server.
|
|
|
|
*/
|
|
|
|
boolean isServer();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets a view of this connection from the local {@link Endpoint}.
|
|
|
|
*/
|
|
|
|
Endpoint<Http2LocalFlowController> local();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets a view of this connection from the remote {@link Endpoint}.
|
|
|
|
*/
|
|
|
|
Endpoint<Http2RemoteFlowController> remote();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Indicates whether or not a {@code GOAWAY} was received from the remote endpoint.
|
|
|
|
*/
|
|
|
|
boolean goAwayReceived();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Indicates that a {@code GOAWAY} was received from the remote endpoint and sets the last known stream.
|
|
|
|
*/
|
2015-03-20 18:04:38 +01:00
|
|
|
void goAwayReceived(int lastKnownStream, long errorCode, ByteBuf message);
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Indicates whether or not a {@code GOAWAY} was sent to the remote endpoint.
|
|
|
|
*/
|
|
|
|
boolean goAwaySent();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Indicates that a {@code GOAWAY} was sent to the remote endpoint and sets the last known stream.
|
|
|
|
*/
|
2015-03-20 18:04:38 +01:00
|
|
|
void goAwaySent(int lastKnownStream, long errorCode, ByteBuf message);
|
2015-01-20 01:48:11 +01:00
|
|
|
}
|