api-files

Source: crates/lvcs-api/src/files.rs.

/// `open`: start (or find) the document actor for `address`, as
/// `workspace` (a workspace name or id; `main` when omitted) sees it. The
/// same `workspace` field on `read`, `edit`, `subscribe`, and the pushes
/// names the workspace view they act on (design §8).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct OpenParams {
    pub address: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspace: Option<String>,
}

/// `open` result.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct OpenResult {
    pub kind: String,
    pub heads: Vec<String>,
}

/// `read`: the rendered body, or the value at `pointer`. With `heads`
/// (decision 303), the file as it was at those heads (lowercase hex change
/// hashes, as a `read` or a frontier's document returned them), on `main`
/// only and with no `pointer`; heads the document lacks are refused
/// `unknown_base`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ReadParams {
    pub address: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pointer: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspace: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub heads: Option<Vec<String>>,
}

/// `read` result: exactly one of `text`, `bytes_base64`, or `json` is
/// present; `deleted` is true when the file is deleted.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ReadResult {
    pub heads: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub text: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub bytes_base64: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub json: Option<String>,
    pub deleted: bool,
}

/// One splice against the text at `base`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct SpliceParams {
    pub pos: usize,
    pub delete: usize,
    pub insert: String,
}

/// `edit`: splices against the text at `base`, sorted by `pos`, disjoint.
/// In a forked workspace, `base` is a view frontier (the heads a `read` or
/// push of that view returned) and the splices are positions in the view
/// text; the edit lands in the workspace's overrides, never in the base.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct EditParams {
    pub address: String,
    pub base: Vec<String>,
    pub splices: Vec<SpliceParams>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspace: Option<String>,
}

/// `edit` result.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct EditResult {
    pub heads: Vec<String>,
}

/// `subscribe`: an exact address or a `**` prefix pattern.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct SubscribeParams {
    pub pattern: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspace: Option<String>,
}

/// `subscribe` result; pushes carry the same id.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SubscribeResult {
    pub sub: u64,
}

/// Server push, JSON-RPC notification method `changed`; `workspace` is
/// the subscription's (omitted for `main`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChangedPush {
    pub sub: u64,
    pub address: String,
    pub heads: Vec<String>,
    pub splices: Vec<SpliceParams>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspace: Option<String>,
}

/// Server push, JSON-RPC notification method `stale_save`: a mirror save
/// was applied against an older disk base (design §8). Sent to every client
/// connected as the mirror's author; clients show it until dismissed.
/// `workspace` is the mirror's (omitted for `main`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StaleSavePush {
    pub address: String,
    pub chosen_base: Vec<String>,
    pub newest_base: Vec<String>,
    pub heads: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspace: Option<String>,
}

/// Server push, JSON-RPC notification method `write_held`: the mirror
/// stopped writing a file because another program held it open past
/// `HELD_DEADLINE_MS` (Windows, the held-rename row refining decision
/// 252). Sent to every client connected as the mirror's author, with the
/// `write_held` notification in its inbox. `workspace` is the mirror's
/// (omitted for `main`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct WriteHeldPush {
    pub address: String,
    /// The heads of the version the mirror could not write.
    pub heads: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspace: Option<String>,
    /// Why, and how to recover: as [`StatusHeld`]'s.
    pub error: ErrorData,
}

/// `snapshot`: the visible frontier of `workspace` (`main` when omitted).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct SnapshotParams {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspace: Option<String>,
}

/// `snapshot` result: the frontier id and its documents, as a JSON array of
/// `[address, heads]` pairs sorted by address.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SnapshotResult {
    pub frontier: String,
    pub docs: Vec<(String, Vec<String>)>,
}

/// `files.list` (decision 312): main's `file` documents, or a
/// forked workspace's view's paths, under `prefix` when named, sorted,
/// each with how many participants are present on it now and how many
/// threads are anchored on it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct FilesListParams {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub prefix: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspace: Option<String>,
}

/// `files.list` result.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FilesListResult {
    #[serde(default)]
    pub files: Vec<FileEntry>,
}

/// One file.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FileEntry {
    pub path: String,
    /// The participants present on it now.
    #[serde(default)]
    pub presence: u32,
    /// The threads anchored on it.
    #[serde(default)]
    pub threads: u32,
}