| // Copyright (c) 2015, the Dart project authors. Please see the AUTHORS file | |
| // for details. All rights reserved. Use of this source code is governed by a | |
| // BSD-style license that can be found in the LICENSE file. | |
| import 'dart:async'; | |
| import 'dart:io'; | |
| import 'src/connection.dart'; | |
| import 'src/hpack/hpack.dart' show Header; | |
| export 'src/frames/frames.dart' show ErrorCode; | |
| export 'src/hpack/hpack.dart' show Header; | |
| typedef ActiveStateHandler = void Function(bool isActive); | |
| /// Default maximum number of peer-initiated streams per connection. | |
| /// | |
| /// A limit of 100 follows the lower bound recommended by | |
| /// [RFC 9113 section 6.5.2](https://www.rfc-editor.org/rfc/rfc9113.html#section-6.5.2), | |
| /// avoiding an unnecessarily restrictive default while bounding per-stream | |
| /// state. | |
| const int defaultMaxConcurrentStreams = 100; | |
| /// Default maximum compressed size of one inbound HTTP/2 field block. | |
| /// | |
| /// This matches [defaultMaxInboundHeaderListSize]. An HPACK-encoded field | |
| /// block is normally smaller than the decoded size of its field section, | |
| /// which counts 32 bytes of overhead per field, so a field section within | |
| /// [defaultMaxInboundHeaderListSize] also fits within this limit. This matters | |
| /// because exceeding this limit terminates the connection (the rest of the | |
| /// field block cannot be skipped without desynchronizing the HPACK state), | |
| /// whereas exceeding only [defaultMaxInboundHeaderListSize] resets just the | |
| /// affected stream. | |
| const int defaultMaxInboundHeaderBlockSize = defaultMaxInboundHeaderListSize; | |
| /// Default maximum decoded size of one inbound HTTP/2 field section. | |
| /// | |
| /// 256 KiB matches the limit that Chromium/Cronet apply to field sections | |
| /// sent by servers, bounding HPACK amplification before headers reach | |
| /// application code. The field-size accounting follows | |
| /// [RFC 9113 section 6.5.2](https://www.rfc-editor.org/rfc/rfc9113.html#section-6.5.2). | |
| const int defaultMaxInboundHeaderListSize = 256 * 1024; | |
| /// Default absolute time allowed to finish an inbound HTTP/2 field block. | |
| /// | |
| /// Ten seconds allows for ordinary network delay while bounding how long a | |
| /// slow peer can retain field-block and HPACK processing state. | |
| const Duration defaultInboundHeaderBlockTimeout = Duration(seconds: 10); | |
| /// Default maximum number of CONTINUATION frames in one field block. | |
| /// | |
| /// The byte limit alone does not bound floods of empty or very small frames. | |
| /// A [defaultMaxInboundHeaderBlockSize] field block sent in frames of the | |
| /// protocol's initial maximum size (16 KiB, see | |
| /// [RFC 9113 section 4.1](https://www.rfc-editor.org/rfc/rfc9113.html#section-4.1)) | |
| /// needs up to 16 CONTINUATION frames. 64 still permits such a block to be | |
| /// split into fragments averaging about 4 KiB while placing a finite bound on | |
| /// per-frame processing, addressing the class of issue described by | |
| /// [CERT VU#421644](https://kb.cert.org/vuls/id/421644). | |
| const int defaultMaxContinuationFramesPerBlock = 64; | |
| /// Default number of consecutive peer stream-limit violations before GOAWAY. | |
| /// | |
| /// Once the peer has acknowledged the advertised stream limit, eight tolerates | |
| /// a short burst of racing streams while still terminating a peer that | |
| /// repeatedly ignores the limit. Accepting a peer stream resets the violation | |
| /// count. | |
| const int defaultMaxPeerStreamLimitViolations = 8; | |
| /// Settings for a [TransportConnection]. | |
| abstract class Settings { | |
| /// The maximum number of concurrent streams the remote end can open | |
| /// (defaults to [defaultMaxConcurrentStreams]). | |
| /// | |
| /// This limit is advertised and enforced locally. Set to `null` to make the | |
| /// number of peer-initiated streams unlimited. Reserved peer streams are | |
| /// included in the local allocation guard even though the HTTP/2 setting | |
| /// counts only open and half-closed streams. | |
| final int? concurrentStreamLimit; | |
| /// The default stream window size the remote peer can use when creating new | |
| /// streams (defaults to 65535 bytes). | |
| /// | |
| /// It is sent in this end's initial SETTINGS. A value above 65535 applies | |
| /// to this end's receive windows from then on, without waiting for the | |
| /// peer's acknowledgement; a smaller one applies once acknowledged. | |
| /// | |
| /// From 2 * 65535 bytes on, received data is acknowledged once per half | |
| /// window rather than once per DATA frame (also for | |
| /// [connectionWindowSize]). | |
| final int? streamWindowSize; | |
| /// The connection-level window the remote peer can use (defaults to 65535 | |
| /// bytes; must be between 65535 and 2147483647). | |
| /// | |
| /// HTTP/2 has no setting for the connection window; a larger value is | |
| /// granted by a WINDOW_UPDATE on stream 0 right after the initial SETTINGS. | |
| /// With the default, one connection moves at most 64 KiB per round trip | |
| /// however large [streamWindowSize] is. | |
| final int? connectionWindowSize; | |
| /// The largest frame payload this end accepts, sent as | |
| /// SETTINGS_MAX_FRAME_SIZE (defaults to 16384 bytes; must be between 16384 | |
| /// and 16777215). | |
| /// | |
| /// Like [streamWindowSize], it applies from the initial SETTINGS on. | |
| final int? maxFrameSize; | |
| /// Maximum compressed bytes retained for one inbound field block. | |
| /// | |
| /// This is a local enforcement limit and is not advertised to the peer. | |
| /// Set to `null` to disable the limit. | |
| final int? maxInboundHeaderBlockSize; | |
| /// Maximum decoded size of one inbound field section. | |
| /// | |
| /// The size is the sum of `name.length + value.length + 32` for every field. | |
| /// This value is both advertised with SETTINGS_MAX_HEADER_LIST_SIZE and | |
| /// enforced locally. Set to `null` to disable both behaviors. | |
| final int? maxInboundHeaderListSize; | |
| /// Absolute time allowed to receive a complete inbound field block. | |
| /// | |
| /// The timer starts as soon as the initial HEADERS or PUSH_PROMISE frame | |
| /// header is parsed, before its payload is buffered. It is not extended by | |
| /// CONTINUATION frames and ends only after the final frame is fully read. | |
| /// Set to `null` to disable the timeout. | |
| final Duration? inboundHeaderBlockTimeout; | |
| /// Maximum number of CONTINUATION frames accepted for one field block. | |
| /// | |
| /// Set to `null` to disable the frame-count limit. | |
| final int? maxContinuationFramesPerBlock; | |
| /// Consecutive peer stream-limit violations allowed before terminating the | |
| /// connection with ENHANCE_YOUR_CALM. | |
| /// | |
| /// Individual violations are rejected with REFUSED_STREAM. The counter is | |
| /// incremented only after the peer acknowledges the advertised stream limit | |
| /// and is reset after a peer-initiated stream is accepted. Set to `null` to | |
| /// never terminate the connection based only on this violation count. | |
| final int? maxPeerStreamLimitViolations; | |
| const Settings({ | |
| this.concurrentStreamLimit, | |
| this.streamWindowSize, | |
| this.connectionWindowSize, | |
| this.maxFrameSize, | |
| this.maxInboundHeaderBlockSize, | |
| this.maxInboundHeaderListSize, | |
| this.inboundHeaderBlockTimeout, | |
| this.maxContinuationFramesPerBlock, | |
| this.maxPeerStreamLimitViolations, | |
| }); | |
| } | |
| /// Settings for a [TransportConnection] a server can make. | |
| class ServerSettings extends Settings { | |
| const ServerSettings({ | |
| super.concurrentStreamLimit = defaultMaxConcurrentStreams, | |
| super.streamWindowSize, | |
| super.connectionWindowSize, | |
| super.maxFrameSize, | |
| super.maxInboundHeaderBlockSize = defaultMaxInboundHeaderBlockSize, | |
| super.maxInboundHeaderListSize = defaultMaxInboundHeaderListSize, | |
| super.inboundHeaderBlockTimeout = defaultInboundHeaderBlockTimeout, | |
| super.maxContinuationFramesPerBlock = defaultMaxContinuationFramesPerBlock, | |
| super.maxPeerStreamLimitViolations = defaultMaxPeerStreamLimitViolations, | |
| }); | |
| } | |
| /// Settings for a [TransportConnection] a client can make. | |
| class ClientSettings extends Settings { | |
| /// Whether the client allows pushes from the server (defaults to false). | |
| final bool allowServerPushes; | |
| const ClientSettings({ | |
| super.concurrentStreamLimit = defaultMaxConcurrentStreams, | |
| super.streamWindowSize, | |
| super.connectionWindowSize, | |
| super.maxFrameSize, | |
| super.maxInboundHeaderBlockSize = defaultMaxInboundHeaderBlockSize, | |
| super.maxInboundHeaderListSize = defaultMaxInboundHeaderListSize, | |
| super.inboundHeaderBlockTimeout = defaultInboundHeaderBlockTimeout, | |
| super.maxContinuationFramesPerBlock = defaultMaxContinuationFramesPerBlock, | |
| super.maxPeerStreamLimitViolations = defaultMaxPeerStreamLimitViolations, | |
| this.allowServerPushes = false, | |
| }); | |
| } | |
| /// Represents a HTTP/2 connection. | |
| abstract class TransportConnection { | |
| /// Pings the other end. | |
| Future ping(); | |
| /// Sets the active state callback. | |
| /// | |
| /// This callback is invoked with `true` when the number of active streams | |
| /// goes from 0 to 1 (the connection goes from idle to active), and with | |
| /// `false` when the number of active streams becomes 0 (the connection goes | |
| /// from active to idle). | |
| set onActiveStateChanged(ActiveStateHandler callback); | |
| /// Future which completes when the first SETTINGS frame is received from | |
| /// the peer. | |
| Future<void> get onInitialPeerSettingsReceived; | |
| /// Stream which emits an event with the ping id every time a ping is received | |
| /// on this connection. | |
| Stream<int> get onPingReceived; | |
| /// Stream which emits an event every time a ping is received on this | |
| /// connection. | |
| Stream<void> get onFrameReceived; | |
| /// Finish this connection. | |
| /// | |
| /// No new streams will be accepted or can be created. | |
| Future finish(); | |
| /// Terminates this connection forcefully. | |
| Future terminate([int? errorCode, String? message]); | |
| } | |
| abstract class ClientTransportConnection extends TransportConnection { | |
| factory ClientTransportConnection.viaSocket( | |
| Socket socket, { | |
| ClientSettings? settings, | |
| }) => | |
| ClientTransportConnection.viaStreams(socket, socket, settings: settings); | |
| factory ClientTransportConnection.viaStreams( | |
| Stream<List<int>> incoming, | |
| StreamSink<List<int>> outgoing, { | |
| ClientSettings? settings, | |
| }) { | |
| settings ??= const ClientSettings(); | |
| return ClientConnection(incoming, outgoing, settings); | |
| } | |
| /// Whether this connection is open and can be used to make new requests | |
| /// via [makeRequest]. | |
| bool get isOpen; | |
| /// The maximum number of concurrent streams the peer currently allows, per | |
| /// its most recent SETTINGS_MAX_CONCURRENT_STREAMS (RFC 7540 6.5.2), or | |
| /// `null` if the peer hasn't advertised a limit. | |
| /// | |
| /// This is only known once the peer's initial SETTINGS frame has arrived - | |
| /// see [onInitialPeerSettingsReceived]. | |
| int? get peerMaxConcurrentStreams; | |
| /// Creates a new outgoing stream. | |
| ClientTransportStream makeRequest( | |
| List<Header> headers, { | |
| bool endStream = false, | |
| }); | |
| } | |
| abstract class ServerTransportConnection extends TransportConnection { | |
| factory ServerTransportConnection.viaSocket( | |
| Socket socket, { | |
| ServerSettings? settings, | |
| }) { | |
| return ServerTransportConnection.viaStreams( | |
| socket, | |
| socket, | |
| settings: settings, | |
| ); | |
| } | |
| factory ServerTransportConnection.viaStreams( | |
| Stream<List<int>> incoming, | |
| StreamSink<List<int>> outgoing, { | |
| ServerSettings? settings = const ServerSettings(), | |
| }) { | |
| settings ??= const ServerSettings(); | |
| return ServerConnection(incoming, outgoing, settings); | |
| } | |
| /// Incoming HTTP/2 streams. | |
| Stream<ServerTransportStream> get incomingStreams; | |
| } | |
| /// Represents a HTTP/2 stream. | |
| abstract class TransportStream { | |
| /// The id of this stream. | |
| /// | |
| /// * odd numbered streams are client streams | |
| /// * even numbered streams are opened from the server | |
| int get id; | |
| /// A stream of data and/or headers from the remote end. | |
| Stream<StreamMessage> get incomingMessages; | |
| /// A sink for writing data and/or headers to the remote end. | |
| StreamSink<StreamMessage> get outgoingMessages; | |
| /// Sets the termination handler on this stream. | |
| /// | |
| /// The handler will be called if the stream receives an RST_STREAM frame. | |
| set onTerminated(void Function(int?) value); | |
| /// Terminates this HTTP/2 stream in an un-normal way. | |
| /// | |
| /// For normal termination, one can cancel the [StreamSubscription] from | |
| /// `incoming.listen()` and close the `outgoing` [StreamSink]. | |
| /// | |
| /// Terminating this HTTP/2 stream will free up all resources associated with | |
| /// it locally and will notify the remote end that this stream is no longer | |
| /// used. | |
| void terminate(); | |
| // For convenience only. | |
| void sendHeaders(List<Header> headers, {bool endStream = false}) { | |
| outgoingMessages.add(HeadersStreamMessage(headers, endStream: endStream)); | |
| if (endStream) outgoingMessages.close(); | |
| } | |
| void sendData(List<int> bytes, {bool endStream = false}) { | |
| outgoingMessages.add(DataStreamMessage(bytes, endStream: endStream)); | |
| if (endStream) outgoingMessages.close(); | |
| } | |
| } | |
| abstract class ClientTransportStream extends TransportStream { | |
| /// Streams which the remote end pushed to this endpoint. | |
| /// | |
| /// If peer pushes were enabled, the client is responsible to either | |
| /// handle or reject any peer push. | |
| Stream<TransportStreamPush> get peerPushes; | |
| } | |
| abstract class ServerTransportStream extends TransportStream { | |
| /// Whether a method to [push] will succeed. Requirements for this getter to | |
| /// return `true` are: | |
| /// * this stream must be in the Open or HalfClosedRemote state | |
| /// * the client needs to have the "enable push" settings enabled | |
| /// * the number of active streams has not reached the maximum | |
| bool get canPush; | |
| /// Pushes a new stream to the remote peer. | |
| ServerTransportStream push(List<Header> requestHeaders); | |
| } | |
| /// Represents a message which can be sent over a HTTP/2 stream. | |
| abstract class StreamMessage { | |
| final bool endStream; | |
| StreamMessage({bool? endStream}) : endStream = endStream ?? false; | |
| } | |
| /// Represents a data message which can be sent over a HTTP/2 stream. | |
| class DataStreamMessage extends StreamMessage { | |
| final List<int> bytes; | |
| DataStreamMessage(this.bytes, {super.endStream}); | |
| @override | |
| String toString() => 'DataStreamMessage(${bytes.length} bytes)'; | |
| } | |
| /// Represents a headers message which can be sent over a HTTP/2 stream. | |
| class HeadersStreamMessage extends StreamMessage { | |
| final List<Header> headers; | |
| HeadersStreamMessage(this.headers, {super.endStream}); | |
| @override | |
| String toString() => 'HeadersStreamMessage(${headers.length} headers)'; | |
| } | |
| /// Represents a remote stream push. | |
| class TransportStreamPush { | |
| /// The request headers which [stream] is the response to. | |
| final List<Header> requestHeaders; | |
| /// The remote stream push. | |
| final ClientTransportStream stream; | |
| TransportStreamPush(this.requestHeaders, this.stream); | |
| @override | |
| String toString() => | |
| 'TransportStreamPush(${requestHeaders.length} request headers headers)'; | |
| } | |
| /// An exception thrown by the HTTP/2 implementation. | |
| class TransportException implements Exception { | |
| final String message; | |
| TransportException(this.message); | |
| @override | |
| String toString() => 'HTTP/2 error: $message'; | |
| } | |
| /// An exception thrown when a HTTP/2 connection error occurred. | |
| class TransportConnectionException extends TransportException { | |
| final int errorCode; | |
| TransportConnectionException(this.errorCode, String details) | |
| : super('Connection error: $details (errorCode: $errorCode)'); | |
| } | |
| /// An exception thrown when a HTTP/2 stream error occured. | |
| class StreamTransportException extends TransportException { | |
| StreamTransportException(String details) : super('Stream error: $details'); | |
| } |