wherobots-python-dbapi 0.28.2__tar.gz → 0.30.0__tar.gz

{wherobots_python_dbapi-0.28.2 → wherobots_python_dbapi-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: wherobots-python-dbapi
-Version: 0.28.2
+Version: 0.30.0
 Summary: Python DB-API driver for Wherobots DB
 Project-URL: Homepage, https://github.com/wherobots/wherobots-python-dbapi-driver
 Project-URL: Tracker, https://github.com/wherobots/wherobots-python-dbapi-driver/issues
@@ -225,6 +225,49 @@ Progress events are best-effort and may not be available for all query
 types or server versions. The handler is simply not invoked when no
 progress information is available.
 
+### Recovering from a lost connection
+
+If the WebSocket to the SQL session drops while queries are running (a
+network path failure, a keepalive timeout), the connection reconnects to
+the same SQL session by itself and re-attaches every pending query, so
+their results still arrive: there's nothing for your code to do. It keeps
+trying, with backoff, for up to `reconnect_timeout_seconds` (60 seconds by
+default; see below). It never starts a new session, and gives up at once
+if the session refuses the connection, for example because it's gone.
+While it reconnects, `execute()` and cancelling (closing a cursor, or
+executing on it) wait for it to finish.
+
+A re-attached query can still fail:
+
+* If the SQL session doesn't know the execution (the statement didn't
+    reach it before the connection dropped, or the session restarted),
+    fetching raises `ExecutionNotFoundError`, a subclass of
+    `OperationalError`.
+* If the SQL session cancelled the execution while the connection was
+    down (for example, its grace period for a lost connection ran out, or
+    another client cancelled it), fetching raises
+    `ExecutionCancelledError`, also an `OperationalError` subclass: its
+    outcome, including whether a write committed, is unknown. An execution
+    that you cancel yourself, by closing the cursor or executing on it,
+    completes with an empty result, as usual.
+* An older SQL session that doesn't support attaching still answers with
+    the execution's state, and the driver polls it for the outcome (see
+    `stale_query_probe_seconds` below). If such a session reports no
+    location for a stored result, because it predates reporting it or
+    because the stored result is empty, the driver can't tell which, and
+    fails the query with an `OperationalError`. With probes disabled, a
+    running execution on such a session fails right away.
+
+If the connection can't reconnect in time, or reconnecting is turned off
+(`reconnect_timeout_seconds=None`), fetching a pending query's outcome
+raises `ConnectionLostError`, another `OperationalError` subclass. The
+query may still have run, or be running, on the SQL session: its outcome,
+including whether a write committed, is unknown. The error's
+`execution_id` and `session_id` attributes identify it, and a cursor's
+`execution_id` property holds the ID of its current or last execution.
+(When `execute()` itself raises `ConnectionLostError`, the connection was
+already lost and the statement was never sent.)
+
 ### Runtime and region selection
 
 You can chose the Wherobots runtime you want to use using the `runtime`
@@ -302,3 +345,21 @@ users may find useful:
     caller needs to interrupt it (e.g. on client disconnect or timeout).
     The event is checked before each HTTP request, between retry
     attempts, and before the WebSocket handshake.
+* `session_key`: keeps this connection on SQL sessions of its own. The
+    API reuses a session only for connections that ask with the same key,
+    and never one opened without a key, so a heavy query elsewhere never
+    holds the session your queries run on. When a new session would exceed
+    your organization's quota, the API shares another of your sessions
+    under another key instead, with or without `session_key`, and the
+    connection's `session_fallback` is `"quota"` (it is `None` otherwise).
+    `connection.session_id` names the session.
+* `stale_query_probe_seconds`: how long a running query may go without
+    any message from the SQL session before the driver asks the session
+    for its state again, in case the query's completion event was lost.
+    Repeat probes back off to at most 8 times this interval. Defaults to
+    30 seconds; pass `None` to disable probing.
+* `reconnect_timeout_seconds`: how long the connection keeps trying to
+    reconnect to the same SQL session after losing its WebSocket (see
+    "Recovering from a lost connection" above). Defaults to 60 seconds,
+    which fits in the SQL session's 120-second grace period for the
+    queries of a lost connection; pass `None` to turn reconnecting off.

{wherobots_python_dbapi-0.28.2 → wherobots_python_dbapi-0.30.0}/README.md

@@ -200,6 +200,49 @@ Progress events are best-effort and may not be available for all query
 types or server versions. The handler is simply not invoked when no
 progress information is available.
 
+### Recovering from a lost connection
+
+If the WebSocket to the SQL session drops while queries are running (a
+network path failure, a keepalive timeout), the connection reconnects to
+the same SQL session by itself and re-attaches every pending query, so
+their results still arrive: there's nothing for your code to do. It keeps
+trying, with backoff, for up to `reconnect_timeout_seconds` (60 seconds by
+default; see below). It never starts a new session, and gives up at once
+if the session refuses the connection, for example because it's gone.
+While it reconnects, `execute()` and cancelling (closing a cursor, or
+executing on it) wait for it to finish.
+
+A re-attached query can still fail:
+
+* If the SQL session doesn't know the execution (the statement didn't
+    reach it before the connection dropped, or the session restarted),
+    fetching raises `ExecutionNotFoundError`, a subclass of
+    `OperationalError`.
+* If the SQL session cancelled the execution while the connection was
+    down (for example, its grace period for a lost connection ran out, or
+    another client cancelled it), fetching raises
+    `ExecutionCancelledError`, also an `OperationalError` subclass: its
+    outcome, including whether a write committed, is unknown. An execution
+    that you cancel yourself, by closing the cursor or executing on it,
+    completes with an empty result, as usual.
+* An older SQL session that doesn't support attaching still answers with
+    the execution's state, and the driver polls it for the outcome (see
+    `stale_query_probe_seconds` below). If such a session reports no
+    location for a stored result, because it predates reporting it or
+    because the stored result is empty, the driver can't tell which, and
+    fails the query with an `OperationalError`. With probes disabled, a
+    running execution on such a session fails right away.
+
+If the connection can't reconnect in time, or reconnecting is turned off
+(`reconnect_timeout_seconds=None`), fetching a pending query's outcome
+raises `ConnectionLostError`, another `OperationalError` subclass. The
+query may still have run, or be running, on the SQL session: its outcome,
+including whether a write committed, is unknown. The error's
+`execution_id` and `session_id` attributes identify it, and a cursor's
+`execution_id` property holds the ID of its current or last execution.
+(When `execute()` itself raises `ConnectionLostError`, the connection was
+already lost and the statement was never sent.)
+
 ### Runtime and region selection
 
 You can chose the Wherobots runtime you want to use using the `runtime`
