feat(riff-raff-generator)!: Support multiple Riff-Raff projects

Author: akash1810

.changeset/eleven-animals-pick.md

@@ -0,0 +1,70 @@
+---
+"@guardian/cdk": major
+---
+
+Support generating multiple `riff-raff.yaml` files. To do this, set the `riffRaffProjectName` property of a `GuStack`.
+This is helpful in a few scenarios, for example if you have a singleton (INFRA) stack, and CODE/PROD application stacks.
+
+In the following, two files will be produced:
+- `/path/to/cdk.out/deploy::core-infra/riff-raff.yaml`
+- `/path/to/cdk.out/deploy::my-app/riff-raff.yaml`
+
+```ts
+class MyCoreInfraStack extends GuStack {}
+class MyApplicationStack extends GuStack {}
+
+new MyCoreInfraStack(app, "MyCoreInfra", {
+  stack: "deploy",
+  stage: "INFRA",
+  env: { region: "eu-west-1" },
+  riffRaffProjectName: "deploy::core-infra",
+});
+
+new MyApplicationStack(app, "MyApp-CODE", {
+  stack: "deploy",
+  stage: "CODE",
+  env: { region: "eu-west-1" },
+  riffRaffProjectName: "deploy::my-app",
+});
+
+new MyApplicationStack(app, "MyApp-PROD", {
+  stack: "deploy",
+  stage: "PROD",
+  env: { region: "eu-west-1" },
+  riffRaffProjectName: "deploy::my-app",
+});
+```
+
+BREAKING CHANGE: Within `RiffRaffYamlFile` the `riffRaffYaml` property has been removed.
+NOTE: If you're using `GuRoot`, this change should not impact you.
+
+To migrate, use the `configuration` property:
+
+```ts
+// BEFORE
+const app = new App();
+const riffRaff = new RiffRaffYamlFile(app);
+const deployments = riffRaff.riffRaffYaml.deployments;
+
+const myStack = new MyStack(app, "my-stack", {
+  stack: "playground",
+  stage: "PROD",
+  env: { region: "eu-west-1" },
+  riffRaffProjectName: "playground::my-stack",
+});
+
+deployments.set("additional-deployment", {
+  type: "aws-s3",
+  ...
+});
+
+// AFTER
+const app = new App();
+const riffRaff = new RiffRaffYamlFile(app);
+const { configuration } = riffRaff;
+
+configuration.get("playground::my-stack")?.deployments.set("additional-deployment", {
+  type: "aws-s3",
+  ...
+});
+```

src/riff-raff-yaml-file/README.md

@@ -37,14 +37,52 @@ new MyStack(app, "my-stack-CODE", {});
 new MyStack(app, "my-stack-PROD", {});
 ```
 
+### Generating multiple `riff-raff.yaml` files
+Multiple `riff-raff.yaml` files can be generated by setting the `riffRaffProjectName` property of a `GuStack`.
+
+In the example below, we have a singleton stack creating some core infrastructure and an application stack.
+We'll generate two `riff-raff.yaml` files:
+1. `/path/to/cdk.out/playground::core-infra/riff-raff.yaml`
+2. `/path/to/cdk.out/playground::api/riff-raff.yaml`.
+
+```ts
+import { GuStack } from "@guardian/cdk/lib/constructs/core";
+import { GuRoot } from "@guardian/cdk/lib/constructs/root";
+
+class CoreInfraStack extends GuStack {}
+class MyApi extends GuStack {}
+
+const app = new GuRoot();
+
+new CoreInfraStack(app, "core-infra", {
+  stack: "playground",
+  stage: "INFRA",
+  riffRaffProjectName: "playground::core-infra",
+});
+
+new MyApi(app, "api-code", {
+  stack: "playground",
+  stage: "CODE",
+  riffRaffProjectName: "playground::api",
+});
+
+new MyApi(app, "api-prod", {
+  stack: "playground",
+  stage: "PROD",
+  riffRaffProjectName: "playground::api",
+});
+```
+
 ### Advanced usage
+#### Additional deployments
 As noted above, only specific deployment types are currently supported.
 
 If you want to add additional deployment types, you can do so by instantiating `RiffRaffYamlFile` directly:
 
 ```ts
 import { App } from "aws-cdk-lib";
 import { RiffRaffYamlFile } from "@guardian/cdk/lib/riff-raff-yaml-file";
+import { UnknownRiffRaffProjectName } from "@guardian/cdk/lib/riff-raff-yaml-file/types";
 
 const app = new App();
 
