service.go

// Code generated by goa v3.23.4, DO NOT EDIT.
//
// control-plane service
//
// Command:
// $ goa gen github.com/pgEdge/control-plane/api/apiv1/design -o apiv1

package controlplane

import (
	"context"

	goa "goa.design/goa/v3/pkg"
)

// Service is the control-plane service interface.
type Service interface {
	// Initializes a new cluster.
	InitCluster(context.Context, *InitClusterRequest) (res *ClusterJoinToken, err error)
	// Joins this host to an existing cluster.
	JoinCluster(context.Context, *ClusterJoinToken) (err error)
	// Gets the join token for this cluster.
	GetJoinToken(context.Context) (res *ClusterJoinToken, err error)
	// Internal endpoint for other cluster members seeking to join this cluster.
	GetJoinOptions(context.Context, *ClusterJoinRequest) (res *ClusterJoinOptions, err error)
	// Returns information about the cluster.
	GetCluster(context.Context) (res *Cluster, err error)
	// Lists all hosts within the cluster.
	ListHosts(context.Context) (res *ListHostsResponse, err error)
	// Returns information about a particular host in the cluster.
	GetHost(context.Context, *GetHostPayload) (res *Host, err error)
	// Removes a host from the cluster.
	RemoveHost(context.Context, *RemoveHostPayload) (res *RemoveHostResponse, err error)
	// Lists all databases in the cluster.
	ListDatabases(context.Context) (res *ListDatabasesResponse, err error)
	// Creates a new database in the cluster.
	CreateDatabase(context.Context, *CreateDatabaseRequest) (res *CreateDatabaseResponse, err error)
	// Returns information about a particular database in the cluster.
	GetDatabase(context.Context, *GetDatabasePayload) (res *Database, err error)
	// Updates a database with the given specification.
	UpdateDatabase(context.Context, *UpdateDatabasePayload) (res *UpdateDatabaseResponse, err error)
	// Deletes a database from the cluster.
	DeleteDatabase(context.Context, *DeleteDatabasePayload) (res *DeleteDatabaseResponse, err error)
	// Initiates a backup for a database node.
	BackupDatabaseNode(context.Context, *BackupDatabaseNodePayload) (res *BackupDatabaseNodeResponse, err error)
	// Performs a planned switchover for a node's primary to a replica candidate.
	SwitchoverDatabaseNode(context.Context, *SwitchoverDatabaseNodePayload) (res *SwitchoverDatabaseNodeResponse, err error)
	// Performs a failover for a node to a replica candidate.
	FailoverDatabaseNode(context.Context, *FailoverDatabaseNodeRequest) (res *FailoverDatabaseNodeResponse, err error)
	// Lists all tasks for a database.
	ListDatabaseTasks(context.Context, *ListDatabaseTasksPayload) (res *ListDatabaseTasksResponse, err error)
	// Returns information about a particular task.
	GetDatabaseTask(context.Context, *GetDatabaseTaskPayload) (res *Task, err error)
	// Returns the log of a particular task for a database.
	GetDatabaseTaskLog(context.Context, *GetDatabaseTaskLogPayload) (res *TaskLog, err error)
	// Lists all tasks for a host.
	ListHostTasks(context.Context, *ListHostTasksPayload) (res *ListHostTasksResponse, err error)
	// Returns information about a particular task for a host.
	GetHostTask(context.Context, *GetHostTaskPayload) (res *Task, err error)
	// Returns the log of a particular task for a host.
	GetHostTaskLog(context.Context, *GetHostTaskLogPayload) (res *TaskLog, err error)
	// Lists tasks across all scopes with optional filtering by scope and entity ID.
	ListTasks(context.Context, *ListTasksPayload) (res *ListTasksResponse, err error)
	// Perform an in-place restore of one or more nodes using the given restore
	// configuration.
	RestoreDatabase(context.Context, *RestoreDatabasePayload) (res *RestoreDatabaseResponse, err error)
	// Returns version information for this Control Plane server.
	GetVersion(context.Context) (res *VersionInfo, err error)
	// Restarts a specific instance within a database. Supports immediate or
	// scheduled restarts.
	RestartInstance(context.Context, *RestartInstancePayload) (res *RestartInstanceResponse, err error)
	// Stops a specific instance within a database. Supports immediate stops.
	StopInstance(context.Context, *StopInstancePayload) (res *StopInstanceResponse, err error)
	// Starts a specific instance within a database. Supports immediate starts
	StartInstance(context.Context, *StartInstancePayload) (res *StartInstanceResponse, err error)
	// Cancels a running or pending task for a database.
	CancelDatabaseTask(context.Context, *CancelDatabaseTaskPayload) (res *Task, err error)
}

// APIName is the name of the API as defined in the design.
const APIName = "control-plane"

// APIVersion is the version of the API as defined in the design.
const APIVersion = "v0.7.0"

// ServiceName is the name of the service as defined in the design. This is the
// same value that is set in the endpoint request contexts under the ServiceKey
// key.
const ServiceName = "control-plane"

// MethodNames lists the service method names as defined in the design. These
// are the same values that are set in the endpoint request contexts under the
// MethodKey key.
var MethodNames = [29]string{"init-cluster", "join-cluster", "get-join-token", "get-join-options", "get-cluster", "list-hosts", "get-host", "remove-host", "list-databases", "create-database", "get-database", "update-database", "delete-database", "backup-database-node", "switchover-database-node", "failover-database-node", "list-database-tasks", "get-database-task", "get-database-task-log", "list-host-tasks", "get-host-task", "get-host-task-log", "list-tasks", "restore-database", "get-version", "restart-instance", "stop-instance", "start-instance", "cancel-database-task"}

// A Control Plane API error.
type APIError struct {
	// The name of the error.
	Name string `json:"name"`
	// The error message.
	Message string `json:"message"`
}

type BackupConfigSpec struct {
	// The repositories for this backup configuration.
	Repositories []*BackupRepositorySpec `json:"repositories"`
	// The schedules for this backup configuration.
	Schedules []*BackupScheduleSpec `json:"schedules,omitempty"`
}

