backend

type Applier func(ctx context.Context, kind apitype.UpdateKind, stack Stack, op UpdateOperation,
	opts ApplierOptions, events chan<- engine.Event) (*deploy.Plan, sdkDisplay.ResourceChanges, error)

type ApplierOptions struct {
	// DryRun indicates if the update should not change any resource state and instead just preview changes.
	DryRun bool
	// ShowLink indicates if a link to the update persisted result can be displayed.
	ShowLink bool
}

type Backend interface {
	// Name returns a friendly name for this backend.
	Name() string
	// URL returns a URL at which information about this backend may be seen.
	URL() string

	// SetCurrentProject sets the current ambient project for this backend.
	SetCurrentProject(proj *workspace.Project)

	// GetPolicyPack returns a PolicyPack object tied to this backend, or nil if it cannot be found.
	GetPolicyPack(ctx context.Context, policyPack string, d diag.Sink) (PolicyPack, error)

	// ListPolicyGroups returns all Policy Groups for an organization in this backend or an error if it cannot be found.
	ListPolicyGroups(ctx context.Context, orgName string, inContToken ContinuationToken) (
		apitype.ListPolicyGroupsResponse, ContinuationToken, error)

	// ListPolicyPacks returns all Policy Packs for an organization in this backend, or an error if it cannot be found.
	ListPolicyPacks(ctx context.Context, orgName string, inContToken ContinuationToken) (
		apitype.ListPolicyPacksResponse, ContinuationToken, error)

	// SupportsTags tells whether a stack can have associated tags stored with it in this backend.
	SupportsTags() bool

	// SupportsOrganizations tells whether a user can belong to multiple organizations in this backend.
	SupportsOrganizations() bool

	// SupportsProgress tells whether the backend supports showing whether an operation is currently in progress
	SupportsProgress() bool

	// SupportsDeployments tells whether it is possible to manage deployments in this backend.
	SupportsDeployments() bool

	// ParseStackReference takes a string representation and parses it to a reference which may be used for other
	// methods in this backend.
	ParseStackReference(s string) (StackReference, error)
	// ValidateStackName verifies that the string is a legal identifier for a (potentially qualified) stack.
	// Will check for any backend-specific naming restrictions.
	ValidateStackName(s string) error

	// DoesProjectExist returns true if a project with the given name exists in this backend, or false otherwise.
	DoesProjectExist(ctx context.Context, orgName string, projectName string) (bool, error)

	// GetStack returns a stack object tied to this backend with the given name, or nil if it cannot be found.
	GetStack(ctx context.Context, stackRef StackReference) (Stack, error)
	// CreateStack creates a new stack with the given name, initial state and options that are specific to the
	// backend provider.
	CreateStack(
		ctx context.Context,
		stackRef StackReference,
		root string,
		initialState *apitype.UntypedDeployment,
		opts *CreateStackOptions,
	) (Stack, error)

	// RemoveStack removes a stack with the given name.  If force is true, the stack will be removed even if it
	// still contains resources.  Otherwise, if the stack contains resources, a non-nil error is returned, and the
	// first boolean return value will be set to true.
	RemoveStack(ctx context.Context, stack Stack, force bool) (bool, error)
	// ListStacks returns a list of stack summaries for all known stacks in the target backend.
	ListStacks(ctx context.Context, filter ListStacksFilter, inContToken ContinuationToken) (
		[]StackSummary, ContinuationToken, error)

	// RenameStack renames the given stack to a new name, and then returns an updated stack reference that
	// can be used to refer to the newly renamed stack.
	RenameStack(ctx context.Context, stack Stack, newName tokens.QName) (StackReference, error)

	// Preview shows what would be updated given the current workspace's contents.
	Preview(
		ctx context.Context, stack Stack, op UpdateOperation, events chan<- engine.Event,
	) (*deploy.Plan, sdkDisplay.ResourceChanges, error)
	// Update updates the target stack with the current workspace's contents (config and code).
	Update(ctx context.Context, stack Stack, op UpdateOperation) (sdkDisplay.ResourceChanges, error)
	// Import imports resources into a stack.
	Import(ctx context.Context, stack Stack, op UpdateOperation,
		imports []deploy.Import) (sdkDisplay.ResourceChanges, error)
	// Refresh refreshes the stack's state from the cloud provider.
	Refresh(ctx context.Context, stack Stack, op UpdateOperation) (sdkDisplay.ResourceChanges, error)
	// Destroy destroys all of this stack's resources.
	Destroy(ctx context.Context, stack Stack, op UpdateOperation) (sdkDisplay.ResourceChanges, error)
	// Watch watches the project's working directory for changes and automatically updates the active stack.
	Watch(ctx context.Context, stack Stack, op UpdateOperation, paths []string) error

	// Query against the resource outputs in a stack's state checkpoint.
	Query(ctx context.Context, op QueryOperation) error

	// GetHistory returns all updates for the stack. The returned UpdateInfo slice will be in
	// descending order (newest first).
	GetHistory(ctx context.Context, stackRef StackReference, pageSize int, page int) ([]UpdateInfo, error)
	// GetLogs fetches a list of log entries for the given stack, with optional filtering/querying.
	GetLogs(ctx context.Context, secretsProvider secrets.Provider, stack Stack, cfg StackConfiguration,
		query operations.LogQuery) ([]operations.LogEntry, error)
	// Get the configuration from the most recent deployment of the stack.
	GetLatestConfiguration(ctx context.Context, stack Stack) (config.Map, error)

	// UpdateStackTags updates the stacks's tags, replacing all existing tags.
	UpdateStackTags(ctx context.Context, stack Stack, tags map[apitype.StackTagName]string) error

	// Encrypt secrets using the DS encryption key
	EncryptStackDeploymentSettingsSecret(ctx context.Context, stack Stack, secret string) (*apitype.SecretValue, error)
	// UpdateStackDeploymentSettings updates the stacks's deployment settings.
	UpdateStackDeploymentSettings(ctx context.Context, stack Stack, deployment apitype.DeploymentSettings) error
	// Fetch deployment settings
	GetStackDeploymentSettings(ctx context.Context, stack Stack) (*apitype.DeploymentSettings, error)
	// Deletes the stach deployment settings
	DestroyStackDeploymentSettings(ctx context.Context, stack Stack) error
	// Fetch the GH App installation status
	GetGHAppIntegration(ctx context.Context, stack Stack) (*apitype.GitHubAppIntegration, error)

	// ExportDeployment exports the deployment for the given stack as an opaque JSON message.
	ExportDeployment(ctx context.Context, stack Stack) (*apitype.UntypedDeployment, error)
	// ImportDeployment imports the given deployment into the indicated stack.
	ImportDeployment(ctx context.Context, stack Stack, deployment *apitype.UntypedDeployment) error
	// Returns the identity of the current user and any organizations they are in for the backend.
	CurrentUser() (string, []string, *workspace.TokenInformation, error)

	// Cancel the current update for the given stack.
	CancelCurrentUpdate(ctx context.Context, stackRef StackReference) error

	// DefaultSecretManager accepts a project stack configuration (which may be empty, but not nil) and populates it with
	// the default secrets manager configuration for stacks created against this backend, returning a secrets manager
	// corresponding to that configuration.
	//
	// If the project stack configuration contains configuration for the same type of secrets manager as the backend
	// default, this should be respected.
	//
	// If it is not possible to determine a default secrets manager for a stack prior to its creation, this method should
	// return nil and make no changes to the supplied project stack configuration.
	//
	// When a stack has been instantiated, you should favor using the Stack.DefaultSecretManager method to get a default
	// secrets manager for that stack.
	DefaultSecretManager(ps *workspace.ProjectStack) (secrets.Manager, error)
}

