Skip to main content

Crate day_part_permissions

Crate day_part_permissions 

Source
Expand description

day-part-permissions: a headless portable API for the OS permission system. No UI; any Rust code can depend on this crate to ask what the OS will do, and to ask the OS itself.

use day_part_permissions::{Permission, Status, request, status};
if status(Permission::Camera) != Status::Granted {
    request(Permission::Camera, |s| println!("camera: {s}"));
}

Platform selection is purely #[cfg(target_os)]/#[cfg(target_env)] (consent is an OS concern, not a widget-toolkit one): Apple platforms use the per-framework authorization APIs (CLLocationManager, AVCaptureDevice, PHPhotoLibrary, UNUserNotificationCenter, CMMotionActivityManager), Android Context.checkSelfPermission plus requestPermissions from a headless Fragment, HarmonyOS OH_AT_CheckSelfPermission, and the web navigator.permissions with the per-API request calls. Desktop Linux and Windows have no consent database, so every gated capability there answers Gate::Ungated / Status::Granted.

§Two questions, two vocabularies

gate answers “does this target gate the capability at all?” and status answers “what will the OS do if I use it now?”. Keeping them apart is what lets desktop Linux answer Status::Granted for the camera (nothing stands in your way, so proceed, and let the real failure surface at open("/dev/video0")) without losing the structural fact that Linux has no permission system (Gate::Ungated).

§Declare before you ask

Every mobile OS also requires a BUILD-TIME declaration, and Day generates those from the [permissions] table in Day.toml (docs/permissions.md). This matters more than it sounds: an undeclared permission reports Status::Restricted on Android, and on iOS/macOS touching a gated API without its NS…UsageDescription key terminates the process.

§Reasons are not a runtime parameter

No platform accepts one. iOS and macOS read NS…UsageDescription from Info.plist; requestPermissions(String[], int) and requestPermissionsFromUser(context, string[]) take no text, and neither does getUserMedia or Notification.requestPermission. So the reason lives in the declaration, where it reaches the OS, and this crate hands you should_show_rationale and can_prompt so your app can draw its own explanation first, in its own localized copy.

§Threading and cancellation

request’s completion runs on an unspecified thread, possibly the UI thread (Android’s onRequestPermissionsResult, the browser’s only thread), so deliver results with a day_reactive::Setter, the way day-part-http does. There is no blocking request: the OS prompt is drawn by the very thread a blocking call would park, so it would deadlock by construction. And dropping a StatusFuture does not take the prompt off the screen; no platform can do that. See StatusFuture.

Modules§

android
Android permission ids beyond the portable set.
apple
Apple authorizations beyond the portable set.
ohos
HarmonyOS permission names beyond the portable set.
web
Browser Permissions-API names beyond the portable set. The string is passed straight to navigator.permissions.query.

Structs§

StatusFuture
A pending permission answer, from status_future or request_future.
StatusesFuture
The request_many_future counterpart of StatusFuture; same drop semantics.

Enums§

Gate
Whether the compiled target gates a capability at all: the structural question, asked separately from status so that “no gate here” never has to masquerade as a denial.
Permission
A permission to query or request.
Status
What the OS will do if the capability is used now.

Functions§

can_prompt
Whether calling request would actually put a prompt on screen right now. When this is false the answer is already final for this launch, so draw an “open Settings” path (open_settings) rather than a “grant access” button.
gate
Whether this target gates perm at all (fixed at compile time for most permissions; a few are decided by the OS version, e.g. Android motion below API 29).
open_settings
Open the OS page where the user can change this app’s permissions. true if a page was opened.
request
Ask the OS for perm, showing the system prompt when can_prompt says one would appear and resolving immediately with the current status when it would not.
request_future
request as a Future.
request_many
Ask for several permissions in one prompt sequence where the platform batches them (Android submits a single array; elsewhere they are chained). Answers are positional: out[i] is the status of perms[i].
request_many_future
request_many as a Future.
should_show_rationale
Whether the user has already refused once and a further prompt is still possible: the platform’s signal that an explanation should come first. This is Android’s shouldShowRequestPermissionRationale; every other platform answers false, because Apple never re-prompts and the web has no equivalent.
status
What the OS will do if perm is used now. Never blocks.
status_async
status, but always authoritative: it waits for the platform’s answer where that is asynchronous, so it never yields Status::Unknown.
status_future
status_async as a Future. Plain oneshot plumbing over the same completion; any executor can await it, including a test’s block_on.