Tags · jaemk/self_update

v1.0.0-rc.2

finalize the 1.0 api surface (rc.2) (#184)

* feat: edition 2024, rustls default, rename tls/compression features, gate backends and indicatif

Breaking changes to the feature surface and build baseline for the 1.0 release:

- move to edition 2024 (MSRV stays 1.85); fixes the now-illegal explicit
`ref` bindings in the `Display` impl and an s3 match pattern.
- default TLS is now `rustls` instead of native-tls; `default = [reqwest,
rustls, progress-bar, github]`.
- rename `default-tls` -> `native-tls` and `compression-flate2` ->
`compression-tar-gz`.
- add a default-on `progress-bar` feature gating `indicatif` and the
terminal bar. `progress_callback` and `show_download_progress` stay
always-on; when the feature is off the bar is a no-op.
- gate each backend behind a feature (`github` default, `gitlab`, `gitea`,
`s3`); `quick-xml` is optional behind `s3` and `s3-auth` implies `s3`.
- declare `required-features` for the backend examples and feature-gate the
s3 doctest so a default `cargo test` no longer builds them.

The reqwest/ureq and native-tls/rustls mutual-exclusion compile_errors are
unchanged; --all-features still does not build.

* feat: object-safe injectable HttpClient/HttpResponse traits, non-exclusive http clients

Replace the compile-time-monomorphized transport seam with a runtime
trait dispatch so callers can supply their own HTTP transport:

- add object-safe `HttpClient`/`HttpResponse` traits (and async
`AsyncHttpClient`/`AsyncHttpResponse`); `reqwest` and `ureq` become
built-in impls behind namespaced modules. `.http_client(Arc<dyn
HttpClient>)` is the canonical injection path; `ClientOverride` and the
concrete-client carriers are gone (thin convenience setters remain).
- drop the public `AsyncResponse = reqwest::Response` alias; the async
download streams through the trait's `bytes_stream`.
- `HttpResponse` exposes a streaming `body`/`body_buffered`; the s3 listing
now parses XML from the reader instead of buffering the whole body.
- remove the both-clients, neither-client, and both-TLS `compile_error!`
guards. reqwest and ureq now coexist (reqwest is preferred when both are
on) and rustls wins when both TLS features are enabled, so
`cargo build --all-features` builds. Only the no-client and
async-requires-reqwest guards remain.

Backends keep their existing send/fetch flow; the sans-io rewrite is
separate. `make ci` and `cargo build --all-features` both pass.

* feat: unify backend fetch on a sans-io core, add AsyncReleaseUpdate, offload the async install tail

Collapse the duplicated per-backend sync/async fetch paths and fix the
async executor blocking:

- introduce a transport-free `PageRequest`/`Page` core with shared
`run_paginated`/`run_paginated_async` drivers; each backend's URL building
and JSON/XML parsing is now written once and run through either driver, so
the sync and async paths no longer drift.
- add a public sealed `AsyncReleaseUpdate` trait mirroring `ReleaseUpdate`
(replacing the crate-private `AsyncFetch`); the async verbs keep their
names but are now nameable and usable as a bound.
- run the checksum/extract/replace finish tail inside `spawn_blocking` so the
async update no longer stalls the runtime.
- git listing stops paginating at the first release not newer than the
current version instead of walking the whole history; `ReleaseList::fetch`
still walks every page.
- s3 listing follows `NextContinuationToken` so buckets with more than one
page of objects list fully; add `max_keys` (clamped 1..=1000) and
`signature_ttl` setters, replacing the hardcoded 100-key cap and 300s TTL.
- drop the unused `current_version` argument from the custom-source
`get_latest_releases` methods.

make ci passes on both clients and cargo build --all-features builds.

* feat: structure the Config/Release/Update error variants, fix discarded source chains

Replace the three stringly-typed catch-all `Error` variants with
structured ones and restore the broken `source()` chains:

- `Config(String)` becomes `MissingField { field }`, `InvalidHeader
{ source }`, and `InvalidAuthToken { source }` (a residual `Config`
remains only for the s3-auth hostless-url case).
- `Release(String)` becomes `NoReleaseFound { target }`, `MissingAssetField
{ field }`, and `InvalidResponse { source }`.
- `Update(String)` becomes `VerificationRejected { reason }` for a rejecting
`verify_with` hook and `Internal { message, source }` for genuine
invariants; the discarded tokio `JoinError`, s3 XML/regex, header, and
auth-token sources now chain through `Error::source()`.
- add `#[non_exhaustive]` to the new struct variants and to `Unauthorized`/
`HttpStatus` so future fields stay non-breaking.

`Io` stays a concrete `io::Error` and the boxed dependency variants stay
opaque. make ci passes on both clients and cargo build --all-features builds.

* feat: encapsulate Release/ReleaseAsset behind getters, return Releases from ReleaseList::fetch

Finalize the release model for downstream stability and cheaper parsing:

- make `Release`/`ReleaseAsset` fields `pub(crate)` `Arc<str>` with borrow
getters (`name`/`version`/`date`/`body`/`assets`, `name`/`download_url`);
construction stays via `Release::builder()`/`ReleaseAsset::new`.
- parse forge releases through private `#[derive(Deserialize)]` DTOs instead
of walking a `serde_json::Value` tree (`Deserialize` stays off the public
types).
- `ReleaseList::fetch` returns `Releases` (with `into_vec()` to recover the
`Vec<Release>`); `Releases` carries an optional current version so a bare
listing has `current_version() == None`.
- add `Releases::from_releases` for downstream tests and `ReleaseStatus::version()`
to mirror `VersionStatus`.

make ci passes on both clients and cargo build --all-features builds.

* feat: split UpdateInternals off the sealed trait, unify auth, Result-returning verify hook, ergonomics

Regularize the builder/config surface for the 1.0 release:

- move the crate-private-typed accessors off the sealed `UpdateConfig`
onto a `pub(crate)` `UpdateInternals` trait, so the public trait no longer
names unnameable types.
- add a total-order `cmp_versions` and a shared newest-first release
comparator used by both `choose_latest_release` and the s3 sort, replacing
the non-antisymmetric bool-mapped sort.
- carry the authorization scheme (`token` for github/gitea, `Bearer` for
gitlab) on the request config and apply it on both the listing and download
paths, honoring a user `AUTHORIZATION` override on both; drop the github
default baked into the trait.
- change the `verify_binary` hook (renamed from `verify_with`) to return
`Result<()>` so a rejection carries its reason; an `Err` becomes
`VerificationRejected`.
- take `impl Into<String>`/`impl AsRef<Path>` on `Download::from_url` and the
`Extract`/`Move`/`MoveAll` constructors (dropping their lifetime); replace
the two transposable `progress_style` strings with a typed `ProgressStyle`;
rename `Download::header` to `request_header`; drop the redundant per-client
setters now that `http_client` injection covers them.
- make retry backoff configurable via `retry_backoff`; make the custom
backend's `retries` apply to its download.
- rename `EndPoint` to `Endpoint` with a tuple `Generic` variant; align the
gitea `url` parameter; remove the deprecated no-op s3 `auth_token` setters.

make ci passes on both clients and cargo build --all-features builds.

* fix: make the http_client module public so custom transports are implementable

The `http_client` module was private, so `HttpClient`/`HttpResponse` could not
be named or implemented downstream even though the `http_client(Arc<dyn
HttpClient>)` builder setter accepts them. Make the module public and add an
integration test that implements a transport through the public API and drives a
backend with no reqwest/ureq and no network. `serde_json` becomes a dev-dep for
the test (implementing `HttpResponse::json_value` names `serde_json::Value`).

* test: add sigv4 presigned-url conformance vectors

Pin the hand-rolled S3 presigned-URL signer against AWS-documented known
answers: the GET Object query-auth example (canonical request, string-to-sign
digest, and final signature), the documented signing-key derivation bytes, the
canonical-request SHA256, and the UriEncode/credential-scope formatting. A small
`s3_signature_v4_at(now_secs)` split lets the vectors feed a fixed timestamp;
the runtime-produced URLs are unchanged.

* docs: document the 1.0 breaking changes in the migration guides and changelog

Fold the additional 1.0 breaking changes into the 0.x-to-1.0 migration guides
(agent and human), updating the entries that later changes superseded
(`verify_with` -> `verify_binary`, `Download::header` -> `request_header`, the
`Release`/`ReleaseAsset` getters, the feature renames, `EndPoint` -> `Endpoint`,
s3 region errors now `MissingField`). Add the unreleased changelog section.
Correct `ref-feature-flags.md` for the coexisting reqwest/ureq and
native-tls/rustls features, and drop stale internal labels from the reference
specs.

* chore: drop internal tracking labels from code comments

Reword test and build comments to plain descriptions, removing the internal
workstream/finding labels and a few em dashes. Comment-only; no code change.

* feat: embedded key verification, pagination fix, asset-name traversal guard

Add compile-time VerifyingKey embedding example and hermetic tests for the
key rotation protocol. Fix pagination early-stop that assumed semver-descending
release ordering (could silently drop updates on backport releases). Add
server-supplied asset name validation before filesystem use to prevent path
traversal before signature verification runs. Harden the default_client test
to actually call default_client(). Fix retry_backoff_ms saturating-shift
overflow for high retry counts.

Update README, lib.rs, AGENTS.md, appveyor.yml, Cargo.toml, macros.rs,
version.rs, and all ref-* specs to match post-1.0 reality: rustls is the
default TLS, s3/gitlab/gitea require their feature, clients/TLS may coexist,
download request-establishment is retried, error variants are split, and
ReleaseDto replaces the old Release::from_release* constructors.

* fix: gitea pagination continue-not-break, missing #[non_exhaustive], build_client async guard; update stale 1.0 docs

Behavior fixes:
- gitea.rs: replace early-stop break with continue in release_array_page, matching
github.rs and gitlab.rs; a backport release on page 1 no longer silently prevents
finding a newer release on page 2. Remove dead auth_token field from ReleaseList
and dead auth param threading through releases_plan/api_headers.
- errors.rs: add #[non_exhaustive] to Unauthorized, HttpStatus, InvalidAssetName;
these were missing the attribute despite the CHANGELOG claiming all new struct
variants have it.
- common.rs: gate the async cert-build in build_client on the async slot being empty;
previously an injected sync client alongside root certs would still trigger the
async cert-build path and set cert_error.

Doc corrections (stale names, wrong error variants, contradictions):
- ref-update-pipeline.md: verify_with -> verify_binary, Error::Update ->
Error::VerificationRejected/Internal, Download::header -> request_header, remove
deleted reqwest_client/ureq_agent setters, fix "download never retried" claim.
- ref-s3-backend.md: EndPoint -> Endpoint, Generic { end_point } -> Generic(String),
auth_token removed (not deprecated), Error::Release -> Error::InvalidResponse,
Error::Config -> Error::MissingField for missing bucket/region.
- ref-common-config.md: progress_style two-arg -> one ProgressStyle arg, verify_with
-> verify_binary, Error::Config -> Error::InvalidHeader/MissingField.
- AGENTS.md: remove stale "--all-features does not build" note; update setter/type
names (identifier -> asset_identifier, Error::Http -> Error::Transport, etc.);
fix ureq "mutually exclusive" and async "incompatible with ureq" claims.
- ref-feature-flags.md: remove "cannot compile" claim for --all-features; add
dep:bytes to async feature, fix dep:... placeholder for github/gitlab/gitea.
- ref-gitlab-backend.md: auth token failure Error::InvalidHeader ->
Error::InvalidAuthToken; missing-field errors Error::Config -> Error::MissingField.
- ref-gitea-backend.md: same error variant corrections.
- ref-custom-backend.md: Error::Release/Config/Update -> split variants.
- async-api.md: remove stale "async + ureq is a compile_error!" claim.
- async-future-extensions.md: mark spawn_blocking extract tail as implemented.
- CHANGELOG.md: correct Error::Config producer list (cert-build failure is also a
producer, not only the s3-auth case); correct pagination description (per-item
filter, continues all pages).
- docs/migrations/0.x-to-1.0-human.md: remove Error::Release(s) arm from "after"
match block; same producer/pagination corrections.
- ref-errors.md: same Error::Config producer corrections.
- README.md: fix cross-compile troubleshooting snippet (dropped reqwest, causing
compile_error); fix github example run command (re-add archive features).
- appveyor.yml: add gitlab/gitea/s3 features to cargo test (backends are now
feature-gated and were silently skipped on Windows CI).
- examples/s3.rs: add missing s3 feature to run command.
- examples/embedded_key.rs: remove dead #[cfg(not(feature="signatures"))] branches.
- specs/README.md: mark 5 specs done (error-variant-granularity, s3-max-keys,
update-config-internal-accessors, releases-test-constructor, choose-latest-sort).
- transport-control.md: correct http_client injection site (builders only, not Download).
- src/http_client/mod.rs: doc note that HttpResponse body methods are single-use.
- src/update.rs: use target_asset.name() getter consistently.
- src/version.rs: demote cmp_releases_newest_first to pub(crate) (internal only).

* feat: complete custom root CA support (`Certificate`, `add_root_certificate`)

Commits the CORP-1 custom-root-CA work that was split across the previous
commit boundary: `src/tls.rs` (the opaque `Certificate` type), the `mod tls;`
declaration and `self_update::Certificate` re-export, the `add_root_certificate`
builder setter, `Download::root_certificate`, and the per-client
`build_with_certs` / `client_with_root_certs` wiring. HEAD referenced
`crate::tls::Certificate` from `common.rs`/`gitea.rs` without these, so it did
not compile standalone; this makes the tree coherent.

* fix: gate the auth token to the configured API host

Attach the derived `auth_token` only to requests whose host matches the
backend's configured API base host (or an `allow_auth_host` entry), over https
(loopback hosts may use http). Previously the token was sent to the
server-supplied asset `download_url` and to `Link` next-page URLs with no origin
check, so a malicious or compromised release server could set either to its own
host and receive the user's platform token.

`apply_auth` now takes the request URL and consults a new `auth_base_host` on
`RequestConfig` (set by each backend at build time) plus a user-managed
`auth_hosts` list. Add the `allow_auth_host` builder setter for release assets
legitimately served from a separate CDN or mirror host.

* fix: reject drive-relative asset names, check before prompt, derive asset arch/os from target, match exe by canonical path

- `is_safe_asset_name` now requires a single normal path component, rejecting
Windows drive-relative names like `C:evil` that are not absolute yet let
`Path::join` escape the temp dir. The check runs before the status print and
confirmation prompt, so a traversal-unsafe name is never echoed or confirmed.
- `Release::asset_for` derives its arch/os fallback tokens from the `target`
argument instead of the build host's `std::env::consts`, so an explicitly
configured cross-target selects its own asset and `darwin`-named macOS assets
match a `*-apple-darwin` target.
- `install_binary` compares the install path against `current_exe()` by
canonicalized path, so a symlinked or differently-spelled path to the running
binary still takes the `self_replace` path.

* fix: harden zip extraction, cross-device install, confirm prompt, progress template

- `Extract` rejects zip entries whose path escapes the output dir (zip-slip) via
`enclosed_name`, creates directory entries, and preserves the archived unix
permission mode so a zip-packaged binary stays executable when installed to a
custom path.
- `Move::to_dest` falls back to copy-and-rename when source and dest are on
different filesystems (the extract temp dir is often a tmpfs), instead of
failing with EXDEV after a successful download.
- `confirm` treats stdin EOF as a decline rather than a blank-line yes, so an
unattended caller without `no_confirm` aborts instead of self-replacing.
- an invalid progress-bar template returns `Error::Config` instead of panicking
mid-download.
- the derived auth header value is marked sensitive so it renders as `Sensitive`
in `Debug` output and is kept out of client logs.

* fix: redact s3 presigned-url secrets in errors and status output

`status_to_error` stores a redacted request URL, and the pre-update status print
redacts the download URL, so an s3 presigned URL does not carry a live
`X-Amz-Signature` or the `X-Amz-Credential` access-key id into error messages,
the `url()` accessor, logs, or stdout.

* fix: map a malformed release-listing body to `InvalidResponse`

A 200 response whose body is not a JSON array (a proxy error page, a captive
portal) now surfaces as `Error::InvalidResponse` on the github/gitlab/gitea
listing paths instead of `NoReleaseFound`, so a broken network is not silently
read as an empty release list. A valid empty `[]` still yields `NoReleaseFound`.
Matches the s3 backend and the single-release endpoints.

* fix: single-encode s3 object keys in the sigv4 canonical uri and signed url; encode listing prefix

The signer re-encoded the URL parser's already percent-encoded path, so any
object key with a reserved character (a space, `+`, unicode) produced a
canonical URI with `%2520` and a `SignatureDoesNotMatch` from S3. The canonical
URI now uses `url.path()` verbatim and the signed URL is rebuilt from the same
path, so the two are byte-identical. The listing `prefix` query param is now
percent-encoded, matching the continuation-token handling.

* feat: replace `Error::Config` with structured variants; harden custom-CA support

Error model:
- Replace the stringly `Error::Config(String)` with `Error::InvalidCertificate
{ source }` (cert-parse / client-build failures) and, under `progress-bar`,
`Error::InvalidProgressStyle { source }` (bad bar template). Route the s3 SigV4
host-extraction failure to `Error::S3Auth`. `Config` is removed.
- `client_with_root_certs` returns a boxed error so the Download path preserves
the cert-build source chain.
- Add public `Error` constructors so custom `ReleaseSource` implementors can
build the release-flow variants: `no_release_found`, `missing_asset_field`,
`invalid_response`, `http_status_error`.

Custom-CA support:
- `build_client` materializes each client slot independently: injecting a client
for one transport no longer drops the custom roots for the other auto-built
transport.
- The crate-built ureq cert agent is now built per request, so it honors the
per-request timeout and `HTTP(S)_PROXY` env, matching the default ureq path.
- reqwest merges all supplied certs in a single `tls_certs_merge` call.
- Rename `Download::root_certificate` to `add_root_certificate`, matching the
builder setter. Document that ureq-only DER validation is deferred to connection
time.

* feat: rename `verify_keys` -> `verifying_keys`, github `url` -> `api_base_url`, gitlab/gitea `url` -> `host`

- The signature-key setter is `verifying_keys` (matching the `VerifyingKey` type
and the stored field), not `verify_keys`.
- The github endpoint setter is `api_base_url` (it takes the full API base,
including any `/api/v3` path); gitlab and gitea name their instance-base setter
`host`. The same-named `url` setter across all three hid that github's contract
differs. gitea's missing-instance error now names the `host` field.

* feat: add archive-tar + compression-tar-gz to default features; add `dangerously_allow_non_https_auth_forwarding`

- The default feature set now includes `archive-tar` and `compression-tar-gz`, so
a crate added with default features can install the `.tar.gz` releases most
projects ship without opting into extra features. Zip stays opt-in.
- `dangerously_allow_non_https_auth_forwarding` on the builders lifts the https
requirement for auth-token forwarding to a host-matched request (still gated to
the configured API host / `allow_auth_host` set), for a trusted internal http
network.

* feat: return concrete `Update` from `build()` with inherent update verbs

`build()` now returns the backend's concrete `Update` instead of
`Box<dyn ReleaseUpdate>`. `Update` is `Send`, so it can move to a worker thread
(`thread::spawn(move || updater.update())`), and it exposes `update`,
`update_extended`, `get_latest_release`, `get_latest_releases`,
`get_release_version`, and `is_update_available` as inherent methods (via
`impl_sync_update_verbs!`), so `.build()?.update()?` needs no trait import. The
sealed `ReleaseUpdate` trait still carries the shared orchestration.

* feat: rename the filtered `get_latest_releases` to `get_newer_releases`; add `is_update_available`

The `ReleaseUpdate` verb that returns only releases strictly newer than the
current version is now `get_newer_releases` (and `get_newer_releases_async` on
`AsyncReleaseUpdate`), distinct from the raw `get_latest_release` (singular). The
`ReleaseSource` custom-backend method keeps its `get_latest_releases` name (it
returns the source's candidates, unfiltered). `Update` gains an inherent
`is_update_available() -> Option<Release>` convenience.

* feat: add `Error::CompressionNotEnabled`, reject gzip assets when the codec feature is off

A plain `.gz` asset with `compression-tar-gz` disabled previously installed its
still-compressed bytes as the binary; a `.tar.gz` with the tar container but no
gzip codec failed opaquely inside the tar reader. `detect_archive` now returns
`Error::CompressionNotEnabled` for a gzip layer when the feature is off, and the
`ArchiveKind::*(Some(Gz))` kinds are only produced when the codec is available.

* feat: make `Download::request_header` infallible, deferring header errors to `download_to`

`Download::request_header` now returns `&mut Self` and records an invalid
name/value as a deferred error surfaced from `download_to`/`download_to_async` as
`Error::InvalidHeader`, matching the builders' `request_header` so code moves
between the high-level flow and the manual `Download` flow without a change in the
error contract.

* feat: `max_keys` takes `u16`, `Extract` dirs take `impl AsRef<Path>`, expose `Releases::from_listing`

- s3 `max_keys` takes a plain `u16` instead of `impl Into<u16>`, so a numeric
literal infers without a conversion.
- `Extract::extract_into` / `extract_file` take `impl AsRef<Path>` for the output
dir, matching the other path-taking constructors.
- `Releases::from_listing` is public, so downstream tests can build the
bare-listing state (no current version) that `ReleaseList::fetch` returns.

* feat: trim `HttpResponse` to `headers` + `body`, dropping the `&mut self` `json_value`/`text`

The sync `HttpResponse` trait now requires only `headers` and `body` (plus the
defaulted `body_buffered`); the crate parses JSON/XML from the body reader
itself. The removed `json_value`/`text` took `&mut self` (a single-use footgun for
custom-transport implementors and the reason for the drained-placeholder hack in
the reqwest impl) and were never called in production. The async
`AsyncHttpResponse::text` (consuming, used by the async parse path) is unchanged.

* feat: add `ReleaseList::fetch_async` on every backend

Async sibling of `ReleaseList::fetch`: a bare release listing was the one sync
verb with no async equivalent, so async callers had to build a full `Update` just
to list releases. `fetch_async` mirrors `fetch` on the async transport (github/
gitlab/gitea via `run_paginated_async`, s3 via its async listing walk).

* test: cover end-to-end cert-build failure; use `NoExpand` in bin-path substitution

- A malformed `add_root_certificate` surfaces as `Error::InvalidCertificate` from
both the github Update and ReleaseList `build()`.
- `bin_path_in_archive` template substitution uses `regex::NoExpand`, so a `$` in
the bin name or version is inserted literally instead of being read as a capture
reference.

* fix: percent-encode gitlab `repo_name`, clamp s3 `signature_ttl` to the aws expires range

- gitlab's `repo_name` is percent-encoded in the `projects/{owner}%2F{name}` path
like `repo_owner`, so a name with a reserved character does not create an extra
path segment.
- s3 `signature_ttl` is clamped to AWS's `X-Amz-Expires` range (1s..=7d), so a
too-long TTL does not sign only to be rejected by S3 at request time.

* docs: update changelog for the final 1.0 surface

* docs: update the 1.0 migration guides for the final api names and behavior

* docs: fix crate-doc cert setter name and the update-check example, regenerate readme

The `add_root_certificate` name replaces the stale `root_certificate` in the
`Certificate` docs, and the "checking for an update" section uses the new
`Update::is_update_available()` method directly instead of the old fetch-then-query
pattern.

* ci: run `make ci`, add msrv and windows jobs, gate publish on ci

- The build workflow runs `make ci` (fmt, README drift, clippy -D warnings on
every client, the default/reqwest/ureq/async test lanes, the --all-features
build, and example builds) instead of a bare `cargo check` + `make tests`, and
adds a 1.85 MSRV build job and a windows-latest test job. Toolchain setup moves
from the archived `actions-rs/toolchain` to `dtolnay/rust-toolchain`.
- The publish workflow gates `cargo publish` on a `make ci` job and tags only when
the publish succeeds, so a failed publish never tags a version that did not reach
crates.io. Windows CI moves off AppVeyor into the build workflow.

* docs: update reference specs for the final 1.0 api

* release 1.0.0-rc.2

* fix: expect the platform exe suffix from `bin_name()` in accessor tests

Jul 5, 2026
1006eeb
zip
tar.gz

v1.0.0-rc.1

ci: tag the released version in the publish workflow

Derive the version from Cargo.toml and create/push `v<version>` if the tag does not
already exist. Runs with `if: always()` so the tag is created even when `cargo publish`
is a no-op (version already on crates.io). Add `contents: write` to push the tag.

Jun 22, 2026
b69a9a2
zip
tar.gz

PreviousNext

Navigation Menu

v1.3.0

v1.2.0

v1.1.0

v1.0.0

v1.0.0-rc.6

v1.0.0-rc.5

v1.0.0-rc.4

v1.0.0-rc.3

v1.0.0-rc.2

v1.0.0-rc.1

Tags: jaemk/self_update