loki_file_access/
lib.rs

1// SPDX-License-Identifier: MIT
2// Copyright (c) 2026 AppThere
3
4//! # loki-file-access
5//!
6//! Cross-platform, frontend-agnostic file picker and capability-based file
7//! access for Rust applications.
8//!
9//! This crate provides a unified API for presenting native file-picker dialogs
10//! and accessing user-selected files across all major platforms:
11//!
12//! - **Desktop** (Windows, macOS, Linux, BSD) — via the [`rfd`](https://crates.io/crates/rfd) crate
13//! - **Android** — via the Storage Access Framework with persistable URI permissions
14//! - **iOS** — via `UIDocumentPickerViewController` with security-scoped bookmarks
15//! - **WASM** — via `<input type="file">` with in-memory file buffers
16//!
17//! # Zero UI Framework Dependencies
18//!
19//! `loki-file-access` has **no UI framework dependencies**.  It returns
20//! standard [`Future`] values implemented with only `std` primitives (no Tokio,
21//! no async-std required).  It is usable from Dioxus, egui, Iced, Xilem,
22//! `pollster::block_on`, or any other async or sync Rust context.
23//!
24//! # Quick Start
25//!
26//! ```no_run
27//! use loki_file_access::{FilePicker, PickOptions};
28//! use std::io::Read;
29//!
30//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
31//! let picker = FilePicker::new();
32//!
33//! // Pick a file to open
34//! let token = picker
35//!     .pick_file_to_open(PickOptions {
36//!         mime_types: vec!["text/plain".into()],
37//!         ..Default::default()
38//!     })
39//!     .await?;
40//!
41//! if let Some(token) = token {
42//!     let mut reader = token.open_read()?;
43//!     let mut contents = String::new();
44//!     reader.read_to_string(&mut contents)?;
45//!     println!("File contents: {contents}");
46//!
47//!     // Serialize the token for later use
48//!     let stored = token.serialize();
49//!     println!("Token: {stored}");
50//! }
51//! # Ok(())
52//! # }
53//! ```
54//!
55//! # Capability Tokens
56//!
57//! Every picker operation returns a [`FileAccessToken`] — a serializable
58//! capability that encapsulates all platform-specific state needed to re-open
59//! the file.  Tokens can be serialized to a URL-safe string for storage in a
60//! recent-files list and deserialized to re-open files across app restarts.
61//!
62//! On Android, the token holds a content URI with a persistable permission
63//! grant.  On iOS, it holds a security-scoped bookmark.  On desktop, it holds
64//! a filesystem path.  On WASM, it holds the file data in memory.
65
66pub mod api;
67pub mod error;
68pub(crate) mod future;
69mod platform;
70pub mod token;
71
72// Re-export public types at crate root for convenience.
73pub use api::{FilePicker, PickOptions, SaveOptions};
74pub use error::{AccessError, PickerError, TokenParseError};
75pub use token::{FileAccessToken, PermissionStatus, ReadSeek, WriteSeek};
loki_file_access/lib.rs

loki_file_access/
lib.rs
