Added some useful methods and docs

cedar-policy-core/src/ast/entity.rs

@@ -317,8 +317,17 @@ pub struct Entity {
     ancestors: HashSet<EntityUID>,
 }
 
+impl std::hash::Hash for Entity {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.uid.hash(state);
+    }
+}
+
 impl Entity {
     /// Create a new `Entity` with this UID, attributes, and ancestors
+    ///
+    /// # Errors
+    /// - Will error if any of the [`RestrictedExpr]`s in `attrs` error when evaluated
     pub fn new(
         uid: EntityUID,
         attrs: HashMap<SmolStr, RestrictedExpr>,
@@ -346,6 +355,13 @@ impl Entity {
         })
     }
 
+    /// Create a new `Entity` with this UID, ancestors, and an empty set of attributes
+    ///
+    /// Since there are no attributes, this method does not error, and returns `Self` instead of `Result<Self>`
+    pub fn new_empty_attrs(uid: EntityUID, ancestors: HashSet<EntityUID>) -> Self {
+        Self::new_with_attr_partial_value(uid, HashMap::new(), ancestors)
+    }
+
     /// Create a new `Entity` with this UID, attributes, and ancestors.
     ///
     /// Unlike in `Entity::new()`, in this constructor, attributes are expressed

cedar-policy-core/src/entities.rs