// BackupDatabaseNodePayload is the payload type of the control-plane service
// backup-database-node method.
type BackupDatabaseNodePayload struct {
	// ID of the database to back up.
	DatabaseID Identifier
	// Name of the node to back up.
	NodeName string
	Options  *BackupOptions
	// Forcibly attempt backup even in unmodifiable state
	Force bool
}

// BackupDatabaseNodeResponse is the result type of the control-plane service
// backup-database-node method.
type BackupDatabaseNodeResponse struct {
	// The task that will backup this database node.
	Task *Task `json:"task"`
}

type BackupOptions struct {
	// The type of backup.
	Type string `json:"type"`
	// Annotations for the backup.
	Annotations map[string]string `json:"annotations,omitempty"`
	// Options for the backup.
	BackupOptions map[string]string `json:"backup_options,omitempty"`
}

type BackupRepositorySpec struct {
	// The unique identifier of this repository.
	ID *Identifier `json:"id,omitempty"`
	// The type of this repository.
	Type string `json:"type"`
	// The S3 bucket name for this repository. Only applies when type = 's3'.
	S3Bucket *string `json:"s3_bucket,omitempty"`
	// The region of the S3 bucket for this repository. Only applies when type =
	// 's3'.
	S3Region *string `json:"s3_region,omitempty"`
	// The optional S3 endpoint for this repository. Only applies when type = 's3'.
	S3Endpoint *string `json:"s3_endpoint,omitempty"`
	// An optional AWS access key ID to use for this repository. If not provided,
	// pgbackrest will use the default credential provider chain. This field will
	// be excluded from the response of all endpoints. It can also be omitted from
	// update requests to keep the current value.
	S3Key *string `json:"s3_key,omitempty"`
	// The corresponding secret for the AWS access key ID in s3_key. This field
	// will be excluded from the response of all endpoints. It can also be omitted
	// from update requests to keep the current value.
	S3KeySecret *string `json:"s3_key_secret,omitempty"`
	// The GCS bucket name for this repository. Only applies when type = 'gcs'.
	GcsBucket *string `json:"gcs_bucket,omitempty"`
	// The optional GCS endpoint for this repository. Only applies when type =
	// 'gcs'.
	GcsEndpoint *string `json:"gcs_endpoint,omitempty"`
	// Optional base64-encoded private key data. If omitted, pgbackrest will use
	// the service account attached to the instance profile. This field will be
	// excluded from the response of all endpoints. It can also be omitted from
	// update requests to keep the current value.
	GcsKey *string `json:"gcs_key,omitempty"`
	// The Azure account name for this repository. Only applies when type = 'azure'.
	AzureAccount *string `json:"azure_account,omitempty"`
	// The Azure container name for this repository. Only applies when type =
	// 'azure'.
	AzureContainer *string `json:"azure_container,omitempty"`
	// The optional Azure endpoint for this repository. Only applies when type =
	// 'azure'.
	AzureEndpoint *string `json:"azure_endpoint,omitempty"`
	// The Azure storage account access key to use for this repository. This field
	// will be excluded from the response of all endpoints. It can also be omitted
	// from update requests to keep the current value.
	AzureKey *string `json:"azure_key,omitempty"`
	// The count of full backups to retain or the time to retain full backups.
	RetentionFull *int `json:"retention_full,omitempty"`
	// The type of measure used for retention_full.
	RetentionFullType *string `json:"retention_full_type,omitempty"`
	// The base path within the repository to store backups. Required for type =
	// 'posix' and 'cifs'.
	BasePath *string `json:"base_path,omitempty"`
	// Additional options to apply to this repository.
	CustomOptions map[string]string `json:"custom_options,omitempty"`
}

type BackupScheduleSpec struct {
	// The unique identifier for this backup schedule.
	ID string `json:"id"`
	// The type of backup to take on this schedule.
	Type string `json:"type"`
	// The cron expression for this schedule.
	CronExpression string `json:"cron_expression"`
}

// CancelDatabaseTaskPayload is the payload type of the control-plane service
// cancel-database-task method.
type CancelDatabaseTaskPayload struct {
	// ID of the database that owns the task.
	DatabaseID Identifier
	// ID of the task to cancel.
	TaskID Identifier
}

// Cluster is the result type of the control-plane service get-cluster method.
type Cluster struct {
	// Unique identifier for the cluster.
	ID Identifier `json:"id"`
	// Current status of the cluster.
	Status *ClusterStatus `json:"status"`
	// All of the hosts in the cluster.
	Hosts []*Host `json:"hosts"`
}

type ClusterCredentials struct {
	// The Etcd username for the new host.
	Username string `json:"username"`
	// The Etcd password for the new host.
	Password string `json:"password"`
	// The base64-encoded CA certificate for the cluster.
	CaCert string `json:"ca_cert"`
	// The base64-encoded etcd client certificate for the new cluster member.
	ClientCert string `json:"client_cert"`
	// The base64-encoded etcd client key for the new cluster member.
	ClientKey string `json:"client_key"`
	// The base64-encoded etcd server certificate for the new cluster member.
	ServerCert string `json:"server_cert"`
	// The base64-encoded etcd server key for the new cluster member.
	ServerKey string `json:"server_key"`
}

// ClusterJoinOptions is the result type of the control-plane service
// get-join-options method.
type ClusterJoinOptions struct {
	// Connection information for the etcd cluster leader
	Leader *EtcdClusterMember `json:"leader"`
	// Credentials for the new host joining the cluster.
	Credentials *ClusterCredentials `json:"credentials"`
}

// ClusterJoinRequest is the payload type of the control-plane service
// get-join-options method.
type ClusterJoinRequest struct {
	// Token to join the cluster.
	Token string `json:"token"`
	// The unique identifier for the host that's joining the cluster.
	HostID Identifier `json:"host_id"`
	// The peer addresses of the host that's joining the cluster.
	Addresses []string `json:"addresses"`
	// True if the joining member is configured to run an embedded an etcd server.
	EmbeddedEtcdEnabled bool `json:"embedded_etcd_enabled"`
}