@@ -277,3 +320,21 @@ users may find useful:
     caller needs to interrupt it (e.g. on client disconnect or timeout).
     The event is checked before each HTTP request, between retry
     attempts, and before the WebSocket handshake.
+* `session_key`: keeps this connection on SQL sessions of its own. The
+    API reuses a session only for connections that ask with the same key,
+    and never one opened without a key, so a heavy query elsewhere never
+    holds the session your queries run on. When a new session would exceed
+    your organization's quota, the API shares another of your sessions
+    under another key instead, with or without `session_key`, and the
+    connection's `session_fallback` is `"quota"` (it is `None` otherwise).
+    `connection.session_id` names the session.
+* `stale_query_probe_seconds`: how long a running query may go without
+    any message from the SQL session before the driver asks the session
+    for its state again, in case the query's completion event was lost.
+    Repeat probes back off to at most 8 times this interval. Defaults to
+    30 seconds; pass `None` to disable probing.
+* `reconnect_timeout_seconds`: how long the connection keeps trying to
+    reconnect to the same SQL session after losing its WebSocket (see
+    "Recovering from a lost connection" above). Defaults to 60 seconds,
+    which fits in the SQL session's 120-second grace period for the
+    queries of a lost connection; pass `None` to turn reconnecting off.

{wherobots_python_dbapi-0.28.2 → wherobots_python_dbapi-0.30.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wherobots-python-dbapi"
-version = "0.28.2"
+version = "0.30.0"
 description = "Python DB-API driver for Wherobots DB"
 authors = [{ name = "Maxime Petazzoni", email = "max@wherobots.com" }]
 requires-python = ">=3.10, <4"

{wherobots_python_dbapi-0.28.2 → wherobots_python_dbapi-0.30.0}/wherobots/db/__init__.py

@@ -3,7 +3,10 @@ from .cursor import Cursor
 from .driver import connect, connect_direct
 from .errors import (
     Error,
+    ConnectionLostError,
     DatabaseError,
+    ExecutionCancelledError,
+    ExecutionNotFoundError,
     InternalError,
     InterfaceError,
     OperationalError,
@@ -26,6 +29,9 @@ __all__ = [
     "InternalError",
     "InterfaceError",
     "OperationalError",
+    "ConnectionLostError",
+    "ExecutionCancelledError",
+    "ExecutionNotFoundError",
     "ProgrammingError",
     "NotSupportedError",
     "Region",

wherobots_python_dbapi-0.30.0/wherobots/db/_transport.py

@@ -0,0 +1,57 @@
+"""Transport termination independent of the WebSocket protocol's send lock."""
+
+import errno
+import select
+import selectors
+import socket
+
+from websockets.sync.client import ClientConnection
+
+
+def abort_connection(ws: ClientConnection) -> None:
+    """Disable further writes and wake blocked I/O before publishing failures.
+
+    ClientConnection.close() takes the library's protocol mutex, which a
+    stalled sendall() may hold. Shutdown the owned socket instead; the library's
+    receive thread will observe EOF/error and finish protocol cleanup itself.
+    Already transmitted bytes may still execute remotely.
+    """
+    try:
+        ws.socket.shutdown(socket.SHUT_RDWR)
+    except OSError as exc:
+        if exc.errno not in (errno.ENOTCONN, errno.EBADF, errno.ECONNRESET):
+            raise
+    finally:
+        # Even if shutdown fails, prevent any later send on this socket object.
+        ws.socket.close()
+
+
+def socket_writable(ws: ClientConnection) -> bool:
+    """Whether a small write to the transport's socket won't block right now.
+
+    For a send that must not stall the reader thread: a full send buffer
+    (a peer that keeps sending but stops reading) would park sendall(), which
+    also holds the library's protocol mutex, so even keepalive pings stall.
+
+    Never raises. Returns ``True`` (proceed, as without this check) on any
+    failure or for a transport without a real socket, such as a test fake:
+    ``False`` would silently disable the caller's sends. Uses ``poll`` (or a
+    selector), not ``select.select``, which fails for fds above FD_SETSIZE.
+    """
+    try:
+        sock = getattr(ws, "socket", None)
+        if not isinstance(sock, socket.socket):
+            return True
+        fd = sock.fileno()
+        if fd < 0:
+            return True  # Closed: let the send itself report it.
+        if hasattr(select, "poll"):
+            poller = select.poll()
+            poller.register(fd, select.POLLOUT)
+            # POLLERR/POLLHUP count as writable: the send then fails fast.
+            return bool(poller.poll(0))
+        with selectors.DefaultSelector() as selector:
+            selector.register(fd, selectors.EVENT_WRITE)
+            return bool(selector.select(0))
+    except Exception:
+        return True