Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add APIs to get schema annotations #1389

Merged
merged 9 commits into from
Jan 13, 2025
Merged

Add APIs to get schema annotations #1389

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
bb06d89
Add APIs to get schema annotations
shaobo-he-aws Dec 20, 2024
4708c47
added tests
shaobo-he-aws Dec 21, 2024
b3a02d5
Update cedar-policy/src/api.rs
shaobo-he-aws Dec 30, 2024
5eb2a23
renaming
shaobo-he-aws Dec 31, 2024
1e2e136
Apply suggestions from code review
shaobo-he-aws Jan 2, 2025
649ef49
Apply suggestions from code review
shaobo-he-aws Jan 8, 2025
a418e4a
Merge remote-tracking branch 'origin/main' into feature/shaobo/annota…
shaobo-he-aws Jan 8, 2025
eb70160
Merge remote-tracking branch 'origin/main' into feature/shaobo/annota…
shaobo-he-aws Jan 8, 2025
0010302
added APIs to get individual annotation
shaobo-he-aws Jan 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 166 additions & 0 deletions cedar-policy/src/api.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ use cedar_policy_validator::entity_manifest;
pub use cedar_policy_validator::entity_manifest::{
AccessTrie, EntityManifest, EntityRoot, Fields, RootAccessTrie,
};
use cedar_policy_validator::json_schema;
use cedar_policy_validator::typecheck::{PolicyCheck, Typechecker};
pub use id::*;

Expand Down Expand Up @@ -1397,7 +1398,172 @@ pub struct SchemaFragment {
lossless: cedar_policy_validator::json_schema::Fragment<cedar_policy_validator::RawName>,
}

fn get_annotation_by_key(
annotations: &est::Annotations,
annotation_key: impl AsRef<str>,
) -> Option<&str> {
annotations
.0
.get(&annotation_key.as_ref().parse().ok()?)
.map(|value| annotation_value_to_str_ref(value.as_ref()))
}

fn annotation_value_to_str_ref(value: Option<&ast::Annotation>) -> &str {
value.map_or("", |a| a.as_ref())
}

fn annotations_to_pairs(annotations: &est::Annotations) -> impl Iterator<Item = (&str, &str)> {
annotations
.0
.iter()
.map(|(key, value)| (key.as_ref(), annotation_value_to_str_ref(value.as_ref())))
}

