update

Documentation

Overview

Package update keeps magpie current. Builds are published as GitHub releases of yetone/magpie-releases; usemagpie.ai/api/latest describes the newest one: its version, notes, and every file with its SHA-256.

The macOS app replaces its own bundle: the new zip is downloaded, checked against its hash, unpacked, and accepted only if it is signed by the same team as the app already installed. A bare binary (the terminal build, and the desktop app on Windows and Linux) replaces itself the same way, minus the signature.

Index

• Constants
• Variables
• func Alive(pid int) bool
• func AppAsset() string
• func AwaitPredecessor()
• func BinaryAsset() string
• func Bundle() string
• func CanElevate() bool
• func CheckMirror(prefix string) error
• func CheckProxy(proxy string) error
• func CopiedCLI() string
• func Executable() (string, error)
• func Feed() string
• func Homebrew(exe string) bool
• func InLang(md, lang string) string
• func Install(staged, bundle string) error
• func InstallAsAdmin(staged, bundle string) error
• func InstallBinary(staged, exe string) error
• func InstallBinaryAsAdmin(staged, exe string) error
• func Mirror(ctx context.Context) string
• func NeedsAdmin(err error) bool
• func Newer(a, b string) bool
• func NotesFeed() string
• func Reexec(exe string, args, env []string) error
• func Relaunch(bundle string) error
• func RelaunchArgs(window bool, view string) []string
• func RelaunchBinary(exe string, window bool, view string) error
• func ReleasePage(version string) string
• func Released(v string) bool
• func RemoveOld(exe string)
• func RemoveStaleNew(exe string)
• func ReplaceBinary(ctx context.Context, rel *Release) error
• func Replaced(exe string, started os.FileInfo) bool
• func ShowNotes(last, current string, existed bool) (after string, show bool)
• func Stage(ctx context.Context, rel *Release, bundle string) (string, error)
• func StageBinary(ctx context.Context, rel *Release) (string, error)
• func StaleCLI(appVersion string) string
• func StripInstall(md string) string
• func Stuck(bundle string) string
• func WithMirror(ctx context.Context, prefix string) context.Context
• func WithProgress(ctx context.Context, f func(done, total int64)) context.Context
• func WithProxy(ctx context.Context, proxy string) context.Context
• func Writable(dir string) bool
• type Asset
• type Note
  • func Between(notes []Note, after, upto string) []Note
  • func NotesBetween(ctx context.Context, after, upto, lang string) ([]Note, error)
• type Release
  • func Latest(ctx context.Context) (*Release, error)
  • func LatestIn(ctx context.Context, lang string) (*Release, error)

Constants

const MaxNotes = 40

MaxNotes is how many releases' notes are shown at most: magpie releases often, and a long-unopened one would have pages of them.

const Site = "https://usemagpie.ai"

Site is magpie's home; its /api/latest is the update feed.

Variables

var ErrCanceled = errors.New("the update was canceled")

ErrCanceled is the administrator's password prompt dismissed.

var GUI bool

GUI says this binary has the desktop app in it. Off the Mac that app is a single binary too, and it updates from its own build, not the terminal one.

Functions

func Alive

func Alive(pid int) bool

Alive reports whether the process pid is still running.

func AppAsset

func AppAsset() string

AppAsset and BinaryAsset name the files this machine would install.

func AwaitPredecessor

func AwaitPredecessor()

AwaitPredecessor blocks, for a while at most, until the magpie that relaunched this one has exited.

func BinaryAsset

func BinaryAsset() string

func Bundle

func Bundle() string

Bundle is the .app the running binary lives in, or "" when it is not in one.

func CanElevate

func CanElevate() bool

CanElevate reports whether this system can ask for the administrator's password: always on a Mac, with polkit on Linux, not on Windows.

func CheckMirror

func CheckMirror(prefix string) error

CheckMirror says what is wrong with a mirror prefix, nil when it is one.

func CheckProxy

func CheckProxy(proxy string) error

CheckProxy says what is wrong with a proxy address, nil when it is one.

func CopiedCLI

func CopiedCLI() string

