document WtStreamManager.cpp & WtStreamManager.h

Summary: add some documentation around how things behave (api in .h file) and how things work (implementation details in .cpp)

Reviewed By: afrind

Differential Revision: D84727476

fbshipit-source-id: d5ea77742c823e89d2747b3f1b493dd7fb62a55c

Author: hanidamlaj

proxygen/lib/http/coro/util/WtStreamManager.cpp

@@ -6,6 +6,63 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/**
+ * This comment block documents the implementation details of WtStreamManager
+ * (i.e. the how).
+ *
+ * WriteHandle & ReadHandle (concrete implementations of
+ * WebTransport::WriteHandle and WebTransport::ReadHandle respsectively, defined
+ * below) are anonymous and strictly scoped to this TU. This requires
+ * downcasting in all apis that receive a pointer to those pure virtual classes.
+ * To prevent leaking implementation details by marking methods in
+ * WtStreamManager public just for internal use by WriteHandle & ReadHandle, we
+ * utilize a friend struct Accessor (also anonymously defined and strictly
+ * scoped to this TU).
+ *
+ * First thing to note is that we always allocate both a WriteHandle and
+ * ReadHandle regardless of the underlying properities of the stream (e.g. if
+ * it's a unidirectional stream). This makes things extremely easier to reason
+ * about, as there's a single map from [id]->[bidi_handle]. The public api in
+ * WtStreamManager is extremely restrictive, and we do not hand out a pointer to
+ * an invalid handle. For example, if a client WtStreamManager attempts to
+ * retrieve a EgressHandle for a server-initiated unidirectional stream (e.g.
+ * id=0x03), the state for such a handle exists but we return nullptr – it's
+ * effectively invisible to the user.
+ *
+ * A note about flow control:
+ * – Ingress flow control is strict, as a peer exceeding the advertised max
+ *   offset is a connection- or stream-level flow control.
+ *
+ * – Egress flow control is not strict, as an application can enqueue too much
+ *   data for any number of reasons (large write, ignoring backpressure, etc.).
+ *   We buffer this data in WriteHandle and is subsequently dequeued by the
+ *   transport whenever the stream is writable (hence the need for
+ *   WtEgressContainer to manage this small complexity). Applications should
+ *   respect backpressure signalled by returning FcState::BLOCKED from
+ *   WriteHandle::writeStreamData
+ *
+ * A note about stream states:
+ * – An egress handle transitions from [HandleState::Open] ->
+ *   [HandleState::Closed] in three cases: fin is dequeued from WriteHandle via
+ *   ::dequeue, the application resets the stream (i.e.
+ *   WebTransport::WriteHandle::resetStream), or the transport receives a
+ *   stop_sending and WtStreamManager::onStopSending is invoked.
+ *
+ * – An ingress handle transitions from [HandleState::Open] ->
+ *   [HandleState::Closed] in three cases: fin is read via ::readStreamData(),
+ *   the application is no longer interested in ingress (i.e.
+ *   WebTransport::ReadHandle::stopSending), or the transport receives a
+ *   reset_stream and WtStreamManager::onResetStream is invoked.
+ *
+ * – An invalid handle (e.g. client egress handle for a
+ *   server-initiated unidirectional stream) starts in the HandleState::Closed.
+ *
+ * – Once both the ingress & egress handles have reached the HandleState::Closed
+ *   state, we deallocate the state. Since we always allocate both a ReadHandle
+ *   and WriteHandle, they're both unconditionally linked together for
+ *   simplicity.
+ */
+
 #include <proxygen/lib/http/coro/util/WtStreamManager.h>
 
 #include <folly/logging/xlog.h>

proxygen/lib/http/coro/util/WtStreamManager.h

@@ -21,6 +21,48 @@
 #include <proxygen/lib/http/coro/util/WtEgressContainer.h>
 #include <proxygen/lib/http/webtransport/WebTransport.h>
 
+/**
+ * This comment block documents the api of WtStreamManager (i.e. its behaviour).
+ * Please refer to the documentation in WtStreamManager.cpp for the
+ * implementation details (i.e. the how).
+ *
+ * WtStreamManager, as the name suggestions, simply manages the stream state of
+ * WebTransport streams. Following good design philosophy, as much as possible
+ * is hidden from the user of this class.
+ *
+ * There are two channels to interact with this class:
+ *
+ * – The application via the handles (StreamWriteHandle & StreamReadHandle) and
+ *   their respective methods (e.g. WriteHandle::writeStreamData,
+ *   ReadHandle::stopSending, etc.).
+ *
+ * – The backing transport (http/2, quic, etc.) via the methods in this class
+ *   (e.g. onMaxStreams, onMaxData, ::enqueue(ReadHandle&),
+ *   ::dequeue(WriteHandle&), etc.)
+ *
+ * As of now, there's a single channel to communicate events to the backing
+ * transport –via WtStreamManager::Callback. This simply lets the backing
+ * transport know that there is an event available for the write loop to action
+ * on – there are two main events:
+ *
+ * – Control frames that need to be serialized/sent by the transport (e.g.
+ *   reset_stream, stop_sending, etc.). The transport should invoke ::moveEvents
+ *   and install a visitor to ensure all control-frames are handled
+ *   appropriately.
+ *
+ * – A stream that is now writable (e.g. ::nextWritable will return
+ *   non-nullptr). The transport should query the nextWritable stream and
+ *   dequeue data from the handle.
+ *
+ *
+ * A note about stream handles – everything is dervied from WtDir (the role of
+ * the endpoint, e.g. client or server) and stream id. Any attempt to
+ * access/create a handle for an invalid direction will return nullptr. For
+ * example, a client invoking ::getEgressHandle for a stream id that is
+ * logically a server-initiated unidirectional stream (e.g. id=0x03) will return
+ * nullptr.
+ */
+
 namespace proxygen::coro::detail {
 
 enum WtDir : uint8_t { Client = 0, Server = 1 };
@@ -30,7 +72,7 @@ constexpr uint64_t kMaxVarint = (1ull << 62) - 1;
 
 struct WtStreamManager {
   /**
-   * This level-triggered callback (::eventsAvailable) is invoked once control
+   * This edge-triggered callback (::eventsAvailable) is invoked once control
    * events are available to be dequeued by the backing transport – (e.g.
    * connection- and stream-level flow control, reset_stream, stop_sending,
    * etc.)