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
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

36 changes: 18 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
</p>

<p align="center">
<a href="https://github.com/emulebb/emulebb-tooling/blob/f88a8ce608bc75a619aea6909f54a9cdecdddb6e/docs/products/emulebb-rust/reference/GUIDE-GETTING-STARTED.md"><strong>Use eMuleBB Rust</strong></a> &nbsp;&middot;&nbsp;
<a href="https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/reference/GUIDE-GETTING-STARTED/"><strong>Use eMuleBB Rust</strong></a> &nbsp;&middot;&nbsp;
<a href="https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/reference/GUIDE-CONTRIBUTING/"><strong>Develop with eMuleBB Rust</strong></a>
</p>
<p align="center">
Expand Down Expand Up @@ -58,34 +58,34 @@ channel. Prebuilt packages need no Rust toolchain.

Choose a runnable asset from the [nightly releases](https://github.com/emulebb/emulebb-rust/releases),
then compare its exact filename against that release's `SHA256SUMS`.
The [platform run guide](https://github.com/emulebb/emulebb-tooling/blob/f88a8ce608bc75a619aea6909f54a9cdecdddb6e/docs/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS.md)
The [platform run guide](https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS/)
owns installation commands, profile paths, requirements and qualification scope.

| Platform | Choose | Install and run |
| --- | --- | --- |
| Windows | x64 or ARM64 ZIP | [Extract and launch](https://github.com/emulebb/emulebb-tooling/blob/f88a8ce608bc75a619aea6909f54a9cdecdddb6e/docs/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS.md#windows-x64-and-arm64) |
| Linux | x64 or ARM64 DEB, AppImage or static-musl tar/zstd | [Choose a Linux variant](https://github.com/emulebb/emulebb-tooling/blob/f88a8ce608bc75a619aea6909f54a9cdecdddb6e/docs/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS.md#linux) |
| macOS | Intel or Apple Silicon DMG | [Copy and launch the app](https://github.com/emulebb/emulebb-tooling/blob/f88a8ce608bc75a619aea6909f54a9cdecdddb6e/docs/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS.md#macos-intel-and-apple-silicon) |
| Docker / OCI | Linux amd64 or arm64; Ubuntu or Alpine | [Run with persistent volumes](https://github.com/emulebb/emulebb-tooling/blob/f88a8ce608bc75a619aea6909f54a9cdecdddb6e/docs/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS.md#containers) |
| Android APK | Universal ARM64 + x86_64; Android 12+ | [Permissions, manual Start and WebUI](https://github.com/emulebb/emulebb-tooling/blob/f88a8ce608bc75a619aea6909f54a9cdecdddb6e/docs/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS.md#android-application) |
| Android / Termux native | Experimental `android-arm64-v8a.tar.zst` or `android-x86_64.tar.zst` | [Extract under private HOME and launch](https://github.com/emulebb/emulebb-tooling/blob/f88a8ce608bc75a619aea6909f54a9cdecdddb6e/docs/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS.md#termux-native-shell) |
| Windows | x64 or ARM64 ZIP | [Extract and launch](https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS/#windows-x64-and-arm64) |
| Linux | x64 or ARM64 DEB, AppImage or static-musl tar/zstd | [Choose a Linux variant](https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS/#linux) |
| macOS | Intel or Apple Silicon DMG | [Copy and launch the app](https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS/#macos-intel-and-apple-silicon) |
| Docker / OCI | Linux amd64 or arm64; Ubuntu or Alpine | [Run with persistent volumes](https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS/#containers) |
| Android APK | Universal ARM64 + x86_64; Android 12+ | [Permissions, manual Start and WebUI](https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS/#android-application) |
| Android / Termux native | Experimental `android-arm64-v8a.tar.zst` or `android-x86_64.tar.zst` | [Extract under private HOME and launch](https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS/#termux-native-shell) |

The macOS app is unsigned and not notarized. For containers, both
[`ghcr.io/emulebb/emulebb-rust`](https://github.com/emulebb/emulebb-rust/pkgs/container/emulebb-rust)
variants publish versioned tags and moving `nightly` / `nightly-ubuntu` /
`nightly-alpine` aliases; there is no `latest` tag.

**Android remains experimental.** Use the signed APK only when the selected
published release includes it after qualification. Both native ABI archives
remain separate public nightly assets alongside that APK. Their API 28 binary
floor and compile/ELF evidence do not qualify Termux runtime, the full Android
API matrix, Fire OS or 24-hour continuous operation. The APK minimum is Android
12/API 31; its foreground service starts manually and has no boot-resume option.
See [Android evidence and remaining acceptance](https://github.com/emulebb/emulebb-tooling/blob/f88a8ce608bc75a619aea6909f54a9cdecdddb6e/docs/products/emulebb-rust/active/items/RUST-FEAT-056.md).
**Android remains experimental.** The nightly release contract includes the
signed Android 12+ APK and both native archives, `android-arm64-v8a.tar.zst`
and `android-x86_64.tar.zst`. Follow the platform guide for installation and
manual foreground-service start, including after reboot. The native archives
target API 28 for compilation; compile and ELF checks do not qualify Termux or
Fire OS runtime. Termux runtime, Fire OS, automatic boot-resume and 24-hour
endurance remain unqualified. See [Android evidence and remaining acceptance](https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/active/items/RUST-FEAT-056/).

## Get started

1. Follow your [platform's run instructions](https://github.com/emulebb/emulebb-tooling/blob/f88a8ce608bc75a619aea6909f54a9cdecdddb6e/docs/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS.md).
1. Follow your [platform's run instructions](https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/reference/GUIDE-DOWNLOADS-PLATFORMS/).
Keep the complete extracted archive layout, including `webui`.
2. Open **<http://127.0.0.1:20017/>** on the daemon host. The default listener
is **`0.0.0.0:20017`**. Native packages use the ready key
Expand All @@ -103,7 +103,7 @@ settings; mutable client settings live in the profile database.
Startup may fetch discovery inputs and start configured networking. During beta,
an incompatible database requires an entirely fresh profile; preserve the
stopped old profile, payloads and matching binary for rollback. The
[getting-started guide](https://github.com/emulebb/emulebb-tooling/blob/f88a8ce608bc75a619aea6909f54a9cdecdddb6e/docs/products/emulebb-rust/reference/GUIDE-GETTING-STARTED.md)
[getting-started guide](https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/reference/GUIDE-GETTING-STARTED/)
covers everyday operation, shutdown and troubleshooting.

## Use the API
Expand Down Expand Up @@ -144,7 +144,7 @@ this trust set. Updated roots arrive with new client builds.

## Help and security

- [Troubleshoot startup, listeners and logs](https://github.com/emulebb/emulebb-tooling/blob/f88a8ce608bc75a619aea6909f54a9cdecdddb6e/docs/products/emulebb-rust/reference/GUIDE-GETTING-STARTED.md#common-problems).
- [Troubleshoot startup, listeners and logs](https://emulebb.github.io/emulebb-tooling/products/emulebb-rust/reference/GUIDE-GETTING-STARTED/#common-problems).
- [Report a bug](https://github.com/emulebb/emulebb-rust/issues) with the package
version and sanitized reproduction steps.
- Follow [private security reporting](SECURITY.md) for vulnerabilities.
Expand Down
6 changes: 3 additions & 3 deletions crates/emulebb-daemon/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ impl DaemonProfile {
let opened = match host_folders {
Some((incoming, shared)) => MetadataStore::open_with_profile_lease_and_storage(
metadata_path,
profile_lease.file(),
profile_lease.guard(),
move || {
anyhow::ensure!(
incoming.is_absolute() && shared.is_absolute(),
Expand All @@ -209,7 +209,7 @@ impl DaemonProfile {
})
},
),
None => MetadataStore::open_with_profile_lease(metadata_path, profile_lease.file()),
None => MetadataStore::open_with_profile_lease(metadata_path, profile_lease.guard()),
};
let metadata = opened.with_context(|| {
format!(
Expand Down Expand Up @@ -267,7 +267,7 @@ impl DaemonProfile {
.context("load the profile before opening writable metadata")?;
MetadataStore::open_with_profile_lease(
lease.directory().join(PROFILE_METADATA_FILE),
lease.file(),
lease.guard(),
)
}

Expand Down
19 changes: 10 additions & 9 deletions crates/emulebb-daemon/src/profile_ownership.rs
Original file line number Diff line number Diff line change
@@ -1,25 +1,26 @@
//! OS-backed ownership of a writable profile, retained by all metadata handles.

use std::{
fs::{self, File, OpenOptions, TryLockError},
fs::{self, OpenOptions, TryLockError},
path::{Path, PathBuf},
sync::Arc,
};

use anyhow::{Context, Result, bail, ensure};
use emulebb_metadata::ProfileLeaseGuard;

const PROFILE_LEASE_FILE: &str = ".emulebb-profile.lock";

/// An opaque, cloneable lease for one physical profile directory.
///
/// The persistent empty file is a lock target, not an ownership marker. Never
/// remove it on release: the operating system releases ownership when the last
/// handle closes, including after process death. Locks must be supported by the
/// selected filesystem; an unsupported/failed lock is an error, never a bypass.
/// remove it on release: the final logical owner unlocks its acquired descriptor,
/// and the operating system releases ownership after process death. Locks must
/// be supported by the selected filesystem; a failed lock is never a bypass.
#[derive(Debug, Clone)]
pub struct ProfileLease {
directory: PathBuf,
file: Arc<File>,
guard: Arc<ProfileLeaseGuard>,
}

impl ProfileLease {
Expand Down Expand Up @@ -63,8 +64,8 @@ impl ProfileLease {
profile.display()
)
})?;
match file.try_lock() {
Ok(()) => Ok(Self { directory: canonical_profile, file: Arc::new(file) }),
match ProfileLeaseGuard::try_lock(file) {
Ok(guard) => Ok(Self { directory: canonical_profile, guard: Arc::new(guard) }),
Err(TryLockError::WouldBlock) => bail!(
"profile is already in use: {}; stop its daemon or offline command before retrying",
profile.display()
Expand All @@ -82,8 +83,8 @@ impl ProfileLease {
&self.directory
}

pub(crate) fn file(&self) -> Arc<File> {
Arc::clone(&self.file)
pub(crate) fn guard(&self) -> Arc<ProfileLeaseGuard> {
Arc::clone(&self.guard)
}
}

Expand Down
15 changes: 15 additions & 0 deletions crates/emulebb-daemon/tests/profile_ownership.rs
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,21 @@ fn unrelated_profiles_can_be_owned_concurrently() {
second.finish();
}

#[test]
fn profile_clones_and_metadata_handles_share_one_logical_lease() {
let temporary = temporary();
let path = temporary.path().join("profile");
let profile = DaemonProfile::load_for_import(path.clone()).unwrap();
let cloned = profile.clone();
let metadata = profile.open_metadata_store().unwrap();
drop(profile);
probe(&path, "busy", &temporary.path().join("profile-clone"));
drop(cloned);
probe(&path, "busy", &temporary.path().join("metadata"));
drop(metadata);
probe(&path, "available", &temporary.path().join("released"));
}

#[test]
#[ignore = "isolated subprocess fixture invoked by the ownership regression tests"]
fn profile_ownership_child() {
Expand Down
3 changes: 3 additions & 0 deletions crates/emulebb-metadata/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,6 @@ hex.workspace = true
rusqlite.workspace = true
unicode-normalization.workspace = true
uuid.workspace = true

[target.'cfg(unix)'.dev-dependencies]
libc.workspace = true
2 changes: 2 additions & 0 deletions crates/emulebb-metadata/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ mod peer_model;
mod peer_store;
mod profile_import;
mod profile_model;
mod profile_ownership;
mod profile_store;
mod schema;
mod schema_validation;
Expand Down Expand Up @@ -51,6 +52,7 @@ pub use native_file::{NativeFileFingerprint, NativeFileIdentity, NativeFileTimes
pub use native_path::NativePath;
pub use peer_model::MetadataPeerCredit;
pub use profile_model::{MetadataCategory, MetadataFriend, MetadataServer};
pub use profile_ownership::ProfileLeaseGuard;
pub use schema::{SCHEMA_ID, SCHEMA_SQL, SCHEMA_VERSION};
pub use search_model::{
MetadataSearch, MetadataSearchResult, MetadataSearchResultObservation, MetadataSearchSpec,
Expand Down
39 changes: 39 additions & 0 deletions crates/emulebb-metadata/src/profile_ownership.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
//! Descriptor ownership shared by profile loaders and their metadata handles.

use std::fs::{File, TryLockError};

/// An acquired exclusive profile lock, shared through `Arc` by logical owners.
///
/// Release never removes the persistent lock file. The acquiring process
/// explicitly unlocks its descriptor when the final owner drops, so transient
/// descriptors inherited by a spawning child cannot prolong profile ownership.
#[derive(Debug)]
pub struct ProfileLeaseGuard {
file: File,
acquisition_pid: u32,
}

impl ProfileLeaseGuard {
/// Acquire the supplied lock-file descriptor without waiting.
///
/// Contention, unsupported locks, and other I/O failures remain errors.
/// Only a successfully acquired descriptor becomes an owned guard.
pub fn try_lock(file: File) -> Result<Self, TryLockError> {
file.try_lock()?;
Ok(Self {
file,
acquisition_pid: std::process::id(),
})
}
}

impl Drop for ProfileLeaseGuard {
fn drop(&mut self) {
// WHY: a fork/spawn can temporarily retain the same open-file description
// after the final logical owner drops. Unlock that acquired descriptor
// explicitly, but never let an inherited child unlock its parent's lease.
if self.acquisition_pid == std::process::id() {
let _ = self.file.unlock();
}
}
}
13 changes: 8 additions & 5 deletions crates/emulebb-metadata/src/store.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
use std::{
fs::File,
path::{Path, PathBuf},
sync::{Arc, Mutex, MutexGuard, TryLockError},
time::{SystemTime, UNIX_EPOCH},
Expand All @@ -10,6 +9,7 @@ use rusqlite::{Connection, OptionalExtension, params};
use uuid::Uuid;

use crate::{
ProfileLeaseGuard,
model::{MetadataIndexedFile, MetadataIndexedFileOrigin, MetadataSharedDirectoryRoot},
native_path::{NativePath, current_platform},
schema::{SCHEMA_ID, SCHEMA_SQL, SCHEMA_VERSION},
Expand All @@ -34,7 +34,7 @@ pub struct MetadataStore {
conn: Arc<Mutex<Connection>>,
// WHY: close the connection before releasing its process profile lease.
// Clones retain both handles; independent profile connections share the lease.
_profile_lease: Option<Arc<File>>,
_profile_lease: Option<Arc<ProfileLeaseGuard>>,
initialized_new_schema: bool,
}

Expand All @@ -48,7 +48,10 @@ impl MetadataStore {
///
/// The caller acquires the lock before bootstrap/metadata initialization.
/// Every cloned store retains it until its connection has finished closing.
pub fn open_with_profile_lease(path: impl AsRef<Path>, lease: Arc<File>) -> Result<Self> {
pub fn open_with_profile_lease(
path: impl AsRef<Path>,
lease: Arc<ProfileLeaseGuard>,
) -> Result<Self> {
let conn = Connection::open(path)?;
Self::from_connection_with_profile_lease(conn, Some(lease), None)
}
Expand All @@ -57,7 +60,7 @@ impl MetadataStore {
/// never called for an existing schema, including an empty operator root list.
pub fn open_with_profile_lease_and_storage(
path: impl AsRef<Path>,
lease: Arc<File>,
lease: Arc<ProfileLeaseGuard>,
initialize: impl FnOnce() -> Result<InitialProfileStorage> + 'static,
) -> Result<Self> {
Self::from_connection_with_profile_lease(
Expand All @@ -82,7 +85,7 @@ impl MetadataStore {

fn from_connection_with_profile_lease(
conn: Connection,
profile_lease: Option<Arc<File>>,
profile_lease: Option<Arc<ProfileLeaseGuard>>,
initialize_storage: Option<StorageInitializer>,
) -> Result<Self> {
// The guarded constructor retains ownership before any pragma/schema
Expand Down
Loading
Loading