Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,36 @@ All notable changes to python-libei are recorded here. The format follows

## [Unreleased]

### Added

- **A malformed portal signal payload now raises the new typed
`PortalProtocolError` instead of hanging or crashing the caller.** Every
signal `wait_for_activation()` and `wait_for_deactivation()` wait on is
specified as `(o session_handle, a{sv} options)`, and that shape used to
be unpacked on faith, failing differently depending on how it was wrong:
an empty tuple raised `IndexError` inside the GLib signal callback — where
PyGI prints the traceback to stderr and swallows it, so the loop kept
running and the wait hung (unboundedly, with `timeout=None`), the worst
case because it was invisible; a wrong-length tuple or a non-dict options
value instead slipped through to the caller and crashed it with
`ValueError`/`AttributeError`. The shape is now checked in one place and
any mismatch ends the wait with `PortalProtocolError`, naming the signal
and the payload that arrived. The value level is covered too: every field
the spec types — `activation_id` (`u`), `cursor_position` (`(dd)`, now
checked for exactly two numeric components rather than any iterable),
`barrier_id` (`u`) — is converted under one guard, so a non-conforming
value in any of them raises the same typed error (including the
`OverflowError` an infinite `activation_id` would otherwise throw past an
`except PortalError`) rather than crashing the caller later doing
arithmetic on a string. One `except PortalProtocolError` therefore covers
every way a non-conforming portal can malform one of these signals. The
error carries `.step` (the signal name, the attribute every sibling
portal error uses), `.payload`, and `.detail` (`None` for a shape fault,
a phrase naming the field for a value fault). Signals and the wait's
deadline or a session close that become ready in the same GLib
main-context iteration now resolve to whichever outcome was recorded
first, rather than a delivered activation being dropped for a timeout.

## [0.7.0] - 2026-10-16

### Added
Expand Down
11 changes: 7 additions & 4 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,15 +87,18 @@ import each from the module that raises it.
| `libei.portal` | `PortalVersionError` | The RemoteDesktop portal is too old to offer `ConnectToEIS` |
| `libei.portal` | `PortalTimeoutError` | A step was accepted and never answered. Carries `.step` and `.timeout` |
| `libei.portal` | `PortalDeniedError` | `CreateSession`, `SelectDevices` or `Start` came back non-zero — an explicit decline, or any other code the spec does not distinguish from one. Carries `.step` and `.message` |
| `libei.portal` | `PortalSessionClosedError` | The session was ended from the compositor's side while a wait was outstanding — a restart, the portal dying, capture revoked from a settings panel. Carries `.step` |
| `libei.portal` | `PortalProtocolError` | A portal signal's payload does not match the spec — either the `(session_handle, options)` shape or a value inside it (`activation_id`, `cursor_position`, `barrier_id`). Carries `.step`, `.payload`, and `.detail` (`None` for a shape fault, a phrase naming the field for a value fault) |
| `libei.ei`, `libei.eis`, `libei.oeffis` | `LibraryNotFoundError` | The native library is missing or too old to export the function being called. A `RuntimeError`, and raised at the first *call* — see below |

Which of those to catch depends on the families, because they do not nest under
a single base:

- **`except PortalError`** covers `PortalVersionError`, `PortalTimeoutError`
and `PortalDeniedError`. `PortalTimeoutError` is the one to think about before
treating it as a failure: the call is still outstanding, and by far the most
common cause is a consent dialog a user has not answered yet.
- **`except PortalError`** covers `PortalVersionError`, `PortalTimeoutError`,
`PortalDeniedError`, `PortalSessionClosedError` and `PortalProtocolError`.
`PortalTimeoutError` is the one to think about before treating it as a
failure: the call is still outstanding, and by far the most common cause is a
consent dialog a user has not answered yet.
- **`except DisconnectedError`** covers `SessionClosedError` too. That one is
not an error in libei's view — the session ended normally — which is why it
has its own class rather than reusing its base.
Expand Down
210 changes: 188 additions & 22 deletions src/libei/portal.py
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,8 @@
"PortalVersionError",
"PortalDeniedError",
"PortalTimeoutError",
"PortalSessionClosedError",
"PortalProtocolError",
"RemoteDesktopSession",
"Activation",
"InputCaptureSession",
Expand Down Expand Up @@ -185,6 +187,45 @@ def __init__(self, step: str, message: str | None = None) -> None:
self.message = message


class PortalProtocolError(PortalError):
"""A portal signal arrived with a payload that does not match the spec.

Every signal :func:`_wait_for_signal` waits on is specified as
``(o session_handle, a{sv} options)``, and two kinds of mismatch used
to fail in two different, equally unhelpful ways. The *shape* being
wrong -- an empty tuple, a non-string handle, a wrong-length tuple, a
non-dict options -- either raised ``IndexError`` *inside* the GLib
signal callback, where PyGI prints the traceback to stderr and
swallows it so the wait hung invisibly (unboundedly, with
``timeout=None``), or slipped through to the caller and crashed it with
``ValueError``/``AttributeError``. A *value* inside a correctly-shaped
options being wrong -- an ``activation_id`` that is not an integer, a
``cursor_position`` that is not two numbers -- crashed the caller later
still, doing arithmetic on it. Both now end the wait with this error.

``detail`` distinguishes the two: ``None`` for a shape fault (the
default message names the expected shape), a phrase for a value fault
(naming the field). ``payload`` is whatever best shows the fault -- the
whole signal tuple for a shape fault, the options dict for a value one.
"""

