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): 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();