Skip to content

Latest commit

 

History

History
137 lines (116 loc) · 7.68 KB

verification.md

File metadata and controls

137 lines (116 loc) · 7.68 KB

What has actually been verified

The package is beta (0.8.2) and the API is not frozen — expect renames before 1.0. This page is what that qualifier covers, concretely: which paths have been driven against real libraries, which have only ever been driven against fakes, and which libei versions the whole thing has met.

Driven end to end against the real libraries

  • The injection path — connect, bind, wait for a device, send events — is exercised by tests/test_integration_socketpair.py, and is in use as the Wayland input backend of a separate GUI-automation project.
  • Text input, touch cancellation, ping/pong, keymap transfer, region mapping ids and peek_event_type() are each round-tripped through a real libeis server in tests/test_integration_extras.py.

The portal paths, which can only be verified by hand

Both libei.oeffis and libei.portal need an interactive consent dialog that nothing here can drive automatically, so their automated coverage stops at a fake D-Bus connection.

tests/test_portal.py covers libei.portal's orchestration against that fake: raceless subscribe-before-call, the session_handle_token crash workaround, persist_mode/restore_token, and closing the portal session on a negotiation that fails part-way.

By hand:

  • libei.oeffis, 2026-08-25. See troubleshooting.md for what that run established about the GNOME 44 hangs.

  • libei.portal.RemoteDesktopSession, 2026-09-01, against a real GNOME Wayland session (RemoteDesktop v2). A first run raised the consent dialog and was approved (5.4s); a second replaying the restore_token was granted with no dialog at all (0.2s); three devices resumed on the returned fd — relative pointer, keyboard, absolute pointer, in that order, which is the device race ei-side callers must handle; and Session.Close() was exercised. No input was injected — emulation is libei.ei's job.

  • libei.portal.InputCaptureSession (added 0.5.0), the v1 half, 2026-09-08, against a real Fedora 44 / GNOME Shell 50.0 session (xdg-desktop-portal 1.21.1). That portal reports InputCapture version 0, so this exercised the v1 CreateSession path: consent dialog approved, a real EIS fd returned, zones() answering (0, [(1920, 1080, 0, 0)]), and Session.Close() exercised.

  • The v2 half, CreateSession2 -> Start, 2026-10-04, against a real Fedora 45 / GNOME Shell 51.0 session (xdg-desktop-portal 1.22.1, xdg-desktop-portal-gnome 51.0, libei 1.6.0, Python 3.15rc2). That portal reports InputCapture version 2, so the version gate sent this run down the half the 2026-09-08 one could not reach -- and v1 is not reachable there at all any more, which makes the two dates a pair rather than a repeat. Every call was driven live, in order: CreateSession2 (0.03s -- a plain call, with the session existing before anything is asked), Start (12.94s -- the consent dialog, approved), ConnectToEIS (0.10s -- a real EIS fd; fstat reports a socket), GetZones (0.06s, answering (0, [(1920, 974, 0, 0)])) and Session.Close (0.03s): 13.07s end to end. Nothing was captured, and nothing could have been -- the run stopped at negotiation, and by the shipped spec it is Enable that arms capture, not Start.

    So both negotiation routes have now been run against a real compositor. Two things remain untested live on this route: persistence, since persist_mode and the restore_token Start returns are v2 additions this run did not use -- and the capture half itself.

    The capture half remains unverified, and unlike the rest of libei.portal its consent dialog is not the whole reason why. Approving a capture exclusively diverts the approving developer's own pointer, keyboard or touch input away from their desktop for as long as it stays active, so verifying set_pointer_barriers() / enable() / wait_for_activation() needs someone to deliberately accept that, not merely click through a permission prompt. Those were designed against the shipped D-Bus spec (/usr/share/dbus-1/interfaces/org.freedesktop.portal.InputCapture.xml) and unit-tested against a fake connection reproducing its documented shapes (tests/test_inputcapture.py) instead.

    What that cost, on record: wait_for_activation()/ wait_for_deactivation() subscribed to their signals on the session's own object path, where the portal never emits them — so they always ran to their timeout. The fake connection modelled the same misreading (it fired a pending signal on whatever path was subscribed), so a wrong subscription and a wrong fake agreed all the way to a green suite, and the live symptom — a wait that never returns — was indistinguishable from a compositor that never activates capture. It was diagnosed as the latter, across two GNOME versions, a standalone C reproducer and an upstream Mutter report, before an xdg-desktop-portal developer identified it (2026-09-09). Fixed, with the fake corrected to emit on the portal object as a real one does. Two things generalise: a fake written from the same assumption as the code proves only that they agree, and a never-arriving signal looks exactly like a signal never sent.

Which libei versions this has met

  • Verified against libei 1.6.0 on Fedora 44 / GNOME 50.4.
  • Verified against a locally built 1.2.1 — 130 passed, 4 skipped, the 1.4 and 1.6 features gating themselves out.
  • CI repeats the 1.2.1 run on Python 3.10–3.13, so the 1.0.0 core floor is exercised on a real old build rather than asserted.
  • Re-run 2026-09-30 against 1.6.0 on Fedora 45 (libei 1.6.0-3, under Python 3.15rc2) and against Ubuntu 24.04's 1.2.1 in a container: the full suite passes on both, the 1.4 and 1.6 features gating themselves out on 1.2.1.
  • 1.0–1.1 and 1.3 have never been run against -- and neither has 1.4 or 1.5 at runtime. What they have had is the header check below.

Checked against the headers

tests/test_abi.py compares every bound function's argument count, argument classes and return class (pointer, 4-byte int, 8-byte int, double, bool, void) with the upstream prototype, and every Python enum member's value with the C enumerator. It needs the headers, so it runs only when LIBEI_SOURCE_DIR names an upstream checkout (or an installed libei-dev provides them). Run on 2026-09-30 against the public headers of 1.0.0, 1.2.1, 1.4.0, 1.5.0 and 1.6.0, with the installed 1.6.0 and 1.2.1 libraries checked for every declared export: clean on all five once six declarations were marked with the release that added them (touch cancellation and pong_get_ping on both sides in 1.4, eis_backend_socket_get_client_pid in 1.5). They had no marker, so the version each one needs was missing from the source -- an omission that cost nothing on 1.6 and would have presented as an unexplained missing symbol on an older library.

There are no ctypes.Structure bindings, so there is no layout to verify; every object is an opaque pointer and every value crosses as a scalar.

A separate CI job installs the package with no native libraries at all and imports it, which is the property the lazy loader exists to provide.

How the version floors were established

By building libei 1.2.1 and diffing its exported symbols against every binding here — not by reading @since annotations. Three of those are missing upstream, and taking their absence to mean 1.0 got touch cancellation wrong by four releases.

That is why the per-feature table in the README's requirements section can be trusted: each row is a symbol that was observed present or absent in a real build, not a documentation claim.