doc

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(())
 //! }

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);
 ///   "#

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();

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<T: AsRef<str>>(self, source: T) -> Result<Self, error::Token> {
         self.add_code_with_params(source, HashMap::new(), HashMap::new())

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)]