@@ -55,9 +93,9 @@ const { stack, region } = new MyStack(app, "my-stack", {
 });
 
 const riffRaff = new RiffRaffYamlFile(app);
-const { riffRaffYaml: { deployments } } = riffRaff;
+const { configuration } = riffRaff;
 
-deployments.set("upload-my-static-files", {
+configuration.get(UnknownRiffRaffProjectName)?.deployments.set("upload-my-static-files", {
   actions: ["uploadStaticFiles"],
   app: "my-static-site",
   contentDirectory: "my-static-site",

src/riff-raff-yaml-file/group-by.ts

@@ -1,6 +1,7 @@
 import type { GuStack } from "../constructs/core";
 import { groupBy } from "../utils/array";
-import type { ClassName, Region, StackTag, StageTag } from "./types";
+import type { ClassName, Region, RiffRaffProjectName, StackTag, StageTag } from "./types";
+import { UnknownRiffRaffProjectName } from "./types";
 
 export function groupByClassName(cdkStacks: GuStack[]): Record<ClassName, GuStack[]> {
   return groupBy(cdkStacks, (stack) => stack.constructor.name);
@@ -17,3 +18,7 @@ export function groupByStageTag(cdkStacks: GuStack[]): Record<StageTag, GuStack[
 export function groupByRegion(cdkStacks: GuStack[]): Record<Region, GuStack[]> {
   return groupBy(cdkStacks, ({ region }) => region);
 }
+
+export function groupByRiffRaffProjectName(cdkStacks: GuStack[]): Record<RiffRaffProjectName, GuStack[]> {
+  return groupBy(cdkStacks, (_) => _.riffRaffProjectName ?? UnknownRiffRaffProjectName);
+}

src/riff-raff-yaml-file/index.test.ts

@@ -9,7 +9,8 @@ import { GuStack } from "../constructs/core";
 import { GuLambdaFunction } from "../constructs/lambda";
 import { GuEc2AppExperimental } from "../experimental/patterns/ec2-app";
 import { GuEc2App, GuNodeApp, GuPlayApp, GuScheduledLambda } from "../patterns";
-import { RiffRaffYamlFile } from "./index";
+import { UnknownRiffRaffProjectName } from "./types";
+import { RiffRaffYamlFile, validateRiffRaffYamlDirectory } from "./index";
 
 describe("The RiffRaffYamlFile class", () => {
   it("Should support deploying different GuStacks to multiple AWS accounts (aka Riff-Raff stacks), and regions", () => {
@@ -1110,7 +1111,7 @@ describe("The RiffRaffYamlFile class", () => {
 
     const riffraff = new RiffRaffYamlFile(app);
 
-    riffraff.riffRaffYaml.deployments.set("upload-my-static-files", {
+    riffraff.configuration.get(UnknownRiffRaffProjectName)?.deployments.set("upload-my-static-files", {
       app: "my-static-site",
       contentDirectory: "my-static-site",
       parameters: {
@@ -2008,5 +2009,157 @@ describe("The RiffRaffYamlFile class", () => {
         new RiffRaffYamlFile(app);
       }).toThrow("Unable to produce a working riff-raff.yaml file; missing 2 definitions");
     });
+
+    it("should generate multiple configurations", () => {
+      const app = new App({ outdir: "/tmp/cdk.out" });
+
+      class MyCoreInfraStack extends GuStack {}
+      class MyApplicationStack extends GuStack {}
+
+      new MyCoreInfraStack(app, "MyCoreInfra", {
+        stack: "deploy",
+        stage: "INFRA",
+        env: { region: "eu-west-1" },
+        riffRaffProjectName: "deploy::core-infra",
+      });
+
+      new MyApplicationStack(app, "MyApp-CODE", {
+        stack: "deploy",
+        stage: "CODE",
+        env: { region: "eu-west-1" },
+        riffRaffProjectName: "deploy::my-app",
+      });
+
+      new MyApplicationStack(app, "MyApp-PROD", {
+        stack: "deploy",
+        stage: "PROD",
+        env: { region: "eu-west-1" },
+        riffRaffProjectName: "deploy::my-app",
+      });
+
+      const riffraff = new RiffRaffYamlFile(app);
+
+      expect(Array.from(riffraff.configuration.keys())).toEqual(["deploy::core-infra", "deploy::my-app"]);
+
+      expect(riffraff.toYAML("deploy::core-infra")).toMatchInlineSnapshot(`
+        "allowedStages:
+          - INFRA
+        deployments:
+          cfn-eu-west-1-deploy-my-core-infra-stack:
+            type: cloud-formation
+            regions:
+              - eu-west-1
+            stacks:
+              - deploy
+            app: my-core-infra-stack
+            contentDirectory: /tmp/cdk.out
+            parameters:
+              templateStagePaths:
+                INFRA: MyCoreInfra.template.json
+        "
+      `);
+      expect(riffraff.toYAML("deploy::my-app")).toMatchInlineSnapshot(`
+        "allowedStages:
+          - CODE
+          - PROD
+        deployments:
+          cfn-eu-west-1-deploy-my-application-stack:
+            type: cloud-formation
+            regions:
+              - eu-west-1
+            stacks:
+              - deploy
+            app: my-application-stack
+            contentDirectory: /tmp/cdk.out
+            parameters:
+              templateStagePaths:
+                CODE: MyApp-CODE.template.json
+                PROD: MyApp-PROD.template.json
+        "
+      `);
+    });
+
+    it("should throw when generating multiple configurations and there are missing definitions", () => {
+      const app = new App({ outdir: "/tmp/cdk.out" });
+
+      class MyCoreInfraStack extends GuStack {}
+      class MyApplicationStack extends GuStack {}
+      class MyDatabaseStack extends GuStack {}
+
+      new MyCoreInfraStack(app, "MyCoreInfra", {
+        stack: "deploy",
+        stage: "INFRA",
+        env: { region: "eu-west-1" },
+        riffRaffProjectName: "deploy::core-infra",
+      });
+
+      new MyApplicationStack(app, "MyApp-CODE", {
+        stack: "deploy",
+        stage: "CODE",
+        env: { region: "eu-west-1" },
+        riffRaffProjectName: "deploy::my-app",
+      });
+
+      new MyApplicationStack(app, "MyApp-PROD", {
+        stack: "deploy",
+        stage: "PROD",
+        env: { region: "eu-west-1" },
+        riffRaffProjectName: "deploy::my-app",
+      });
+
+      new MyDatabaseStack(app, "MyDatabase-PROD", {
+        stack: "deploy",
+        stage: "PROD",
+        env: { region: "eu-west-1" },
+        riffRaffProjectName: "deploy::my-app",
+      });
+
+      expect(() => {
+        new RiffRaffYamlFile(app);
+      }).toThrow("Unable to produce a working riff-raff.yaml file; missing 1 definitions");
+    });
+  });
+});
+
+describe("The validateRiffRaffYamlDirectory function", () => {
+  it("accepts a child directory", () => {
+    const actual = validateRiffRaffYamlDirectory("/tmp/cdk.out", "playground::my-project");
+    expect(actual).toBe("/tmp/cdk.out/playground::my-project");
+  });
+
+  it("accepts a grand-child directory", () => {
+    const actual = validateRiffRaffYamlDirectory("/tmp/cdk.out", "playground/my-project");
+    expect(actual).toBe("/tmp/cdk.out/playground/my-project");
+  });
+
+  it("accepts the empty string", () => {
+    const actual = validateRiffRaffYamlDirectory("/tmp/cdk.out", "");
+    expect(actual).toBe("/tmp/cdk.out");
+  });
+
+  it("accepts a .. directory name", () => {
+    const actual = validateRiffRaffYamlDirectory("/tmp/cdk.out", "..final");
+    expect(actual).toBe("/tmp/cdk.out/..final");
+  });
+
+  it("rejects a parent directory", () => {
+    expect(() => {
+      validateRiffRaffYamlDirectory("/tmp/cdk.out", "../playground::my-project");
+    }).toThrow(
+      "Directory traversal detected: '../playground::my-project' would create a directory outside of /tmp/cdk.out (riffRaffProjectName=../playground::my-project, resolvedPath='/tmp/playground::my-project', resolvedBase='/tmp/cdk.out')",
+    );
+  });
+
+  it("accepts an ancestor directory", () => {
+    const actual = validateRiffRaffYamlDirectory("/tmp/cdk.out", "child/../final");
+    expect(actual).toBe("/tmp/cdk.out/final");
+  });
+
+  it("rejects a multi-ancestor directory", () => {
+    expect(() => {
+      validateRiffRaffYamlDirectory("/tmp/cdk.out", "child/../somewhere/../../final");
+    }).toThrow(
+      "Directory traversal detected: 'child/../somewhere/../../final' would create a directory outside of /tmp/cdk.out (riffRaffProjectName=child/../somewhere/../../final, resolvedPath='/tmp/final', resolvedBase='/tmp/cdk.out')",
+    );
   });
 });