From cc456730545b146193a32db30a8b8105a41cee6e Mon Sep 17 00:00:00 2001 From: Victor Woeltjen Date: Wed, 1 Apr 2015 13:30:22 -0700 Subject: [PATCH] [Policy] Design/document policyService Design and document the behavior of the policy service, WTD-973. --- platform/policy/README.md | 93 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 platform/policy/README.md diff --git a/platform/policy/README.md b/platform/policy/README.md new file mode 100644 index 0000000000..a35a9a8d3e --- /dev/null +++ b/platform/policy/README.md @@ -0,0 +1,93 @@ +# Overview + +This bundle provides support for policy in Open MCT Web. Policy can be +used to limit the applicability of certain actions, or more broadly, +to provide an extension point for arbitrary decisions. + +# Services + +This bundle introduces the `policyService`, which may be consulted for +various decisions which are intended to be open for extension. + +The `policyService` has a single method, `allow`, which takes three +arguments and returns a boolean value (true if policy says this decision +should be allowed, false if not): + +* `category`: A string identifying which kind of decision is being made. + Typically, this will be a non-plural form of an extension type that is + being filtered down; for instance, to check whether or not a given + action should be returned by an `actionService`, one would use the + `action` category of extension. +* `candidate`: An object representing the thing which shall or shall not + be allowed. Usually, this will be an instance of an extension of the + category defined above. + * This does need to be the case; additional + policies which are not specific to any extension may also be defined + and consulted using unique `category` identifiers. In this case, the + type of the object delivered for the candidate may be unique to the + policy type. +* `context`: An object representing the context in which the decision is + occurring. Its contents are specific to each policy category. +* `callback`: Optional; a function to call if the policy decision is + rejected. This function will be called with the `message` string + (which may be undefined) of whichever individual policy caused the + operation to fail. + +_Design rationale_: Returning a boolean here limits the amount of +information that can be conveyed by a policy decision, but has the +benefit of simplicity. In MCT on the desktop, the policy service +returned a more complex object with both a boolean status and a string +message; the string message was used rarely (by only around 15% of +policy user code) and as such is made optional in the call itself here. + +_Design rationale_: Returning a boolean instead of a promise here implies +that policy decisions must occur synchronously. This limits the logic +which can be involved in a policy decision, but broadens its applicability; +policy is meant to be used by a variety of other services to separate out +a certain category of business logic, and a synchronous response means +that this capability may be utilized by both synchronous and asynchronous +services. Additionally, policies will often be used in loops (e.g. to filter +down a set of applicable actions) where latency will have the result of +harming the user experience (e.g. the user right-clicks and gets stuck +waiting for a bunch of policy decisions to complete before a menu showing +available actions can appear.) + +The `policyService` is a composite service; it may be modified by adding +decorators, aggregators, etc. + +## Service Components + +The policy service is most often used by decorators for other composite +services. For instance, this bundle contains a decorator for `actionService` +which filters down the applicable actions exposed by that service based +on policy. + +# Policy Categories + +This bundle introduces `action` as a policy category. Policies of this +category shall take action instances as their candidate argument, and +action contexts as their context argument. + +# Extensions + +This bundle introduces the `policies` category of extension. An extension +of this category should have both an implementation, as well as the following +metadata: + +* `category`: A string identifying which kind of policy decision this + effects. +* `message`: Optional; a human-readable string describing the policy + decision when it fails. + +An extension of this category must also have an implementation which +takes no arguments to its constructor and provides a single method, +`allow`, which takes two arguments, `candidate` and `context` (see +descriptions above under documentation for `actionService`) and returns +a boolean indicating whether or not it allows the policy decision. + +Policy decisions require consensus among all policies; that is, if a +single policy returns false, then the policy decision as a whole returns +false. As a consequence, policies should be written in a permissive +manner; that is, they should be designed to prohibit behavior under a +specific set of conditions (by returning false), and allow any behavior +which does not match those conditions (by returning true.) \ No newline at end of file