mirror of
https://github.com/nasa/openmct.git
synced 2024-12-22 14:32:22 +00:00
93 lines
4.4 KiB
Markdown
93 lines
4.4 KiB
Markdown
# 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.) |