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 RunRoleBinding(applicationID, connection, schema, role string) string
- type AppRef
- type AssetViewer
- type Assets
- type Candidate
- type CandidateLister
- type Candidates
- type DiagramDeps
- type DiagramRequest
- type PartSchedule
- type PartView
- type RefusedError
- type Roles
- type Schedules
- type Schema
- type SchemaView
- type Scripts
- type Sealer
- type Service
- func (s *Service) AddPart(ctx context.Context, actor application.Actor, ref, kind, id string) (*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) 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) 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) 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) SchemaOf(ctx context.Context, a *application.Application, current *application.Release) *SchemaView
- 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)
- type Sites
- type SourceActivity
- type Sources
- type Status
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 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 or webhook source 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 DiagramDeps ¶ added in v1.154.2
type DiagramDeps struct {
Binding func(ctx context.Context, scriptID string) (*appdiagram.Binding, error)
AssetContent func(ctx context.Context, assetID string, version int) string
SchemaWrites func(ctx context.Context, connection, schema string) []string
}
DiagramDeps is what the diagram reads besides the service's stores: a script's endpoint binding, 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"`
Schedule *PartSchedule `json:"schedule,omitempty"`
// EventSource is the webhook source a script runs for, empty for none.
EventSource string `json:"event_source,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 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 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 {
GetSchedule(ctx context.Context, scriptID string) (*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; nil checks nothing.
HasConnection func(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
// 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
}
Service is the application operations.
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.
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) 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 and assets (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) 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) 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) 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) 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 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)
LatestRelease(ctx context.Context, site string) (int, error)
ReleaseExists(ctx context.Context, site string, number int) bool
ApplyPin(ctx context.Context, actorEmail, site, environment string, number int) 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"`
}
Status is where an application stands: its record, its current release, and what a release now would change.