// ClusterJoinToken is the result type of the control-plane service
// init-cluster method.
type ClusterJoinToken struct {
	// Token to join an existing cluster.
	Token string `json:"token"`
	// Existing server to join
	ServerUrls []string `json:"server_urls"`
}

type ClusterStatus struct {
	// The current state of the cluster.
	State string `json:"state"`
}

type ComponentStatus struct {
	// Indicates if the component is healthy.
	Healthy bool `json:"healthy"`
	// Error message from any errors that occurred during the health check.
	Error *string `json:"error,omitempty"`
	// Additional details about the component.
	Details map[string]any `json:"details,omitempty"`
}

// CreateDatabaseRequest is the payload type of the control-plane service
// create-database method.
type CreateDatabaseRequest struct {
	// Unique identifier for the database.
	ID *Identifier `json:"id,omitempty"`
	// Unique identifier for the database's owner.
	TenantID *Identifier `json:"tenant_id,omitempty"`
	// The specification for the database.
	Spec *DatabaseSpec `json:"spec"`
}

// CreateDatabaseResponse is the result type of the control-plane service
// create-database method.
type CreateDatabaseResponse struct {
	// The task that will create this database.
	Task *Task `json:"task"`
	// The database being created.
	Database *Database `json:"database"`
}

// Database is the result type of the control-plane service get-database method.
type Database struct {
	// Unique identifier for the database.
	ID Identifier `json:"id"`
	// Unique identifier for the database's owner.
	TenantID *Identifier `json:"tenant_id,omitempty"`
	// The time that the database was created.
	CreatedAt string `json:"created_at"`
	// The time that the database was last updated.
	UpdatedAt string `json:"updated_at"`
	// Current state of the database.
	State string `json:"state"`
	// All of the instances in the database.
	Instances []*Instance `json:"instances,omitempty"`
	// Service instances running alongside this database.
	ServiceInstances []*ServiceInstance `json:"service_instances,omitempty"`
	// The user-provided specification for the database.
	Spec *DatabaseSpec `json:"spec,omitempty"`
}

// Controls how the service connects to the database. When omitted, all nodes
// are included with the local node first and target_session_attrs is derived
// from the service config.
type DatabaseConnection struct {
	// Optional ordered list of database node names. When set, the service's
	// database connection includes only the listed nodes in the specified order.
	TargetNodes []string `json:"target_nodes,omitempty"`
	// Optional libpq target_session_attrs value. When set, overrides the default
	// derived from the service config. Valid values: primary, prefer-standby,
	// standby, read-write, any.
	TargetSessionAttrs *string `json:"target_session_attrs,omitempty"`
}

type DatabaseNodeSpec struct {
	// The name of the database node.
	Name string `json:"name"`
	// The IDs of the hosts that should run this node. When multiple hosts are
	// specified, one host will chosen as a primary, and the others will be read
	// replicas.
	HostIds []Identifier `json:"host_ids"`
	// The Postgres version for this node in 'major.minor' format. Overrides the
	// Postgres version set in the DatabaseSpec.
	PostgresVersion *string `json:"postgres_version,omitempty"`
	// The port used by the Postgres database for this node. Overrides the Postgres
	// port set in the DatabaseSpec.
	Port *int `json:"port,omitempty"`
	// The port used by Patroni for this node. Overrides the Patroni port set in
	// the DatabaseSpec. NOTE: This field is not currently supported for Docker
	// Swarm.
	PatroniPort *int `json:"patroni_port,omitempty"`
	// The number of CPUs to allocate for the database on this node and to use for
	// tuning Postgres. It can include the SI suffix 'm', e.g. '500m' for 500
	// millicpus. Cannot allocate units smaller than 1m. Defaults to the number of
	// available CPUs on the host if 0 or unspecified. Cannot allocate more CPUs
	// than are available on the host. Whether this limit is enforced depends on
	// the orchestrator.
	Cpus *string `json:"cpus,omitempty"`
	// The amount of memory in SI or IEC notation to allocate for the database on
	// this node and to use for tuning Postgres. Defaults to the total available
	// memory on the host. Whether this limit is enforced depends on the
	// orchestrator.
	Memory *string `json:"memory,omitempty"`
	// Additional postgresql.conf settings for this particular node. Will be merged
	// with the settings provided by control-plane.
	PostgresqlConf map[string]any `json:"postgresql_conf,omitempty"`
	// The backup configuration for this node. Overrides the backup configuration
	// set in the DatabaseSpec.
	BackupConfig *BackupConfigSpec `json:"backup_config,omitempty"`
	// The restore configuration for this node. Overrides the restore configuration
	// set in the DatabaseSpec.
	RestoreConfig *RestoreConfigSpec `json:"restore_config,omitempty"`
	// Orchestrator-specific configuration options.
	OrchestratorOpts *OrchestratorOpts `json:"orchestrator_opts,omitempty"`
	// The name of the source node to use for sync. This is typically the node
	// (like 'n1') from which the data will be copied to initialize this new node.
	SourceNode *string `json:"source_node,omitempty"`
}

