- Reference Issues: cedar-policy/cedar#986
- Implementation PR(s): (leave this empty)
- Started: 2024-06-28
Similar to Object-Relational Mapping (ORM), this RFC proposes a macro-based conversion between Rust objects and entities.
The following Rust code defines how type Team and type Member map to entity type Example::Team.
#[derive(Debug, Clone, Cedar)]
#[cedar(rename="Example::Team")]
struct Team {
#[cedar(eid)]
id: String,
members: HashSet<Member>,
#[cedar(skip)]
nickname: String,
}
#[derive(Debug, Clone, Cedar)]
#[cedar(type=record)]
struct Member {
name: String,
#[cedar(rename="region")]
location: Option<String>,
}An object Team { id: "A", nickname: "AAA", members: { Member { name: "alice", location: Some("West")}, Member { name: "bob", location: None}}} is converted to the following entities in JSON,
[
{
{
"uid": { "type": "Team", "id": "A"},
"attrs": {
"members": [
{
"name": "alice",
"region": "West"
},
{
"name": "bob"
}
]
},
"parents": []
}
}
]There currently do not exist any convenient methods to programmatically convert Rust objects to entities or vice versa. The status quo of converting a Rust object to an entity is to create an entity without any attributes and then insert attributes. The whole process is akin to that of manually serializing Rust objects to JSON, the latter of which is automated by serde. Users should be able to do the same for Rust object to entity conversion. This RFC addresses this need using Rust derive macros.
Moreover, OEM can potentially facilitate the adoption of Cedar on applications using databases. For instance, developers can leverage ORM to seamlessly convert results of database queries into Rust objects and then into entities. That is, developers are able to conveniently construct authorization requests by fetching data from databases.
Given limited knowledge about Rust macros the proposer has, the design details are subject to significant changes.
The macros over a Rust type eventually expand to implementations of Into<Entities>. In the meantime, they also give rise to implementations of Into<Value> for this type. By default, the implementation of Into<Value> for a type produces an entity uid unless the type is annotated with the #[cedar(type=record)] clause, where it produces a record.
The implementation of Into<Entities> for any type not annotated with the #[cedar(type=entity)] clause produces an empty entity slice. Those for types without such annotations construct an entity by iterating its fields. If a field type corresponds to an entity type, the entity slice derived from the field is merged into the final resulting entity slice. That is the reason why a Rust object converts to an entity slice instead of a single entity.
We require all types of struct fields to implement Into<Option<Value>>. The Option here is to encode optional attributes. We provide default implementations for various primitive types, Option<T:Into<Value>>, HashMap<S:ToString,T:Into<Value>>, HashMap<S:ToString,Option<T:Into<Value>>>, HashSet<T:Into<Value>>.
We use clause #[cedar(rename=...)] to describe entity type/attribute name mappings, where the argument is the string representation of an entity type or attribute name. Entity type/attribute name is the Rust type/field name without such clause.
We allow the conversion to ignore certain fields by annotating them with #[cedar(skip)]. Note that this makes OEM unidirectional. That is, we can only convert objects into entities, not the opposite.
We use clause #[cedar(eid)] to denote the field corresponding to the Eid. We require the field type to implement ToString.
Rust macros are unstable and hard to write. Moreover, users may find manual construction of entities not that hard.
Manual construction of entities.
How do we describe membership relations?