Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion bindings/python/offline_protocol_sdk/local_api/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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__ = [
Expand All @@ -28,6 +28,7 @@
"Policy",
"RpcError",
"SERVER_NAME",
"SocketPathError",
"SESSION_METHODS",
"ServiceOwnership",
"Session",
Expand Down
7 changes: 5 additions & 2 deletions bindings/python/offline_protocol_sdk/local_api/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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


Expand Down
34 changes: 30 additions & 4 deletions bindings/python/offline_protocol_sdk/local_api/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
import os
import secrets
import stat
import sys
from pathlib import Path
from typing import Any

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Expand All @@ -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"
)


Expand All @@ -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()
46 changes: 40 additions & 6 deletions bindings/python/tests/local_api/test_local_api_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
import json
import os
import stat
from pathlib import Path

import pytest
import websockets
Expand All @@ -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
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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):
Expand Down
33 changes: 26 additions & 7 deletions crates/offline-protocol/src/protocol/storage.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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(_) => {}
}
}
}
Expand Down
70 changes: 70 additions & 0 deletions crates/offline-protocol/src/protocol/tests/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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::<MessagePriority>, None::<String>)
.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();
Expand Down
Loading