feat(python): Handler wrapper on the C ABI (RFC #43)

[dzerik]

Summary

Python wrapper for the Handler C ABI merged in #44. Python users can now write seccomp-notif handlers as Handler subclasses without touching ctypes directly.

Per RFC #43 phasing, this is the second of three PRs:

1. C ABI surface — merged in feat(ffi): C ABI for the Handler trait (RFC #43) #44.
2. Python wrapper layer (this PR) — Handler base class, registration via Sandbox.run_with_handlers, audit smoke test.
3. Ergonomic layer — path-helper convenience methods, fixtures, full docs page. Deferred.

What's in this PR

C ABI extension — one new exception-policy discriminant:

• SANDLOCK_EXCEPTION_DENY_EIO = 3. Your RFC RFC: Python parity for the Handler trait (Follow-up B) #43 reply on Q5 suggested letting audit-only handlers opt down to Errno(EIO); feat(ffi): C ABI for the Handler trait (RFC #43) #44 shipped only DENY_EPERM. EIO is the idiomatic choice for Python audit handlers (propagates as OSError rather than PermissionError). Discriminant appended after CONTINUE=2 — ABI-stable.

Python module sandlock.handler:

• NotifAction — frozen dataclass mirroring sandlock_action_out_t; factory classmethods (continue_, errno, return_value_, hold, kill, inject_fd_send).
• Handler — base class; subclass and override handle(ctx) -> NotifAction. Class attribute on_exception defaults to KILL (fail-closed, per Q5 = D).
• HandlerCtx — read-only notification snapshot + read_cstr / read / write child-memory accessors.
• ExceptionPolicy — IntEnum mirroring sandlock_exception_policy_t.

ctypes glue (_handler_ffi.py, _sdk.py):

• A module-scope C-callable trampoline bridges the synchronous C callback to Handler.handle. Dispatch is via an integer-id registry lookup — no raw PyObject* crosses the FFI boundary.
• The trampoline checks Py_IsInitialized() before touching Python state, catches handler exceptions (routing to the configured on_exception policy), rejects non-NotifAction return values, and translates the action into setter calls on sandlock_action_out_t.
• The child-memory handle is wrapped in a liveness cell that the trampoline invalidates once the callback returns. A HandlerCtx that escapes its handle() call fails safe — read/read_cstr/write return None/False — rather than dereferencing the supervisor stack-local it pointed at.

Sandbox.run_with_handlers(cmd, handlers, name=None) — registers (syscall_nr, Handler) pairs and runs, mirroring the existing Sandbox.run mechanics.

Cross-cutting concerns (RFC #43)

The RFC listed four cross-cutting items. How each is handled:

• GIL contention — each handle() dispatch holds the GIL; documented as a known limitation. Handlers should be fast and protect mutable state themselves.
• Interpreter finalization — the trampoline's Py_IsInitialized() check returns an error if Py_FinalizeEx ran mid-dispatch, routing the notification through on_exception.
• Native crashes inside handle() — not recoverable; documented as user responsibility.
• Tokio runtime reentrancy — sandlock_run_with_handlers builds its own runtime; documented that it must not be called from within an existing Tokio runtime.

All four are written up in docs/extension-handlers.md under a new "Python wrapper" section, plus ownership rules for Handler instances and injected file descriptors.

Ownership

• Handler instances are held by the Sandbox for the run's duration; the C container's ud_drop releases the Python reference on completion.
• After sandlock_run_with_handlers returns, all handler-container pointers are owned by the supervisor — the Python side does not free them. The mid-loop allocation-failure path frees only the containers created before the failure (registry-entry-removed-exactly-once invariant, test-pinned).
• The process-global handler registry is swept in a finally after sandlock_run_with_handlers returns: on the normal path the supervisor's ud_drop calls have already emptied the slots, but the run entry point is extern "C-unwind", so a panic (e.g. invoked from within an existing Tokio runtime) propagates as a Python exception — the unconditional, idempotent sweep keeps a panic from orphaning entries.

Test plan

• cargo test -p sandlock-ffi — 45 tests pass (44 + 1 new DenyEio policy test), 0 ignored.
• pytest python/tests/test_handler_smoke.py — 29 tests pass: NotifAction factories + frozen-ness, ExceptionPolicy/Handler defaults & override, HandlerCtx field exposure + frozen-ness, ABI-discriminant pins, handler-registry hygiene, and the end-to-end integration tests below.
• Audit smoke test (RFC §Phasing item 2) — a Handler counting SYS_openat interceptions on a real child process.
• End-to-end coverage of every non-Continue action — errno (child observes EPERM from a denied openat), return_value (child's getpid returns the synthetic value), kill returned directly by a handler (child terminated; on_exception set to Continue so the termination provably comes from the action, not a policy fallback). Each was destructively verified — neutering the trampoline's action dispatch makes each test fail.
• Failure-path tests — a raising handler with on_exception=CONTINUE lets the child complete; with on_exception=KILL it terminates the child.
• HandlerCtx memory accessor — a handler decodes the real openat path from child memory via read_cstr and denies a specific file.
• Lifetime safety — a HandlerCtx retained past its handle() call has its memory accessors fail safe; verified the liveness cell is invalidated on the trampoline's finally path.
• run_with_handlers argument validation — empty handler list runs cleanly; a non-Handler entry raises.
• Handler-registry hygiene — a completed run leaves the process-global registry empty; a mid-loop registration failure (a non-int syscall_nr on the second entry) rolls back with no orphaned registry entry. The rollback test is destructively verified — neutering the rollback except block leaves an orphaned entry and the test fails.
• pytest python/tests/test_sandbox.py — no regression from the _sdk.py additions.
• No Rust source changed beyond the one DenyEio discriminant.

Out of scope (PR 3)

• Path-helper convenience methods (ctx.read_path()).
• Preset/fixture handlers.
• A dedicated docs page (this PR adds one section to extension-handlers.md).
• Async handler wrappers — handlers stay synchronous per RFC Q1 = A.

Notes

• One pre-existing test, test_sandbox.py::TestCpuThrottle::test_throttle_slows_execution, is flaky on loaded CI hosts (a CPU-time-ratio assertion). It fails identically on main without this PR — unrelated to the Handler wrapper.
• Happy to split the DenyEio C-ABI discriminant into its own commit/PR if you'd prefer the Python wrapper PR to touch zero Rust.