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§
- Status
Future - A pending permission answer, from
status_futureorrequest_future. - Statuses
Future - The
request_many_futurecounterpart ofStatusFuture; same drop semantics.
Enums§
- Gate
- Whether the compiled target gates a capability at all: the structural question, asked
separately from
statusso 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
requestwould actually put a prompt on screen right now. When this isfalsethe 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
permat 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.
trueif a page was opened. - request
- Ask the OS for
perm, showing the system prompt whencan_promptsays one would appear and resolving immediately with the current status when it would not. - request_
future requestas aFuture.- 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 ofperms[i]. - request_
many_ future request_manyas aFuture.- 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 answersfalse, because Apple never re-prompts and the web has no equivalent. - status
- What the OS will do if
permis used now. Never blocks. - status_
async status, but always authoritative: it waits for the platform’s answer where that is asynchronous, so it never yieldsStatus::Unknown.- status_
future status_asyncas aFuture. Plain oneshot plumbing over the same completion; any executor can await it, including a test’sblock_on.