Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
38 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
f2f51b1
meta: add the reference index of what each manifest names
Skyfuller1303 Nov 4, 2026
d0ff336
server: add verify and index build, and finish a manifest's index bef…
Skyfuller1303 Nov 4, 2026
b70886d
docs: describe the reference index and verify
Skyfuller1303 Nov 4, 2026
54ff35c
meta: find negative ordinals and reset an index in bounded batches
Skyfuller1303 Nov 4, 2026
d7c6898
server, meta, store: verify only an existing server and check the siz…
Skyfuller1303 Nov 4, 2026
c8725af
test: cover reference index edge cases
Skyfuller1303 Nov 4, 2026
1f9610a
meta, server: make the reference index edge-case tests prove what the…
Skyfuller1303 Nov 4, 2026
84599b5
meta, server: open an existing SQLite database read-only so verify ca…
Skyfuller1303 Nov 5, 2026
25c859d
meta: add account storage estimates
Skyfuller1303 Nov 5, 2026
7b46036
proto, server: expose account usage route
Skyfuller1303 Nov 5, 2026
17968bc
docs: document account usage estimates
Skyfuller1303 Nov 5, 2026
205bafd
meta: leave saved versions out of the history estimate
Skyfuller1303 Nov 5, 2026
6913574
server, docs: describe the quota override without naming a pull request
Skyfuller1303 Nov 5, 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
2ddd75d
Merge trash: a folder comes back with what was deleted with it
Skyfuller1303 Nov 6, 2026
455353a
Merge gc-reference-index: a folder comes back with what was deleted w…
Skyfuller1303 Nov 6, 2026
b61fcd6
meta: a folder restore or removal takes at most the cap below it, the…
Skyfuller1303 Nov 6, 2026
2c45e1b
Merge trash: a folder restore or removal takes at most the cap below it
Skyfuller1303 Nov 6, 2026
6dbb9f2
Merge gc-reference-index: a folder restore or removal takes at most t…
Skyfuller1303 Nov 6, 2026
98020a2
meta tests: name the trash tests' sorting helper sorted_nodes
Skyfuller1303 Nov 6, 2026
19ca781
Merge trash: a folder restore or removal takes at most the cap below it
Skyfuller1303 Nov 6, 2026
8a23d1f
Merge gc-reference-index: a folder restore or removal takes at most t…
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
150 changes: 148 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,
AccountUsage, 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, UsageEstimateReason, UsageEstimates, 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,7 +57,13 @@ 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("/account/usage", get(account_usage))
.route("/tree", get(tree))
.route("/changes", get(changes))
.route("/live", get(crate::live::connect))
Expand Down Expand Up @@ -167,6 +174,19 @@ async fn space(State(state): State<Shared>, Extension(auth): Extension<DeviceAut
Ok(Json(SpaceResponse { space: auth.space, root: info.root, epoch: info.epoch, seq: info.seq, username: auth.username }))
}

async fn account_usage(State(state): State<Shared>, Extension(auth): Extension<DeviceAuth>) -> Result<Json<AccountUsage>, ApiError> {
let estimate = state.meta.storage_estimate(auth.space).await?;
let index_complete = estimate.reason.is_none();
Ok(Json(AccountUsage {
stored_bytes: estimate.stored_bytes,
// A per-account quota override, once there is one, takes precedence over this cap.
quota_bytes: state.meta.stored_bytes_cap(),
trash_bytes: estimate.trash_bytes,
history_bytes: estimate.history_bytes,
estimates: UsageEstimates { index_complete, reason: estimate.reason.map(|_| UsageEstimateReason::IndexIncomplete) },
}))
}

