hosts

type AdapterStore interface {
	List(ctx context.Context) ([]state.AdapterConfig, error)
	Save(ctx context.Context, c state.AdapterConfig) (state.Replaced, error)
}

type AuditWriter interface {
	Write(ctx context.Context, e audit.Event) error
}

type Authority struct {
	Cert *x509.Certificate
	Key  crypto.Signer
}

type BackupDestinations interface {
	Default(c api.Category) (string, bool)
	Backup(ref string) (api.BackupAdapter, bool)
}

type ControlKeys struct {
	DatabaseURL secret.Value
	// SecretsKey is the local secrets adapter's key, empty when the install
	// uses another secrets adapter. SecretsKeyPath is where that adapter's
	// configuration, which the joining host reads from the shared database,
	// says it lives.
	SecretsKey     secret.Value
	SecretsKeyPath string
	TokenKey       secret.Value
	// Authority is the cluster authority's certificate and key, PEM.
	Authority secret.Value
}

type ControlPeers struct {
	Store HostPublisher
	Self  string
	Port  int
	Pin   string
	// PinOf, when set, is the fingerprint of the certificate the host
	// answers with now, in place of Pin: the certificate is renewed while
	// the host runs (R-421).
	PinOf  func() string
	Logger *zap.Logger
}

type CredentialStore interface {
	Put(ctx context.Context, adapterID, field string, v secret.Value) error
}

type Decoded struct {
	Address       string
	AuthorityHash string
	Secret        secret.Value
}

type EveryVerbChecker interface {
	CheckHoldsEveryInstallVerb(ctx context.Context, p authz.Principal, act, because string) error
}

type HostCerts struct {
	Host  *hostagent.RenewingCert
	Probe *hostagent.RenewingCert
}

type HostLister interface {
	Hosts(ctx context.Context) ([]state.Host, error)
}

type HostPublisher interface {
	HostLister
	// Revoked is every host removed from the cluster, whose pings a control
	// host refuses (R-415, Members).
	Revoked(ctx context.Context) (state.Revoked, error)
	SetHostPing(ctx context.Context, hostID, address, certSHA256 string) error
	RotateHostCert(ctx context.Context, hostID, next string) error
}

type HostRenewal struct {
	// Address is the cluster listener, https://host:port: the join token's.
	Address string
	// Dir is the cluster directory the join wrote to.
	Dir  string
	Name string
	// AuthorityPEM is the cluster authority's certificate (ca.crt).
	AuthorityPEM []byte
	// HTTP makes the client a renewal connects with; nil is one with a
	// one-minute timeout.
	HTTP func(*tls.Config) *http.Client
	// Now is the clock; nil is time.Now.
	Now func() time.Time
}

type InstallHostInfo struct {
	// Hostname is the machine's; the host is named by its first label.
	Hostname string
	// Address is where its agent is reached, host:port.
	Address  string
	Platform string
	Version  string
}

type InstallHostStore interface {
	RecordFirstHost(ctx context.Context, h state.Host) (state.Host, bool, error)
}

type JoinFiles struct {
	// Dir holds the host's certificate and key, the authority's
	// certificate, the database address for a control host, and joined.json,
	// written last, which says the join is done.
	Dir string
	// DatabaseURLPath is where config.Load reads a joined control host's
	// database address from, ahead of database.url.
	DatabaseURLPath string
	// TokenKeyPath and AuthorityPath are server.token_key_path and
	// server.cluster_authority_path: a control host's keys replace what its
	// own first start made there.
	TokenKeyPath  string
	AuthorityPath string
}

type JoinReadiness interface {
	ReadyToJoin(ctx context.Context, roles []string) error
}

type JoinRequest struct {
	Secret   secret.Value
	Name     string
	CSR      []byte
	Platform string
	Version  string
	// Address is where the joining host's agent listens, host:port (R-416).
	Address string
}

type JoinResult struct {
	Host state.Host
	// Certificate is the host's own, issued from the authority; Authority is
	// the authority's certificate. Both PEM.
	Certificate []byte
	Authority   []byte
	// HostClientCert and HostClientKey are the certificate, and its key, the
	// host checks the others' agents with (R-421): subject pando-host, client
	// authentication only, which an agent answers with a ping and nothing
	// else. Issued here because only a holder of the authority's key can
	// issue one. PEM.
	HostClientCert []byte
	HostClientKey  secret.Value
	// NetworkPool is the runtime's app network range, which the host's agent
	// forwards into and nowhere else (R-416). Empty is the runtime's default.
	NetworkPool string
	// Keys is set for a host with the control role, and only then.
	Keys *ControlKeys
}

