Documentation
¶
Overview ¶
Package export reads an installation through the ports and writes it into a backup archive (backup.Writer). It is the producer half of the archive: the restore engine decodes what it writes with Decode.
What is exported ¶
For each module of layout v5:
- state: every State record the module owns, with the lifetime it has left, and, for oidc, every Index set. The leases, notifications, gates, caches and dedupe records of the controllers, and the maintenance record, are not exported: they are rebuilt, or (the maintenance record) managed by the restore itself. The backup module's own records (its runs, its restores, its retention pass) are not exported either.
- secrets: every secret under internal/<module> and, where the module has an external namespace, external/<module>, as the stored document (its latest version). The backup module's own secrets (the restore identity) are not exported: the backup role never reads them.
- blobs: the objects under the module's blob prefixes (BlobPrefixes), each a file of its own in the archive.
Records ¶
A record is one JSON object on one line of the module's state.jsonl or secrets.jsonl. Every record carries `v` (the record version, RecordVersion) and `t` (its type), so it is read without the file that held it:
state {"v":1,"t":"state","key":..., "value":<base64>, "expires":<RFC 3339>}
index {"v":1,"t":"index","key":..., "members":[...], "expires":<RFC 3339>}
secret {"v":1,"t":"secret","ns":"internal|external","name":..., "doc":<the stored JSON object>}
A State key is the logical key, which port.Locate5 addresses; `expires` is absolute and absent for a permanent record, so a restore later computes what is left. The values of secrets and records appear only inside the encrypted archive.
One pass ¶
A run is one pass over a fixed list of units (one State family, one set family, one secret namespace or one blob prefix of one module); it is not resumed. The writer spools to local disk, so memory is one record or one blob.
Index ¶
Constants ¶
const ( TypeState = "state" TypeIndex = "index" TypeSecret = "secret" )
Record types.
const ( Internal = "internal" External = "external" )
The secret namespaces.
const RecordVersion = 1
RecordVersion is the version of the record encoding this release writes.
Variables ¶
var BlobPrefixes = map[port.Module][]string{ port.ModuleGitHub: {blobprefix.GitHubReports}, port.ModuleSlack: {blobprefix.SlackReports}, }
BlobPrefixes are the blob prefixes each module owns and a backup keeps: what each controller last reported. The hub's directory snapshots (`google/`) are a cache that the module rewrites on its next refresh and are not kept.
var ErrRecord = errors.New("export: unreadable record")
ErrRecord is a record that cannot be decoded: not JSON, an unknown version or type, a type that does not belong in the section, or a field out of range.
Functions ¶
func Run ¶
Run exports the source into w and closes it, returning the archive (a local file; backup.Publish uploads it). The writer is aborted when the run fails. A run is one pass: there is nothing to resume.
Types ¶
type Index ¶
type Index struct {
V int `json:"v"`
T string `json:"t"`
Key string `json:"key"`
Members []string `json:"members"`
Expires string `json:"expires,omitempty"`
}
Index is one Index set.
type Options ¶
type Options struct {
// Modules limits the run; the default is every module of [port.Modules].
Modules []port.Module
// Now is the clock the remaining lifetimes are made absolute by.
Now func() time.Time
// Log receives one line per unit, with counts only. Nil is silent.
Log *slog.Logger
}
Options are the optional parts of a run.
type Record ¶
type Record interface {
// contains filtered or unexported methods
}
Record is a decoded record: State, Index or Secret. A blob is not a record: it is a file of its own in the archive.
type Secret ¶
type Secret struct {
V int `json:"v"`
T string `json:"t"`
// NS is [Internal] or [External]; Name is the path below
// <ns>/<module>.
NS string `json:"ns"`
Name string `json:"name"`
// Doc is the stored JSON object, the latest version.
Doc json.RawMessage `json:"doc"`
}
Secret is one secret as the store holds it.
type Source ¶
type Source struct {
// State and Index read every module's records and sets; the Router of the
// DynamoDB adapter is both.
State port.StateExporter
Index port.IndexExporter
// Secrets are the installation's secrets on layout v5.
Secrets *secretstore.StoresV5
// Blob holds the modules' blobs.
Blob port.Blob
}
Source is what an export reads. All four are required.
Source Files