Merge pull request #31 from bordumb/dev-tokioSpawnWrapper

feat: add spawn_with wrapper and tokio guide to capsec-tokio

Author: bordumb

crates/capsec-tokio/Cargo.toml

@@ -9,11 +9,12 @@ keywords = ["security", "capability", "tokio", "async"]
 categories = ["asynchronous", "rust-patterns"]
 
 [features]
+rt = ["dep:tokio", "tokio/rt"]
 fs = ["dep:tokio", "tokio/fs"]
 net = ["dep:tokio", "tokio/net"]
 process = ["dep:tokio", "tokio/process"]
 io-util = ["dep:tokio", "tokio/io-util"]
-full = ["fs", "net", "process", "io-util"]
+full = ["rt", "fs", "net", "process", "io-util"]
 
 [dependencies]
 capsec-core.workspace = true

crates/capsec-tokio/README.md

@@ -10,19 +10,52 @@ You probably want to depend on the `capsec` facade crate with the `tokio` featur
 capsec = { version = "0.1", features = ["tokio"] }
 ```
 
-## Example
+## Capsec + Tokio Guide
+
+There are three common patterns for using capabilities in async code.
+
+### Pattern 1: Scoped proof (no spawn)
+
+When your async code runs on the current task (no `tokio::spawn`), pass capabilities by reference. The scope-before-await pattern inside each wrapper keeps futures `Send` automatically.
+
+```rust,ignore
+async fn handle_request(cap: &impl Has<FsRead>) {
+    let data = capsec::tokio::fs::read("/tmp/config.toml", cap).await?;
+    // use data...
+}
+```
+
+### Pattern 2: `spawn_with` (single capability)
+
+When spawning a task that needs one capability, use `capsec_tokio::task::spawn_with`. It converts `Cap<P>` to `SendCap<P>` for you — no need to call `.make_send()` manually.
 
 ```rust,ignore
-use capsec::prelude::*;
+let cap = root.grant::<FsRead>();
 
+let handle = capsec::tokio::task::spawn_with(cap, |cap| async move {
+    capsec::tokio::fs::read("/tmp/data.bin", &cap).await.unwrap()
+});
+
+let data = handle.await?;
+```
+
+### Pattern 3: `Arc` context (multiple capabilities)
+
+When a spawned task needs multiple capabilities, use `#[capsec::context(send)]` to create a `Send`-safe context struct, wrap it in `Arc`, and clone for each task.
+
+```rust,ignore
 #[capsec::context(send)]
 struct AppCtx {
     fs: FsRead,
+    net: NetConnect,
 }
 
-async fn load_config(ctx: &AppCtx) -> Result<String, CapSecError> {
-    capsec::tokio::fs::read_to_string("/etc/app/config.toml", ctx).await
-}
+let ctx = Arc::new(AppCtx::new(&root));
+
+let ctx2 = Arc::clone(&ctx);
+tokio::spawn(async move {
+    let data = capsec::tokio::fs::read("/tmp/data", &*ctx2).await?;
+});
 ```
 
 ## Modules
@@ -31,6 +64,7 @@ Enable via feature flags (`full` enables all):
 
 | Module | Feature | Permission required | What it wraps |
 |--------|---------|-------------------|---------------|
+| `task` | `rt` | — | `tokio::spawn` — capability-aware task spawning |
 | `fs` | `fs` | `FsRead` / `FsWrite` | `tokio::fs` — read, write, delete, rename, copy, open, create |
 | `net` | `net` | `NetConnect` / `NetBind` | `tokio::net` — TCP connect, TCP/UDP bind |
 | `process` | `process` | `Spawn` | `tokio::process` — Command::new, run |

crates/capsec-tokio/src/lib.rs

@@ -11,10 +11,84 @@
 //!
 //! Enable via feature flags:
 //!
+//! - `rt` — task spawning with capability transfer ([`task::spawn_with`])
 //! - `fs` — async filesystem operations (`tokio::fs`)
 //! - `net` — async network operations (`tokio::net`)
 //! - `process` — async subprocess execution (`tokio::process`)
 //! - `full` — all of the above
