Add a frame delegate

Sources/NIOHTTP2/HTTP2ChannelHandler.swift

@@ -113,6 +113,9 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
     /// The maximum number of sequential CONTINUATION frames.
     private let maximumSequentialContinuationFrames: Int
 
+    /// A delegate which is told about frames which have been written.
+    private let frameDelegate: NIOHTTP2FrameDelegate?
+
     @usableFromInline
     internal var inboundStreamMultiplexer: InboundStreamMultiplexer? {
         self.inboundStreamMultiplexerState.multiplexer
@@ -242,7 +245,8 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
             maximumResetFrameCount: 200,
             resetFrameCounterWindow: .seconds(30),
             maximumStreamErrorCount: 200,
-            streamErrorCounterWindow: .seconds(30)
+            streamErrorCounterWindow: .seconds(30),
+            frameDelegate: nil
         )
     }
 
@@ -280,7 +284,8 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
             maximumResetFrameCount: 200,
             resetFrameCounterWindow: .seconds(30),
             maximumStreamErrorCount: 200,
-            streamErrorCounterWindow: .seconds(30)
+            streamErrorCounterWindow: .seconds(30),
+            frameDelegate: nil
         )
 
     }
@@ -295,6 +300,27 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
         mode: ParserMode,
         connectionConfiguration: ConnectionConfiguration = .init(),
         streamConfiguration: StreamConfiguration = .init()
+    ) {
+        self.init(
+            mode: mode,
+            frameDelegate: nil,
+            connectionConfiguration: connectionConfiguration,
+            streamConfiguration: streamConfiguration
+        )
+    }
+
+    /// Constructs a ``NIOHTTP2Handler``.
+    ///
+    /// - Parameters:
+    ///   - mode: The mode for this handler, client or server.
+    ///   - frameDelegate: A delegate which is notified about frames being written.
+    ///   - connectionConfiguration: The settings that will be used when establishing the connection.
+    ///   - streamConfiguration: The settings that will be used when establishing new streams.
+    public convenience init(
+        mode: ParserMode,
+        frameDelegate: NIOHTTP2FrameDelegate?,
+        connectionConfiguration: ConnectionConfiguration = ConnectionConfiguration(),
+        streamConfiguration: StreamConfiguration = StreamConfiguration()
     ) {
         self.init(
             mode: mode,
@@ -310,7 +336,8 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
             maximumResetFrameCount: streamConfiguration.streamResetFrameRateLimit.maximumCount,
             resetFrameCounterWindow: streamConfiguration.streamResetFrameRateLimit.windowLength,
             maximumStreamErrorCount: streamConfiguration.streamErrorRateLimit.maximumCount,
-            streamErrorCounterWindow: streamConfiguration.streamErrorRateLimit.windowLength
+            streamErrorCounterWindow: streamConfiguration.streamErrorRateLimit.windowLength,
+            frameDelegate: frameDelegate
         )
     }
 
@@ -328,7 +355,8 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
         maximumResetFrameCount: Int,
         resetFrameCounterWindow: TimeAmount,
         maximumStreamErrorCount: Int,
