Response

The sequence of channel responses the server sends, what ends it, and what a finish with nothing before it means.

[0]                  the file is at the path
[1][error JSON …]    it is not

• The sequence. Exactly one channel response, followed by the channel response finish. The server sends it after the content has ended and the proxy has answered. A channel response finish that no channel response precedes states that the proxy did not serve the write.
• Written. The byte 0 and nothing after it: the proxy answered that the file is at the path, whole.
• The error. After the byte 1, exactly one JSON value in the form defined on the volumes::list response page: the error the client sent on the content channel, the proxy’s refusal, or the server’s own. The destination is as it was before the write.

The channel response is defined by diverge-provider-sdk/src/endpoints/containers/tools/run/server/channel_response/write_path/frame.rs:

//! What a server's channel response frame carries on a write channel.

use std::fmt;

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

/// The file landed, or it did not.
///
/// A payload leads with one byte saying which — `0` for
/// [`Written`](Self::Written), `1` for [`Error`](Self::Error) — and
/// the rest is that variant's own bytes.
///
/// # How it ends
///
/// | the channel ends with | means |
/// |-----------------------|-------|
/// | a [`Written`](Self::Written), then a finish | the file is at the path |
/// | an [`Error`](Self::Error), then a finish | it is not, and nothing partial is |
///
/// Only a finish ends it. What a caller does about an error is not
/// specified here.
///
/// # The failure is this scope's, the answer is not
///
/// [`Written`](Self::Written) carries
/// [`write_path::response::Frame`](crate::shared::containers::write_path::response::Frame),
/// which means the same thing wherever the exchange happens. The
/// [`Error`](Self::Error) beside it is the exchange's own.
#[derive(Debug, Clone, PartialEq)]
pub enum Frame {
    /// The file is at the path. Tag `0`.
    Written(write_path::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::Written`].
const WRITTEN: u8 = 0;

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

impl Encode for Frame {
    /// The ordinary JSON failure, from the half that has one. The
    /// other cannot fail.
    type Error = serde_json::Error;

    // 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<(), serde_json::Error> {
        match self {
            Frame::Written(inner) => {
                out.extend_from_slice(&[WRITTEN]);
                // Its error is `Infallible`, and an empty match on one
                // is how you say so: there is no value to handle.
                inner.encode(out).map_err(|error| match error {})
            }
            Frame::Error(error) => {
                out.extend_from_slice(&[ERROR]);
                error.encode(out)
            }
        }
    }
}

impl Decode<'_> for Frame {
    /// Three ways to fail, and only one of them is a parse.
    type Error = FrameError;

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

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

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

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

and by diverge-provider-sdk/src/shared/containers/write_path/response/frame.rs:

//! What a response frame carries on a write path channel.

use std::convert::Infallible;

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

/// The file landed.
///
/// It carries nothing, because saying so IS the whole message — no
/// fields, and no bytes on the wire either.
///
/// # Failing is not this type's business
///
/// It used to spend a tag byte against the day failure got a shape.
/// Failure has one now, and it is not here: the endpoints that allow a
/// write to fail wrap this in an enum of their own — every
/// [`containers`](crate::endpoints::containers) scope does — and that
/// enum's tag does the discriminating. A byte here
/// as well would be two discriminators for one choice.
///
/// What a write can fail with is the exchange's business. What "the
/// file landed" looks like is not, and it looks like nothing.
///
/// # What a partial write leaves behind
///
/// Nothing at the destination. A provider writes to a temporary in the
/// destination's own directory and renames it into place, so the path
/// holds the old file, then nothing, then the new one — never a prefix
/// of the new one. That holds whether this frame arrives or not.
///
/// Where space is too tight for both copies, unlinking the old one
/// first frees exactly what the new one needs. That trades the old
/// contents away on failure, which is why it is worth doing only after
/// the ordinary attempt returns `ENOSPC` rather than up front.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct Frame;

impl Encode for Frame {
    /// [`Infallible`]: writing nothing has no failure mode.
    type Error = Infallible;

    fn encode(&self, _out: &mut Writer<'_>) -> Result<(), Self::Error> {
        Ok(())
    }
}

impl Decode<'_> for Frame {
    /// [`Infallible`]: there is nothing to read.
    type Error = Infallible;

    /// Whatever bytes arrive are ignored. There are none to send, so a
    /// peer that sent some knows something this version does not, and
    /// leaving room for it is cheaper than refusing it.
    fn decode(_bytes: &[u8]) -> Result<Self, Self::Error> {
        Ok(Frame)
    }
}