Documentation
¶
Overview ¶
Package dr holds the disaster-recovery primitives shared by the running platform and the host-side `miabi restore`: the sealed identity envelope and the naming of a recovery point's artifacts. It depends on nothing else in Miabi — the restore path runs on a bare host.
Index ¶
- Constants
- Variables
- func EncodeManifest(m *Manifest) ([]byte, error)
- func IdentityObject(prefix, ref string) string
- func IsRef(s string) bool
- func ManifestObject(rootPrefix, ref string) string
- func NewRef(installID string, at time.Time) string
- func RefFromIdentityObject(key string) string
- func RefFromManifestObject(key string) string
- func Seal(id *Identity, passphrase string) ([]byte, error)
- func TenantPath(base, workspace string) string
- func ValidatePassphrase(pass string) error
- type Artifact
- type Identity
- type Manifest
Examples ¶
Constants ¶
const ( SubjectDatabase = "database" SubjectVolume = "volume" SubjectIdentity = "identity" SubjectTenantDatabase = "tenant-database" SubjectTenantVolume = "tenant-volume" )
Artifact subjects, mirroring models.PlatformBackupSubject.
const IdentityExt = ".mbid"
IdentityExt is the sealed identity envelope's file extension.
const IdentitySchema = 1
IdentitySchema is the envelope payload version. Restore refuses a schema it does not know rather than guessing at fields.
const ManifestExt = ".xml"
ManifestExt is the info file's extension. XML, and only XML: it is written for people and tooling outside Miabi to read, and one format means one thing to find in a bucket rather than two to look for.
const ManifestNotice = "Miabi recovery point index."
ManifestNotice is stamped into every info file so whoever finds one in a bucket knows what it is. The file is deliberately readable: it is the index a restore consults before it has a database. It carries no key, credential or passphrase.
const ManifestSchema = 1
ManifestSchema is the manifest's version.
const RefPrefix = "mbdr_"
RefPrefix marks a platform recovery point. Restore matches on it so a mistyped argument fails fast instead of listing a whole bucket.
const TenantSegment = "tenants"
TenantSegment is the branch tenant artifacts live under, below the database or volume prefix: "<prefix>/tenants/<workspace>".
Variables ¶
var ( // ErrBadPassphrase means the envelope did not authenticate: a wrong // passphrase, or a tampered file. The two are indistinguishable by design. ErrBadPassphrase = errors.New("identity envelope did not decrypt: wrong passphrase or corrupt file") // ErrNotEnvelope means the bytes are not an identity envelope at all. ErrNotEnvelope = errors.New("not a Miabi identity envelope") // ErrWeakPassphrase is returned when a passphrase is too weak to protect the // most sensitive artifact the platform produces. ErrWeakPassphrase = fmt.Errorf("backup passphrase must be at least %d characters and mix letters with digits or symbols", minPassLen) )
Functions ¶
func EncodeManifest ¶
EncodeManifest renders a manifest for upload. It stamps the schema defensively, but callers should set it at construction: anything that validates before encoding sees a zero. Validate deliberately does not assign it — a validator that repairs what it checks cannot report a mismatch.
Example ¶
ExampleEncodeManifest shows the info file an operator finds in the bucket: XML, readable, and stating in the file itself why it is not encrypted.
ref := NewRef("mbi_demo", time.Unix(1_760_000_000, 0).UTC())
m := &Manifest{
Schema: ManifestSchema, Ref: ref,
InstallID: "mbi_demo", MiabiVersion: "1.7.3", KEKFingerprint: "mrt_abc",
Encrypted: true, IdentitySealed: true, Prefix: "prod/databases",
Artifacts: []Artifact{{Subject: SubjectDatabase, File: "miabi_2026.sql.gz.gpg", Encrypted: true}},
CreatedAt: time.Unix(1_760_000_000, 0).UTC(),
}
body, err := EncodeManifest(m)
if err != nil {
panic(err)
}
fmt.Println(ManifestObject("prod", ref))
fmt.Println(string(body)[:38])
Output: prod/recovery-mbdr_mbi_demo_20251009T085320Z.xml <?xml version="1.0" encoding="UTF-8"?>
func IdentityObject ¶
IdentityObject is the identity envelope's object name within a bucket prefix. It sits beside the artifacts of its own set, named for it, so an operator listing a bucket can see which envelope belongs to which recovery point.
func ManifestObject ¶
ManifestObject is the info file's object name within the backup ROOT prefix, not under the database or volume paths. It is the one file an operator is expected to find by looking, so it sits at the top of the tree rather than inside one of its branches.
func NewRef ¶
NewRef builds a recovery point's stable name from the install it came from and the moment it started: "mbdr_<install-id>_20260731T020000Z".
func RefFromIdentityObject ¶
RefFromIdentityObject recovers the ref from an identity object key, or "" when the key is not one. Lets `miabi restore` discover recovery points in a bucket without a database to list them from.
func RefFromManifestObject ¶
RefFromManifestObject recovers the ref from an info file's object key, or "".
func Seal ¶
Seal encrypts the identity under a key derived from passphrase with Argon2id, returning the framed envelope. A fresh random salt and nonce are generated per call, so sealing the same identity twice never produces the same bytes.
func TenantPath ¶
TenantPath is the object prefix for one workspace's artifacts of a kind. It lives next to the manifest because the backup writes it and the restore has to find it again: two implementations of the same layout is how a restore ends up searching a path nothing was written to.
func ValidatePassphrase ¶
ValidatePassphrase rejects passphrases too weak for the envelope. This is the one artifact whose compromise hands over the whole platform, so the floor is enforced rather than suggested.
Types ¶
type Artifact ¶
type Artifact struct {
// Subject is "database", "volume", "identity", "tenant-database" or
// "tenant-volume".
Subject string `json:"subject" xml:"subject,attr"`
// Volume is the Docker volume an archive restores into (subject=volume).
Volume string `json:"volume,omitempty" xml:"volume,omitempty"`
// Workspace is the owning workspace slug for tenant artifacts.
Workspace string `json:"workspace,omitempty" xml:"workspace,omitempty"`
// Database is the logical database name for tenant database artifacts.
Database string `json:"database,omitempty" xml:"database,omitempty"`
// Engine is the tenant database engine (postgres, mysql, …), which decides
// which restore tool can read the dump back.
Engine string `json:"engine,omitempty" xml:"engine,omitempty"`
// File is the artifact's name as the *-bkup tools record it, relative to
// Path. The identity envelope records its full object key instead.
File string `json:"file" xml:"file"`
// Path is the object prefix this artifact was written under. Recorded per artifact because it
// cannot be derived from the subject alone — tenant artifacts live under a per-workspace branch.
// Empty on manifests written before this field existed; see ArtifactPath.
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"`
}
Artifact is one file in a recovery point.
type Identity ¶
type Identity struct {
Schema int `json:"schema"`
InstallID string `json:"install_id"`
MiabiVersion string `json:"miabi_version"`
DBSchema string `json:"db_schema,omitempty"`
// EncryptionKey is MIABI_ENCRYPTION_KEY — the master key every workspace
// data-encryption key is wrapped under. It is the reason this envelope exists.
EncryptionKey string `json:"encryption_key"`
// JWTSecret keeps issued API tokens and sessions valid across the restore.
JWTSecret string `json:"jwt_secret"`
Domain string `json:"domain,omitempty"`
WebURL string `json:"web_url,omitempty"`
ControlURL string `json:"control_url,omitempty"`
ACMEEmail string `json:"acme_email,omitempty"`
RegistryHost string `json:"registry_host,omitempty"`
RegistryStorage string `json:"registry_storage,omitempty"`
NetworkName string `json:"network_name,omitempty"`
NetworkSubnet string `json:"network_subnet,omitempty"`
InternalNetworkName string `json:"internal_network_name,omitempty"`
CreatedAt time.Time `json:"created_at"`
}
Identity is everything needed to rebuild the stack that owns a control-plane dump. Without it a fresh host lists every workspace and decrypts no secret, since a fresh install generates a new key. The database and Redis passwords are NOT here — those belong to the new host.
type Manifest ¶
type Manifest struct {
XMLName xml.Name `json:"-" xml:"recoveryPoint"`
// Notice is stamped on every file so whoever finds one in a bucket — months
// later, mid-incident, without this repository open — can tell what it is.
Notice string `json:"_notice" xml:"notice"`
Schema int `json:"schema" xml:"schema,attr"`
Ref string `json:"ref" xml:"ref,attr"`
InstallID string `json:"install_id" xml:"installId"`
MiabiVersion string `json:"miabi_version" xml:"miabiVersion"`
SchemaVersion string `json:"schema_version,omitempty" xml:"schemaVersion,omitempty"`
// KEKFingerprint is HMAC-SHA256(master key, KEKFingerprintLabel).
KEKFingerprint string `json:"kek_fingerprint,omitempty" xml:"kekFingerprint,omitempty"`
Encrypted bool `json:"encrypted" xml:"encrypted"`
IdentitySealed bool `json:"identity_sealed" xml:"identitySealed"`
Bucket string `json:"bucket,omitempty" xml:"bucket,omitempty"`
// Prefix is the object prefix the database dump lives under.
Prefix string `json:"prefix,omitempty" xml:"prefix,omitempty"`
// VolumePrefix is the object prefix volume archives live under; the two are
// configured separately, and a restore that guessed would find nothing.
VolumePrefix string `json:"volume_prefix,omitempty" xml:"volumePrefix,omitempty"`
Artifacts []Artifact `json:"artifacts" xml:"artifacts>artifact"`
CreatedAt time.Time `json:"created_at" xml:"createdAt"`
}
Manifest is a recovery point's self-description, written to the bucket in cleartext beside the sealed identity envelope, so restore preflight works with nothing but the bucket and the passphrase. Nothing in it is secret: the KEK fingerprint identifies a key without revealing it.
func DecodeManifest ¶
DecodeManifest parses and validates a manifest read from the bucket.
func (*Manifest) ArtifactKey ¶
ArtifactKey is an artifact's full object key.
func (*Manifest) ArtifactPath ¶
ArtifactPath is the prefix an artifact lives under. It prefers the value recorded on the artifact; manifests written before that field existed carry none, so the layout is reconstructed from the subject — in one place, and aware of tenant artifacts.
func (*Manifest) DatabaseArtifact ¶
DatabaseArtifact returns the control-plane dump, or nil.
func (*Manifest) TenantArtifacts ¶
TenantArtifacts returns the tenant database dumps and volume archives — the workload data, restored after the control plane is back and its containers have been recreated.
func (*Manifest) VolumeArtifacts ¶
VolumeArtifacts returns the platform volume archives.