-        streamErrorCounterWindow: TimeAmount
+        streamErrorCounterWindow: TimeAmount,
+        frameDelegate: NIOHTTP2FrameDelegate?
     ) {
         self._eventLoop = eventLoop
         self.stateMachine = HTTP2ConnectionStateMachine(
@@ -355,6 +383,7 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
         self.inboundStreamMultiplexerState = .uninitializedLegacy
         self.maximumSequentialContinuationFrames = maximumSequentialContinuationFrames
         self.glitchesMonitor = GlitchesMonitor(maximumGlitches: maximumConnectionGlitches)
+        self.frameDelegate = frameDelegate
     }
 
     /// Constructs a ``NIOHTTP2Handler``.
@@ -391,7 +420,8 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
         resetFrameCounterWindow: TimeAmount = .seconds(30),
         maximumStreamErrorCount: Int = 200,
         streamErrorCounterWindow: TimeAmount = .seconds(30),
-        maximumConnectionGlitches: Int = GlitchesMonitor.defaultMaximumGlitches
+        maximumConnectionGlitches: Int = GlitchesMonitor.defaultMaximumGlitches,
+        frameDelegate: NIOHTTP2FrameDelegate? = nil
     ) {
         self.stateMachine = HTTP2ConnectionStateMachine(
             role: .init(mode),
@@ -418,6 +448,7 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
         self.inboundStreamMultiplexerState = .uninitializedLegacy
         self.maximumSequentialContinuationFrames = maximumSequentialContinuationFrames
         self.glitchesMonitor = GlitchesMonitor(maximumGlitches: maximumConnectionGlitches)
+        self.frameDelegate = frameDelegate
     }
 
     public func handlerAdded(context: ChannelHandlerContext) {
@@ -1067,6 +1098,11 @@ extension NIOHTTP2Handler {
             return
         }
 
+        // Tell the delegate, if there is one.
+        if let delegate = self.frameDelegate {
+            delegate.wroteFrame(frame)
+        }
+
         // Ok, if we got here we're good to send data. We want to attach the promise to the latest write, not
         // always the frame header.
         self.wroteFrame = true
@@ -1391,7 +1427,8 @@ extension NIOHTTP2Handler {
             maximumResetFrameCount: streamConfiguration.streamResetFrameRateLimit.maximumCount,
             resetFrameCounterWindow: streamConfiguration.streamResetFrameRateLimit.windowLength,
             maximumStreamErrorCount: streamConfiguration.streamErrorRateLimit.maximumCount,
-            streamErrorCounterWindow: streamConfiguration.streamErrorRateLimit.windowLength
+            streamErrorCounterWindow: streamConfiguration.streamErrorRateLimit.windowLength,
+            frameDelegate: nil
         )
 
         self.inboundStreamMultiplexerState = .uninitializedInline(
@@ -1408,6 +1445,7 @@ extension NIOHTTP2Handler {
         connectionConfiguration: ConnectionConfiguration = .init(),
         streamConfiguration: StreamConfiguration = .init(),
         streamDelegate: NIOHTTP2StreamDelegate? = nil,
+        frameDelegate: NIOHTTP2FrameDelegate?,
         inboundStreamInitializerWithAnyOutput: @escaping StreamInitializerWithAnyOutput
     ) {
         self.init(
@@ -1424,7 +1462,8 @@ extension NIOHTTP2Handler {
             maximumResetFrameCount: streamConfiguration.streamResetFrameRateLimit.maximumCount,
             resetFrameCounterWindow: streamConfiguration.streamResetFrameRateLimit.windowLength,
             maximumStreamErrorCount: streamConfiguration.streamErrorRateLimit.maximumCount,
-            streamErrorCounterWindow: streamConfiguration.streamErrorRateLimit.windowLength
+            streamErrorCounterWindow: streamConfiguration.streamErrorRateLimit.windowLength,
+            frameDelegate: frameDelegate
         )
         self.inboundStreamMultiplexerState = .uninitializedAsync(
             streamConfiguration,

Sources/NIOHTTP2/HTTP2PipelineHelpers.swift

@@ -866,13 +866,50 @@ extension ChannelPipeline.SynchronousOperations {
         streamDelegate: NIOHTTP2StreamDelegate?,
         configuration: NIOHTTP2Handler.Configuration = NIOHTTP2Handler.Configuration(),
         streamInitializer: @escaping NIOChannelInitializerWithOutput<Output>
+    ) throws -> NIOHTTP2Handler.AsyncStreamMultiplexer<Output> {
+        try self.configureAsyncHTTP2Pipeline(
+            mode: mode,
+            streamDelegate: streamDelegate,
+            frameDelegate: nil,
+            configuration: configuration,
+            streamInitializer: streamInitializer
+        )
+    }
+
+    /// Configures a `ChannelPipeline` to speak HTTP/2 and sets up mapping functions so that it may be interacted with from concurrent code.
+    ///
+    /// This operation **must** be called on the event loop.
+    ///
+    /// In general this is not entirely useful by itself, as HTTP/2 is a negotiated protocol. This helper does not handle negotiation.
+    /// Instead, this simply adds the handler required to speak HTTP/2 after negotiation has completed, or when agreed by prior knowledge.
+    /// Use this function to setup a HTTP/2 pipeline if you wish to use async sequence abstractions over inbound and outbound streams,
+    /// as it allows that pipeline to evolve without breaking your code.
+    ///
+    /// - Parameters:
+    ///   - mode: The mode this pipeline will operate in, server or client.
+    ///   - streamDelegate: A delegate which is called when streams are created and closed.
+    ///   - frameDelegate: A delegate which is called when frames are written to the network.
+    ///   - configuration: The settings that will be used when establishing the connection and new streams.
+    ///   - streamInitializer: A closure that will be called whenever the remote peer initiates a new stream.
+    ///     The output of this closure is the element type of the returned multiplexer
+    /// - Returns: An `EventLoopFuture` containing the `AsyncStreamMultiplexer` inserted into this pipeline, which can
+    /// be used to initiate new streams and iterate over inbound HTTP/2 stream channels.
+    @inlinable
+    @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
+    public func configureAsyncHTTP2Pipeline<Output: Sendable>(
+        mode: NIOHTTP2Handler.ParserMode,
+        streamDelegate: NIOHTTP2StreamDelegate?,
+        frameDelegate: NIOHTTP2FrameDelegate?,
+        configuration: NIOHTTP2Handler.Configuration = NIOHTTP2Handler.Configuration(),
+        streamInitializer: @escaping NIOChannelInitializerWithOutput<Output>
     ) throws -> NIOHTTP2Handler.AsyncStreamMultiplexer<Output> {
         let handler = NIOHTTP2Handler(
             mode: mode,
             eventLoop: self.eventLoop,
             connectionConfiguration: configuration.connection,
             streamConfiguration: configuration.stream,
             streamDelegate: streamDelegate,
+            frameDelegate: frameDelegate,
             inboundStreamInitializerWithAnyOutput: { channel in
                 streamInitializer(channel).map { $0 }
             }

Sources/NIOHTTP2/NIOHTTP2FrameDelegate.swift

@@ -0,0 +1,30 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2025 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import NIOCore
+import NIOHPACK
+
+/// A delegate which can be used with the ``NIOHTTP2Handler`` which is notified
+/// when various frame types are written into the connection channel.
+///
+/// This delegate, when used by the ``NIOHTTP2Handler`` will be called on the event
+/// loop associated with the channel that the handler is a part of. As such you should
+/// avoid doing expensive or blocking work in this delegate.
+public protocol NIOHTTP2FrameDelegate {
+    /// Called when a frame is written by the connection channel.
+    ///
+    /// - Parameters:
+    ///   - frame: The frame to write.
+    func wroteFrame(_ frame: HTTP2Frame)
+}