type CancellationScope interface {
	// Context returns the cancellation context used to observe cancellation and termination requests for this scope.
	Context() *cancel.Context
	// Close closes the cancellation scope.
	Close()
}

type CancellationScopeSource interface {
	// NewScope creates a new cancellation scope.
	NewScope(events chan<- engine.Event, isPreview bool) CancellationScope
}

type ConflictingUpdateError struct {
	Err error // The error that occurred while starting the operation.
}

type ContinuationToken *string

type CreateStackOptions struct {
	// Teams is a list of teams who should have access to
	// the newly created stack.
	// This option is only appropriate for backends
	// which support teams (i.e. the Codeinfra Service).
	//
	// The backend may return ErrTeamsNotSupported
	// if Teams is specified but not supported.
	Teams []string
}

type EnvironmentsBackend interface {
	CreateEnvironment(
		ctx context.Context,
		org string,
		projectName string,
		envName string,
		yaml []byte,
	) (apitype.EnvironmentDiagnostics, error)

	CheckYAMLEnvironment(
		ctx context.Context,
		org string,
		yaml []byte,
	) (*esc.Environment, apitype.EnvironmentDiagnostics, error)

	// OpenYAMLEnvironment opens a literal environment.
	OpenYAMLEnvironment(
		ctx context.Context,
		org string,
		yaml []byte,
		duration time.Duration,
	) (*esc.Environment, apitype.EnvironmentDiagnostics, error)
}