CopiedCLI is the command's path when it's a plain copied file rather than install.sh's link, or "" when it's absent, a link, or not a regular file. A bare Lstat — nothing is run, nothing is written — so the app's window can ask on every launch. It can't tell a stale copy from a current one (that needs the copy's version, which only `magpie update` may read), so what the window says off it is advice with a dismiss, not a warning that knows. Only on the Mac; on Linux the app and the command are one file.

func Executable

func Executable() (string, error)

Executable is the running binary, symlinks resolved.

func Feed

func Feed() string

Feed is where the newest release is described. MAGPIE_UPDATE_FEED points it elsewhere, for testing an update against a local server.

func Homebrew

func Homebrew(exe string) bool

Homebrew is whether exe was installed by Homebrew (brew install magpie), which keeps it in its Cellar and has to be the one to upgrade it: a binary replaced under it leaves brew thinking the old version is there.

func InLang

func InLang(md, lang string) string

InLang is a release's notes in lang, as the site cuts them (a site from before it did, or a feed elsewhere, hands them whole): "zh" the Chinese where there is some, else the English, everything above the marker. Notes from before the marker are English alone, in any language.

func Install

func Install(staged, bundle string) error

Install swaps the staged app in for bundle. The running copy keeps going until it quits; the next launch is the new one. Where the folder is not magpie's to change the error is a permission one (NeedsAdmin), and InstallAsAdmin can do it instead.

func InstallAsAdmin

func InstallAsAdmin(staged, bundle string) error

InstallAsAdmin is Install with the administrator's password, asked for by the system.

func InstallBinary

func InstallBinary(staged, exe string) error

InstallBinary swaps a staged binary in for exe, the running one, which keeps going until it exits.

func InstallBinaryAsAdmin

func InstallBinaryAsAdmin(staged, exe string) error

InstallBinaryAsAdmin is InstallBinary with the administrator's password.

func Mirror

func Mirror(ctx context.Context) string

Mirror is the mirror downloads under ctx go through, "" for none.

func NeedsAdmin

func NeedsAdmin(err error) bool

NeedsAdmin reports whether err is magpie not being allowed to change the folder it lives in, which the administrator's password gets past.

func Newer

func Newer(a, b string) bool

Newer reports whether version a comes after b. A pre-release comes before the release it leads up to.

func NotesFeed

func NotesFeed() string

NotesFeed is where the notes of past releases are listed: beside the update feed, on magpie's site. MAGPIE_NOTES_FEED points it elsewhere.

func Reexec

func Reexec(exe string, args, env []string) error

Reexec runs exe in this process's place with args and env: the same process, in the same terminal or under the same service manager, now running the new version (magpie web's restart to update).

func Relaunch

func Relaunch(bundle string) error

Relaunch opens bundle again once this process (pid) has exited.

func RelaunchArgs

func RelaunchArgs(window bool, view string) []string

RelaunchArgs is what RelaunchBinary starts magpie with: `gui [view]` for the window, `tray` for the tray icon alone.

func RelaunchBinary

func RelaunchBinary(exe string, window bool, view string) error

RelaunchBinary starts exe again: with its window on view when window is set (the window was open), else as the tray app alone, as autostart starts it. The new process waits for this one to exit before it takes the gateway's port; see AwaitPredecessor.

func ReleasePage

func ReleasePage(version string) string

