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 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
}
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 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.