type InMemoryPersister struct {
	Snap *deploy.Snapshot
}

type ListStacksFilter struct {
	Organization *string
	Project      *string
	TagName      *string
	TagValue     *string
}

type MakeQuery func(context.Context, QueryOperation) (engine.QueryInfo, error)

type MockBackend struct {
	NameF                  func() string
	URLF                   func() string
	SetCurrentProjectF     func(proj *workspace.Project)
	GetPolicyPackF         func(ctx context.Context, policyPack string, d diag.Sink) (PolicyPack, error)
	SupportsTagsF          func() bool
	SupportsOrganizationsF func() bool
	SupportsProgressF      func() bool
	ParseStackReferenceF   func(s string) (StackReference, error)
	SupportsDeploymentsF   func() bool
	ValidateStackNameF     func(s string) error
	DoesProjectExistF      func(context.Context, string, string) (bool, error)
	GetStackF              func(context.Context, StackReference) (Stack, error)
	CreateStackF           func(
		context.Context,
		StackReference,
		string,
		*apitype.UntypedDeployment,
		*CreateStackOptions,
	) (Stack, error)
	RemoveStackF func(context.Context, Stack, bool) (bool, error)
	ListStacksF  func(context.Context, ListStacksFilter, ContinuationToken) (
		[]StackSummary, ContinuationToken, error)
	RenameStackF                          func(context.Context, Stack, tokens.QName) (StackReference, error)
	GetStackCrypterF                      func(StackReference) (config.Crypter, error)
	QueryF                                func(context.Context, QueryOperation) error
	GetLatestConfigurationF               func(context.Context, Stack) (config.Map, error)
	GetHistoryF                           func(context.Context, StackReference, int, int) ([]UpdateInfo, error)
	UpdateStackTagsF                      func(context.Context, Stack, map[apitype.StackTagName]string) error
	ExportDeploymentF                     func(context.Context, Stack) (*apitype.UntypedDeployment, error)
	ImportDeploymentF                     func(context.Context, Stack, *apitype.UntypedDeployment) error
	EncryptStackDeploymentSettingsSecretF func(ctx context.Context,
		stack Stack, secret string) (*apitype.SecretValue, error)
	UpdateStackDeploymentSettingsF  func(context.Context, Stack, apitype.DeploymentSettings) error
	DestroyStackDeploymentSettingsF func(ctx context.Context, stack Stack) error
	GetGHAppIntegrationF            func(ctx context.Context, stack Stack) (*apitype.GitHubAppIntegration, error)
	GetStackDeploymentSettingsF     func(context.Context, Stack) (*apitype.DeploymentSettings, error)
	CurrentUserF                    func() (string, []string, *workspace.TokenInformation, error)
	PreviewF                        func(context.Context, Stack,
		UpdateOperation) (*deploy.Plan, sdkDisplay.ResourceChanges, error)
	UpdateF func(context.Context, Stack,
		UpdateOperation) (sdkDisplay.ResourceChanges, error)
	ImportF func(context.Context, Stack,
		UpdateOperation, []deploy.Import) (sdkDisplay.ResourceChanges, error)
	RefreshF func(context.Context, Stack,
		UpdateOperation) (sdkDisplay.ResourceChanges, error)
	DestroyF func(context.Context, Stack,
		UpdateOperation) (sdkDisplay.ResourceChanges, error)
	WatchF func(context.Context, Stack,
		UpdateOperation, []string) error
	GetLogsF func(context.Context, secrets.Provider, Stack, StackConfiguration,
		operations.LogQuery) ([]operations.LogEntry, error)

	CancelCurrentUpdateF func(ctx context.Context, stackRef StackReference) error

	DefaultSecretManagerF func(ps *workspace.ProjectStack) (secrets.Manager, error)
}

