From 18410676a09ea1ac614336014bd8a9fa75c14640 Mon Sep 17 00:00:00 2001 From: Aditi Polkam Date: Mon, 16 Nov 2026 15:08:01 +0530 Subject: [PATCH 1/2] fix(python): report a refused service socket path without a traceback 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. --- .../local_api/__init__.py | 3 +- .../offline_protocol_sdk/local_api/cli.py | 7 ++- .../offline_protocol_sdk/local_api/server.py | 34 ++++++++++++-- .../tests/local_api/test_local_api_server.py | 46 ++++++++++++++++--- 4 files changed, 77 insertions(+), 13 deletions(-) diff --git a/bindings/python/offline_protocol_sdk/local_api/__init__.py b/bindings/python/offline_protocol_sdk/local_api/__init__.py index 008e78dec..ddbf7f1ea 100644 --- a/bindings/python/offline_protocol_sdk/local_api/__init__.py +++ b/bindings/python/offline_protocol_sdk/local_api/__init__.py @@ -10,7 +10,7 @@ from .codec import RpcError # noqa: F401 from .dispatch import BEFORE_HELLO, EXPOSED, ID_RESULTS, PLATFORM, SESSION_METHODS # noqa: F401 from .mux import HELD_TAGS, HOLD_CAPACITY, EventRouter # noqa: F401 -from .server import API_VERSION, MAX_MESSAGE_SIZE, SERVER_NAME, LocalApiServer # noqa: F401 +from .server import API_VERSION, MAX_MESSAGE_SIZE, SERVER_NAME, LocalApiServer, SocketPathError # noqa: F401 from .session import Session # noqa: F401 __all__ = [ @@ -28,6 +28,7 @@ "Policy", "RpcError", "SERVER_NAME", + "SocketPathError", "SESSION_METHODS", "ServiceOwnership", "Session", diff --git a/bindings/python/offline_protocol_sdk/local_api/cli.py b/bindings/python/offline_protocol_sdk/local_api/cli.py index 0f2de11cf..74ff71fbf 100644 --- a/bindings/python/offline_protocol_sdk/local_api/cli.py +++ b/bindings/python/offline_protocol_sdk/local_api/cli.py @@ -32,7 +32,7 @@ from ..protocol_manager import ProtocolManager from . import codec from .authz import Policy -from .server import LocalApiServer +from .server import LocalApiServer, SocketPathError DEFAULT_STORE_KEY_ENV = "OFFLINE_PROTOCOL_STORE_KEY" DEFAULT_RELAY_TOKEN_ENV = "OFFLINE_PROTOCOL_RELAY_TOKEN" @@ -288,7 +288,10 @@ def main(argv: list[str] | None = None) -> int: server = build_server(args, manager) except ValueError as exc: raise SystemExit(str(exc)) from None - asyncio.run(run(server, http)) + try: + asyncio.run(run(server, http)) + except SocketPathError as exc: + raise SystemExit(f"--socket: {exc}") from None return 0 diff --git a/bindings/python/offline_protocol_sdk/local_api/server.py b/bindings/python/offline_protocol_sdk/local_api/server.py index b57936f49..386d70f42 100644 --- a/bindings/python/offline_protocol_sdk/local_api/server.py +++ b/bindings/python/offline_protocol_sdk/local_api/server.py @@ -24,6 +24,7 @@ import os import secrets import stat +import sys from pathlib import Path from typing import Any @@ -199,6 +200,7 @@ async def start(self) -> None: # Refused before the engine starts: a directory or a path the # server may not use is the operator's to fix, and no reason to # have opened the stores. + _check_socket_path_length(self.socket_path) _prepare_socket_directory(self.socket_path.parent) _remove_stale_socket(self.socket_path) self._manager.on_event(self._on_engine_event) @@ -585,6 +587,29 @@ def _permission_denied(message: str) -> tuple[int, str, dict[str, Any]]: return error.code, error.message, error.data or {} +class SocketPathError(ValueError): + """The socket path or its directory is one the server refuses to use. + + Raised by :meth:`LocalApiServer.start` before the engine comes up, so an + operator's command line can report it as a mistake to fix rather than a + crash. A :class:`ValueError`, as these refusals always were. + """ + + +# `sun_path` holds the path and its terminating NUL: 104 bytes on macOS and +# the BSDs, 108 on Linux. A longer path fails at bind, after the engine has +# opened its stores, with only "AF_UNIX path too long". +_SUN_PATH_MAX = 108 if sys.platform.startswith("linux") else 104 + + +def _check_socket_path_length(path: Path) -> None: + length = len(os.fsencode(path)) + if length >= _SUN_PATH_MAX: + raise SocketPathError( + f"{path} is {length} bytes; a Unix socket path must be under {_SUN_PATH_MAX} on this system" + ) + + def _prepare_socket_directory(directory: Path) -> None: """The socket's directory, owner-only, without touching what the server did not create. @@ -603,13 +628,14 @@ def _prepare_socket_directory(directory: Path) -> None: os.chmod(directory, stat.S_IRWXU) return if not stat.S_ISDIR(found.st_mode): - raise ValueError(f"{directory} exists and is not a directory") + raise SocketPathError(f"{directory} exists and is not a directory") mode = stat.S_IMODE(found.st_mode) if found.st_uid != os.getuid() or mode & 0o077: - raise ValueError( + raise SocketPathError( f"{directory} must be owned by this user with no group or other " f"permissions (found mode {mode:04o}); the server does not narrow a " - "directory it did not create" + f"directory it did not create. Run `chmod 700 {directory}` if it is " + "yours to narrow, or put the socket in a directory of its own" ) @@ -620,5 +646,5 @@ def _remove_stale_socket(path: Path) -> None: except FileNotFoundError: return if not stat.S_ISSOCK(found.st_mode): - raise ValueError(f"{path} exists and is not a socket; refusing to remove it") + raise SocketPathError(f"{path} exists and is not a socket; refusing to remove it") path.unlink() diff --git a/bindings/python/tests/local_api/test_local_api_server.py b/bindings/python/tests/local_api/test_local_api_server.py index 07f37df21..9706f4339 100644 --- a/bindings/python/tests/local_api/test_local_api_server.py +++ b/bindings/python/tests/local_api/test_local_api_server.py @@ -8,6 +8,7 @@ import json import os import stat +from pathlib import Path import pytest import websockets @@ -21,7 +22,7 @@ Policy, ) from offline_protocol_sdk.local_api import codec -from offline_protocol_sdk.local_api.server import FILE_SIZE_LIMIT +from offline_protocol_sdk.local_api.server import FILE_SIZE_LIMIT, SocketPathError from offline_protocol_sdk.protocol_manager import ProtocolManager from .conftest import RpcFailure, make_config @@ -553,12 +554,42 @@ async def test_a_wide_pre_existing_directory_is_refused_and_not_narrowed(harness os.chmod(wide, 0o755) manager = ProtocolManager(make_config(profile="unix-wide")) server = LocalApiServer(manager, socket_path=wide / "api.sock") - with pytest.raises(ValueError, match="no group or other"): + with pytest.raises(SocketPathError, match="no group or other") as err: await server.start() + # The refusal names the fix, and stays a ValueError for older callers. + assert f"chmod 700 {wide}" in str(err.value) + assert isinstance(err.value, ValueError) assert stat.S_IMODE(os.stat(wide).st_mode) == 0o755 assert not (wide / "api.sock").exists() +@pytest.mark.skipif(os.name == "nt", reason="Unix sockets and POSIX modes only") +async def test_a_socket_path_too_long_to_bind_is_refused_before_the_engine_starts(harness): + directory = harness._tmp / ("d" * 120) + manager = ProtocolManager(make_config(profile="unix-long")) + server = LocalApiServer(manager, socket_path=directory / "api.sock") + with pytest.raises(SocketPathError, match="Unix socket path must be under"): + await server.start() + assert not directory.exists(), "refused before anything was created" + + +@pytest.mark.skipif(os.name == "nt", reason="Unix sockets and POSIX modes only") +def test_the_cli_reports_a_refused_socket_directory_without_a_traceback(tmp_path): + import shutil + import tempfile + + # Short enough to bind on macOS, where pytest's own temp path is not. + wide = Path(tempfile.mkdtemp(prefix="op-", dir="/tmp")) + try: + os.chmod(wide, 0o755) + cli, _ = _cli_args(tmp_path) + argv = [*_cli_argv(tmp_path), "--socket", str(wide / "api.sock")] + with pytest.raises(SystemExit, match=r"^--socket: .* `chmod 700 "): + cli.main(argv) + finally: + shutil.rmtree(wide) + + @pytest.mark.skipif(os.name == "nt", reason="Unix sockets and POSIX modes only") async def test_a_regular_file_at_the_socket_path_is_refused_and_kept(harness): directory = harness._tmp / "kept" @@ -738,14 +769,17 @@ def _cli_args(tmp_path, *extra, **config): path = tmp_path / "config.json" path.write_text(json.dumps(fields)) os.environ["OP_TEST_CLI_KEY"] = "ab" * 32 - argv = [ - "--config", str(path), + argv = [*_cli_argv(tmp_path), *extra] + return cli, cli.build_parser().parse_args(argv) + + +def _cli_argv(tmp_path): + return [ + "--config", str(tmp_path / "config.json"), "--mls-root", str(tmp_path / "mls"), "--state-root", str(tmp_path / "state"), "--store-key-env", "OP_TEST_CLI_KEY", - *extra, ] - return cli, cli.build_parser().parse_args(argv) async def test_the_cli_configures_the_gateway_from_its_option(tmp_path): From 7938d57f1a5302e04439116435b926375d2fa1c0 Mon Sep 17 00:00:00 2001 From: Aditi Polkam Date: Mon, 16 Nov 2026 15:08:01 +0530 Subject: [PATCH 2/2] fix(core): skip the lamport flush on drop when storage already holds 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. --- .../offline-protocol/src/protocol/storage.rs | 33 +++++++-- .../src/protocol/tests/mod.rs | 70 +++++++++++++++++++ 2 files changed, 96 insertions(+), 7 deletions(-) diff --git a/crates/offline-protocol/src/protocol/storage.rs b/crates/offline-protocol/src/protocol/storage.rs index e31b4e533..473e0d6de 100644 --- a/crates/offline-protocol/src/protocol/storage.rs +++ b/crates/offline-protocol/src/protocol/storage.rs @@ -5396,10 +5396,20 @@ impl OfflineProtocol { self.write_lamport_clock_to_storage(current); } - /// Forces the Lamport clock to storage regardless of debounce state. - /// Called on shutdown to avoid losing any un-flushed ticks. + /// Writes the Lamport clock to storage regardless of debounce state, when + /// storage does not already hold it. Called on stop, pause and drop so no + /// tick is lost. + /// + /// Skipping a write storage already has is what lets a stopped engine be + /// freed without calling its storage provider: a host frees it whenever + /// its runtime gets round to it, Python during interpreter shutdown, when + /// a provider can no longer run and UniFFI panics on the failed callback. pub(crate) fn flush_lamport_clock(&mut self) { - self.write_lamport_clock_to_storage(self.lamport_clock.value()); + let current = self.lamport_clock.value(); + if current == self.last_persisted_lamport { + return; + } + self.write_lamport_clock_to_storage(current); } fn write_lamport_clock_to_storage(&mut self, value: u64) { @@ -5423,29 +5433,38 @@ impl OfflineProtocol { /// /// Uses `max(current, restored)` so the clock never goes backward even /// if the in-memory value has advanced before storage was attached. + /// `last_persisted_lamport` becomes what this storage holds (zero when it + /// holds nothing usable), not the clock: ticks taken before it was + /// attached are not in it yet, and `flush_lamport_clock` skips a value it + /// believes is stored. pub(crate) fn restore_lamport_clock(&mut self) { let Some(storage) = self.protocol_state_storage.clone() else { return; }; - if let Ok(Some(data)) = self.read_state_record( + match self.read_state_record( storage.as_ref(), storage_keys::LAMPORT_CLOCK, storage_keys::LAMPORT_CLOCK_ID, ) { - if data.len() == 8 { + Ok(Some(data)) if data.len() == 8 => { let restored = u64::from_le_bytes(data.try_into().expect("verified length is 8")); let restored_clock = LamportClock::from_value(restored); if restored_clock > self.lamport_clock { self.lamport_clock = restored_clock; } - self.last_persisted_lamport = self.lamport_clock.value(); + self.last_persisted_lamport = restored; debug!(clock = %self.lamport_clock, "Restored Lamport clock from storage"); - } else { + } + Ok(Some(data)) => { warn!( len = data.len(), "Corrupted Lamport clock in storage (expected 8 bytes), starting fresh" ); + self.last_persisted_lamport = 0; } + Ok(None) => self.last_persisted_lamport = 0, + // Unknown: keep the watermark, as before. + Err(_) => {} } } } diff --git a/crates/offline-protocol/src/protocol/tests/mod.rs b/crates/offline-protocol/src/protocol/tests/mod.rs index 1f51f00ff..17f9b16e4 100644 --- a/crates/offline-protocol/src/protocol/tests/mod.rs +++ b/crates/offline-protocol/src/protocol/tests/mod.rs @@ -21063,6 +21063,76 @@ fn test_lamport_clock_restore_never_goes_backward() { assert_eq!(protocol.lamport_clock.value(), 20); } +#[test] +fn test_a_stopped_protocol_is_dropped_without_writing_the_lamport_clock() { + // A host frees the engine when its runtime decides to (Python during + // interpreter shutdown, when the storage provider can no longer run): a + // stopped engine must have nothing left to write by then. + let storage = Arc::new(InMemoryStorage::new()); + let mut protocol = OfflineProtocol::new(create_test_config()).unwrap(); + let mock_transport = MockTransport::new(TransportType::BLE); + mock_transport.start().unwrap(); + protocol + .transport_manager_mut() + .add_transport(TransportType::BLE, Box::new(mock_transport)); + protocol + .enable_message_persistence_for_test(storage.clone()) + .unwrap(); + protocol.start().unwrap(); + protocol + .send_message("bob", "one", None::, None::) + .unwrap(); + protocol.stop().unwrap(); + assert!(storage + .load(storage_keys::LAMPORT_CLOCK, storage_keys::LAMPORT_CLOCK_ID) + .unwrap() + .is_some()); + + storage + .delete(storage_keys::LAMPORT_CLOCK, storage_keys::LAMPORT_CLOCK_ID) + .unwrap(); + drop(protocol); + assert!( + storage + .load(storage_keys::LAMPORT_CLOCK, storage_keys::LAMPORT_CLOCK_ID) + .unwrap() + .is_none(), + "drop wrote a clock stop() had already stored" + ); +} + +#[test] +fn test_lamport_ticks_taken_before_storage_was_attached_are_flushed() { + let storage = Arc::new(InMemoryStorage::new()); + storage + .store( + storage_keys::LAMPORT_CLOCK, + storage_keys::LAMPORT_CLOCK_ID, + &3u64.to_le_bytes(), + ) + .unwrap(); + { + let mut protocol = OfflineProtocol::new(create_test_config()).unwrap(); + for _ in 0..7 { + protocol.lamport_clock.tick(); + } + protocol + .enable_message_persistence_for_test(storage.clone()) + .unwrap(); + assert_eq!(protocol.lamport_clock.value(), 7); + protocol.flush_lamport_clock(); + } + let mut protocol = OfflineProtocol::new(create_test_config()).unwrap(); + protocol + .enable_message_persistence_for_test(storage.clone()) + .unwrap(); + assert_eq!( + protocol.lamport_clock.value(), + 7, + "storage held 3 before the flush" + ); +} + #[test] fn test_lamport_clock_merge_on_internal_message() { let mut protocol = OfflineProtocol::new(create_test_config()).unwrap();