docs/generated/contracts.mdgenerated from code
Reference · 3 min read
api-watch
Contracts: api-watch.
Read as
Source: crates/lvcs-api/src/watch.rs.
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}