Response

The server sends a snapshot of the tree, one response per change to it, a further snapshot whenever it has lost track of changes, and an error as its last response when the watch fails; each response is the byte 0 followed by a filetree frame in the postcard wire format, or the byte 1 followed by an error as one JSON value; the response finish follows the last response.

The server sends zero or more responses on the scope, and the response finish follows the last of them. No frame bearing the scope follows the finish.

[0][filetree frame, postcard …]      the snapshot, or one change
[1][error JSON …]                    last

The sequence. The first response is a snapshot, or an error. Zero or more responses follow the first, each of which is one change or a further snapshot. An error, when the server sends one, is the last response. The response finish follows the last response. A response finish that no response precedes states that the request was not served, as Endpoints provides.
The filetree frame. A payload whose first byte is 0 carries a filetree frame after that byte, running to the end of the payload, encoded as the postcard reading of Notation provides. The frame is one of four variants, and its discriminant is a varint: 0 is Snapshot, followed by children, a varint count followed by that many nodes; 1 is Inserted, followed by path, a varint count followed by that many strings, followed by node, one node; 2 is Modified, followed by path and node in the same forms; 3 is Removed, followed by path.
The node. A node is one of three variants, and its discriminant is a varint: 0 is File, followed by name, a string, size, an optional u64, created_at, an optional u64, and modified_at, an optional u64; 1 is Directory, followed by name, created_at, modified_at, changes, one byte 0 or 1, and children, a varint count followed by that many nodes; 2 is Symlink, followed by name, path, a varint count followed by that many strings, created_at and modified_at. An optional u64 is the byte 0, or the byte 1 followed by a varint. name is the name of the node in its directory and is never a path. size is the length of the file in bytes, absent when the server could not read it. created_at and modified_at are seconds since 1970-01-01T00:00:00Z, unsigned, absent when the filesystem records no such time. children is never absent; an empty directory carries an empty list. A Symlink is the link itself, never followed: its path is the target of the link as components relative to the root of the volume, and is present whether or not a node exists at that path.
Paths. Every path is a sequence of components from the root of the volume, each component the name of a node. The root of the volume has no path and no node; a snapshot carries the entries of the root. The last component of the path of an Inserted or Modified frame equals the name of its node.
The snapshot. The first response of every watch the server can serve is a Snapshot carrying the whole tree of the volume at that time. The server sends a further Snapshot whenever it has lost track of changes to the tree. Every Snapshot replaces the tree whole.
A change. After a snapshot, the server sends one response for each change to the filesystem of the volume, as the change occurs. A node that comes into existence at a path that held no node is sent as Inserted at that path, with the node complete, a directory with its whole subtree. A node that changes in place is sent as Modified at its path, with the node’s complete new value, a directory with its whole subtree; the value replaces the node and is not merged into it. A node that ceases to exist is sent as Removed at its path; a directory takes everything beneath it, and the server sends no response for a descendant. A node that is relocated, whether renamed within its directory, moved elsewhere in the tree, or moved out of or into the volume, is sent as Removed at the path it left, followed by Inserted at the path it arrived at, with the inserted node complete. The server sends no response that states a relocation as one event, and no frame of this specification does so.
Order and repetition. The server sends the responses for changes in the order in which the changes occurred. The server may send a response for one change more than once, and it may send a Snapshot at any time. Every response places or clears exactly one place in the tree, and no response depends on the tree the client holds.
A directory not watched. A Directory whose changes is 0 is one whose contents the server does not watch: the server sends no response for a change beneath it until the next Snapshot, and its children are the entries the server found when it read the directory.
The tree the client holds. A client that holds the tree applies each response as follows. A Snapshot replaces the tree with its children. An Inserted or a Modified places its node at its path, replacing a node of that name in that directory when one is there. A Removed removes the node at its path and everything beneath it. A response whose path names a parent that is absent from the tree, or that is not a directory, has no effect on the tree; the next Snapshot corrects it.
The error. A payload whose first byte is 1 carries an error after that byte, running to the end of the payload. The error is exactly one JSON value, in the form defined on the volumes::list response page. This revision prescribes nothing about its content. The error states that the server no longer keeps the watch: it is the last response, and the tree the client holds is not kept current after it.
Malformed. A payload with no byte, a payload whose first byte is neither 0 nor 1, a payload whose bytes after 0 do not decode as a filetree frame, and a payload whose bytes after 1 are not one JSON value are malformed.

