Struct Entities

pub struct Entities(/* private fields */);

Represents an entity hierarchy, and allows looking up Entity objects by Uid.

Implementations

impl Entities

pub fn empty() -> Self

Create a fresh Entities with no entities

let entities = Entities::empty();

pub fn get(&self, uid: &EntityUid) -> Option<&Entity>

Get the Entity with the given Uid, if any

pub fn partial(self) -> Self

Available on crate feature partial-eval only.

Transform the store into a partial store, where attempting to dereference a non-existent EntityUID results in a residual instead of an error.

This feature is experimental. For more information see https://github.com/cedar-policy/rfcs/blob/main/README.md#experimental-features

pub fn iter(&self) -> impl Iterator<Item = &Entity>

Iterate over the Entity’s in the Entities

pub fn from_entities( entities: impl IntoIterator<Item = Entity>, schema: Option<&Schema>, ) -> Result<Self, EntitiesError>

Create an Entities object with the given entities.

schema represents a source of Action entities, which will be added to the entities provided. (If any Action entities are present in the provided entities, and a schema is also provided, each Action entity in the provided entities must exactly match its definition in the schema or an error is returned.)

If a schema is present, this function will also ensure that the produced entities fully conform to the schema – for 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

pub fn add_entities( self, entities: impl IntoIterator<Item = Entity>, schema: Option<&Schema>, ) -> Result<Self, EntitiesError>

Add all of the Entitys in the collection to this Entities structure, re-computing the transitive closure.

If a schema is provided, this method will ensure that the added entities fully conform to the schema – for 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. (This method will not add action entities from the schema.)

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_from_json_str( self, json: &str, schema: Option<&Schema>, ) -> Result<Self, EntitiesError>

Parse an entities JSON file (in &str form) and add them into this Entities structure, re-computing the transitive closure

If a schema is provided, this will inform the parsing: for instance, it will allow __entity and __extn escapes to be implicit. This method will also ensure that the added entities fully conform to the schema – for 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. (This method will not add action entities from the schema.)

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: Value, schema: Option<&Schema>, ) -> Result<Self, EntitiesError>

Parse an entities JSON file (in serde_json::Value form) and add them into this Entities structure, re-computing the transitive closure

If a schema is provided, this will inform the parsing: for instance, it will allow __entity and __extn escapes to be implicit. This method will also ensure that the added entities fully conform to the schema – for 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. (This method will not add action entities from the schema.)

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 Read, schema: Option<&Schema>, ) -> Result<Self, EntitiesError>

Parse an entities JSON file (in std::io::Read form) and add them into this Entities structure, re-computing the transitive closure

If a schema is provided, this will inform the parsing: for instance, it will allow __entity and __extn escapes to be implicit. This method will also ensure that the added entities fully conform to the schema – for 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. (This method will not add action entities from the schema.)

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 from_json_str( json: &str, schema: Option<&Schema>, ) -> Result<Self, EntitiesError>

Parse an entities JSON file (in &str form) into an Entities object

schema represents a source of Action entities, which will be added to the entities parsed from JSON. (If any Action entities are present in the JSON, and a schema is also provided, each Action entity in the JSON must exactly match its definition in the schema or an error is returned.)

If a schema is present, this will also inform the parsing: for instance, it will allow __entity and __extn escapes to be implicit.

Finally, if a schema is present, this function will ensure that the produced entities fully conform to the schema – for 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

let data =r#"
[
{
  "uid": {"type":"User","id":"alice"},
  "attrs": {
    "age":19,
    "ip_addr":{"__extn":{"fn":"ip", "arg":"10.0.1.101"}}
  },
  "parents": [{"type":"Group","id":"admin"}]
},
{
  "uid": {"type":"Group","id":"admin"},
  "attrs": {},
  "parents": []
}
]
"#;
let entities = Entities::from_json_str(data, None).unwrap();

pub fn from_json_value( json: Value, schema: Option<&Schema>, ) -> Result<Self, EntitiesError>

Parse an entities JSON file (in serde_json::Value form) into an Entities object

schema represents a source of Action entities, which will be added to the entities parsed from JSON. (If any Action entities are present in the JSON, and a schema is also provided, each Action entity in the JSON must exactly match its definition in the schema or an error is returned.)

If a schema is present, this will also inform the parsing: for instance, it will allow __entity and __extn escapes to be implicit.

Finally, if a schema is present, this function will ensure that the produced entities fully conform to the schema – for 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::InvalidEntityif schema is not none and any entities do not conform to the schema
• EntitiesError::Deserialization if there are errors while parsing the json

let data =serde_json::json!(
[
{
  "uid": {"type":"User","id":"alice"},
  "attrs": {
    "age":19,
    "ip_addr":{"__extn":{"fn":"ip", "arg":"10.0.1.101"}}
  },
  "parents": [{"type":"Group","id":"admin"}]
},
{
  "uid": {"type":"Groupd","id":"admin"},
  "attrs": {},
  "parents": []
}
]
);
let entities = Entities::from_json_value(data, None).unwrap();

pub fn from_json_file( json: impl Read, schema: Option<&Schema>, ) -> Result<Self, EntitiesError>

Parse an entities JSON file (in std::io::Read form) into an Entities object

schema represents a source of Action entities, which will be added to the entities parsed from JSON. (If any Action entities are present in the JSON, and a schema is also provided, each Action entity in the JSON must exactly match its definition in the schema or an error is returned.)

If a schema is present, this will also inform the parsing: for instance, it will allow __entity and __extn escapes to be implicit.

Finally, if a schema is present, this function will ensure that the produced entities fully conform to the schema – for 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 is_ancestor_of(&self, a: &EntityUid, b: &EntityUid) -> bool

Is entity a an ancestor of entity b? Same semantics as b in a in the Cedar language

pub fn ancestors<'a>( &'a self, euid: &EntityUid, ) -> Option<impl Iterator<Item = &'a EntityUid>>

Get an iterator over the ancestors of the given Euid. Returns None if the given Euid does not exist.

pub fn write_to_json(&self, f: impl Write) -> Result<(), EntitiesError>

Dump an Entities object into an entities JSON file.

The resulting JSON will be suitable for parsing in via from_json_*, and will be parse-able even with no Schema.

To read an Entities object from an entities JSON file, use from_json_file.

pub fn to_dot_str(&self) -> String

This feature is experimental. For more information see https://github.com/cedar-policy/rfcs/blob/main/README.md#experimental-features

Visualize an `Entities` object in the graphviz `dot` format. Entity visualization is best-effort and not well tested. Feel free to submit an issue if you are using this feature and would like it improved.

Trait Implementations

impl Clone for Entities

fn clone(&self) -> Entities

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Entities

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Entities

fn default() -> Entities

Returns the “default value” for a type.

impl IntoIterator for Entities

type Item = Entity

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Entities

fn eq(&self, other: &Entities) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefCast for Entities

type From = Entities

fn ref_cast(_from: &Self::From) -> &Self

fn ref_cast_mut(_from: &mut Self::From) -> &mut Self

impl Eq for Entities

impl StructuralPartialEq for Entities