Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
29befa3
proto: add the history and restore bodies
Skyfuller1303 Nov 4, 2026
7c7096c
meta: add version history and restore of an old version
Skyfuller1303 Nov 4, 2026
d2a0c0f
server: add the history and restore routes
Skyfuller1303 Nov 4, 2026
2171728
docs: describe version history and restore
Skyfuller1303 Nov 4, 2026
ec83bd7
meta, docs: index the history query and correct the restore note
Skyfuller1303 Nov 4, 2026
48106b5
proto: add the trash bodies
Skyfuller1303 Nov 4, 2026
523ff28
meta: add the trash, with deletion times and a restore that works aro…
Skyfuller1303 Nov 4, 2026
aa7f082
server: add the trash routes and retention.trash_days
Skyfuller1303 Nov 4, 2026
4023e5c
docs: describe the trash
Skyfuller1303 Nov 4, 2026
135688a
meta, proto: bring a file back as a new version and keep restored fol…
Skyfuller1303 Nov 4, 2026
015f2de
sync: do not delete a folder twice after a delete whose answer was lost
Skyfuller1303 Nov 4, 2026
81224f0
docs, server: correct the agent compatibility of the trash restore
Skyfuller1303 Nov 4, 2026
b7e6cb1
sync: judge a folder whose delete was in doubt after the files it hel…
Skyfuller1303 Nov 4, 2026
28d7aa7
sync: settle a lost folder delete deepest first and on a relist
Skyfuller1303 Nov 4, 2026
2aad296
sync: pin folder rules after lost deletes
Skyfuller1303 Nov 4, 2026
1fe8c6c
meta, server: a folder comes back and goes with everything of it in t…
Skyfuller1303 Nov 6, 2026
1dfad98
sync: tests keep a folder alone by taking what is below it out of the…
Skyfuller1303 Nov 6, 2026
b61fcd6
meta: a folder restore or removal takes at most the cap below it, the…
Skyfuller1303 Nov 6, 2026
98020a2
meta tests: name the trash tests' sorting helper sorted_nodes
Skyfuller1303 Nov 6, 2026
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
37 changes: 37 additions & 0 deletions apps/craft-cloud-agent/tests/end_to_end.rs
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,43 @@ async fn a_first_sync_goes_both_ways() {
assert_eq!(a.files(), b.files());
}

/// Deleting a folder with files in it and restoring it from the trash: the folder and everything that was in the trash
/// below it, also a file deleted on its own before, come back to the disk of both computers by their normal pass.
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn a_folder_restored_from_the_trash_comes_back_with_its_files() {
let server = server().await;
let a = Agent::signed_in(&server, "desktop").await;
a.write("dir1/child.txt", "deleted with the folder");
a.write("dir1/early.txt", "deleted first");
a.write("dir1/sub/deep.txt", "deep");
a.write("keep.txt", "stays");
assert_eq!(a.sync().await, Exit::Done);
let b = Agent::signed_in(&server, "laptop").await;
assert_eq!(b.sync().await, Exit::Done);
assert_eq!(b.files().len(), 4);

std::fs::remove_file(a.path("dir1/early.txt")).unwrap();
assert_eq!(a.sync().await, Exit::Done);
std::fs::remove_dir_all(a.path("dir1")).unwrap();
assert_eq!(a.sync().await, Exit::Done);
assert_eq!(b.sync().await, Exit::Done);
assert_eq!(a.files(), ["keep.txt"]);
assert_eq!(b.files(), ["keep.txt"]);

let ana = server.meta.user_by_name("ana").await.unwrap().unwrap();
let listed = server.meta.trash(ana.space, None, 200, 0).await.unwrap().entries;
assert_eq!(listed.iter().map(|e| e.name.as_str()).collect::<Vec<_>>(), ["dir1"], "the folder is listed alone");
let device = server.meta.list_devices(ana.id).await.unwrap().into_iter().find(|d| d.name == "desktop").unwrap().id;
server.meta.restore_from_trash(ana.space, device, listed[0].id, 0).await.unwrap();

for agent in [&a, &b] {
assert_eq!(agent.sync().await, Exit::Done);
assert_eq!(agent.files(), ["dir1/child.txt", "dir1/early.txt", "dir1/sub/deep.txt", "keep.txt"]);
assert_eq!(agent.read("dir1/sub/deep.txt").as_deref(), Some("deep"));
assert_eq!(agent.read("dir1/early.txt").as_deref(), Some("deleted first"));
}
}

