backup

Documentation

Overview

Package backup packs what the user set up in magpie into one file, sealed with a passphrase, to carry to another machine: the providers (their keys too, unless left out), the pictures picked for them, the settings, the profiles, every agent's model and the library (the instructions, MCP servers and skills magpie gives the agents). Subscriptions are not in it: each is the sign-in of an agent on this machine, so each machine signs in on its own.

The file is JSON: a header naming how it is sealed, and the bundle encrypted with AES-256-GCM under a key derived from the passphrase with PBKDF2-SHA256. Nothing in it can be read without the passphrase.

Index

• Constants
• Variables
• func AddPlugins(es []plugin.Entry) ([]string, map[string]string)
• func Flag(keys bool) *bool
• func OpenData(sealed []byte, pass string) ([]byte, error)
• func Seal(b Bundle, pass string) ([]byte, error)
• func SealData(data []byte, pass string) ([]byte, error)
• func Secret(name string) bool
• type Bundle
  • func Collect(keys bool, app string) (Bundle, error)
  • func Open(data []byte, pass string) (Bundle, error)
• type Parts
• type Result
  • func Restore(b Bundle, parts Parts) (Result, error)

Constants

const BundleVersion = 2

BundleVersion is the bundle's structure: 2 carries the per-part credential markers (ProvidersKeys, SettingsKeys, LibraryKeys) as their own three-state flags; 1 and before had the whole-bundle Keys alone.

const Ext = ".magpie-backup"

Ext is the extension backups are saved with.

Variables

var All = Parts{true, true, true, true, true}

All is every part.

var ErrCorrupt = errors.New("not a magpie backup")

ErrCorrupt is a file that isn't a backup at all, or one cut short: its JSON, format, or key-derivation fields don't read. It is told from a wrong passphrase and from a newer magpie's file, so a sync can rebuild the damaged one from this computer rather than fail on it forever.

var ErrNotBackup = errors.New("not a magpie backup")

ErrNotBackup is a file that doesn't begin like a backup at all: an empty one, a page a server answered with, another app's file. It reads as ErrCorrupt does, but is never rebuilt over by a sync on its own.

var ErrPassphrase = errors.New("wrong passphrase, or the file was changed")

ErrPassphrase is a passphrase that does not open the backup.

Functions

func AddPlugins

func AddPlugins(es []plugin.Entry) ([]string, map[string]string)

AddPlugins installs the plugins a backup or a sync carries that aren't here (provider.AddPlugins), giving each its time: a first one downloads Bun. It says why each it couldn't add wasn't, by spec.

func Flag

func Flag(keys bool) *bool

Flag is a per-part credential marker as a bundle field takes one: the part's own, written when a sync merged it. Absent (nil) is a whole collect's or an older magpie's.

func OpenData

func OpenData(sealed []byte, pass string) ([]byte, error)

OpenData opens what SealData sealed.

func Seal

func Seal(b Bundle, pass string) ([]byte, error)

Seal encrypts the bundle under the passphrase.

func SealData

func SealData(data []byte, pass string) ([]byte, error)

SealData seals data under the passphrase, as Seal does a bundle.

func Secret

func Secret(name string) bool

Secret reports whether a header or an environment variable by that name looks like it holds a key: what a backup without keys leaves empty.

Types

type Bundle

type Bundle struct {
	Version     int                        `json:"version"`
	Created     time.Time                  `json:"created"`
	App         string                     `json:"app,omitempty"` // the magpie that made it
	Keys        bool                       `json:"keys"`          // whole-backup credential policy
	Providers   []provider.Provider        `json:"providers"`
	Icons       map[string][]byte          `json:"icons,omitempty"`  // pictures picked for providers, by file name
	Groups      []provider.Group           `json:"groups,omitempty"` // the user's model groups
	Settings    *settings.Settings         `json:"settings,omitempty"`
	GatewayKeys *[]access.Key              `json:"gatewayKeys,omitempty"`
	Profiles    map[string]profile.Profile `json:"profiles,omitempty"`
	Agents      map[string]string          `json:"agents,omitempty"`  // every agent's fields as they are now
	Library     *library.Bundle            `json:"library,omitempty"` // nil from a magpie before it, or with none
	// Searches are the web search APIs (#419), their keys with the
	// providers'; nil from a magpie before them.
	Searches *[]provider.SearchAPI `json:"searches,omitempty"`
	// Order is the order the user put the providers in (#499), by id;
	// none from a magpie before it went, or when they were never arranged.
	Order []string `json:"order,omitempty"`
	// GroupOrder is the order the user put the routing groups in (#779),
	// by id; none from a magpie before it, or when never arranged.
	GroupOrder []string `json:"groupOrder,omitempty"`
	// Plugins are the OpenCode plugins and middlewares added from npm or
	// git (provider.Carried), installed where the backup is put back:
	// the providers they serve come with them. Their sign-ins don't, as a
	// subscription's don't. Nil from a magpie before them.
	Plugins *[]plugin.Entry `json:"plugins,omitempty"`
	// Sync can carry one part's credentials without changing the others'
	// Keys policy; these are absent from older backups and whole collects.
	ProvidersKeys *bool `json:"providersKeys,omitempty"`
	SettingsKeys  *bool `json:"settingsKeys,omitempty"`
	LibraryKeys   *bool `json:"libraryKeys,omitempty"`
}

Bundle is what a backup holds.

func Collect

func Collect(keys bool, app string) (Bundle, error)

Collect gathers the bundle; without keys, providers carry none, nor any header that looks like one, and the library's servers no environment variable or header that looks like one (their names stay).

func Open

func Open(data []byte, pass string) (Bundle, error)

Open decrypts a backup. A byte order mark in front of the JSON is read through: the file is written back through edit.WriteAtomic, which keeps the mark a Windows tool saved the file with (#1534), and a backup moved through an editor that writes one opens as it is.

type Parts

type Parts struct {
	Providers, Settings, Profiles, Agents, Library bool
}

Parts picks what a restore puts back.

type Result

type Result struct {
	Added, Replaced int      // providers
	NeedKey         []string // providers that came without a key and have none here
	// SignIn is the subscriptions whose settings came with no account
	// here: a backup carries no sign-in, so they are listed once one is
	SignIn []string `json:",omitempty"`
	// Plugins are the plugins installed for it, PluginErrors why the others
	// couldn't be, by spec
	Plugins         []string          `json:",omitempty"`
	PluginErrors    map[string]string `json:",omitempty"`
	Settings        bool
	Profiles        int
	Agents          int               // agent fields changed
	Skipped         []string          // agent fields left alone: the agent is not on this machine, or the value failed
	Library         bool              // the library was put in
	LibraryProblems []library.Problem `json:",omitempty"` // what of it couldn't be given to an agent
}

Result says what a restore did.

func Restore

func Restore(b Bundle, parts Parts) (Result, error)

Restore puts the chosen parts of the bundle in. Providers come first, so the agents' models that go through them resolve. Only agents on this machine are set.