Module socket 

Cross-platform local socket seam, the owner-tree endpoint over it, and the per-user runtime directory that names both.

v2 keeps every local socket in one machine-level runtime directory: $ONLYNE_RUNTIME_DIR when the operator sets it, /tmp/onlyne-<uid>/ otherwise, created 0700 and adopted only when this process owns it alone. One workspace owns two files there, both named by workspace_digest — the first 16 hex characters of sha256 over the canonical workspace root:

• <digest>.sock: the socket bind_socket_v2 binds and connect_local reaches, 0600.
• <digest>.json: the RegistrationFile naming who serves it — kind, role, root, pid, version, runtime. read_registration, registration_path, and list_registrations are the discovery seam the CLI, the test harness, and external-runtime plugins read instead of walking workspace trees.

v1 kept the socket at <run_dir>/s while that spelling fit sun_path, moved it to a short derived path when it did not, and published the choice in run/socket. A generated role nests deep enough (<root>/.onlyne/ws/<topology>/<role>/.onlyne/run/s) that the canonical spelling passes UNIX_SOCKET_PATH_MAX, so the two-rule answer split one tree across two directories depending on who resolved when. The runtime path is about 40 bytes for any root, so one tree owns one spelling, and <run_dir>/s survives only as SocketEndpoint::natural, the spelling operators and older tooling print.

The unix base is /tmp rather than std::env::temp_dir because a launchd-started daemon and an interactive shell see different TMPDIR and XDG_RUNTIME_DIR values; one fixed base makes every context compute the same path for the same root.

Windows cannot bind a UDS on stable 1.85, so <digest>.sock there is a regular marker file whose contents name an NPFS pipe (v1:onlyne-<32hex>) and the pipe carries the traffic. --socket values that already start with a verbatim pipe path skip derivation and travel as GenericFilePath. Frame I/O stays generic AsyncRead/AsyncWrite.

create_dir, set_dir_mode, and apply_private_mode are the mode half of the same seam: one spelling of “owner-only run/, keys/, and runtime directory” for the daemon that binds and the layout that bootstraps.

Modules

prelude

Traits needed to .accept() / .connect() the interprocess types.

Structs

RegistrationFile

The one file that names a workspace’s endpoint: <runtime>/<digest>.json.

SocketEndpoint

The owner tree’s local socket: the path v2 binds, the canonical spelling v1 bound, the registration that names it, and the root all three derive from.

Enums

LayoutError

Errors produced by the owner-only mode helpers below.

RegistrationKind

Which side of a socket one RegistrationFile describes.

Constants

REGISTRATION_SUFFIX

Registration leaf inside a runtime directory: <digest>.json.

RUNTIME_DIR_ENV

Environment variable that replaces the default runtime directory, used verbatim when set and non-empty.

SOCKET_FILE_NAME

Socket file name inside run/, the canonical spelling every v1 layout path used. v2 binds elsewhere and keeps this only as SocketEndpoint::natural.

SOCKET_SUFFIX

Socket leaf inside a runtime directory: <digest>.sock.

UNIX_SOCKET_PATH_MAX

Bytes available in sun_path on unix, including the trailing NUL. macOS allows 104.

WIRE_VERSION

The version of the wire protocol this crate speaks, the version every RegistrationFile written here carries, so a reader can tell which protocol a live endpoint expects.

Functions

absolute_path

Absolute, symlink-free spelling of a path when it exists, its lexical absolute otherwise.

apply_private_mode

Apply 0600 to an existing private file.

bind_local

Bind a tokio listener at path.

bind_local_sync

Blocking bind, used by CLI tests that serve one frame on a helper thread.

bind_local_sync_poll

Blocking bind whose accept returns WouldBlock when no client is waiting.

bind_socket

Bind the owner tree’s local socket at socket_path in the runtime directory and return it with the endpoint that names it.

bind_socket_registered

Bind the owner tree’s socket and publish reg for it in one call, for a daemon that knows its surface at start.

bind_socket_v2

Bind the owner tree’s socket in the runtime directory.

bind_tokio

Synchronous counterpart of bind_local for the tokio listener type.

connect_local

Connect to the listener that bind_local created for path.

connect_local_sync

Blocking connect matching bind_local_sync.

create_dir

Create a directory, optionally setting its mode.

is_verbatim_pipe_path

true when --socket is already an NPFS path and must not be hashed.

list_registrations

Every registration this machine’s runtime directory holds, sorted by file path.

pipe_name_for

NPFS leaf onlyne-<32hex> derived from path without touching the filesystem.

read_registration

The registration for root, or None when nothing published one.

registration_path

The registration belonging to socket_path’s socket, <runtime_dir>/<workspace_digest>.json.

remove_registration

Remove the registration for root. Removing nothing is not an error.

runtime_dir

The runtime directory, created and owner-verified.

runtime_dir_path

The runtime directory’s spelling without creating or checking anything, so a caller can name a path before any daemon exists (/tmp is one component).

set_dir_mode

socket_path

The socket one workspace owns: <runtime_dir>/<workspace_digest>.sock.

workspace_digest

Identity of one owner tree: sha256 of its canonical spelling, the first 16 lowercase hex characters.

write_registration

Publish reg as the registration for root, creating the runtime directory.

Type Aliases

LocalListener

Tokio listener produced by bind_local.

LocalListenerSync

Blocking listener for tests that cannot run inside a tokio runtime.

LocalStream

Tokio stream produced by connect_local or LocalListener::accept.

LocalStreamSync

Blocking stream matching LocalListenerSync.