README
¶
PACKAGE DOCUMENTATION
package update
import "github.com/inconshreveable/go-update"
Package update allows a program to "self-update", replacing its
executable file with new bytes.
Package update provides the facility to create user experiences like
auto-updating or user-approved updates which manifest as user prompts in
commercial applications with copy similar to "Restart to being using the
new version of X".
Updating your program to a new version is as easy as:
err := update.FromUrl("http://release.example.com/2.0/myprogram")
if err != nil {
fmt.Printf("Update failed: %v", err)
}
The most low-level API is FromStream() which updates the current
executable with the bytes read from an io.Reader.
Additional APIs are provided for common update strategies which include
updating from a file with FromFile() and updating from the internet with
FromUrl().
Using the more advaced Download.UpdateFromUrl() API gives you the
ability to resume an interrupted download to enable large updates to
complete even over intermittent or slow connections. This API also
enables more fine-grained control over how the update is downloaded from
the internet as well as access to download progress,
VARIABLES
var (
// Returned when the remote server indicates that no download is available
UpdateUnavailable error
)
FUNCTIONS
func FromFile(filepath string) (err error)
FromFile reads the contents of the given file and uses them to update
the current program's executable file by calling FromStream().
func FromStream(newBinary io.Reader) (err error)
FromStream reads the contents of the supplied io.Reader newBinary and
uses them to update the current program's executable file.
FromStream performs the following actions to ensure a cross-platform
safe update:
- Renames the current program's executable file from
/path/to/program-name to /path/to/.program-name.old
- Opens the now-empty path /path/to/program-name with mode 0755 and
copies the contents of newBinary into the file.
- If the copy is successful, it erases /path/to/.program.old. If this
operation fails, no error is reported.
- If the copy is unsuccessful, it attempts to rename
/path/to/.program-name.old back to /path/to/program-name. If this
operation fails, the error is not reported in order to not mask the
error that caused the rename recovery attempt.
func FromUrl(url string) error
FromUrl downloads the contents of the given url and uses them to update
the current program's executable file. It is a convenience function
which is equivalent to
NewDownload().UpdateFromUrl(url)
See Download.UpdateFromUrl for more details.
TYPES
type Download struct {
// net/http.Client to use when downloading the update.
// If nil, a default http.Client is used
HttpClient *http.Client
// Path on the file system to dowload the update to
// If empty, a temporary file is used.
// After the download begins, this path will be set
// so that the client can use it to resume aborted
// downloads
Path string
// Progress returns the percentage of the download
// completed as an integer between 0 and 100
Progress chan (int)
// HTTP Method to use in the download request. Default is "GET"
Method string
}
Type Download encapsulates the necessary parameters and state needed to
download an update from the internet. Create an instance with the
NewDownload() factory function.
func NewDownload() *Download
NewDownload initializes a new Download object
func (d *Download) UpdateFromUrl(url string) (err error)
UpdateFromUrl downloads the given url from the internet to a file on
disk and then calls FromStream() to update the current program's
executable file with the contents of that file.
If the update is successful, the downloaded file will be erased from
disk. Otherwise, it will remain in d.Path to allow the download to
resume later or be skipped entirely.
Only HTTP/1.1 servers that implement the Range header are supported.
UpdateFromUrl() uses HTTP status codes to determine what action to take.
- The HTTP server should return 200 or 206 for the update to be
downloaded.
- The HTTP server should return 204 if no update is available at this
time. This will cause UpdateFromUrl to return the error
UpdateUnavailable.
- If the HTTP server returns a 3XX redirect, it will be followed
according to d.HttpClient's redirect policy.
- Any other HTTP status code will cause UpdateFromUrl to return an
error.
Documentation
¶
Overview ¶
Package update allows a program to "self-update", replacing its executable file with new bytes.
Package update provides the facility to create user experiences like auto-updating or user-approved updates which manifest as user prompts in commercial applications with copy similar to "Restart to being using the new version of X".
Updating your program to a new version is as easy as:
err := update.FromUrl("http://release.example.com/2.0/myprogram")
if err != nil {
fmt.Printf("Update failed: %v", err)
}
The most low-level API is FromStream() which updates the current executable with the bytes read from an io.Reader.
Additional APIs are provided for common update strategies which include updating from a file with FromFile() and updating from the internet with FromUrl().
Using the more advaced Download.UpdateFromUrl() API gives you the ability to resume an interrupted download to enable large updates to complete even over intermittent or slow connections. This API also enables more fine-grained control over how the update is downloaded from the internet as well as access to download progress,
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromFile ¶
FromFile reads the contents of the given file and uses them to update the current program's executable file by calling FromStream().
func FromStream ¶
FromStream reads the contents of the supplied io.Reader newBinary and uses them to update the current program's executable file.
FromStream performs the following actions to ensure a cross-platform safe update:
- Creates a new file, /path/to/.program-name.new with mode 0755 and copies the contents of newBinary into the file
- Renames the current program's executable file from /path/to/program-name to /path/to/.program-name.old
- Renames /path/to/.program-name.new to /path/to/program-name
- If the rename is successful, it erases /path/to/.program.old. If this operation fails, no error is reported.
- If the rename is unsuccessful, it attempts to rename /path/to/.program-name.old back to /path/to/program-name. If this operation fails, the error is not reported in order to not mask the error that caused the rename recovery attempt.
func FromUrl ¶
FromUrl downloads the contents of the given url and uses them to update the current program's executable file. It is a convenience function which is equivalent to
NewDownload(url).GetAndUpdate()
See Download.Get() for more details.
func SanityCheck ¶
func SanityCheck() (err error)
SanityCheck() attempts to determine whether an in-place executable update could succeed by performing preliminary checks (to establish valid permissions, etc). This helps avoid downloading updates when we know the update can't be successfully applied later.
Types ¶
type Download ¶
type Download struct {
// net/http.Client to use when downloading the update.
// If nil, a default http.Client is used
HttpClient *http.Client
// Path on the file system to dowload the update to
// If empty, a temporary file is used.
// After the download begins, this path will be set
// so that the client can use it to resume aborted
// downloads
Path string
// Progress returns the percentage of the download
// completed as an integer between 0 and 100
Progress chan (int)
// HTTP Method to use in the download request. Default is "GET"
Method string
// HTTP URL to issue the download request to
Url string
// Set to true when the server confirms a new version is available
// even if the updating process encounters an error later on
Available bool
}
Type Download encapsulates the necessary parameters and state needed to download an update from the internet. Create an instance with the NewDownload() factory function.
You may only use a Download once,
func NewDownload ¶
NewDownload initializes a new Download object
func (*Download) Get ¶
Get() downloads the given url from the internet to a file on disk and then calls FromStream() to update the current program's executable file with the contents of that file.
If the update is successful, the downloaded file will be erased from disk. Otherwise, it will remain in d.Path to allow the download to resume later or be skipped entirely.
Only HTTP/1.1 servers that implement the Range header support resuming a partially completed download.
UpdateFromUrl() uses HTTP status codes to determine what action to take.
- The HTTP server should return 200 or 206 for the update to be downloaded.
- The HTTP server should return 204 if no update is available at this time.
- If the HTTP server returns a 3XX redirect, it will be followed according to d.HttpClient's redirect policy.
- Any other HTTP status code will cause UpdateFromUrl to return an error.
func (*Download) GetAndUpdate ¶
type MeteredReader ¶
type MeteredReader struct {
// contains filtered or unexported fields
}
func (*MeteredReader) Close ¶
func (m *MeteredReader) Close() error
type RoundTripper ¶
We wrap the round tripper when making requests because we need to add headers to the requests we make even when they are requests made after a redirect
Source Files