Add normandy.recipe to filter expressions in the add-on.

docs/user/filter_expressions.rst

@@ -222,6 +222,21 @@ filter expressions.
 
    Boolean specifying whether the user has enabled Do Not Track.
 
+.. js:attribute:: normandy.recipe
+
+   Object containing information about the recipe being checked. Only documented
+   attributes are guaranteed to be available.
+
+   .. js:attribute:: normandy.recipe.id
+
+      Unique ID number for the recipe.
+
+   .. js:attribute:: normandy.recipe.arguments
+
+      Object containing the arguments entered for the recipe. The shape of this
+      object varies depending on the recipe, and use of this property is only
+      recommended if you are familiar with the argument schema.
+
 Transforms
 ----------
 This section describes the transforms available to filter expressions, and what

recipe-client-addon/lib/RecipeRunner.jsm

@@ -99,9 +99,9 @@ this.RecipeRunner = {
     }
   },
 
-  getFilterContext() {
+  getFilterContext(recipe) {
     return {
-      normandy: ClientEnvironment.getEnvironment(),
+      normandy: Object.assign(ClientEnvironment.getEnvironment(), {recipe}),
     };
   },
 
@@ -113,7 +113,7 @@ this.RecipeRunner = {
    *                   if an error occurred during evaluation.
    */
   async checkFilter(recipe) {
-    const context = this.getFilterContext();
+    const context = this.getFilterContext(recipe);
     try {
       const result = await FilterExpressions.eval(recipe.filter_expression, context);
       return !!result;

recipe-client-addon/test/browser/browser_RecipeRunner.js

@@ -87,7 +87,8 @@ add_task(async function globalObject() {
 });
 
 add_task(async function getFilterContext() {
-  const context = RecipeRunner.getFilterContext();
+  const recipe = {filter_expression: "1+1==2"};
+  const context = RecipeRunner.getFilterContext(recipe);
 
   // Test for expected properties in the filter expression context.
   const expectedNormandyKeys = [
@@ -98,6 +99,7 @@ add_task(async function getFilterContext() {
     "isDefaultBrowser",
     "locale",
     "plugins",
+    "recipe",
     "request_time",
     "searchEngine",
     "syncDesktopDevices",
@@ -111,6 +113,12 @@ add_task(async function getFilterContext() {
   for (const key of expectedNormandyKeys) {
     ok(key in context.normandy, `normandy.${key} is available`);
   }
+
+  Assert.deepEqual(
+    context.normandy.recipe,
+    recipe,
+    "normandy.recipe is the recipe passed to getFilterContext",
+  );
 });
 
 add_task(async function checkFilter() {
@@ -121,6 +129,12 @@ add_task(async function checkFilter() {
 
   // Non-boolean filter results result in a true return value.
   ok(await check("[1, 2, 3]"), "Non-boolean filter expressions return true");
+
+  // The given recipe must be available to the filter context.
+  const recipe = {filter_expression: "normandy.recipe.seven == 7", seven: 7};
+  ok(await RecipeRunner.checkFilter(recipe), "The recipe is available in the filter context");
+  recipe.seven = 4;
+  ok(!(await RecipeRunner.checkFilter(recipe)), "The recipe is available in the filter context");
 });
 
 add_task(async function testStart() {

recipe-server/normandy/recipes/api/serializers.py

@@ -29,6 +29,9 @@ class ActionSerializer(serializers.ModelSerializer):
 
 
 class RecipeSerializer(serializers.ModelSerializer):
+    # Attributes serialized here are made available to filter expressions via
+    # normandy.recipe, and should be documented if they are intended to be
+    # used in filter expressions.
     enabled = serializers.BooleanField(required=False)
     last_updated = serializers.DateTimeField(read_only=True)
     revision_id = serializers.CharField(source='latest_revision.id', read_only=True)