Documentation
¶
Overview ¶
Package wsbundle holds the format of a Miabi Portable Bundle: one workspace, its configuration, its secrets and its data, written to an S3 bucket as a self-describing set of objects.
It deliberately depends on nothing else in Miabi. A bundle is meant to be read by an instance that did not write it — a different install, a different ID space, a different encryption key — so its format must be expressible without the platform that produced it.
Index ¶
- Constants
- Variables
- func DatabasePath(prefix, ref string) string
- func EncodeInfo(i *Info) ([]byte, error)
- func InfoObject(prefix, ref string) string
- func IsRef(s string) bool
- func NewRef(workspace string, at time.Time) string
- func RefFromInfoObject(key string) string
- func Root(prefix, ref string) string
- func Seal(st *State, passphrase string) ([]byte, error)
- func Segment(s string) string
- func StateObject(prefix, ref string) string
- func ValidatePassphrase(pass string) error
- func VolumePath(prefix, ref string) string
- type Application
- type Artifact
- type Certificate
- type CronJob
- type DNSProvider
- type DatabaseInstance
- type Domain
- type EnvVar
- type Environment
- type GitRepository
- type GitSource
- type Info
- type LogicalDatabase
- type Member
- type Middleware
- type Mount
- type Network
- type Pipeline
- type Port
- type Registry
- type Route
- type Secret
- type Source
- type Stack
- type State
- type Volume
- type Workspace
Constants ¶
const ( // SubjectState is the sealed state file: the workspace's configuration and // its secrets. Exactly one per bundle, and the one artifact without which a // bundle restores nothing. SubjectState = "state" // SubjectDatabase is one logical database's dump. SubjectDatabase = "database" // SubjectVolume is one workspace volume's archive. SubjectVolume = "volume" )
Artifact subjects.
const InfoExt = ".xml"
const InfoNotice = "Miabi portable workspace bundle index. The state file beside it is encrypted with the backup passphrase."
InfoNotice is stamped into every info file, so whoever finds one in a bucket — months later, on another install, without this repository open — can tell what it is.
The file is deliberately readable: it is the index a restore consults before it has opened anything, and it is what lets an operator see what a bucket holds with nothing but an S3 client. It carries no secret — the workspace's own configuration and every secret it owns live in the sealed state file beside it, and the names here are already visible in the object keys.
const InfoSchema = 1
InfoSchema is the info file's version.
const RefPrefix = "mbwb_"
RefPrefix marks a workspace bundle. Restore matches on it, so a mistyped argument fails fast instead of listing a whole bucket.
const StateExt = ".mbws"
StateExt is the sealed state file's extension.
const StateSchema = 1
StateSchema is the state document's version. A restore refuses a schema it does not know rather than guessing at fields.
Variables ¶
var ( // ErrBadPassphrase means the state file did not authenticate: a wrong // passphrase, or a tampered file. The two are indistinguishable by design. ErrBadPassphrase = errors.New("bundle state did not decrypt: wrong passphrase or corrupt file") // ErrNotState means the bytes are not a sealed bundle state file at all. ErrNotState = errors.New("not a Miabi workspace bundle state file") // ErrWeakPassphrase is returned when a passphrase is too weak to protect a // workspace's entire vault. ErrWeakPassphrase = fmt.Errorf("backup passphrase must be at least %d characters and mix letters with digits or symbols", minPassLen) )
Functions ¶
func DatabasePath ¶
DatabasePath is where a bundle's database dumps live.
func EncodeInfo ¶
EncodeInfo renders an info file for upload.
It stamps the schema defensively, but callers should set it at construction: anything that validates before encoding sees a zero and rejects its own info file. Validate is deliberately not the thing that assigns it — a validator that repairs what it checks cannot report a genuine mismatch.
func InfoObject ¶
InfoObject is the info file's object key.
Unlike everything else it sits at the TOP of the configured prefix, not inside the bundle's branch: it is the one file an operator (or a restore with nothing but a bucket) is expected to find by looking, so listing the prefix lists the bundles rather than their contents.
func NewRef ¶
NewRef builds a bundle's stable name from the workspace it came from and the moment it started: "mbwb_shop_20260731T020000Z".
func RefFromInfoObject ¶
RefFromInfoObject recovers the ref from an info file's object key, or "". It is what lets a restore discover the bundles in a bucket with no database to list them from.
func Root ¶
Root is the object prefix every artifact of one bundle lives under: "<prefix>/<ref>". Keeping a bundle in its own branch is what lets a restore list one bundle's artifacts without reading every object in the bucket, and what lets an operator delete a bundle by removing a single prefix.
func Seal ¶
Seal encrypts a state document under a key derived from passphrase with Argon2id, returning the framed file. A fresh random salt and nonce are generated per call, so sealing the same state twice never produces the same bytes.
func StateObject ¶
StateObject is the sealed state file's object key. It sits inside the bundle's own branch, next to the data it describes.
func ValidatePassphrase ¶
ValidatePassphrase rejects passphrases too weak for the bundle. A bundle holds every secret the workspace owns, so the floor is enforced rather than suggested.
func VolumePath ¶
VolumePath is where a bundle's volume archives live.
Types ¶
type Application ¶
type Application struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
SourceType string `json:"source_type,omitempty"` // image | git
Icon string `json:"icon,omitempty"`
Image string `json:"image,omitempty"`
Tag string `json:"tag,omitempty"`
GitRepo string `json:"git_repo,omitempty"`
GitRef string `json:"git_ref,omitempty"`
BuildMethod string `json:"build_method,omitempty"`
Builder string `json:"builder,omitempty"`
Buildpacks []string `json:"buildpacks,omitempty"`
BuildEnv map[string]string `json:"build_env,omitempty"`
// Registry and GitRepository name the stored credentials this app uses.
Registry string `json:"registry,omitempty"`
GitRepository string `json:"git_repository,omitempty"`
Stack string `json:"stack,omitempty"`
Networks []string `json:"networks,omitempty"`
Command []string `json:"command,omitempty"`
Port int `json:"port,omitempty"`
Ports []Port `json:"ports,omitempty"`
Mounts []Mount `json:"mounts,omitempty"`
Env []EnvVar `json:"env,omitempty"`
MemoryBytes int64 `json:"memory_bytes,omitempty"`
NanoCPUs int64 `json:"nano_cpus,omitempty"`
GPUCount int `json:"gpu_count,omitempty"`
GPUKind string `json:"gpu_kind,omitempty"`
RestartPolicy string `json:"restart_policy,omitempty"`
ImagePullPolicy string `json:"image_pull_policy,omitempty"`
RuntimeKind string `json:"runtime_kind,omitempty"`
Replicas int `json:"replicas,omitempty"`
PlacementConstraints []string `json:"placement_constraints,omitempty"`
HealthcheckType string `json:"healthcheck_type,omitempty"`
HealthcheckHTTPPath string `json:"healthcheck_http_path,omitempty"`
HealthcheckPort int `json:"healthcheck_port,omitempty"`
HealthcheckCommand string `json:"healthcheck_command,omitempty"`
HealthcheckIntervalSeconds int `json:"healthcheck_interval_seconds,omitempty"`
HealthcheckTimeoutSeconds int `json:"healthcheck_timeout_seconds,omitempty"`
HealthcheckRetries int `json:"healthcheck_retries,omitempty"`
HealthcheckStartPeriodSeconds int `json:"healthcheck_start_period_seconds,omitempty"`
DeployStrategy string `json:"deploy_strategy,omitempty"`
ContainerLabels map[string]string `json:"container_labels,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
}
Application is a workload's full spec.
type Artifact ¶
type Artifact struct {
// Subject is "state", "database" or "volume".
Subject string `json:"subject" xml:"subject,attr"`
// Database is the logical database name a dump restores into
// (subject=database), and Instance the managed instance that hosts it.
Database string `json:"database,omitempty" xml:"database,omitempty"`
Instance string `json:"instance,omitempty" xml:"instance,omitempty"`
// Engine decides which restore tool can read a dump back.
Engine string `json:"engine,omitempty" xml:"engine,omitempty"`
// Volume is the workspace volume an archive restores into (subject=volume),
// by its Miabi name — never the Docker name, which the target mints itself.
Volume string `json:"volume,omitempty" xml:"volume,omitempty"`
// File is the artifact's name as the *-bkup tools record it, relative to Path.
File string `json:"file" xml:"file"`
// Path is the object prefix this artifact was written under. Recorded per
// artifact because a restore must find it again without re-deriving a layout;
// two implementations of one layout is how a restore ends up looking in a path
// nothing was ever written to.
Path string `json:"path,omitempty" xml:"path,omitempty"`
SizeBytes int64 `json:"size_bytes,omitempty" xml:"sizeBytes,omitempty"`
Encrypted bool `json:"encrypted,omitempty" xml:"encrypted,omitempty"`
// Error records why an artifact is missing from an otherwise complete bundle.
// A bundle that lists what it failed to capture is honest; one that silently
// omits it looks complete until the day it is needed.
Error string `json:"error,omitempty" xml:"error,omitempty"`
}
Artifact is one file in a bundle.
type Certificate ¶
type Certificate struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Source string `json:"source,omitempty"` // imported | acme
DNSNames []string `json:"dns_names,omitempty"`
// CertPEM and KeyPEM are the material, present only for an imported cert.
CertPEM string `json:"cert_pem,omitempty"`
KeyPEM string `json:"key_pem,omitempty"`
// DNSProvider and AutoRenew describe how a managed cert was issued, so the
// report can say what to re-issue and against which connection.
DNSProvider string `json:"dns_provider,omitempty"`
AutoRenew bool `json:"auto_renew,omitempty"`
}
Certificate is a TLS certificate the workspace owns.
Only uploaded certificates carry their material. A Miabi-issued (ACME) one carries its declaration and nothing else: its private key was minted for a host that, at restore time, still resolves to the source — reissuing is a cutover step, not an import step (see the restore report).
type CronJob ¶
type CronJob struct {
Name string `json:"name"`
App string `json:"app"`
Schedule string `json:"schedule"`
Command []string `json:"command,omitempty"`
Entrypoint []string `json:"entrypoint,omitempty"`
Image string `json:"image,omitempty"`
Registry string `json:"registry,omitempty"`
TimeoutSecs int `json:"timeout_secs,omitempty"`
Enabled bool `json:"enabled"`
ConcurrencyPolicy string `json:"concurrency_policy,omitempty"`
HistoryLimit int `json:"history_limit,omitempty"`
}
CronJob is a scheduled command in an application's runtime context. The schedule travels; the runs it produced do not.
type DNSProvider ¶
type DNSProvider struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Type string `json:"type"` // cloudflare | route53 | digitalocean
// Credentials is the provider's credential blob as JSON, the same shape the
// platform stores encrypted.
Credentials string `json:"credentials,omitempty"`
}
DNSProvider is a connection to a DNS host. Credentials travel because the thing they authorize — publishing an ownership TXT record, answering a DNS-01 challenge — is exactly what the target must do before a migrated domain serves anything.
type DatabaseInstance ¶
type DatabaseInstance struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Engine string `json:"engine"`
Version string `json:"version,omitempty"`
VolumeSize int64 `json:"volume_size_bytes,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
Databases []LogicalDatabase `json:"logical_databases,omitempty"`
}
DatabaseInstance is a managed database server and the logical databases on it.
Database credentials deliberately do NOT travel. Data crosses as a logical dump, which restores into a server the target initialized itself, with its own admin password and its own per-database user — so carrying the source's credentials would at best be dead weight and at worst the password-vs-data-dir trap, where a restored server refuses to start against data initialized under a different password. The apps that consume a database are re-injected with the target's connection on restore, which is why EnvPrefix and App do travel.
type Domain ¶
type Domain struct {
Name string `json:"name"`
TLSMode string `json:"tls_mode,omitempty"`
// DNSProvider names the connection that automates this domain's records, so
// the target can prove ownership without an operator pasting a TXT record.
DNSProvider string `json:"dns_provider,omitempty"`
Wildcard bool `json:"wildcard,omitempty"`
}
Domain is an owned hostname. Ownership is not carried: a domain is verified against DNS, and DNS on the target points wherever it points — so a restored domain starts unverified and re-proves itself.
type EnvVar ¶
type EnvVar struct {
Key string `json:"key"`
Value string `json:"value,omitempty"`
IsSecret bool `json:"is_secret,omitempty"`
}
EnvVar is one environment variable. Secret values are in plaintext here, inside the sealed file, because the target re-encrypts under its own key.
type Environment ¶
type Environment struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Description string `json:"description,omitempty"`
Rank int `json:"rank,omitempty"`
RequiredApprovals int `json:"required_approvals,omitempty"`
GitSource string `json:"gitops_source,omitempty"`
}
Environment is a promotion stage. Approvals recorded against releases do not travel — they are decisions made about a release on the platform that held it.
type GitRepository ¶
type GitRepository struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
URL string `json:"url"`
AuthType string `json:"auth_type,omitempty"`
Username string `json:"username,omitempty"`
Secret string `json:"secret,omitempty"`
}
GitRepository is a Git credential, so a git-source app still clones.
type GitSource ¶
type GitSource struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
RepoURL string `json:"repo_url"`
Ref string `json:"ref,omitempty"`
Path string `json:"path,omitempty"`
GitRepository string `json:"git_repository,omitempty"` // stored credential, by name
SyncPolicy string `json:"sync_policy,omitempty"` // manual | auto
Prune bool `json:"prune,omitempty"`
SelfHeal bool `json:"self_heal,omitempty"`
AllowEmpty bool `json:"allow_empty,omitempty"`
// LastSyncedCommit lets the target decide "already at HEAD" instead of
// redeploying everything on its first reconcile.
LastSyncedCommit string `json:"last_synced_commit,omitempty"`
}
GitSource is a GitOps connection: the repository of manifests, not a fork of it. The manifests are in Git — the source of truth — so what travels is how to reach it and how to reconcile it.
The webhook secret does not travel. It authenticates a webhook configured at the provider against one platform; carrying it would let the same push drive two installs, which is precisely what a migration is trying to stop doing.
type Info ¶
type Info struct {
XMLName xml.Name `json:"-" xml:"workspaceBundle"`
Notice string `json:"_notice" xml:"notice"`
Schema int `json:"schema" xml:"schema,attr"`
Ref string `json:"ref" xml:"ref,attr"`
// Workspace is the source workspace's handle — the natural key everything in
// the state file hangs off, and the default name a restore recreates it under.
Workspace string `json:"workspace" xml:"workspace"`
DisplayName string `json:"display_name,omitempty" xml:"displayName,omitempty"`
// SourceInstall identifies the install that produced the bundle. Informational:
// a bundle is portable by design, so a restore never requires a match.
SourceInstall string `json:"source_install,omitempty" xml:"sourceInstall,omitempty"`
MiabiVersion string `json:"miabi_version,omitempty" xml:"miabiVersion,omitempty"`
// Encrypted records that the state file (and, when the backup helpers support
// it, the data artifacts) are sealed with a passphrase.
Encrypted bool `json:"encrypted" xml:"encrypted"`
Bucket string `json:"bucket,omitempty" xml:"bucket,omitempty"`
// Prefix is the object prefix the bundle's own branch lives under.
Prefix string `json:"prefix,omitempty" xml:"prefix,omitempty"`
// Counts summarize the configuration carried in the sealed state file, which
// cannot be inspected without the passphrase. They are what makes a bucket
// listing informative rather than a list of opaque refs.
Apps int `json:"apps" xml:"apps,omitempty"`
Databases int `json:"databases" xml:"databases,omitempty"`
Volumes int `json:"volumes" xml:"volumes,omitempty"`
Secrets int `json:"secrets" xml:"secrets,omitempty"`
Routes int `json:"routes" xml:"routes,omitempty"`
// Certificates, Pipelines and GitOpsSources are counted separately because
// they are the classes an operator most often wants to confirm travelled
// before trusting a bundle as a migration rather than a data backup.
Certificates int `json:"certificates" xml:"certificates,omitempty"`
Pipelines int `json:"pipelines" xml:"pipelines,omitempty"`
GitOpsSources int `json:"gitops_sources" xml:"gitopsSources,omitempty"`
Artifacts []Artifact `json:"artifacts" xml:"artifacts>artifact"`
CreatedAt time.Time `json:"created_at" xml:"createdAt"`
}
Info is a bundle's self-description, written to the bucket in cleartext beside the sealed state file.
It exists so that a restore is possible with nothing but the bucket and the passphrase. The same facts live in the platform's database — and the platform that holds that database is precisely what a migration leaves behind.
func DecodeInfo ¶
DecodeInfo parses and validates an info file read from the bucket.
func (*Info) StateArtifact ¶
StateArtifact returns the sealed state file's artifact, or nil.
type LogicalDatabase ¶
type LogicalDatabase struct {
Name string `json:"name"`
EnvPrefix string `json:"env_prefix,omitempty"`
App string `json:"app,omitempty"` // owning application, by name
Metadata map[string]string `json:"metadata,omitempty"`
}
LogicalDatabase is one named database on an instance and the app it belongs to.
type Member ¶
type Member struct {
Email string `json:"email"`
Role string `json:"role"`
Owner bool `json:"owner,omitempty"`
}
Member is a workspace membership, by email. Users are instance-global: the target may know this person, or may not, and either way it authenticates them itself. Password hashes, sessions, 2FA secrets and token values never travel.
type Middleware ¶
type Middleware struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Type string `json:"type"`
Paths []string `json:"paths,omitempty"`
Rule map[string]any `json:"rule,omitempty"`
}
Middleware is a gateway middleware routes attach by name. Its rule may hold secret fields (a basicAuth password, a forwardAuth shared secret) — which is why, like everything else here, it only exists inside the sealed state file.
type Mount ¶
type Mount struct {
Volume string `json:"volume"`
Path string `json:"path"`
ReadOnly bool `json:"read_only,omitempty"`
}
Mount attaches a managed volume, by the volume's Miabi name. Privileged host-path binds are not carried: their source is an allow-listed preset on the node that granted it, and it may not exist — or may mean something else — on the target.
type Network ¶
type Network struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Driver string `json:"driver,omitempty"`
Internal bool `json:"internal,omitempty"`
}
Network is a workspace-owned Docker network. The Docker name is not carried: it is platform-managed and globally unique, so the target mints its own.
type Pipeline ¶
type Pipeline struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
App string `json:"app,omitempty"`
Spec string `json:"spec"`
Enabled bool `json:"enabled"`
// Source is manual or repo. A repo-owned spec is carried as it was last read,
// and the target re-reads it from the repository at the next run.
Source string `json:"source,omitempty"`
SourcePath string `json:"source_path,omitempty"`
SourceRef string `json:"source_ref,omitempty"`
}
Pipeline is a pipeline-as-code definition. Its runs, logs and built images stay behind: a run is a record of something that happened on the platform that ran it, and the definition is what reproduces it.
type Port ¶
type Port struct {
Container int `json:"container"`
Protocol string `json:"protocol,omitempty"`
Scheme string `json:"scheme,omitempty"`
Name string `json:"name,omitempty"`
}
Port is a container port the app exposes.
type Registry ¶
type Registry struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Server string `json:"server,omitempty"`
Username string `json:"username,omitempty"`
Secret string `json:"secret,omitempty"`
}
Registry is a container-registry credential (secret in plaintext, inside the sealed file), so a private-image app still pulls on the target.
type Route ¶
type Route struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
App string `json:"app"`
Hosts []string `json:"hosts,omitempty"`
Path string `json:"path,omitempty"`
Methods []string `json:"methods,omitempty"`
Middlewares []string `json:"middlewares,omitempty"`
Rewrite string `json:"rewrite,omitempty"`
TargetPort int `json:"target_port,omitempty"`
TLSMode string `json:"tls_mode,omitempty"`
// Certificate names the uploaded certificate a custom-TLS route serves, by
// its Miabi name.
Certificate string `json:"certificate,omitempty"`
Enabled bool `json:"enabled"`
}
Route is an HTTP routing rule bound to an app by name.
type Secret ¶
type Secret struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Description string `json:"description,omitempty"`
Value string `json:"value"`
Metadata map[string]string `json:"metadata,omitempty"`
}
Secret is one vault entry with its value.
type Source ¶
type Source struct {
InstallID string `json:"install_id,omitempty"`
MiabiVersion string `json:"miabi_version,omitempty"`
ExportedAt time.Time `json:"exported_at"`
}
Source is the bundle's provenance.
type Stack ¶
type Stack struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Description string `json:"description,omitempty"`
// Env is injected into every member application's containers. Secret values
// are in plaintext here, inside the sealed file, as everywhere else.
Env []EnvVar `json:"env,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
}
Stack groups applications and carries the environment shared by its members.
type State ¶
type State struct {
Schema int `json:"schema"`
// Source describes where the bundle came from, for the restore report. It is
// never required to match anything on the target.
Source Source `json:"source"`
Workspace Workspace `json:"workspace"`
Registries []Registry `json:"registries,omitempty"`
GitRepos []GitRepository `json:"git_repositories,omitempty"`
DNSProviders []DNSProvider `json:"dns_providers,omitempty"`
Networks []Network `json:"networks,omitempty"`
Secrets []Secret `json:"secrets,omitempty"`
Volumes []Volume `json:"volumes,omitempty"`
Stacks []Stack `json:"stacks,omitempty"`
Databases []DatabaseInstance `json:"databases,omitempty"`
Certificates []Certificate `json:"certificates,omitempty"`
Apps []Application `json:"apps,omitempty"`
CronJobs []CronJob `json:"cron_jobs,omitempty"`
Middlewares []Middleware `json:"middlewares,omitempty"`
Routes []Route `json:"routes,omitempty"`
Domains []Domain `json:"domains,omitempty"`
Environments []Environment `json:"environments,omitempty"`
Pipelines []Pipeline `json:"pipelines,omitempty"`
GitSources []GitSource `json:"gitops_sources,omitempty"`
Members []Member `json:"members,omitempty"`
}
State is a workspace's whole configuration, by natural key.
Nothing here carries a primary key. Across two installs a `uint` id is meaningless — app 42 on one is a different row (or nothing) on the other — so every reference is a name: an app names its stack, a mount names its volume, a route names its app. Restore rebuilds the graph from those names and mints its own ids.
It holds plaintext secrets, which is why it only ever exists inside the sealed state file (see Seal) and in memory.
type Volume ¶
type Volume struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
SizeBytes int64 `json:"size_bytes,omitempty"`
Driver string `json:"driver,omitempty"`
AccessMode string `json:"access_mode,omitempty"`
HostPath string `json:"host_path,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
}
Volume is a managed volume's declaration. Its contents travel separately, as a data artifact named after Name.
type Workspace ¶
type Workspace struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Description string `json:"description,omitempty"`
}
Workspace is the workspace record itself. Plan, quota and privilege are deliberately absent: they are the target platform's decisions about a tenant, not the tenant's own state, and a bundle that carried them would let an import grant itself capacity or privilege.