@@ -162,6 +162,13 @@ impl Entities {
     ///
     /// If you pass `TCComputation::AssumeAlreadyComputed`, then the caller is
     /// responsible for ensuring that TC and DAG hold before calling this method.
+    ///
+    /// # Errors
+    /// - [`EntitiesError::Duplicate`] if there are any duplicate entities in `entities`
+    /// - [`EntitiesError::TransitiveClosureError`] if `tc_computation ==
+    ///   TCComputation::EnforceAlreadyComputed` and the entities are not transitivly closed
+    /// - [`EntitiesError::InvalidEntity`] if `schema` is not none and any entities do not conform
+    ///   to the schema
     pub fn from_entities(
         entities: impl IntoIterator<Item = Entity>,
         schema: Option<&impl Schema>,
@@ -817,7 +824,7 @@ mod json_parsing_tests {
         parser.from_json_value(json).expect("JSON is correct")
     }
 
-    /// Ensure the initial conditions of the entiites still hold
+    /// Ensure the initial conditions of the entities still hold
     fn simple_entities_still_sane(e: &Entities) {
         let bob = r#"Test::"bob""#.parse().unwrap();
         let alice = e.entity(&r#"Test::"alice""#.parse().unwrap()).unwrap();

cedar-policy/CHANGELOG.md

@@ -17,6 +17,10 @@ Cedar Language Version: TBD
   that provides the Entity Manifest: a data
   structure that describes what data is required to satisfy a
   Cedar request. To use this API you must enable the `entity-manifest` feature flag.
+- `Entity` is now `Hash`. The hash implementation compares the hash of
+  the entity UID
+- `Entity::new_empty_attrs` utility constructor that can't error 
+
 
 ## [4.0.0] - Coming soon
 Cedar Language Version: 4.0

cedar-policy/src/api.rs

@@ -61,7 +61,7 @@ use std::str::FromStr;
 
 /// Entity datatype
 #[repr(transparent)]
-#[derive(Debug, Clone, PartialEq, Eq, RefCast)]
+#[derive(Debug, Clone, PartialEq, Eq, RefCast, Hash)]
 pub struct Entity(ast::Entity);
 
 impl Entity {
@@ -104,6 +104,16 @@ impl Entity {
         )?))
     }
 
+    /// Create a new `Entity` with this Uid, parents, and no attributes.
+    /// This is the same as `Self::new` except the attributes are empty, and therefore it can
+    /// return `Self` instead of `Result<Self>`
+    pub fn new_empty_attrs(uid: EntityUid, parents: HashSet<EntityUid>) -> Self {
+        Self(ast::Entity::new_empty_attrs(
+            uid.into(),
+            parents.into_iter().map(EntityUid::into).collect(),
+        ))
+    }
+
     /// Create a new `Entity` with no attributes.
     ///
     /// Unlike [`Entity::new()`], this constructor cannot error.
@@ -345,6 +355,10 @@ impl Entities {
     /// error if attributes have the wrong types (e.g., string instead of
     /// integer), or if required attributes are missing or superfluous
     /// attributes are provided.
+    /// ## Errors
+    /// - [`EntitiesError::Duplicate`] if there are any duplicate entities in `entities`
+    /// - [`EntitiesError::InvalidEntity`] if `schema` is not none and any entities do not conform
+    ///   to the schema
     pub fn from_entities(
         entities: impl IntoIterator<Item = Entity>,
         schema: Option<&Schema>,
@@ -371,6 +385,10 @@ impl Entities {
     ///
     /// Re-computing the transitive closure can be expensive, so it is advised
     /// to not call this method in a loop.
+    /// ## Errors
+    /// - [`EntitiesError::Duplicate`] if there are any duplicate entities in `entities`
+    /// - [`EntitiesError::InvalidEntity`] if `schema` is not none and any entities do not conform
+    ///   to the schema
     pub fn add_entities(
         self,
         entities: impl IntoIterator<Item = Entity>,
@@ -401,6 +419,11 @@ impl Entities {
     ///
     /// Re-computing the transitive closure can be expensive, so it is advised
     /// to not call this method in a loop.
+    /// ## Errors
+    /// - [`EntitiesError::Duplicate`] if there are any duplicate entities in `entities`
+    /// - [`EntitiesError::InvalidEntity`] if `schema` is not none and any entities do not conform
+    ///   to the schema
+    /// - [`EntitiesError::Deserialization`] if there are errors while parsing the json
     pub fn add_entities_from_json_str(
         self,
         json: &str,
@@ -434,6 +457,11 @@ impl Entities {
     ///
     /// Re-computing the transitive closure can be expensive, so it is advised
     /// to not call this method in a loop.
+    /// ## Errors
+    /// - [`EntitiesError::Duplicate`] if there are any duplicate entities in `entities`
+    /// - [`EntitiesError::InvalidEntity`] if `schema` is not none and any entities do not conform
+    ///   to the schema
+    /// - [`EntitiesError::Deserialization`] if there are errors while parsing the json
     pub fn add_entities_from_json_value(
         self,
         json: serde_json::Value,
@@ -467,6 +495,12 @@ impl Entities {
     ///
     /// Re-computing the transitive closure can be expensive, so it is advised
     /// to not call this method in a loop.
+    ///
+    /// ## Errors
+    /// - [`EntitiesError::Duplicate`] if there are any duplicate entities in `entities`
+    /// - [`EntitiesError::InvalidEntity`] if `schema` is not none and any entities do not conform
+    ///   to the schema
+    /// - [`EntitiesError::Deserialization`] if there are errors while parsing the json
     pub fn add_entities_from_json_file(
         self,
         json: impl std::io::Read,
@@ -504,6 +538,12 @@ impl Entities {
     /// instead of integer), or if required attributes are missing or
     /// superfluous attributes are provided.
     ///
+    /// ## Errors
+    /// - [`EntitiesError::Duplicate`] if there are any duplicate entities in `entities`
+    /// - [`EntitiesError::InvalidEntity`] if `schema` is not none and any entities do not conform
+    ///   to the schema
+    /// - [`EntitiesError::Deserialization`] if there are errors while parsing the json
+    ///
     /// ```
     /// # use cedar_policy::{Entities, EntityId, EntityTypeName, EntityUid, EvalResult, Request,PolicySet};
     /// # use std::str::FromStr;
@@ -559,6 +599,12 @@ impl Entities {
     /// instead of integer), or if required attributes are missing or
     /// superfluous attributes are provided.
     ///
+    /// ## Errors
+    /// - [`EntitiesError::Duplicate`] if there are any duplicate entities in `entities`
+    /// - [`EntitiesError::InvalidEntity`]if `schema` is not none and any entities do not conform
+    ///   to the schema
+    /// - [`EntitiesError::Deserialization`] if there are errors while parsing the json
+    ///
     /// ```
     /// # use cedar_policy::{Entities, EntityId, EntityTypeName, EntityUid, EvalResult, Request,PolicySet};
     /// let data =serde_json::json!(
@@ -610,6 +656,12 @@ impl Entities {
     /// instance, it will error if attributes have the wrong types (e.g., string
     /// instead of integer), or if required attributes are missing or
     /// superfluous attributes are provided.
+    ///
+    /// ## Errors
+    /// - [`EntitiesError::Duplicate`] if there are any duplicate entities in `entities`
+    /// - [`EntitiesError::InvalidEntity`] if `schema` is not none and any entities do not conform
+    ///   to the schema
+    /// - [`EntitiesError::Deserialization`] if there are errors while parsing the json
     pub fn from_json_file(
         json: impl std::io::Read,
         schema: Option<&Schema>,
@@ -1492,7 +1544,7 @@ impl Schema {
 
     /// Returns an iterator over every entity type that can be a principal for `action` in this schema
     ///
-    /// # Errors
+    /// ## Errors
     ///
     /// Returns [`None`] if `action` is not found in the schema
     pub fn principals_for_action(
@@ -1506,7 +1558,7 @@ impl Schema {
 
     /// Returns an iterator over every entity type that can be a resource for `action` in this schema
     ///
-    /// # Errors
+    /// ## Errors
     ///
     /// Returns [`None`] if `action` is not found in the schema
     pub fn resources_for_action(
@@ -1520,7 +1572,7 @@ impl Schema {
 
     /// Returns an iterator over all the entity types that can be an ancestor of `ty`
     ///
-    /// # Errors
+    /// ## Errors
     ///
     /// Returns [`None`] if the `ty` is not found in the schema
     pub fn ancestors<'a>(