def __init__(self, step: str, payload: object, detail: str | None = None) -> None:
"""Name the signal, what arrived, and -- for a value fault -- which."""
reason = detail or (
"the portal spec gives it the shape (session_handle, options dict)"
)
super().__init__(
f"{step} arrived with a malformed payload: {reason}, got {payload!r}"
)
# `step` mirrors the attribute every sibling portal error raised
# from the same `_wait_for_signal` call site carries
# (PortalTimeoutError, PortalSessionClosedError), so a caller that
# catches PortalError and reads `.step` works across all of them.
self.step = step
self.payload = payload
self.detail = detail


class PortalSessionClosedError(PortalError):
"""The portal session ended while something was still waiting on it.

Expand Down Expand Up @@ -1021,6 +1062,88 @@ def _create_input_capture_session_v1(
return session_handle


def _classify_signal_payload(
args: tuple[Any, ...], session_handle: str, signal: str
) -> str:
"""How `_wait_for_signal` should treat one unpacked signal payload.

``"take"`` -- it is this session's, correctly shaped, record it.
``"drop"`` -- another session's; keep waiting (logged, since a dropped
signal is otherwise indistinguishable from one that never fired).
``"malformed"`` -- not the ``(o session_handle, a{sv} options)`` shape
the spec gives every signal here; the session filter runs *between* the
two shape checks on purpose, so a malformed payload for another session
is still dropped rather than raised in this waiter.
"""
if not args or not isinstance(args[0], str):
return "malformed"
if args[0] != session_handle:
logger.debug(
"ignoring %s for session %s while waiting for %s",
signal,
args[0],
session_handle,
)
return "drop"
if len(args) != 2 or not isinstance(args[1], dict):
return "malformed"
return "take"


def _deactivation_id(options: dict[str, Any], signal: str) -> int:
"""The ``activation_id`` from Deactivated's options, as the spec's ``u``.

``_wait_for_signal`` checks the payload's *shape* -- that options is a
dict -- but not the types of the values in it. ``activation_id`` is a
``u``, and a non-conforming portal that put something else there would
crash the caller with ``ValueError``/``TypeError``/``OverflowError``
(the last from ``int(float('inf'))``) past the shape check. Converting
it here turns that into the same typed :class:`PortalProtocolError` the
shape check raises, so a caller that guards against malformed signals
catches one error, not two.
"""
try:
return int(options.get("activation_id", 0))
except (ValueError, TypeError, OverflowError) as exc:
raise PortalProtocolError(
signal, options, "activation_id is not an integer"
) from exc


def _activation_from_options(options: dict[str, Any], signal: str) -> Activation:
"""Build an :class:`Activation` from Activated's options, spec-typed.

The companion to the shape check in ``_wait_for_signal`` for the value
level: every field the portal spec types is converted here under one
guard, so a non-conforming value in any of them -- an ``activation_id``
that is not a ``u``, a ``cursor_position`` that is not two ``d``s, a
``barrier_id`` that is not a ``u`` -- becomes the same typed
:class:`PortalProtocolError` rather than a crash in the caller later,
doing arithmetic on a string. One guard rather than three means the
next field added to the signal is validated by construction, not by a
fourth hand-rolled check nobody remembers to write.
"""
try:
activation_id = int(options.get("activation_id", 0))
cursor = options.get("cursor_position")
if cursor is None:
cursor_position = None
else:
cx, cy = cursor # (dd): exactly two, or this unpacking raises
cursor_position = (float(cx), float(cy))
barrier = options.get("barrier_id")
barrier_id = None if barrier is None else int(barrier)
except (ValueError, TypeError, OverflowError) as exc:
raise PortalProtocolError(
signal, options, "an option value is not the type the spec gives it"
) from exc
return Activation(
activation_id=activation_id,
cursor_position=cursor_position,
barrier_id=barrier_id,
)


def _wait_for_signal(
connection: Any,
Gio: Any,
Expand Down Expand Up @@ -1056,12 +1179,31 @@ def _wait_for_signal(
D-Bus specification restricts plain ``arg0=`` match rules to arguments
of type STRING, and this one is an OBJECT_PATH, which is the same shape
of silent non-delivery all over again.

A payload that does not match the spec's ``(o session_handle, a{sv}
options)`` shape raises :class:`PortalProtocolError` rather than being
unpacked on faith -- see that class for why the alternative was not an
exception but a hang.
"""
loop = GLib.MainLoop()
result: dict[str, Any] = {}
malformed: dict[str, Any] = {}
timed_out = False
session_closed = False

