PEP 748: shutdown(show: 0|1|2) instead of close(force: bool)

Author: Julien00859

peps/pep-0748.rst

@@ -421,7 +421,7 @@ need to implement the following:
 
 * ``recv`` and ``send``
 * ``accept`` (server-side)
-* ``close``
+* ``shutdown`` and ``close``
 * ``getsockname``
 * ``getpeername``
 
@@ -463,15 +463,64 @@ The following code describes these functions in more detail:
             ...
 
         @abstractmethod
-        def close(self, force: bool = False) -> None:
-            """Shuts down the connection and mark the socket closed.
-            If force is True, this method should send the close_notify alert and shut down
-            the socket without waiting for the other side.
-            If force is False, this method should send the close_notify alert and raise
-            the WantReadError exception until a corresponding close_notify alert has been
-            received from the other side.
-            In either case, this method should return WantWriteError if sending the
-            close_notify alert currently fails."""
+        def shutdown(self, how: Literal[0, 1, 2]) -> None:
+            """
+            Shutdown TLS and the underlying socket.
+
+            Proper TLS applications ought to signal their peers when they're
+            done sending data by sending a closing alert.
+
+            * ``socket.SHUT_WR`` (``1``) sends the closing alert to the peer and
+              then prevents sending any further message. Proper TLS application
+              **MUST** call this method with this parameter to gracefully close
+              the TLS connection. *Safe* in TLS 1.3. Actually acts like
+              ``SHUT_RDWD`` in TLS 1.2 and is as *unsafe* as ``SHUT_RD``.
+
+            * ``socket.SHUT_RD`` (``0``) simulates receiving the closing alert
+              from the peer and then ignores all further received messages.
+              *Unsafe* (risk of data loss) unless the connection is otherwise
+              known to be over thanks to the application-layer protocol (e.g.
+              HTTP Content-Length).
+
+            * ``socket.SHUT_RDWR`` (``2``) does both ``SHUT_RD`` and ``SHUT_WR``.
+              As *unsafe* as ``SHUT_RD``.
+
+            In TLS 1.2, the closing alert is synchronous, receiving it triggers
+            an immediate closing alert response, and both connections are
+            immediately shut. It means that ``SHUT_WR`` acts like ``SHUT_RDWR``
+            and is unsafe unless all the data have been received.
+
+            In TLS 1.3, the closing alert is asynchronous, sending the closing
+            alert only closes the sender's sending-end and receiver's
+            receiving-end. The peer can keep on sending data until he
+            independently decides to close its own sending-end of the
+            connection. There is not risk of data truncation with ``SHUT_WR``.
+
+            .. danger::
+
+                Both ``socket.SHUT_RD`` (``0``) and ``socket.SHUT_RDWR`` (``2``)
+                pose a risk of data loss, only use them when facing a bad actor
+                or when the connection is otherwise known to be over.
+
+                In TLS 1.2 the same risk applies also to ``socket.SHUT_WR`` (``1``).
+            """
+            ...
+
+        @abstractmethod
+        def close(self) -> None:
+            """
+            Close the underlying socket, but only when it is safe to do so.
+
+            When the sending-end of the connection is still open, it sends a
+            closing alert before closing the socket, raising ``WantWriteError``
+            when it fails.
+
+            When the receiving-end of the connection is still open, it always
+            raises ``WantReadError`` as there's a risk of data loss / truncation
+            attack. The user must first either: (safe) ``recv`` until the peer
+            closes its sending-end of the connection, or (unsafe) take the risk
+            and unilateraly ``shutdown`` the reading-end of the connection.
+            """
             ...
 
         @abstractmethod