#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn big_files_travel_in_chunks_and_keep_their_exec_bit() {
let server = server().await;
Expand Down
133 changes: 131 additions & 2 deletions apps/craft-cloud-server/src/api.rs
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,9 @@ use axum::routing::{delete, get, post, put};
use axum::{Json, Router, middleware};
use craft_cloud_meta::{BlobKind, DeviceAuth, valid_username};
use craft_cloud_proto::api::{
CommitRequest, CommitResponse, DeviceInfo, InfoResponse, LoginRequest, LoginResponse, MAX_MISSING_IDS, MissingRequest, MissingResponse,
PROTOCOL_MAX, PROTOCOL_MIN, SpaceResponse, codes,
CommitRequest, CommitResponse, DeviceInfo, HISTORY_DEFAULT_LIMIT, HistoryCursor, HistoryResponse, InfoResponse, LoginRequest, LoginResponse,
MAX_MISSING_IDS, MissingRequest, MissingResponse, PROTOCOL_MAX, PROTOCOL_MIN, RestoreRequest, RestoreResponse, SpaceResponse,
TRASH_DEFAULT_LIMIT, TrashCursor, TrashItem, TrashResponse, TrashRestoreResponse, codes,
};
use craft_cloud_proto::limits::{MAX_BATCH_JSON_BYTES, MAX_BATCH_OPS, MAX_CHUNK_BYTES, MAX_MANIFEST_BYTES, MAX_PAGE_NODES};
use craft_cloud_proto::{ChangeSet, ChunkId, DeviceId, Manifest, ManifestId, NodeId, PageCursor};
Expand Down Expand Up @@ -56,6 +57,11 @@ pub fn router(state: Shared) -> Router {
.route("/manifests/{id}", put(put_manifest).get(get_manifest).layer(DefaultBodyLimit::max(MAX_MANIFEST_BYTES)))
.route("/commit", post(commit).layer(DefaultBodyLimit::max(MAX_BATCH_JSON_BYTES)))
.route("/saves", post(attach_save).layer(DefaultBodyLimit::max(SMALL_JSON_BYTES)))
.route("/nodes/{id}/history", get(history))
.route("/nodes/{id}/restore", post(restore).layer(DefaultBodyLimit::max(SMALL_JSON_BYTES)))
.route("/trash", get(trash))
.route("/trash/{id}/restore", post(restore_from_trash))
.route("/trash/{id}", delete(remove_from_trash))
.route("/space", get(space))
.route("/tree", get(tree))
.route("/changes", get(changes))
Expand Down Expand Up @@ -385,6 +391,129 @@ async fn attach_save(
Ok(Json(CommitResponse { seq: outcome.seq, epoch: outcome.epoch }))
}

#[derive(Debug, Deserialize)]
struct HistoryQuery {
cursor: Option<String>,
limit: Option<u32>,
}

/// `GET /nodes/{id}/history`: the versions of a file of the caller's own space, newest first. The node is looked
/// up in the space of the device token, so another account's node is `not_found`.
async fn history(
State(state): State<Shared>,
Extension(auth): Extension<DeviceAuth>,
id: Result<Path<NodeId>, PathRejection>,
q: Result<Query<HistoryQuery>, QueryRejection>,
) -> Result<Json<HistoryResponse>, ApiError> {
let Path(node) = id?;
let Query(q) = q?;
let after = q.cursor.as_deref().map(str::parse::<HistoryCursor>).transpose().map_err(|_| ApiError::invalid("bad history cursor"))?;
let page = state.meta.history(auth.space, node, after, q.limit.unwrap_or(HISTORY_DEFAULT_LIMIT)).await?;
Ok(Json(HistoryResponse { versions: page.versions, next: page.next.map(|c| c.to_string()) }))
}

/// `POST /nodes/{id}/restore`: a new version with the content of an old one, as an ordinary update of the file.
async fn restore(
State(state): State<Shared>,
Extension(auth): Extension<DeviceAuth>,
id: Result<Path<NodeId>, PathRejection>,
request: Request,
) -> Result<Json<RestoreResponse>, ApiError> {
let Path(node) = id?;
let req: RestoreRequest = read_json(&state, request, SMALL_JSON_BYTES).await?;
// As a commit: the publish is never skipped for a change that went through.
let task_state = state.clone();
let outcome = tokio::spawn(async move {
let outcome = task_state.meta.restore_version(auth.space, auth.device, node, req.version, req.expected_version, task_state.now_ms()).await?;
task_state.notifier.publish(auth.space, outcome.seq);
Ok::<_, ApiError>(outcome)
})
.await
.map_err(|e| {
tracing::error!(error = %e, "restore task failed");
ApiError::internal()
})??;
Ok(Json(RestoreResponse { version: outcome.version, parent_version: outcome.parent_version, seq: outcome.seq, epoch: outcome.epoch }))
}

const MS_PER_DAY: i64 = 86_400_000;

#[derive(Debug, Deserialize)]
struct TrashQuery {
cursor: Option<String>,
limit: Option<u32>,
}

/// `GET /trash`: the deleted nodes of the caller's own space, newest deletion first.
async fn trash(
State(state): State<Shared>,
Extension(auth): Extension<DeviceAuth>,
q: Result<Query<TrashQuery>, QueryRejection>,
) -> Result<Json<TrashResponse>, ApiError> {
let Query(q) = q?;
let after = q.cursor.as_deref().map(str::parse::<TrashCursor>).transpose().map_err(|_| ApiError::invalid("bad trash cursor"))?;
let page = state.meta.trash(auth.space, after, q.limit.unwrap_or(TRASH_DEFAULT_LIMIT), state.now_ms()).await?;
if page.repaired > 0 {
tracing::warn!(count = page.repaired, "deleted nodes without a deletion time were stamped with the current time");
}
let keep = i64::from(state.trash_days).saturating_mul(MS_PER_DAY);
let items = page
.entries
.into_iter()
.map(|e| TrashItem {
id: e.id,
parent: e.parent,
name: e.name,
is_dir: e.is_dir,
size: e.size,
deleted_ms: e.deleted_ms,
purge_after_ms: e.deleted_ms.saturating_add(keep),
})
.collect();
Ok(Json(TrashResponse { items, next: page.next.map(|c| c.to_string()) }))
}

/// `POST /trash/{id}/restore`: a deleted node of the caller's space comes back, in one change.
async fn restore_from_trash(
State(state): State<Shared>,
Extension(auth): Extension<DeviceAuth>,
id: Result<Path<NodeId>, PathRejection>,
) -> Result<Json<TrashRestoreResponse>, ApiError> {
let Path(node) = id?;
// As a commit: the publish is never skipped for a change that went through.
let task_state = state.clone();
let outcome = tokio::spawn(async move {
let outcome = task_state.meta.restore_from_trash(auth.space, auth.device, node, task_state.now_ms()).await?;
task_state.notifier.publish(auth.space, outcome.seq);
Ok::<_, ApiError>(outcome)
})
.await
.map_err(|e| {
tracing::error!(error = %e, "trash restore task failed");
ApiError::internal()
})??;
Ok(Json(TrashRestoreResponse {
node: outcome.node,
parent: outcome.parent,
name: outcome.name,
renamed: outcome.renamed,
version: outcome.version,
seq: outcome.seq,
epoch: outcome.epoch,
}))
}

/// `DELETE /trash/{id}`: takes a deleted node out of the trash. Only marks it: nothing is freed.
async fn remove_from_trash(
State(state): State<Shared>,
Extension(auth): Extension<DeviceAuth>,
id: Result<Path<NodeId>, PathRejection>,
) -> Result<StatusCode, ApiError> {
let Path(node) = id?;
state.meta.request_purge(auth.space, node, state.now_ms()).await?;
Ok(StatusCode::NO_CONTENT)
}

fn cursor(after_seq: Option<u64>, after_node: Option<NodeId>) -> Result<Option<PageCursor>, ApiError> {
match (after_seq, after_node) {
(Some(seq), Some(node)) => Ok(Some(PageCursor { seq, node })),
Expand Down
52 changes: 52 additions & 0 deletions apps/craft-cloud-server/src/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@
//! # live_bytes_per_user = 1_073_741_824 # cap on what one account's live documents hold, in bytes (1 GiB)
//! # public_url = "https://cloud.example.com" # where computers reach the server; `user invite` prints it
//!
//! # [retention]
//! # trash_days = 30 # how long a deleted file stays in the trash before the server may remove it (1 to 3650)
//!
//! [database]
//! url = "sqlite:/var/lib/craft-cloud/meta.db" # or postgres://user:pass@host/db
//!
Expand Down Expand Up @@ -55,12 +58,39 @@ pub enum ConfigError {
agent could not tell a full account from a file that is too big. Raise it, or remove it for no cap"
)]
StoredBytesCapTooSmall(u64, u32),
#[error("retention.trash_days = {0} is not between {MIN_TRASH_DAYS} and {MAX_TRASH_DAYS}")]
TrashDays(u32),
#[error("public_url = {0:?} is not a server address like https://cloud.example.com (a host, an optional port and path, no query)")]
PublicUrl(String),
#[error("storage.{0} is missing (set it in the config or the {1} environment variable)")]
MissingS3Credential(&'static str, &'static str),
}

/// Fewest and most days a deleted node waits in the trash.
pub const MIN_TRASH_DAYS: u32 = 1;
pub const MAX_TRASH_DAYS: u32 = 3650;
/// Days in the trash when `retention.trash_days` is not set.
pub const DEFAULT_TRASH_DAYS: u32 = 30;

/// `[retention]`: how long things are kept. Only the trash today; nothing is removed by it yet.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RetentionConfig {
/// Days a deleted node stays in the trash before the server may remove it for good (shown as `purge_after_ms`).
#[serde(default = "default_trash_days")]
pub trash_days: u32,
}

