codify-plugin-lib 1.0.76 → 1.0.77

package/src/plan/plan-types.ts

@@ -0,0 +1,27 @@
+import { StringIndexedObject } from 'codify-schemas';
+
+import { Plan } from './plan.js';
+
+/**
+ * A narrower type for plans for CREATE operations. Only desiredConfig is not null.
+ */
+export interface CreatePlan<T extends StringIndexedObject> extends Plan<T> {
+  desiredConfig: T;
+  currentConfig: null;
+}
+
+/**
+ * A narrower type for plans for DESTROY operations. Only currentConfig is not null.
+ */
+export interface DestroyPlan<T extends StringIndexedObject> extends Plan<T> {
+  desiredConfig: null;
+  currentConfig: T;
+}
+
+/**
+ * A narrower type for plans for MODIFY and RE-CREATE operations.
+ */
+export interface ModifyPlan<T extends StringIndexedObject> extends Plan<T> {
+  desiredConfig: T;
+  currentConfig: T;
+}

package/src/{entities → plan}/plan.test.ts

@@ -1,12 +1,15 @@
 import { describe, expect, it } from 'vitest';
 import { Plan } from './plan.js';
-import { TestResource } from './resource.test.js';
 import { ParameterOperation, ResourceOperation } from 'codify-schemas';