+//!
+//! # Capsec + Tokio Guide
+//!
+//! There are three common patterns for using capabilities in async code,
+//! depending on whether you're spawning tasks and how many capabilities
+//! you need.
+//!
+//! ## Pattern 1: Scoped proof (no spawn)
+//!
+//! When your async code runs on the current task (no `tokio::spawn`), pass
+//! capabilities by reference. The scope-before-await pattern inside each
+//! wrapper keeps futures `Send` automatically.
+//!
+//! ```no_run
+//! use capsec_core::has::Has;
+//! use capsec_core::permission::FsRead;
+//!
+//! async fn handle_request(cap: &impl Has<FsRead>) {
+//!     let data = capsec_tokio::fs::read("/tmp/config.toml", cap).await.unwrap();
+//!     // ...
+//! }
+//! ```
+//!
+//! ## Pattern 2: `spawn_with` (single capability)
+//!
+//! When spawning a task that needs one capability, use
+//! [`task::spawn_with`]. It converts `Cap<P>` to `SendCap<P>` for you —
+//! no need to call `.make_send()` manually.
+//!
+//! ```no_run
+//! use capsec_core::permission::FsRead;
+//!
+//! # async fn example(root: capsec_core::root::CapRoot) {
+//! let cap = root.grant::<FsRead>();
+//!
+//! let handle = capsec_tokio::task::spawn_with(cap, |cap| async move {
+//!     capsec_tokio::fs::read("/tmp/data.bin", &cap).await.unwrap()
+//! });
+//!
+//! let data = handle.await.unwrap();
+//! # }
+//! ```
+//!
+//! ## Pattern 3: `Arc` context (multiple capabilities)
+//!
+//! When a spawned task needs multiple capabilities, use
+//! `#[capsec::context(send)]` to create a `Send`-safe context struct,
+//! wrap it in `Arc`, and clone for each task.
+//!
+//! ```no_run
+//! use std::sync::Arc;
+//!
+//! // The `send` flag generates SendCap<P> fields instead of Cap<P>
+//! #[capsec_macro::context(send)]
+//! struct AppCtx {
+//!     fs: capsec_core::permission::FsRead,
+//!     net: capsec_core::permission::NetConnect,
+//! }
+//!
+//! # async fn example(root: capsec_core::root::CapRoot) {
+//! let ctx = Arc::new(AppCtx::new(&root));
+//!
+//! let ctx2 = Arc::clone(&ctx);
+//! tokio::spawn(async move {
+//!     let data = capsec_tokio::fs::read("/tmp/data", &*ctx2).await.unwrap();
+//! });
+//!
+//! let ctx3 = Arc::clone(&ctx);
+//! tokio::spawn(async move {
+//!     let stream = capsec_tokio::net::tcp_connect("127.0.0.1:8080", &*ctx3).await.unwrap();
+//! });
+//! # }
+//! ```
 
 #[cfg(feature = "fs")]
 pub mod file;
@@ -24,3 +98,5 @@ pub mod fs;
 pub mod net;
 #[cfg(feature = "process")]
 pub mod process;
+#[cfg(feature = "rt")]
+pub mod task;

crates/capsec-tokio/src/task.rs

@@ -0,0 +1,58 @@
+//! Task spawning with capability transfer.
+//!
+//! [`spawn_with`] is a convenience wrapper around [`tokio::spawn`] that handles
+//! the `Cap<P>` → `SendCap<P>` conversion automatically. Without it, users
+//! must manually call `.make_send()` before spawning — a common source of
+//! confusing `!Send` compiler errors.
+//!
+//! # Example
+//!
+//! ```no_run
+//! use capsec_core::permission::FsRead;
+//!
+//! # async fn example(root: capsec_core::root::CapRoot) {
+//! let cap = root.grant::<FsRead>();
+//!
+//! let handle = capsec_tokio::task::spawn_with(cap, |cap| async move {
+//!     capsec_tokio::fs::read("/tmp/data.bin", &cap).await.unwrap()
+//! });
+//!
+//! let data = handle.await.unwrap();
+//! # }
+//! ```
+
+use capsec_core::cap::{Cap, SendCap};
+use capsec_core::permission::Permission;
+use std::future::Future;
+
+/// Spawns a tokio task with a capability, handling the `Send` conversion.
+///
+/// Takes a `Cap<P>` (which is `!Send`), converts it to a `SendCap<P>`, and
+/// passes it into the closure that produces the spawned future. This removes
+/// the need to manually call `.make_send()`.
+///
+/// # Example
+///
+/// ```no_run
+/// use capsec_core::permission::FsRead;
+///
+/// # async fn example(root: capsec_core::root::CapRoot) {
+/// let cap = root.grant::<FsRead>();
+///
+/// let handle = capsec_tokio::task::spawn_with(cap, |cap| async move {
+///     capsec_tokio::fs::read("/tmp/data.bin", &cap).await.unwrap()
+/// });
+///
+/// let data = handle.await.unwrap();
+/// # }
+/// ```
+pub fn spawn_with<P, F, Fut, T>(cap: Cap<P>, f: F) -> tokio::task::JoinHandle<T>
+where
+    P: Permission,
+    F: FnOnce(SendCap<P>) -> Fut + Send + 'static,
+    Fut: Future<Output = T> + Send + 'static,
+    T: Send + 'static,
+{
+    let send_cap = cap.make_send();
+    tokio::spawn(f(send_cap))
+}

crates/capsec-tokio/tests/async_io.rs

@@ -144,3 +144,26 @@ async fn context_struct_works_with_async_wrappers() {
     let data = capsec_tokio::fs::read("/dev/null", &ctx).await.unwrap();
     assert!(data.is_empty());
 }
+
+#[tokio::test]
+async fn spawn_with_single_cap() {
+    let root = test_root();
+    let cap = root.fs_read();
+    let handle = capsec_tokio::task::spawn_with(cap, |cap| async move {
+        capsec_tokio::fs::read("/dev/null", &cap).await.unwrap()
+    });
+    let data = handle.await.unwrap();
+    assert!(data.is_empty());
+}
+
+#[tokio::test]
+async fn spawn_with_future_is_send() {
+    fn assert_send<T: Send>(_: &T) {}
+    let root = test_root();
+    let cap = root.fs_read();
+    let handle = capsec_tokio::task::spawn_with(cap, |cap| async move {
+        capsec_tokio::fs::read("/dev/null", &cap).await.unwrap()
+    });
+    assert_send(&handle);
+    let _ = handle.await.unwrap();
+}

crates/capsec/src/lib.rs

@@ -90,6 +90,10 @@ pub mod process {
 /// ```
 #[cfg(feature = "tokio")]
 pub mod tokio {
+    /// Task spawning with capability transfer.
+    pub mod task {
+        pub use capsec_tokio::task::*;
+    }
     /// Async capability-gated filesystem operations.
     pub mod fs {
         pub use capsec_tokio::file::{AsyncReadFile, AsyncWriteFile};