type DatabaseSpec struct {
	// The name of the Postgres database.
	DatabaseName string `json:"database_name"`
	// The Postgres version in 'major.minor' format.
	PostgresVersion *string `json:"postgres_version,omitempty"`
	// The major version of the Spock extension.
	SpockVersion *string `json:"spock_version,omitempty"`
	// The port used by the Postgres database. If the port is 0, each instance will
	// be assigned a random port. If the port is unspecified, the database will not
	// be exposed on any port, dependent on orchestrator support for that feature.
	Port *int `json:"port,omitempty"`
	// The port used by Patroni for this database. NOTE: This field is not
	// currently supported for Docker Swarm.
	PatroniPort *int `json:"patroni_port,omitempty"`
	// The number of CPUs to allocate for the database and to use for tuning
	// Postgres. Defaults to the number of available CPUs on the host. Can include
	// an SI suffix, e.g. '500m' for 500 millicpus. Whether this limit is enforced
	// depends on the orchestrator.
	Cpus *string `json:"cpus,omitempty"`
	// The amount of memory in SI or IEC notation to allocate for the database and
	// to use for tuning Postgres. Defaults to the total available memory on the
	// host. Whether this limit is enforced depends on the orchestrator.
	Memory *string `json:"memory,omitempty"`
	// The Spock nodes for this database.
	Nodes []*DatabaseNodeSpec `json:"nodes"`
	// The users to create for this database.
	DatabaseUsers []*DatabaseUserSpec `json:"database_users,omitempty"`
	// Service instances to run alongside the database (e.g., MCP servers).
	Services []*ServiceSpec `json:"services,omitempty"`
	// The backup configuration for this database.
	BackupConfig *BackupConfigSpec `json:"backup_config,omitempty"`
	// The restore configuration for this database.
	RestoreConfig *RestoreConfigSpec `json:"restore_config,omitempty"`
	// Additional postgresql.conf settings. Will be merged with the settings
	// provided by control-plane.
	PostgresqlConf map[string]any `json:"postgresql_conf,omitempty"`
	// Orchestrator-specific configuration options.
	OrchestratorOpts *OrchestratorOpts `json:"orchestrator_opts,omitempty"`
}

type DatabaseSummary struct {
	// Unique identifier for the database.
	ID Identifier `json:"id"`
	// Unique identifier for the database's owner.
	TenantID *Identifier `json:"tenant_id,omitempty"`
	// The time that the database was created.
	CreatedAt string `json:"created_at"`
	// The time that the database was last updated.
	UpdatedAt string `json:"updated_at"`
	// Current state of the database.
	State string `json:"state"`
	// All of the instances in the database.
	Instances []*Instance `json:"instances,omitempty"`
}

type DatabaseUserSpec struct {
	// The username for this database user.
	Username string `json:"username"`
	// The password for this database user. This field will be excluded from the
	// response of all endpoints. It can also be omitted from update requests to
	// keep the current value.
	Password *string `json:"password,omitempty"`
	// If true, this user will be granted database ownership.
	DbOwner *bool `json:"db_owner,omitempty"`
	// The attributes to assign to this database user.
	Attributes []string `json:"attributes,omitempty"`
	// The roles to assign to this database user.
	Roles []string `json:"roles,omitempty"`
}

// DeleteDatabasePayload is the payload type of the control-plane service
// delete-database method.
type DeleteDatabasePayload struct {
	// ID of the database to delete.
	DatabaseID Identifier
	// Force deletion of a database even in an unmodifiable state
	Force bool
}

// DeleteDatabaseResponse is the result type of the control-plane service
// delete-database method.
type DeleteDatabaseResponse struct {
	// The task that will delete this database.
	Task *Task `json:"task"`
}

type EtcdClusterMember struct {
	// The name of the Etcd cluster member.
	Name string `json:"name"`
	// The Etcd peer endpoint for this cluster member.
	PeerUrls []string `json:"peer_urls"`
	// The Etcd client endpoint for this cluster member.
	ClientUrls []string `json:"client_urls"`
}

// Describes an additional Docker network to attach the container to.
type ExtraNetworkSpec struct {
	// The name or ID of the network to connect to.
	ID string `json:"id"`
	// Optional network-scoped aliases for the container.
	Aliases []string `json:"aliases,omitempty"`
	// Optional driver options for the network connection.
	DriverOpts map[string]string `json:"driver_opts,omitempty"`
}

// Extra volumes to mount from the host to the database container.
type ExtraVolumesSpec struct {
	// The host path for the volume.
	HostPath string `json:"host_path"`
	// The path inside the container where the volume will be mounted.
	DestinationPath string `json:"destination_path"`
}

// FailoverDatabaseNodeRequest is the payload type of the control-plane service
// failover-database-node method.
type FailoverDatabaseNodeRequest struct {
	// ID of the database to perform the failover for.
	DatabaseID Identifier `json:"database_id"`
	// Name of the node to initiate the failover from.
	NodeName string `json:"node_name"`
	// Optional instance_id of the replica to promote. If omitted, a candidate will
	// be selected.
	CandidateInstanceID *string `json:"candidate_instance_id,omitempty"`
	// If true, skip the health validations that prevent running failover on a
	// healthy cluster.
	SkipValidation bool `json:"skip_validation,omitempty"`
}

// FailoverDatabaseNodeResponse is the result type of the control-plane service
// failover-database-node method.
type FailoverDatabaseNodeResponse struct {
	// The task that will perform the failover.
	Task *Task `json:"task"`
}

// GetDatabasePayload is the payload type of the control-plane service
// get-database method.
type GetDatabasePayload struct {
	// ID of the database to get.
	DatabaseID Identifier
}

// GetDatabaseTaskLogPayload is the payload type of the control-plane service
// get-database-task-log method.
type GetDatabaseTaskLogPayload struct {
	// ID of the database to get the task log for.
	DatabaseID Identifier
	// ID of the task to get the log for.
	TaskID string
	// ID of the entry to start from.
	AfterEntryID *string
	// Maximum number of entries to return.
	Limit *int
}

// GetDatabaseTaskPayload is the payload type of the control-plane service
// get-database-task method.
type GetDatabaseTaskPayload struct {
	// ID of the database the task belongs to.
	DatabaseID Identifier
	// ID of the task to get.
	TaskID string
}

// GetHostPayload is the payload type of the control-plane service get-host
// method.
type GetHostPayload struct {
	// ID of the host to get.
	HostID Identifier
}

// GetHostTaskLogPayload is the payload type of the control-plane service
// get-host-task-log method.
type GetHostTaskLogPayload struct {
	// ID of the host to get the task logs for.
	HostID Identifier
	// ID of the task to get the logs for.
	TaskID string
	// ID of the entry to start from.
	AfterEntryID *string
	// Maximum number of entries to return.
	Limit *int
}