type Joined struct {
	HostID   string    `json:"host_id"`
	Name     string    `json:"name"`
	Roles    []string  `json:"roles"`
	Cluster  string    `json:"cluster"`
	JoinedAt time.Time `json:"joined_at"`
	// NetworkPool is the runtime's app network range when the host joined,
	// which its agent forwards into (R-416). Empty is the runtime's default.
	NetworkPool string `json:"network_pool,omitempty"`
}

type Joiner struct {
	// Fresh reports whether this Pando has had an account or an app; a Pando
	// that has cannot join (R-415).
	Fresh func(ctx context.Context) (accounts, apps bool, err error)

	Files JoinFiles

	// Version and Platform are this binary's; AgentAddress is where this
	// host's agent will listen, host:port (R-416).
	Version      string
	Platform     string
	AgentAddress string

	// HTTP makes the client a join connects with, from the pinned TLS
	// configuration. Nil is a client with a one-minute timeout.
	HTTP func(*tls.Config) *http.Client

	// DefaultName is the host's name when the join gives none: this
	// machine's hostname.
	DefaultName string

	// Restart starts Pando again once a join made at setup has been answered,
	// into the cluster: as a replica for the control role, as a host agent
	// for the app role alone.
	Restart func()

	// SetupToken checks the setup token a join from the setup screen presents
	// (state.Users.CheckSetupToken): the one POST /setup needs, so that being
	// first to a fresh Pando is not enough to join it to a cluster of one's
	// own (R-046, R-415). Nil refuses every such join.
	SetupToken func(ctx context.Context, token secret.Value) error

	Now func() time.Time
}

type KeySource struct {
	DatabaseURL  secret.Value
	TokenKeyPath string
	// SecretsKeyPath is where the local secrets adapter keeps its key, or ""
	// when the install uses another.
	SecretsKeyPath func(context.Context) string
}

type Members struct {
	// contains filtered or unexported fields
}

type MintRequest struct {
	Roles     []string
	MaxUses   int
	ExpiresIn time.Duration
	Address   string
}

type Minted struct {
	Token state.JoinToken `json:"token"`
	Join  secret.Value    `json:"join"`
}

type Peer struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Address string `json:"address"`
	// Control is that the host holds the control role, so its Address is
	// a cluster listener: where an app host asks for this list again when
	// the one in its join token is gone (PeerSync).
	Control bool `json:"control,omitempty"`
	// Lost is that the host is marked lost (R-421): it is left out of the
	// cluster's size on every host, as it is on the leader.
	Lost bool `json:"lost,omitempty"`
}

type PeerList struct {
	Hosts   []Peer        `json:"hosts"`
	Revoked state.Revoked `json:"revoked"`
}

type PeerSync struct {
	// Address is the cluster listener, https://host:port: the join token's.
	Address string
	TLS     *tls.Config
	File    string
	// HTTP is the client; nil is one with a short timeout, since a round
	// waits for it.
	HTTP *http.Client
	// Members, when set, is given every host the list says was removed,
	// and keeps them in RevokedFile beside File (R-415).
	Members *Members
}

type PolicyLoader interface {
	Load(ctx context.Context) (policy.Document, error)
}

type Readiness struct {

	// Routing is the adapter registry, for the check that a second control
	// host's edge can share certificates with this one's (O-68). Nil skips
	// it.
	Routing RoutingAdapters
	// contains filtered or unexported fields
}

type Removed struct {
	Host state.Host `json:"host"`
	// Rotate names the keys a removed control host was handed at its join
	// (R-415), which removing it does not take back.
	Rotate []string `json:"rotate,omitempty"`
	Notice string   `json:"notice,omitempty"`
}

type RenewResult struct {
	Host           state.Host
	Certificate    []byte
	HostClientCert []byte
	HostClientKey  secret.Value
}

type RestartSignal interface {
	RequestRestart(ctx context.Context) error
}

type RoutingAdapters interface {
	ByCategory(c api.Category) []string
	Routing(ref string) (api.RoutingAdapter, bool)
}

type Runtime struct {
	Hosts       HostLister
	Adapters    AdapterStore
	Credentials CredentialStore
	Restart     RestartSignal
	Audit       AuditWriter

	// Authority is the cluster's: the agents' mutual TLS is the cluster's,
	// handed to the runtime as its agent_authority credential (R-416).
	Authority *Authority

	// LocalName is the name the install's own machine takes in the host list
	// when it becomes the control host and first app host (R-418), when it
	// has no row in cluster_hosts to take it from (localName). Empty is
	// "control". It names the machine's volumes from then on, so it does not
	// change.
	LocalName string

	// LocalAgentAddress is where the control host's agent is reached, as
	// host:port: this machine's address and the agent port.
	LocalAgentAddress string

	// Joined is set on a control host that joined the cluster: it is not the
	// install's own machine, so a conversion it makes takes that machine's
	// agent address from the machine's cluster_hosts row, not from
	// LocalAgentAddress (R-416).
	Joined bool

	// Declared reports whether the configuration file declares the adapter
	// with this ID (R-271), which a stored row then does not override.
	Declared func(id string) bool
}

