// @generated by canopy-api-codegen from crates/public-server/openapi.json.
// Run `just gen-api` to refresh; do not edit by hand.
/// Version of the OpenAPI document this source was generated from, which is also
/// this crate's own version.
pub const OPENAPI_VERSION: &str = "1.0.1";
/// BLAKE3 digest of that document, so a document that changed without the
/// version moving with it can be told from one that did not.
pub const OPENAPI_BLAKE3: &str = "7618bb56960b10e83dac565b3dde53060531f2ef31bc1a7fa4fe6cf308ef5f02";
/// Error types.
pub mod error {
/// Error from a `TryFrom` or `FromStr` implementation.
pub struct ConversionError(::std::borrow::Cow<'static, str>);
impl ::std::error::Error for ConversionError {}
impl ::std::fmt::Display for ConversionError {
fn fmt(
&self,
f: &mut ::std::fmt::Formatter<'_>,
) -> Result<(), ::std::fmt::Error> {
::std::fmt::Display::fmt(&self.0, f)
}
}
impl ::std::fmt::Debug for ConversionError {
fn fmt(
&self,
f: &mut ::std::fmt::Formatter<'_>,
) -> Result<(), ::std::fmt::Error> {
::std::fmt::Debug::fmt(&self.0, f)
}
}
impl From<&'static str> for ConversionError {
fn from(value: &'static str) -> Self {
Self(value.into())
}
}
impl From<String> for ConversionError {
fn from(value: String) -> Self {
Self(value.into())
}
}
}
///What one application on the asking machine may act on.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "What one application on the asking machine may act on.",
/// "type": "object",
/// "required": [
/// "certificates",
/// "domains",
/// "may_manage_dns",
/// "may_manage_tls",
/// "paused",
/// "registered_names",
/// "type"
/// ],
/// "properties": {
/// "certificates": {
/// "description": "The certificates Canopy holds for it.",
/// "type": "array",
/// "items": {
/// "$ref": "#/components/schemas/HeldCertificate"
/// }
/// },
/// "domains": {
/// "description": "The domains its group controls.",
/// "type": "array",
/// "items": {
/// "type": "string"
/// }
/// },
/// "may_manage_dns": {
/// "description": "Whether this application may manage its own DNS records.",
/// "type": "boolean"
/// },
/// "may_manage_tls": {
/// "description": "Whether this application may obtain its own TLS certificates.",
/// "type": "boolean"
/// },
/// "paused": {
/// "description": "Whether Canopy is currently making no new changes on its behalf.",
/// "type": "boolean"
/// },
/// "registered_names": {
/// "description": "The names it has registered addresses for.",
/// "type": "array",
/// "items": {
/// "type": "string"
/// }
/// },
/// "type": {
/// "description": "The type of application these entitlements belong to.\n\nA reporter correlates an entry to a workload it runs by the machine it\nasked as and this type. Canopy's own identifier for the application is\ninternal and never on the wire.",
/// "$ref": "#/components/schemas/ApplicationType"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct ApplicationEntitlements {
///The certificates Canopy holds for it.
pub certificates: ::std::vec::Vec<HeldCertificate>,
///The domains its group controls.
pub domains: ::std::vec::Vec<::std::string::String>,
///Whether this application may manage its own DNS records.
pub may_manage_dns: bool,
///Whether this application may obtain its own TLS certificates.
pub may_manage_tls: bool,
///Whether Canopy is currently making no new changes on its behalf.
pub paused: bool,
///The names it has registered addresses for.
pub registered_names: ::std::vec::Vec<::std::string::String>,
/**The type of application these entitlements belong to.
A reporter correlates an entry to a workload it runs by the machine it
asked as and this type. Canopy's own identifier for the application is
internal and never on the wire.*/
#[serde(rename = "type")]
pub type_: ApplicationType,
}
///One application within a push, as the reporter found it.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "One application within a push, as the reporter found it.",
/// "type": "object",
/// "required": [
/// "detail",
/// "type"
/// ],
/// "properties": {
/// "detail": {
/// "description": "Everything the reporter has to say about this application beyond its\nchecks, including its `tamanuVersion`.",
/// "type": "object"
/// },
/// "health": {
/// "description": "This application's checks. Reported bare; Canopy qualifies them with\nthe application's type when cataloguing them.",
/// "type": [
/// "array",
/// "null"
/// ],
/// "items": {
/// "$ref": "#/components/schemas/HealthCheck"
/// }
/// },
/// "type": {
/// "description": "What this application is: the software and the role it plays together,\nfor example `tamanu-central`. Required, and part of how Canopy\ncorrelates the report to its own record — a different type under a key\nalready in use means the reporter has stopped reporting one application\nand started reporting another.",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct ApplicationReport {
/**Everything the reporter has to say about this application beyond its
checks, including its `tamanuVersion`.*/
pub detail: ::serde_json::Map<::std::string::String, ::serde_json::Value>,
/**This application's checks. Reported bare; Canopy qualifies them with
the application's type when cataloguing them.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub health: ::std::option::Option<::std::vec::Vec<HealthCheck>>,
/**What this application is: the software and the role it plays together,
for example `tamanu-central`. Required, and part of how Canopy
correlates the report to its own record — a different type under a key
already in use means the reporter has stopped reporting one application
and started reporting another.*/
#[serde(rename = "type")]
pub type_: ::std::string::String,
}
///What an application is: the software and the role it plays, as a slug. The set is open — a report carrying a type Canopy does not know creates an application of that type, which simply carries no per-type capabilities.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "What an application is: the software and the role it plays, as a slug. The set is open — a report carrying a type Canopy does not know creates an application of that type, which simply carries no per-type capabilities.",
/// "examples": [
/// "tamanu-central"
/// ],
/// "type": "string"
///}
/// ```
/// </details>
#[derive(
::serde::Deserialize,
::serde::Serialize,
Clone,
Debug,
Eq,
Hash,
Ord,
PartialEq,
PartialOrd
)]
#[serde(transparent)]
pub struct ApplicationType(pub ::std::string::String);
impl ::std::ops::Deref for ApplicationType {
type Target = ::std::string::String;
fn deref(&self) -> &::std::string::String {
&self.0
}
}
impl ::std::convert::From<ApplicationType> for ::std::string::String {
fn from(value: ApplicationType) -> Self {
value.0
}
}
impl ::std::convert::From<::std::string::String> for ApplicationType {
fn from(value: ::std::string::String) -> Self {
Self(value)
}
}
impl ::std::str::FromStr for ApplicationType {
type Err = ::std::convert::Infallible;
fn from_str(value: &str) -> ::std::result::Result<Self, Self::Err> {
Ok(Self(value.to_string()))
}
}
impl ::std::fmt::Display for ApplicationType {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
self.0.fmt(f)
}
}
/**A downloadable artifact belonging to a release version: an installer,
package, or other file published for a given type and platform.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "A downloadable artifact belonging to a release version: an installer,\npackage, or other file published for a given type and platform.",
/// "type": "object",
/// "required": [
/// "artifact_type",
/// "download_url",
/// "id",
/// "platform"
/// ],
/// "properties": {
/// "artifact_type": {
/// "description": "What kind of artifact this is (e.g. an installer or package name).",
/// "type": "string"
/// },
/// "device_id": {
/// "description": "The device that registered this artifact, if it was registered by a\nreleaser device rather than created by an operator.",
/// "type": [
/// "string",
/// "null"
/// ],
/// "format": "uuid"
/// },
/// "download_url": {
/// "description": "URL the artifact can be downloaded from.",
/// "type": "string"
/// },
/// "id": {
/// "description": "Unique identifier of the artifact.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "platform": {
/// "description": "The platform the artifact targets (e.g. an OS or architecture name).",
/// "type": "string"
/// },
/// "version_id": {
/// "description": "The exact version this artifact belongs to. `null` for range\nartifacts, which apply to every version matching\n`version_range_pattern` instead.",
/// "type": [
/// "string",
/// "null"
/// ],
/// "format": "uuid"
/// },
/// "version_range_pattern": {
/// "description": "Semver range this artifact applies to (e.g. `^2.10.0`), for artifacts\nshared across a range of versions rather than pinned to one. `null`\nfor exact-version artifacts.",
/// "type": [
/// "string",
/// "null"
/// ]
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct Artifact {
///What kind of artifact this is (e.g. an installer or package name).
pub artifact_type: ::std::string::String,
/**The device that registered this artifact, if it was registered by a
releaser device rather than created by an operator.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub device_id: ::std::option::Option<::uuid::Uuid>,
///URL the artifact can be downloaded from.
pub download_url: ::std::string::String,
///Unique identifier of the artifact.
pub id: ::uuid::Uuid,
///The platform the artifact targets (e.g. an OS or architecture name).
pub platform: ::std::string::String,
/**The exact version this artifact belongs to. `null` for range
artifacts, which apply to every version matching
`version_range_pattern` instead.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub version_id: ::std::option::Option<::uuid::Uuid>,
/**Semver range this artifact applies to (e.g. `^2.10.0`), for artifacts
shared across a range of versions rather than pinned to one. `null`
for exact-version artifacts.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub version_range_pattern: ::std::option::Option<::std::string::String>,
}
///`BTreeMap`
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "type": "object",
/// "additionalProperties": {
/// "description": "Describes one configurable parameter that a replica of a restore intent\naccepts.",
/// "type": "object",
/// "required": [
/// "type"
/// ],
/// "properties": {
/// "default": {
/// "description": "The value used when the parameter is left unset. `None` means an\nunset parameter is sent as JSON `null` rather than a default value."
/// },
/// "type": {
/// "description": "The parameter's data type, which determines how its value is\nvalidated.",
/// "$ref": "#/components/schemas/ParamType"
/// }
/// }
/// },
/// "propertyNames": {
/// "type": "string"
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(transparent)]
pub struct BTreeMap(
pub ::std::collections::HashMap<::std::string::String, BTreeMapValue>,
);
impl ::std::ops::Deref for BTreeMap {
type Target = ::std::collections::HashMap<::std::string::String, BTreeMapValue>;
fn deref(
&self,
) -> &::std::collections::HashMap<::std::string::String, BTreeMapValue> {
&self.0
}
}
impl ::std::convert::From<BTreeMap>
for ::std::collections::HashMap<::std::string::String, BTreeMapValue> {
fn from(value: BTreeMap) -> Self {
value.0
}
}
impl ::std::convert::From<
::std::collections::HashMap<::std::string::String, BTreeMapValue>,
> for BTreeMap {
fn from(
value: ::std::collections::HashMap<::std::string::String, BTreeMapValue>,
) -> Self {
Self(value)
}
}
/**Describes one configurable parameter that a replica of a restore intent
accepts.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Describes one configurable parameter that a replica of a restore intent\naccepts.",
/// "type": "object",
/// "required": [
/// "type"
/// ],
/// "properties": {
/// "default": {
/// "description": "The value used when the parameter is left unset. `None` means an\nunset parameter is sent as JSON `null` rather than a default value."
/// },
/// "type": {
/// "description": "The parameter's data type, which determines how its value is\nvalidated.",
/// "$ref": "#/components/schemas/ParamType"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct BTreeMapValue {
/**The value used when the parameter is left unset. `None` means an
unset parameter is sent as JSON `null` rather than a default value.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub default: ::std::option::Option<::serde_json::Value>,
/**The parameter's data type, which determines how its value is
validated.*/
#[serde(rename = "type")]
pub type_: ParamType,
}
///Request body for registering the backup types a server can run.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Request body for registering the backup types a server can run.",
/// "type": "object",
/// "required": [
/// "types"
/// ],
/// "properties": {
/// "types": {
/// "description": "The backup types this server is able to run. Each type is a plain\nstring (e.g. `tamanu-postgres`); custom type names are accepted.",
/// "type": "array",
/// "items": {
/// "type": "string"
/// }
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct BackupCapabilitiesArgs {
/**The backup types this server is able to run. Each type is a plain
string (e.g. `tamanu-postgres`); custom type names are accepted.*/
pub types: ::std::vec::Vec<::std::string::String>,
}
/**Request body for minting short-lived S3 credentials for a backup or
restore run.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Request body for minting short-lived S3 credentials for a backup or\nrestore run.",
/// "type": "object",
/// "required": [
/// "type"
/// ],
/// "properties": {
/// "purpose": {
/// "description": "What the credentials will be used for. `backup` (the default) grants\nwrite access for uploading backups; `restore` grants strictly read-only\naccess. Either way the credentials are scoped to the group's backup\nstorage only.",
/// "$ref": "#/components/schemas/BackupPurpose"
/// },
/// "run_id": {
/// "description": "This must be the run-uuid the client minted for this run.\nThe field is optional only so older clients don't break; it WILL be made\nmandatory in future.",
/// "type": [
/// "string",
/// "null"
/// ],
/// "format": "uuid"
/// },
/// "type": {
/// "description": "The backup type the credentials are for (e.g. `tamanu-postgres`). For a\n`backup`, the type must be an enabled capability of this server or the\nsubject of a pending \"backup now\" request; for a `restore`, the server's\nrestore window must be open (an operator allows restores for it in\ncanopy). Otherwise the request is rejected with 409.",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct BackupCredentialsArgs {
/**What the credentials will be used for. `backup` (the default) grants
write access for uploading backups; `restore` grants strictly read-only
access. Either way the credentials are scoped to the group's backup
storage only.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub purpose: ::std::option::Option<BackupPurpose>,
/**This must be the run-uuid the client minted for this run.
The field is optional only so older clients don't break; it WILL be made
mandatory in future.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub run_id: ::std::option::Option<::uuid::Uuid>,
/**The backup type the credentials are for (e.g. `tamanu-postgres`). For a
`backup`, the type must be an enabled capability of this server or the
subject of a pending "backup now" request; for a `restore`, the server's
restore window must be open (an operator allows restores for it in
canopy). Otherwise the request is rejected with 409.*/
#[serde(rename = "type")]
pub type_: ::std::string::String,
}
/**Why a backup credential was issued, or what a reported run was for.
Determines the access the credential grants: a `backup` credential can
write new data but not delete existing data, while a `restore`
credential is read-only.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Why a backup credential was issued, or what a reported run was for.\nDetermines the access the credential grants: a `backup` credential can\nwrite new data but not delete existing data, while a `restore`\ncredential is read-only.",
/// "type": "string",
/// "enum": [
/// "backup",
/// "restore"
/// ]
///}
/// ```
/// </details>
#[derive(
::serde::Deserialize,
::serde::Serialize,
Clone,
Copy,
Debug,
Eq,
Hash,
Ord,
PartialEq,
PartialOrd
)]
pub enum BackupPurpose {
#[serde(rename = "backup")]
Backup,
#[serde(rename = "restore")]
Restore,
}
impl ::std::fmt::Display for BackupPurpose {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
match *self {
Self::Backup => f.write_str("backup"),
Self::Restore => f.write_str("restore"),
}
}
}
impl ::std::str::FromStr for BackupPurpose {
type Err = self::error::ConversionError;
fn from_str(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
match value {
"backup" => Ok(Self::Backup),
"restore" => Ok(Self::Restore),
_ => Err("invalid value".into()),
}
}
}
impl ::std::convert::TryFrom<&str> for BackupPurpose {
type Error = self::error::ConversionError;
fn try_from(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for BackupPurpose {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for BackupPurpose {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
/**The backup storage target for the calling server's group: where the backup
repository lives and the passphrase to open it.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "The backup storage target for the calling server's group: where the backup\nrepository lives and the passphrase to open it.",
/// "type": "object",
/// "required": [
/// "bucket",
/// "prefix",
/// "region",
/// "repo_password",
/// "storage"
/// ],
/// "properties": {
/// "bucket": {
/// "description": "Name of the S3 bucket holding the group's backup repository.",
/// "type": "string"
/// },
/// "prefix": {
/// "description": "Key prefix within the bucket under which the repository lives. Normally\nempty (the repository is at the bucket root).",
/// "type": "string"
/// },
/// "region": {
/// "description": "AWS region of the bucket.",
/// "type": "string"
/// },
/// "repo_password": {
/// "description": "Passphrase for the group's backup repository (a Kopia repository).",
/// "$ref": "#/definitions/CanopySecret"
/// },
/// "storage": {
/// "description": "Kind of storage backend. Always `\"s3\"`.",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct BackupTarget {
///Name of the S3 bucket holding the group's backup repository.
pub bucket: ::std::string::String,
/**Key prefix within the bucket under which the repository lives. Normally
empty (the repository is at the bucket root).*/
pub prefix: ::std::string::String,
///AWS region of the bucket.
pub region: ::std::string::String,
///Passphrase for the group's backup repository (a Kopia repository).
pub repo_password: crate::Redacted<::std::string::String>,
///Kind of storage backend. Always `"s3"`.
pub storage: ::std::string::String,
}
///Request to start device enrollment against a machine.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Request to start device enrollment against a machine.",
/// "type": "object",
/// "required": [
/// "server_id",
/// "token"
/// ],
/// "properties": {
/// "server_id": {
/// "description": "ID of the machine to enroll against. Named `server_id` because that is\nthe name fielded agents send; the value has always identified the box.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "spki": {
/// "description": "Base64-standard-encoded DER SubjectPublicKeyInfo (SPKI) of the\ndevice's public key. Only required when enrolling over a transport\nwith no client certificate to read the key from (e.g. over\nTailscale); omit it when enrolling over mTLS, where the key is\ntaken from the presented client certificate. The returned challenge\nis bound to this key, so the same value must be supplied again when\ncompleting enrollment.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "token": {
/// "description": "The enrollment token issued by an operator for this machine.",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct BeginArgs {
/**ID of the machine to enroll against. Named `server_id` because that is
the name fielded agents send; the value has always identified the box.*/
pub server_id: ::uuid::Uuid,
/**Base64-standard-encoded DER SubjectPublicKeyInfo (SPKI) of the
device's public key. Only required when enrolling over a transport
with no client certificate to read the key from (e.g. over
Tailscale); omit it when enrolling over mTLS, where the key is
taken from the presented client certificate. The returned challenge
is bound to this key, so the same value must be supplied again when
completing enrollment.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub spki: ::std::option::Option<::std::string::String>,
///The enrollment token issued by an operator for this machine.
pub token: ::std::string::String,
}
///A freshly-issued enrollment challenge to sign and return.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "A freshly-issued enrollment challenge to sign and return.",
/// "type": "object",
/// "required": [
/// "channel_binding_required",
/// "nonce"
/// ],
/// "properties": {
/// "channel_binding_required": {
/// "description": "True if the server requires channel-binding data (the connection's\nTLS exported keying material) to be folded into the signed\ntranscript. Only relevant when enrolling over mTLS; it never\napplies on a transport without TLS channel binding.",
/// "type": "boolean"
/// },
/// "nonce": {
/// "description": "Base64-standard-encoded 32-byte challenge nonce. Sign it, together\nwith the machine ID, device public key, and channel-binding data if\nrequired, and submit the signature when completing enrollment.",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct BeginResponse {
/**True if the server requires channel-binding data (the connection's
TLS exported keying material) to be folded into the signed
transcript. Only relevant when enrolling over mTLS; it never
applies on a transport without TLS channel binding.*/
pub channel_binding_required: bool,
/**Base64-standard-encoded 32-byte challenge nonce. Sign it, together
with the machine ID, device public key, and channel-binding data if
required, and submit the signature when completing enrollment.*/
pub nonce: ::std::string::String,
}
///Where a certificate request stands, and the chain once there is one.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Where a certificate request stands, and the chain once there is one.",
/// "type": "object",
/// "required": [
/// "key_must_be_replaced",
/// "name",
/// "revoked",
/// "state",
/// "usable"
/// ],
/// "properties": {
/// "chain": {
/// "description": "The chain, PEM, once Canopy holds one — including while a renewal is\nunder way, the chain in hand staying valid until the new one lands.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "key_must_be_replaced": {
/// "description": "Whether the key must be replaced before asking again, rather than just the\ncertificate.",
/// "type": "boolean"
/// },
/// "last_error": {
/// "description": "Why the last attempt failed, if one did. Present while Canopy is still\nretrying.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "name": {
/// "description": "The name the certificate is (or will be) for, as Canopy normalised it.",
/// "type": "string"
/// },
/// "not_after": {
/// "description": "When it expires.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "profile": {
/// "description": "The profile it was issued under, if the authority named one.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "revoked": {
/// "description": "Whether an operator revoked it. Stop serving it and ask again.",
/// "type": "boolean"
/// },
/// "state": {
/// "description": "`pending`, `issued`, `failed`, or `revoked`.",
/// "type": "string"
/// },
/// "usable": {
/// "description": "Whether the chain can be served now.",
/// "type": "boolean"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct CertificateResponse {
/**The chain, PEM, once Canopy holds one — including while a renewal is
under way, the chain in hand staying valid until the new one lands.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub chain: ::std::option::Option<::std::string::String>,
/**Whether the key must be replaced before asking again, rather than just the
certificate.*/
pub key_must_be_replaced: bool,
/**Why the last attempt failed, if one did. Present while Canopy is still
retrying.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub last_error: ::std::option::Option<::std::string::String>,
///The name the certificate is (or will be) for, as Canopy normalised it.
pub name: ::std::string::String,
///When it expires.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub not_after: ::std::option::Option<::std::string::String>,
///The profile it was issued under, if the authority named one.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub profile: ::std::option::Option<::std::string::String>,
///Whether an operator revoked it. Stop serving it and ask again.
pub revoked: bool,
///`pending`, `issued`, `failed`, or `revoked`.
pub state: ::std::string::String,
///Whether the chain can be served now.
pub usable: bool,
}
/**Outcome of a single health check reported in a server's status update.
Older reports may send a plain pass/fail flag instead of one of these
outcomes; when that happens a passing flag is treated as `passed` and a
failing flag as `failed`.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Outcome of a single health check reported in a server's status update.\n\nOlder reports may send a plain pass/fail flag instead of one of these\noutcomes; when that happens a passing flag is treated as `passed` and a\nfailing flag as `failed`.",
/// "type": "string",
/// "enum": [
/// "passed",
/// "warning",
/// "failed",
/// "broken",
/// "skipped"
/// ]
///}
/// ```
/// </details>
#[derive(
::serde::Deserialize,
::serde::Serialize,
Clone,
Copy,
Debug,
Eq,
Hash,
Ord,
PartialEq,
PartialOrd
)]
pub enum CheckResult {
#[serde(rename = "passed")]
Passed,
#[serde(rename = "warning")]
Warning,
#[serde(rename = "failed")]
Failed,
#[serde(rename = "broken")]
Broken,
#[serde(rename = "skipped")]
Skipped,
}
impl ::std::fmt::Display for CheckResult {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
match *self {
Self::Passed => f.write_str("passed"),
Self::Warning => f.write_str("warning"),
Self::Failed => f.write_str("failed"),
Self::Broken => f.write_str("broken"),
Self::Skipped => f.write_str("skipped"),
}
}
}
impl ::std::str::FromStr for CheckResult {
type Err = self::error::ConversionError;
fn from_str(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
match value {
"passed" => Ok(Self::Passed),
"warning" => Ok(Self::Warning),
"failed" => Ok(Self::Failed),
"broken" => Ok(Self::Broken),
"skipped" => Ok(Self::Skipped),
_ => Err("invalid value".into()),
}
}
}
impl ::std::convert::TryFrom<&str> for CheckResult {
type Error = self::error::ConversionError;
fn try_from(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for CheckResult {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for CheckResult {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
/**How a server should treat one of its healthchecks, distilled from
canopy's operator-side configuration (the policy catalog and the
silences) into a three-level device-facing vocabulary.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "How a server should treat one of its healthchecks, distilled from\ncanopy's operator-side configuration (the policy catalog and the\nsilences) into a three-level device-facing vocabulary.",
/// "type": "string",
/// "enum": [
/// "skip",
/// "warn",
/// "fail"
/// ]
///}
/// ```
/// </details>
#[derive(
::serde::Deserialize,
::serde::Serialize,
Clone,
Copy,
Debug,
Eq,
Hash,
Ord,
PartialEq,
PartialOrd
)]
pub enum CheckSeverity {
#[serde(rename = "skip")]
Skip,
#[serde(rename = "warn")]
Warn,
#[serde(rename = "fail")]
Fail,
}
impl ::std::fmt::Display for CheckSeverity {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
match *self {
Self::Skip => f.write_str("skip"),
Self::Warn => f.write_str("warn"),
Self::Fail => f.write_str("fail"),
}
}
}
impl ::std::str::FromStr for CheckSeverity {
type Err = self::error::ConversionError;
fn from_str(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
match value {
"skip" => Ok(Self::Skip),
"warn" => Ok(Self::Warn),
"fail" => Ok(Self::Fail),
_ => Err("invalid value".into()),
}
}
}
impl ::std::convert::TryFrom<&str> for CheckSeverity {
type Error = self::error::ConversionError;
fn try_from(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for CheckSeverity {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for CheckSeverity {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
/**Request to complete device enrollment by presenting a signed
challenge obtained from the start-enrollment endpoint.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Request to complete device enrollment by presenting a signed\nchallenge obtained from the start-enrollment endpoint.",
/// "type": "object",
/// "required": [
/// "nonce",
/// "server_id",
/// "signature"
/// ],
/// "properties": {
/// "nonce": {
/// "description": "Base64-standard-encoded challenge nonce returned when enrollment\nwas started.",
/// "type": "string"
/// },
/// "server_id": {
/// "description": "ID of the machine being enrolled. Must match the value used when\nstarting enrollment.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "signature": {
/// "description": "Base64-standard-encoded ASN.1 DER ECDSA (P-256, SHA-256) signature\nover the challenge transcript, proving possession of the device's\nprivate key. The transcript is the byte concatenation of: the raw\nchallenge nonce, the raw 16 bytes of the machine ID, the DER SPKI of\nthe device public key, and — only when channel binding was flagged\nas required — the connection's TLS exported keying material.",
/// "type": "string"
/// },
/// "spki": {
/// "description": "Base64-standard-encoded DER SPKI of the device's public key. Only\nrequired when enrolling over a transport with no client\ncertificate to read the key from; must match the key used when\nenrollment was started.",
/// "type": [
/// "string",
/// "null"
/// ]
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct CompleteArgs {
/**Base64-standard-encoded challenge nonce returned when enrollment
was started.*/
pub nonce: ::std::string::String,
/**ID of the machine being enrolled. Must match the value used when
starting enrollment.*/
pub server_id: ::uuid::Uuid,
/**Base64-standard-encoded ASN.1 DER ECDSA (P-256, SHA-256) signature
over the challenge transcript, proving possession of the device's
private key. The transcript is the byte concatenation of: the raw
challenge nonce, the raw 16 bytes of the machine ID, the DER SPKI of
the device public key, and — only when channel binding was flagged
as required — the connection's TLS exported keying material.*/
pub signature: ::std::string::String,
/**Base64-standard-encoded DER SPKI of the device's public key. Only
required when enrolling over a transport with no client
certificate to read the key from; must match the key used when
enrollment was started.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub spki: ::std::option::Option<::std::string::String>,
}
///Result of a successful enrollment.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Result of a successful enrollment.",
/// "type": "object",
/// "required": [
/// "device_id",
/// "server_id"
/// ],
/// "properties": {
/// "device_id": {
/// "description": "The device identity created or reused for this enrollment. The\ndevice authenticates as this ID from now on.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "server_id": {
/// "description": "The machine the device is now enrolled against.",
/// "type": "string",
/// "format": "uuid"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct CompleteResponse {
/**The device identity created or reused for this enrollment. The
device authenticates as this ID from now on.*/
pub device_id: ::uuid::Uuid,
///The machine the device is now enrolled against.
pub server_id: ::uuid::Uuid,
}
/**Short-lived AWS credentials in the AWS `credential_process` output format,
so they can be consumed directly by AWS SDKs and tools. Field names use the
exact casing (`Version`, `AccessKeyId`, ...) that format requires.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Short-lived AWS credentials in the AWS `credential_process` output format,\nso they can be consumed directly by AWS SDKs and tools. Field names use the\nexact casing (`Version`, `AccessKeyId`, ...) that format requires.",
/// "type": "object",
/// "required": [
/// "AccessKeyId",
/// "Expiration",
/// "SecretAccessKey",
/// "SessionToken",
/// "Version"
/// ],
/// "properties": {
/// "AccessKeyId": {
/// "description": "The temporary AWS access key ID.",
/// "type": "string"
/// },
/// "Expiration": {
/// "description": "When the credentials expire, as an RFC 3339 / ISO 8601 UTC instant.\nCredentials last at most one hour; request a fresh set per run.",
/// "$ref": "#/definitions/CanopyTimestamp"
/// },
/// "SecretAccessKey": {
/// "description": "The temporary AWS secret access key.",
/// "$ref": "#/definitions/CanopySecret"
/// },
/// "SessionToken": {
/// "description": "The session token that must accompany the temporary key pair.",
/// "$ref": "#/definitions/CanopySecret"
/// },
/// "Version": {
/// "description": "Version of the `credential_process` format. Always the literal `1`.",
/// "type": "integer",
/// "format": "int32",
/// "minimum": 0.0
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct CredentialProcessOutput {
///The temporary AWS access key ID.
#[serde(rename = "AccessKeyId")]
pub access_key_id: ::std::string::String,
/**When the credentials expire, as an RFC 3339 / ISO 8601 UTC instant.
Credentials last at most one hour; request a fresh set per run.*/
#[serde(rename = "Expiration")]
pub expiration: ::jiff::Timestamp,
///The temporary AWS secret access key.
#[serde(rename = "SecretAccessKey")]
pub secret_access_key: crate::Redacted<::std::string::String>,
///The session token that must accompany the temporary key pair.
#[serde(rename = "SessionToken")]
pub session_token: crate::Redacted<::std::string::String>,
///Version of the `credential_process` format. Always the literal `1`.
#[serde(rename = "Version")]
pub version: i32,
}
///What a server is entitled to do with names, and what it already holds.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "What a server is entitled to do with names, and what it already holds.",
/// "type": "object",
/// "required": [
/// "certificates",
/// "domains",
/// "may_manage_dns",
/// "may_manage_tls",
/// "paused",
/// "registered_names"
/// ],
/// "properties": {
/// "applications": {
/// "description": "One entry per application on the asking machine.\n\nAn identity belongs to a machine, so an agent asks on behalf of the box\nand gets an answer for every workload on it. The flat fields above\ndescribe a single-application machine, which is every machine today;\non a machine hosting several they are left at their defaults and this\nlist is the answer.",
/// "type": "array",
/// "items": {
/// "$ref": "#/components/schemas/ApplicationEntitlements"
/// }
/// },
/// "certificates": {
/// "description": "The certificates Canopy holds for this server.",
/// "type": "array",
/// "items": {
/// "$ref": "#/components/schemas/HeldCertificate"
/// }
/// },
/// "domains": {
/// "description": "The domains this server's group controls. Any name at or beneath one of\nthese is a name this server may act on — which is what lets an agent\nrequest a certificate before anything asks for one.",
/// "type": "array",
/// "items": {
/// "type": "string"
/// }
/// },
/// "may_manage_dns": {
/// "description": "Whether this server may manage its own DNS records.",
/// "type": "boolean"
/// },
/// "may_manage_tls": {
/// "description": "Whether this server may obtain its own TLS certificates.",
/// "type": "boolean"
/// },
/// "paused": {
/// "description": "Whether Canopy is currently making no new changes on this server's\nbehalf. While true, requests are refused and an agent should wait.",
/// "type": "boolean"
/// },
/// "registered_names": {
/// "description": "The names this server has registered addresses for.",
/// "type": "array",
/// "items": {
/// "type": "string"
/// }
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct Entitlements {
/**One entry per application on the asking machine.
An identity belongs to a machine, so an agent asks on behalf of the box
and gets an answer for every workload on it. The flat fields above
describe a single-application machine, which is every machine today;
on a machine hosting several they are left at their defaults and this
list is the answer.*/
#[serde(default, skip_serializing_if = "::std::vec::Vec::is_empty")]
pub applications: ::std::vec::Vec<ApplicationEntitlements>,
///The certificates Canopy holds for this server.
pub certificates: ::std::vec::Vec<HeldCertificate>,
/**The domains this server's group controls. Any name at or beneath one of
these is a name this server may act on — which is what lets an agent
request a certificate before anything asks for one.*/
pub domains: ::std::vec::Vec<::std::string::String>,
///Whether this server may manage its own DNS records.
pub may_manage_dns: bool,
///Whether this server may obtain its own TLS certificates.
pub may_manage_tls: bool,
/**Whether Canopy is currently making no new changes on this server's
behalf. While true, requests are refused and an agent should wait.*/
pub paused: bool,
///The names this server has registered addresses for.
pub registered_names: ::std::vec::Vec<::std::string::String>,
}
///One health-check result within a status push.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "One health-check result within a status push.",
/// "type": "object",
/// "required": [
/// "check"
/// ],
/// "properties": {
/// "check": {
/// "description": "Name of the check. Must be a non-empty string, and should stay stable\nacross pushes: results for the same name are correlated over time, so\nsuccessive failures and the eventual recovery land on the same issue.",
/// "type": "string"
/// },
/// "healthy": {
/// "description": "Legacy pass/fail form: `true` means `passed`, `false` means `failed`.\nMutually exclusive with `result`.",
/// "type": [
/// "boolean",
/// "null"
/// ]
/// },
/// "result": {
/// "oneOf": [
/// {
/// "type": "null"
/// },
/// {
/// "description": "Outcome of the check: `passed`, `warning`, `failed`, `broken`, or\n`skipped`. Exactly one of `result` / `healthy` must be present per\nentry. `warning` and `failed` open the check's issue as graded by\nits policy; `broken` (the check itself errored, not the system under\ntest) neither confirms nor clears a known failure — the issue stays\nopen, retaining its contribution; `skipped` (a precondition was\nnot met) and `passed` open nothing and close prior issues.",
/// "$ref": "#/components/schemas/CheckResult"
/// }
/// ]
/// }
/// },
/// "additionalProperties": true
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct HealthCheck {
/**Name of the check. Must be a non-empty string, and should stay stable
across pushes: results for the same name are correlated over time, so
successive failures and the eventual recovery land on the same issue.*/
pub check: ::std::string::String,
/**Legacy pass/fail form: `true` means `passed`, `false` means `failed`.
Mutually exclusive with `result`.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub healthy: ::std::option::Option<bool>,
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub result: ::std::option::Option<CheckResult>,
/// Any further keys the schema accepts alongside those above,
/// carried verbatim.
#[serde(flatten)]
#[builder(default)]
pub extra: ::serde_json::Map<::std::string::String, ::serde_json::Value>,
}
/**A certificate Canopy holds for the asking server, as the server needs to see
it: enough to decide whether to renew, and nothing about anyone else.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "A certificate Canopy holds for the asking server, as the server needs to see\nit: enough to decide whether to renew, and nothing about anyone else.",
/// "type": "object",
/// "required": [
/// "key_fingerprint",
/// "key_must_be_replaced",
/// "name",
/// "revoked",
/// "usable"
/// ],
/// "properties": {
/// "key_fingerprint": {
/// "description": "Hex SHA-256 of the certified key's subject public key info, so an agent\ncan tell whether this covers a key it still holds.",
/// "type": "string"
/// },
/// "key_must_be_replaced": {
/// "description": "Whether the key itself is condemned, not just the certificate — the key\npair has to be replaced before asking again.",
/// "type": "boolean"
/// },
/// "name": {
/// "description": "The name it covers.",
/// "type": "string"
/// },
/// "not_after": {
/// "description": "When it expires.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "profile": {
/// "description": "The profile it was issued under, if the authority named one.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "revoked": {
/// "description": "Whether an operator has revoked it. Stop serving it.",
/// "type": "boolean"
/// },
/// "usable": {
/// "description": "Whether it can still be served: not revoked, not expired. True even while\na renewal is under way, the chain in hand staying valid until the new one\nlands.",
/// "type": "boolean"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct HeldCertificate {
/**Hex SHA-256 of the certified key's subject public key info, so an agent
can tell whether this covers a key it still holds.*/
pub key_fingerprint: ::std::string::String,
/**Whether the key itself is condemned, not just the certificate — the key
pair has to be replaced before asking again.*/
pub key_must_be_replaced: bool,
///The name it covers.
pub name: ::std::string::String,
///When it expires.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub not_after: ::std::option::Option<::std::string::String>,
///The profile it was issued under, if the authority named one.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub profile: ::std::option::Option<::std::string::String>,
///Whether an operator has revoked it. Stop serving it.
pub revoked: bool,
/**Whether it can still be served: not revoked, not expired. True even while
a renewal is under way, the chain in hand staying valid until the new one
lands.*/
pub usable: bool,
}
/**One restore purpose a consumer advertises support for: the behaviours it
opts into and the settings it accepts per replica.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "One restore purpose a consumer advertises support for: the behaviours it\nopts into and the settings it accepts per replica.",
/// "type": "object",
/// "required": [
/// "intent"
/// ],
/// "properties": {
/// "description": {
/// "description": "Human-readable description of the intent, if provided.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "intent": {
/// "description": "Name of the intent: an arbitrary identifier chosen by the consumer\n(e.g. `verify`); any name may be advertised.",
/// "type": "string"
/// },
/// "params": {
/// "description": "Configurable parameters this intent accepts per replica, keyed by\nparameter name.",
/// "$ref": "#/components/schemas/BTreeMap"
/// },
/// "semantics": {
/// "description": "Behaviours this intent opts into. Recognised values are `check` (a\nhealth report is expected for each replica), `once` (a given snapshot\nis only ever dispatched to a replica once, rather than repeatedly\nuntil overdue), and `url` (a replica's health report includes a link\nto it). Unrecognised values are stored but have no effect.",
/// "type": "array",
/// "items": {
/// "type": "string"
/// }
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct IntentDescriptor {
///Human-readable description of the intent, if provided.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub description: ::std::option::Option<::std::string::String>,
/**Name of the intent: an arbitrary identifier chosen by the consumer
(e.g. `verify`); any name may be advertised.*/
pub intent: ::std::string::String,
/**Configurable parameters this intent accepts per replica, keyed by
parameter name.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub params: ::std::option::Option<BTreeMap>,
/**Behaviours this intent opts into. Recognised values are `check` (a
health report is expected for each replica), `once` (a given snapshot
is only ever dispatched to a replica once, rather than repeatedly
until overdue), and `url` (a replica's health report includes a link
to it). Unrecognised values are stored but have no effect.*/
#[serde(default, skip_serializing_if = "::std::vec::Vec::is_empty")]
pub semantics: ::std::vec::Vec<::std::string::String>,
}
///The calling identity, the box it is enrolled as, and what runs on that box.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "The calling identity, the box it is enrolled as, and what runs on that box.",
/// "type": "object",
/// "required": [
/// "applications",
/// "device_id",
/// "machine_id"
/// ],
/// "properties": {
/// "applications": {
/// "description": "The types of application Canopy currently holds for that machine. Empty\nfor a box that has enrolled but not yet reported what runs on it, which\nis awaiting a report rather than an error.\n\nA workload is named by its type, which is what the reporter itself said\nit was. Canopy's own identifier for an application is internal and never\non the wire.",
/// "type": "array",
/// "items": {
/// "$ref": "#/components/schemas/ApplicationType"
/// }
/// },
/// "device_id": {
/// "description": "The calling identity's own identifier.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "machine_id": {
/// "description": "The machine this identity is enrolled as.",
/// "type": "string",
/// "format": "uuid"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct MachineSelfResponse {
/**The types of application Canopy currently holds for that machine. Empty
for a box that has enrolled but not yet reported what runs on it, which
is awaiting a report rather than an error.
A workload is named by its type, which is what the reporter itself said
it was. Canopy's own identifier for an application is internal and never
on the wire.*/
pub applications: ::std::vec::Vec<ApplicationType>,
///The calling identity's own identifier.
pub device_id: ::uuid::Uuid,
///The machine this identity is enrolled as.
pub machine_id: ::uuid::Uuid,
}
///How the target version's migrations went against the restored replica.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "How the target version's migrations went against the restored replica.",
/// "type": "object",
/// "required": [
/// "data_bytes_after",
/// "data_bytes_before",
/// "timings",
/// "total_elapsed_seconds"
/// ],
/// "properties": {
/// "application_type": {
/// "description": "The type of application whose candidate version was tried, echoed from\nthe worklist entry's `application_type`. Omitted by a consumer that\npredates the entry carrying it, in which case Canopy derives the\napplication from the machine and the version.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "data_bytes_after": {
/// "description": "Size of the data after they ran. The growth between the two is what shows\na migration that backfills heavily.",
/// "type": "integer",
/// "format": "int64"
/// },
/// "data_bytes_before": {
/// "description": "Size of the data before the migrations ran.",
/// "type": "integer",
/// "format": "int64"
/// },
/// "error": {
/// "description": "What the migration runner said about that failure: the message, and the\nDETAIL naming the row it refused, which is what tells a deployment what\nto fix. Send no connection strings or credentials. Kept to the first\n2000 characters.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "failed_migration": {
/// "description": "The migration that failed, when one did.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "target_version": {
/// "description": "The version whose migrations were applied, as semver, taken from the\nworklist entry's `target_version`. This is the version the consumer\nactually migrated to; send it in preference to echoing the identifier.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "target_version_id": {
/// "description": "The version whose migrations were applied, as the identifier a consumer\nechoes from the worklist entry's `target_version_id`. Accepted only for\nolder consumers that report the identifier; omit it when `target_version`\nis sent.",
/// "type": [
/// "string",
/// "null"
/// ],
/// "format": "uuid"
/// },
/// "timings": {
/// "description": "One entry per migration that ran, in the order they ran.",
/// "type": "array",
/// "items": {
/// "$ref": "#/components/schemas/MigrationTimingArgs"
/// }
/// },
/// "total_elapsed_seconds": {
/// "description": "Whole seconds the whole migration run took.",
/// "type": "integer",
/// "format": "int64"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct MigrationArgs {
/**The type of application whose candidate version was tried, echoed from
the worklist entry's `application_type`. Omitted by a consumer that
predates the entry carrying it, in which case Canopy derives the
application from the machine and the version.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub application_type: ::std::option::Option<::std::string::String>,
/**Size of the data after they ran. The growth between the two is what shows
a migration that backfills heavily.*/
pub data_bytes_after: i64,
///Size of the data before the migrations ran.
pub data_bytes_before: i64,
/**What the migration runner said about that failure: the message, and the
DETAIL naming the row it refused, which is what tells a deployment what
to fix. Send no connection strings or credentials. Kept to the first
2000 characters.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub error: ::std::option::Option<::std::string::String>,
///The migration that failed, when one did.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub failed_migration: ::std::option::Option<::std::string::String>,
/**The version whose migrations were applied, as semver, taken from the
worklist entry's `target_version`. This is the version the consumer
actually migrated to; send it in preference to echoing the identifier.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub target_version: ::std::option::Option<::std::string::String>,
/**The version whose migrations were applied, as the identifier a consumer
echoes from the worklist entry's `target_version_id`. Accepted only for
older consumers that report the identifier; omit it when `target_version`
is sent.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub target_version_id: ::std::option::Option<::uuid::Uuid>,
///One entry per migration that ran, in the order they ran.
pub timings: ::std::vec::Vec<MigrationTimingArgs>,
///Whole seconds the whole migration run took.
pub total_elapsed_seconds: i64,
}
///How long one migration took.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "How long one migration took.",
/// "type": "object",
/// "required": [
/// "elapsed_seconds",
/// "name"
/// ],
/// "properties": {
/// "elapsed_seconds": {
/// "description": "Whole seconds it took.",
/// "type": "integer",
/// "format": "int64"
/// },
/// "name": {
/// "description": "The migration's name, as the migration runner reports it.",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct MigrationTimingArgs {
///Whole seconds it took.
pub elapsed_seconds: i64,
///The migration's name, as the migration runner reports it.
pub name: ::std::string::String,
}
/**The data type of a restore-replica configuration parameter, which
determines how its value is validated. `duration` and `bytes` values must
be non-negative integers (a count of seconds and of bytes, respectively);
`integer` accepts any whole number, positive or negative; `boolean` is a
JSON boolean; `text` is a JSON string.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "The data type of a restore-replica configuration parameter, which\ndetermines how its value is validated. `duration` and `bytes` values must\nbe non-negative integers (a count of seconds and of bytes, respectively);\n`integer` accepts any whole number, positive or negative; `boolean` is a\nJSON boolean; `text` is a JSON string.",
/// "type": "string",
/// "enum": [
/// "duration",
/// "bytes",
/// "boolean",
/// "integer",
/// "text"
/// ]
///}
/// ```
/// </details>
#[derive(
::serde::Deserialize,
::serde::Serialize,
Clone,
Copy,
Debug,
Eq,
Hash,
Ord,
PartialEq,
PartialOrd
)]
pub enum ParamType {
#[serde(rename = "duration")]
Duration,
#[serde(rename = "bytes")]
Bytes,
#[serde(rename = "boolean")]
Boolean,
#[serde(rename = "integer")]
Integer,
#[serde(rename = "text")]
Text,
}
impl ::std::fmt::Display for ParamType {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
match *self {
Self::Duration => f.write_str("duration"),
Self::Bytes => f.write_str("bytes"),
Self::Boolean => f.write_str("boolean"),
Self::Integer => f.write_str("integer"),
Self::Text => f.write_str("text"),
}
}
}
impl ::std::str::FromStr for ParamType {
type Err = self::error::ConversionError;
fn from_str(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
match value {
"duration" => Ok(Self::Duration),
"bytes" => Ok(Self::Bytes),
"boolean" => Ok(Self::Boolean),
"integer" => Ok(Self::Integer),
"text" => Ok(Self::Text),
_ => Err("invalid value".into()),
}
}
}
impl ::std::convert::TryFrom<&str> for ParamType {
type Error = self::error::ConversionError;
fn try_from(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for ParamType {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for ParamType {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
/**Standard error response body, returned for every non-2xx response.
This follows the RFC 7807 "Problem Details" shape: a stable machine-readable
`type`, a short `title`, the repeated HTTP `status` code, and an optional
`detail` string with specifics of this particular occurrence.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Standard error response body, returned for every non-2xx response.\n\nThis follows the RFC 7807 \"Problem Details\" shape: a stable machine-readable\n`type`, a short `title`, the repeated HTTP `status` code, and an optional\n`detail` string with specifics of this particular occurrence.",
/// "type": "object",
/// "required": [
/// "status",
/// "title",
/// "type"
/// ],
/// "properties": {
/// "detail": {
/// "description": "Human-readable explanation specific to this occurrence of the\nproblem, if any extra detail is available.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "status": {
/// "description": "HTTP status code of the response, repeated here for convenience.",
/// "type": "integer",
/// "format": "int32",
/// "minimum": 0.0,
/// "example": 404
/// },
/// "title": {
/// "description": "Short, human-readable summary of the problem type. Does not vary\nbetween occurrences of the same `type`.",
/// "type": "string"
/// },
/// "type": {
/// "description": "A URI reference identifying the problem type. Stable across\noccurrences of the same error, so callers can match on it.",
/// "type": "string",
/// "format": "uri",
/// "example": "/errors/resource-not-found"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct ProblemDetailsSchema {
/**Human-readable explanation specific to this occurrence of the
problem, if any extra detail is available.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub detail: ::std::option::Option<::std::string::String>,
///HTTP status code of the response, repeated here for convenience.
pub status: i32,
/**Short, human-readable summary of the problem type. Does not vary
between occurrences of the same `type`.*/
pub title: ::std::string::String,
/**A URI reference identifying the problem type. Stable across
occurrences of the same error, so callers can match on it.*/
#[serde(rename = "type")]
pub type_: ::std::string::String,
}
///A progress sample from a run still in flight.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "A progress sample from a run still in flight.",
/// "type": "object",
/// "required": [
/// "run_id",
/// "type"
/// ],
/// "properties": {
/// "bytes_cached": {
/// "description": "Bytes found already present in the repository, and so not re-uploaded.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "bytes_estimated": {
/// "description": "Total bytes this run currently expects to handle. May be revised upward.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "bytes_hashed": {
/// "description": "Bytes processed (hashed, compressed) so far.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "bytes_read": {
/// "description": "Source bytes read so far.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "bytes_uploaded": {
/// "description": "Bytes uploaded to the repository so far.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "current_path": {
/// "description": "What the run is working on right now, for display.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "errors": {
/// "description": "Errors hit so far.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "extra": {
/// "description": "Any further detail the backup engine emits. Canopy makes no commitment\nabout its shape: it is stored and shown verbatim, never interpreted.",
/// "type": "object"
/// },
/// "files_done": {
/// "description": "Files finished so far.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "files_estimated": {
/// "description": "Total files this run currently expects to handle.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "ignored_errors": {
/// "description": "Errors hit and deliberately ignored so far.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "purpose": {
/// "description": "Whether this is a `backup` or a `restore` run.",
/// "$ref": "#/components/schemas/BackupPurpose"
/// },
/// "run_id": {
/// "description": "The run-uuid the client minted for this run — the same one it passes to\n`POST /backup-credentials` and reports under at `POST /backup-report`.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "s3_received_payload_bytes": {
/// "description": "Bytes of decoded object payload received from S3 so far.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "s3_received_raw_bytes": {
/// "description": "Bytes of raw HTTP traffic received from S3 so far.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "s3_sent_payload_bytes": {
/// "description": "Bytes of decoded object payload sent to S3 so far.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "s3_sent_raw_bytes": {
/// "description": "Bytes of raw HTTP traffic sent to S3 so far, including protocol and\nsigning overhead.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "snapshot_taken_at": {
/// "description": "When this run froze the data it is backing up — the point in time the\nbackup represents, as opposed to when its upload finishes. Send it as soon\nas it is known (before any transfer starts). Recorded once per run: the\nfirst value Canopy sees stands, whether it arrives here or on the report.",
/// "oneOf": [
/// {
/// "type": "null"
/// },
/// {
/// "$ref": "#/definitions/CanopyTimestamp"
/// }
/// ]
/// },
/// "type": {
/// "description": "The backup type being run (e.g. `tamanu-postgres`).",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct ProgressArgs {
///Bytes found already present in the repository, and so not re-uploaded.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub bytes_cached: ::std::option::Option<i64>,
///Total bytes this run currently expects to handle. May be revised upward.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub bytes_estimated: ::std::option::Option<i64>,
///Bytes processed (hashed, compressed) so far.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub bytes_hashed: ::std::option::Option<i64>,
///Source bytes read so far.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub bytes_read: ::std::option::Option<i64>,
///Bytes uploaded to the repository so far.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub bytes_uploaded: ::std::option::Option<i64>,
///What the run is working on right now, for display.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub current_path: ::std::option::Option<::std::string::String>,
///Errors hit so far.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub errors: ::std::option::Option<i64>,
/**Any further detail the backup engine emits. Canopy makes no commitment
about its shape: it is stored and shown verbatim, never interpreted.*/
#[serde(default, skip_serializing_if = "::serde_json::Map::is_empty")]
pub extra: ::serde_json::Map<::std::string::String, ::serde_json::Value>,
///Files finished so far.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub files_done: ::std::option::Option<i64>,
///Total files this run currently expects to handle.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub files_estimated: ::std::option::Option<i64>,
///Errors hit and deliberately ignored so far.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub ignored_errors: ::std::option::Option<i64>,
///Whether this is a `backup` or a `restore` run.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub purpose: ::std::option::Option<BackupPurpose>,
/**The run-uuid the client minted for this run — the same one it passes to
`POST /backup-credentials` and reports under at `POST /backup-report`.*/
pub run_id: ::uuid::Uuid,
///Bytes of decoded object payload received from S3 so far.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub s3_received_payload_bytes: ::std::option::Option<i64>,
///Bytes of raw HTTP traffic received from S3 so far.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub s3_received_raw_bytes: ::std::option::Option<i64>,
///Bytes of decoded object payload sent to S3 so far.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub s3_sent_payload_bytes: ::std::option::Option<i64>,
/**Bytes of raw HTTP traffic sent to S3 so far, including protocol and
signing overhead.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub s3_sent_raw_bytes: ::std::option::Option<i64>,
/**When this run froze the data it is backing up — the point in time the
backup represents, as opposed to when its upload finishes. Send it as soon
as it is known (before any transfer starts). Recorded once per run: the
first value Canopy sees stands, whether it arrives here or on the report.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub snapshot_taken_at: ::std::option::Option<::jiff::Timestamp>,
///The backup type being run (e.g. `tamanu-postgres`).
#[serde(rename = "type")]
pub type_: ::std::string::String,
}
///A publicly-listed central server that a client can connect to.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "A publicly-listed central server that a client can connect to.",
/// "type": "object",
/// "required": [
/// "host",
/// "name"
/// ],
/// "properties": {
/// "host": {
/// "description": "The server's reachable base URL.",
/// "$ref": "#/components/schemas/UrlField"
/// },
/// "name": {
/// "description": "Public-facing display name of the server.",
/// "type": "string"
/// },
/// "rank": {
/// "oneOf": [
/// {
/// "type": "null"
/// },
/// {
/// "description": "The server's environment tier (production, clone, demo, test, or\ndev), if set. Used to order the listing and to let clients label\nnon-production entries.",
/// "$ref": "#/components/schemas/ServerRank"
/// }
/// ]
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct PublicServer {
///The server's reachable base URL.
pub host: UrlField,
///Public-facing display name of the server.
pub name: ::std::string::String,
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub rank: ::std::option::Option<ServerRank>,
}
/**How the masking manifest went against the restored replica.
Reported when the redaction settles, which for a failure is before any
switchover: the restore itself succeeded and is reported healthy, and the
replica stays on the data it was already serving.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "How the masking manifest went against the restored replica.\n\nReported when the redaction settles, which for a failure is before any\nswitchover: the restore itself succeeded and is reported healthy, and the\nreplica stays on the data it was already serving.",
/// "type": "object",
/// "required": [
/// "outcome"
/// ],
/// "properties": {
/// "columns_masked": {
/// "description": "How many columns the manifest masked.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "columns_skipped": {
/// "description": "How many columns the manifest named but could not mask. Non-zero is\nwhat makes an outcome `partial`.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "error": {
/// "description": "Why the redaction failed, when it did.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "manifest_version": {
/// "description": "The version resolved into the manifest URL. Omit when the URL named no\nversion to resolve.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "outcome": {
/// "description": "How far the manifest got: `complete`, `partial`, or `failed`.",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct RedactionArgs {
///How many columns the manifest masked.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub columns_masked: ::std::option::Option<i64>,
/**How many columns the manifest named but could not mask. Non-zero is
what makes an outcome `partial`.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub columns_skipped: ::std::option::Option<i64>,
///Why the redaction failed, when it did.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub error: ::std::option::Option<::std::string::String>,
/**The version resolved into the manifest URL. Omit when the URL named no
version to resolve.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub manifest_version: ::std::option::Option<::std::string::String>,
///How far the manifest got: `complete`, `partial`, or `failed`.
pub outcome: ::std::string::String,
}
///The name a server should be reachable at, and where.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "The name a server should be reachable at, and where.",
/// "type": "object",
/// "required": [
/// "addresses",
/// "name"
/// ],
/// "properties": {
/// "addresses": {
/// "description": "Every external address this server is reachable at. IPv4 addresses become\nA records and IPv6 addresses AAAA records, replacing whatever was\nregistered before. An empty list withdraws the name.",
/// "type": "array",
/// "items": {
/// "type": "string"
/// }
/// },
/// "name": {
/// "description": "The name to publish records at. Must sit within a domain this server's\ngroup controls.",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct RegisterNameArgs {
/**Every external address this server is reachable at. IPv4 addresses become
A records and IPv6 addresses AAAA records, replacing whatever was
registered before. An empty list withdraws the name.*/
pub addresses: ::std::vec::Vec<::std::string::String>,
/**The name to publish records at. Must sit within a domain this server's
group controls.*/
pub name: ::std::string::String,
}
///What Canopy holds for a registered name.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "What Canopy holds for a registered name.",
/// "type": "object",
/// "required": [
/// "addresses",
/// "name",
/// "published",
/// "published_addresses"
/// ],
/// "properties": {
/// "addresses": {
/// "description": "The addresses Canopy will publish.",
/// "type": "array",
/// "items": {
/// "type": "string"
/// }
/// },
/// "last_error": {
/// "description": "Why the last publish attempt failed, if it did.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "name": {
/// "description": "The name, as Canopy normalised it.",
/// "type": "string"
/// },
/// "published": {
/// "description": "Whether the zone has caught up with what was asked for.",
/// "type": "boolean"
/// },
/// "published_addresses": {
/// "description": "The addresses Canopy has published so far. Differs from `addresses` until\nthe change has been reconciled into the zone.",
/// "type": "array",
/// "items": {
/// "type": "string"
/// }
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct RegisteredName {
///The addresses Canopy will publish.
pub addresses: ::std::vec::Vec<::std::string::String>,
///Why the last publish attempt failed, if it did.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub last_error: ::std::option::Option<::std::string::String>,
///The name, as Canopy normalised it.
pub name: ::std::string::String,
///Whether the zone has caught up with what was asked for.
pub published: bool,
/**The addresses Canopy has published so far. Differs from `addresses` until
the change has been reconciled into the zone.*/
pub published_addresses: ::std::vec::Vec<::std::string::String>,
}
///Report of a completed backup or restore run.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Report of a completed backup or restore run.",
/// "type": "object",
/// "required": [
/// "outcome",
/// "purpose",
/// "run_id",
/// "type"
/// ],
/// "properties": {
/// "bytes_uploaded": {
/// "description": "Total bytes of backup data uploaded during the run, if known.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "error": {
/// "description": "Human-readable error detail, when the run failed.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "outcome": {
/// "description": "Whether the run succeeded (`success`) or failed (`failure`).",
/// "$ref": "#/components/schemas/RunOutcome"
/// },
/// "purpose": {
/// "description": "Whether the run was a `backup` or a `restore`.",
/// "$ref": "#/components/schemas/BackupPurpose"
/// },
/// "run_id": {
/// "description": "Client-generated UUID identifying this run, minted at run start. Each\nrun must use a fresh UUID: reporting the same `run_id` twice is\nrejected with 409.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "s3_received_payload_bytes": {
/// "description": "Bytes of decoded object payload received from S3 during the run.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "s3_received_raw_bytes": {
/// "description": "Bytes of raw HTTP traffic received from S3 during the run, including\nprotocol overhead.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "s3_sent_payload_bytes": {
/// "description": "Bytes of decoded object payload sent to S3 during the run (excluding\nprotocol and signing overhead).",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "s3_sent_raw_bytes": {
/// "description": "Bytes of raw HTTP traffic sent to S3 during the run, including protocol\nand signing overhead. Report on both success and failure; omit when\ntraffic was not measured.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "snapshot_id": {
/// "description": "Identifier of the repository snapshot the run produced, for a\nsuccessful backup.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "snapshot_taken_at": {
/// "description": "When this run froze the data it backed up — the point in time the backup\nrepresents, as opposed to when its upload finished. Often a filesystem-level\nsnapshot taken before the transfer, in which case it is not recoverable\nfrom the repository and only the device can report it. Recorded once per\nrun: if progress reports already carried it, that value stands.",
/// "oneOf": [
/// {
/// "type": "null"
/// },
/// {
/// "$ref": "#/definitions/CanopyTimestamp"
/// }
/// ]
/// },
/// "type": {
/// "description": "The backup type that ran (e.g. `tamanu-postgres`).",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct ReportArgs {
///Total bytes of backup data uploaded during the run, if known.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub bytes_uploaded: ::std::option::Option<i64>,
///Human-readable error detail, when the run failed.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub error: ::std::option::Option<::std::string::String>,
///Whether the run succeeded (`success`) or failed (`failure`).
pub outcome: RunOutcome,
///Whether the run was a `backup` or a `restore`.
pub purpose: BackupPurpose,
/**Client-generated UUID identifying this run, minted at run start. Each
run must use a fresh UUID: reporting the same `run_id` twice is
rejected with 409.*/
pub run_id: ::uuid::Uuid,
///Bytes of decoded object payload received from S3 during the run.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub s3_received_payload_bytes: ::std::option::Option<i64>,
/**Bytes of raw HTTP traffic received from S3 during the run, including
protocol overhead.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub s3_received_raw_bytes: ::std::option::Option<i64>,
/**Bytes of decoded object payload sent to S3 during the run (excluding
protocol and signing overhead).*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub s3_sent_payload_bytes: ::std::option::Option<i64>,
/**Bytes of raw HTTP traffic sent to S3 during the run, including protocol
and signing overhead. Report on both success and failure; omit when
traffic was not measured.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub s3_sent_raw_bytes: ::std::option::Option<i64>,
/**Identifier of the repository snapshot the run produced, for a
successful backup.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub snapshot_id: ::std::option::Option<::std::string::String>,
/**When this run froze the data it backed up — the point in time the backup
represents, as opposed to when its upload finished. Often a filesystem-level
snapshot taken before the transfer, in which case it is not recoverable
from the repository and only the device can report it. Recorded once per
run: if progress reports already carried it, that value stands.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub snapshot_taken_at: ::std::option::Option<::jiff::Timestamp>,
///The backup type that ran (e.g. `tamanu-postgres`).
#[serde(rename = "type")]
pub type_: ::std::string::String,
}
///A request to certify a key for a name.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "A request to certify a key for a name.",
/// "type": "object",
/// "required": [
/// "csr",
/// "name"
/// ],
/// "properties": {
/// "csr": {
/// "description": "The certificate signing request, DER, base64. Must ask for exactly `name`\nand nothing else — a request carrying any other name is refused rather\nthan trimmed.",
/// "type": "string"
/// },
/// "name": {
/// "description": "The name to certify. Must sit within a domain this server's group\ncontrols.",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct RequestCertificateArgs {
/**The certificate signing request, DER, base64. Must ask for exactly `name`
and nothing else — a request carrying any other name is refused rather
than trimmed.*/
pub csr: ::std::string::String,
/**The name to certify. Must sit within a domain this server's group
controls.*/
pub name: ::std::string::String,
}
/**Request body for registering the restore intents a consumer device can
satisfy.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Request body for registering the restore intents a consumer device can\nsatisfy.",
/// "type": "object",
/// "required": [
/// "intents"
/// ],
/// "properties": {
/// "intents": {
/// "description": "The intents this device can satisfy — arbitrary consumer-chosen\nidentifiers (e.g. `verify`) — each with its description, the semantics\nit opts into, and the schema of the parameters it accepts. Replaces the\ndevice's previously advertised set wholesale.",
/// "type": "array",
/// "items": {
/// "$ref": "#/components/schemas/IntentDescriptor"
/// }
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct RestoreCapabilitiesArgs {
/**The intents this device can satisfy — arbitrary consumer-chosen
identifiers (e.g. `verify`) — each with its description, the semantics
it opts into, and the schema of the parameters it accepts. Replaces the
device's previously advertised set wholesale.*/
pub intents: ::std::vec::Vec<IntentDescriptor>,
}
/**Read-only S3 credentials plus the repository passphrase for one group and
backup type: everything needed to open the group's backup repository and
read a snapshot out of it.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Read-only S3 credentials plus the repository passphrase for one group and\nbackup type: everything needed to open the group's backup repository and\nread a snapshot out of it.",
/// "type": "object",
/// "required": [
/// "credentials",
/// "repo_password"
/// ],
/// "properties": {
/// "credentials": {
/// "description": "Temporary read-only AWS credentials in the `credential_process` output\nformat, valid for at most one hour.",
/// "$ref": "#/components/schemas/CredentialProcessOutput"
/// },
/// "repo_password": {
/// "description": "Passphrase for the group's backup repository (a Kopia repository).",
/// "$ref": "#/definitions/CanopySecret"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct RestoreCredentials {
/**Temporary read-only AWS credentials in the `credential_process` output
format, valid for at most one hour.*/
pub credentials: CredentialProcessOutput,
///Passphrase for the group's backup repository (a Kopia repository).
pub repo_password: crate::Redacted<::std::string::String>,
}
///Request body for minting read-only restore credentials.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Request body for minting read-only restore credentials.",
/// "type": "object",
/// "required": [
/// "group",
/// "type"
/// ],
/// "properties": {
/// "group": {
/// "description": "The server group whose backup repository to read.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "run_id": {
/// "description": "This must be the run-uuid the client minted for this run.\nThe field is optional only so older clients don't break; it WILL be made\nmandatory in future.",
/// "type": [
/// "string",
/// "null"
/// ],
/// "format": "uuid"
/// },
/// "type": {
/// "description": "The backup type to restore (e.g. `tamanu-postgres`).",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct RestoreCredentialsArgs {
///The server group whose backup repository to read.
pub group: ::uuid::Uuid,
/**This must be the run-uuid the client minted for this run.
The field is optional only so older clients don't break; it WILL be made
mandatory in future.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub run_id: ::std::option::Option<::uuid::Uuid>,
///The backup type to restore (e.g. `tamanu-postgres`).
#[serde(rename = "type")]
pub type_: ::std::string::String,
}
///Outcome of a reported backup or restore run.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Outcome of a reported backup or restore run.",
/// "type": "string",
/// "enum": [
/// "success",
/// "failure"
/// ]
///}
/// ```
/// </details>
#[derive(
::serde::Deserialize,
::serde::Serialize,
Clone,
Copy,
Debug,
Eq,
Hash,
Ord,
PartialEq,
PartialOrd
)]
pub enum RunOutcome {
#[serde(rename = "success")]
Success,
#[serde(rename = "failure")]
Failure,
}
impl ::std::fmt::Display for RunOutcome {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
match *self {
Self::Success => f.write_str("success"),
Self::Failure => f.write_str("failure"),
}
}
}
impl ::std::str::FromStr for RunOutcome {
type Err = self::error::ConversionError;
fn from_str(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
match value {
"success" => Ok(Self::Success),
"failure" => Ok(Self::Failure),
_ => Err("invalid value".into()),
}
}
}
impl ::std::convert::TryFrom<&str> for RunOutcome {
type Error = self::error::ConversionError;
fn try_from(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for RunOutcome {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for RunOutcome {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
///The calling device's own identity, as assigned at enrollment.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "The calling device's own identity, as assigned at enrollment.",
/// "type": "object",
/// "required": [
/// "device_id",
/// "server_id"
/// ],
/// "properties": {
/// "device_id": {
/// "description": "The calling device's own identity.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "server_id": {
/// "description": "The box the calling device is enrolled as. This is the id a device\npushes status against, and the one `GET /machines/self` calls\n`machine_id`.",
/// "type": "string",
/// "format": "uuid"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct SelfResponse {
///The calling device's own identity.
pub device_id: ::uuid::Uuid,
/**The box the calling device is enrolled as. This is the id a device
pushes status against, and the one `GET /machines/self` calls
`machine_id`.*/
pub server_id: ::uuid::Uuid,
}
///The environment tier of a server, from `production` down to `dev`.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "The environment tier of a server, from `production` down to `dev`.",
/// "type": "string",
/// "enum": [
/// "production",
/// "clone",
/// "demo",
/// "test",
/// "dev"
/// ]
///}
/// ```
/// </details>
#[derive(
::serde::Deserialize,
::serde::Serialize,
Clone,
Copy,
Debug,
Eq,
Hash,
Ord,
PartialEq,
PartialOrd
)]
pub enum ServerRank {
#[serde(rename = "production")]
Production,
#[serde(rename = "clone")]
Clone,
#[serde(rename = "demo")]
Demo,
#[serde(rename = "test")]
Test,
#[serde(rename = "dev")]
Dev,
}
impl ::std::fmt::Display for ServerRank {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
match *self {
Self::Production => f.write_str("production"),
Self::Clone => f.write_str("clone"),
Self::Demo => f.write_str("demo"),
Self::Test => f.write_str("test"),
Self::Dev => f.write_str("dev"),
}
}
}
impl ::std::str::FromStr for ServerRank {
type Err = self::error::ConversionError;
fn from_str(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
match value {
"production" => Ok(Self::Production),
"clone" => Ok(Self::Clone),
"demo" => Ok(Self::Demo),
"test" => Ok(Self::Test),
"dev" => Ok(Self::Dev),
_ => Err("invalid value".into()),
}
}
}
impl ::std::convert::TryFrom<&str> for ServerRank {
type Error = self::error::ConversionError;
fn try_from(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for ServerRank {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for ServerRank {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
///A single named SQL snippet from the bestool snippet library.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "A single named SQL snippet from the bestool snippet library.",
/// "type": "object",
/// "required": [
/// "sql"
/// ],
/// "properties": {
/// "description": {
/// "description": "Human-readable explanation of what the snippet does, if the author\nprovided one.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "sql": {
/// "description": "The snippet's SQL text.",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct SnippetResponse {
/**Human-readable explanation of what the snippet does, if the author
provided one.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub description: ::std::option::Option<::std::string::String>,
///The snippet's SQL text.
pub sql: ::std::string::String,
}
/**A status push: a server's periodic heartbeat carrying its self-reported
health.
Besides the reserved `healthy` and `health` keys described here, any
additional top-level fields are accepted and stored verbatim as extra
status data.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "A status push: a server's periodic heartbeat carrying its self-reported\nhealth.\n\nBesides the reserved `healthy` and `health` keys described here, any\nadditional top-level fields are accepted and stored verbatim as extra\nstatus data.",
/// "type": "object",
/// "required": [
/// "health"
/// ],
/// "properties": {
/// "applications": {
/// "description": "The applications the reporter found on the machine, each with its own\nhealth checks and detail, keyed by a key the reporter chooses.\n\nThe key must be unique among the applications on that machine and must\nidentify the same application across this reporter's pushes; what it is\nderived from is the reporter's own business. Canopy correlates on the\nmachine, the key and the type together, and never discloses its own\nidentifier for an application.\n\nOnly read alongside `machine`. An application named here that Canopy\ndoes not already hold is created.",
/// "type": [
/// "object",
/// "null"
/// ],
/// "additionalProperties": {
/// "$ref": "#/components/schemas/ApplicationReport"
/// },
/// "propertyNames": {
/// "type": "string"
/// }
/// },
/// "health": {
/// "description": "Per-check breakdown. A push without a `health` array is the legacy\nTamanu direct-report format: it is treated as the `tamanu` source\nreporting a single always-passing `tasks` heartbeat check. May be\nempty (`[]`) for a source that genuinely runs no checks — which\nrecovers every check it previously reported. Each entry must\ninclude a non-empty `check` name and exactly one of `result` /\n`healthy`; any additional fields per check (latency, free disk %,\ncertificate expiry, etc.) are passed through verbatim and shown in the\nstatus UI.\n\nEvery check name seen — whatever its result — is added to the\noperator-facing check catalog, where the policy grading its results\ncan be reviewed and adjusted. A check whose effective result is\nfailed or warning opens (or keeps open) its issue; a broken check\nkeeps the same issue open, retaining a known failure's contribution\nwhile warning the check itself is broken; effective passed and\nskipped results open nothing and close prior issues.",
/// "type": "array",
/// "items": {
/// "$ref": "#/components/schemas/HealthCheck"
/// }
/// },
/// "healthy": {
/// "description": "Overall self-reported health of the server. **Absent means `true`**,\nso senders that predate this field are never treated as unhealthy by\nomission. Recorded for historical analysis and display, but **not\nconsulted for incident or severity decisions** — those are derived\nfrom the per-check results in `health`, with each check's severity\ncontrolled by an operator-managed catalog.",
/// "type": [
/// "boolean",
/// "null"
/// ]
/// },
/// "machine": {
/// "oneOf": [
/// {
/// "type": "null"
/// },
/// {
/// "description": "The machine's own health checks and detail: what the box is, rather\nthan what runs on it.\n\nSending this puts the push in the current format, and Canopy takes the\nseparation as given. A push without it is a transitional unified push,\nwhich Canopy separates into the two grains itself from `health` and the\nflat body.",
/// "$ref": "#/components/schemas/TargetReport"
/// }
/// ]
/// },
/// "source": {
/// "description": "The name of the source pushing this status: the reporting agent, e.g.\n`alertd`. Multiple sources may report on one server, each with its own\nset of checks; a source's push only opens and recovers its own checks.\n\n**Transitionally optional: this field will become mandatory.** A push\nwithout a `source` is attributed to `alertd`; new reporters must send\ntheir own name. Must be a non-empty string; the names `canopy` and\n`manual` are reserved for canopy itself and are rejected.",
/// "type": [
/// "string",
/// "null"
/// ]
/// }
/// },
/// "additionalProperties": true
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct StatusPayload {
/**The applications the reporter found on the machine, each with its own
health checks and detail, keyed by a key the reporter chooses.
The key must be unique among the applications on that machine and must
identify the same application across this reporter's pushes; what it is
derived from is the reporter's own business. Canopy correlates on the
machine, the key and the type together, and never discloses its own
identifier for an application.
Only read alongside `machine`. An application named here that Canopy
does not already hold is created.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub applications: ::std::option::Option<
::std::collections::HashMap<::std::string::String, ApplicationReport>,
>,
/**Per-check breakdown. A push without a `health` array is the legacy
Tamanu direct-report format: it is treated as the `tamanu` source
reporting a single always-passing `tasks` heartbeat check. May be
empty (`[]`) for a source that genuinely runs no checks — which
recovers every check it previously reported. Each entry must
include a non-empty `check` name and exactly one of `result` /
`healthy`; any additional fields per check (latency, free disk %,
certificate expiry, etc.) are passed through verbatim and shown in the
status UI.
Every check name seen — whatever its result — is added to the
operator-facing check catalog, where the policy grading its results
can be reviewed and adjusted. A check whose effective result is
failed or warning opens (or keeps open) its issue; a broken check
keeps the same issue open, retaining a known failure's contribution
while warning the check itself is broken; effective passed and
skipped results open nothing and close prior issues.*/
pub health: ::std::vec::Vec<HealthCheck>,
/**Overall self-reported health of the server. **Absent means `true`**,
so senders that predate this field are never treated as unhealthy by
omission. Recorded for historical analysis and display, but **not
consulted for incident or severity decisions** — those are derived
from the per-check results in `health`, with each check's severity
controlled by an operator-managed catalog.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub healthy: ::std::option::Option<bool>,
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub machine: ::std::option::Option<TargetReport>,
/**The name of the source pushing this status: the reporting agent, e.g.
`alertd`. Multiple sources may report on one server, each with its own
set of checks; a source's push only opens and recovers its own checks.
**Transitionally optional: this field will become mandatory.** A push
without a `source` is attributed to `alertd`; new reporters must send
their own name. Must be a non-empty string; the names `canopy` and
`manual` are reserved for canopy itself and are rejected.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub source: ::std::option::Option<::std::string::String>,
/// Any further keys the schema accepts alongside those above,
/// carried verbatim.
#[serde(flatten)]
#[builder(default)]
pub extra: ::serde_json::Map<::std::string::String, ::serde_json::Value>,
}
/**The status-push response: only the return-path instructions the device
can act on. The stored status record is deliberately not echoed back —
the device already has everything it sent.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "The status-push response: only the return-path instructions the device\ncan act on. The stored status record is deliberately not echoed back —\nthe device already has everything it sent.",
/// "type": "object",
/// "required": [
/// "backup_now",
/// "check_severities",
/// "names",
/// "tags"
/// ],
/// "properties": {
/// "applications": {
/// "description": "Canopy's answer about each application the push described, keyed by the\nkey the reporter named it with. Present only for a push in the current\nformat.\n\nA key Canopy holds no application for is absent rather than empty,\nwhich is what a source whose pushes are ignored sees: nothing was\ncreated for it to be told about.",
/// "type": [
/// "object",
/// "null"
/// ],
/// "additionalProperties": {
/// "$ref": "#/components/schemas/TargetResponse"
/// },
/// "propertyNames": {
/// "type": "string"
/// }
/// },
/// "backup_now": {
/// "description": "Backup types the server should back up now: operator-requested\none-offs plus scheduled backups that are due. Each serializes as a\nplain string (e.g. `\"tamanu-postgres\"`). The device should run each\nlisted type, then report via `POST /backup-report`; an empty list\nmeans nothing to do. Only sent to `alertd` pushes (the agent that\nruns backups); other sources always receive an empty list.",
/// "type": "array",
/// "items": {
/// "type": "string"
/// }
/// },
/// "check_severities": {
/// "description": "The effective handling of every healthcheck canopy knows about, keyed\nby check name (as reported in `health[].check`): `skip` (silenced for\nthis server, or classified below warning), `warn` (warning), or `fail`\n(error or critical). Only the static severity baseline is reflected —\noperator-defined conditional rules are evaluated per push and not\nincluded. Checks absent from the map are new to canopy and default to\n`warn`. Clients that predate this field can safely ignore it; the\nsame mapping is served on demand at `GET /status/{server_id}/check-severities`.",
/// "type": "object",
/// "additionalProperties": {
/// "$ref": "#/components/schemas/CheckSeverity"
/// },
/// "propertyNames": {
/// "type": "string"
/// }
/// },
/// "machine": {
/// "oneOf": [
/// {
/// "type": "null"
/// },
/// {
/// "description": "Canopy's answer about the machine. Present only for a push in the\ncurrent format: a transitional unified push is answered by the flat\nfields above and nothing else, so the response a fielded reporter sees\nis the one it already saw.",
/// "$ref": "#/components/schemas/TargetResponse"
/// }
/// ]
/// },
/// "names": {
/// "description": "What this server is entitled to do with names: the domains its group\ncontrols, the grants it holds, whether it is paused, and the names and\ncertificates it already has. A server-wide fact, so returned to every\nsource — an agent already reporting status learns of a new domain or a\nnewly granted permission without asking separately. Identical to what\n`GET /names/entitlements` returns. Clients that predate this field can\nsafely ignore it.",
/// "$ref": "#/components/schemas/Entitlements"
/// },
/// "tags": {
/// "description": "The server's effective tags: its own tags overlaid on its group's,\nplus the synthetic read-only `canopy:` tags and effective `billing.*`\nlabels. Identical to what the standalone `GET /tags` endpoint\nreturns — see that endpoint for the full contract. Clients that\npredate this field can safely ignore it.\n\nOn a push in the current format this is the machine's, the push being\nthe machine's; each application's own are under `applications`.",
/// "$ref": "#/components/schemas/TagMap"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct StatusResponse {
/**Canopy's answer about each application the push described, keyed by the
key the reporter named it with. Present only for a push in the current
format.
A key Canopy holds no application for is absent rather than empty,
which is what a source whose pushes are ignored sees: nothing was
created for it to be told about.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub applications: ::std::option::Option<
::std::collections::HashMap<::std::string::String, TargetResponse>,
>,
/**Backup types the server should back up now: operator-requested
one-offs plus scheduled backups that are due. Each serializes as a
plain string (e.g. `"tamanu-postgres"`). The device should run each
listed type, then report via `POST /backup-report`; an empty list
means nothing to do. Only sent to `alertd` pushes (the agent that
runs backups); other sources always receive an empty list.*/
pub backup_now: ::std::vec::Vec<::std::string::String>,
/**The effective handling of every healthcheck canopy knows about, keyed
by check name (as reported in `health[].check`): `skip` (silenced for
this server, or classified below warning), `warn` (warning), or `fail`
(error or critical). Only the static severity baseline is reflected —
operator-defined conditional rules are evaluated per push and not
included. Checks absent from the map are new to canopy and default to
`warn`. Clients that predate this field can safely ignore it; the
same mapping is served on demand at `GET /status/{server_id}/check-severities`.*/
pub check_severities: ::std::collections::HashMap<
::std::string::String,
CheckSeverity,
>,
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub machine: ::std::option::Option<TargetResponse>,
/**What this server is entitled to do with names: the domains its group
controls, the grants it holds, whether it is paused, and the names and
certificates it already has. A server-wide fact, so returned to every
source — an agent already reporting status learns of a new domain or a
newly granted permission without asking separately. Identical to what
`GET /names/entitlements` returns. Clients that predate this field can
safely ignore it.*/
pub names: Entitlements,
/**The server's effective tags: its own tags overlaid on its group's,
plus the synthetic read-only `canopy:` tags and effective `billing.*`
labels. Identical to what the standalone `GET /tags` endpoint
returns — see that endpoint for the full contract. Clients that
predate this field can safely ignore it.
On a push in the current format this is the machine's, the push being
the machine's; each application's own are under `applications`.*/
pub tags: TagMap,
}
///Free-form key/value tags, as a JSON object whose values are all strings.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Free-form key/value tags, as a JSON object whose values are all strings.",
/// "type": "object",
/// "additionalProperties": {
/// "type": "string"
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(transparent)]
pub struct TagMap(
pub ::std::collections::HashMap<::std::string::String, ::std::string::String>,
);
impl ::std::ops::Deref for TagMap {
type Target = ::std::collections::HashMap<
::std::string::String,
::std::string::String,
>;
fn deref(
&self,
) -> &::std::collections::HashMap<::std::string::String, ::std::string::String> {
&self.0
}
}
impl ::std::convert::From<TagMap>
for ::std::collections::HashMap<::std::string::String, ::std::string::String> {
fn from(value: TagMap) -> Self {
value.0
}
}
impl ::std::convert::From<
::std::collections::HashMap<::std::string::String, ::std::string::String>,
> for TagMap {
fn from(
value: ::std::collections::HashMap<::std::string::String, ::std::string::String>,
) -> Self {
Self(value)
}
}
/**One target's material within a push: its health checks and its detail.
A machine and an application are described the same way, so the two grains
read alike and a reporter builds one shape for both.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "One target's material within a push: its health checks and its detail.\n\nA machine and an application are described the same way, so the two grains\nread alike and a reporter builds one shape for both.",
/// "type": "object",
/// "required": [
/// "detail"
/// ],
/// "properties": {
/// "detail": {
/// "description": "Everything the reporter has to say about this target beyond its checks.\nRecorded verbatim against the target it was attached to.",
/// "type": "object"
/// },
/// "health": {
/// "description": "This target's checks. Absent and empty mean the same thing — the source\ncurrently has no checks for this target — which recovers every check it\npreviously reported for it.",
/// "type": [
/// "array",
/// "null"
/// ],
/// "items": {
/// "$ref": "#/components/schemas/HealthCheck"
/// }
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct TargetReport {
/**Everything the reporter has to say about this target beyond its checks.
Recorded verbatim against the target it was attached to.*/
pub detail: ::serde_json::Map<::std::string::String, ::serde_json::Value>,
/**This target's checks. Absent and empty mean the same thing — the source
currently has no checks for this target — which recovers every check it
previously reported for it.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub health: ::std::option::Option<::std::vec::Vec<HealthCheck>>,
}
///What Canopy answers about one target the push described.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "What Canopy answers about one target the push described.",
/// "type": "object",
/// "required": [
/// "check_severities",
/// "tags"
/// ],
/// "properties": {
/// "check_severities": {
/// "description": "How every check this reporter can file against this target is graded,\non the same terms as the top-level `check_severities`. Keyed by bare\ncheck name, so a machine check and an application check of the same\nname are each answered under the target they belong to.",
/// "type": "object",
/// "additionalProperties": {
/// "$ref": "#/components/schemas/CheckSeverity"
/// },
/// "propertyNames": {
/// "type": "string"
/// }
/// },
/// "tags": {
/// "description": "This target's effective tags, on the same terms as the top-level\n`tags`.",
/// "$ref": "#/components/schemas/TagMap"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct TargetResponse {
/**How every check this reporter can file against this target is graded,
on the same terms as the top-level `check_severities`. Keyed by bare
check name, so a machine check and an application check of the same
name are each answered under the target they belong to.*/
pub check_severities: ::std::collections::HashMap<
::std::string::String,
CheckSeverity,
>,
/**This target's effective tags, on the same terms as the top-level
`tags`.*/
pub tags: TagMap,
}
/**A URL, given as a plain string. Any trailing slash is stripped when the
value is returned.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "A URL, given as a plain string. Any trailing slash is stripped when the\nvalue is returned.",
/// "type": "string",
/// "format": "uri"
///}
/// ```
/// </details>
#[derive(
::serde::Deserialize,
::serde::Serialize,
Clone,
Debug,
Eq,
Hash,
Ord,
PartialEq,
PartialOrd
)]
#[serde(transparent)]
pub struct UrlField(pub ::std::string::String);
impl ::std::ops::Deref for UrlField {
type Target = ::std::string::String;
fn deref(&self) -> &::std::string::String {
&self.0
}
}
impl ::std::convert::From<UrlField> for ::std::string::String {
fn from(value: UrlField) -> Self {
value.0
}
}
impl ::std::convert::From<::std::string::String> for UrlField {
fn from(value: ::std::string::String) -> Self {
Self(value)
}
}
impl ::std::str::FromStr for UrlField {
type Err = ::std::convert::Infallible;
fn from_str(value: &str) -> ::std::result::Result<Self, Self::Err> {
Ok(Self(value.to_string()))
}
}
impl ::std::fmt::Display for UrlField {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
self.0.fmt(f)
}
}
///Report of a restore attempt and the health of the resulting replica.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Report of a restore attempt and the health of the resulting replica.",
/// "type": "object",
/// "required": [
/// "group",
/// "intent",
/// "observed_at",
/// "outcome",
/// "replica_healthy",
/// "replica_id",
/// "type"
/// ],
/// "properties": {
/// "error": {
/// "description": "Human-readable error detail, when the restore failed.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "group": {
/// "description": "The server group whose backup was restored.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "health_details": {
/// "description": "Arbitrary structured health data to record alongside the report\n(database statistics, whether indexes needed rebuilding, and so on).\nStored and displayed as-is."
/// },
/// "intent": {
/// "description": "The restore intent this attempt was performed under.",
/// "type": "string"
/// },
/// "machine_id": {
/// "description": "The machine whose backup was restored, from the worklist entry's\n`machine_id`.\n\nOptional only so a reporter built against the earlier shape, which knew\nthis as `server_id`, is still accepted; one of the two must be present.",
/// "type": [
/// "string",
/// "null"
/// ],
/// "format": "uuid"
/// },
/// "migration": {
/// "oneOf": [
/// {
/// "type": "null"
/// },
/// {
/// "description": "What the migrations did, for a report under a `migrate` intent. Omit for\nevery other intent.",
/// "$ref": "#/components/schemas/MigrationArgs"
/// }
/// ]
/// },
/// "observed_at": {
/// "description": "When the restore result was observed, as an RFC 3339 timestamp.",
/// "type": "string"
/// },
/// "outcome": {
/// "description": "Whether the restore succeeded (`success`) or failed (`failure`).",
/// "type": "string"
/// },
/// "postgres_version": {
/// "description": "Version of the PostgreSQL server the data was restored into, if\napplicable.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "redaction": {
/// "oneOf": [
/// {
/// "type": "null"
/// },
/// {
/// "description": "What the masking manifest did, for a replica that redacts. Omit for a\nreplica that doesn't.",
/// "$ref": "#/components/schemas/RedactionArgs"
/// }
/// ]
/// },
/// "replica_healthy": {
/// "description": "Whether the restored database came up healthy and passed readiness\nchecks. A replica only counts as verified when the outcome is\n`success` and this is `true`.",
/// "type": "boolean"
/// },
/// "replica_id": {
/// "description": "The declaration this report concerns, taken from the worklist entry's\n`replica_id`. Required: several replicas can share one group, machine,\ntype, and intent, so a report that named no declaration could not be\nattributed to one of them.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "run_id": {
/// "description": "This must be the run-uuid the client minted for this run.\nThe field is optional only so older clients don't break; it WILL be made\nmandatory in future.",
/// "type": [
/// "string",
/// "null"
/// ],
/// "format": "uuid"
/// },
/// "s3_received_payload_bytes": {
/// "description": "Bytes of decoded object payload received from S3 during the restore.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "s3_received_raw_bytes": {
/// "description": "Bytes of raw HTTP traffic received from S3 during the restore,\nincluding protocol overhead.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "s3_sent_payload_bytes": {
/// "description": "Bytes of decoded object payload sent to S3 during the restore.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "s3_sent_raw_bytes": {
/// "description": "Bytes of raw HTTP traffic sent to S3 during the restore, including\nprotocol and signing overhead. Omit when traffic was not measured.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "server_id": {
/// "description": "The same machine under the name this field carried when a server was a\nbox and the software on it at once.\n\nDeprecated in favour of `machine_id`. A report naming only this is\naccepted and read as the machine, since a machine that predates the\nsplit took its application's id. Naming both is an error rather than a\nsilent preference, because a reporter that disagrees with itself about\nwhat it restored has not been understood.",
/// "deprecated": true,
/// "type": [
/// "string",
/// "null"
/// ],
/// "format": "uuid"
/// },
/// "snapshot_id": {
/// "description": "Identifier of the snapshot that was restored. Omit on a failure that\nnever got as far as selecting a snapshot.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "type": {
/// "description": "The backup type that was restored (e.g. `tamanu-postgres`).",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct VerificationArgs {
///Human-readable error detail, when the restore failed.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub error: ::std::option::Option<::std::string::String>,
///The server group whose backup was restored.
pub group: ::uuid::Uuid,
/**Arbitrary structured health data to record alongside the report
(database statistics, whether indexes needed rebuilding, and so on).
Stored and displayed as-is.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub health_details: ::std::option::Option<::serde_json::Value>,
///The restore intent this attempt was performed under.
pub intent: ::std::string::String,
/**The machine whose backup was restored, from the worklist entry's
`machine_id`.
Optional only so a reporter built against the earlier shape, which knew
this as `server_id`, is still accepted; one of the two must be present.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub machine_id: ::std::option::Option<::uuid::Uuid>,
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub migration: ::std::option::Option<MigrationArgs>,
///When the restore result was observed, as an RFC 3339 timestamp.
pub observed_at: ::std::string::String,
///Whether the restore succeeded (`success`) or failed (`failure`).
pub outcome: ::std::string::String,
/**Version of the PostgreSQL server the data was restored into, if
applicable.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub postgres_version: ::std::option::Option<::std::string::String>,
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub redaction: ::std::option::Option<RedactionArgs>,
/**Whether the restored database came up healthy and passed readiness
checks. A replica only counts as verified when the outcome is
`success` and this is `true`.*/
pub replica_healthy: bool,
/**The declaration this report concerns, taken from the worklist entry's
`replica_id`. Required: several replicas can share one group, machine,
type, and intent, so a report that named no declaration could not be
attributed to one of them.*/
pub replica_id: ::uuid::Uuid,
/**This must be the run-uuid the client minted for this run.
The field is optional only so older clients don't break; it WILL be made
mandatory in future.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub run_id: ::std::option::Option<::uuid::Uuid>,
///Bytes of decoded object payload received from S3 during the restore.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub s3_received_payload_bytes: ::std::option::Option<i64>,
/**Bytes of raw HTTP traffic received from S3 during the restore,
including protocol overhead.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub s3_received_raw_bytes: ::std::option::Option<i64>,
///Bytes of decoded object payload sent to S3 during the restore.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub s3_sent_payload_bytes: ::std::option::Option<i64>,
/**Bytes of raw HTTP traffic sent to S3 during the restore, including
protocol and signing overhead. Omit when traffic was not measured.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub s3_sent_raw_bytes: ::std::option::Option<i64>,
/**The same machine under the name this field carried when a server was a
box and the software on it at once.
Deprecated in favour of `machine_id`. A report naming only this is
accepted and read as the machine, since a machine that predates the
split took its application's id. Naming both is an error rather than a
silent preference, because a reporter that disagrees with itself about
what it restored has not been understood.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub server_id: ::std::option::Option<::uuid::Uuid>,
/**Identifier of the snapshot that was restored. Omit on a failure that
never got as far as selecting a snapshot.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub snapshot_id: ::std::option::Option<::std::string::String>,
///The backup type that was restored (e.g. `tamanu-postgres`).
#[serde(rename = "type")]
pub type_: ::std::string::String,
}
/**A release version of the monitored software, with its publication
status and changelog.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "A release version of the monitored software, with its publication\nstatus and changelog.",
/// "type": "object",
/// "required": [
/// "changelog",
/// "created_at",
/// "id",
/// "major",
/// "minor",
/// "patch",
/// "status",
/// "updated_at"
/// ],
/// "properties": {
/// "changelog": {
/// "description": "Changelog text for this version, as Markdown.",
/// "type": "string"
/// },
/// "created_at": {
/// "description": "When the version record was created.",
/// "$ref": "#/definitions/CanopyTimestamp"
/// },
/// "device_id": {
/// "description": "The releaser device that published this version, if it was published\nby a device rather than created by an operator.",
/// "type": [
/// "string",
/// "null"
/// ],
/// "format": "uuid"
/// },
/// "id": {
/// "description": "Unique identifier of the version.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "major": {
/// "description": "Major version number.",
/// "type": "integer",
/// "format": "int32"
/// },
/// "minor": {
/// "description": "Minor version number.",
/// "type": "integer",
/// "format": "int32"
/// },
/// "patch": {
/// "description": "Patch version number.",
/// "type": "integer",
/// "format": "int32"
/// },
/// "status": {
/// "description": "Publication status: `draft`, `published`, or `yanked`.",
/// "$ref": "#/components/schemas/VersionStatus"
/// },
/// "updated_at": {
/// "description": "When the version record was last changed.",
/// "$ref": "#/definitions/CanopyTimestamp"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct Version {
///Changelog text for this version, as Markdown.
pub changelog: ::std::string::String,
///When the version record was created.
pub created_at: ::jiff::Timestamp,
/**The releaser device that published this version, if it was published
by a device rather than created by an operator.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub device_id: ::std::option::Option<::uuid::Uuid>,
///Unique identifier of the version.
pub id: ::uuid::Uuid,
///Major version number.
pub major: i32,
///Minor version number.
pub minor: i32,
///Patch version number.
pub patch: i32,
///Publication status: `draft`, `published`, or `yanked`.
pub status: VersionStatus,
///When the version record was last changed.
pub updated_at: ::jiff::Timestamp,
}
///Publication status of a release version.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Publication status of a release version.",
/// "type": "string",
/// "enum": [
/// "draft",
/// "published",
/// "yanked"
/// ]
///}
/// ```
/// </details>
#[derive(
::serde::Deserialize,
::serde::Serialize,
Clone,
Copy,
Debug,
Eq,
Hash,
Ord,
PartialEq,
PartialOrd
)]
pub enum VersionStatus {
#[serde(rename = "draft")]
Draft,
#[serde(rename = "published")]
Published,
#[serde(rename = "yanked")]
Yanked,
}
impl ::std::fmt::Display for VersionStatus {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
match *self {
Self::Draft => f.write_str("draft"),
Self::Published => f.write_str("published"),
Self::Yanked => f.write_str("yanked"),
}
}
}
impl ::std::str::FromStr for VersionStatus {
type Err = self::error::ConversionError;
fn from_str(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
match value {
"draft" => Ok(Self::Draft),
"published" => Ok(Self::Published),
"yanked" => Ok(Self::Yanked),
_ => Err("invalid value".into()),
}
}
}
impl ::std::convert::TryFrom<&str> for VersionStatus {
type Error = self::error::ConversionError;
fn try_from(
value: &str,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for VersionStatus {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for VersionStatus {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
/**A release version as returned by the version-listing endpoints: the
version numbers, publication status, and changelog.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "A release version as returned by the version-listing endpoints: the\nversion numbers, publication status, and changelog.",
/// "type": "object",
/// "required": [
/// "changelog",
/// "id",
/// "major",
/// "minor",
/// "patch",
/// "status"
/// ],
/// "properties": {
/// "changelog": {
/// "description": "Changelog text for this version, as Markdown.",
/// "type": "string"
/// },
/// "id": {
/// "description": "Unique identifier of the version.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "major": {
/// "description": "Major version number.",
/// "type": "integer",
/// "format": "int32"
/// },
/// "minor": {
/// "description": "Minor version number.",
/// "type": "integer",
/// "format": "int32"
/// },
/// "patch": {
/// "description": "Patch version number.",
/// "type": "integer",
/// "format": "int32"
/// },
/// "status": {
/// "description": "Publication status: `draft`, `published`, or `yanked`.",
/// "$ref": "#/components/schemas/VersionStatus"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct ViewVersion {
///Changelog text for this version, as Markdown.
pub changelog: ::std::string::String,
///Unique identifier of the version.
pub id: ::uuid::Uuid,
///Major version number.
pub major: i32,
///Minor version number.
pub minor: i32,
///Patch version number.
pub patch: i32,
///Publication status: `draft`, `published`, or `yanked`.
pub status: VersionStatus,
}
/**One replica the consumer device should currently maintain: an operator
declaration expanded against a single server, carrying the snapshot to
restore and the repository coordinates to find it. S3 credentials and the
repository passphrase are obtained separately via
`POST /restore-credentials`.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "One replica the consumer device should currently maintain: an operator\ndeclaration expanded against a single server, carrying the snapshot to\nrestore and the repository coordinates to find it. S3 credentials and the\nrepository passphrase are obtained separately via\n`POST /restore-credentials`.",
/// "type": "object",
/// "required": [
/// "bucket",
/// "group_id",
/// "intent",
/// "machine_id",
/// "name",
/// "params",
/// "prefix",
/// "region",
/// "replica_id",
/// "server_id",
/// "storage",
/// "type"
/// ],
/// "properties": {
/// "application_type": {
/// "description": "For a `migrate` entry, the type of application whose candidate version is\nunder test. Absent on any other entry.\n\nA snapshot is a machine's and a candidate version is an application's, so\na migration test names both: it restores the machine's data and applies\nthat application's next version's migrations to it. The workload is named\nby its type, which is what the reporter itself said it was; Canopy's own\nidentifier for an application is internal and never on the wire.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "bucket": {
/// "description": "Name of the S3 bucket holding the group's backup repository.",
/// "type": "string"
/// },
/// "group_id": {
/// "description": "The server group whose backup repository holds the snapshot.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "intent": {
/// "description": "The restore intent this entry is for; one of the intents this device\nadvertised via `POST /restore-capabilities`.",
/// "type": "string"
/// },
/// "machine_id": {
/// "description": "The machine whose backup should be restored. Echo it back in reports.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "name": {
/// "description": "Operator-assigned label for the declaration.",
/// "type": "string"
/// },
/// "overdue_after_seconds": {
/// "description": "Bound, in whole seconds, after which the replica counts as overdue;\n`null` means no bound. Interpreted per the intent's semantics: for a\nrun-once (`once`) intent, how long the latest snapshot may go without a\nhealthy verification report; for a standing replica, how stale its last\nhealthy report may be.",
/// "type": [
/// "integer",
/// "null"
/// ],
/// "format": "int64"
/// },
/// "params": {
/// "description": "Resolved parameter values for this replica: one key per parameter the\nintent advertises. Parameters the operator left unset carry the\nintent's declared default, or JSON `null` when there is none.",
/// "type": "object"
/// },
/// "prefix": {
/// "description": "Key prefix within the bucket under which the repository lives. Normally\nempty (the repository is at the bucket root).",
/// "type": "string"
/// },
/// "region": {
/// "description": "AWS region of the bucket.",
/// "type": "string"
/// },
/// "replica_id": {
/// "description": "Identifier of the declaration this entry was expanded from. Echo it\nback in `POST /restore-verification` reports.",
/// "type": "string",
/// "format": "uuid"
/// },
/// "server_id": {
/// "description": "The same machine under the name this field carried when a server was a\nbox and the software on it at once.\n\nDeprecated in favour of `machine_id`, and emitted so a consumer built\nagainst the earlier shape keeps working across the transition. Every\nmachine that predates the split took its application's id, so for those\nthe two values are equal; a machine created since has no server to be.",
/// "deprecated": true,
/// "type": "string",
/// "format": "uuid"
/// },
/// "snapshot_at": {
/// "description": "When that snapshot was reported, as an RFC 3339 timestamp; `null` if\nunknown.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "snapshot_id": {
/// "description": "Identifier of the snapshot to restore — the latest successful backup\nfor this server and type. `null` when no successful backup is known\nyet.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "storage": {
/// "description": "Kind of storage backend. Always `\"s3\"`.",
/// "type": "string"
/// },
/// "target_version": {
/// "description": "For a `migrate` intent, the version whose schema migrations to apply\nafter restoring. Obtain them from that version's published artefacts, the\nsame way a server being upgraded does. `null` for every other intent.",
/// "type": [
/// "string",
/// "null"
/// ]
/// },
/// "target_version_id": {
/// "description": "Identifier of that version. Echo it back in the migration-test report.",
/// "type": [
/// "string",
/// "null"
/// ],
/// "format": "uuid"
/// },
/// "type": {
/// "description": "The backup type to restore (e.g. `tamanu-postgres`).",
/// "type": "string"
/// }
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[derive(::bon::Builder)]
#[non_exhaustive]
pub struct WorklistEntry {
/**For a `migrate` entry, the type of application whose candidate version is
under test. Absent on any other entry.
A snapshot is a machine's and a candidate version is an application's, so
a migration test names both: it restores the machine's data and applies
that application's next version's migrations to it. The workload is named
by its type, which is what the reporter itself said it was; Canopy's own
identifier for an application is internal and never on the wire.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub application_type: ::std::option::Option<::std::string::String>,
///Name of the S3 bucket holding the group's backup repository.
pub bucket: ::std::string::String,
///The server group whose backup repository holds the snapshot.
pub group_id: ::uuid::Uuid,
/**The restore intent this entry is for; one of the intents this device
advertised via `POST /restore-capabilities`.*/
pub intent: ::std::string::String,
///The machine whose backup should be restored. Echo it back in reports.
pub machine_id: ::uuid::Uuid,
///Operator-assigned label for the declaration.
pub name: ::std::string::String,
/**Bound, in whole seconds, after which the replica counts as overdue;
`null` means no bound. Interpreted per the intent's semantics: for a
run-once (`once`) intent, how long the latest snapshot may go without a
healthy verification report; for a standing replica, how stale its last
healthy report may be.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub overdue_after_seconds: ::std::option::Option<i64>,
/**Resolved parameter values for this replica: one key per parameter the
intent advertises. Parameters the operator left unset carry the
intent's declared default, or JSON `null` when there is none.*/
pub params: ::serde_json::Map<::std::string::String, ::serde_json::Value>,
/**Key prefix within the bucket under which the repository lives. Normally
empty (the repository is at the bucket root).*/
pub prefix: ::std::string::String,
///AWS region of the bucket.
pub region: ::std::string::String,
/**Identifier of the declaration this entry was expanded from. Echo it
back in `POST /restore-verification` reports.*/
pub replica_id: ::uuid::Uuid,
/**The same machine under the name this field carried when a server was a
box and the software on it at once.
Deprecated in favour of `machine_id`, and emitted so a consumer built
against the earlier shape keeps working across the transition. Every
machine that predates the split took its application's id, so for those
the two values are equal; a machine created since has no server to be.*/
pub server_id: ::uuid::Uuid,
/**When that snapshot was reported, as an RFC 3339 timestamp; `null` if
unknown.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub snapshot_at: ::std::option::Option<::std::string::String>,
/**Identifier of the snapshot to restore — the latest successful backup
for this server and type. `null` when no successful backup is known
yet.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub snapshot_id: ::std::option::Option<::std::string::String>,
///Kind of storage backend. Always `"s3"`.
pub storage: ::std::string::String,
/**For a `migrate` intent, the version whose schema migrations to apply
after restoring. Obtain them from that version's published artefacts, the
same way a server being upgraded does. `null` for every other intent.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub target_version: ::std::option::Option<::std::string::String>,
///Identifier of that version. Echo it back in the migration-test report.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub target_version_id: ::std::option::Option<::uuid::Uuid>,
///The backup type to restore (e.g. `tamanu-postgres`).
#[serde(rename = "type")]
pub type_: ::std::string::String,
}
/// One method per operation in canopy's OpenAPI document.
impl<T: crate::CanopyTransport> crate::CanopyClient<T> {
/// List publicly-listed central applications.
///
/// The `/applications` name for [`list`], answering identically.
///
/// `GET /applications`
pub async fn applications(&self) -> crate::Result<::std::vec::Vec<PublicServer>> {
self.call_json(::http::Method::GET, "/applications", None::<&()>).await
}
/// Get the calling identity and the box it is enrolled as.
///
/// The `/applications` name for [`self_identity`], answering identically.
///
/// `GET /applications/self`
pub async fn applications_self(&self) -> crate::Result<SelfResponse> {
self.call_json(::http::Method::GET, "/applications/self", None::<&()>).await
}
/// Register a downloadable artifact for a version or version range.
///
/// Requires a device certificate with the releaser role (or admin). The
/// path identifies the version the artifact belongs to — either an exact
/// version (e.g. `2.10.5`) or a semver range pattern (e.g. `2.10.x`,
/// `^2.10.0`) — followed by the artifact's type and target platform. The
/// request body is the plain-text URL clients should download the
/// artifact from.
///
/// When an exact version is given and it doesn't exist yet, it is created
/// automatically as an unpublished draft so the artifact has a version to
/// attach to; publishing that version later (via the version-creation
/// endpoint) is a separate step. When a range pattern is given instead,
/// the artifact isn't tied to one version — it matches whichever
/// published version currently satisfies the range at lookup time.
///
/// Returns the created artifact record. Returns 400 if the version or
/// range syntax can't be parsed.
///
/// `POST /artifacts/{version}/{artifact_type}/{platform}`
pub async fn artifacts(&self, version: &str, artifact_type: &str, platform: &str) -> crate::Result<Artifact> {
self.call_json(::http::Method::POST, &format!("/artifacts/{}/{}/{}", version, artifact_type, platform), None::<&()>).await
}
/// Register the backup types this server can run.
///
/// Declares the set of backup types the calling device is able to execute on
/// its server. Types not seen before are added to the server's capability set,
/// starting out enabled or disabled according to the fleet-wide default for
/// that type (disabled if the type has no default configured). Types already
/// registered keep whatever enabled/disabled state an operator has set for
/// them, so re-registering on every startup is safe and expected.
///
/// Only types that are registered here (and enabled) can later be issued
/// credentials via `POST /backup-credentials`, outside of explicit
/// operator-requested runs.
///
/// Errors: 412 when the calling device is not bound to a live server; 409 when
/// the server is not in a group.
///
/// `POST /backup-capabilities`
pub async fn backup_capabilities(&self, body: &BackupCapabilitiesArgs) -> crate::Result<()> {
self.call_empty(::http::Method::POST, "/backup-capabilities", Some(body)).await
}
/// Mint short-lived S3 credentials for a backup or restore run.
///
/// Issues temporary AWS credentials scoped to the backup storage of the
/// calling server's group, in the `credential_process` output format. With
/// `purpose: backup` the credentials can upload and manage backup data but
/// cannot destroy existing backups; with `purpose: restore` they are strictly
/// read-only. They expire after at most one hour, so request a fresh set for
/// each run rather than caching them. Every issuance is recorded for audit.
///
/// The storage coordinates the credentials apply to (bucket, prefix, region)
/// come from `GET /backup-target`.
///
/// Errors: 409 when the server is not in a group, when the group's backup
/// configuration is not ready, when a `backup` type is neither an enabled
/// capability of this server nor the subject of a pending "backup now" request,
/// or when a `restore` is requested but the server's restore window is not
/// open; 412 when the device is not bound to a live server; 502 when the
/// credential issuer is unavailable or not configured.
///
/// `POST /backup-credentials`
pub async fn backup_credentials(&self, body: &BackupCredentialsArgs) -> crate::Result<CredentialProcessOutput> {
self.call_json(::http::Method::POST, "/backup-credentials", Some(body)).await
}
/// Report progress for a run that is still in flight.
///
/// Optional throughout: a run that never reports progress is recorded and
/// displayed exactly as it is today. Reporting it lets Canopy show how far a
/// long-running backup has got, at what rate, and when it last heard from the
/// device — which for a multi-hour backup is the difference between "running"
/// and "running, and moving".
///
/// **Every counter is cumulative from the start of the run**, not an interval
/// delta. Send totals-so-far each time. A dropped or repeated report then costs
/// only resolution, never the accuracy of a total, and the last report Canopy
/// received can stand in for a figure the final report omits. Omit any counter
/// you do not measure rather than sending zero.
///
/// Canopy timestamps each report on receipt, so no clock agreement is needed —
/// except for `snapshot_taken_at`, which is necessarily the device's own claim
/// about its filesystem.
///
/// Unlike `POST /backup-credentials`, this does not require the group's backup
/// configuration to be ready or the type to be an enabled capability: it
/// describes a run already under way, and refusing it would blind Canopy exactly
/// when something is misconfigured.
///
/// A refused report is never a reason to abandon a run — this is telemetry.
/// Reporting progress for a run that has already been reported complete is
/// accepted rather than refused, so a report racing the completion is not an
/// error.
///
/// Errors: 412 when the calling device is not bound to a live server; 409 when
/// the server is not in a group; 429 when reporting faster than Canopy accepts.
///
/// `POST /backup-progress`
pub async fn backup_progress(&self, body: &ProgressArgs) -> crate::Result<()> {
self.call_empty(::http::Method::POST, "/backup-progress", Some(body)).await
}
/// Report the outcome of a backup or restore run.
///
/// Records the run against the calling server and its group. Send one report
/// per run, on success and on failure alike. Reporting also clears any pending
/// operator-requested run for the same type and purpose — regardless of
/// outcome, since an operator request is for one attempt — so the server's
/// status responses stop asking for it (see the `backup_now` field of the
/// status-push response).
///
/// Errors: 409 when the server is not in a group, or when the `run_id` has
/// already been reported; 412 when the device is not bound to a live server.
///
/// `POST /backup-report`
pub async fn backup_report(&self, body: &ReportArgs) -> crate::Result<()> {
self.call_empty(::http::Method::POST, "/backup-report", Some(body)).await
}
/// Fetch the backup storage target for this server's group.
///
/// Returns the bucket, prefix, region, and repository passphrase the device
/// needs to connect to its group's backup repository. Call it on every run
/// rather than caching the result, as the target can change. S3 credentials
/// are obtained separately via `POST /backup-credentials`.
///
/// Errors: 409 when the server is not in a group or the group's backup
/// configuration is not ready; 412 when the device is not bound to a live
/// server; 502 when the passphrase store is unavailable or not configured.
///
/// `GET /backup-target`
pub async fn backup_target(&self) -> crate::Result<BackupTarget> {
self.call_json(::http::Method::GET, "/backup-target", None::<&()>).await
}
/// List all current bestool SQL snippets.
///
/// Returns the library of named SQL snippets that devices running bestool
/// fetch and run, keyed by snippet name. Only the current version of each
/// snippet is included: if a snippet has been superseded by a newer one
/// under the same name, only the newer version is returned, and
/// soft-deleted snippets are omitted entirely. This endpoint does not
/// require device authentication.
///
/// `GET /bestool/snippets`
pub async fn bestool_snippets(&self) -> crate::Result<::std::collections::HashMap<::std::string::String, SnippetResponse>> {
self.call_json(::http::Method::GET, "/bestool/snippets", None::<&()>).await
}
/// Ask for a certificate, and collect it once there is one.
///
/// The same call does both, and is safe to repeat: a name and key Canopy already
/// holds a certificate for is answered from what it holds rather than ordering
/// again, so a server that lost its local copy costs the authority nothing. A
/// request naming a different key opens a new order.
///
/// Proving control of a name through DNS takes far longer than any client waits
/// mid-handshake, so a first request records the order and answers `pending`;
/// call again to collect. A server is expected to hold a certificate before it
/// needs one rather than to obtain one while a client waits.
///
/// `POST /certificates/request`
pub async fn certificates_request(&self, body: &RequestCertificateArgs) -> crate::Result<CertificateResponse> {
self.call_json(::http::Method::POST, "/certificates/request", Some(body)).await
}
/// Report the calling machine's own identity.
///
/// Resolves the caller from its certificate and returns the box it is enrolled
/// as, together with the applications Canopy holds for that box. A machine
/// authenticates entirely from its certificate, so it never needs these ids to
/// make calls; this endpoint lets one that has lost track of them recover them.
///
/// An identity belongs to at most one machine, so the answer is never
/// ambiguous — unlike `GET /servers/self`, which asks which *application* the
/// caller is and cannot answer for a box running more than one.
///
/// - **401**: no client certificate, or one that matches no known identity.
/// - **412**: the identity is registered but is not enrolled as a machine.
///
/// `GET /machines/self`
pub async fn machines_self(&self) -> crate::Result<MachineSelfResponse> {
self.call_json(::http::Method::GET, "/machines/self", None::<&()>).await
}
/// What this server may act on, and what it already holds.
///
/// Answers the boundary rather than making an agent discover it by being
/// refused: the domains its group controls, the grants it holds, whether it is
/// paused, and the names and certificates it already has. Enough to request a
/// certificate before anything asks for one, and to renew before expiry.
///
/// A server with no grants, or whose group controls no domain, gets an empty
/// answer rather than an error — asking what one may do is not a privileged act.
/// The same content rides on the response to a status push.
///
/// `GET /names/entitlements`
pub async fn names_entitlements(&self) -> crate::Result<Entitlements> {
self.call_json(::http::Method::GET, "/names/entitlements", None::<&()>).await
}
/// Register the addresses a name should resolve to.
///
/// Replaces whatever addresses were registered for the name; an empty list
/// withdraws it. Canopy publishes what it is told — it does not verify that an
/// address is really this server's, the grant being the trust boundary.
///
/// Publishing happens in the background, so the response says what Canopy will
/// publish and what it has published so far rather than waiting for the zone.
///
/// `POST /names/register`
pub async fn names_register(&self, body: &RegisterNameArgs) -> crate::Result<RegisteredName> {
self.call_json(::http::Method::POST, "/names/register", Some(body)).await
}
/// Register the restore intents this device can satisfy.
///
/// Declares the restore intents the calling device supports, replacing any
/// previously advertised set. Only worklist entries whose intent is currently
/// advertised are dispatched to this device via `GET /restore-worklist`, so
/// register on startup and whenever the supported set changes.
///
/// `POST /restore-capabilities`
pub async fn restore_capabilities(&self, body: &RestoreCapabilitiesArgs) -> crate::Result<()> {
self.call_empty(::http::Method::POST, "/restore-capabilities", Some(body)).await
}
/// Mint read-only credentials for a group's backup repository.
///
/// Issues temporary AWS credentials — always strictly read-only, scoped to the
/// group's backup storage — together with the repository passphrase, so the
/// device can read the snapshot named in a worklist entry. Credentials expire
/// after at most one hour; request a fresh set per restore rather than caching
/// them. Every issuance is recorded for audit.
///
/// The device must hold an enabled restore declaration covering the requested
/// group and type (i.e. the pair must appear in its worklist configuration);
/// otherwise the request is rejected with 403.
///
/// Errors: 403 when no enabled declaration authorizes this group and type;
/// 409 when the group has no ready backup configuration; 502 when the
/// credential issuer or the passphrase store is unavailable or not configured.
///
/// `POST /restore-credentials`
pub async fn restore_credentials(&self, body: &RestoreCredentialsArgs) -> crate::Result<RestoreCredentials> {
self.call_json(::http::Method::POST, "/restore-credentials", Some(body)).await
}
/// Report the outcome of a restore attempt and the replica's health.
///
/// Records a verification report for a restore the device performed from its
/// worklist. Send one report per attempt, on success and on failure alike. A
/// report with a `success` outcome and `replica_healthy: true` marks the
/// snapshot as verified; for run-once intents this is what removes the entry
/// from `GET /restore-worklist` until a newer snapshot appears.
///
/// Authorization matches `POST /restore-credentials`: the device must hold an
/// enabled restore declaration covering the reported group and type,
/// otherwise the request is rejected with 403.
///
/// The report names the declaration it is about, and that declaration must
/// still exist and belong to the calling consumer. A replica nothing declares
/// any more is not one Canopy tracks, so a report naming a retired declaration
/// is refused rather than recorded against a replica that could never recover.
///
/// `POST /restore-verification`
pub async fn restore_verification(&self, body: &VerificationArgs) -> crate::Result<()> {
self.call_empty(::http::Method::POST, "/restore-verification", Some(body)).await
}
/// Fetch the full set of replicas this device should maintain.
///
/// Returns the device's complete desired state, computed fresh on every call:
/// each enabled restore declaration whose intent this device currently
/// advertises, expanded into one entry per server it covers. A group-wide
/// declaration expands to every live server in its group; a server-scoped
/// declaration yields a single entry and takes precedence over a group-wide
/// one covering the same server, type, and intent. Entries for groups whose
/// backup configuration is not ready are omitted, and entries for run-once
/// intents disappear once the latest snapshot has a healthy verification
/// report, reappearing when a newer snapshot exists.
///
/// An empty array means there is nothing to do. Poll this endpoint and
/// reconcile: create or refresh the replicas listed, and tear down any the
/// device is maintaining that no longer appear.
///
/// `GET /restore-worklist`
pub async fn restore_worklist(&self) -> crate::Result<::std::vec::Vec<WorklistEntry>> {
self.call_json(::http::Method::GET, "/restore-worklist", None::<&()>).await
}
/// List publicly-listed central applications.
///
/// Returns every central server that has both a public display name and a
/// reachable host configured, ordered by environment tier (production
/// first, then clone, demo, test, dev) and then by name. Used by clients
/// to let a user pick which server to connect to.
///
/// `GET /servers`
pub async fn servers(&self) -> crate::Result<::std::vec::Vec<PublicServer>> {
self.call_json(::http::Method::GET, "/servers", None::<&()>).await
}
/// Start device enrollment against a machine.
///
/// Validates the enrollment token against the given machine and, if valid,
/// issues a short-lived (5 minute) signed challenge bound to the machine
/// ID, the token, and the caller's public key. The device must sign this
/// challenge and submit it to the completion endpoint to finish
/// enrollment; the token itself is validated here but not yet consumed.
///
/// This endpoint is rate-limited per source IP and per target machine; a
/// tripped limit returns 429. Any other failure — an unknown or archived
/// machine, or an invalid or expired token — is surfaced as a generic 403,
/// deliberately not distinguishing which check failed.
///
/// `POST /servers/register/begin`
pub async fn servers_register_begin(&self, body: &BeginArgs) -> crate::Result<BeginResponse> {
self.call_json(::http::Method::POST, "/servers/register/begin", Some(body)).await
}
/// Complete device enrollment by presenting a signed challenge.
///
/// Verifies the signature over the challenge transcript using the public
/// key supplied here, then binds the device to the machine: an existing
/// device re-enrolling with the same key is reused as-is; a device
/// re-enrolling with a different key replaces the machine's previous
/// device (revoking that device's access); otherwise a new device
/// identity is created. On success the device is granted the machine
/// role, the enrollment token is consumed, and the machine is marked as
/// registered.
///
/// Enrollment is refused if the presented public key is already bound to
/// a different live machine. Like the start-enrollment endpoint, this one
/// is rate-limited per source IP and per target machine (429 on a tripped
/// limit) and reports every other kind of failure as a generic 403.
///
/// `POST /servers/register/complete`
pub async fn servers_register_complete(&self, body: &CompleteArgs) -> crate::Result<CompleteResponse> {
self.call_json(::http::Method::POST, "/servers/register/complete", Some(body)).await
}
/// Report the calling device's own identity.
///
/// Deprecated in favour of `GET /machines/self`, which says what runs on the box
/// as well as which box it is.
///
/// Resolves the caller from its device certificate and returns the box it is
/// enrolled as together with its own device ID — the same pair returned when the
/// device completed enrollment. A device authenticates entirely from its
/// certificate, so it never needs these IDs to make calls; this endpoint lets
/// one that has lost track of them recover them.
///
/// The id answered is the box's, not any workload's: an identity belongs to a
/// box, so the answer stays the same however many applications run on it.
///
/// - **401**: the request has no client certificate, or the certificate
/// doesn't match a known device.
/// - **409**: retained for callers that handle it; no longer raised, since an
/// identity is enrolled as at most one box.
/// - **412**: the device is registered but has not yet been attached to a
/// box.
///
/// `GET /servers/self`
pub async fn servers_self(&self) -> crate::Result<SelfResponse> {
self.call_json(::http::Method::GET, "/servers/self", None::<&()>).await
}
/// Submit a status heartbeat for a machine.
///
/// `server_id` in the path is the id the agent was enrolled with, which
/// identifies the machine it runs on. Canopy works out which application on
/// that machine the push describes from the push itself.
///
/// Records a periodic status push against that machine: overall
/// self-reported health, a per-check breakdown, and any free-form extra
/// data. Machine-subject checks and detail file against the machine and the
/// rest against its application. Each failed or warning check opens (or keeps
/// open) an issue at that check's operator-configured severity, and each
/// passed check closes any issue it previously opened; the application's
/// tracked software version is also updated from the payload.
///
/// The calling device must be the one enrolled for this exact machine (or
/// hold the admin role). The response carries only return-path
/// instructions: a `backup_now` list of backup types the server should
/// back up immediately — devices should treat a non-empty list as a
/// prompt to run those backups and report them afterwards — a
/// `check_severities` map describing how canopy classifies each known
/// healthcheck for this server (`skip`/`warn`/`fail`), and the server's
/// effective `tags` (as served by `GET /tags`). The stored status record
/// is not echoed back.
///
/// `POST /status/{server_id}`
pub async fn status(&self, server_id: &str, body: &StatusPayload) -> crate::Result<StatusResponse> {
self.call_json(::http::Method::POST, &format!("/status/{}", server_id), Some(body)).await
}
/// Fetch the effective healthcheck severity mapping for a server.
///
/// Returns, for every healthcheck the `alertd` source reports, how that
/// check is handled for this server: `skip` (the check is silenced for
/// this server — at server or group scope — or its policy ceiling means it
/// never alerts), `warn` (graded at most a warning), or `fail` (failures
/// count as failures). Keys are check names as reported in
/// `health[].check` on status pushes. Only the static policy ceiling is
/// reflected; operator-defined conditional rules are evaluated per push
/// and not included here. The same mapping also rides along every
/// status-push response as `check_severities`, scoped to the pushing
/// source.
///
/// `server_id` in the path is the id the agent was enrolled with, which
/// identifies the machine it runs on.
///
/// The calling device must be the one enrolled for this exact machine (or
/// hold the admin role).
///
/// `GET /status/{server_id}/check-severities`
pub async fn status_check_severities(&self, server_id: &str) -> crate::Result<::std::collections::HashMap<::std::string::String, CheckSeverity>> {
self.call_json(::http::Method::GET, &format!("/status/{}/check-severities", server_id), None::<&()>).await
}
/// Get the tags for the calling device's own server.
///
/// Returns the effective set of tags for the server the calling device is
/// registered as: any tags set on the server itself, overlaid onto any tags
/// inherited from its server group (a tag set on the server takes precedence
/// over a group tag with the same key). If the server isn't in a group,
/// this returns just its own tags.
///
/// The result also includes a few read-only, synthetic tags describing the
/// server, under the reserved `canopy:` key prefix: `canopy:kind`,
/// `canopy:rank` (if the server has one set), and `canopy:group-id` /
/// `canopy:group-name` (if the server belongs to a group). Operators cannot
/// set tags under that prefix, so these never collide with tags you set
/// yourself.
///
/// When the server belongs to a group, the effective `billing.*` labels are
/// also included, matching the labels canopy attributes to cloud resources:
/// `billing.product`, `billing.deployment`, and `billing.stage` (the last
/// derived from *this* server's own rank, and omitted when the server has no
/// rank). The stage is per-server, not the group's highest rank, so a `clone`
/// server reports `billing.stage=clone` rather than the group's `prod`.
///
/// These are only defaults: a stored `billing.*` tag is honoured over the
/// computed value — the server's own tag first, then the group's. So an
/// operator can pin any billing label on a specific server or the whole group.
///
/// - **401**: the request has no client certificate, or the certificate
/// doesn't match a known device.
/// - **409**: the calling device is attached to more than one server, which
/// should not normally happen; contact support if you see this.
/// - **412**: the device is registered but has not yet been attached to a
/// server.
///
/// `GET /tags`
pub async fn tags(&self) -> crate::Result<TagMap> {
self.call_json(::http::Method::GET, "/tags", None::<&()>).await
}
/// List published, ready-to-serve versions.
///
/// Returns every version currently in the published state, excluding any
/// version a recorded known-issue range still covers (whether that issue
/// is still open or has since been fixed in a later patch). Ordered
/// newest first.
///
/// `GET /versions`
pub async fn get_versions(&self) -> crate::Result<::std::vec::Vec<Version>> {
self.call_json(::http::Method::GET, "/versions", None::<&()>).await
}
/// Check for available updates from a given version.
///
/// The path parameter is the caller's currently-installed exact version.
/// For each later minor release line within the same major version,
/// returns the latest published version that hasn't been excluded by a
/// recorded known-issue range — falling back to an older ready patch
/// within that same minor line rather than dropping the line entirely, if
/// the newest patch isn't ready. Clients use this to discover and offer
/// available updates.
///
/// `GET /versions/update-for/{version}`
pub async fn versions_update_for(&self, version: &str) -> crate::Result<::std::vec::Vec<ViewVersion>> {
self.call_json(::http::Method::GET, &format!("/versions/update-for/{}", version), None::<&()>).await
}
/// Yank a version.
///
/// Requires a device certificate with the admin role. Marks the given
/// exact version as yanked, hiding it from listings, update checks, and
/// artifact lookups without deleting its history.
///
/// `DELETE /versions/{version}`
pub async fn delete_versions(&self, version: &str) -> crate::Result<()> {
self.call_empty(::http::Method::DELETE, &format!("/versions/{}", version), None::<&()>).await
}
/// Publish a version with its changelog.
///
/// Requires a device certificate with the releaser role (or admin). The
/// path parameter is the exact version being published (e.g. `2.10.5`);
/// the request body is the changelog for that version, as up to 1 MiB of
/// markdown text.
///
/// If the version already exists in the draft state — for example
/// because an artifact was registered against it before its changelog
/// was written — the draft is published in place, with this changelog
/// replacing whatever it had before. Otherwise a new version is created
/// directly in the published state. Publishing a version that already
/// exists and is not a draft (already published, or yanked) fails.
///
/// Returns the resulting version record.
///
/// `POST /versions/{version}`
pub async fn post_versions(&self, version: &str) -> crate::Result<Version> {
self.call_json(::http::Method::POST, &format!("/versions/{}", version), None::<&()>).await
}
/// List the artifacts available for a version or version range.
///
/// The path parameter accepts either an exact version or a semver range
/// pattern (e.g. `2.10.x`, `^2.10.0`). It resolves to the latest
/// published, ready version satisfying the input, then returns that
/// version's artifacts — both ones registered against the exact version
/// and ones registered against a range pattern that covers it. Returns
/// 404 if no published, ready version matches.
///
/// `GET /versions/{version}/artifacts`
pub async fn versions_artifacts(&self, version: &str) -> crate::Result<::std::vec::Vec<Artifact>> {
self.call_json(::http::Method::GET, &format!("/versions/{}/artifacts", version), None::<&()>).await
}
}