The response frame is defined by diverge-provider-sdk/src/endpoints/volumes/watch/server/response/frame.rs:

//! One change on the watched tree, or a failure to keep watching.

use std::fmt;

use crate::decode::Decode;
use crate::encode::{Encode, Writer};
use crate::shared::error::Error;
use crate::shared::filetree;

/// One change on the watched tree, or the news that there will not be
/// another.
///
/// A payload leads with one byte saying which — `0` for
/// [`Filetree`](Self::Filetree), `1` for [`Error`](Self::Error) — and
/// the rest is that variant's own bytes.
///
/// # The failure is this endpoint's, the tree is not
///
/// [`Filetree`](Self::Filetree) carries
/// [`filetree::response::Frame`](crate::shared::filetree::response::Frame),
/// which is what a change to a tree looks like anywhere — a
/// [`container`](crate::endpoints::containers) reports one over its
/// own filesystem using the same type. Defining it
/// again here would be two definitions of one thing waiting to
/// disagree, and
/// [`Root::update`](crate::shared::filetree::response::Root::update)
/// would be where they did.
///
/// The [`Error`](Self::Error) beside it is not shared, because what
/// can go wrong belongs to the exchange: a volume that went away under
/// a watch is this endpoint's problem, and a container that stopped is
/// the laboratory's.
///
/// # A watch is the one stream that does not expect to end
///
/// The others answer a question and finish. This one runs for as long
/// as the caller holds the scope, so an [`Error`](Self::Error) here is
/// the interesting case rather than the edge one — it is how a caller
/// learns that a tree it has been folding is no longer being kept up
/// to date, which it could not otherwise tell from quiet.
#[derive(Debug, Clone, PartialEq)]
pub enum Frame {
    /// One change on the tree. Tag `0`.
    ///
    /// The snapshot that establishes it, or one node inserted,
    /// modified, moved or removed. See
    /// [`filetree::response::Frame`](crate::shared::filetree::response::Frame)
    /// for the variants and for what makes the stream replay-safe.
    Filetree(filetree::response::Frame),
    /// A failure. Tag `1`.
    ///
    /// See [`shared::error::Error`](crate::shared::error::Error) for
    /// why it says so little.
    Error(Error),
}

/// Tag for [`Frame::Filetree`].
const FILETREE: u8 = 0;

/// Tag for [`Frame::Error`].
const ERROR: u8 = 1;

/// Two variants, two formats, and the tag chooses between them. A
/// filetree frame is postcard's and is handed to postcard; an
/// [`Error`](Frame::Error) is a [`serde_json::Value`], which
/// deserializes through `deserialize_any` and so cannot come back out
/// of a format with no self-description.
impl Encode for Frame {
    /// One failure per half, and they are different libraries'.
    type Error = FrameEncodeError;

    // Spelled out rather than `Self::Error`: this enum has a variant
    // called `Error`, so the associated type is ambiguous by that name.
    fn encode(
        &self,
        out: &mut Writer<'_>,
    ) -> Result<(), FrameEncodeError> {
        match self {
            Frame::Filetree(frame) => {
                out.extend_from_slice(&[FILETREE]);
                frame.encode(out).map_err(FrameEncodeError::Filetree)
            }
            Frame::Error(error) => {
                out.extend_from_slice(&[ERROR]);
                error.encode(out).map_err(FrameEncodeError::Error)
            }
        }
    }
}

impl Decode<'_> for Frame {
    /// Four ways to fail, and each names which half failed.
    type Error = FrameDecodeError;

    // Spelled out for the same reason as `encode` above.
    fn decode(bytes: &[u8]) -> Result<Self, FrameDecodeError> {
        let (tag, rest) = bytes.split_first().ok_or(FrameDecodeError::Empty)?;
        match *tag {
            FILETREE => filetree::response::Frame::decode(rest)
                .map(Frame::Filetree)
                .map_err(FrameDecodeError::Filetree),
            ERROR => Error::decode(rest)
                .map(Frame::Error)
                .map_err(FrameDecodeError::Error),
            tag => Err(FrameDecodeError::UnknownTag(tag)),
        }
    }
}

