Document the RequestProcessor class and caches.

- Add the beginnings of the documentation for why and how ``PersistentConnectionProvider`` instances cache request information and responses in order to process them appropriately.
- Link to the ``RequestProcessor`` documentation from the ``WebsocketProviderV2`` docs.

Author: fselmo

docs/internals.rst

@@ -185,3 +185,118 @@ Managers
 The Manager acts as a gatekeeper for the request/response lifecycle.  It is
 unlikely that you will need to change the Manager as most functionality can be
 implemented in the Middleware layer.
+
+.. _request_processor:
+
+RequestProcessor
+----------------
+
+The ``RequestProcessor`` class is responsible for the storing and syncing up of
+asynchronous requests to responses for a ``PersistentConnectionProvider``. The best
+example of one such provider is the ``WebsocketProviderV2``. In order to send a
+websocket message and receive a response to that particular request,
+``PersistentConnectionProvider`` instances have to match request *id* values to
+response *id* values coming back from the websocket connection. Any provider that does
+not adhere to the `JSON-RPC 2.0 specification <https://www.jsonrpc.org/specification>`_
+in this way will not work with ``PersistentConnectionProvider`` instances. The specifics
+of how the request processor handles this is outlined below.
+
+One-To-One Requests
+~~~~~~~~~~~~~~~~~~~
+
+One-to-one requests can be summarized as any request that expects one response back.
+An example is using the ``eth`` module API to request the latest block number.
+
+.. code-block:: python
+
+    >>> async def wsV2_example():
+    ...     async with AsyncWeb3.persistent_websocket(
+    ...         WebsocketProviderV2(f"ws://127.0.0.1:8546")
+    ...     ) as w3:
+    ...         # make a request and expect a single response returned on the same line
+    ...         latest_block_num = await w3.eth.block_number
+
+With websockets we have to call ``ws_send()`` and asynchronously receive responses via
+``ws.recv()``. In order to make the one-to-one request-to-response call work, we
+have to save the request information somewhere so that, when the response is received,
+we can match it to the original request that was made (the request with a matching *id*
+to the response that was received), and use that request information to process the
+response. Processing the response, in this case, means running it through the
+formatters and middlewares internal to the *web3.py* library.
+
+In order to store the request information, the ``RequestProcessor`` class has an
+internal ``RequestInformation`` cache. The ``RequestInformation`` class saves important
+information about a request, such as:
+
+    - ``method``: The name of the method - e.g. "eth_subscribe".
+    - ``params``: The params used when the call was made - e.g.
+      ("newPendingTransactions", True).
+    - ``response_formatters``: The formatters that will be used to process the response.
+    - ``middleware_response_processors``: Any middleware that processes responses that
+      is present on the instance at the time of the request is appended here, in order,
+      so the response may be piped through that logic when it comes in.
+    - ``subscription_id``: If the request is an ``eth_subscribe`` request, rather than
+      popping this information from the cache when the response to the subscription call
+      comes in (i.e. the subscription *id*), we save the subscription id with the
+      request information so that we can correctly process all subscription messages
+      that come in with that subscription *id*. For one-to-one request-to-response
+      calls, this value is always ``None``.
+
+One-to-one responses, those that include a JSON-RPC *id* in the response object, are
+stored in an internal ``SimpleCache`` class, isolated from any one-to-many responses.
+When the ``PersistentConnectionProvider`` is looking for a response internally, it will
+cycle within a ``while`` loop, alternating between checking this cache (in case
+somewhere else in the code our desired response was cached by another call) and calling
+``recv()`` on the websocket connection to see if it is yet to come.
+
+One-To-Many Requests
+~~~~~~~~~~~~~~~~~~~~
+
+One-to-many requests can be summarized by any request that expects many responses as a
+result of the initial request. An example is the ``eth_subscribe`` request. The initial
+``eth_subscribe`` request expects only one response, the subscription *id* value, but
+it also expects to receive many ``eth_subscription`` messages if and when the request is
+successful. For this reason, the original request is considered a one-to-one request
+so that a subscription *id* can be returned to the user on the same line, but the
+``listen_to_websocket()`` method on the ``WebsocketConnection`` class, the public API
+for interacting with the active websocket connection, is set up to receive many-to-one
+``eth_subscription`` responses over an asynchronous interator pattern.
+
+.. code-block:: python
+
+    >>> async def ws_v2_subscription_example():
+    ...     async with AsyncWeb3.persistent_websocket(
+    ...         WebsocketProviderV2(f"ws://127.0.0.1:8546")
+    ...     ) as w3:
+    ...         # Subscribe to new block headers and receive the subscription_id.
+    ...         # A one-to-one call with a trigger for many responses
+    ...         subscription_id = await w3.eth.subscribe("newHeads")
+    ...
+    ...         # Listen to the websocket for the many responses utilizing the ``w3.ws``
+    ...         # ``WebsocketConnection`` public API method ``listen_to_websocket()``
+    ...         async for response in w3.ws.listen_to_websocket():
+    ...             # Receive only one-to-many responses here so that we don't
+    ...             # accidentally return the response for a one-to-one request in this
+    ...             # block
+    ...
+    ...             print(f"{response}\n")
+    ...
+    ...             if some_condition:
+    ...                 # unsubscribe from new block headers, another one-to-one request
+    ...                 is_unsubscribed = await w3.eth.unsubscribe(subscription_id)
+    ...                 if is_unsubscribed:
+    ...                     break
+
+    >>> asyncio.run(ws_v2_subscription_example())
+
+One-to-many responses, those that do not include a JSON-RPC *id* in the response object,
+are stored in an internal ``collections.deque`` instance, isolated from any one-to-one
+responses. When the ``PersistentConnectionProvider`` is looking for a one-to-many
+response internally, it will cycle within a ``while`` loop, alternating between
+checking this deque (in case somewhere else in the code, subscriptions responses were
+put in the deque by another call looking for another response type) and calling
+``recv()`` on the websocket connection to see if the response is yet to be received.
+With each iteration on this iterator, if the ``deque`` is non-empty, it will yield
+messages from the ``deque`` as FIFO order until the deque is empty before receiving any
+new messages from the websocket connection, guaranteeing the messages are yielded in the
+order they were received.

docs/providers.rst

@@ -348,6 +348,11 @@ provider in separate lines. Both of these examples are shown below.
     >>> asyncio.run(ws_v2_alternate_init_example_1)
     >>> asyncio.run(ws_v2_alternate_init_example_2)
 
+The ``WebsocketProviderV2`` class uses the :ref:`RequestProcessor <request_processor>`
+class under the hood to sync up the receiving and response processing for one-to-one and
+one-to-many request-to-response requests. Refer to the linked documentation for the
+``RequestProcessor`` for details on why and how it handles this processing.
+
 _PersistentConnectionWeb3 via AsyncWeb3.persistent_websocket()
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~