appsvc

package
v1.156.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

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

View Source
const (
	DiagramCurrent = "current"
	DiagramLatest  = "latest"
)

The versions of an application a diagram is drawn at (#2540), besides a release's number.

View Source
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).

View Source
const MaxCandidates = 50

MaxCandidates bounds the candidates listed of each kind.

Variables

This section is empty.

Functions

func RunRoleBinding added in v1.154.2

func RunRoleBinding(applicationID, connection, schema, role string) string

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 Assets

type Assets interface {
	Get(ctx context.Context, id string) (*portaldomain.Asset, error)
}

Assets reads portal assets.

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

Create makes an application owned by the actor.

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, actor application.Actor, ref string) error

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

func (s *Service) FindingsIntroduced(ctx context.Context, scriptID string, before int) []string

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) StatusOf

func (s *Service) StatusOf(ctx context.Context, ref string) (*Status, error)

StatusOf reads where an application stands.

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 Sources

type Sources interface {
	Exists(ctx context.Context, name string) (bool, error)
}

Sources reports whether a webhook source exists.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL