Merge pull request #65 from manomayam/feat-docs-up

feat: add readme for fcrates

Cargo.toml

@@ -29,10 +29,10 @@ members = [
     "crates/manas_storage",
     "crates/manas_podverse",
     "crates/manas_server",
-    # "crates/manas_server/recipes/single_fs_wac",
-    # "crates/manas_server/recipes/single_fs_noauth",
-    # "crates/manas_server/recipes/single_s3_wac",
-    # "crates/manas"
+    "crates/manas_server/recipes/single_fs_wac",
+    "crates/manas_server/recipes/single_fs_noauth",
+    "crates/manas_server/recipes/single_s3_wac",
+    "crates/manas"
     # "crates/manas_tauri"
 ]
 

fcrates/acp/README.md

@@ -0,0 +1,6 @@
+# acp
+
+An implementation of [access control policy](https://solid.github.io/authorization-panel/acp-specification/) concepts and engine for rust.
+
+
+License: MIT OR Apache-2.0

fcrates/capped_stream/README.md

@@ -0,0 +1,6 @@
+# capped_stream
+
+This crate provides types for size capped streams.
+
+
+License: MIT OR Apache-2.0

fcrates/dpop/README.md

@@ -0,0 +1,6 @@
+# dpop
+
+This crate provides rust implementation of [DPoP](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-14).
+
+
+License: MIT OR Apache-2.0

fcrates/gdp_rs/Cargo.toml

@@ -19,6 +19,10 @@ serde = { version = "1.0.203", optional = true }
 [features]
 serde = ["dep:serde"]
 
+[dev-dependencies]
+iri-string = "0.7.2"
+thiserror = "1.0.61"
+
 [package.metadata.docs.rs]
 all-features = true
 rustdoc-args = ["--cfg", "doc_cfg"]

fcrates/gdp_rs/README.md

@@ -0,0 +1,21 @@
+# gdp_rs
+
+This crate provides utilities to employ [Ghosts-of-Departed-Proofs](https://kataskeue.com/gdp.pdf)
+pattern in rust projects.
+This enables type drive development following [Parse, don't validate](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/) principle.
+
+The idea is that, instead of checking or validating the values of a Type for
+satisfying certain properties, one create a wrapper refined new type that
+can only constructed from the values satisfying desired predicates.
+Thus, one can centralize the validation mechanism, and use typesystem to
+enforce right invariant.
+
+This crate provides a type [`Proven`], which is generic over the predicate type.
+It can be instantiated only from valid subject values of a type, satisfying the
+predicate function.
+
+The crate also provides combinatrics over multiple predicates, so that one
+compose a compound predicate type from list of other predicate type.
+
+
+License: MIT OR Apache-2.0

fcrates/gdp_rs/examples/simple.rs

@@ -0,0 +1,66 @@
+//! This example demonstrates on creating a refinement type satisfying a single predicate.
+//!
+
+use gdp_rs::{
+    predicate::{Predicate, PurePredicate, SyncEvaluablePredicate},
+    Proven,
+};
+
+/// A struct for representing a password, that allows arbitrary string value.
+struct Password {
+    value: String,
+}
+
+/// A predicate type overt [`Password`], that checks if it is strong.
+#[derive(Debug)]
+struct IsStrong {}
+
+// Implement predicate contract over subject values of [``Password`] type.
+impl Predicate<Password> for IsStrong {
+    fn label() -> std::borrow::Cow<'static, str> {
+        "IsStrong".into()
+    }
+}
+
+impl SyncEvaluablePredicate<Password> for IsStrong {
+    type EvalError = IsNotStrong;
+
+    fn evaluate_for(sub: &Password) -> Result<(), Self::EvalError> {
+        let p = &sub.value;
+        // We have simple check of length for password strength.
+        if p.len() >= 8 {
+            Ok(())
+        } else {
+            Err(IsNotStrong)
+        }
+    }
+}
+
+/// Mark predicate as pure.
+impl PurePredicate<Password> for IsStrong {}
+
+/// Define alias for refined new type.
+type StrongPassword = Proven<Password, IsStrong>;
+
+/// Now use the newtype. No need of further validation inside the function.
+fn set_password(_username: String, _password: StrongPassword) {
+    // ...
+}
+
+/// Error type for predicate.
+#[derive(Debug, thiserror::Error)]
+#[error("Given password is not a strong password")]
+struct IsNotStrong;
+
+fn main() {
+    let password_input = Password {
+        value: "anc1234f".into(),
+    };
+
+    let validated_password = StrongPassword::try_new(password_input).unwrap_or_else(|e| {
+        let sub = e.subject;
+        panic!("Entered password {} is not strong", sub.value);
+    });
+
+    set_password("username".into(), validated_password);
+}

fcrates/gdp_rs/src/binclassified.rs

@@ -3,7 +3,7 @@
 
 use std::ops::Deref;
 
-use either::Either;
+pub use either::Either;
 
 use crate::{
     predicate::{PurePredicate, SyncEvaluablePredicate},

fcrates/gdp_rs/src/lib.rs

@@ -1,5 +1,20 @@
-//! I define types for using [Ghosts-of-Departed-Proofs](https://kataskeue.com/gdp.pdf) pattern in rust.
+//! This crate provides utilities to employ [Ghosts-of-Departed-Proofs](https://kataskeue.com/gdp.pdf)
+//! pattern in rust projects.
+//! This enables type drive development following [Parse, don't validate](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/) principle.
 //!
+//! The idea is that, instead of checking or validating the values of a Type for
+//! satisfying certain properties, one create a wrapper refined new type that
+//! can only constructed from the values satisfying desired predicates.
+//! Thus, one can centralize the validation mechanism, and use typesystem to
+//! enforce right invariant.
+//! 
+//! This crate provides a type [`Proven`], which is generic over the predicate type.
+//! It can be instantiated only from valid subject values of a type, satisfying the 
+//! predicate function.
+//! 
+//! The crate also provides combinatrics over multiple predicates, so that one
+//! compose a compound predicate type from list of other predicate type.
+//! 
 
 #![warn(missing_docs)]
 #![cfg_attr(doc_cfg, feature(doc_auto_cfg))]

fcrates/gdp_rs/src/predicate/impl_/all_of.rs

@@ -2,10 +2,14 @@
 
 use std::{borrow::Cow, marker::PhantomData};
 
+pub use frunk_core::{
+    hlist::{HCons, HNil},
+    HList,
+};
+
 use frunk_core::{
-    hlist::{HCons, HNil, Plucker, Sculptor},
+    hlist::{Plucker, Sculptor},
     traits::IntoReverse,
-    HList,
 };
 
 use crate::{

fcrates/http_typed_headers/Cargo.toml

@@ -54,7 +54,7 @@ accept-method = ["media-type"]
 ##! Enables `Link` typed header.
 link = ["dep:iri-string"]
 ##! Enables `Location` typed header.
-location = ["dep:iri-string", "itertools"]
+location = ["dep:iri-string", "dep:itertools"]
 ##! Enables `Forwarded`, `X-Forwarded-*` typed headers.
 forwarded = []
 ##! Enables `Prefer` typed header.

fcrates/http_typed_headers/README.md

@@ -0,0 +1,6 @@
+# http_typed_headers
+
+This crate provides few typed http headers.
+
+
+License: MIT OR Apache-2.0

fcrates/http_typed_headers/src/lib.rs

@@ -50,3 +50,11 @@ pub mod wac_allow;
 
 #[cfg(feature = "www-authenticate")]
 pub mod www_authenticate;
+
+
+// Re exports
+#[cfg(feature = "media-type")]
+pub use mime;
+
+#[cfg(any(feature = "link", feature = "location"))]
+pub use iri_string;

fcrates/http_uri/README.md

@@ -0,0 +1,6 @@
+# http_uri
+
+This crate provides types for representing http uris and their invariants.
+
+
+License: MIT OR Apache-2.0

fcrates/http_uri/src/lib.rs

@@ -19,6 +19,12 @@ use iri_string::{
 };
 use unicase::Ascii;
 
+// Reexports
+pub use iri_string;
+
+#[cfg(feature = "invariants")]
+pub use {frunk_core, gdp_rs};
+
 #[cfg(feature = "invariants")]
 pub mod invariant;
 #[cfg(feature = "invariants")]

fcrates/name_locker/README.md

@@ -0,0 +1,9 @@
+# name_locker
+
+This crate defines trait for asynchronous name lockers,
+that can run an async task with advisory-lock on a given name.
+
+It also provides a default inmemory implementation.
+
+
+License: MIT OR Apache-2.0

fcrates/name_locker/src/lib.rs

@@ -1,8 +1,7 @@
 //! This crate defines trait for asynchronous name lockers,
 //! that can run an async task with advisory-lock on a given name.
 //!
-//! It also provides a default inmemory implementation
-//! using dashmap.
+//! It also provides a default inmemory implementation.
 //!
 
 #![warn(missing_docs)]
@@ -11,7 +10,7 @@
 
 use std::hash::Hash;
 
-use futures::{future::BoxFuture, stream::BoxStream, Future, Stream};
+pub use futures::{future::BoxFuture, stream::BoxStream, Future, Stream};
 
 pub mod impl_;