Open mwhicks1 opened 6 months ago
We likely want to do this with https://github.com/cedar-policy/cedar/issues/184 so that users have an easy and persistent way to find error in the docs. We'll also want to add #[diagnostic(url("docs.cedarpolicy.com/errors/{error_code}"))]
annotation to our errors.
This issue requests an explanation of errors for Cedar users who are not likely to look at the Rust docs. Are you thinking that the Rust docs would link to the explanation on the main documentation pages?
Yes, @john-h-kastner-aws' suggestion would result in the Rust docs linking to these docs.cedarpolicy.com
error explanations
Request: Cedar error messages, from the validator and evaluator, can be confusing because of the lack of context. We should provide explanations and examples for the messages in the documentation.
Example: https://github.com/cedar-policy/cedar/issues/103 describes how the error
can be confusing because it's not clear what sub-expression in the policy is causing the policy to always evaluate to false. But there's a bigger problem: Users may not even know what "policy expression evaluates to false for all valid requests" even means. They need to understand what the message is trying to communicate so they can try to debug their policy.
Proposal: Add a section to the documentation called EXPLANATION OF ERRORS, perhaps toward the end. This will have two parts: One for validation errors and one for evaluation/authorization errors. In each, have a table of error messages, with links to explanations for individual messages. The explanations could have three parts: (1) Error (what is the error text), (2) Explanation (a textual explanation of what the error means), and (3) Example (an example policy/schema/etc. that exhibits the error).
For our example, we could write
Error:
Policy is impossible. The policy expression evaluates to false for all valid requests
Explanation: The validator has determined that there is no request that can possibly satisfy this policy. To make this determination, the validator considers all legal requests that conform to the schema. It finds that for none of them will the policy ever evaluate totrue
. Usually the reason for this is some condition in the policy that can never be true, which thus causes the whole policy to always be unsatisfied. Example: Suppose we have the policypermit(principal,action,resource) when { resource has Owner && resource.Owner == principal };
and we attempt to validate it under this schema. According to theactions
part of the schema, for all legal actions theresource
could be eitherList
orApplication
, but neither of these entities (again, per the schema) can ever have anOwner
attribute. This means that the expressionresource has Owner
in thewhen
clause will always evaluate to false, which always makes the whole policy false. This situation arises from a presumed typo: AList
can have attributeowner
, but Cedar is case sensitive:Owner
andowner
are not the same thing.