-import { Resource } from './resource.js';
+import { TestConfig, TestResource } from '../utils/test-utils.test.js';
+import { ResourceController } from '../resource/resource-controller.js';
+import { ParsedResourceSettings } from '../resource/parsed-resource-settings.js';
+import { ResourceSettings } from '../resource/resource-settings.js';
 
 describe('Plan entity tests', () => {
   it('Adds default values properly when plan is parsed from request (Create)', () => {
-    const resource = createResource();
+    const resource = createTestResource()
+    const controller = new ResourceController(resource);
 
     const plan = Plan.fromResponse({
       operation: ResourceOperation.CREATE,
@@ -17,7 +20,7 @@ describe('Plan entity tests', () => {
         previousValue: null,
         newValue: 'propBValue'
       }]
-    }, resource.defaultValues);
+    }, controller.parsedSettings.defaultValues);
 
     expect(plan.currentConfig).to.be.null;
 
@@ -33,7 +36,8 @@ describe('Plan entity tests', () => {
   })
 
   it('Adds default values properly when plan is parsed from request (Destroy)', () => {
-    const resource = createResource();
+    const resource = createTestResource()
+    const controller = new ResourceController(resource);
 
     const plan = Plan.fromResponse({
       operation: ResourceOperation.DESTROY,
@@ -44,7 +48,7 @@ describe('Plan entity tests', () => {
         previousValue: 'propBValue',
         newValue: null,
       }]
-    }, resource.defaultValues);
+    }, controller.parsedSettings.defaultValues);
 
     expect(plan.currentConfig).toMatchObject({
       type: 'type',
@@ -60,7 +64,8 @@ describe('Plan entity tests', () => {
   })
 
   it('Adds default values properly when plan is parsed from request (No-op)', () => {
-    const resource = createResource();
+    const resource = createTestResource()
+    const controller = new ResourceController(resource);
 
     const plan = Plan.fromResponse({
       operation: ResourceOperation.NOOP,
@@ -71,7 +76,7 @@ describe('Plan entity tests', () => {
         previousValue: 'propBValue',
         newValue: 'propBValue',
       }]
-    }, resource.defaultValues);
+    }, controller.parsedSettings.defaultValues);
 
     expect(plan.currentConfig).toMatchObject({
       type: 'type',
@@ -91,7 +96,8 @@ describe('Plan entity tests', () => {
   })
 
   it('Does not add default value if a value has already been specified', () => {
-    const resource = createResource();
+    const resource = createTestResource()
+    const controller = new ResourceController(resource);
 
     const plan = Plan.fromResponse({
       operation: ResourceOperation.CREATE,
@@ -107,7 +113,7 @@ describe('Plan entity tests', () => {
         previousValue: null,
         newValue: 'propAValue',
       }]
-    }, resource.defaultValues);
+    }, controller.parsedSettings.defaultValues);
 
     expect(plan.currentConfig).to.be.null
 
@@ -123,19 +129,17 @@ describe('Plan entity tests', () => {
   })
 
   it('Returns the original resource names', () => {
-    const resource = createResource();
-
-    const plan = Plan.create(
-      {
-        propA: 'propA',
-      },
-      {
-        propA: 'propA2',
-      },
-      {
+    const plan = Plan.calculate<TestConfig>({
+      desiredParameters: { propA: 'propA' },
+      currentParametersArray: [{ propA: 'propA2' }],
+      stateParameters: null,
+      coreParameters: {
         type: 'type',
         name: 'name1'
-      }, { statefulMode: false });
+      },
+      settings: new ParsedResourceSettings<TestConfig>({ id: 'type' }),
+      statefulMode: false,
+    });
 
     expect(plan.toResponse()).toMatchObject({
       resourceType: 'type',
@@ -145,15 +149,17 @@ describe('Plan entity tests', () => {
   })
 })
 
-function createResource(): Resource<any> {
+function createTestResource() {
   return new class extends TestResource {
-    constructor() {
-      super({
-        type: 'type',
-        parameterOptions: {
-          propA: { default: 'defaultA' }
+    getSettings(): ResourceSettings<TestConfig> {
+      return {
+        id: 'type',
+        parameterSettings: {
+          propA: {
+            default: 'defaultA'
+          }
         }
-      });
+      }
     }
-  }
+  };
 }

package/src/plan/plan.ts

@@ -0,0 +1,353 @@
+import {
+  ApplyRequestData,
+  ParameterOperation,
+  PlanResponseData,
+  ResourceConfig,
+  ResourceOperation,
+  StringIndexedObject,
+} from 'codify-schemas';
+import { v4 as uuidV4 } from 'uuid';
+
+import { ParsedResourceSettings } from '../resource/parsed-resource-settings.js';
+import { ArrayParameterSetting, ResourceSettings, StatefulParameterSetting } from '../resource/resource-settings.js';
+import { ChangeSet } from './change-set.js';
+
+/**
+ * A plan represents a set of actions that after taken will turn the current resource into the desired one.
+ * A plan consists of list of parameter level changes (ADD, REMOVE, MODIFY or NO-OP) as well as a resource level
+ * operation (CREATE, DESTROY, MODIFY, RE-CREATE, NO-OP).
+ */
+export class Plan<T extends StringIndexedObject> {
+  id: string;
+  changeSet: ChangeSet<T>;
+  coreParameters: ResourceConfig
+
+  constructor(id: string, changeSet: ChangeSet<T>, resourceMetadata: ResourceConfig) {
+    this.id = id;
+    this.changeSet = changeSet;
+    this.coreParameters = resourceMetadata;
+  }
+
+  /**
+   * The desired config that a plan will achieve after executing all the actions.
+   */
+  get desiredConfig(): T | null {
+    if (this.changeSet.operation === ResourceOperation.DESTROY) {
+      return null;
+    }
+
+    return {
+      ...this.coreParameters,
+      ...this.changeSet.desiredParameters,
+    }
+  }
+
+  /**
+   * The current config that the plan is changing.
+   */
+  get currentConfig(): T | null {
+    if (this.changeSet.operation === ResourceOperation.CREATE) {
+      return null;
+    }
+
+    return {
+      ...this.coreParameters,
+      ...this.changeSet.currentParameters,
+    }
+  }
+
+  /**
+   * When multiples of the same resource are allowed, this matching function will match a given config with one of the
+   * existing configs on the system. For example if there are multiple versions of Android Studios installed, we can use
+   * the application name and location to match it to our desired configs name and location.
+   *
+   * @param params
+   * @private
+   */
+  private static matchCurrentParameters<T extends StringIndexedObject>(params: {
+    desiredParameters: Partial<T> | null,
+    currentParametersArray: Partial<T>[] | null,
+    stateParameters: Partial<T> | null,
+    settings: ResourceSettings<T>,
+    statefulMode: boolean,
+  }): Partial<T> | null {
+    const {
+      desiredParameters,
+      currentParametersArray,
+      stateParameters,
+      settings,
+      statefulMode
+    } = params;
+
+    if (!settings.allowMultiple) {
+      return currentParametersArray?.[0] ?? null;
+    }
+
+    if (!currentParametersArray) {
+      return null;
+    }
+
+    if (statefulMode) {
+      return stateParameters
+        ? settings.allowMultiple.matcher(stateParameters, currentParametersArray)
+        : null
+    }
+
+    return settings.allowMultiple.matcher(desiredParameters!, currentParametersArray);
+  }
+
+  /**
+   * The type (id) of the resource
+   *
+   * @return string
+   */
+  getResourceType(): string {
+    return this.coreParameters.type
+  }
+
+  static calculate<T extends StringIndexedObject>(params: {
+    desiredParameters: Partial<T> | null,
+    currentParametersArray: Partial<T>[] | null,
+    stateParameters: Partial<T> | null,
+    coreParameters: ResourceConfig,
+    settings: ParsedResourceSettings<T>,
+    statefulMode: boolean,
+  }): Plan<T> {
+    const {
+      desiredParameters,
+      currentParametersArray,
+      stateParameters,
+      coreParameters,
+      settings,
+      statefulMode
+    } = params
+
+    const currentParameters = Plan.matchCurrentParameters<T>({
+      desiredParameters,
+      currentParametersArray,
+      stateParameters,
+      settings,
+      statefulMode
+    });
+
+    const filteredCurrentParameters = Plan.filterCurrentParams<T>({
+      desiredParameters,
+      currentParameters,
+      stateParameters,
+      settings,
+      statefulMode
+    });
+
+    // Empty
+    if (!filteredCurrentParameters && !desiredParameters) {
+      return new Plan(
+        uuidV4(),
+        ChangeSet.empty<T>(),
+        coreParameters,
+      )
+    }
+
+    // CREATE
+    if (!filteredCurrentParameters && desiredParameters) {
+      return new Plan(
+        uuidV4(),
+        ChangeSet.create(desiredParameters),
+        coreParameters
+      )
+    }
+
+    // DESTROY
+    if (filteredCurrentParameters && !desiredParameters) {
+      return new Plan(
+        uuidV4(),
+        ChangeSet.destroy(filteredCurrentParameters),
+        coreParameters
+      )
+    }
+
+    // NO-OP, MODIFY or RE-CREATE
+    const changeSet = ChangeSet.calculateModification(
+      desiredParameters!,
+      filteredCurrentParameters!,
+      settings.parameterSettings,
+    );
+
+    return new Plan(
+      uuidV4(),
+      changeSet,
+      coreParameters,
+    );
+  }
+
+  /**
+   *  Only keep relevant params for the plan. We don't want to change settings that were not already
+   *  defined.
+   *
+   *  1. In stateless mode, filter current by desired. We only want to know about settings that the user has specified
+   *  2. In stateful mode, filter current by state and desired. We only know about the settings the user has previously set
+   *  or wants to set. If a parameter is not specified then it's not managed by Codify.
+   */
+  private static filterCurrentParams<T extends StringIndexedObject>(params: {
+    desiredParameters: Partial<T> | null,
+    currentParameters: Partial<T> | null,
+    stateParameters: Partial<T> | null,
+    settings: ResourceSettings<T>,
+    statefulMode: boolean,
+  }): Partial<T> | null {
+    const {
+      desiredParameters: desired,
+      currentParameters: current,
+      stateParameters: state,
+      settings,
+      statefulMode
+    } = params;
+
+    if (!current) {
+      return null;
+    }
+
+    const filteredCurrent = filterCurrent()
+    if (!filteredCurrent) {
+      return null
+    }
+
+    // For stateful mode, we're done after filtering by the keys of desired + state. Stateless mode
+    // requires additional filtering for stateful parameter arrays and objects.
+    if (statefulMode) {
+      return filteredCurrent;
+    }
+
+    // TODO: Add object handling here in addition to arrays in the future
+    const arrayStatefulParameters = Object.fromEntries(
+      Object.entries(filteredCurrent)
+        .filter(([k, v]) => isArrayStatefulParameter(k, v))
+        .map(([k, v]) => [k, filterArrayStatefulParameter(k, v)])
+    )
+
+    return { ...filteredCurrent, ...arrayStatefulParameters }
+
+    function filterCurrent(): Partial<T> | null {
+      if (!current) {
+        return null;
+      }
+
+      if (statefulMode) {
+        const keys = new Set([...Object.keys(state ?? {}), ...Object.keys(desired ?? {})]);
+        return Object.fromEntries(
+          Object.entries(current)
+            .filter(([k]) => keys.has(k))
+        ) as Partial<T>;
+      }
+
+      // Stateless mode
+      const keys = new Set(Object.keys(desired ?? {}));
+      return Object.fromEntries(
+        Object.entries(current)
+          .filter(([k]) => keys.has(k))
+      ) as Partial<T>;
+    }
+
+    function isArrayStatefulParameter(k: string, v: T[keyof T]): boolean {
+      return settings.parameterSettings?.[k]?.type === 'stateful'
+        && (settings.parameterSettings[k] as StatefulParameterSetting).definition.getSettings().type === 'array'
+        && Array.isArray(v)
+    }
+
+    function filterArrayStatefulParameter(k: string, v: unknown[]): unknown[] {
+      const desiredArray = desired![k] as unknown[];
+      const matcher = ((settings.parameterSettings![k] as StatefulParameterSetting)
+        .definition
+        .getSettings() as ArrayParameterSetting)
+        .isElementEqual;
+
+      return v.filter((cv) =>
+        desiredArray.find((dv) => (matcher ?? ((a: any, b: any) => a === b))(dv, cv))
+      )
+    }
+  }
+
+  // TODO: This needs to be revisited. I don't think this is valid anymore.
+  //   1. For all scenarios, there shouldn't be an apply without a plan beforehand
+  //   2. Even if there was (maybe for testing reasons), the plan values should not be adjusted
+  static fromResponse<T extends ResourceConfig>(data: ApplyRequestData['plan'], defaultValues?: Partial<Record<keyof T, unknown>>): Plan<T> {
+    if (!data) {
+      throw new Error('Data is empty');
+    }
+
+    addDefaultValues();
+
+    return new Plan(
+      uuidV4(),
+      new ChangeSet<T>(
+        data.operation,
+        data.parameters
+      ),
+      {
+        type: data.resourceType,
+        name: data.resourceName,
+      },
+    );
+
+   function addDefaultValues(): void {
+      Object.entries(defaultValues ?? {})
+        .forEach(([key, defaultValue]) => {
+          const configValueExists = data!
+            .parameters
+            .some((p) => p.name === key);
+
+          // Only set default values if the value does not exist in the config
+          if (configValueExists) {
+            return;
+          }
+
+          switch (data!.operation) {
+            case ResourceOperation.CREATE: {
+              data!.parameters.push({
+                name: key,
+                operation: ParameterOperation.ADD,
+                previousValue: null,
+                newValue: defaultValue,
+              });
+              break;
+            }
+
+            case ResourceOperation.DESTROY: {
+              data!.parameters.push({
+                name: key,
+                operation: ParameterOperation.REMOVE,
+                previousValue: defaultValue,
+                newValue: null,
+              });
+              break;
+            }
+
+            case ResourceOperation.MODIFY:
+            case ResourceOperation.RECREATE:
+            case ResourceOperation.NOOP: {
+              data!.parameters.push({
+                name: key,
+                operation: ParameterOperation.NOOP,
+                previousValue: defaultValue,
+                newValue: defaultValue,
+              });
+              break;
+            }
+          }
+        });
+    }
+
+  }
+
+  /**
+   * Convert the plan to a JSON response object
+   */
+  toResponse(): PlanResponseData {
+    return {
+      planId: this.id,
+      operation: this.changeSet.operation,
+      resourceName: this.coreParameters.name,
+      resourceType: this.coreParameters.type,
+      parameters: this.changeSet.parameterChanges,
+    }
+  }
+}

package/src/{entities → plugin}/plugin.test.ts

@@ -1,9 +1,10 @@
 import { describe, expect, it } from 'vitest';
 import { Plugin } from './plugin.js';
 import { ParameterOperation, ResourceOperation, StringIndexedObject } from 'codify-schemas';
-import { Resource } from './resource.js';
-import { Plan } from './plan.js';
+import { Resource } from '../resource/resource.js';
+import { Plan } from '../plan/plan.js';
 import { spy } from 'sinon';
+import { ResourceSettings } from '../resource/resource-settings.js';
 
 interface TestConfig extends StringIndexedObject {
   propA: string;
@@ -12,17 +13,17 @@ interface TestConfig extends StringIndexedObject {
 }
 
 class TestResource extends Resource<TestConfig> {
-  constructor() {
-    super({
-      type: 'testResource'
-    });
+  getSettings(): ResourceSettings<TestConfig> {
+    return {
+      id: 'testResource'
+    };
   }
 
-  applyCreate(plan: Plan<TestConfig>): Promise<void> {
+  create(plan: Plan<TestConfig>): Promise<void> {
     return Promise.resolve(undefined);
   }
 
-  applyDestroy(plan: Plan<TestConfig>): Promise<void> {
+  destroy(plan: Plan<TestConfig>): Promise<void> {
     return Promise.resolve(undefined);
   }
 
@@ -49,7 +50,7 @@ describe('Plugin tests', () => {
     };
 
     await plugin.apply({ plan });
-    expect(resource.applyCreate.calledOnce).to.be.true;
+    expect(resource.create.calledOnce).to.be.true;
   });
 
   it('Can destroy resource', async () => {
@@ -65,7 +66,7 @@ describe('Plugin tests', () => {
     };
 
     await testPlugin.apply({ plan })
-    expect(resource.applyDestroy.calledOnce).to.be.true;
+    expect(resource.destroy.calledOnce).to.be.true;
   });
 
   it('Can re-create resource', async () => {
@@ -81,8 +82,8 @@ describe('Plugin tests', () => {
     };
 
     await testPlugin.apply({ plan })
-    expect(resource.applyDestroy.calledOnce).to.be.true;
-    expect(resource.applyCreate.calledOnce).to.be.true;
+    expect(resource.destroy.calledOnce).to.be.true;
+    expect(resource.create.calledOnce).to.be.true;
   });
 
   it('Can modify resource', async () => {
@@ -98,6 +99,6 @@ describe('Plugin tests', () => {
     };
 
     await testPlugin.apply({ plan })
-    expect(resource.applyModify.calledOnce).to.be.true;
+    expect(resource.modify.calledOnce).to.be.true;
   });
 });

package/src/{entities → plugin}/plugin.ts

@@ -8,35 +8,39 @@ import {
   ValidateResponseData
 } from 'codify-schemas';
 
+import { Plan } from '../plan/plan.js';
+import { Resource } from '../resource/resource.js';
+import { ResourceController } from '../resource/resource-controller.js';
 import { splitUserConfig } from '../utils/utils.js';
-import { Plan } from './plan.js';
-import { Resource } from './resource.js';
 
 export class Plugin {
   planStorage: Map<string, Plan<any>>;
 
-  static create(name: string, resources: Resource<any>[]) {
-    const resourceMap = new Map<string, Resource<any>>(
-      resources.map((r) => [r.typeId, r] as const)
-    );
-
-    return new Plugin(name, resourceMap);
-  }
-
   constructor(
     public name: string,
-    public resources: Map<string, Resource<ResourceConfig>>
+    public resourceControllers: Map<string, ResourceController<ResourceConfig>>
   ) {
     this.planStorage = new Map();
   }
 
+  static create(name: string, resources: Resource<any>[]) {
+    const controllers = resources
+      .map((resource) => new ResourceController(resource))
+
+    const controllersMap = new Map<string, ResourceController<any>>(
+      controllers.map((r) => [r.typeId, r] as const)
+    );
+
+    return new Plugin(name, controllersMap);
+  }
+
   async initialize(): Promise<InitializeResponseData> {
-    for (const resource of this.resources.values()) {
-      await resource.onInitialize();
+    for (const controller of this.resourceControllers.values()) {
+      await controller.initialize();
     }
 
     return {
-      resourceDefinitions: [...this.resources.values()]
+      resourceDefinitions: [...this.resourceControllers.values()]
         .map((r) => ({
           dependencies: r.dependencies,
           type: r.typeId,
@@ -47,14 +51,14 @@ export class Plugin {
   async validate(data: ValidateRequestData): Promise<ValidateResponseData> {
     const validationResults = [];
     for (const config of data.configs) {
-      if (!this.resources.has(config.type)) {
+      if (!this.resourceControllers.has(config.type)) {
         throw new Error(`Resource type not found: ${config.type}`);
       }
 
-      const { parameters, resourceMetadata } = splitUserConfig(config);
-      const validation = await this.resources
+      const { parameters, coreParameters } = splitUserConfig(config);
+      const validation = await this.resourceControllers
         .get(config.type)!
-        .validate(parameters, resourceMetadata);
+        .validate(parameters, coreParameters);
 
       validationResults.push(validation);
     }
@@ -68,11 +72,11 @@ export class Plugin {
   async plan(data: PlanRequestData): Promise<PlanResponseData> {
     const type = data.desired?.type ?? data.state?.type
 
-    if (!type || !this.resources.has(type)) {
+    if (!type || !this.resourceControllers.has(type)) {
       throw new Error(`Resource type not found: ${type}`);
     }
 
-    const plan = await this.resources.get(type)!.plan(
+    const plan = await this.resourceControllers.get(type)!.plan(
       data.desired ?? null,
       data.state ?? null,
       data.isStateful
@@ -89,7 +93,7 @@ export class Plugin {
 
     const plan = this.resolvePlan(data);
 
-    const resource = this.resources.get(plan.getResourceType());
+    const resource = this.resourceControllers.get(plan.getResourceType());
     if (!resource) {
       throw new Error('Malformed plan with resource that cannot be found');
     }
@@ -108,12 +112,12 @@ export class Plugin {
       return this.planStorage.get(planId)!
     }
 
-    if (!planRequest?.resourceType || !this.resources.has(planRequest.resourceType)) {
+    if (!planRequest?.resourceType || !this.resourceControllers.has(planRequest.resourceType)) {
       throw new Error('Malformed plan. Resource type must be supplied or resource type was not found');
     }
 
-    const resource = this.resources.get(planRequest.resourceType)!;
-    return Plan.fromResponse(planRequest, resource.defaultValues);
+    const resource = this.resourceControllers.get(planRequest.resourceType)!;
+    return Plan.fromResponse(planRequest, resource.parsedSettings.defaultValues);
   }
 
   protected async crossValidateResources(configs: ResourceConfig[]): Promise<void> {}