def _settled() -> bool:
"""Whether some terminal outcome has already been recorded.

GLib dispatches every source ready in one main-context iteration,
regardless of an earlier ``loop.quit()``, so two outcomes -- a
signal and the timeout, a signal and Closed -- can both fire in the
same poll. Every callback checks this first so the *first* recorded
outcome wins and the post-loop raise order is never handed a second
one to misreport (a delivered activation dropped for a timeout, a
protocol fault overwritten by session-closed).
"""
return bool(result) or bool(malformed) or timed_out or session_closed

def on_closed(*_args: Any) -> None:
"""End the wait: a closed session can never deliver the signal.

Expand All @@ -1076,7 +1218,7 @@ def on_closed(*_args: Any) -> None:
that merely had not fired yet.
"""
nonlocal session_closed
if result:
if _settled():
return
logger.debug("session %s closed while waiting for %s", session_handle, signal)
session_closed = True
Expand All @@ -1092,21 +1234,22 @@ def on_signal(
*_a: Any,
) -> None:
"""Record the first matching signal; anything else is logged and dropped."""
if result: # a subscription that outlives its own wait can fire twice
if _settled(): # a subscription outliving its wait fires twice
return
args = params.unpack()
if args[0] != session_handle:
# Logged, not silently dropped: this filter can hide a signal
# that *did* arrive just as effectively as the wrong-path
# subscription above did, and the two are indistinguishable
# from the outside -- both look exactly like a compositor that
# never fired. One debug line is what tells them apart.
logger.debug(
"ignoring %s for session %s while waiting for %s",
signal,
args[0],
session_handle,
)
# The verdict is computed by `_classify_signal_payload`, but ACTED
# on here and the error raised only after the loop, because this
# runs inside a GLib callback: PyGI prints an exception raised here
# to stderr and swallows it, so a bare raise on a malformed payload
# would leave the loop running -- a timeout at best, an unbounded
# hang with timeout=None, both indistinguishable from a compositor
# that never fired.
verdict = _classify_signal_payload(args, session_handle, signal)
if verdict == "drop":
return
if verdict == "malformed":
malformed["args"] = args
loop.quit()
return
logger.debug("received %s for session %s", signal, session_handle)
result["args"] = args
Expand All @@ -1115,6 +1258,11 @@ def on_signal(
def on_timeout() -> bool:
"""Stop the loop and record that it timed out rather than finished."""
nonlocal timed_out
if _settled():
# A signal delivered in the same poll as the deadline has
# already recorded its outcome; the timeout must not overwrite
# a real activation with PortalTimeoutError.
return False
timed_out = True
loop.quit()
return False
Expand Down Expand Up @@ -1148,7 +1296,7 @@ def on_timeout() -> bool:
session_handle,
)
try:
if not result and not session_closed:
if not result and not session_closed and not malformed:
timeout_source = None
if timeout is not None:
timeout_source = GLib.timeout_add(int(timeout * 1000), on_timeout)
Expand All @@ -1169,8 +1317,31 @@ def on_timeout() -> bool:
finally:
connection.signal_unsubscribe(subscription)
connection.signal_unsubscribe(closed_subscription)
return _signal_outcome(
signal, timeout, result, malformed, timed_out, session_closed
)


def _signal_outcome(
signal: str,
timeout: float | None,
result: dict[str, Any],
malformed: dict[str, Any],
timed_out: bool,
session_closed: bool,
) -> tuple[Any, ...]:
"""Raise for the terminal outcome `_wait_for_signal` recorded, or return it.

Order is load-bearing and matches the callbacks' `_settled` guard:
whichever outcome was recorded first is the only one set, so this order
only ever decides between genuinely simultaneous dispatches, where a
session that has closed or a payload that was malformed is the more
useful answer than "timed out".
"""
if session_closed:
raise PortalSessionClosedError(signal)
if malformed:
raise PortalProtocolError(signal, malformed["args"])
if timed_out:
# timed_out is only ever set inside on_timeout, itself only ever
# registered when timeout is not None -- so this always holds, but
Expand Down Expand Up @@ -1497,12 +1668,7 @@ def wait_for_activation(self, timeout: float | None = None) -> Activation:
self.session_handle,
timeout,
)
cursor = options.get("cursor_position")
return Activation(
activation_id=int(options.get("activation_id", 0)),
cursor_position=tuple(cursor) if cursor is not None else None,
barrier_id=options.get("barrier_id"),
)
return _activation_from_options(options, "Activated")

def wait_for_deactivation(self, timeout: float | None = None) -> int:
"""Block until the current capture ends, returning its activation_id."""
Expand All @@ -1520,7 +1686,7 @@ def wait_for_deactivation(self, timeout: float | None = None) -> int:
self.session_handle,
timeout,
)
return int(options.get("activation_id", 0))
return _deactivation_id(options, "Deactivated")

def close(self) -> None:
"""End the portal session, and close the EIS fd if unclaimed.
Expand Down
Loading
Loading