Generated with the help of my own dear MeatBrain.

Problem/Motivation

There are some situations where a module should ship recipes, or a set of recipes, that set that module up in various ways. An example is https://git.drupalcode.org/project/canvas/-/merge_requests/2070, where Canvas wants to ship a recipe that sets up OAuth for Canvas CLI (which would otherwise be an arduous, persnickety process).

In these kinds of situations, the recipe is pretty tightly coupled to the module in question, and stays within the boundaries of that module. But a bigger recipe, like a site template, might want to invoke that recipe. In other words: "in this site template, I would like to set up Canvas OAuth in a specific way that Canvas OAuth defines/maintains".

Recipes have no syntax for this. There's no way to include "a specific recipe that is embedded in a module". The only way to make that work is for the recipe in question to be split out into its own project, which is both complicated and adds substantial maintenance burden.

Proposed resolution

Support this syntax in recipe.yml:

recipes:
  - @canvas:a_recipe

This means "include path/to/canvas/recipes/a_recipe/recipe.yml".

Intentional limitations:

  • The canvas module must exist, although it need not be installed. This is just a normal dependency: if this recipe wants to apply another recipe from Canvas, it behooves the recipe to depend on Canvas.
  • This only works with modules, not themes. I can't think of any real reason why a theme would need to ship various "set me up in different ways" recipes, but if the need arises, we can always add that in a follow-up. For now, we'll limit it to modules to keep things simple.

Remaining tasks

Create follow up for:
The . character cannot appear anywhere in the include string, to prevent path traversal (and in fact, this should have already been the case for every other kind of recipe include, so let's fix it here as a deliberate hardening).

User interface changes

None.

Introduced terminology

None.

API changes

Yes, recipes will support a bit of new syntax.

Data model changes

None.

Release notes snippet

TBD but I bet we'll want one.

Issue fork drupal-3639289

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

phenaproxima created an issue. See original summary.

phenaproxima’s picture

Status: Active » Needs review

phenaproxima’s picture

Issue tags: +Needs followup

One bit of future scope here, which I don't think we need to handle in this issue, is how to handle inputs to recipes that are referenced this way. It's probably going to take the form of --input="@canvas_oauth:my/recipe.SOME_INPUT_NAME=value", and that's awkward as all hell, but that's why I think it's something to punt rather than handle here. Tagging for a follow-up though.

phenaproxima’s picture

Issue summary: View changes
nicxvan’s picture

Adding a note from slack, I am in favor of this.

I think we should keep some of the current restrictions, they have to be in the recipes subdirectory, and we should reference them like SDCs.

phenaproxima’s picture

nicxvan’s picture

Issue summary: View changes
Status: Needs review » Reviewed & tested by the community

This is very clean.

I'm surprised it's so little code.

I think the symmetry with sdcs and the root recipe is nice.

The earlier iteration would not have worked with recipes in subdirectories anyway.

CR looks good!

I moved the . in the issue summary to remaining tasks, we should create a follow up for that.

alexpott’s picture

Status: Reviewed & tested by the community » Needs work

It looks like we should improve the validation in

      'recipes' => new Optional([
        new All([
          new Type('string'),
          new NotBlank(),
          // If recipe depends on itself, ::validateRecipeExists() will set off
          // an infinite loop. We can avoid that by skipping that validation if
          // the recipe depends on itself, which is what Sequentially does.
          new Sequentially([
            new NotIdenticalTo(
              value: basename(dirname($file)),
              message: 'The {{ compared_value }} recipe cannot depend on itself.',
            ),
            new Callback(
              callback: self::validateRecipeExists(...),
              payload: $include_path,
            ),
          ]),
        ]),
      ]),

This could stop recipes from doing path traversal. +1 for this being in a follow-up and also prevent this on an API level.

Putting back to needs work for the follow-ups to be created. The code looks good to me... can be set back to rtbc once they both exist.

phenaproxima’s picture

Opened both, and linked here. Back to RTBC.

benjifisher’s picture

I am also in favor of this issue.

The use case I have in mind is letting a module provide an "example" or "quick start" recipe. Until now, the only way to implement this is with a mymodule_example submodule.

Should we add a follow-up issue for the project_browser module to support recipes included in modules? That makes sense for my use case, but not the one described in the issue summary.

phenaproxima’s picture

Yeah, I think a follow-up in Project Browser makes sense.