type MockEnvironmentsBackend struct {
	MockBackend

	CreateEnvironmentF func(
		ctx context.Context,
		org string,
		projectName string,
		envName string,
		yaml []byte,
	) (apitype.EnvironmentDiagnostics, error)

	CheckYAMLEnvironmentF func(
		ctx context.Context,
		org string,
		yaml []byte,
	) (*esc.Environment, apitype.EnvironmentDiagnostics, error)

	OpenYAMLEnvironmentF func(
		ctx context.Context,
		org string,
		yaml []byte,
		duration time.Duration,
	) (*esc.Environment, apitype.EnvironmentDiagnostics, error)
}

type MockPolicyPack struct {
	RefF      func() PolicyPackReference
	BackendF  func() Backend
	PublishF  func(context.Context, PublishOperation) error
	EnableF   func(context.Context, string, PolicyPackOperation) error
	DisableF  func(context.Context, string, PolicyPackOperation) error
	ValidateF func(context.Context, PolicyPackOperation) error
	RemoveF   func(context.Context, PolicyPackOperation) error
}

type MockStack struct {
	RefF      func() StackReference
	OrgNameF  func() string
	ConfigF   func() config.Map
	SnapshotF func(ctx context.Context, secretsProvider secrets.Provider) (*deploy.Snapshot, error)
	TagsF     func() map[apitype.StackTagName]string
	BackendF  func() Backend
	PreviewF  func(ctx context.Context, op UpdateOperation) (*deploy.Plan, sdkDisplay.ResourceChanges, error)
	UpdateF   func(ctx context.Context, op UpdateOperation) (sdkDisplay.ResourceChanges, error)
	ImportF   func(ctx context.Context, op UpdateOperation,
		imports []deploy.Import) (sdkDisplay.ResourceChanges, error)
	RefreshF func(ctx context.Context, op UpdateOperation) (sdkDisplay.ResourceChanges, error)
	DestroyF func(ctx context.Context, op UpdateOperation) (sdkDisplay.ResourceChanges, error)
	WatchF   func(ctx context.Context, op UpdateOperation, paths []string) error
	QueryF   func(ctx context.Context, op UpdateOperation) error
	RemoveF  func(ctx context.Context, force bool) (bool, error)
	RenameF  func(ctx context.Context, newName tokens.QName) (StackReference, error)
	GetLogsF func(ctx context.Context, secretsProvider secrets.Provider, cfg StackConfiguration,
		query operations.LogQuery) ([]operations.LogEntry, error)
	ExportDeploymentF     func(ctx context.Context) (*apitype.UntypedDeployment, error)
	ImportDeploymentF     func(ctx context.Context, deployment *apitype.UntypedDeployment) error
	DefaultSecretManagerF func(info *workspace.ProjectStack) (secrets.Manager, error)
}