type RuntimeHost struct {
	Name             string `json:"name"`
	Endpoint         string `json:"endpoint,omitempty"`
	CertSHA256       string `json:"cert_sha256,omitempty"`
	AgentAddress     string `json:"agent_address,omitempty"`
	Control          bool   `json:"control,omitempty"`
	TotalCPUMillis   int    `json:"total_cpu_millis,omitempty"`
	TotalMemoryBytes int64  `json:"total_memory_bytes,omitempty"`
	TotalDiskBytes   int64  `json:"total_disk_bytes,omitempty"`
}

type Service struct {
	Store     Store
	Authority *Authority

	// Address is where a joining host reaches this install's cluster
	// listener, used when a token is minted without one:
	// https://<host>:<cluster port>.
	Address string

	// Runtime keeps the runtime adapter's host list in line with the
	// cluster's app hosts (runtime.go). A join checks Runtime.CheckJoin
	// before it lets an app host in. Nil in tests that do not need it.
	Runtime *Runtime

	// OnChange runs after a host joins or is removed: the server syncs the
	// runtime's host list there (Runtime.Sync) and logs what fails, which
	// does not undo the change. Nil does nothing.
	OnChange func(ctx context.Context)

	// Version is this server's, which a joining host must match (R-415 [P]).
	Version string

	// Keys are read for a host joining with the control role.
	Keys KeySource

	// Readiness, when set, is asked before a join spends a use of its token.
	Readiness JoinReadiness

	// JoinCheckTimeout bounds the checks a join makes before it spends its
	// token's use (readiness, the runtime, the keys); zero is
	// DefaultJoinCheckTimeout.
	JoinCheckTimeout time.Duration

	// IsSelf picks the host serving this process's requests, which Remove
	// refuses. Nil refuses none but the install's own first host.
	IsSelf func(state.Host) bool

	Now func() time.Time
}

type Store interface {
	CreateJoinToken(ctx context.Context, roles []string, maxUses int, createdBy string, expiresAt time.Time) (state.IssuedJoinToken, error)
	JoinTokens(ctx context.Context) ([]state.JoinToken, error)
	RevokeJoinToken(ctx context.Context, tokenID string) (state.JoinToken, error)
	Hosts(ctx context.Context) ([]state.Host, error)
	RemoveHost(ctx context.Context, hostID string) (state.Host, error)
	// A join (R-415): the token checked without spending it, then spent
	// with the host recorded pending, which the host confirms.
	CheckJoinToken(ctx context.Context, presented secret.Value) (state.JoinToken, error)
	Join(ctx context.Context, presented secret.Value, h state.Host) (state.JoinToken, state.Host, error)
	ConfirmJoin(ctx context.Context, hostID string) (bool, error)
	// The host's certificates (R-415, R-421): which host holds one, pending
	// or not, renewing them, and refusing a removed host's.
	HostByCert(ctx context.Context, sha string) (state.Host, bool, error)
	RenewHostCert(ctx context.Context, hostID, presented, next string, nextPEM []byte) (state.Host, bool, error)
	ConfirmHostCert(ctx context.Context, hostID, current string) (bool, error)
	CertRevoked(ctx context.Context, sha string) (bool, error)
	Revoked(ctx context.Context) (state.Revoked, error)
}

type SyncResult struct {
	AdapterID string `json:"adapter_id,omitempty"`
	Converted bool   `json:"converted"`
	Changed   bool   `json:"changed"`
}

type WireJoinRequest struct {
	Secret   string `json:"secret"`
	Name     string `json:"name"`
	CSR      string `json:"csr"`
	Platform string `json:"platform"`
	Version  string `json:"version"`
	Address  string `json:"address"`
}

type WireJoinResult struct {
	Host           state.Host `json:"host"`
	Certificate    string     `json:"certificate"`
	Authority      string     `json:"authority"`
	HostClientCert string     `json:"host_client_certificate,omitempty"`
	HostClientKey  string     `json:"host_client_key,omitempty"`
	NetworkPool    string     `json:"network_pool,omitempty"`
	Keys           *WireKeys  `json:"keys,omitempty"`
}

type WireKeys struct {
	DatabaseURL      string `json:"database_url"`
	SecretsKey       string `json:"secrets_key,omitempty"`
	SecretsKeyPath   string `json:"secrets_key_path,omitempty"`
	TokenKey         string `json:"token_key"`
	ClusterAuthority string `json:"cluster_authority"`
}

type WireRenewRequest struct {
	CSR string `json:"csr"`
}

type WireRenewResult struct {
	Host           state.Host `json:"host"`
	Certificate    string     `json:"certificate"`
	HostClientCert string     `json:"host_client_certificate"`
	HostClientKey  string     `json:"host_client_key"`
}