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

Author: Julien00859

peps/pep-0748.rst

@@ -422,7 +422,7 @@ need to implement the following:
 
 * ``recv`` and ``send``
 * ``accept`` (server-side)
-* ``close``
+* ``shutdown`` and ``close``
 * ``getsockname``
 * ``getpeername``
 
@@ -438,6 +438,12 @@ The following code describes these functions in more detail:
 
 .. code-block:: python
 
+    class TLSShutdownMode(enum.IntEnum):
+        SHUT_RD = 0
+        SHUT_WR = 1
+        SHUT_RDWR = 2
+
+
     class TLSSocket(Protocol):
         """This class implements a socket.socket-like object that creates an OS
         socket, wraps it in an SSL context, and provides read and write methods
@@ -464,15 +470,41 @@ 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: TLSShutdownMode) -> None:
+            """
+            Shutdown TLS and the underlying socket.
+
+            * ``SHUT_RD`` (``0``) unilateraly close the receiving-side: discard
+              present and future unread messages.
+            * ``SHUT_WR`` (``1``) gracefully close the sending-side: send a
+              closing alert and prevent sending more messages.
+            * ``SHUT_RDWR`` (``2``): both ``SHUT_WR`` and ``SHUT_RD``.
+
+            .. danger::
+
+                Both ``shutdown(SHUT_RD)`` and ``shutdown(SHUT_RDWR)`` pose a
+                risk of data loss: they are unsafe unless the connection is
+                otherwise known to be over or when truncation is not an issue.
+
+                In TLS 1.2, the same risk applies also to ``shutdown(SHUT_WR)``.
+            """
+            ...
+
+        @abstractmethod
+        def close(self) -> None:
+            """
+            Close the underlying socket, but only when it is safe to do so.
+
+            When the sending-side of the connection is still open, it gracefully
+            closes the TLS sending-side before closing the socket, raising
+            ``WantWriteError`` when it fails.
+
+            When the receiving-side 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-side of the connection, or (unsafe) take the risk
+            and unilateraly ``shutdown`` the receiving-side of the connection.
+            """
             ...
 
         @abstractmethod