equinox: github.com/equinox-io/equinox Index | Files | Directories

package equinox

import "github.com/equinox-io/equinox"

Package equinox allows applications to remotely update themselves with the equinox.io service.

Minimal Working Example

import "github.com/equinox-io/equinox"

const appID = "<YOUR EQUINOX APP ID>"

var publicKey = []byte(`
-----BEGIN PUBLIC KEY-----
MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEtrVmBxQvheRArXjg2vG1xIprWGuCyESx
MMY8pjmjepSy2kuz+nl9aFLqmr+rDNdYvEBqQaZrYMc6k29gjvoQnQ==
-----END PUBLIC KEY-----
`)

func update(channel string) error {
	opts := equinox.Options{Channel: channel}
	if err := opts.SetPublicKeyPEM(publicKey); err != nil {
		return err
	}

	// check for the update
	resp, err := equinox.Check(appID, opts)
	switch {
	case err == equinox.NotAvailableErr:
		fmt.Println("No update available, already at the latest version!")
		return nil
	case err != nil:
		return err
	}

	// fetch the update and apply it
	err = resp.Apply()
	if err != nil {
		return err
	}

	fmt.Printf("Updated to new version: %s!\n", resp.ReleaseVersion)
	return nil
}

Update To Specific Version

When you specify a channel in the update options, equinox will try to update the application to the latest release of your application published to that channel. Instead, you may wish to update the application to a specific (possibly older) version. You can do this by explicitly setting Version in the Options struct:

opts := equinox.Options{Version: "0.1.2"}

Prompt For Update

You may wish to ask the user for approval before updating to a new version. This is as simple as calling the Check function and only calling Apply on the returned result if the user approves. Example:

// check for the update
resp, err := equinox.Check(appID, opts)
switch {
case err == equinox.NotAvailableErr:
	fmt.Println("No update available, already at the latest version!")
	return nil
case err != nil:
	return err
}

fmt.Println("New version available!")
fmt.Println("Version:", resp.ReleaseVersion)
fmt.Println("Name:", resp.ReleaseTitle)
fmt.Println("Details:", resp.ReleaseDescription)

ok := prompt("Would you like to update?")

if !ok {
	return
}

err = resp.Apply()
// ...

Generating Keys

All equinox releases must be signed with a private ECDSA key, and all updates verified with the public key portion. To do that, you'll need to generate a key pair. The equinox release tool can generate an ecdsa key pair for you easily:

equinox genkey

Index

Package Files

doc.go sdk.go sdk_ctx.go

Variables

var NotAvailableErr = errors.New("No update available")

type Options Uses

type Options struct {
    // Channel specifies the name of an Equinox release channel to check for
    // a newer version of the application.
    //
    // If empty, defaults to 'stable'.
    Channel string

    // Version requests an update to a specific version of the application.
    // If specified, `Channel` is ignored.
    Version string

    // TargetPath defines the path to the file to update.
    // The emptry string means 'the executable file of the running program'.
    TargetPath string

    // Create TargetPath replacement with this file mode. If zero, defaults to 0755.
    TargetMode os.FileMode

    // Public key to use for signature verification. If nil, no signature
    // verification is done. Use `SetPublicKeyPEM` to set this field with PEM data.
    PublicKey crypto.PublicKey

    // Target operating system of the update. Uses the same standard OS names used
    // by Go build tags (windows, darwin, linux, etc).
    // If empty, it will be populated by consulting runtime.GOOS
    OS  string

    // Target architecture of the update. Uses the same standard Arch names used
    // by Go build tags (amd64, 386, arm, etc).
    // If empty, it will be populated by consulting runtime.GOARCH
    Arch string

    // Target ARM architecture, if a specific one if required. Uses the same names
    // as the GOARM environment variable (5, 6, 7).
    //
    // GoARM is ignored if Arch != 'arm'.
    // GoARM is ignored if it is the empty string. Omit it if you do not need
    // to distinguish between ARM versions.
    GoARM string

    // The current application version. This is used for statistics and reporting only,
    // it is optional.
    CurrentVersion string

    // CheckURL is the URL to request an update check from. You should only set
    // this if you are running an on-prem Equinox server.
    // If empty the default Equinox update service endpoint is used.
    CheckURL string

    // HTTPClient is used to make all HTTP requests necessary for the update check protocol.
    // You may configure it to use custom timeouts, proxy servers or other behaviors.
    HTTPClient *http.Client
}

func (*Options) SetPublicKeyPEM Uses

func (o *Options) SetPublicKeyPEM(pembytes []byte) error

SetPublicKeyPEM is a convenience method to set the PublicKey property used for checking a completed update's signature by parsing a Public Key formatted as PEM data.

type Response Uses

type Response struct {
    // Version of the release that will be updated to if applied.
    ReleaseVersion string

    // Title of the the release
    ReleaseTitle string

    // Additional details about the release
    ReleaseDescription string

    // Creation date of the release
    ReleaseDate time.Time
    // contains filtered or unexported fields
}

Response is returned by Check when an update is available. It may be passed to Apply to perform the update.

func Check Uses

func Check(appID string, opts Options) (Response, error)

Check communicates with an Equinox update service to determine if an update for the given application matching the specified options is available. The returned error is nil only if an update is available.

The appID is issued to you when creating an application at https://equinox.io

You can compare the returned error to NotAvailableErr to differentiate between a successful check that found no update from other errors like a failed network connection.

func CheckContext Uses

func CheckContext(ctx context.Context, appID string, opts Options) (Response, error)

CheckContext is like Check but includes a context.

func (Response) Apply Uses

func (r Response) Apply() error

Apply performs an update of the current executable (or TargetFile, if it was set on the Options) with the update specified by Response.

Error is nil if and only if the entire update completes successfully.

func (Response) ApplyContext Uses

func (r Response) ApplyContext(ctx context.Context) error

ApplyContext is like Apply but includes a context.

Directories

PathSynopsis
internal/go-updatePackage update provides functionality to implement secure, self-updating Go programs (or other single-file targets).
internal/go-update/internal/binarydistPackage binarydist implements binary diff and patch as described on http://www.daemonology.net/bsdiff/.
internal/go-update/internal/osextExtensions to the standard "os" package.
internal/osextExtensions to the standard "os" package.
protopackage proto defines a set of structures used to negotiate an update between an an application (the client) and an Equinox update service.

Package equinox imports 19 packages (graph) and is imported by 5 packages. Updated 2018-09-25. Refresh now. Tools for package owners.