Documentation
¶
Overview ¶
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.
A bundle carries no secret value, credential, data row, script state or run history: export reads none of them. It reads a script version's source, a migration's SQL and an asset's content, which are what the application is made of; a migration carrying a literal password is refused at export as it is when it is added (#2411).
Index ¶
- Constants
- type AppInfo
- type Asset
- type Bundle
- type Bundler
- func (b *Bundler) Build(ctx context.Context, ref string, release int) (*Bundle, error)
- func (b *Bundler) Bundle(ctx context.Context, actor application.Actor, ref string, release int) (*Bundle, error)
- func (b *Bundler) Export(ctx context.Context, actor application.Actor, ref string, release int) (any, error)
- func (b *Bundler) Import(ctx context.Context, actor application.Actor, ref string, ...) (any, error)
- func (b *Bundler) ImportBundle(ctx context.Context, actor application.Actor, bundle *Bundle, ...) (*Imported, error)
- type Deps
- type Endpoint
- type Exported
- type Imported
- type Migration
- type Names
- type Recording
- type SaveGate
- type Schedule
- type Schema
- type Script
Constants ¶
const ( Format = "mcp-data-platform.application" FormatVersion = 1 )
Format identifies a bundle.
const MaxBytes = 64 << 20
MaxBytes bounds a bundle.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Asset ¶
type Asset struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
ContentType string `json:"content_type"`
Tags []string `json:"tags"`
Version int `json:"version"`
Content []byte `json:"content"`
}
Asset is one asset at its pinned version.
type Bundle ¶
type Bundle struct {
Format string `json:"format"`
FormatVersion int `json:"format_version"`
Application AppInfo `json:"application"`
Release int `json:"release"`
Note string `json:"note,omitempty"`
ExportedAt time.Time `json:"exported_at"`
Schema *Schema `json:"schema,omitempty"`
Scripts []Script `json:"scripts"`
Assets []Asset `json:"assets"`
// Sources is the webhook sources that are parts of the application, by
// name; each is mapped to one on the importing deployment.
Sources []string `json:"sources"`
Names Names `json:"names"`
}
Bundle is one exported release.
type Bundler ¶
type Bundler struct{ Deps }
Bundler exports and imports applications.
func (*Bundler) Bundle ¶
func (b *Bundler) Bundle(ctx context.Context, actor application.Actor, ref string, release int) (*Bundle, error)
Bundle assembles the bundle of a release for an administrator, without writing it: the portal hands it to the browser as a download.
func (*Bundler) Export ¶
func (b *Bundler) Export(ctx context.Context, actor application.Actor, ref string, release int) (any, error)
Export writes a release of an application as a bundle in the caller's library. release 0 is the current release.
func (*Bundler) Import ¶
func (b *Bundler) Import(ctx context.Context, actor application.Actor, ref string, mapping map[string]string) (any, error)
Import reads a bundle from a managed resource, maps every name it uses to mapping's name on this deployment, creates the application or finds the one with its name, writes each part, and releases it. A name left unmapped refuses the import before anything is written.
type Deps ¶
type Deps struct {
Service *appsvc.Service
Migrations interface {
List(ctx context.Context, connection, schema string) ([]postgreskit.Migration, error)
Put(ctx context.Context, m postgreskit.Migration) (bool, error)
}
Bindings interface {
Get(ctx context.Context, scriptID string) (*epbinding.Binding, error)
}
Schedules interface {
GetSchedule(ctx context.Context, scriptID string) (*script.Schedule, error)
SetSchedule(ctx context.Context, sched *script.Schedule) error
}
// FormConnection is the connection a form's webhook source is on.
FormConnection func(ctx context.Context, sourceName string) (string, error)
Blobs interface {
GetObject(ctx context.Context, bucket, key string) ([]byte, string, error)
PutObject(ctx context.Context, bucket, key string, data []byte, contentType string) error
}
Lander interface {
LandResource(ctx context.Context, dest toolkit.ResourceDestination, content io.Reader, contentType string) (*toolkit.ResourceLanding, error)
}
Reader interface {
Source(ctx context.Context, ref string, claims resource.Claims, limit int64) (string, error)
}
Claims func(ctx context.Context) resource.Claims
Scripts interface {
Create(ctx context.Context, sc *script.Script, author script.Author) error
UpdateWithVersion(ctx context.Context, sc *script.Script, author script.Author) error
}
Assets interface {
Insert(ctx context.Context, asset portaldomain.Asset) error
}
AssetVersions interface {
CreateVersion(ctx context.Context, version portaldomain.AssetVersion) (int, error)
}
Bucket, Prefix string
// Endpoints carries out an endpoint command, as manage_script does.
Endpoints func(ctx context.Context, req epcmd.Request) (map[string]any, error)
// HasSchemaConnection reports whether an application database
// connection is configured here.
HasSchemaConnection func(name string) bool
// Recordings is where the recorded runs a script's tests replay are read
// from on export and stored on import (#2476). Nil exports and imports
// none: a script whose tests name one is refused.
Recordings interface {
Get(ctx context.Context, runID string) (*scriptrec.Stored, error)
Save(ctx context.Context, rec scriptrec.Stored) error
Keep(ctx context.Context, scriptID, author string, runIDs []string) error
}
// SaveGate is the gate every save of a script's source crosses
// (internal/platform/scriptsave): an imported script is put through it as
// the importing administrator before anything is written (#2476). Nil
// refuses an import that holds a script.
SaveGate SaveGate
}
Deps is what export and import use.
type Endpoint ¶
type Endpoint struct {
Name string `json:"name"`
Methods []string `json:"methods"`
Path string `json:"path"`
AuthMode string `json:"auth_mode"`
Callers []string `json:"callers"`
BotCheck string `json:"bot_check,omitempty"`
CheckedMethods []string `json:"checked_methods"`
TimeoutSeconds int `json:"timeout_seconds,omitempty"`
MaxMemoryBytes int64 `json:"max_memory_bytes,omitempty"`
MaxBodyBytes int `json:"max_body_bytes,omitempty"`
AllowedOrigins []string `json:"allowed_origins"`
RateLimit int `json:"rate_limit,omitempty"`
CallerRateLimit int `json:"caller_rate_limit,omitempty"`
Enabled bool `json:"enabled"`
// ResponseMode and PageCDNs make the endpoint a browser page (#2517).
ResponseMode string `json:"response_mode,omitempty"`
PageCDNs []string `json:"page_cdns,omitempty"`
// FormConnection is the connection a form's submissions table is on.
FormConnection string `json:"form_connection,omitempty"`
}
Endpoint is a script's endpoint binding.
type Exported ¶
type Exported struct {
Application string `json:"application"`
Release int `json:"release"`
Bundle *toolkit.ResourceLanding `json:"bundle"`
Names Names `json:"names"`
Scripts int `json:"scripts"`
Assets int `json:"assets"`
Migrations int `json:"migrations"`
// Notes are what the importer should know: a script whose connections a
// static read cannot all see.
Notes []string `json:"notes"`
}
Exported is what an export reports.
type Imported ¶
type Imported struct {
Application string `json:"application"`
Created bool `json:"created"`
Release *application.Release `json:"release"`
// Scripts and Assets name each part and whether the import created it,
// gave it a new version, or found it unchanged.
Scripts map[string]string `json:"scripts"`
Assets map[string]string `json:"assets"`
}
Imported is what an import reports.
type Migration ¶
type Migration struct {
Version int `json:"version"`
Name string `json:"name"`
Up string `json:"up"`
Down string `json:"down,omitempty"`
Transactional bool `json:"transactional"`
}
Migration is one migration as the release holds it.
type Names ¶
type Names struct {
Connections []string `json:"connections"`
Secrets []string `json:"secrets"`
Sources []string `json:"sources"`
BotChecks []string `json:"bot_checks"`
}
Names is every name of the source deployment the bundle uses, which an import maps to names on its own.
type Recording ¶
type Recording struct {
RunID string `json:"run_id"`
Data []byte `json:"data" swaggertype:"string" format:"byte"`
}
Recording is one recorded run a script's tests replay: its run id, as the tests name it, and the recording as the platform writes it (gzipped JSON lines, base64 in the bundle). It holds the answers the run's calls were given; a secret is kept only as its {{secret:name}} placeholder.
type SaveGate ¶
type SaveGate interface {
Check(ctx context.Context, req scriptsave.Request) scriptsave.Result
}
SaveGate checks one script source save; *scriptsave.Gate is one.
type Schedule ¶
type Schedule struct {
CronSpec string `json:"cron_spec"`
Timezone string `json:"timezone"`
Params map[string]any `json:"params,omitempty"`
Enabled bool `json:"enabled"`
}
Schedule is a script's schedule.
type Schema ¶
type Schema struct {
Connection string `json:"connection"`
Schema string `json:"schema"`
Migrations []Migration `json:"migrations"`
}
Schema is the application database schema and its migrations up to the release.
type Script ¶
type Script struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Description string `json:"description,omitempty"`
Category string `json:"category,omitempty"`
Tags []string `json:"tags"`
Source string `json:"source"`
Params []script.Param `json:"params"`
Exclusive string `json:"exclusive,omitempty"`
EventSource string `json:"event_source,omitempty"`
Version int `json:"version"`
Endpoint *Endpoint `json:"endpoint,omitempty"`
Schedule *Schedule `json:"schedule,omitempty"`
// DynamicConnections is set when the source names a connection in a way
// a static read cannot see; those names are not in Names.
DynamicConnections bool `json:"dynamic_connections,omitempty"`
// Recordings are the recorded runs the source's tests replay, so the
// importing deployment's save gate runs the same tests (#2476).
Recordings []Recording `json:"recordings,omitempty"`
}
Script is one script at its pinned version.