/// A watch response that could not be written.
#[derive(Debug)]
pub enum FrameEncodeError {
    /// The filetree frame did not serialize.
    Filetree(postcard::Error),
    /// The error did not serialize.
    Error(serde_json::Error),
}

impl fmt::Display for FrameEncodeError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            FrameEncodeError::Filetree(error) => {
                write!(f, "filetree frame did not serialize: {error}")
            }
            FrameEncodeError::Error(error) => {
                write!(f, "watch error did not serialize: {error}")
            }
        }
    }
}

impl std::error::Error for FrameEncodeError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            FrameEncodeError::Filetree(error) => Some(error),
            FrameEncodeError::Error(error) => Some(error),
        }
    }
}

/// A watch response that could not be read.
#[derive(Debug)]
pub enum FrameDecodeError {
    /// No bytes at all, so not even a tag.
    Empty,
    /// A tag that is neither of this frame's two.
    UnknownTag(u8),
    /// The filetree frame did not decode.
    Filetree(postcard::Error),
    /// The error did not parse.
    Error(serde_json::Error),
}

impl fmt::Display for FrameDecodeError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            FrameDecodeError::Empty => {
                f.write_str("watch response frame is empty")
            }
            FrameDecodeError::UnknownTag(tag) => {
                write!(f, "unknown watch response frame tag {tag}")
            }
            FrameDecodeError::Filetree(error) => {
                write!(f, "filetree frame did not decode: {error}")
            }
            FrameDecodeError::Error(error) => {
                write!(f, "watch error did not parse: {error}")
            }
        }
    }
}

impl std::error::Error for FrameDecodeError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            FrameDecodeError::Filetree(error) => Some(error),
            FrameDecodeError::Error(error) => Some(error),
            FrameDecodeError::Empty | FrameDecodeError::UnknownTag(_) => None,
        }
    }
}

The filetree frame is defined by diverge-provider-sdk/src/shared/filetree/response/frame.rs:

//! What a filetree response frame carries.

use serde::{Deserialize, Serialize};

use super::Node;
use crate::decode::Decode;
use crate::encode::{Encode, Writer};

/// One change on a filetree stream.
///
/// [`Snapshot`](Frame::Snapshot) establishes the tree. Every other
/// variant names exactly one node and says what became of it: it
/// appeared ([`Inserted`](Frame::Inserted)), changed in place
/// ([`Modified`](Frame::Modified)), or ceased to exist
/// ([`Removed`](Frame::Removed)).
///
/// Insertion and modification are distinguished because a consumer
/// usually wants to treat them differently — a newly appeared file is
/// not the same news as an existing one being written to. The
/// distinction is INFORMATION, not a constraint: a consumer with no
/// use for it may treat the two identically, and doing so is what
/// keeps the fold tolerant of replay and reordering.
///
/// A delta that carries a node carries its COMPLETE value, never a
/// patch against a value the consumer is assumed to hold. That is what
/// makes replaying an already-applied frame harmless, and therefore
/// what makes at-least-once delivery safe: every variant overwrites
/// or clears one place in the tree, and none reads the tree first.
///
/// # A rename is two frames
///
/// There is no move. A node renamed — within one directory or across
/// the tree — is reported as what happened on disk:
/// [`Removed`](Frame::Removed) at the path it left and
/// [`Inserted`](Frame::Inserted) at the path it arrived at, the
/// inserted node complete, a directory with its whole subtree. The
/// pairing a filesystem offers for the two halves is not reliable
/// enough to promise a consumer, and the tree is right without it;
/// what a consumer loses is only the knowledge that the two were one
/// node.
///
/// Every `path` in every variant is a component vector relative to the
/// filetree root — one meaning of "path" throughout, matching
/// [`Node::Symlink`]'s.
///
/// # Variant ORDER is part of the wire format
///
/// Serialized in serde's default representation, which writes the
/// variant's INDEX rather than its name — the same arrangement
/// [`Node`] uses, and for the same reason: an index needs no lookahead
/// to read, which is what makes it encodable in a format with no
/// self-description.
///
/// It is also a constraint. Reordering these variants, or inserting
/// one among them, silently changes what existing bytes mean. New
/// variants go on the END; nowhere else is a compatible change.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum Frame {
    /// The whole tree: the root's entries, recursively.
    ///
    /// The first frame of every stream, and the only frame that may
    /// come again: a source that lost track of the tree — a watch
    /// whose event queue overflowed — sends a fresh one rather than
    /// deltas it cannot know. Each replaces the tree whole.
    Snapshot {
        /// The root's entries. The root itself is not among them and
        /// is not described — see [`Root`](super::Root).
        children: Vec<Node>,
    },
    /// A node came into existence at a path that held nothing.
    ///
    /// Also how a node arrives by rename, from elsewhere in the tree
    /// or from outside it: from this path's point of view nothing was
    /// relocated, something appeared.
    Inserted {
        /// Where the node appeared. The last element equals `node`'s
        /// `name`.
        ///
        /// Components rather than a joined string: a path is a
        /// sequence, and joining it would invent a separator that then
        /// has to be escaped out of names that contain it.
        path: Vec<String>,
        /// The node's complete value. A directory carries its whole
        /// subtree.
        node: Node,
    },
    /// A node that already existed changed, staying where it was.
    Modified {
        /// The node's path, unchanged by this frame. The last element
        /// equals `node`'s `name`.
        path: Vec<String>,
        /// The node's complete new value, replacing the old one. A
        /// directory carries its whole subtree, so this replaces rather
        /// than merges.
        node: Node,
    },
    /// A node ceased to exist. A directory takes its whole subtree with
    /// it — no per-descendant removals follow.
    ///
    /// Also how a node leaves by rename — to elsewhere in the tree,
    /// where an [`Inserted`](Frame::Inserted) reports its arrival, or
    /// out of it.
    Removed {
        /// The vanished node's path.
        path: Vec<String>,
    },
}

