Skip to content

add install-path writability preflight and path context on install errors#196

Open
jaemk wants to merge 1 commit into
masterfrom
260717.permissions-ux
Open

add install-path writability preflight and path context on install errors#196
jaemk wants to merge 1 commit into
masterfrom
260717.permissions-ux

Conversation

@jaemk

@jaemk jaemk commented Jul 18, 2026

Copy link
Copy Markdown
Owner

Closes #112.

  • Add an opt-in check_install_path_writable(bool) builder setter (default off, all backends): probe bin_install_path writability immediately before the download and fail with the new Error::InstallPathNotWritable { path } on a definite permission refusal, before any bytes are fetched. Indeterminate probe results proceed. Sync and async flows.
  • Name the install path in install-step IO failures (always on): PermissionDenied from self_replace / move-to-dest becomes InstallPathNotWritable; any other IO error is rewrapped with "installing to {path}" context, preserving the ErrorKind. Previously this surfaced as a bare Io(Permission denied) with no path.
  • Document the non-goal: the crate never escalates privileges (no sudo re-exec, no polkit/UAC). A new Permissions section in the crate docs shows detecting the error and relaunching elevated via the restart module as the application's choice.
  • Add hermetic integration tests (tests/permissions.rs) proving a refused preflight downloads nothing (recording client, zero requests), with async parity. Update specs/ref-update-pipeline.md and specs/ref-errors.md.

Note that the probe is conservative by design: only a definite PermissionDenied fails the preflight; anything ambiguous (missing parent, unusual filesystems, Windows ACL edge cases) proceeds and lets the real install operation surface the error, now with path context.

…PathNotWritable`, name the install path in install errors

- new opt-in builder setter `check_install_path_writable(bool)` (default off,
  all backends): probe `bin_install_path` writability before the download and
  fail with the new `Error::InstallPathNotWritable { path }` on a definite
  permission refusal, before any bytes are fetched. Indeterminate probe results
  proceed. Sync and async flows. (#112)
- install-step IO failures now always name the install path: `PermissionDenied`
  from self_replace / move-to-dest becomes `InstallPathNotWritable`; any other
  IO error is rewrapped with "installing to {path}" context, preserving the
  `ErrorKind`.
- the crate never escalates privileges (documented non-goal); a new Permissions
  section in the crate docs shows detecting the error and relaunching elevated
  via the `restart` module as the application's choice.
- hermetic integration tests in tests/permissions.rs prove a refused preflight
  downloads nothing (recording client, zero requests) with async parity.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Managing around sudo or missing permissions

1 participant