impl SchemaFragment {
/// Get annotations of a non-empty namespace.
///
/// We do not allow namespace-level annotations on the empty namespace.
///
/// Returns `None` if `namespace` is not found in the [`SchemaFragment`]
pub fn namespace_annotations(
&self,
namespace: EntityNamespace,
) -> Option<impl Iterator<Item = (&str, &str)>> {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having all of these APIs return Iterator<Item = (&str, &str)> is good, but I wonder if we need an additional API to get the value of an annotation with a user-specified key. For instance if I want to specifically look up the value of the foo annotation on a particular namespace. As is, I'd be forced to iterate through the entire iterator looking for the key foo. We could solve this either by adding a separate API namespace_annotation(&self, namespace, key) or perhaps by returning a map structure (HashMap or BTreeMap) instead of an iterator in this API, so that users could do their own lookups.

Same for the other new annotation-getting APIs.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. I think that having an iterator is a generic. That is, users can collect them into a HashMap or BTreeMap given their preferences (e.g., performance vs order). I also think it may be a good idea to let user collect the iterator and get the value by key, instead of having APIs. Maybe I'm too paranoid about breaking changes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess I'm concerned that having the user collect the iterator in order to get the value by key is

  1. a little complicated, compared to having a direct method for it -- so, creates a suboptimal user experience
  2. potentially poor performance, as getting any value by key at all requires collecting the entire iterator

If we're worried about breaking changes, we don't have to return a map structure, we can just implement our own getter, something like:

pub fn namespace_annotation(
    &self,
    namespace: EntityNamespace,
    annotation_key: &str,
) -> Option<&str> { ... }

that gets a particular annotation value given a key. I don't think adding a method like this is overly committing to any particular implementation details

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure. I can do it.

self.lossless
.0
.get(&Some(namespace.0))
.map(|ns_def| annotations_to_pairs(&ns_def.annotations))
}

/// Get annotation value of a non-empty namespace by annotation key
/// `annotation_key`
///
/// We do not allow namespace-level annotations on the empty namespace.
///
/// Returns `None` if `namespace` is not found in the [`SchemaFragment`]
/// or `annotation_key` is not a valid annotation key
/// or it does not exist
pub fn namespace_annotation(
&self,
namespace: EntityNamespace,
annotation_key: impl AsRef<str>,
) -> Option<&str> {
let ns = self.lossless.0.get(&Some(namespace.0))?;
get_annotation_by_key(&ns.annotations, annotation_key)
}

/// Get annotations of a common type declaration
///
/// Returns `None` if `namespace` is not found in the [`SchemaFragment`] or
/// `ty` is not a valid common type ID or `ty` is not found in the
/// corresponding namespace definition
Comment on lines +1457 to +1459
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

overloading the None case here isn't great. Maybe we could publicly expose an Id data type so that error can be reported sooner? Though, using that in other places in the API would probably be a breaking change, so perhaps it's better to stick with this signature for now

pub fn common_type_annotations(
&self,
namespace: Option<EntityNamespace>,
ty: &str,
) -> Option<impl Iterator<Item = (&str, &str)>> {
let ns_def = self.lossless.0.get(&namespace.map(|n| n.0))?;
let ty = json_schema::CommonTypeId::new(ast::UnreservedId::from_normalized_str(ty).ok()?)
.ok()?;
ns_def
.common_types
.get(&ty)
.map(|ty| annotations_to_pairs(&ty.annotations))
}

/// Get annotation value of a common type declaration by annotation key
/// `annotation_key`
///
/// Returns `None` if `namespace` is not found in the [`SchemaFragment`]
/// or `ty` is not a valid common type ID
/// or `ty` is not found in the corresponding namespace definition
/// or `annotation_key` is not a valid annotation key
/// or it does not exist
pub fn common_type_annotation(
&self,
namespace: Option<EntityNamespace>,
ty: &str,
annotation_key: impl AsRef<str>,
) -> Option<&str> {
let ns_def = self.lossless.0.get(&namespace.map(|n| n.0))?;
let ty = json_schema::CommonTypeId::new(ast::UnreservedId::from_normalized_str(ty).ok()?)
.ok()?;
get_annotation_by_key(&ns_def.common_types.get(&ty)?.annotations, annotation_key)
}

/// Get annotations of an entity type declaration
///
/// Returns `None` if `namespace` is not found in the [`SchemaFragment`] or
/// `ty` is not a valid entity type name or `ty` is not found in the
/// corresponding namespace definition
pub fn entity_type_annotations(
&self,
namespace: Option<EntityNamespace>,
ty: &str,
) -> Option<impl Iterator<Item = (&str, &str)>> {
let ns_def = self.lossless.0.get(&namespace.map(|n| n.0))?;
let ty = ast::UnreservedId::from_normalized_str(ty).ok()?;
ns_def
.entity_types
.get(&ty)
.map(|ty| annotations_to_pairs(&ty.annotations))
}

/// Get annotation value of an entity type declaration by annotation key
/// `annotation_key`
///
/// Returns `None` if `namespace` is not found in the [`SchemaFragment`]
/// or `ty` is not a valid entity type name
/// or `ty` is not found in the corresponding namespace definition
/// or `annotation_key` is not a valid annotation key
/// or it does not exist
pub fn entity_type_annotation(
&self,
namespace: Option<EntityNamespace>,
ty: &str,
annotation_key: impl AsRef<str>,
) -> Option<&str> {
let ns_def = self.lossless.0.get(&namespace.map(|n| n.0))?;
let ty = ast::UnreservedId::from_normalized_str(ty).ok()?;
get_annotation_by_key(&ns_def.entity_types.get(&ty)?.annotations, annotation_key)
}

/// Get annotations of an action declaration
///
/// Returns `None` if `namespace` is not found in the [`SchemaFragment`] or
/// `id` is not found in the corresponding namespace definition
pub fn action_annotations(
&self,
namespace: Option<EntityNamespace>,
id: EntityId,
) -> Option<impl Iterator<Item = (&str, &str)>> {
let ns_def = self.lossless.0.get(&namespace.map(|n| n.0))?;
ns_def
.actions
.get(id.as_ref())
.map(|a| annotations_to_pairs(&a.annotations))
}

/// Get annotation value of an action declaration by annotation key
/// `annotation_key`
///
/// Returns `None` if `namespace` is not found in the [`SchemaFragment`]
/// or `id` is not found in the corresponding namespace definition
/// or `annotation_key` is not a valid annotation key
/// or it does not exist
pub fn action_annotation(
&self,
namespace: Option<EntityNamespace>,
id: EntityId,
annotation_key: impl AsRef<str>,
) -> Option<&str> {
let ns_def = self.lossless.0.get(&namespace.map(|n| n.0))?;
get_annotation_by_key(
&ns_def.actions.get(id.as_ref())?.annotations,
annotation_key,
)
}

/// Extract namespaces defined in this [`SchemaFragment`].
///
/// `None` indicates the empty namespace.
Expand Down
Loading
Loading