fskit-rs

A Rust companion to FSKitBridge that provides the protocol & socket layer and a trait for implementing your macOS FSKit backend in Rust.

Requires macOS 15.4+

Why fskit-rs?

FSKit runs file systems in user space on macOS, but its public API is Swift. fskit-rs lets you keep the engine in Rust while FSKitBridge (Swift/appex) handles FSKit/XPC. The two talk over TCP localhost using length-delimited Protobuf messages defined in protocol.proto.

Keep your core in Rust; let FSKitBridge speak Swift to macOS.

FSKitBridge

This crate pairs with the Swift-side FSKitBridge project (host app + FSKitExt appex). For the Swift/FSKit integration details, see:

• Architecture
• How to use
• Tests

What’s in this crate?

• Trait-based backend API: Implement the Filesystem trait to handle file system operations.
• Types & schema (protocol.proto): Common FS/OS types re-exported from code generated by the protocol schema. The schema is the wire contract between the Swift appex and this Rust backend — defining all RPC messages/enums.
• Handle errors: Unified Error (includes POSIX via libc::*) and Result<T>.
• Session runner: session::mount(fs, opts) mounts and serves requests until dropped.
• Installer helpers: install(source), activate(app_name), and uninstall(app_name) utilities for host app lifecycle (optional).

Observed on current macOS versions:

• The installer helpers manage host apps in /Applications/<app name>, which remains the supported installation target for this crate.
• During local experiments, non-/Applications paths may also work after the extension is enabled, but runtime behavior is stateful and not guaranteed across identities, paths, or prior registrations.
• install(source) is intentionally non-destructive: it does not overwrite an existing host app at the final destination and returns AppInstalled instead.
• activate(app_name) verifies the installed app bundle, then re-runs the registration steps whenever the host app is not already active.
• If activation still fails, the error now distinguishes between "not registered", "registered from a different app path", and "registered but not elected" states.
• uninstall(app_name) removes the installed app and also performs best-effort cleanup of related LaunchServices, PlugInKit, Application Scripts, and Containers state for the exact installed bundle identities.

This crate is the transport + protocol + trait layer. You bring the actual file system logic.

Quick start

A minimal example is provided in examples/basic_fs.rs. It starts a stub backend with default MountOptions, mounts the file system (e.g., at /tmp/fskitbridge), and serves requests until you press Ctrl+C. Use it as a skeleton and replace the ENOSYS stubs with your real logic.

License

This project is dual-licensed under Apache-2.0 and MIT:

• Apache License, Version 2.0 — LICENSE-APACHE
• MIT License — LICENSE-MIT

Contributions: Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work shall be dual-licensed as above, without additional terms or conditions.