Crate blit_fssync 

Filesystem state sync engine (docs/fs-watch.md).

The server side of FEATURE_FS, split in two:

• A shared root per watched (path, recursive, cross_filesystem), refcounted across every sync of that root on every connection: one native watcher, one hint-driven reconciler owning the canonical metadata index, publishing immutable Arc<Index> snapshots.
• A per-sync engine holding only client state: the shadow snapshot (what the client holds), the held-content map for delta bases, the ack window, and staged RESET … SYNC update assembly.

Content flows through the process-wide content-addressed blob store: once any sync reads and hashes a file, the reconciler adopts the hash and every other sync serves those bytes from memory. Native backends deliver hints (a path may have changed / rescan everything); all protocol-visible behavior lives here, so the three platforms behave identically by construction.

Re-exports

pub use ignores::IgnoreSpec;

pub use ignores::MAX_PATTERNS as MAX_IGNORE_PATTERNS;

Modules

backend

Native watch backend via the notify crate (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows), demoted to a dirty-set hint source: every event becomes Hint::Dirty(path) and every loss signal — overflow, rescan flag, backend error — degrades to Hint::Rescan. No backend behavior is client-visible; the engine verifies everything against the filesystem before emitting.

ignores

Configurable exclusion for a synced root (docs/design/fs-watch.md “Ignoring”).

Structs

BlobStore

Content-addressed LRU cache of file bytes, keyed by BLAKE3-128 and shared by every sync in the process: identical files cost one entry, and delta bases are found by the hash each engine recorded for the content its client holds. Eviction only costs efficiency — a missing base falls back to full content.

HintSender

Wrap the reconciler inbox for a hint source (native backend or test).

InflightGuard

Per-connection in-flight write accounting. The server inserts a request’s nonce before dispatch — rejecting a duplicate (INVALID) or an over-cap request (BUDGET) — and attaches this guard to the request; the engine drops it once the request is answered, removing the nonce and freeing a slot. Bounds the otherwise-unbounded engine channel depth (and thus resident inbound content) to the in-flight cap.

NodeMeta

NoopBackend

OpReq

A metadata op forwarded to the engine. op is FS_OP_*; a/b are escaped wire paths (b empty except for RENAME).

RootKey

Identity of a shared root. Enumeration scope is part of the identity: recursive and non-recursive syncs of the same directory index different trees and cannot share a reconciler — and neither do two syncs that exclude different things, for exactly the same reason.

SharedRootHandle

A shared root: keeps the native watcher armed and the reconciler reachable. Engines hold an Arc; when the last one drops, the watcher disarms, the reconciler’s inbox disconnects, and its thread exits.

SyncHandle

Handle owned by the client connection. Dropping it stops the engine (and, transitively, releases its share of the root).

SyncOptions

WriteReq

A content write forwarded to the engine (docs/design/fs-write.md). path is the escaped wire path; flags are FS_WRITE_*.

Enums

Command

Commands forwarded from the client connection.

DiffOp

Hint

A hint from a native backend. Hints are unreliable and duplicated; the reconciler verifies everything against the filesystem before emitting.

ReadOutcome

Traits

BackendHandle

Registration interface a backend exposes to the reconciler so the set of watched directories tracks the set of indexed ones (inotify, where a recursive watch is a descriptor per directory and an excluded subtree would otherwise still cost them all). FSEvents/RDCW cover a tree with one object and use the no-op default, as does any unfiltered root.

Functions

blake3_128

BLAKE3 truncated to 128 bits, little-endian — the protocol-wide content hash (docs/design/fs-watch.md). pub so sibling stores (the KV store, docs/design/kv.md) share the one convention instead of re-deriving it.

blob_store

The process-wide store; budget via BLIT_FS_BLOB_MAX (default 256 MiB).

diff

Compute ops that transform prev into curr.

encode_delta

Single-span delta: the longest common prefix and suffix become COPYs, the middle an INSERT. Covers appends, prepends, truncations, and one contiguous in-place edit — the common shapes of saved files and logs. Scattered edits degrade to a large INSERT; the caller falls back to full content when the encoding is not clearly smaller.

escape_bytes

escape_path

Escape a whole path for wire use (e.g. the FS_SYNCED canonical-root detail): same scheme as components, separators left intact.

escape_wide

Escape UTF-16 code units (Windows names): valid text passes through (% → %25), unpaired surrogates become %uXXXX. A literal %u in a name escapes to %25u, so the forms never collide. Pure so every host can test it; cfg(windows) wires it to OsStr.

open_root

Open (or join) the shared root for key, arming a native watcher on first open — before the initial enumeration, so nothing slips between scan and event delivery. On failure returns an FS_STATUS_* code plus diagnostic, so the server can answer FS_SYNCED accurately.

open_root_unwatched

Open (or join) a shared root without a native watcher; hints come from SharedRootHandle::hint_sender. For tests and embedders.

open_single_root

Open (or join) the shared root for an FS_SYNC_SINGLE sync of path (a canonical FILE path from validate_single_root). The native watch arms on the file’s PARENT directory, non-recursive — a watch on the file itself would follow its inode and go silent after a delete or a rename-over, exactly the transitions a single-file sync must deliver. recursive/cross_filesystem/ignores do not apply (nothing is enumerated — the client named the one file it wants), so every SINGLE sync of one file shares a single normalized key.

open_single_root_unwatched

open_single_root without a native watcher; hints come from SharedRootHandle::hint_sender. For tests and embedders.

read_verified

[read_verified_meta] without the stat, for fetch responses and tests.

resolve_wire_path

Resolve a wire path (relative, ‘/’-separated, escaped) against a root. Rejects traversal — the result always stays under the root.

start_sync

Spawn a sync engine subscribed to shared, streaming to outbox. The engine’s initial RESET … SYNC series is cut from the root’s current snapshot — later syncs of an already-watched root never rescan.

unescape_to_bytes

Reverse escape_bytes. Returns None on malformed escapes.

unescape_to_wide

Reverse escape_wide: %uXXXX → one code unit, %XX → one unit below 0x100 (covers %25), everything else re-encoded as UTF-16.

validate_root

Validate and canonicalize a requested root. Returns the canonical path or an FS_STATUS_* code plus diagnostic.

validate_single_root

Validate and canonicalize an FS_SYNC_SINGLE root: the same canonicalization as validate_root, plus the path must not be a directory — a directory root answers the existing invalid-path error (docs/design/fs-watch.md “Single-file sync”). Canonicalization resolves symlinks, so the returned path is the file itself, never a link to it.

Type Aliases

Outbox

Messages the engine emits, ready for the client outbox. Returns false when the client is gone; the engine then exits.