/// Postcard, where the rest of the crate is JSON.
///
/// A filetree stream is the one thing here that is both high-volume
/// and free to choose: it relays nothing, so no byte of it has to
/// survive a round trip unchanged, and nothing downstream reads it as
/// text. What it is instead is spammy — one frame per changed node,
/// indefinitely — so the envelope is worth minimizing.
///
/// Postcard drops field names entirely and varint-encodes every length
/// and integer, which puts a small delta within a couple of bytes of
/// the information it actually carries. `Removed` naming
/// `src/main.rs` is fourteen bytes, ten of them the two strings
/// themselves.
impl Encode for Frame {
    /// Postcard's own failure. It has few ways to happen when writing
    /// — a buffer that will not take bytes, mostly — since everything
    /// here is a shape it can always represent.
    type Error = postcard::Error;

    fn encode(&self, out: &mut Writer<'_>) -> Result<(), Self::Error> {
        postcard::to_io(self, &mut *out)?;
        Ok(())
    }
}

impl Decode<'_> for Frame {
    /// Postcard's own failure.
    type Error = postcard::Error;

    fn decode(bytes: &[u8]) -> Result<Self, Self::Error> {
        postcard::from_bytes(bytes)
    }
}

The node is defined by diverge-provider-sdk/src/shared/filetree/response/node.rs:

//! One node of the filesystem tree.

use serde::{Deserialize, Serialize};