ReleasePage is version's page on GitHub, where its notes are when the site can't give them (#661).

func Released

func Released(v string) bool

Released reports whether v is a release version rather than a build from source ("dev", "0bcb2cc-dirty", git describe's "v0.1.0-3-g0bcb2cc"); only releases update themselves.

func RemoveOld

func RemoveOld(exe string)

RemoveOld removes what earlier updates moved aside of exe, those no longer running.

func RemoveStaleNew

func RemoveStaleNew(exe string)

RemoveStaleNew removes exe.new when it is exe over again: the update a magpie left running from before it downloaded once more.

func ReplaceBinary

func ReplaceBinary(ctx context.Context, rel *Release) error

ReplaceBinary puts the release's build for this binary where the running one is.

func Replaced

func Replaced(exe string, started os.FileInfo) bool

Replaced reports whether exe is no longer the binary that was there when this process looked (started, from os.Stat): another magpie installed an update over it, and this one runs from where it was moved aside.

func ShowNotes

func ShowNotes(last, current string, existed bool) (after string, show bool)

ShowNotes decides, as magpie starts on current having last run as last ("" when it never said), whether to show what changed since, and from which version on (exclusive). Only an upgrade between releases shows: not a fresh install, the same version again, a downgrade, or a build from source. A magpie from before versions were kept has no last; when it was already in use (existed) its own version's notes are shown, from "", which Between takes as upto's alone.

func Stage

func Stage(ctx context.Context, rel *Release, bundle string) (string, error)

Stage downloads the app in rel and unpacks it next to the installed bundle, ready for Install. It returns the unpacked app.

func StageBinary

func StageBinary(ctx context.Context, rel *Release) (string, error)

StageBinary downloads the release's build for this binary next to it (or to the cache, where magpie may not write there), ready for InstallBinary.

func StaleCLI

func StaleCLI(appVersion string) string

StaleCLI is the path of a `magpie` command that is a copied file behind the app, or "" when there's nothing to say. install.sh links the command to magpie.app's binary so it follows every GUI update for free; a command that arrived as a copy — an older installer, a hand cp, or the standalone magpie-cli build — keeps running its own build once the app moves on, and a command behind the app is a stale build: one that predates the WebDAV short-write check (#531) truncated a remote backup on `magpie webdav now`, wedging the sync.

A copy is only worth mentioning when it actually trails the app, so this reads the copy's version and stays quiet when it is at or ahead of appVersion, or isn't a release at all (a build from source, or one that won't run — none of those is a stale release to nag about). Reading the version runs the old binary, and that isn't read-only: magpie's start-up runs its migrations before `version` answers. So only `magpie update`, which the user started, asks this — the app's window uses CopiedCLI and its advice can be dismissed instead. magpie doesn't rewrite the user's PATH — the fix is theirs: re-run install.sh, or link it by hand, which is what the advice says. Only on the Mac, where the app and the command are two places; on Linux they are one file.

func StripInstall

func StripInstall(md string) string

StripInstall takes a release's "Install" section (in any language) out of its notes: the download links, which mean nothing to a magpie that just updated itself. The section runs to the next heading of its level or above.

func Stuck

func Stuck(bundle string) string

Stuck says why the app at bundle cannot be replaced where it is, or "" when it can: opened from its disk image, or moved aside by macOS (App Translocation) because it was never moved out of Downloads.

func WithMirror

func WithMirror(ctx context.Context, prefix string) context.Context

WithMirror has the downloads made under ctx go through the mirror prefix; "off" goes through none, whatever Settings say, and "" leaves ctx as it is.

func WithProgress

func WithProgress(ctx context.Context, f func(done, total int64)) context.Context

WithProgress has downloads made under ctx report how far along they are; total is 0 while the size is unknown.

func WithProxy

func WithProxy(ctx context.Context, proxy string) context.Context

WithProxy has the update feed and the downloads asked under ctx go through proxy (http://, https://, socks5://, socks5h://; host:port is http; "direct" for none), over Settings' Proxy and the environment's.

func Writable

func Writable(dir string) bool

Writable reports whether magpie may replace what lives in dir.

Types

type Asset

type Asset struct {
	URL    string `json:"url"`
	Size   int64  `json:"size"`
	SHA256 string `json:"sha256"`
}

Asset is one downloadable file of a release.

type Note

type Note struct {
	Version string `json:"version"` // no v
	Notes   string `json:"notes"`   // markdown, its Install section taken out
	URL     string `json:"url,omitempty"`
}

Note is one release's notes, as the app shows them after an update.

func Between

func Between(notes []Note, after, upto string) []Note

Between keeps the notes of the releases after after up to and including upto, newest first, at most MaxNotes; with after "" only upto's. Each one's Install section is taken out, and one left empty is dropped.

func NotesBetween

func NotesBetween(ctx context.Context, after, upto, lang string) ([]Note, error)

NotesBetween asks the site for the notes of every release after after (none when "") up to and including upto, newest first, in lang (see InLang).

type Release

type Release struct {
	Version string           `json:"version"` // "0.2.0", no v
	Notes   string           `json:"notes"`   // markdown
	URL     string           `json:"url"`     // the release page
	Assets  map[string]Asset `json:"assets"`  // by file name
}

Release is one published version.

func Latest

func Latest(ctx context.Context) (*Release, error)

Latest asks the feed for the newest release, its notes in English.

func LatestIn

func LatestIn(ctx context.Context, lang string) (*Release, error)

LatestIn asks the feed for the newest release, its notes in lang (see InLang): the app's language, which What's new follows.