type MockStackReference struct {
	StringV             string
	NameV               tokens.StackName
	ProjectV            tokens.Name
	FullyQualifiedNameV tokens.QName
}

type OverStackLimitError struct {
	Message string
}

type PolicyPack interface {
	// Ref returns a reference to this PolicyPack.
	Ref() PolicyPackReference
	// Backend returns the backend this PolicyPack is managed by.
	Backend() Backend
	// Publish the PolicyPack to the service.
	Publish(ctx context.Context, op PublishOperation) error
	// Enable the PolicyPack to a Policy Group in an organization. If Policy Group is
	// empty, it enables it for the default Policy Group.
	Enable(ctx context.Context, policyGroup string, op PolicyPackOperation) error

	// Disable the PolicyPack for a Policy Group in an organization. If Policy Group is
	// empty, it disables it for the default Policy Group.
	Disable(ctx context.Context, policyGroup string, op PolicyPackOperation) error

	// Validate the PolicyPack configuration against configuration schema.
	Validate(ctx context.Context, op PolicyPackOperation) error

	// Remove the PolicyPack from an organization. The Policy Pack must be removed from
	// all Policy Groups before it can be removed.
	Remove(ctx context.Context, op PolicyPackOperation) error
}

type PolicyPackOperation struct {
	// If nil, the latest version is assumed.
	VersionTag *string
	Scopes     CancellationScopeSource
	Config     map[string]*json.RawMessage
}

type PolicyPackReference interface {
	// fmt.Stringer's String() method returns a string of the stack identity, suitable for display in the CLI
	fmt.Stringer
	// OrgName is the name of the organization that is managing the PolicyPack.
	OrgName() string
	// Name is the name of the PolicyPack being referenced.
	Name() tokens.QName
}

type PublishOperation struct {
	Root       string
	PlugCtx    *plugin.Context
	PolicyPack *workspace.PolicyPackProject
	Scopes     CancellationScopeSource
}

type QueryOperation struct {
	Proj               *workspace.Project
	Root               string
	Opts               UpdateOptions
	SecretsManager     secrets.Manager
	SecretsProvider    secrets.Provider
	StackConfiguration StackConfiguration
	Scopes             CancellationScopeSource
}

type QueryOptions struct {
	// Engine contains all of the engine-specific options.
	Engine engine.UpdateOptions
	// Display contains all of the backend display options.
	Display display.Options
}

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

type SnapshotPersister interface {
	// Persists the given snapshot. Returns an error if the persistence failed.
	Save(snapshot *deploy.Snapshot) error
}

type SpecificDeploymentExporter interface {
	// ExportDeploymentForVersion exports a specific deployment from the history of a stack. The meaning of
	// version is backend-specific. For the Codeinfra Console, it is the numeric version. (The first update
	// being version "1", the second "2", and so on.) Though this might change in the future to use some
	// other type of identifier or commitish .
	ExportDeploymentForVersion(ctx context.Context, stack Stack, version string) (*apitype.UntypedDeployment, error)
}