// GetHostTaskPayload is the payload type of the control-plane service
// get-host-task method.
type GetHostTaskPayload struct {
	// ID of the host the task belongs to.
	HostID Identifier
	// ID of the task to get.
	TaskID string
}

// Health check result for a service instance.
type HealthCheckResult struct {
	// The health status.
	Status string `json:"status"`
	// Optional message about the health status.
	Message *string `json:"message,omitempty"`
	// The time this health check was performed.
	CheckedAt string `json:"checked_at"`
}

// Host is the result type of the control-plane service get-host method.
type Host struct {
	// Unique identifier for the host.
	ID Identifier `json:"id"`
	// The orchestrator used by this host.
	Orchestrator string `json:"orchestrator"`
	// The data directory for the host.
	DataDir string `json:"data_dir"`
	// The cohort that this host belongs to.
	Cohort *HostCohort `json:"cohort,omitempty"`
	// The addresses that this host advertises to other hosts.
	PeerAddresses []string `json:"peer_addresses"`
	// The addresses that this host advertises to client applications.
	ClientAddresses []string `json:"client_addresses"`
	// The number of CPUs on this host.
	Cpus *int `json:"cpus,omitempty"`
	// The amount of memory available on this host.
	Memory *string `json:"memory,omitempty"`
	// Current status of the host.
	Status *HostStatus `json:"status"`
	// The default PgEdge version for this host.
	DefaultPgedgeVersion *PgEdgeVersion `json:"default_pgedge_version,omitempty"`
	// The PgEdge versions supported by this host.
	SupportedPgedgeVersions []*PgEdgeVersion `json:"supported_pgedge_versions,omitempty"`
	// The etcd mode for this host.
	EtcdMode *string `json:"etcd_mode,omitempty"`
}

type HostCohort struct {
	// The type of cohort that the host belongs to.
	Type string `json:"type"`
	// The member ID of the host within the cohort.
	MemberID string `json:"member_id"`
	// Indicates if the host is a control node in the cohort.
	ControlAvailable bool `json:"control_available"`
}

type HostStatus struct {
	State string `json:"state"`
	// The last time the host status was updated.
	UpdatedAt string `json:"updated_at"`
	// The status of each component of the host.
	Components map[string]*ComponentStatus `json:"components"`
}

// A user-specified identifier. Must be 1-63 characters, contain only
// lower-cased letters and hyphens, start and end with a letter or number, and
// not contain consecutive hyphens.
type Identifier string

// InitClusterRequest is the payload type of the control-plane service
// init-cluster method.
type InitClusterRequest struct {
	// Optional id for the cluster, omit for default generated id
	ClusterID *Identifier `json:"cluster_id,omitempty"`
}

// An instance of pgEdge Postgres running on a host.
type Instance struct {
	// Unique identifier for the instance.
	ID string `json:"id"`
	// The ID of the host this instance is running on.
	HostID string `json:"host_id"`
	// The Spock node name for this instance.
	NodeName string `json:"node_name"`
	// The time that the instance was created.
	CreatedAt string `json:"created_at"`
	// The time that the instance was last modified.
	UpdatedAt string `json:"updated_at"`
	// The time that the instance status information was last updated.
	StatusUpdatedAt *string `json:"status_updated_at,omitempty"`
	State           string  `json:"state"`
	// Connection information for the instance.
	ConnectionInfo *InstanceConnectionInfo `json:"connection_info,omitempty"`
	// Postgres status information for the instance.
	Postgres *InstancePostgresStatus `json:"postgres,omitempty"`
	// Spock status information for the instance.
	Spock *InstanceSpockStatus `json:"spock,omitempty"`
	// An error message if the instance is in an error state.
	Error *string `json:"error,omitempty"`
}

// Connection information for a pgEdge instance.
type InstanceConnectionInfo struct {
	// The addresses of the host that's running this instance.
	Addresses []string `json:"addresses,omitempty"`
	// The host port that Postgres is listening on for this instance.
	Port *int `json:"port,omitempty"`
}

// Postgres status information for a pgEdge instance.
type InstancePostgresStatus struct {
	// The version of Postgres for this instance.
	Version      *string `json:"version,omitempty"`
	PatroniState *string `json:"patroni_state,omitempty"`
	Role         *string `json:"role,omitempty"`
	// True if this instance has a pending restart from a configuration change.
	PendingRestart *bool `json:"pending_restart,omitempty"`
	// True if Patroni is paused for this instance.
	PatroniPaused *bool `json:"patroni_paused,omitempty"`
}

// Spock status information for a pgEdge instance.
type InstanceSpockStatus struct {
	// The current spock.readonly setting.
	ReadOnly *string `json:"read_only,omitempty"`
	// The version of Spock for this instance.
	Version *string `json:"version,omitempty"`
	// Status information for this instance's Spock subscriptions.
	Subscriptions []*InstanceSubscription `json:"subscriptions,omitempty"`
}

// Status information for a Spock subscription.
type InstanceSubscription struct {
	// The Spock node name of the provider for this subscription.
	ProviderNode string `json:"provider_node"`
	// The name of the subscription.
	Name string `json:"name"`
	// The current status of the subscription.
	Status string `json:"status"`
}

// ListDatabaseTasksPayload is the payload type of the control-plane service
// list-database-tasks method.
type ListDatabaseTasksPayload struct {
	// ID of the database to list tasks for.
	DatabaseID Identifier
	// ID of the task to start from.
	AfterTaskID *string
	// Maximum number of tasks to return.
	Limit *int
	// Sort order for the tasks.
	SortOrder *string
}

// ListDatabaseTasksResponse is the result type of the control-plane service
// list-database-tasks method.
type ListDatabaseTasksResponse struct {
	// The tasks for the given database.
	Tasks []*Task `json:"tasks"`
}

// ListDatabasesResponse is the result type of the control-plane service
// list-databases method.
type ListDatabasesResponse struct {
	// The databases managed by this cluster.
	Databases []*DatabaseSummary `json:"databases"`
}

