Documentation
¶
Overview ¶
Package updates implements a mechanism for checking if software updates are available, and fetching a changelog.
Given a domain, the latest version of the software is queried in DNS from "_updates.<domain>" as a TXT record. If a new version is available, the changelog compared to a last known version can be retrieved. A changelog base URL and public key for signatures has to be specified explicitly.
Downloading or upgrading to the latest version is not part of this package.
Index ¶
- Variables
- func Check(ctx context.Context, elog *slog.Logger, resolver dns.Resolver, ...) (rversion Version, rrecord *Record, changelog *Changelog, rerr error)
- func Lookup(ctx context.Context, elog *slog.Logger, resolver dns.Resolver, ...) (rversion Version, rrecord *Record, rerr error)
- type Change
- type Changelog
- type Record
- type Version
Constants ¶
This section is empty.
Variables ¶
var ( MetricLookup stub.HistogramVec = stub.HistogramVecIgnore{} MetricFetchChangelog stub.HistogramVec = stub.HistogramVecIgnore{} HTTPClientObserve func(ctx context.Context, log *slog.Logger, pkg, method string, statusCode int, err error, start time.Time) = stub.HTTPClientObserveIgnore )
var ( // Lookup errors. ErrDNS = errors.New("updates: dns error") ErrRecordSyntax = errors.New("updates: dns record syntax") ErrNoRecord = errors.New("updates: no dns record") ErrMultipleRecords = errors.New("updates: multiple dns records") ErrBadVersion = errors.New("updates: malformed version") // Fetch changelog errors. ErrChangelogFetch = errors.New("updates: fetching changelog") )
Functions ¶
func Check ¶
func Check(ctx context.Context, elog *slog.Logger, resolver dns.Resolver, domain dns.Domain, lastKnown Version, changelogBaseURL string, pubKey []byte) (rversion Version, rrecord *Record, changelog *Changelog, rerr error)
Check checks for an updated version through DNS and fetches a changelog if so.
Check looks up a TXT record at _updates.<domain>, and parses the record. If the latest version is more recent than lastKnown, an update is available, and Check will fetch the signed changes since lastKnown, verify the signatures, and return the changelog. The latest version and parsed DNS record is returned regardless of whether a new version was found. A non-nil changelog is only returned when a new version was found and a changelog could be fetched and verified.
Types ¶
type Change ¶
type Change struct {
PubKey []byte // Key used for signing.
Sig []byte // Signature over text, with ed25519.
Text string // Signed changelog entry, starts with header similar to email, with at least fields "version" and "date".
}
Change is a an entry in the changelog, a released version.
type Changelog ¶
type Changelog struct {
Changes []Change // Newest first.
}
Changelog is returned as JSON.
The changelog itself is not signed, only individual changes. The goal is to prevent a potential future different domain owner from notifying users about new versions.
func FetchChangelog ¶
func FetchChangelog(ctx context.Context, elog *slog.Logger, baseURL string, base Version, pubKey []byte) (changelog *Changelog, rerr error)
FetchChangelog fetches the changelog compared against the base version, which can be the Version zero value.
The changelog is requested using HTTP GET from baseURL with optional "from" query string parameter.
Individual changes are verified using pubKey. If any signature is invalid, an error is returned.
A changelog can be maximum 1 MB.
type Record ¶
type Record struct {
Version string // v=UPDATES0, required and must always be first.
Latest Version // l=<version>, required.
}
Record is an updates DNS record.
type Version ¶
Version is a specified version in an updates records.
func ParseVersion ¶
ParseVersion parses a version as used in an updates records.
Rules:
- Optionally start with "v"
- A dash and anything after it is ignored, e.g. for non-release modifiers.
- Remaining string must be three dot-separated numbers.
Source Files