From c55e6b2ce22be7ab5a0166735b3c4176506b162b Mon Sep 17 00:00:00 2001 From: Geoffroy Couprie Date: Thu, 28 Nov 2024 11:02:15 +0100 Subject: [PATCH] doc --- biscuit-auth/src/lib.rs | 22 +++++++++++++------- biscuit-auth/src/macros.rs | 21 ++++++++++++------- biscuit-auth/src/token/authorizer.rs | 18 +++++++++------- biscuit-auth/src/token/builder/authorizer.rs | 19 +++++++++-------- biscuit-auth/src/token/mod.rs | 21 ++++++++++--------- 5 files changed, 58 insertions(+), 43 deletions(-) diff --git a/biscuit-auth/src/lib.rs b/biscuit-auth/src/lib.rs index f5719a3a..10df1b8b 100644 --- a/biscuit-auth/src/lib.rs +++ b/biscuit-auth/src/lib.rs @@ -88,7 +88,7 @@ //! // - one for /a/file1.txt and a write operation //! // - one for /a/file2.txt and a read operation //! -//! let v1 = authorizer!(r#" +//! let mut v1 = authorizer!(r#" //! resource("/a/file1.txt"); //! operation("read"); //! @@ -101,26 +101,32 @@ //! // explicit catch-all deny. here it is not necessary: if no policy //! // matches, a default deny applies //! deny if true; -//! "#); +//! "#) +//! .add_token(&biscuit2) +//! .build()?; //! //! let mut v2 = authorizer!(r#" //! resource("/a/file1.txt"); //! operation("write"); //! allow if right("/a/file1.txt", "write"); -//! "#); -//! +//! "#) +//! .add_token(&biscuit2) +//! .build()?; +//! //! let mut v3 = authorizer!(r#" //! resource("/a/file2.txt"); //! operation("read"); //! allow if right("/a/file2.txt", "read"); -//! "#); +//! "#) +//! .add_token(&biscuit2) +//! .build()?; //! //! // the token restricts to read operations: -//! assert!(biscuit2.authorize(&v1).is_ok()); +//! assert!(v1.authorize().is_ok()); //! // the second verifier requested a read operation -//! assert!(biscuit2.authorize(&v2).is_err()); +//! assert!(v2.authorize().is_err()); //! // the third verifier requests /a/file2.txt -//! assert!(biscuit2.authorize(&v3).is_err()); +//! assert!(v3.authorize().is_err()); //! //! Ok(()) //! } diff --git a/biscuit-auth/src/macros.rs b/biscuit-auth/src/macros.rs index cbd47669..a0075b72 100644 --- a/biscuit-auth/src/macros.rs +++ b/biscuit-auth/src/macros.rs @@ -26,7 +26,7 @@ //! expiration = SystemTime::now() + Duration::from_secs(86_400), //! )).expect("Failed to append block"); //! -//! new_biscuit.authorize(&authorizer!( +//! authorizer!( //! r#" //! time({now}); //! operation({operation}); @@ -42,7 +42,12 @@ //! operation = "read", //! resource = "file1", //! user_id = "1234", -//! )).expect("Failed to authorize biscuit"); +//! ) +//! .add_token(&new_biscuit) +//! .build() +//! .expect("failed to build the authorizer") +//! .authorize() +//! .expect("Failed to authorize biscuit"); //! ``` /// Create an `Authorizer` from a datalog string and optional parameters. @@ -78,8 +83,8 @@ pub use biscuit_quote::authorizer; /// now = SystemTime::now() /// ); /// -/// authorizer_merge!( -/// &mut b, +/// b = authorizer_merge!( +/// b, /// r#" /// allow if true; /// "# @@ -128,8 +133,8 @@ pub use biscuit_quote::biscuit; /// user_id = "1234" /// ); /// -/// biscuit_merge!( -/// &mut b, +/// b = biscuit_merge!( +/// b, /// r#" /// check if time($time), $time < {expiration} /// "#, @@ -173,8 +178,8 @@ pub use biscuit_quote::block; /// user_id = "1234" /// ); /// -/// block_merge!( -/// &mut b, +/// b = block_merge!( +/// b, /// r#" /// check if user($id); /// "# diff --git a/biscuit-auth/src/token/authorizer.rs b/biscuit-auth/src/token/authorizer.rs index bf594a95..a2e6e86b 100644 --- a/biscuit-auth/src/token/authorizer.rs +++ b/biscuit-auth/src/token/authorizer.rs @@ -110,10 +110,11 @@ impl Authorizer { /// # use biscuit_auth::Biscuit; /// # use biscuit_auth::builder::Algorithm; /// let keypair = KeyPair::new(Algorithm::Ed25519); - /// let mut builder = Biscuit::builder(); - /// builder.add_fact("user(\"John Doe\", 42)"); - /// - /// let biscuit = builder.build(&keypair).unwrap(); + /// let biscuit = Biscuit::builder() + /// .add_fact("user(\"John Doe\", 42)") + /// .expect("parse error") + /// .build(&keypair) + /// .unwrap(); /// /// let mut authorizer = biscuit.authorizer().unwrap(); /// let res: Vec<(String, i64)> = authorizer.query("data($name, $id) <- user($name, $id)").unwrap(); @@ -200,10 +201,11 @@ impl Authorizer { /// # use biscuit_auth::Biscuit; /// # use biscuit_auth::builder::Algorithm; /// let keypair = KeyPair::new(Algorithm::Ed25519,); - /// let mut builder = Biscuit::builder(); - /// builder.add_fact("user(\"John Doe\", 42)"); - /// - /// let biscuit = builder.build(&keypair).unwrap(); + /// let biscuit = Biscuit::builder() + /// .add_fact("user(\"John Doe\", 42)") + /// .expect("parse error") + /// .build(&keypair) + /// .unwrap(); /// /// let mut authorizer = biscuit.authorizer().unwrap(); /// let res: Vec<(String, i64)> = authorizer.query_all("data($name, $id) <- user($name, $id)").unwrap(); diff --git a/biscuit-auth/src/token/builder/authorizer.rs b/biscuit-auth/src/token/builder/authorizer.rs index c6f448a1..87d0c5af 100644 --- a/biscuit-auth/src/token/builder/authorizer.rs +++ b/biscuit-auth/src/token/builder/authorizer.rs @@ -61,18 +61,19 @@ impl<'a> AuthorizerBuilder<'a> { /// ```rust /// extern crate biscuit_auth as biscuit; /// - /// use biscuit::Authorizer; + /// use biscuit::builder::AuthorizerBuilder; /// - /// let mut authorizer = Authorizer::new(); + /// let mut authorizer = AuthorizerBuilder::new() + /// .add_code(r#" + /// resource("/file1.txt"); /// - /// authorizer.add_code(r#" - /// resource("/file1.txt"); + /// check if user(1234); /// - /// check if user(1234); - /// - /// // default allow - /// allow if true; - /// "#).expect("should parse correctly"); + /// // default allow + /// allow if true; + /// "#) + /// .expect("should parse correctly") + /// .build(); /// ``` pub fn add_code>(self, source: T) -> Result { self.add_code_with_params(source, HashMap::new(), HashMap::new()) diff --git a/biscuit-auth/src/token/mod.rs b/biscuit-auth/src/token/mod.rs index 79d82975..fd9a5bb4 100644 --- a/biscuit-auth/src/token/mod.rs +++ b/biscuit-auth/src/token/mod.rs @@ -54,25 +54,26 @@ pub fn default_symbol_table() -> SymbolTable { /// /// use biscuit::{KeyPair, Biscuit, builder::*, builder_ext::*}; /// -/// fn main() { +/// fn main() -> Result<(), biscuit::error::Token> { /// let root = KeyPair::new(Algorithm::Ed25519); /// /// // first we define the authority block for global data, /// // like access rights /// // data from the authority block cannot be created in any other block -/// let mut builder = Biscuit::builder(); -/// builder.add_fact(fact("right", &[string("/a/file1.txt"), string("read")])); +/// let token1 = Biscuit::builder() +/// .add_fact(fact("right", &[string("/a/file1.txt"), string("read")]))? /// -/// // facts and rules can also be parsed from a string -/// builder.add_fact("right(\"/a/file1.txt\", \"read\")").expect("parse error"); -/// -/// let token1 = builder.build(&root).unwrap(); +/// // facts and rules can also be parsed from a string +/// .add_fact("right(\"/a/file1.txt\", \"read\")")? +/// .build(&root)?; /// /// // we can create a new block builder from that token -/// let mut builder2 = BlockBuilder::new(); -/// builder2.check_operation("read"); +/// let builder2 = BlockBuilder::new() +/// .check_operation("read"); +/// +/// let token2 = token1.append(builder2)?; /// -/// let token2 = token1.append(builder2).unwrap(); +/// Ok(()) /// } /// ``` #[derive(Clone, Debug)]