// ListHostTasksPayload is the payload type of the control-plane service
// list-host-tasks method.
type ListHostTasksPayload struct {
	// ID of the host to list tasks for.
	HostID Identifier
	// ID of the task to start from.
	AfterTaskID *string
	// Maximum number of tasks to return.
	Limit *int
	// Sort order for the tasks.
	SortOrder *string
}

// ListHostTasksResponse is the result type of the control-plane service
// list-host-tasks method.
type ListHostTasksResponse struct {
	// The tasks for the given host.
	Tasks []*Task `json:"tasks"`
}

// ListHostsResponse is the result type of the control-plane service list-hosts
// method.
type ListHostsResponse struct {
	// List of hosts in the cluster
	Hosts []*Host `json:"hosts"`
}

// ListTasksPayload is the payload type of the control-plane service list-tasks
// method.
type ListTasksPayload struct {
	// Optional scope to filter tasks (database or host).
	Scope *string
	// Optional entity ID to filter tasks. Requires scope to be set.
	EntityID *Identifier
	// ID of the task to start from.
	AfterTaskID *string
	// Maximum number of tasks to return.
	Limit *int
	// Sort order for the tasks.
	SortOrder *string
}

// ListTasksResponse is the result type of the control-plane service list-tasks
// method.
type ListTasksResponse struct {
	// The tasks for the given entity.
	Tasks []*Task `json:"tasks"`
}

// Options specific to the selected orchestrator.
type OrchestratorOpts struct {
	// Swarm-specific configuration.
	Swarm *SwarmOpts `json:"swarm,omitempty"`
}

type PgEdgeVersion struct {
	// The Postgres major and minor version.
	PostgresVersion string `json:"postgres_version"`
	// The Spock major version.
	SpockVersion string `json:"spock_version"`
}

// Port mapping information for a service instance.
type PortMapping struct {
	// The name of the port (e.g., 'http', 'web-client').
	Name string `json:"name"`
	// The port number inside the container.
	ContainerPort *int `json:"container_port,omitempty"`
	// The port number on the host (if port-forwarded).
	HostPort *int `json:"host_port,omitempty"`
}

// RemoveHostPayload is the payload type of the control-plane service
// remove-host method.
type RemoveHostPayload struct {
	// ID of the host to remove.
	HostID Identifier
	// Force removal even if instances exist or quorum would be violated. Use only
	// for disaster recovery when a host is permanently lost.
	Force bool
}

// RemoveHostResponse is the result type of the control-plane service
// remove-host method.
type RemoveHostResponse struct {
	// The task that tracks the overall host removal operation.
	Task *Task `json:"task"`
	// The tasks that will update databases affected by the host removal.
	UpdateDatabaseTasks []*Task `json:"update_database_tasks"`
}

// RestartInstancePayload is the payload type of the control-plane service
// restart-instance method.
type RestartInstancePayload struct {
	// The ID of the database that owns the instance.
	DatabaseID Identifier
	// The ID of the instance to restart.
	InstanceID Identifier
	// The time at which the restart is scheduled.
	ScheduledAt *string
}

// Returns a task representing the restart operation.
type RestartInstanceResponse struct {
	// Task representing the restart operation
	Task *Task `json:"task"`
}

type RestoreConfigSpec struct {
	// The ID of the database to restore this database from.
	SourceDatabaseID Identifier `json:"source_database_id"`
	// The name of the node to restore this database from.
	SourceNodeName string `json:"source_node_name"`
	// The name of the database in this repository. The database will be renamed to
	// the database_name in the DatabaseSpec after it's restored.
	SourceDatabaseName string `json:"source_database_name"`
	// The repository to restore this database from.
	Repository *RestoreRepositorySpec `json:"repository"`
	// Additional options to use when restoring this database. If omitted, the
	// database will be restored to the latest point in the given repository.
	RestoreOptions map[string]string `json:"restore_options,omitempty"`
}

// RestoreDatabasePayload is the payload type of the control-plane service
// restore-database method.
type RestoreDatabasePayload struct {
	// ID of the database to restore.
	DatabaseID Identifier
	Request    *RestoreDatabaseRequest
	// Force restoration of a database even in an unmodifiable state
	Force bool
}

type RestoreDatabaseRequest struct {
	// Configuration for the restore process.
	RestoreConfig *RestoreConfigSpec `json:"restore_config"`
	// The nodes to restore. Defaults to all nodes if empty or unspecified.
	TargetNodes []string `json:"target_nodes,omitempty"`
}

// RestoreDatabaseResponse is the result type of the control-plane service
// restore-database method.
type RestoreDatabaseResponse struct {
	// The task that will restore this database.
	Task *Task `json:"task"`
	// The tasks that will restore each database node.
	NodeTasks []*Task `json:"node_tasks"`
	// The database being restored.
	Database *Database `json:"database"`
}

type RestoreRepositorySpec struct {
	// The unique identifier of this repository.
	ID *Identifier `json:"id,omitempty"`
	// The type of this repository.
	Type string `json:"type"`
	// The S3 bucket name for this repository. Only applies when type = 's3'.
	S3Bucket *string `json:"s3_bucket,omitempty"`
	// The region of the S3 bucket for this repository. Only applies when type =
	// 's3'.
	S3Region *string `json:"s3_region,omitempty"`
	// The optional S3 endpoint for this repository. Only applies when type = 's3'.
	S3Endpoint *string `json:"s3_endpoint,omitempty"`
	// An optional AWS access key ID to use for this repository. If not provided,
	// pgbackrest will use the default credential provider chain.
	S3Key *string `json:"s3_key,omitempty"`
	// The corresponding secret for the AWS access key ID in s3_key.
	S3KeySecret *string `json:"s3_key_secret,omitempty"`
	// The GCS bucket name for this repository. Only applies when type = 'gcs'.
	GcsBucket *string `json:"gcs_bucket,omitempty"`
	// The optional GCS endpoint for this repository. Only applies when type =
	// 'gcs'.
	GcsEndpoint *string `json:"gcs_endpoint,omitempty"`
	// Optional base64-encoded private key data. If omitted, pgbackrest will use
	// the service account attached to the instance profile.
	GcsKey *string `json:"gcs_key,omitempty"`
	// The Azure account name for this repository. Only applies when type = 'azure'.
	AzureAccount *string `json:"azure_account,omitempty"`
	// The Azure container name for this repository. Only applies when type =
	// 'azure'.
	AzureContainer *string `json:"azure_container,omitempty"`
	// The optional Azure endpoint for this repository. Only applies when type =
	// 'azure'.
	AzureEndpoint *string `json:"azure_endpoint,omitempty"`
	// An optional Azure storage account access key to use for this repository. If
	// not provided, pgbackrest will use the VM's managed identity.
	AzureKey *string `json:"azure_key,omitempty"`
	// The base path within the repository to store backups. Required for type =
	// 'posix' and 'cifs'.
	BasePath *string `json:"base_path,omitempty"`
	// Additional options to apply to this repository.
	CustomOptions map[string]string `json:"custom_options,omitempty"`
}