async fn list_devices(State(state): State<Shared>, Extension(auth): Extension<DeviceAuth>) -> Result<Json<Vec<DeviceInfo>>, ApiError> {
let devices = state.meta.list_devices(auth.user).await?;
Ok(Json(
Expand Down Expand Up @@ -328,6 +348,9 @@ async fn put_manifest(
state.meta.check_room(auth.space, BlobKind::Manifest, id.as_bytes(), body.len() as u64 + 1).await?;
state.store.put(BlobKey::manifest(&id), &body).await?;
state.meta.add_manifest(auth.space, &manifest, body.len() as u64 + 1, state.now_ms()).await?;
// The index of its chunks is complete before the upload is acknowledged: a manifest of up to the index budget was indexed
// in the transaction above, a longer one is finished here in batches (and by `index build` if this is cut short).
state.meta.index_complete(&manifest).await?;
Ok(StatusCode::NO_CONTENT)
}

Expand Down Expand Up @@ -385,6 +408,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
11 changes: 7 additions & 4 deletions apps/craft-cloud-server/src/auth.rs
Original file line number Diff line number Diff line change
Expand Up @@ -72,10 +72,13 @@ fn bearer(request: &Request) -> Option<&str> {
pub async fn require_device(State(state): State<Arc<AppState>>, mut request: Request, next: Next) -> Result<Response, ApiError> {
let token = bearer(&request).ok_or_else(ApiError::unauthorized)?;
let device = state.meta.device_by_token(&token_hash(token)).await?.ok_or_else(ApiError::unauthorized)?;
// Off the request's path: the write may wait for the SQLite write lock, and the request needn't wait with it.
let touching = state.clone();
let (id, now) = (device.device, state.now_ms());
tokio::spawn(async move { touching.touch(id, now).await });
// Usage reads are fingerprinted as read-only; do not update the device's last-used timestamp for them.
if !matches!(request.uri().path(), "/api/v1/account/usage" | "/account/usage") {
// Off the request's path: the write may wait for the SQLite write lock, and the request needn't wait with it.
let touching = state.clone();
let (id, now) = (device.device, state.now_ms());
tokio::spawn(async move { touching.touch(id, now).await });
}
let space = device.space;
let epoch = state.meta.space_info(space).await?.epoch;
request.extensions_mut().insert(device);
Expand Down
85 changes: 85 additions & 0 deletions apps/craft-cloud-server/src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,28 @@ pub enum Command {
#[arg(long)]
all: bool,
},
/// Check the database and the blob store against each other and report: the reference index of every manifest, the
/// manifests and chunks the database names against the objects in the store, and what names what. Changes nothing;
/// exits with an error when it finds a problem. Reads every chunk object (`--skip-chunk-reads` leaves that out).
Verify {
/// Path to config.toml.
#[arg(long)]
config: Option<PathBuf>,
/// Print the report as JSON.
#[arg(long)]
json: bool,
/// Check chunks against the database only; do not read their objects from the store.
#[arg(long)]
skip_chunk_reads: bool,
},
/// The reference index of what each manifest names.
Index {
/// Path to config.toml. May come before or after the action.
#[arg(long, global = true)]
config: Option<PathBuf>,
#[command(subcommand)]
action: IndexAction,
},
/// Manage live documents.
Live {
/// Path to config.toml. May come before or after the action.
Expand All @@ -87,6 +109,18 @@ pub enum Command {
},
}

#[derive(Debug, Subcommand)]
pub enum IndexAction {
/// Complete the index of every manifest whose index is not complete: reads each manifest from the store, checks it
/// against its ID, and writes its edges in batches. Writes only that derived index. Safe to stop and run again, and to
/// run beside the server.
Build {
/// Edges written per database transaction (default 5000).
#[arg(long)]
batch_rows: Option<usize>,
},
}

#[derive(Debug, Subcommand)]
pub enum LiveAction {
/// Empty a user's recents document of an app (one that is full: `quota_exceeded`), or, given a document's ID
Expand Down Expand Up @@ -132,6 +166,9 @@ pub enum CliError {
Store(#[from] craft_cloud_store::StoreError),
#[error("{0}")]
Usage(String),
/// A check found something wrong (its report was written first).
#[error("{0}")]
Inconsistent(String),
#[error("I/O error: {0}")]
Io(#[from] std::io::Error),
}
Expand All @@ -148,6 +185,23 @@ pub async fn open(config: &Config) -> Result<(Meta, Store), CliError> {
Ok((meta, store))
}

/// Like [`open`], for a command that only reads: the database and the storage must exist already, and nothing is
/// created or upgraded. A config that points at the wrong place is an error, not a new empty server that has no problems.
pub async fn open_existing(config: &Config) -> Result<(Meta, Store), CliError> {
let meta = Meta::open_existing(&config.database.url).await?;
let store = match (&config.storage, config.storage.s3()?) {
(_, Some(s3)) => Store::new(S3Backend::new(&s3)?),
(StorageConfig::Disk { path }, None) => {
if !path.is_dir() {
return Err(CliError::Usage(format!("the storage directory {} does not exist (is the config's path right?)", path.display())));
}
Store::new(DiskBackend::new(path)?)
}
(StorageConfig::S3 { .. }, None) => return Err(CliError::Usage("S3 storage without settings".into())),
};
Ok((meta, store))
}

/// `--config` is global, which clap can't also make required, so it is checked here.
fn config_path(config: Option<PathBuf>) -> Result<PathBuf, CliError> {
config.ok_or_else(|| CliError::Usage("--config <path to config.toml> is required".into()))
Expand Down Expand Up @@ -241,6 +295,37 @@ pub async fn run(command: Command, input: &mut impl BufRead, out: &mut impl Writ
}
Ok(())
}
Command::Verify { config, json, skip_chunk_reads } => {
let (meta, store) = open_existing(&Config::load(&config_path(config)?)?).await?;
let report = crate::verify::verify(&meta, &store, crate::verify::VerifyOptions { read_chunks: !skip_chunk_reads }).await?;
if json {
writeln!(out, "{}", report.to_json())?;
} else {
write!(out, "{}", report.to_text())?;
}
match report.problem_count() {
0 => Ok(()),
n => Err(CliError::Inconsistent(format!("verify found {n} problem(s)"))),
}
}
Command::Index { config, action: IndexAction::Build { batch_rows } } => {
let (meta, store) = open(&Config::load(&config_path(config)?)?).await?;
let meta = match batch_rows {
Some(0) => return Err(CliError::Usage("--batch-rows must be at least 1".into())),
Some(rows) => meta.with_index_batch_rows(rows),
None => meta,
};
let report = crate::verify::build_index(&meta, &store).await?;
writeln!(out, "indexed {} manifest(s)", report.indexed)?;
for (id, why) in &report.unreadable {
writeln!(out, "could not index manifest {id}: {why}")?;
}
if report.unreadable.is_empty() {
Ok(())
} else {
Err(CliError::Inconsistent(format!("{} manifest(s) could not be indexed", report.unreadable.len())))
}
}
Command::Live { config, action: LiveAction::ResetDoc { username, app } } => {
let (meta, _) = open(&Config::load(&config_path(config)?)?).await?;
let user = user_id(&meta, &username).await?;
Expand Down
Loading