application

package
v1.163.0 Latest Latest
Warning

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

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

Documentation

Overview

Package application is the record of an application built on the platform (#2411): one name for everything a bespoke system is made of — an application database schema with its migrations, managed scripts (an endpoint or a form is its script's binding), webhook sources and the portal assets that are its user interface — and its releases, each of which pins the migration version and every script's and asset's version.

While a script or an asset belongs to a released application, the version its application's current release pins is the one a run executes and the portal serves; saving it changes nothing live until the next release. A part belongs to at most one application.

An application has one owner. Everyone signed in reads it; its owner and administrators edit its record and its parts; administrators release, roll back, export and import, because a release changes the code behind a public endpoint and runs migrations on the target database.

Index

Constants

View Source
const (
	KindScript = "script"
	KindAsset  = "asset"
	KindSource = "source"
	// KindSchema is the application database schema the application holds
	// (#2539), at most one, identified as "<connection>/<schema>". Its
	// migrations are applied by releases; it is not pinned, since a release
	// records the migration version instead.
	KindSchema = "schema"
	// KindSite is one environment of a static site (#2518), identified as
	// "<site>/<environment>". A release pins the site's newest release number
	// and points the environment at it.
	KindSite = "site"
)

The kinds of part.

View Source
const (
	ActionRelease  = "release"
	ActionRollback = "rollback"
	ActionImport   = "import"
)

The actions a release row records.

View Source
const (
	ModeLinked  = "linked"
	ModeCoupled = "coupled"
)

The release modes a site environment part takes (#2679).

View Source
const MaxDescription = 2000

MaxDescription bounds the description.

Variables

View Source
var (
	ErrNotFound   = errors.New("application not found")
	ErrNameTaken  = errors.New("an application with that name exists")
	ErrSchemaHeld = errors.New("another application holds that schema")
	ErrPartTaken  = errors.New("the part belongs to another application")
	ErrNoPart     = errors.New("the application has no such part")
	ErrNotAllowed = errors.New("not allowed")
	ErrNoRelease  = errors.New("the application has no such release")
	// ErrStale is a release recorded against a current release another
	// release has since moved.
	ErrStale = errors.New("another release of the application was recorded first")
)

Errors a caller reads by identity.

View Source
var ErrNoRunRole = errors.New("the application has no run role")

ErrNoRunRole is an application holding no run role.

Kinds is every kind of part, in the order a listing shows them.

Functions

func ParseSchemaPartID added in v1.154.2

func ParseSchemaPartID(id string) (connection, schema string)

ParseSchemaPartID reads a schema part's id: "<connection>/<schema>", or the schema alone, which leaves connection empty for the caller to choose.

func ParseSitePartID added in v1.155.0

func ParseSitePartID(id string) (siteName, environment string, ok bool)

ParseSitePartID reads a site part's id: "<site>/<environment>".

func SchemaPartID added in v1.154.2

func SchemaPartID(connection, schema string) string

SchemaPartID is the id the schema part goes by: "<connection>/<schema>".

func SitePartID added in v1.159.0

func SitePartID(siteName, environment string) string

SitePartID is a site part's id, the form ParseSitePartID reads.

func ValidKind

func ValidKind(kind string) bool

ValidKind reports whether kind names a kind of part.

func ValidMode added in v1.163.0

func ValidMode(mode string) bool

ValidMode reports whether mode is a site part's release mode.

Types

type Actor

type Actor struct {
	Email   string
	Admin   bool
	Subject string
	Roles   []string
}

Actor is who acts on an application. Subject and Roles are the session's identity and authority, which a part an import writes runs under: they come from the caller's own session, MCP or portal alike.

type Application

type Application struct {
	ID          string `json:"id" example:"app_01J9..."`
	Name        string `json:"name" example:"shop"`
	Description string `json:"description" example:"The storefront, its API and its orders"`
	OwnerEmail  string `json:"owner_email" example:"jane@example.com"`
	// Connection and Schema are the application database schema whose
	// migrations a release applies. Empty for an application with none.
	Connection string `json:"connection" example:"orders"`
	Schema     string `json:"schema" example:"shop"`
	// SchemaAdoptedVersion is the migration version the schema had applied
	// when it was added to the application (#2539): migrations no release
	// applied, which a rollback never reverts.
	SchemaAdoptedVersion int `json:"schema_adopted_version" example:"0"`
	// CurrentRelease is the number of the release in force, 0 before the
	// first.
	CurrentRelease int `json:"current_release" example:"3"`
	// ContractVersion is the contract its front ends call (#2679), raised by
	// hand when a release breaks it; 0 declares none, and every front end is
	// compatible.
	ContractVersion int       `json:"contract_version" example:"3"`
	CreatedBy       string    `json:"created_by" example:"jane@example.com"`
	CreatedAt       time.Time `json:"created_at"`
	UpdatedAt       time.Time `json:"updated_at"`
	Parts           []Part    `json:"parts"`
}

Application is the record.

func (*Application) MayEdit

func (a *Application) MayEdit(actor Actor) bool

MayEdit reports whether the actor edits the application's record and parts: its owner or an administrator.

func (*Application) Validate

func (a *Application) Validate() error

Validate checks the record's own fields.

type Changes

type Changes struct {
	Parts []PinChange `json:"parts"`
	// Applied and Reverted are the migration versions the release applied or
	// reverted, in the order it ran them.
	Applied  []int `json:"applied"`
	Reverted []int `json:"reverted"`
	// MigrationsKept says why a rollback left migrations applied: a
	// migration between the two releases has no down migration.
	MigrationsKept string `json:"migrations_kept,omitempty"`
	// Findings are what the application's diagram found at the release that
	// did not refuse it (#2540).
	Findings []string `json:"findings,omitempty"`
	// Forced is each site part an administrator released over though its
	// release does not work with the contract (#2679).
	Forced []string `json:"forced,omitempty"`
}

Changes is what a release did.

type HeldSchema added in v1.154.2

type HeldSchema struct {
	Connection     string
	Schema         string
	AdoptedVersion int
	AddedBy        string
	Role           string
	SealedPassword string
}

HeldSchema is a schema an application takes on: where it is, the migration version it had applied, who added it, and the run role its scripts' statements log in as, with the role's password sealed.

type Part

type Part struct {
	Kind string `json:"kind" example:"script"`
	// ID is the script's id, the asset's id, or the webhook source's name.
	ID      string    `json:"id" example:"5b0c..."`
	AddedBy string    `json:"added_by" example:"jane@example.com"`
	AddedAt time.Time `json:"added_at"`
	// ReleaseMode is a site environment part's (#2679): linked, served as a
	// front end of the application and moved only by promote and rollback,
	// or coupled, moved one step by every application release and returned
	// by every rollback. "" for every other kind.
	ReleaseMode string `json:"release_mode,omitempty" example:"linked"`
}

Part is one member of an application.

type Pin

type Pin struct {
	Kind    string `json:"kind" example:"script"`
	PartID  string `json:"part_id" example:"5b0c..."`
	Version int    `json:"version" example:"4"`
}

Pin is the version a release holds a script or an asset at.

type PinChange

type PinChange struct {
	Kind   string `json:"kind"`
	PartID string `json:"part_id"`
	From   int    `json:"from"`
	To     int    `json:"to"`
}

PinChange is a part whose pinned version a release moved. From is 0 for a part the previous release did not pin; To is 0 for one this release does not.

func Diff

func Diff(prev, next []Pin) []PinChange

Diff is the pins that move from prev to next, in next's order and then prev's pins that next drops.

type Recorded

type Recorded struct {
	Release Release
	// After is the current release the release was decided against; the
	// record fails with ErrStale when another release moved it.
	After int
}

Recorded is a release to record: the row, its pins, and the current release it was decided against.

type Release

type Release struct {
	Number int    `json:"number" example:"3"`
	Action string `json:"action" example:"release"`
	// MigrationVersion is the highest migration the release holds applied.
	MigrationVersion int `json:"migration_version" example:"7"`
	// Restored is the release a rollback restored the pins of.
	Restored  int       `json:"restored,omitempty" example:"2"`
	Changes   Changes   `json:"changes"`
	Note      string    `json:"note,omitempty"`
	CreatedBy string    `json:"created_by" example:"admin@example.com"`
	CreatedAt time.Time `json:"created_at"`
	Pins      []Pin     `json:"pins"`
}

Release is one release row and its pins.

func (*Release) PinOf

func (r *Release) PinOf(kind, id string) int

PinOf is the version the release pins the part at, 0 for none.

type RunRole added in v1.154.2

type RunRole struct {
	ApplicationID  string
	Connection     string
	Schema         string
	Role           string
	SealedPassword string
}

RunRole is an application's run role as stored: the role, and its password sealed.

type SiteEnvironment added in v1.159.0

type SiteEnvironment struct {
	Site        string
	Environment string
	Owner       string
	UpdatedAt   time.Time
}

SiteEnvironment is one environment of a site, as the search for parts to add lists it (#2613).

type Store

type Store interface {
	Create(ctx context.Context, a *Application) error
	Get(ctx context.Context, id string) (*Application, error)
	GetByName(ctx context.Context, name string) (*Application, error)
	List(ctx context.Context) ([]Application, error)
	// Update writes the description and owner.
	Update(ctx context.Context, a *Application) error
	// Delete removes the application, its parts and releases, and clears the
	// released version its parts were held at.
	Delete(ctx context.Context, id string) error
	AddPart(ctx context.Context, applicationID string, p Part) error
	// SetPartMode changes a site environment part's release mode (#2679).
	SetPartMode(ctx context.Context, applicationID, id, mode string) error
	// RemovePart removes the part and clears the released version it was
	// held at.
	RemovePart(ctx context.Context, applicationID, kind, id string) error
	// Owning is the application a part belongs to, ErrNotFound for none.
	Owning(ctx context.Context, kind, id string) (*Application, error)
	// SetSchema makes the application hold a schema and stores its run role,
	// in one transaction: ErrSchemaHeld when another application holds it.
	SetSchema(ctx context.Context, applicationID string, h HeldSchema) error
	// SetRunRole stores the run role of the schema the application holds.
	SetRunRole(ctx context.Context, applicationID string, h HeldSchema) error
	// ClearSchema takes the schema and its run role off the application.
	ClearSchema(ctx context.Context, applicationID string) error
	// Holding is the application holding schema on connection, ErrNotFound
	// for none.
	Holding(ctx context.Context, connection, schema string) (*Application, error)
	// RunRoleOf is the application's run role, ErrNoRunRole for none.
	RunRoleOf(ctx context.Context, applicationID string) (*RunRole, error)
	Releases(ctx context.Context, applicationID string) ([]Release, error)
	Release(ctx context.Context, applicationID string, number int) (*Release, error)
	// Record writes a release and its pins, makes it current, and holds each
	// pinned part at its version, in one transaction.
	Record(ctx context.Context, applicationID string, r Recorded) (*Release, error)
}

Store keeps applications, their parts and their releases.

Directories

Path Synopsis
Package appbundle moves an application between deployments (#2412): export writes one release as a bundle, a JSON managed resource holding the release's migrations, script versions with their endpoint bindings and schedules, and asset versions, with the connections, secrets, webhook sources and bot checks they use named; import reads a bundle, maps every name to one on this deployment, and creates or releases the application.
Package appbundle moves an application between deployments (#2412): export writes one release as a bundle, a JSON managed resource holding the release's migrations, script versions with their endpoint bindings and schedules, and asset versions, with the connections, secrets, webhook sources and bot checks they use named; import reads a bundle, maps every name to one on this deployment, and creates or releases the application.
Package appdiagram derives how an application's parts fit together (#2540): which webhook source starts which script, which script reads and writes which table, loads which library, writes which asset or notifies which channel, which asset calls which endpoint or embeds which form, and what the parts reach outside the application.
Package appdiagram derives how an application's parts fit together (#2540): which webhook source starts which script, which script reads and writes which table, loads which library, writes which asset or notifies which channel, which asset calls which endpoint or embeds which form, and what the parts reach outside the application.
Package apphttp serves applications on the portal (#2411, #2412): the listing, an application's parts, releases and what each changed, and the actions the manage_application tool takes, through the same service and under the same rules.
Package apphttp serves applications on the portal (#2411, #2412): the listing, an application's parts, releases and what each changed, and the actions the manage_application tool takes, through the same service and under the same rules.
Package apprunrole answers what the application database toolkit asks about the applications holding its schemas (#2539): which application holds a schema, and an application's run role with its password, opened from the sealed value the platform stored when the schema was added, for the pool the toolkit builds and nowhere else.
Package apprunrole answers what the application database toolkit asks about the applications holding its schemas (#2539): which application holds a schema, and an application's run role with its password, opened from the sealed value the platform stored when the schema was added, for the pool the toolkit builds and nowhere else.
Package appschema is what an application's release does to its application database schema (#2411): apply the pending migrations so that a release with a failing migration changes nothing, and revert to an earlier release's migration version when every migration between has a down migration.
Package appschema is what an application's release does to its application database schema (#2411): apply the pending migrations so that a release with a failing migration changes nothing, and revert to an earlier release's migration version when every migration between has a down migration.
Package appstore is the PostgreSQL store of applications, their parts and their releases (#2411): the tables of migration 000228, and the released_version columns it adds to scripts and portal_assets, which only this store writes.
Package appstore is the PostgreSQL store of applications, their parts and their releases (#2411): the tables of migration 000228, and the released_version columns it adds to scripts and portal_assets, which only this store writes.
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.
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.
Package apptool is the manage_application MCP tool (#2411, #2412): an application's record, parts, releases, rollbacks, and its export and import between deployments, over the one service the portal routes use.
Package apptool is the manage_application MCP tool (#2411, #2412): an application's record, parts, releases, rollbacks, and its export and import between deployments, over the one service the portal routes use.
Package appwire assembles applications (#2411, #2412) from the platform's stores: the service the manage_application tool and the portal routes share, over the application store, the script and asset stores, the webhook sources and the live application database toolkit, and the bundler that exports and imports them.
Package appwire assembles applications (#2411, #2412) from the platform's stores: the service the manage_application tool and the portal routes share, over the application store, the script and asset stores, the webhook sources and the live application database toolkit, and the bundler that exports and imports them.

Jump to

Keyboard shortcuts

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