// A service instance running on a host alongside the database.
type ServiceInstance struct {
	// Unique identifier for the service instance.
	ServiceInstanceID string `json:"service_instance_id"`
	// The service ID from the DatabaseSpec.
	ServiceID string `json:"service_id"`
	// The ID of the database this service belongs to.
	DatabaseID Identifier `json:"database_id"`
	// The ID of the host this service instance is running on.
	HostID string `json:"host_id"`
	// Current state of the service instance.
	State string `json:"state"`
	// Runtime status information for the service instance.
	Status *ServiceInstanceStatus `json:"status,omitempty"`
	// The time that the service instance was created.
	CreatedAt string `json:"created_at"`
	// The time that the service instance was last updated.
	UpdatedAt string `json:"updated_at"`
	// An error message if the service instance is in an error state.
	Error *string `json:"error,omitempty"`
}

// Runtime status information for a service instance.
type ServiceInstanceStatus struct {
	// The Docker container ID.
	ContainerID *string `json:"container_id,omitempty"`
	// The container image version currently running.
	ImageVersion *string `json:"image_version,omitempty"`
	// The addresses of the host that's running this service instance.
	Addresses []string `json:"addresses,omitempty"`
	// Port mappings for this service instance.
	Ports []*PortMapping `json:"ports,omitempty"`
	// Most recent health check result.
	HealthCheck *HealthCheckResult `json:"health_check,omitempty"`
	// The time of the last health check attempt.
	LastHealthAt *string `json:"last_health_at,omitempty"`
	// Whether the service is ready to accept requests.
	ServiceReady *bool `json:"service_ready,omitempty"`
}

type ServiceSpec struct {
	// The unique identifier for this service.
	ServiceID Identifier `json:"service_id"`
	// The type of service to run.
	ServiceType string `json:"service_type"`
	// The version of the service (e.g., '1.0.0', '14.5') or the literal 'latest'.
	Version string `json:"version"`
	// The IDs of the hosts that should run this service. One service instance will
	// be created per host.
	HostIds []Identifier `json:"host_ids"`
	// The port to publish the service on the host. If 0, Docker assigns a random
	// port. If unspecified, no port is published and the service is not accessible
	// from outside the Docker network.
	Port *int `json:"port,omitempty"`
	// Service-specific configuration. For MCP services, this includes
	// llm_provider, llm_model, and provider-specific API keys.
	Config map[string]any `json:"config"`
	// The number of CPUs to allocate for this service. It can include the SI
	// suffix 'm', e.g. '500m' for 500 millicpus. Defaults to container defaults if
	// unspecified.
	Cpus *string `json:"cpus,omitempty"`
	// The amount of memory in SI or IEC notation to allocate for this service.
	// Defaults to container defaults if unspecified.
	Memory *string `json:"memory,omitempty"`
	// Orchestrator-specific options for this service.
	OrchestratorOpts *OrchestratorOpts `json:"orchestrator_opts,omitempty"`
	// Optional database connection routing configuration.
	DatabaseConnection *DatabaseConnection `json:"database_connection,omitempty"`
}

// StartInstancePayload is the payload type of the control-plane service
// start-instance method.
type StartInstancePayload struct {
	// The ID of the database that owns the instance.
	DatabaseID Identifier
	// The ID of the instance to start.
	InstanceID Identifier
	// Force starting an instance even if database in an unmodifiable state
	Force bool
}

// Returns a task representing the start operation.
type StartInstanceResponse struct {
	// Task representing the start operation
	Task *Task `json:"task"`
}

// StopInstancePayload is the payload type of the control-plane service
// stop-instance method.
type StopInstancePayload struct {
	// The ID of the database that owns the instance.
	DatabaseID Identifier
	// The ID of the instance to stop.
	InstanceID Identifier
	// Force stopping an instance even if database in an unmodifiable state
	Force bool
}

// Returns a task representing the stop operation.
type StopInstanceResponse struct {
	// Task representing the stop operation
	Task *Task `json:"task"`
}

// Docker Swarm-specific options.
type SwarmOpts struct {
	// A list of extra volumes to mount. Each entry defines a host and container
	// path.
	ExtraVolumes []*ExtraVolumesSpec `json:"extra_volumes,omitempty"`
	// A list of additional Docker Swarm networks to attach containers in this
	// database to.
	ExtraNetworks []*ExtraNetworkSpec `json:"extra_networks,omitempty"`
	// Arbitrary labels to apply to the Docker Swarm service
	ExtraLabels map[string]string `json:"extra_labels,omitempty"`
}

// SwitchoverDatabaseNodePayload is the payload type of the control-plane
// service switchover-database-node method.
type SwitchoverDatabaseNodePayload struct {
	// ID of the database to operate on.
	DatabaseID Identifier
	// Name of the node to operate on.
	NodeName string
	// Optional instance_id for the replica candidate.
	CandidateInstanceID *string
	// Optional scheduled time (ISO8601) for the switchover. If absent switchover
	// happens immediately.
	ScheduledAt *string
}

// SwitchoverDatabaseNodeResponse is the result type of the control-plane
// service switchover-database-node method.
type SwitchoverDatabaseNodeResponse struct {
	// The task that will perform the switchover.
	Task *Task `json:"task"`
}

// Task is the result type of the control-plane service get-database-task
// method.
type Task struct {
	// The parent task ID of the task.
	ParentID *string `json:"parent_id,omitempty"`
	// The scope of the task (database or host).
	Scope string `json:"scope"`
	// The entity ID (database_id or host_id) that this task belongs to.
	EntityID string `json:"entity_id"`
	// The database ID of the task.
	DatabaseID *string `json:"database_id,omitempty"`
	// The name of the node that the task is operating on.
	NodeName *string `json:"node_name,omitempty"`
	// The ID of the instance that the task is operating on.
	InstanceID *string `json:"instance_id,omitempty"`
	// The ID of the host that the task is running on.
	HostID *string `json:"host_id,omitempty"`
	// The unique ID of the task.
	TaskID string `json:"task_id"`
	// The time when the task was created.
	CreatedAt string `json:"created_at"`
	// The time when the task was completed.
	CompletedAt *string `json:"completed_at,omitempty"`
	// The type of the task.
	Type string `json:"type"`
	// The status of the task.
	Status string `json:"status"`
	// The error message if the task failed.
	Error *string `json:"error,omitempty"`
}

// TaskLog is the result type of the control-plane service
// get-database-task-log method.
type TaskLog struct {
	// The scope of the task (database or host).
	Scope string `json:"scope"`
	// The entity ID (database_id or host_id) that this task log belongs to.
	EntityID string `json:"entity_id"`
	// The database ID of the task log. Deprecated: use entity_id instead.
	DatabaseID *string `json:"database_id,omitempty"`
	// The unique ID of the task log.
	TaskID string `json:"task_id"`
	// The status of the task.
	TaskStatus string `json:"task_status"`
	// The ID of the last entry in the task log.
	LastEntryID *string `json:"last_entry_id,omitempty"`
	// Entries in the task log.
	Entries []*TaskLogEntry `json:"entries"`
}

type TaskLogEntry struct {
	// The timestamp of the log entry.
	Timestamp string `json:"timestamp"`
	// The log message.
	Message string `json:"message"`
	// Additional fields for the log entry.
	Fields map[string]any `json:"fields,omitempty"`
}

// UpdateDatabasePayload is the payload type of the control-plane service
// update-database method.
type UpdateDatabasePayload struct {
	// ID of the database to update.
	DatabaseID Identifier
	// Force update the database even if the spec is the same.
	ForceUpdate bool
	// Host IDs to treat as removed during this update. Events targeting these
	// hosts will be skipped.
	RemoveHost []string
	Request    *UpdateDatabaseRequest
}

type UpdateDatabaseRequest struct {
	// Unique identifier for the database's owner.
	TenantID *Identifier `json:"tenant_id,omitempty"`
	// The specification for the database.
	Spec *DatabaseSpec `json:"spec"`
}

// UpdateDatabaseResponse is the result type of the control-plane service
// update-database method.
type UpdateDatabaseResponse struct {
	// The task that will update this database.
	Task *Task `json:"task"`
	// The database being updated.
	Database *Database `json:"database"`
}

// VersionInfo is the result type of the control-plane service get-version
// method.
type VersionInfo struct {
	// The version of the API server.
	Version string `json:"version"`
	// The VCS revision of the API server.
	Revision string `json:"revision"`
	// The timestamp associated with the revision.
	RevisionTime string `json:"revision_time"`
	// The CPU architecture of the API server.
	Arch string `json:"arch"`
}

// Error returns an error description.
func (e *APIError) Error() string {
	return "A Control Plane API error."
}

// ErrorName returns "APIError".
//
// Deprecated: Use GoaErrorName - https://github.com/goadesign/goa/issues/3105
func (e *APIError) ErrorName() string {
	return e.GoaErrorName()
}

// GoaErrorName returns "APIError".
func (e *APIError) GoaErrorName() string {
	return e.Name
}

// MakeServerError builds a goa.ServiceError from an error.
func MakeServerError(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "server_error", false, false, false)
}

// MakeClusterAlreadyInitialized builds a goa.ServiceError from an error.
func MakeClusterAlreadyInitialized(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "cluster_already_initialized", false, false, false)
}

// MakeOperationNotSupported builds a goa.ServiceError from an error.
func MakeOperationNotSupported(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "operation_not_supported", false, false, false)
}

// MakeInvalidJoinToken builds a goa.ServiceError from an error.
func MakeInvalidJoinToken(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "invalid_join_token", false, false, false)
}

// MakeInvalidInput builds a goa.ServiceError from an error.
func MakeInvalidInput(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "invalid_input", false, false, false)
}

// MakeClusterNotInitialized builds a goa.ServiceError from an error.
func MakeClusterNotInitialized(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "cluster_not_initialized", false, false, false)
}

// MakeNotFound builds a goa.ServiceError from an error.
func MakeNotFound(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "not_found", false, false, false)
}

// MakeOperationAlreadyInProgress builds a goa.ServiceError from an error.
func MakeOperationAlreadyInProgress(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "operation_already_in_progress", false, false, false)
}

// MakeDatabaseNotModifiable builds a goa.ServiceError from an error.
func MakeDatabaseNotModifiable(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "database_not_modifiable", false, false, false)
}

// MakeRestartFailed builds a goa.ServiceError from an error.
func MakeRestartFailed(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "restart_failed", false, false, false)
}

// MakeStopFailed builds a goa.ServiceError from an error.
func MakeStopFailed(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "stop_failed", false, false, false)
}

// MakeStartFailed builds a goa.ServiceError from an error.
func MakeStartFailed(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "start_failed", false, false, false)
}

// MakeCancelFailed builds a goa.ServiceError from an error.
func MakeCancelFailed(err error) *goa.ServiceError {
	return goa.NewServiceError(err, "cancel_failed", false, false, false)
}