docs/generated/contracts.mdgenerated from code

Reference · 3 min read

api-watch

Contracts: api-watch.

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

ruston main
1/// `watch` (discussion:owner/303): subscribe this connection to `pushes`, each a2/// `push_kind` value that `watch` takes (`channel_moved`, `run`,3/// `frontier_moved`, `protected_moved`, `checks`, `presence`, `activity`);4/// any other is5/// invalid params. It lasts until6/// the connection closes. Right after the answer, a watch of a kind that7/// has a current value is sent it (discussion:owner/661: subscribe, then8/// snapshot): `frontier_moved` with main's visible frontier. An9/// `activity` watch is first replayed the recent activity, none older10/// than `since_ms` (Unix milliseconds) when it names one: a watcher that11/// already holds what came before asks for nothing older (owner/795).12/// `since_ms` must be no later than the watcher's read of its state, or a13/// push between that read and `since_ms` is never replayed.14#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]15pub struct WatchParams {16    pub pushes: Vec<String>,17    #[serde(default, skip_serializing_if = "Option::is_none")]18    pub since_ms: Option<i64>,19}2021/// `watch` result; its pushes carry the same id.22#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]23pub struct WatchResult {24    pub sub: u64,25}2627/// The `push_kind` value a `watch` names, when `watch` takes it.28pub fn watched(name: &str) -> Option<PushKind> {29    use lvcs_vocab::Vocabulary as _;30    PushKind::ALL31        .iter()32        .copied()33        .find(|kind| kind.as_str() == name)34        .filter(|kind| kind.watched())35}3637/// Server push, JSON-RPC notification method `frontier_moved` (`watch`,38/// discussion:owner/518): main's visible file frontier moved, to the frontier39/// `id` (`ID_ENCODING`) that `frontier.read` reads.40#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]41pub struct FrontierMovedPush {42    /// The `watch` it is pushed for.43    pub sub: u64,44    pub id: String,45}4647/// Server push, JSON-RPC notification method `protected_moved` (`watch`,48/// discussion:owner/661): protected path `path`'s approved heads moved to49/// `heads`, sorted, sent by the protected-path owner after commit.50#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]51pub struct ProtectedMovedPush {52    /// The `watch` it is pushed for.53    pub sub: u64,54    pub path: String,55    /// Its heads (`ID_ENCODING`), sorted; empty at genesis.56    pub heads: Vec<String>,57}5859/// Server push, JSON-RPC notification method `channel_moved` (`watch`):60/// a channel's or combination's value moved.61#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]62pub struct ChannelMovedPush {63    /// The `watch` it is pushed for.64    pub sub: u64,65    pub channel: String,66    /// Its new value's frontier ids (`ID_ENCODING`), sorted; empty for67    /// none.68    pub frontiers: Vec<String>,69}7071/// Server push, JSON-RPC notification method `activity` (`watch`):72/// something happened in the project, metadata only.73#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]74pub struct ActivityPush {75    /// The `watch` it is pushed for.76    pub sub: u64,77    pub activity: Activity,78}7980/// One project event, metadata only (discussion:owner/303).81#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]82pub struct Activity {83    /// An `activity_kind` value.84    #[serde(serialize_with = "vocab_to", deserialize_with = "vocab_from")]85    pub kind: ActivityKind,86    /// When, in Unix milliseconds: the signed time when it has one, else87    /// this daemon's clock.88    pub at_ms: i64,89    /// Who, by name (`Named`), when a peer did it.90    #[serde(default, skip_serializing_if = "Option::is_none")]91    pub by: Option<String>,92    /// The document it concerns, if any.93    #[serde(default, skip_serializing_if = "Option::is_none")]94    pub address: Option<String>,95    /// The channel it concerns, if any.96    #[serde(default, skip_serializing_if = "Option::is_none")]97    pub channel: Option<String>,98    /// The node it concerns (`node_joined`, `node_left`), if any.99    #[serde(default, skip_serializing_if = "Option::is_none")]100    pub node: Option<String>,101}102103/// Server push, JSON-RPC notification method `lagged`104/// (discussion:owner/798): the client read too slowly to take every push,105/// so `dropped` pushes never reached it. It reads again what they would106/// have told it. Sent on any connection, watched or not, once room107/// returns; answers are never dropped.108#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]109pub struct LaggedPush {110    /// How many pushes were dropped.111    pub dropped: u64,112}