Documentation
¶
Overview ¶
Package appsvc is what a person does to an application (#2411), the one implementation the manage_application tool and the portal routes share: create it, edit its record and parts, release it, roll it back, and read where it stands. It holds the rules: everyone signed in reads an application; its owner and administrators edit it; a part is added by someone who owns that part (a webhook source, which only administrators manage, by an administrator); and only administrators release and roll back, because a release changes the code behind a public endpoint and runs migrations on the target database.
Index ¶
- Constants
- func NextEnvironment(a *application.Application, env string) (*application.Environment, error)
- func RunRoleBinding(applicationID, connection, schema, role string) string
- type AppRef
- type AssetViewer
- type Assets
- type Candidate
- type CandidateLister
- type Candidates
- type ContractSites
- type DiagramDeps
- type DiagramRequest
- type PartSchedule
- type PartView
- type Promoted
- type RefusedError
- type ReleaseOptions
- type Roles
- type Schedules
- type Schema
- type SchemaView
- type Scripts
- type Sealer
- type Service
- func (s *Service) AddEnvironment(ctx context.Context, actor application.Actor, ref string, ...) (*application.Application, error)
- func (s *Service) AddPart(ctx context.Context, actor application.Actor, ref, kind, id string) (*application.Application, error)
- func (s *Service) AddPartMode(ctx context.Context, actor application.Actor, ref string, p application.Part) (*application.Application, error)
- func (s *Service) Create(ctx context.Context, actor application.Actor, a application.Application) (*application.Application, error)
- func (s *Service) Delete(ctx context.Context, actor application.Actor, ref string) error
- func (s *Service) DeleteVariable(ctx context.Context, actor application.Actor, ref, env, name string) error
- func (s *Service) Describe(ctx context.Context, actor application.Actor, parts []application.Part, ...) []PartView
- func (s *Service) Diagram(ctx context.Context, actor application.Actor, req DiagramRequest) (*appdiagram.Diagram, error)
- func (s *Service) Find(ctx context.Context, ref string) (*application.Application, error)
- func (s *Service) FindCandidates(ctx context.Context, actor application.Actor, ref, query, kind string) (*Candidates, error)
- func (s *Service) FindingsIntroduced(ctx context.Context, scriptID string, before int) []string
- func (s *Service) Promote(ctx context.Context, actor application.Actor, ref, from string) (*Promoted, error)
- func (s *Service) Release(ctx context.Context, actor application.Actor, ref, note string) (*application.Release, error)
- func (s *Service) ReleaseAs(ctx context.Context, actor application.Actor, ref, note, action string) (*application.Release, error)
- func (s *Service) ReleaseWith(ctx context.Context, actor application.Actor, ref string, o ReleaseOptions) (*application.Release, error)
- func (s *Service) RemoveEnvironment(ctx context.Context, actor application.Actor, ref, env string) (*application.Application, error)
- func (s *Service) RemovePart(ctx context.Context, actor application.Actor, ref, kind, id string) (*application.Application, error)
- func (s *Service) Rollback(ctx context.Context, actor application.Actor, ref string, to int) (*application.Release, error)
- func (s *Service) RollbackIn(ctx context.Context, actor application.Actor, ref, env string, to int) (*application.Release, error)
- func (s *Service) SchemaOf(ctx context.Context, a *application.Application, current *application.Release) *SchemaView
- func (s *Service) SetContract(ctx context.Context, actor application.Actor, ref string, version int) (*application.Application, error)
- func (s *Service) SetEnvironmentApproval(ctx context.Context, actor application.Actor, ref, env string, requires bool) (*application.Application, error)
- func (s *Service) SetPartMode(ctx context.Context, actor application.Actor, ref, id, mode string) (*application.Application, error)
- func (s *Service) SetVariable(ctx context.Context, actor application.Actor, ref string, ...) error
- func (s *Service) StatusOf(ctx context.Context, ref string) (*Status, error)
- func (s *Service) Update(ctx context.Context, actor application.Actor, ref, description, owner string) (*application.Application, error)
- func (s *Service) Variables(ctx context.Context, actor application.Actor, ref string) ([]application.Variable, error)
- type SitePartView
- type Sites
- type SourceActivity
- type Sources
- type Status
- type Webhooks
Constants ¶
const ( DiagramCurrent = "current" DiagramLatest = "latest" )
The versions of an application a diagram is drawn at (#2540), besides a release's number.
const ( // PartOK is a part the caller reads. PartOK = "ok" // PartDeleted is a part whose script, asset or webhook source is gone. PartDeleted = "deleted" // PartNotVisible is an asset the caller cannot open: its name is not // told. PartNotVisible = "not_visible" )
The states a part is read in (#2527).
const MaxCandidates = 50
MaxCandidates bounds the candidates listed of each kind.
Variables ¶
This section is empty.
Functions ¶
func NextEnvironment ¶ added in v1.164.0
func NextEnvironment(a *application.Application, env string) (*application.Environment, error)
NextEnvironment is the environment a promote from env moves into.
func RunRoleBinding ¶ added in v1.154.2
RunRoleBinding is what a run role's sealed password is bound to: the application, the connection and schema it holds, and the role. A sealed value opens only for the same four.
Types ¶
type AppRef ¶ added in v1.154.1
type AppRef struct {
ID string `json:"id" example:"app_01J9..."`
Name string `json:"name" example:"billing"`
}
AppRef names an application.
type AssetViewer ¶ added in v1.154.1
type AssetViewer func(ctx context.Context, asset *portaldomain.Asset) bool
AssetViewer reports whether the caller of a request opens an asset.
type Candidate ¶ added in v1.154.1
type Candidate struct {
Kind string `json:"kind" example:"script"`
ID string `json:"id" example:"5b0c..."`
Name string `json:"name" example:"Monthly revenue close"`
OwnerEmail string `json:"owner_email,omitempty"`
ContentType string `json:"content_type,omitempty"`
UpdatedAt *time.Time `json:"updated_at,omitempty"`
// Application is the application the part already belongs to, which
// refuses it here; nil for none.
Application *AppRef `json:"application,omitempty"`
}
Candidate is one script, asset, webhook source or site environment the actor may add.
type CandidateLister ¶ added in v1.154.1
type CandidateLister interface {
ListScripts(ctx context.Context, filter script.ListFilter) ([]script.Script, error)
ListAssets(ctx context.Context, filter portaldomain.AssetFilter) ([]portaldomain.Asset, int, error)
// ListSources lists webhook source names matching query.
ListSources(ctx context.Context, query string, limit int) ([]string, error)
}
CandidateLister lists the scripts and assets a search reads.
type Candidates ¶ added in v1.154.1
type Candidates struct {
Candidates []Candidate `json:"candidates"`
Counts map[string]int `json:"counts"`
}
Candidates is a search for parts to add, with how many of each kind matched.
type ContractSites ¶ added in v1.163.0
type ContractSites interface {
// ServedContract is the release an environment serves and the contract
// it declares, nil for none.
ServedContract(ctx context.Context, siteName, environment string) (int, *site.Contract, error)
// ReleaseContract is the contract a release declares, nil for none.
ReleaseContract(ctx context.Context, siteName string, number int) (*site.Contract, error)
}
ContractSites is what the contract check reads of a site part.
type DiagramDeps ¶ added in v1.154.2
type DiagramDeps struct {
Bindings func(ctx context.Context, scriptID string) ([]appdiagram.Binding, error)
AssetContent func(ctx context.Context, assetID string, version int) string
SchemaTables func(ctx context.Context, connection, schema string) appdiagram.SchemaTables
}
DiagramDeps is what the diagram reads besides the service's stores: a script's endpoint bindings, an asset version's text, and the tables an application schema's migrations fill. Each may be nil, which leaves out what it reads.
type DiagramRequest ¶ added in v1.154.2
type DiagramRequest struct {
App string
Version string
Compare string
View AssetViewer
}
DiagramRequest is a diagram asked for: the application, the version drawn (current, latest, or a release's number), the version it is compared with (none when empty), and which assets the caller opens.
type PartSchedule ¶ added in v1.154.1
type PartSchedule struct {
CronSpec string `json:"cron_spec" example:"0 2 * * *"`
Timezone string `json:"timezone" example:"UTC"`
Enabled bool `json:"enabled" example:"true"`
}
PartSchedule is a script part's schedule, which the page puts in words.
type PartView ¶ added in v1.154.1
type PartView struct {
Kind string `json:"kind" example:"script"`
ID string `json:"id" example:"5b0c..."`
State string `json:"state" example:"ok"`
Name string `json:"name,omitempty" example:"Nightly order sync"`
// Description is the script's or asset's own description.
Description string `json:"description,omitempty"`
// LatestVersion is the script's or asset's newest version; nil for a
// webhook source and for a part not read.
LatestVersion *int `json:"latest_version"`
OwnerEmail string `json:"owner_email,omitempty"`
// Schedules are a script's schedule handlers and EventSources the
// webhook sources it runs for (#2434); empty for none.
Schedules []PartSchedule `json:"schedules,omitempty"`
EventSources []string `json:"event_sources,omitempty"`
// ContentType is an asset's media type.
ContentType string `json:"content_type,omitempty"`
UpdatedAt *time.Time `json:"updated_at,omitempty"`
// RequestsLastDay is how many requests a webhook source accepted in the
// last 24 hours; told to administrators, who manage sources.
RequestsLastDay *int64 `json:"requests_last_day,omitempty"`
AddedBy string `json:"added_by"`
AddedAt time.Time `json:"added_at"`
}
PartView is one part as an application's page shows it (#2527): its name and the facts its description line is built from, never only its id. A part the caller cannot open, or one that is gone, carries its state and no name.
type Promoted ¶ added in v1.164.0
type Promoted struct {
From string `json:"from" example:"dev"`
To string `json:"to" example:"prod"`
Release int `json:"release" example:"8"`
// Replaced is the release the target ran before, 0 for none.
Replaced int `json:"replaced" example:"6"`
}
Promoted is what a promote did.
type RefusedError ¶
type RefusedError struct{ Msg string }
RefusedError is an operation refused for a reason the caller can act on.
func (*RefusedError) Error ¶
func (e *RefusedError) Error() string
type ReleaseOptions ¶ added in v1.163.0
type ReleaseOptions struct {
Note string
Action string
// MoveSites are site parts ("<site>/<environment>") this release moves one
// step besides the coupled ones; a rollback of the release returns them.
MoveSites []string
// Contract is the contract version the release declares; nil keeps the
// application's.
Contract *int
// Force releases over a site part whose release does not work with the
// contract; the release records each such part.
Force bool
}
ReleaseOptions is how a release is made.
type Roles ¶ added in v1.154.2
type Roles interface {
CreateRunRole(ctx context.Context, connection, schema string) (role, password string, err error)
GrantRunRole(ctx context.Context, connection, schema string) (string, error)
DropRunRole(ctx context.Context, connection, schema string) error
}
Roles creates, grants and drops an application's run role on its connection (#2539): the postgres toolkit.
type Schedules ¶ added in v1.154.1
type Schedules interface {
ListSchedules(ctx context.Context, filter script.ScheduleFilter) ([]script.Schedule, error)
}
Schedules reads a script's schedule; script.ErrScheduleNotFound for none.
type Schema ¶
type Schema interface {
State(ctx context.Context, connection, schema string) (*appschema.State, error)
Release(ctx context.Context, connection, schema, actor string) (*appschema.Applied, error)
Rollback(ctx context.Context, connection, schema, actor string, to int) (*appschema.Reverted, error)
}
Schema is what a release does to the application's schema.
type SchemaView ¶ added in v1.154.2
type SchemaView struct {
Connection string `json:"connection" example:"orders"`
Schema string `json:"schema" example:"shop"`
// MigrationVersion is the highest migration applied in the database;
// ReleasedVersion the one the current release recorded; Pending the
// versions a release would apply.
MigrationVersion int `json:"migration_version" example:"7"`
ReleasedVersion int `json:"released_version" example:"6"`
Pending []int `json:"pending"`
// AdoptedVersion is the version applied when the schema was added; a
// rollback reverts nothing at or below it.
AdoptedVersion int `json:"adopted_version" example:"0"`
// RunRole is the role the application's scripts log in as, empty when
// it has none; WriteRole the role it is granted, empty while the
// schema's migrations define none.
RunRole string `json:"run_role" example:"shop_run"`
WriteRole string `json:"write_role" example:"shop_write"`
// Note says what the run role still needs, empty when nothing.
Note string `json:"note,omitempty"`
// Problem says the migrations could not be read, empty when they were.
Problem string `json:"problem,omitempty"`
}
SchemaView is the schema part as an application's page and get show it (#2539): where its migrations stand, what the current release recorded, and the run role its scripts log in as.
type Scripts ¶
type Scripts interface {
GetByID(ctx context.Context, id string) (*script.Script, error)
GetVersion(ctx context.Context, scriptID string, version int) (*script.Version, error)
}
Scripts reads scripts and their versions.
type Sealer ¶ added in v1.154.2
type Sealer interface {
Enabled() bool
SealBound(binding, plaintext string) (string, error)
OpenBound(binding, sealed string) (string, error)
}
Sealer seals a run role's password for storage, bound to what it is the password of, and opens it again: the platform's field encryptor.
type Service ¶
type Service struct {
Store application.Store
Scripts Scripts
Assets Assets
AssetVersions portaldomain.VersionReader
Sources Sources
Schema Schema
// HasConnection reports whether an application database connection
// (kind appdb) is named so, one another replica saved a moment ago
// included (#2662); nil checks nothing.
HasConnection func(ctx context.Context, name string) bool
// Schedules, Activity and Lister describe parts and list the ones that
// may be added (#2527); nil leaves out what each reads.
Schedules Schedules
Activity SourceActivity
Lister CandidateLister
// Webhooks reads the webhook sources each script runs for (#2434); nil
// reads none.
Webhooks Webhooks
// Roles and Sealer create an application's run role when its schema is
// added and keep its password sealed (#2539); without both no schema is
// added. Reach lists the application database connections an actor may
// hold a schema on; Members reports whether a role is a member of
// another on a connection. Nil leaves out what each answers.
Roles Roles
Sealer Sealer
Reach func(ctx context.Context, actor application.Actor) ([]string, error)
Members func(ctx context.Context, connection, member, role string) bool
// Diagrams is what an application's diagram reads besides the stores
// above (#2540).
Diagrams DiagramDeps
// Sites reads a site part and points its environment at a release
// (#2518); nil adds no site.
Sites Sites
// Contracts reads what a site part serves and the contract a release
// declares (#2679); nil checks no contract.
Contracts ContractSites
// Environments keeps the applications' environments and variables
// (#2696); nil refuses every environment operation.
Environments application.EnvironmentStore
}
Service is the application operations.
func (*Service) AddEnvironment ¶ added in v1.164.0
func (s *Service) AddEnvironment(ctx context.Context, actor application.Actor, ref string, e application.Environment, after string) (*application.Application, error)
AddEnvironment adds an environment after the one named after ("" puts it first). It runs no release until one is promoted or released to it.
func (*Service) AddPart ¶
func (s *Service) AddPart(ctx context.Context, actor application.Actor, ref, kind, id string) (*application.Application, error)
AddPart adds a part the actor owns; a site part is linked.
func (*Service) AddPartMode ¶ added in v1.163.0
func (s *Service) AddPartMode(ctx context.Context, actor application.Actor, ref string, p application.Part) (*application.Application, error)
AddPartMode adds a part the actor owns, a site part with the release mode asked for, linked when none is (#2679).
func (*Service) Create ¶
func (s *Service) Create(ctx context.Context, actor application.Actor, a application.Application) (*application.Application, error)
Create makes an application owned by the actor.
func (*Service) Delete ¶
Delete removes an application; its parts stay and run their newest versions again.
func (*Service) DeleteVariable ¶ added in v1.164.0
func (s *Service) DeleteVariable(ctx context.Context, actor application.Actor, ref, env, name string) error
DeleteVariable removes NAME from env, "" for the default.
func (*Service) Describe ¶ added in v1.154.1
func (s *Service) Describe(ctx context.Context, actor application.Actor, parts []application.Part, view AssetViewer) []PartView
Describe reads each of an application's parts for the actor: a script (whose definition everyone signed in reads), an asset only when view says the caller opens it, and a webhook source by its name.
func (*Service) Diagram ¶ added in v1.154.2
func (s *Service) Diagram(ctx context.Context, actor application.Actor, req DiagramRequest) (*appdiagram.Diagram, error)
Diagram draws how an application's parts fit together (#2540). An asset the caller cannot open is drawn unnamed and its content is not read.
func (*Service) Find ¶
func (s *Service) Find(ctx context.Context, ref string) (*application.Application, error)
Find reads an application by id or name.
func (*Service) FindCandidates ¶ added in v1.154.1
func (s *Service) FindCandidates(ctx context.Context, actor application.Actor, ref, query, kind string) (*Candidates, error)
FindCandidates lists the parts the actor may add to an application whose name matches query, by the rules AddPart applies: their own scripts, assets and site environments (every one for an administrator) and, for an administrator, webhook sources. A part already in this application is left out; one in another application is listed with that application, which refuses it. kind narrows the list but not the counts.
func (*Service) FindingsIntroduced ¶ added in v1.154.2
FindingsIntroduced is what a save of the script scriptID, over version before, newly gives its application's diagram to find (#2540): the findings of the application's newest versions that the same application with the script at before does not have. Empty for a script that is part of no application.
func (*Service) Promote ¶ added in v1.164.0
func (s *Service) Promote(ctx context.Context, actor application.Actor, ref, from string) (*Promoted, error)
Promote makes the environment after from run from's release.
func (*Service) Release ¶
func (s *Service) Release(ctx context.Context, actor application.Actor, ref, note string) (*application.Release, error)
Release applies the application's pending migrations and pins every script and asset part at its newest version. A part that cannot be pinned, or a migration that fails, refuses the release and changes nothing.
func (*Service) ReleaseAs ¶
func (s *Service) ReleaseAs(ctx context.Context, actor application.Actor, ref, note, action string) (*application.Release, error)
ReleaseAs is Release recorded as action: an import's release is recorded as one.
func (*Service) ReleaseWith ¶ added in v1.163.0
func (s *Service) ReleaseWith(ctx context.Context, actor application.Actor, ref string, o ReleaseOptions) (*application.Release, error)
ReleaseWith is Release with the options #2679 adds.
func (*Service) RemoveEnvironment ¶ added in v1.164.0
func (s *Service) RemoveEnvironment(ctx context.Context, actor application.Actor, ref, env string) (*application.Application, error)
RemoveEnvironment removes an environment other than the last, with its variables.
func (*Service) RemovePart ¶
func (s *Service) RemovePart(ctx context.Context, actor application.Actor, ref, kind, id string) (*application.Application, error)
RemovePart removes a part; it runs or serves its newest version again.
func (*Service) Rollback ¶
func (s *Service) Rollback(ctx context.Context, actor application.Actor, ref string, to int) (*application.Release, error)
Rollback restores the pins of an earlier release — to, or the release before the current one when to is 0 — and reverts the migrations applied since when each has a down migration; the rollback records which it reverted, or why it reverted none.
func (*Service) RollbackIn ¶ added in v1.164.0
func (s *Service) RollbackIn(ctx context.Context, actor application.Actor, ref, env string, to int) (*application.Release, error)
RollbackIn moves one environment back to an earlier release: to, or the release before the one it runs when to is 0. In the last environment it is Rollback, recorded as a release; in any other it points the environment at the earlier release and records nothing new.
func (*Service) SchemaOf ¶ added in v1.154.2
func (s *Service) SchemaOf(ctx context.Context, a *application.Application, current *application.Release) *SchemaView
SchemaOf is the schema part's view, nil for an application with none.
func (*Service) SetContract ¶ added in v1.163.0
func (s *Service) SetContract(ctx context.Context, actor application.Actor, ref string, version int) (*application.Application, error)
SetContract sets the contract version the application declares (#2679): the owner or an administrator. A release checks it; setting it moves nothing.
func (*Service) SetEnvironmentApproval ¶ added in v1.164.0
func (s *Service) SetEnvironmentApproval(ctx context.Context, actor application.Actor, ref, env string, requires bool) (*application.Application, error)
SetEnvironmentApproval changes whether an agent's promote or rollback into env waits on a person.
func (*Service) SetPartMode ¶ added in v1.163.0
func (s *Service) SetPartMode(ctx context.Context, actor application.Actor, ref, id, mode string) (*application.Application, error)
SetPartMode changes a site environment part's release mode (#2679): the owner or an administrator. It moves nothing: the next release reads it.
func (*Service) SetVariable ¶ added in v1.164.0
func (s *Service) SetVariable(ctx context.Context, actor application.Actor, ref string, v application.Variable) error
SetVariable writes NAME=value in env, "" for the application-wide default. The next run reads it; no release is needed.
func (*Service) Update ¶
func (s *Service) Update(ctx context.Context, actor application.Actor, ref, description, owner string) (*application.Application, error)
Update writes the description and, for an administrator, the owner.
type SitePartView ¶ added in v1.163.0
type SitePartView struct {
PartID string `json:"part_id" example:"store-web/prod"`
Mode string `json:"release_mode" example:"linked"`
// Serves is the release the environment serves now, 0 for none.
Serves int `json:"serves" example:"22"`
// Step is the release a release moving it would point it at, 0 for none.
Step int `json:"step" example:"24"`
// Contract is the range the release it serves declares for this
// application, "" for none.
Contract string `json:"contract" example:">=2 <4"`
// Compatible is whether that release works with the application's
// contract.
Compatible bool `json:"compatible"`
}
SitePartView is one site part as the Parts card and the release dialog read it (#2679).
type Sites ¶ added in v1.155.0
type Sites interface {
// EnvironmentOwner is the owner of the site holding the environment.
EnvironmentOwner(ctx context.Context, site, environment string) (string, error)
// StepRelease is the release an application release pins a site
// environment at: what the environment before it serves, the newest
// release for dev (#2617).
StepRelease(ctx context.Context, site, environment string) (int, error)
ReleaseExists(ctx context.Context, site string, number int) bool
ApplyPin(ctx context.Context, actorEmail, site, environment string, number int) error
// SiteEnvironments is every environment of every site (#2613).
SiteEnvironments(ctx context.Context) ([]application.SiteEnvironment, error)
}
Sites is what an application does with its site parts.
type SourceActivity ¶ added in v1.154.1
type SourceActivity interface {
AcceptedSince(ctx context.Context, name string, since time.Time) (int64, error)
}
SourceActivity counts the requests a webhook source accepted since a time.
type Status ¶
type Status struct {
Application *application.Application `json:"application"`
Current *application.Release `json:"current_release"`
// Pending is the parts whose newest version differs from the current
// release's pin.
Pending []application.PinChange `json:"pending"`
// Migrations is where the schema's migrations stand; nil for an
// application with no schema.
Migrations *appschema.State `json:"migrations,omitempty"`
// Schema is the schema part (#2539): its migration version, the one the
// current release recorded, and its run role; nil for none.
Schema *SchemaView `json:"schema,omitempty"`
// Problems are parts a release would refuse (deleted, or unreadable),
// and what the application's diagram finds (#2540).
Problems []string `json:"problems"`
// Findings are the diagram's findings, each saying whether a release
// refuses it.
Findings []appdiagram.Finding `json:"findings"`
// SiteParts is each site part's mode, what it serves, where a release
// would move it and whether it works with the contract (#2679).
SiteParts []SitePartView `json:"site_parts"`
}
Status is where an application stands: its record, its current release, and what a release now would change.
type Webhooks ¶ added in v1.161.0
type Webhooks interface {
Handlers(ctx context.Context, filter scriptevents.HandlerFilter) ([]scriptevents.Handler, error)
}
Webhooks reads webhook handlers (scriptevents.PostgresStore).