codify-plugin-lib 1.0.75 → 1.0.77

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

@@ -1,4 +1,3 @@
-import { Resource } from './resource.js';
 import {
   ApplyRequestData,
   InitializeResponseData,
@@ -8,37 +7,43 @@ import {
   ValidateRequestData,
   ValidateResponseData
 } from 'codify-schemas';
-import { Plan } from './plan.js';
+
+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';
 
 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) => ({
-          type: r.typeId,
           dependencies: r.dependencies,
+          type: r.typeId,
         }))
     }
   }
@@ -46,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);
     }
@@ -67,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
@@ -83,12 +88,12 @@ export class Plugin {
 
   async apply(data: ApplyRequestData): Promise<void> {
     if (!data.planId && !data.plan) {
-      throw new Error(`For applies either plan or planId must be supplied`);
+      throw new Error('For applies either plan or planId must be supplied');
     }
 
     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');
     }
@@ -97,7 +102,7 @@ export class Plugin {
   }
 
   private resolvePlan(data: ApplyRequestData): Plan<ResourceConfig> {
-    const { planId, plan: planRequest } = data;
+    const { plan: planRequest, planId } = data;
 
     if (planId) {
       if (!this.planStorage.has(planId)) {
@@ -107,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(data.plan, resource.defaultValues);
+    const resource = this.resourceControllers.get(planRequest.resourceType)!;
+    return Plan.fromResponse(planRequest, resource.parsedSettings.defaultValues);
   }
 
   protected async crossValidateResources(configs: ResourceConfig[]): Promise<void> {}

package/src/resource/config-parser.ts

@@ -0,0 +1,77 @@
+import { ResourceConfig, StringIndexedObject } from 'codify-schemas';
+
+import { splitUserConfig } from '../utils/utils.js';
+import { StatefulParameter } from './stateful-parameter.js';
+
+export class ConfigParser<T extends StringIndexedObject> {
+  private readonly desiredConfig: Partial<T> & ResourceConfig | null;
+  private readonly stateConfig: Partial<T> & ResourceConfig | null;
+  private statefulParametersMap: Map<keyof T, StatefulParameter<T, T[keyof T]>>;
+
+  constructor(
+    desiredConfig: Partial<T> & ResourceConfig | null,
+    stateConfig: Partial<T> & ResourceConfig | null,
+    statefulParameters: Map<keyof T, StatefulParameter<T, T[keyof T]>>,
+  ) {
+    this.desiredConfig = desiredConfig;
+    this.stateConfig = stateConfig
+    this.statefulParametersMap = statefulParameters;
+  }
+
+  get coreParameters(): ResourceConfig {
+    const desiredCoreParameters = this.desiredConfig ? splitUserConfig(this.desiredConfig).coreParameters : undefined;
+    const currentCoreParameters = this.stateConfig ? splitUserConfig(this.stateConfig).coreParameters : undefined;
+
+    if (!desiredCoreParameters && !currentCoreParameters) {
+      throw new Error(`Unable to parse resource core parameters from:
+       
+ Desired: ${JSON.stringify(this.desiredConfig, null, 2)}
+  
+ Current: ${JSON.stringify(this.stateConfig, null, 2)}`)
+    }
+
+    return desiredCoreParameters ?? currentCoreParameters!;
+  }
+
+  get desiredParameters(): Partial<T> | null {
+    if (!this.desiredConfig) {
+      return null;
+    }
+
+    const { parameters } = splitUserConfig(this.desiredConfig);
+    return parameters;
+  }
+
+  get stateParameters(): Partial<T> | null {
+    if (!this.stateConfig) {
+      return null;
+    }
+
+    const { parameters } = splitUserConfig(this.stateConfig);
+    return parameters;
+  }
+
+
+  get allParameters(): Partial<T> {
+    return { ...this.desiredParameters, ...this.stateParameters } as Partial<T>;
+  }
+
+  get allNonStatefulParameters(): Partial<T> {
+    const {
+      allParameters,
+      statefulParametersMap,
+    } = this;
+
+    return Object.fromEntries(
+      Object.entries(allParameters).filter(([key]) => !statefulParametersMap.has(key))
+    ) as Partial<T>;
+  }
+
+  get allStatefulParameters(): Partial<T> {
+    const { allParameters, statefulParametersMap } = this;
+
+    return Object.fromEntries(
+      Object.entries(allParameters).filter(([key]) => statefulParametersMap.has(key))
+    ) as Partial<T>;
+  }
+}

package/src/{entities/resource-options.test.ts → resource/parsed-resource-settings.test.ts}

@@ -1,20 +1,21 @@
 import { describe, expect, it } from 'vitest';
-import { ResourceOptions, ResourceOptionsParser } from './resource-options.js';
-import { TestConfig } from './resource.test.js';
+import { ResourceSettings } from './resource-settings.js';
+import { ParsedResourceSettings } from './parsed-resource-settings.js';
+import { TestConfig } from '../utils/test-utils.test.js';
 
 describe('Resource options parser tests', () => {
   it('Parses default values from options', () => {
-    const option: ResourceOptions<TestConfig> = {
-      type: 'typeId',
-      parameterOptions: {
+    const option: ResourceSettings<TestConfig> = {
+      id: 'typeId',
+      parameterSettings: {
         propA: { default: 'propA' },
         propB: { default: 'propB' },
         propC: { isEqual: () => true },
-        propD: { },
+        propD: {},
       }
     }
 
-    const result = new ResourceOptionsParser(option);
+    const result = new ParsedResourceSettings(option);
     expect(result.defaultValues).to.deep.eq({
       propA: 'propA',
       propB: 'propB'