dr

package
v1.10.21 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

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

Examples

Constants

View Source
const (
	SubjectDatabase       = "database"
	SubjectVolume         = "volume"
	SubjectIdentity       = "identity"
	SubjectTenantDatabase = "tenant-database"
	SubjectTenantVolume   = "tenant-volume"
)

Artifact subjects, mirroring models.PlatformBackupSubject.

View Source
const IdentityExt = ".mbid"

IdentityExt is the sealed identity envelope's file extension.

View Source
const IdentitySchema = 1

IdentitySchema is the envelope payload version. Restore refuses a schema it does not know rather than guessing at fields.

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

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

View Source
const ManifestSchema = 1

ManifestSchema is the manifest's version.

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

View Source
const TenantSegment = "tenants"

TenantSegment is the branch tenant artifacts live under, below the database or volume prefix: "<prefix>/tenants/<workspace>".

Variables

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

func EncodeManifest(m *Manifest) ([]byte, error)

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

func IdentityObject(prefix, ref string) string

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 IsRef

func IsRef(s string) bool

IsRef reports whether s looks like a recovery point ref.

func ManifestObject

func ManifestObject(rootPrefix, ref string) string

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

func NewRef(installID string, at time.Time) string

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

func RefFromIdentityObject(key string) string

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

func RefFromManifestObject(key string) string

RefFromManifestObject recovers the ref from an info file's object key, or "".

func Seal

func Seal(id *Identity, passphrase string) ([]byte, error)

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

func TenantPath(base, workspace string) string

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

func ValidatePassphrase(pass string) error

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.

func Open

func Open(sealed []byte, passphrase string) (*Identity, error)

Open decrypts a sealed envelope. A wrong passphrase and a tampered file are reported identically — the AEAD cannot tell them apart, and pretending otherwise would be a decryption oracle.

func (*Identity) Validate

func (i *Identity) Validate() error

Validate checks an opened envelope carries what restore depends on.

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

func DecodeManifest(b []byte) (*Manifest, error)

DecodeManifest parses and validates a manifest read from the bucket.

func (*Manifest) ArtifactKey

func (m *Manifest) ArtifactKey(a Artifact) string

ArtifactKey is an artifact's full object key.

func (*Manifest) ArtifactPath

func (m *Manifest) ArtifactPath(a Artifact) string

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

func (m *Manifest) DatabaseArtifact() *Artifact

DatabaseArtifact returns the control-plane dump, or nil.

func (*Manifest) TenantArtifacts

func (m *Manifest) TenantArtifacts() []Artifact

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

func (m *Manifest) Validate() error

Validate checks a manifest describes something restorable.

func (*Manifest) VolumeArtifacts

func (m *Manifest) VolumeArtifacts() []Artifact

VolumeArtifacts returns the platform volume archives.

Jump to

Keyboard shortcuts

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