type Stack interface {
	// Ref returns this stack's identity.
	Ref() StackReference
	// Snapshot returns the latest deployment snapshot.
	Snapshot(ctx context.Context, secretsProvider secrets.Provider) (*deploy.Snapshot, error)
	// Backend returns the backend this stack belongs to.
	Backend() Backend
	// Tags return the stack's existing tags.
	Tags() map[apitype.StackTagName]string
	// Preview changes to this stack if an Update was run.
	Preview(
		ctx context.Context, op UpdateOperation, events chan<- engine.Event,
	) (*deploy.Plan, display.ResourceChanges, error)
	// Update this stack.
	Update(ctx context.Context, op UpdateOperation) (display.ResourceChanges, error)
	// Import resources into this stack.
	Import(ctx context.Context, op UpdateOperation, imports []deploy.Import) (display.ResourceChanges, error)
	// Refresh this stack's state from the cloud provider.
	Refresh(ctx context.Context, op UpdateOperation) (display.ResourceChanges, error)
	Destroy(ctx context.Context, op UpdateOperation) (display.ResourceChanges, error)
	// Watch this stack.
	Watch(ctx context.Context, op UpdateOperation, paths []string) error

	// Remove this stack.
	Remove(ctx context.Context, force bool) (bool, error)
	// Rename this stack.
	Rename(ctx context.Context, newName tokens.QName) (StackReference, error)
	// GetLogs lists log entries for this stack.
	GetLogs(ctx context.Context, secretsProvider secrets.Provider,
		cfg StackConfiguration, query operations.LogQuery) ([]operations.LogEntry, error)
	// ExportDeployment exports this stack's deployment.
	ExportDeployment(ctx context.Context) (*apitype.UntypedDeployment, error)
	// ImportDeployment imports the given deployment into this stack.
	ImportDeployment(ctx context.Context, deployment *apitype.UntypedDeployment) error

	// DefaultSecretManager returns the default secrets manager to use for this stack. This may be more specific than
	// Backend.DefaultSecretManager.
	DefaultSecretManager(info *workspace.ProjectStack) (secrets.Manager, error)
}

type StackAlreadyExistsError struct {
	StackName string
}

type StackConfiguration struct {
	// List of ESC environments imported by the stack being updated.
	EnvironmentImports []string

	Environment esc.Value
	Config      config.Map
	Decrypter   config.Decrypter
}

type StackReference interface {
	// fmt.Stringer's String() method returns a string of the stack identity, suitable for display in the CLI
	fmt.Stringer
	// Name is the name that will be passed to the Codeinfra engine when preforming operations on this stack. This
	// name may not uniquely identify the stack (e.g. the cloud backend embeds owner information in the StackReference
	// but that information is not part of the StackName() we pass to the engine.
	Name() tokens.StackName

	// Project is the project name that this stack belongs to.
	// For old diy backends this will return false.
	Project() (tokens.Name, bool)

	// Fully qualified name of the stack, including any organization, project, or other information.
	FullyQualifiedName() tokens.QName
}

type StackSummary interface {
	Name() StackReference

	// LastUpdate returns when the stack was last updated, as applicable.
	LastUpdate() *time.Time
	// ResourceCount returns the stack's resource count, as applicable.
	ResourceCount() *int
}

type UpdateInfo struct {
	// Information known before an update is started.
	Kind      apitype.UpdateKind `json:"kind"`
	StartTime int64              `json:"startTime"`

	// Message is an optional message associated with the update.
	Message string `json:"message"`

	// Environment contains optional data from the deploying environment. e.g. the current
	// source code control commit information.
	Environment map[string]string `json:"environment"`

	// Config used for the update.
	Config config.Map `json:"config"`

	// Information obtained from an update completing.
	Version         int                     `json:"version"`
	Result          UpdateResult            `json:"result"`
	EndTime         int64                   `json:"endTime"`
	ResourceChanges display.ResourceChanges `json:"resourceChanges,omitempty"`
}

type UpdateMetadata struct {
	// Message is an optional message associated with the update.
	Message string `json:"message"`
	// Environment contains optional data from the deploying environment. e.g. the current
	// source code control commit information.
	Environment map[string]string `json:"environment"`
}

type UpdateOperation struct {
	Proj               *workspace.Project
	Root               string
	Imports            []deploy.Import
	M                  *UpdateMetadata
	Opts               UpdateOptions
	SecretsManager     secrets.Manager
	SecretsProvider    secrets.Provider
	StackConfiguration StackConfiguration
	Scopes             CancellationScopeSource
}

type UpdateOptions struct {
	// Engine contains all of the engine-specific options.
	Engine engine.UpdateOptions
	// Display contains all of the backend display options.
	Display display.Options

	// AutoApprove, when true, will automatically approve previews.
	AutoApprove bool
	// SkipPreview, when true, causes the preview step to be skipped.
	SkipPreview bool
	// PreviewOnly, when true, causes only the preview step to be run, without running the Update.
	PreviewOnly bool
}

type UpdateResult string