maintenancerunner

type ApplyReport struct {
	// Applied names the migrations that ran, in order. Empty when the database
	// was already up to date.
	Applied []string `json:"applied,omitempty"`

	// Blocked names migrations that were left unapplied because their risk
	// exceeds what the operator authorised, with the risk that stopped them.
	Blocked []BlockedMigration `json:"blocked,omitempty"`
}

type BlockedMigration struct {
	Name string `json:"name"`
	Risk string `json:"risk"`
}

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

type Handler func(ctx context.Context, req Request) *Response

type Host interface {
	// Name identifies the host platform ("aws").
	Name() string

	// Detect reports whether this process is running on it. Implementations
	// should key on something the platform itself sets, not on configuration a
	// user could get wrong.
	Detect() bool

	// Credentials resolves database credentials from the platform's secret
	// store.
	Credentials() dbconn.CredentialSource

	// Serve delivers invocations to handle. It does not return in normal
	// operation.
	Serve(handle Handler, logger *zap.Logger) error
}

type Invoker interface {
	// Invoke runs one operation against a deployed runner. It returns an error
	// only when the runner could not be reached; an operation that ran and
	// failed comes back as a Response with OK false.
	Invoke(ctx context.Context, instance *state.InstanceState, req Request) (*Response, error)

	// Deployed reports whether the instance has a runner at all. An instance
	// deployed before runners existed, or one whose database is publicly
	// reachable, does not.
	Deployed(instance *state.InstanceState) bool
}

type MigrationFile struct {
	// Name is the base file name, never a path. The runner writes these into a
	// directory of its own, and a separator here would let a payload write
	// outside it.
	Name string `json:"name"`

	// Content is the file's bytes as text. Migration files are SQL and the sum
	// file is text, so nothing here needs encoding.
	Content string `json:"content"`
}

type Request struct {
	// Operation is one of the Op constants.
	Operation string `json:"operation"`

	// Database is the abstract name of the celerity/sqlDatabase to act on, as
	// written in the blueprint.
	Database string `json:"database"`

	// Migrations carries the migration directory for OpApply, because the files
	// live on the operator's machine and the runner has no access to it.
	//
	// A synchronous Lambda invocation caps its payload at 6MB, which is far more
	// than a migration directory of text files, but ApplyLimits is checked
	// before invoking so an oversized set is reported as such rather than as a
	// truncated request.
	Migrations []MigrationFile `json:"migrations,omitempty"`

	// MaxRisk is the highest migration risk level the operator authorised, from
	// the same --allow-risky and --allow-breaking flags the local path uses. An
	// empty value permits only safe migrations.
	MaxRisk string `json:"maxRisk,omitempty"`
}

type Response struct {
	Operation string `json:"operation"`
	Database  string `json:"database"`
	OK        bool   `json:"ok"`

	// Error describes why the operation failed, in terms an operator can act on.
	Error string `json:"error,omitempty"`

	// Provision is the report from OpProvisionUser.
	Provision *sqlschema.ProvisionReport `json:"provision,omitempty"`

	// Apply is the report from OpApply.
	Apply *ApplyReport `json:"apply,omitempty"`
}

type Target struct {
	// Engine is "postgres" or "mysql".
	Engine string `json:"engine"`

	// Host and Port are the connection-pool endpoint where there is one,
	// otherwise the database's own endpoint.
	Host string `json:"host"`
	Port string `json:"port"`

	// Database is the database name to connect to.
	Database string `json:"database"`

	// OwnerCredentialRef points at the master/owner credential, the role
	// migrations run as. Empty when the database authenticates its owner with a
	// platform-issued token instead.
	OwnerCredentialRef string `json:"ownerCredentialRef,omitempty"`

	// OwnerUser and Region are what a token is issued for, when
	// OwnerCredentialRef is empty.
	OwnerUser string `json:"ownerUser,omitempty"`
	Region    string `json:"region,omitempty"`

	// AppUser is the role the application connects as.
	AppUser string `json:"appUser"`

	// AppUserCredentialRef points at the application user's generated password.
	// Empty when the application authenticates with a token, which needs no
	// stored credential.
	AppUserCredentialRef string `json:"appUserCredentialRef,omitempty"`

	// AppUserTokenAuth selects platform-issued token authentication (AWS IAM
	// database authentication, and its equivalents) for the application user.
	AppUserTokenAuth bool `json:"appUserTokenAuth,omitempty"`
}

type Targets map[string]*Target