renaming, inlining, and commenting in .proto files (#1488)

Signed-off-by: Craig Disselkoen <cdiss@amazon.com>

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

@@ -355,9 +355,9 @@ fn describe_arity_error(
 }
 
 /// A Policy that contains:
-///   a pointer to its template
-///   an link ID (unless it's an static policy)
-///   the bound values for slots in the template
+///   - a pointer to its template
+///   - a link ID (unless it's a static policy)
+///   - the bound values for slots in the template
 ///
 /// Policies are not serializable (due to the pointer), and can be serialized
 /// by converting to/from LiteralPolicy
@@ -366,10 +366,12 @@ pub struct Policy {
     /// Reference to the template
     template: Arc<Template>,
     /// Id of this link
+    ///
     /// None in the case that this is an instance of a Static Policy
     link: Option<PolicyID>,
     // INVARIANT (values total map)
     // All of the slots in `template` MUST be bound by `values`
+    //
     /// values the slots are bound to.
     /// The constructor `new` is only visible in this module,
     /// so it is the responsibility of callers to maintain
@@ -561,7 +563,8 @@ impl std::fmt::Display for Policy {
 /// Map from Slot Ids to Entity UIDs which fill the slots
 pub type SlotEnv = HashMap<SlotId, EntityUID>;
 
-/// Represents either an static policy or a template linked policy
+/// Represents either a static policy or a template linked policy.
+///
 /// This is the serializable version because it simply refers to the `Template` by its Id
 /// and does not contain a reference to the `Template` itself
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]

cedar-policy/CHANGELOG.md

@@ -16,6 +16,9 @@ Cedar Language Version: TBD
 ### Changed
 
 - Changed `Entities::add_entities` and `Entities::from_entities` to ignore structurally equal entities with the same Entity UID.
+- For `protobufs` experimental feature, a number of changes to the interface and
+  the Protobuf format definitions, as we continue to iterate towards making this
+  feature stable.
 
 ### Added
 

cedar-policy/protobuf_schema/core.proto

@@ -18,16 +18,26 @@ syntax = "proto3";
 package cedar_policy_core;
 
 message Request {
-    EntityUidEntry principal = 1;
-    EntityUidEntry action = 2;
-    EntityUidEntry resource = 3;
-    Context context = 4;
+    EntityUid principal = 1;
+    EntityUid action = 2;
+    EntityUid resource = 3;
+    Expr context = 4;
 }
 
-message LiteralPolicySet {
-    // Key is PolicyID as a string
+// the protobuf PolicySet message describes a complete policy set, including
+// templates, static policies, and/or template-linked policies.
+message PolicySet {
+    // Key is PolicyID as a string.
+    // Value is a `TemplateBody`.
+    // Both templates and static policies are included in this map, with static
+    // policies represented as templates with zero slots.
     map<string, TemplateBody> templates = 1;
-    map<string, LiteralPolicy> links = 2;
+    // Key is PolicyID as a string.
+    // Value is a `Policy`.
+    // All static policies and template-linked policies are included in this map.
+    // Static policies must have exactly one entry in this map, and the PolicyID
+    // of the static policy must be the same in this map and the above map.
+    map<string, Policy> links = 2;
 }
 
 enum Mode {
@@ -40,101 +50,78 @@ message Entities {
     Mode mode = 2;
 }
 
-message Context {
-    Expr context = 1;
-}
-
-// BEGIN REQUEST MESSAGES
-
-message EntityUidEntry {
-    EntityUid euid = 1;
-}
-
 message EntityUid {
-    EntityType ty = 1;
+    Name ty = 1;
     string eid = 2;
 }
 
-message EntityType {
-    Name name = 1;
-}
-
-// alias Id = string
 message Name {
     string id = 1;
     repeated string path = 2;
 }
 
-
-// END REQUEST MESSAGES
-
-
-// BEGIN POLICYSET MESSAGES
-
-message LiteralPolicy {
+// the protobuf Policy message describes either a static or a template-linked policy.
+message Policy {
+    // ID of the template associated with this policy.
+    // For static policies, this is the ID of a zero-slot template.
     string template_id = 1;
-    string link_id = 2;
-    bool link_id_specified = 3;
-    // map<SlotId, EntityUid> is not allowed since keys in map
-    // fields cannot be enum types
-    // map<SlotId, EntityUid> values = 4;
+    // ID of this policy itself.
+    // For static policies, this is omitted/ignored; the ID of the policy is the
+    // `template_id`.
+    optional string link_id = 2;
+    // Whether this policy is a static (false) or template-linked (true) policy
+    bool is_template_link = 3;
+    // Value of the `?principal` slot.
+    // Omitted/ignored for templates without the `?principal` slot.
     EntityUid principal_euid = 4;
+    // Value of the `?resource` slot.
+    // Omitted/ignored for templates without the `?resource` slot.
     EntityUid resource_euid = 5;
 }
 
-message Annotation {
-    string val = 1;
-}
-
 enum Effect {
     Forbid = 0;
     Permit = 1;
 }
 
 message TemplateBody {
     string id = 1;
-    // alias AnyId = string
-    // alias Annotations = map<AnyId, Annotation>
-    map<string, Annotation> annotations = 3;
+    map<string, string> annotations = 3;
     Effect effect = 4;
-    PrincipalConstraint principal_constraint = 5;
+    PrincipalOrResourceConstraint principal_constraint = 5;
     ActionConstraint action_constraint = 6;
-    ResourceConstraint resource_constraint = 7;
+    PrincipalOrResourceConstraint resource_constraint = 7;
     Expr non_scope_constraints = 8;
 }
 
-message PrincipalConstraint {
-    PrincipalOrResourceConstraint constraint = 1;
-}
-
-message ResourceConstraint {
-    PrincipalOrResourceConstraint constraint = 1;
-}
-
+// an EntityReference may either be an EntityUid or a Slot.
 message EntityReference {
     oneof data {
-        Ty ty = 1;
+        Slot slot = 1;
         EntityUid euid = 2;
     }
 
-    // Zero-Arity constructors
-    enum Ty {
-        Slot = 0;
+    // if it's a Slot, we know from context which Slot it is,
+    // so we don't need a `SlotId` and can just use this one-armed enum
+    enum Slot {
+        // the one option for the enum
+        unit = 0;
     }
 }
 
 message PrincipalOrResourceConstraint {
     oneof data {
-        Ty ty = 1;
+        Any any = 1;
         InMessage in = 2;
         EqMessage eq = 3;
         IsMessage is = 4;
         IsInMessage isIn = 5;
     }
 
-    // Zero-arity constructors
-    enum Ty {
-        Any = 0;
+    // Zero-arity constructors represented as enums with only one member
+    enum Any {
+        // the one option for the enum
+        unit = 0;
     }
 
     message InMessage {
@@ -144,11 +131,11 @@ message PrincipalOrResourceConstraint {
         EntityReference er = 1;
     }
     message IsMessage {
-        EntityType et = 1;
+        Name entity_type = 1;
     }
     message IsInMessage {
         EntityReference er = 1;
-        EntityType et = 2;
+        Name entity_type = 2;
     }
 }
 
@@ -159,14 +146,17 @@ enum SlotId {
 
 message ActionConstraint {
     oneof data {
-        Ty ty = 1;
+        Any any = 1;
         InMessage in = 2;
         EqMessage eq = 3;
     }
 
-    enum Ty {
-        Any = 0;
+    // Zero-arity constructors represented as enums with only one member
+    enum Any {
+        // the one option for the enum
+        unit = 0;
     }
+
     message InMessage {
         repeated EntityUid euids = 1;
     }
@@ -210,7 +200,7 @@ message Expr {
         Principal = 0;
         Action = 1;
         Resource = 2;
-        CONTEXT = 3;
+        Context = 3;
     }
 
     message If {
@@ -282,20 +272,21 @@ message Expr {
 
         message PatternElem {
             oneof data {
-                Ty ty = 1;
+                Wildcard wildcard = 1;
                 string c = 2;
             }
 
-            // Zero-arity constructors
-            enum Ty {
-                Wildcard = 0;
+            // Zero-arity constructors represented as enums with only one member
+            enum Wildcard {
+                // the one option for the enum
+                unit = 0;
             }
         }
     }
 
     message Is {
         Expr expr = 1;
-        EntityType entity_type = 2;
+        Name entity_type = 2;
     }
 
     message Set {
@@ -307,16 +298,9 @@ message Expr {
     }
 }
 
-// END POLICYSET MESSAGES
-
-
-// ENTER ENTITIES MESSAGES
-
 message Entity {
     EntityUid uid = 1;
     map<string, Expr> attrs = 2;
     repeated EntityUid ancestors = 3;
     map<string, Expr> tags = 4;
 }
-
-// END ENTITIES MESSAGES