impl Default for RetentionConfig {
fn default() -> Self {
Self { trash_days: DEFAULT_TRASH_DAYS }
}
}

fn default_trash_days() -> u32 {
DEFAULT_TRASH_DAYS
}

#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Config {
Expand Down Expand Up @@ -90,6 +120,8 @@ pub struct Config {
/// trailing slash. Unset: `user invite` prints the bare code and says to put the address in front.
#[serde(default)]
pub public_url: Option<String>,
#[serde(default)]
pub retention: RetentionConfig,
pub database: DatabaseConfig,
pub storage: StorageConfig,
}
Expand Down Expand Up @@ -186,6 +218,9 @@ impl Config {
{
return Err(ConfigError::StoredBytesCapTooSmall(cap, MAX_CHUNK_BYTES));
}
if !(MIN_TRASH_DAYS..=MAX_TRASH_DAYS).contains(&config.retention.trash_days) {
return Err(ConfigError::TrashDays(config.retention.trash_days));
}
let mut config = config;
if let Some(url) = &config.public_url {
config.public_url = Some(public_url(url)?);
Expand Down Expand Up @@ -323,6 +358,23 @@ path = "/tmp/blobs"
assert!(matches!(Config::parse(&no_proxy), Err(ConfigError::IgnoreForwardedForMisplaced)));
}

#[test]
fn the_trash_period_has_a_default_and_bounds() {
assert_eq!(Config::parse(DISK).unwrap().retention, RetentionConfig { trash_days: 30 });
// A table has to come after the top-level keys, so the section goes at the end.
let at_end = |days: &str| Config::parse(&format!("{DISK}\n[retention]\ntrash_days = {days}\n"));
assert_eq!(at_end("1").unwrap().retention.trash_days, 1);
assert_eq!(at_end("3650").unwrap().retention.trash_days, 3650);
for bad in ["0", "3651", "-1", "\"30\"", "1.5"] {
assert!(at_end(bad).is_err(), "{bad}");
}
assert!(matches!(at_end("0"), Err(ConfigError::TrashDays(0))));
assert!(matches!(at_end("3651"), Err(ConfigError::TrashDays(3651))));
// Nothing but `trash_days` is accepted in the section, and the section may be empty.
assert!(matches!(Config::parse(&format!("{DISK}\n[retention]\ngc_wait_hours = 24\n")), Err(ConfigError::Parse(_))));
assert_eq!(Config::parse(&format!("{DISK}\n[retention]\n")).unwrap().retention.trash_days, 30);
}

#[test]
fn unknown_keys_are_errors() {
assert!(matches!(Config::parse(&format!("lisen = 1\n{DISK}")), Err(ConfigError::Parse(_))));
Expand Down
2 changes: 1 addition & 1 deletion apps/craft-cloud-server/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ async fn run_server(config_path: &std::path::Path) -> Result<(), String> {
tracing::warn!("ignore_forwarded_for is set: every client shares one address for sign-in rate limits");
}
let (meta, store) = open(&config).await.map_err(|e| e.to_string())?;
let state = AppState::new(meta, store, config.trusted_proxies.clone()).map_err(|e| e.message)?;
let state = AppState::new(meta, store, config.trusted_proxies.clone()).map_err(|e| e.message)?.with_trash_days(config.retention.trash_days);
let listener = tokio::net::TcpListener::bind(config.listen).await.map_err(|e| format!("can't listen on {}: {e}", config.listen))?;
tracing::info!(listen = %config.listen, behind_proxy = config.behind_proxy, "Craft Cloud server running");
let shutdown = async {
Expand Down
9 changes: 9 additions & 0 deletions apps/craft-cloud-server/src/state.rs
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,8 @@ pub struct AppState {
pub(crate) touches: Mutex<HashMap<DeviceId, i64>>,
/// Verified against when the username doesn't exist, so both cases cost the same.
pub dummy_hash: String,
/// Days a deleted node stays in the trash before the server may remove it (`retention.trash_days`).
pub trash_days: u32,
/// The time of day for everything a request records (a device's last use, a stored blob, a commit).
clock: Clock,
}
Expand All @@ -143,6 +145,7 @@ impl AppState {
limits,
touches: Mutex::new(HashMap::new()),
dummy_hash: hash_password("craft-cloud dummy password")?,
trash_days: 30,
clock: Arc::new(now_ms),
})
}
Expand All @@ -156,6 +159,12 @@ impl AppState {
self
}

/// The state with another trash period in days (`retention.trash_days`; the default is 30).
pub fn with_trash_days(mut self, days: u32) -> Self {
self.trash_days = days;
self
}

/// The state with another clock: a simulation's, so that what requests record and when a device's last use is
/// written again follow simulated time, never the real one. A test seam (the `test-support` feature).
#[cfg(feature = "test-support")]
Expand Down
Loading