equinox

README

equinox client SDK

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

Minimal Working Example

import "gitee.com/marker/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

Documentation

Overview

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

Minimal Working Example

import "gitee.com/marker/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

• Variables
• func CheckRequestParam(appID string, opts *Options) (payload []byte, err error)
• type Options
  • func (o *Options) SetPublicKeyPEM(pembytes []byte) error
• type Response
  • func Check(appID string, opts Options) (Response, error)
  • func CheckContext(ctx context.Context, appID string, opts Options) (Response, error)
  • func CheckForData(data string, opts Options) (r Response, err error)
  • func (r Response) Apply() error
  • func (r Response) ApplyContext(ctx context.Context) error

Variables

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

Functions

func CheckRequestParam

func CheckRequestParam(appID string, opts *Options) (payload []byte, err error)

Types

type Options

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

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

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

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

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

CheckContext is like Check but includes a context.

func CheckForData

func CheckForData(data string, opts Options) (r Response, err error)

func (Response) Apply

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

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

ApplyContext is like Apply but includes a context.