diff options
Diffstat (limited to '')
| -rw-r--r-- | toolkit/components/normandy/docs/suitabilities.rst | 73 |
1 files changed, 73 insertions, 0 deletions
diff --git a/toolkit/components/normandy/docs/suitabilities.rst b/toolkit/components/normandy/docs/suitabilities.rst new file mode 100644 index 0000000000..b199fc2938 --- /dev/null +++ b/toolkit/components/normandy/docs/suitabilities.rst @@ -0,0 +1,73 @@ +Suitabilities +============= + +When Normandy's core passes a recipe to an action, it also passes a +*suitability*, which is the result of evaluating a recipe's filters, +compatibility, signatures, and other checks. This gives actions more +information to make decisions with, which is especially important for +experiments. + +Temporary errors +---------------- +Some of the suitabilities below represent *temporary errors*. These could be +caused by infrastructure problems that prevent the recipe from working +correctly, or are otherwise not the fault of the recipe itself. These +suitabilities should not immediately cause a change in state. If the problem +persists, then eventually it should be considered permanent and state should +be changed. + +In the case of a permanent failure, action such as unenrollment should happen +immediately. For temporary failures, that action should be delayed until the +failure persists longer than some threshold. It is up to individual actions +to track and manage this transition. + +List of Suitabilities +--------------------- + +``FILTER_MATCH`` +~~~~~~~~~~~~~~~~ +All checks have passed, and the recipe is suitable to execute in this client. +Experiments and Rollouts should enroll or update. Heartbeats should be shown +to the user, etc. + +``SIGNATURE_ERROR`` +~~~~~~~~~~~~~~~~~~~ +The recipe's signature is not valid. If any action is taken this recipe +should be treated with extreme suspicion. + +This should be considered a temporary error, because it may be related to +server errors, local clocks, or other temporary problems. + +``CAPABILITIES_MISMATCH`` +~~~~~~~~~~~~~~~~~~~~~~~~~ +The recipe requires capabilities that this recipe runner does not have. Use +caution when interacting with this recipe, as it may not match the expected +schema. + +This should be considered a permanent error, because it is the result of a +choice made on the server. + +``FILTER_MISMATCH`` +~~~~~~~~~~~~~~~~~~~ +This client does not match the recipe's filter, but it is otherwise a +suitable recipe. + +This should be considered a permanent error, since the filter explicitly does +not match the client. + +``FILTER_ERROR`` +~~~~~~~~~~~~~~~~ +There was an error while evaluating the filter. It is unknown if this client +matches this filter. This may be temporary, due to network errors, or +permanent due to syntax errors. + +This should be considered a temporary error, because it may be the result of +infrastructure, such as `Classify Client <./services.html#classify-client>`_, +temporarily failing. + +``ARGUMENTS_INVALID`` +~~~~~~~~~~~~~~~~~~~~~ +The arguments of the recipe do not match the expected schema for the named +action. + +This should be considered a permanent error, since the arguments are generally validated by the server. This likely represents an unrecogonized compatibility error. |