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.

[congwang-mk]

Nice work! The high-level looks pretty good, just some minor issues below.

[congwang-mk]

Could we avoid using raw syscall numbers? It is hard to find them out for different architecture. Maybe use string, like "openat" ?

[dzerik]

Done. run_with_handlers now takes a syscall name (str) — handlers=[("openat", AuditOpens())] — resolved for the host arch, or a raw int for syscalls the resolver doesn't cover (e.g. getpid). Added sandlock_syscall_nr(const char *name) to the C ABI, wrapping the core's syscall_name_to_nr, so C callers get the same. Docs example updated. 9908444.

[congwang-mk]

Is it an issue to always increase _NEXT_ID here?

[dzerik]

Not an issue in practice. _NEXT_ID is a Python int (no fixed width — never overflows), and the registry is swept empty after every run, so only the counter advances, not memory. The one hard ceiling is the C ABI's ud slot — a pointer-width c_void_p (2**64 on 64-bit hosts) — far beyond any realistic process lifetime. A fresh id per registration is also the simplest guarantee that concurrently-live handlers have distinct uds; recycling would add concurrency-sensitive bookkeeping for a non-issue. Added a comment spelling this out in 9908444.

[dzerik]

Both review comments addressed in 9908444.

While testing I also fixed a pre-existing race in a1_ffi_handler_drains_inject_fd_on_panic (6991ab0) — it did a single non-blocking read for EOF, which races peer tests that fork() children holding a transient inherited duplicate of the pipe write end (O_CLOEXEC closes it only at exec). It now polls for POLLHUP with a deadline, so the assertion is about the drain rather than test scheduling. Unrelated to the Handler wrapper; happy to split it into its own PR if you'd prefer.

Local: 48 Rust tests + 35 Python handler tests pass.

[dzerik]

Rebased onto current main. Dropped my a1_ffi_handler_drains_inject_fd_on_panic race fix — your b1a30cd landed the same poll(2)-for-EOF fix, so it is redundant. The PR is now just the syscall-name resolution and the Python wrapper. 13 commits, CI green.