/// One node of the filesystem tree.
///
/// A [`Directory`](Node::Directory) carries its children inline;
/// [`File`](Node::File) and [`Symlink`](Node::Symlink) are leaves. A
/// symlink is the link ITSELF and is never followed, so a dangling or
/// looping link is a leaf rather than an error or an infinite tree.
///
/// Every variant carries `name` — the basename, never a path — plus
/// `created_at` and `modified_at`. A directory alone carries
/// `changes`: whether what happens beneath it will be reported, which
/// is a question only a directory can answer, because only a
/// directory is watched — see the field.
///
/// # Times are unsigned seconds
///
/// The same representation
/// [`Volume::created`](crate::endpoints::volumes::list::server::response::Volume::created)
/// uses, and unsigned for the same reason: nothing a provider offers
/// predates 1970, and a signed field's negative half would exist to
/// represent a state that never occurs. `Option` here is about
/// availability rather than sign — a filesystem that records no birth
/// time has nothing to report, which is not the same as reporting a
/// time before the epoch.
///
/// # Variant ORDER is part of the wire format
///
/// This enum is serialized in serde's default representation, which
/// writes the variant's INDEX rather than its name. That is what makes
/// it encodable at all in a format with no self-description — there is
/// no name to look up and no lookahead to do — and it is also a
/// constraint: reordering these variants, or inserting one among them,
/// silently changes what existing bytes mean.
///
/// New variants go on the END. Nowhere else is a compatible change.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum Node {
    /// A regular file.
    File {
        /// Basename of this file.
        name: String,
        /// Size in bytes. `None` when the stat could not be read.
        size: Option<u64>,
        /// Creation time (unix seconds), when the filesystem records a
        /// birth time. `None` where unsupported — this is display
        /// metadata and is never load-bearing.
        created_at: Option<u64>,
        /// Last-modified time (unix seconds). `None` when the stat
        /// could not be read.
        modified_at: Option<u64>,
    },
    /// A directory, carrying its entries.
    Directory {
        /// Basename of this directory. The watched root has no node of
        /// its own — see [`Root`](super::Root).
        name: String,
        /// Creation time (unix seconds), when the filesystem records a
        /// birth time.
        created_at: Option<u64>,
        /// Last-modified time (unix seconds). A directory's mtime
        /// tracks entry add/remove, not changes within its children.
        modified_at: Option<u64>,
        /// Whether changes beneath this directory stream.
        ///
        /// `true` is the ordinary case: what happens under it arrives
        /// as deltas. `false` is a directory the source could not
        /// watch — a watch limit reached, a corner it was refused —
        /// and with it everything beneath, files included: what is
        /// here is what the walk found, nothing under it will be
        /// reported until the next [`Snapshot`](super::Frame::Snapshot),
        /// and a consumer should treat it as possibly stale. Only a
        /// directory carries this, because only a directory is
        /// watched: a file's changes are its parent's to report, so a
        /// file cannot fail to be watched on its own.
        changes: bool,
        /// This directory's entries. An empty directory carries an
        /// empty list — this field is never absent, so a consumer never
        /// has to distinguish "no children" from "children unknown".
        children: Vec<Node>,
    },
    /// A symbolic link — the link itself, never its target.
    Symlink {
        /// Basename of this link.
        name: String,
        /// The link's target, as path components ALWAYS RELATIVE TO
        /// THE FILETREE ROOT — the same frame of reference as the
        /// `path` carried by [`Frame::Inserted`](super::Frame::Inserted),
        /// [`Frame::Modified`](super::Frame::Modified) and
        /// [`Frame::Removed`](super::Frame::Removed). Every path in
        /// this API means the same thing, so a consumer walks a link's
        /// target down from the snapshot's child list exactly as it
        /// walks a frame's path, with no separate rule for links.
        ///
        /// Addressable is not the same as resolved: the link is still
        /// never followed, and the components may name a node that
        /// does not exist — an ordinary dangling link.
        ///
        /// Always present. A link whose contents could not be read is
        /// not a symlink node with a missing target; it is a failure,
        /// and is reported as one. That is unrelated to dangling: a
        /// link pointing at nothing still reports its components
        /// perfectly well, because reading a link never touches its
        /// target.
        path: Vec<String>,
        /// Creation time (unix seconds), when the filesystem records a
        /// birth time.
        created_at: Option<u64>,
        /// Last-modified time (unix seconds).
        modified_at: Option<u64>,
    },
}

// Visible throughout `response` — but no wider. These exist so
// [`Root`](super::Root)'s fold can walk and edit a tree; they are not
// part of the specification and nothing outside this module should
// depend on them.
impl Node {
    /// This node's basename.
    pub(super) fn name(&self) -> &str {
        match self {
            Node::File { name, .. }
            | Node::Directory { name, .. }
            | Node::Symlink { name, .. } => name,
        }
    }

    /// This node's entries, mutably — `None` for anything but a
    /// directory.
    pub(super) fn children_mut(&mut self) -> Option<&mut Vec<Node>> {
        match self {
            Node::Directory { children, .. } => Some(children),
            _ => None,
        }
    }
}