deploy.list

{
  "type": "object",
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty"
}

{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "How many."
    },
    "deployments": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DeploymentView"
      },
      "description": "Each, in identity order."
    },
    "unreadable": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Refusal"
      },
      "description": "Objects of the deployment kind this executable could not read, with why. A\nmalformed object is reported here rather than hidden by being skipped."
    }
  },
  "required": [
    "count",
    "deployments"
  ],
  "description": "Every deployment the layer declares.",
  "title": "DeploymentList",
  "$defs": {
    "DeploymentView": {
      "type": "object",
      "properties": {
        "file": {
          "type": "string",
          "description": "The repository-relative file the object lives in."
        },
        "schema": {
          "type": "string",
          "description": "The format version; a version this executable does not read is refused."
        },
        "kind": {
          "type": "string",
          "description": "Always `deployment`."
        },
        "id": {
          "type": "string",
          "description": "The identity within the repository."
        },
        "title": {
          "type": "string",
          "description": "One line naming it."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "One line: what it serves and to whom.",
          "default": null
        },
        "status": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeploymentStatus"
            },
            {
              "type": "null"
            }
          ],
          "description": "Where it stands.",
          "default": null
        },
        "application": {
          "type": "string",
          "description": "The application's name: what the deployment is known by in a listing."
        },
        "build": {
          "$ref": "#/$defs/Build",
          "description": "What is shipped and what it is built from."
        },
        "listen": {
          "$ref": "#/$defs/Listen",
          "description": "The address the process listens on."
        },
        "health": {
          "$ref": "#/$defs/HealthRoutes",
          "description": "The routes a platform polls."
        },
        "resources": {
          "$ref": "#/$defs/Resources",
          "description": "What one machine is granted."
        },
        "machines": {
          "$ref": "#/$defs/Machines",
          "description": "How many machines run."
        },
        "region": {
          "type": "string",
          "description": "The region they run in."
        },
        "budgets": {
          "$ref": "#/$defs/Budgets",
          "description": "The measured figures it is held to.",
          "default": {
            "image_bytes": null,
            "binary_bytes": null,
            "build_context_bytes": null,
            "cold_start_ms": null,
            "resident_memory_mb": null,
            "blocking_check_ms": null,
            "request_p99_ms": null
          }
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "When the object was written.",
          "default": null
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "When it was last changed.",
          "default": null
        }
      },
      "required": [
        "file",
        "schema",
        "kind",
        "id",
        "title",
        "application",
        "build",
        "listen",
        "health",
        "resources",
        "machines",
        "region"
      ],
      "description": "One deployment as this process reads it, with where it came from."
    },
    "DeploymentStatus": {
      "oneOf": [
        {
          "type": "string",
          "const": "declared",
          "description": "The object exists and nothing is deployed from it yet."
        },
        {
          "type": "string",
          "const": "active",
          "description": "It is deployed."
        },
        {
          "type": "string",
          "const": "retired",
          "description": "It was, and the object is kept for the record."
        }
      ],
      "description": "Where a deployment stands.\n\n`Status` is the right name inside this module; the schema component namespace is flat,\nand `distribution::Status` answers a different question, so each says which it is."
    },
    "Build": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "package": {
          "type": "string",
          "description": "The Cargo package that is built."
        },
        "binary": {
          "type": "string",
          "description": "The binary target the image runs."
        },
        "profile": {
          "type": "string",
          "description": "The Cargo profile the image is built under."
        },
        "inputs": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The repository-relative paths the build context carries, and the only ones."
        },
        "site": {
          "type": [
            "string",
            "null"
          ],
          "description": "The directory the canonical site pipeline writes; absent means the image serves no\nsite.",
          "default": null
        }
      },
      "required": [
        "package",
        "binary",
        "profile",
        "inputs"
      ],
      "description": "What is shipped and what it is built from."
    },
    "Listen": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "port": {
          "$ref": "#/$defs/Port",
          "description": "The port, stated once for the process and the image."
        },
        "interface": {
          "$ref": "#/$defs/Interface",
          "description": "Which interface."
        }
      },
      "required": [
        "port",
        "interface"
      ],
      "description": "The address the process listens on."
    },
    "Port": {
      "type": "integer",
      "format": "uint16",
      "minimum": 0,
      "maximum": 65535,
      "description": "A TCP port a deployed process may bind. Privileged ports are not among them: the\nprocess runs as a non-root user and could not bind one."
    },
    "Interface": {
      "oneOf": [
        {
          "type": "string",
          "const": "loopback",
          "description": "Reachable from this host alone: the local default, and what every local invocation\nkeeps."
        },
        {
          "type": "string",
          "const": "all",
          "description": "Every interface. A hosted process needs it and a local one never does; stating it\nis the intent that replaces suppressing the bind warning."
        }
      ],
      "description": "Which interface a process listens on."
    },
    "HealthRoutes": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "liveness": {
          "$ref": "#/$defs/Route",
          "description": "Is this process alive."
        },
        "readiness": {
          "$ref": "#/$defs/Route",
          "description": "Can this process serve traffic."
        },
        "grace_seconds": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint32",
          "minimum": 0,
          "description": "How long the platform waits before the first check counts.",
          "default": null
        },
        "interval_seconds": {
          "anyOf": [
            {
              "$ref": "#/$defs/Positive"
            },
            {
              "type": "null"
            }
          ],
          "description": "How often the platform polls liveness.",
          "default": null
        },
        "timeout_seconds": {
          "anyOf": [
            {
              "$ref": "#/$defs/Positive"
            },
            {
              "type": "null"
            }
          ],
          "description": "How long one check may take before it counts as failed.",
          "default": null
        }
      },
      "required": [
        "liveness",
        "readiness"
      ],
      "description": "The routes a platform polls, and how often."
    },
    "Route": {
      "type": "string",
      "description": "A route a platform polls: an absolute path on this service, never a URL. The host is\nthe deployment's to know and not the object's to state."
    },
    "Positive": {
      "type": "integer",
      "format": "uint32",
      "minimum": 0,
      "description": "A count that is at least one: memory in megabytes, CPUs, machines. Zero is refused\nwherever zero would mean \"a deployment that cannot run\"."
    },
    "Resources": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "cpu_kind": {
          "$ref": "#/$defs/CpuKind",
          "description": "Shared or dedicated."
        },
        "cpus": {
          "$ref": "#/$defs/Positive",
          "description": "How many CPUs one machine has."
        },
        "memory_mb": {
          "$ref": "#/$defs/Positive",
          "description": "Memory per machine, in megabytes."
        }
      },
      "required": [
        "cpu_kind",
        "cpus",
        "memory_mb"
      ],
      "description": "What one machine is granted."
    },
    "CpuKind": {
      "oneOf": [
        {
          "type": "string",
          "const": "shared",
          "description": "A fraction of a core: the cheap profile."
        },
        {
          "type": "string",
          "const": "performance",
          "description": "A dedicated one."
        }
      ],
      "description": "What a machine's CPU is."
    },
    "Machines": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "count": {
          "$ref": "#/$defs/Positive",
          "description": "How many machines the application has."
        },
        "min_running": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "How many stay running when idle."
        },
        "autostart": {
          "type": "boolean",
          "description": "Whether a request to a stopped machine starts it."
        },
        "autostop": {
          "type": "boolean",
          "description": "Whether an idle machine is stopped."
        }
      },
      "required": [
        "count",
        "min_running",
        "autostart",
        "autostop"
      ],
      "description": "How many machines run, and whether the platform may stop them."
    },
    "Budgets": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "image_bytes": {
          "anyOf": [
            {
              "$ref": "#/$defs/Positive"
            },
            {
              "type": "null"
            }
          ],
          "description": "Largest accepted compressed image size.",
          "default": null
        },
        "binary_bytes": {
          "anyOf": [
            {
              "$ref": "#/$defs/Positive"
            },
            {
              "type": "null"
            }
          ],
          "description": "Largest accepted stripped binary size.",
          "default": null
        },
        "build_context_bytes": {
          "anyOf": [
            {
              "$ref": "#/$defs/Positive"
            },
            {
              "type": "null"
            }
          ],
          "description": "Largest accepted build context.",
          "default": null
        },
        "cold_start_ms": {
          "anyOf": [
            {
              "$ref": "#/$defs/Positive"
            },
            {
              "type": "null"
            }
          ],
          "description": "Longest accepted time from a stopped machine to a served response.",
          "default": null
        },
        "resident_memory_mb": {
          "anyOf": [
            {
              "$ref": "#/$defs/Positive"
            },
            {
              "type": "null"
            }
          ],
          "description": "Largest accepted resident set under load.",
          "default": null
        },
        "blocking_check_ms": {
          "anyOf": [
            {
              "$ref": "#/$defs/Positive"
            },
            {
              "type": "null"
            }
          ],
          "description": "Longest accepted time for one liveness or readiness check.",
          "default": null
        },
        "request_p99_ms": {
          "anyOf": [
            {
              "$ref": "#/$defs/Positive"
            },
            {
              "type": "null"
            }
          ],
          "description": "Longest accepted p99 for a served request.",
          "default": null
        }
      },
      "description": "The measured figures this deployment is held to. Each is written by the run that\nmeasured it; an absent one has not been measured yet and is not a licence."
    },
    "Refusal": {
      "type": "object",
      "properties": {
        "file": {
          "type": "string",
          "description": "The repository-relative file the value came from."
        },
        "key": {
          "type": "string",
          "description": "The key path within it, as the contract names it."
        },
        "found": {
          "type": "string",
          "description": "The value observed, rendered as it was read."
        },
        "problem": {
          "type": "string",
          "description": "What is wrong with it, in one line."
        },
        "correction": {
          "type": "string",
          "description": "What to do instead."
        }
      },
      "required": [
        "file",
        "key",
        "found",
        "problem",
        "correction"
      ],
      "description": "Why a deployment object is refused: what was read, where, and what to do about it."
    }
  }
}