Skip to content

fix: service socket path errors without a traceback, and no lamport flush panic at python exit - #752

Merged
bahdotsh merged 2 commits into
mainfrom
fix/service-socket-dir-error
Nov 17, 2026
Merged

bahdotsh merged 2 commits into
mainfrom
fix/service-socket-dir-error

Conversation

@aditipolkam

Copy link
Copy Markdown
Member

Summary

Two fixes for crashes reported against the Python SDK:

  1. offline-protocol-service printed a traceback when it refused its socket directory. It now exits with a one-line error that says how to fix it.
  2. A Rust panic at Python interpreter exit (UnexpectedUniFFICallbackError ... Python is likely shutting down) is fixed in the core. It was reported as "LAN discovery crashes without the [lan] extra".

Context / motivation

Socket directory. The local API server deliberately refuses to put its socket in a directory other users can read, because the socket gives full control of the engine. But the refusal surfaced as a raw ValueError traceback through asyncio.run. It looked like a crash and gave no hint. A second failure mode: a socket path longer than sun_path (104 bytes on macOS, 108 on Linux) failed only at bind time with an unclear OS error. The macOS pytest temp directory alone is over the limit.

Shutdown panic. The missing [lan] extra is not the cause: on 0.33.0 and main it gives a clean install hint. The crash is in OfflineProtocol::drop, which always wrote the Lamport clock through the host's state-storage callback, even when stop() had just written the same value. Python often frees the engine during interpreter shutdown, when callbacks can no longer run. MlsStorageError has no From<UnexpectedUniFFICallbackError>, so UniFFI panics. LAN-discovery programs hit it most often, which is why it looked LAN-related.

Changes

Python local API (bindings/python/offline_protocol_sdk/local_api/)

  • server.py:
    • New SocketPathError(ValueError), raised for a wide directory, a path that is not a socket, and a path too long to bind. Existing except ValueError still catches it.
    • The permission message ends with "Run chmod 700 <dir> if it is yours to narrow, or put the socket in a directory of its own".
    • New _check_socket_path_length runs before the directory is prepared or the engine starts.
  • cli.py: catches SocketPathError and exits with --socket: <message>, with no traceback.
  • __init__.py: exports SocketPathError.

Core (crates/offline-protocol/src/protocol/storage.rs)

  • flush_lamport_clock returns early when storage already holds the current value. After a normal stop(), drop writes nothing, so no callback runs at shutdown.

  • restore_lamport_clock sets last_persisted_lamport to what storage actually holds:

    • the stored value when present;
    • 0 when absent or corrupt;
    • unchanged on a read error.

    Without this, the early return would have skipped ticks taken before storage was attached.

Testing

  • cargo test -p offline-protocol --lib: 2195 passed. New tests:
    • test_a_stopped_protocol_is_dropped_without_writing_the_lamport_clock
    • test_lamport_ticks_taken_before_storage_was_attached_are_flushed
  • Python suite: 1151 passed, 4 skipped. New and updated tests in tests/local_api/test_local_api_server.py:
    • A wide directory raises SocketPathError with the chmod 700 hint, and the error is still a ValueError.
    • A too-long socket path is refused before the engine starts.
    • The CLI reports a refused directory as one line, with no traceback.
  • cargo clippy -p offline-protocol -p offline-protocol-uniffi -- -D warnings is clean.
    • With --all-targets, clippy fails in offline-protocol-transport (unwrap_used in tests). That crate is untouched and the failure exists on main.
  • Manual: three scripts that reproduced the shutdown panic (LAN discovery started and stopped, then interpreter exit) no longer panic.

Risk and rollout

  • No binding or UDL changes, so nothing needs regenerating.
  • Core behaviour change: drop no longer rewrites an unchanged Lamport clock. The stored value is the same either way, so this only removes a redundant write.
  • SocketPathError subclasses ValueError, so existing callers are unaffected.
  • Roll back by reverting the PR.

Follow-ups / out of scope

  • An engine that is never stopped, with ticks not yet written, can still panic at exit. So can any unexpected host-callback exception mid-run, such as an OSError from a host store. The robust fix is From<UnexpectedUniFFICallbackError> for MlsStorageError, which needs a new error variant and so regenerating all bindings, the C dispatcher, the C header and the local API table. Left for a separate decision.
  • bindings/python/examples/basic_messaging.py passes a stale user_id config field.

offline-protocol-service refuses a socket directory other users can
read, but the refusal surfaced as a ValueError traceback with no hint.
it now raises SocketPathError (a ValueError) with a chmod 700 hint, the
cli exits with a one-line --socket error, and paths too long for
sun_path are refused before the engine starts.
…the clock

drop always wrote the lamport clock through the host storage callback.
python often frees the engine at interpreter shutdown, when the callback
can no longer run, and uniffi panicked on the unexpected callback error.
the flush now skips a value storage already holds, and restoring the
clock records the stored value so ticks taken before storage was
attached are still written.
@bahdotsh
bahdotsh merged commit c508cc9 into main Nov 17, 2026
45 checks passed
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 17, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants