# Response

> The server sends exactly one response, whose payload is one JSON object with the members volumes_disk, images_disk, container_memory and container_disk, each a count of bytes, with no tag and no length, and the response finish follows it.

Canonical: https://protocol.diverge.network/2.3.0/endpoints/capacity/response/
Specification revision: 2.3.0

The server sends exactly one response on the scope. The response
finish follows the response, and no frame follows the finish.

```text
[capacity JSON …]
```

```json
{"volumes_disk":107374182400,"images_disk":53687091200,"container_memory":4294967296,"container_disk":17179869184}
```

- **The payload.** The payload of the response is one JSON object,
  read as [Notation](/2.3.0/endpoints/#notation) provides, running to the
  end of the frame. No tag precedes it and no length prefixes it.
  The object has exactly four members, `volumes_disk`, `images_disk`,
  `container_memory` and `container_disk`, and the server sends no
  other member.
- **`volumes_disk`.** An integer: the largest size, in bytes, a new
  volume of the client could have as of the instant of the response
  — the room of one place a volume could be made in, and not the sum
  of the server's room. A client reads it only where the server holds
  out at least one [volume mode](/2.3.0/capabilities/#the-volume-modes).
- **`images_disk`.** An integer: the number of bytes the client could
  still add to the client image store, as of the instant of the
  response. A client reads it only where the server holds out
  [`images_store`](/2.3.0/capabilities/#images_store).
- **`container_memory`.** An integer: the number of bytes of memory a
  container run of the client could still reserve, as of the instant
  of the response.
- **`container_disk`.** An integer: the number of bytes of overlay
  disk a container run of the client could still reserve, as of the
  instant of the response.
- **Each integer.** Each member is an integer no less than `0` and no
  greater than `18446744073709551615`. `0` is an answer: no room.
- **The sequence.** Exactly one response precedes the response
  finish, and nothing follows the finish. A response finish that no
  response precedes states that the request was not served, as
  [Endpoints](/2.3.0/endpoints/) provides.
- **Malformed.** A payload that is not valid UTF-8, a payload that is
  not exactly one JSON object, an object with any of the four members
  absent, and a member that is not an integer within the range stated
  are malformed. A member this revision does not define is ignored.

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

```rust
//! What a server's response frame carries for a capacity request.

use serde::{Deserialize, Serialize};

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

/// How much the caller may still use: four counts of bytes, each the
/// most of its resource the caller could use up as of the instant of
/// the answer, as the provider allots it.
///
/// One of these on channel `0`, then the scope finishes. The payload
/// is this struct as JSON — no tag, because there is nothing to
/// discriminate; it runs to the end, so it needs no length either.
///
/// ```json
/// {"volumes_disk":107374182400,"images_disk":53687091200,
/// "container_memory":4294967296,"container_disk":17179869184}
/// ```
///
/// # Each number is the caller's, as of now
///
/// What THIS caller — the connection's identity — could use up at the
/// instant the provider answered, as the provider allots it: a
/// provider that lets every caller use everything it holds answers
/// what it holds; one that partitions its callers answers the
/// caller's share; neither answers more than it would, at that
/// instant, let the caller have. Nothing is set aside by answering: a
/// request that relies on a number — a create, a build, a run — is
/// answered on its own terms, and may be refused for want of room the
/// answer reported.
///
/// # Reckoned by reservation
///
/// The two container numbers count against what the provider's
/// running containers RESERVED — the `memory` and `disk` their
/// requests stated — and not against what the host has free: a run
/// whose `memory` and `disk` are within them is one the provider's
/// caps admit.
///
/// # Every member is sent; a caller reads what the capabilities allow
///
/// A member whose resource the provider's
/// [`Capabilities`](crate::provider::endpoints::info::server::response::Capabilities)
/// do not hold out carries any number, and a caller does not read it:
/// `volumes_disk` where no volume mode object is held out,
/// `images_disk` where `images_store` is not. The container members
/// are always read.
///
/// # There is no failure
///
/// As with [`info`](crate::provider::endpoints::info): every
/// provider counts what it holds, so there is nothing to refuse and
/// nothing to tag. A member this version does not know is ignored.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[derive(schemars::JsonSchema)]
pub struct Frame {
    /// The largest size, in BYTES, a new volume of the caller could
    /// have: room for a volume, which lives in one place, and not the
    /// sum of the provider's room. Read only where a volume mode
    /// object is held out.
    pub volumes_disk: u64,
    /// The number of BYTES the caller could still add to the client
    /// image store by a build. Read only where `images_store` is held
    /// out.
    pub images_disk: u64,
    /// The number of BYTES of memory a container run of the caller
    /// could still reserve: what remains of the provider's memory cap
    /// after every running container's `memory`.
    pub container_memory: u64,
    /// The number of BYTES of overlay disk a container run of the
    /// caller could still reserve: what remains of the provider's
    /// overlay cap after every running container's `disk`, and
    /// whatever else the provider counts against the same cap.
    pub container_disk: u64,
}

/// The struct as JSON, and nothing in front of it.
impl Encode for Frame {
    /// The ordinary JSON failure.
    type Error = serde_json::Error;

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

impl Decode<'_> for Frame {
    /// One way to fail: bytes that are not this struct's JSON.
    type Error = serde_json::Error;

    fn decode(bytes: &[u8]) -> Result<Self, Self::Error> {
        serde_json::from_slice(bytes)
    }
}
```