codify-plugin-lib 1.0.37 → 1.0.39

package/src/entities/resource.ts

@@ -1,134 +1,246 @@
-import { ParameterOperation, ResourceConfig, ResourceOperation } from 'codify-schemas';
-import { ChangeSet, ParameterChange } from './change-set.js';
+import { ParameterOperation, ResourceConfig, ResourceOperation, StringIndexedObject, } from 'codify-schemas';
+import { ParameterChange } from './change-set.js';
 import { Plan } from './plan.js';
 import { StatefulParameter } from './stateful-parameter.js';
+import { ResourceConfiguration, ValidationResult } from './resource-types.js';
+import { setsEqual, splitUserConfig } from '../utils/utils.js';
+import { ParameterConfiguration, PlanConfiguration } from './plan-types.js';
+
+/**
+ * Description of resource here
+ * Two main functions:
+ * - Plan
+ * - Apply
+ *
+ */
+export abstract class Resource<T extends StringIndexedObject> {
+
+  readonly typeId: string;
+  readonly statefulParameters: Map<keyof T, StatefulParameter<T, T[keyof T]>>;
+  readonly dependencies: Resource<any>[]; // TODO: Change this to a string
+  readonly parameterConfigurations: Record<keyof T, ParameterConfiguration>
+
+  private readonly options: ResourceConfiguration<T>;
+
+  protected constructor(configuration: ResourceConfiguration<T>) {
+    this.validateResourceConfiguration(configuration);
+
+    this.typeId = configuration.type;
+    this.statefulParameters = new Map(configuration.statefulParameters?.map((sp) => [sp.name, sp]));
+    this.parameterConfigurations = this.generateParameterConfigurations(configuration);
+
+    this.dependencies = configuration.dependencies ?? [];
+    this.options = configuration;
+  }
 
-export type ErrorMessage = string;
+  getDependencyTypeIds(): string[] {
+    return this.dependencies.map((d) => d.typeId)
+  }
 
-export abstract class Resource<T extends ResourceConfig> {
+  async onInitialize(): Promise<void> {}
 
-  private statefulParameters: Map<string, StatefulParameter<T, keyof T>> = new Map();
+  // TODO: Add state in later.
+  //  Currently only calculating how to add things to reach desired state. Can't delete resources.
+  //  Add previousConfig as a parameter for plan(desired, previous);
+  async plan(desiredConfig: Partial<T> & ResourceConfig): Promise<Plan<T>> {
+
+    // Explanation: these are settings for how the plan will be generated
+    const planConfiguration: PlanConfiguration<T> = {
+      statefulMode: false,
+      parameterConfigurations: this.parameterConfigurations,
+    }
 
-  constructor(
-    private dependencies: Resource<any>[] = [],
-  ) {}
+    const { resourceMetadata, parameters: desiredParameters } = splitUserConfig(desiredConfig);
 
-  abstract getTypeId(): string;
+    const resourceParameters = Object.fromEntries([
+      ...Object.entries(desiredParameters).filter(([key]) => !this.statefulParameters.has(key)),
+    ]) as Partial<T>;
 
-  getDependencyTypeIds(): string[] {
-    return this.dependencies.map((d) => d.getTypeId())
-  }
+    const statefulParameters = [...this.statefulParameters.values()]
+      .filter((sp) => desiredParameters[sp.name] !== undefined) // Checking for undefined is fine here because JSONs can only have null.
 
-  async onInitialize(): Promise<void> {}
+    // Refresh resource parameters
+    // This refreshes the parameters that configure the resource itself
+    const keysToRefresh = new Set(Object.keys(resourceParameters));
+    const currentParameters = await this.refresh(keysToRefresh);
 
-  // TODO: Add state in later.
-  //  Calculate change set from current config -> state -> desired in the future
-  async plan(desiredConfig: T): Promise<Plan<T>> {
-    const currentConfig = await this.getCurrentConfig(desiredConfig);
-    if (!currentConfig) {
-      return Plan.create(ChangeSet.createForNullCurrentConfig(desiredConfig), desiredConfig);
+    if (currentParameters == null && statefulParameters.length === 0) {
+      return Plan.create(desiredConfig, null, planConfiguration);
     }
 
-    // Fetch the status of stateful parameters separately
-    const desiredConfigStatefulParameters = [...this.statefulParameters.values()]
-      .filter((sp) => desiredConfig[sp.name] !== undefined)
-    for(const statefulParameter of desiredConfigStatefulParameters) {
-      const parameterCurrentStatus = await statefulParameter.getCurrent(desiredConfig[statefulParameter.name]);
-      if (parameterCurrentStatus) {
-        currentConfig[statefulParameter.name] = parameterCurrentStatus;
+    this.validateRefreshResults(currentParameters, keysToRefresh);
+
+    // Refresh stateful parameters
+    // This refreshes parameters that are stateful (they can be added, deleted separately from the resource)
+    const currentStatefulParameters = {} as Partial<T>;
+
+    for(const statefulParameter of statefulParameters) {
+      const desiredValue = desiredParameters[statefulParameter.name];
+
+      let currentValue = await statefulParameter.refresh(desiredValue ?? null) ?? undefined;
+
+      // In stateless mode, filter the refreshed parameters by the desired to ensure that no deletes happen
+      if (Array.isArray(currentValue) && Array.isArray(desiredValue) && !planConfiguration.statefulMode) {
+        currentValue = currentValue.filter((p) => desiredValue?.includes(p)) as any;
       }
-    }
 
-    // TODO: After adding in state files, need to calculate deletes here
-    //  Where current config exists and state config exists but desired config doesn't
-
-    // Explanation: This calculates the change set of the parameters between the
-    // two configs and then passes it to the subclass to calculate the overall
-    // operation for the resource
-    const parameterChangeSet = ChangeSet.calculateParameterChangeSet(currentConfig, desiredConfig);
-    const resourceOperation = parameterChangeSet
-      .filter((change) => change.operation !== ParameterOperation.NOOP)
-      .reduce((operation: ResourceOperation, curr: ParameterChange) => {
-        const newOperation = !this.statefulParameters.has(curr.name)
-          ? this.calculateOperation(curr)
-          : ResourceOperation.MODIFY; // All stateful parameters are modify only
-        return ChangeSet.combineResourceOperations(operation, newOperation);
-      }, ResourceOperation.NOOP);
+      currentStatefulParameters[statefulParameter.name] = currentValue;
+    }
 
     return Plan.create(
-      new ChangeSet(resourceOperation, parameterChangeSet),
-      desiredConfig
-    );
+      desiredConfig,
+      { ...currentParameters, ...currentStatefulParameters, ...resourceMetadata } as Partial<T> & ResourceConfig,
+      planConfiguration,
+    )
   }
 
   async apply(plan: Plan<T>): Promise<void> {
-    if (plan.getResourceType() !== this.getTypeId()) {
-      throw new Error(`Internal error: Plan set to wrong resource during apply. Expected ${this.getTypeId()} but got: ${plan.getResourceType()}`);
+    if (plan.getResourceType() !== this.typeId) {
+      throw new Error(`Internal error: Plan set to wrong resource during apply. Expected ${this.typeId} but got: ${plan.getResourceType()}`);
     }
 
     switch (plan.changeSet.operation) {
+      case ResourceOperation.CREATE: {
+        return this._applyCreate(plan); // TODO: Add new parameters value so that apply
+      }
       case ResourceOperation.MODIFY: {
-        const parameterChanges = plan.changeSet.parameterChanges
-          .filter((c: ParameterChange) => c.operation !== ParameterOperation.NOOP);
+        return this._applyModify(plan);
+      }
+      case ResourceOperation.RECREATE: {
+        await this._applyDestroy(plan);
+        return this._applyCreate(plan);
+      }
+      case ResourceOperation.DESTROY: {
+        return this._applyDestroy(plan);
+      }
+    }
+  }
 
-        const statelessParameterChanges = parameterChanges.filter((pc: ParameterChange) => !this.statefulParameters.has(pc.name))
-        if (statelessParameterChanges.length > 0) {
-          await this.applyModify(plan);
-        }
+  private async _applyCreate(plan: Plan<T>): Promise<void> {
+    await this.applyCreate(plan);
 
-        const statefulParameterChanges = parameterChanges.filter((pc: ParameterChange) => this.statefulParameters.has(pc.name))
-        for (const parameterChange of statefulParameterChanges) {
-          const statefulParameter = this.statefulParameters.get(parameterChange.name)!;
-          switch (parameterChange.operation) {
-            case ParameterOperation.ADD: {
-              await statefulParameter.applyAdd(parameterChange, plan);
-              break;
-            }
-            case ParameterOperation.MODIFY: {
-              await statefulParameter.applyModify(parameterChange, plan);
-              break;
-            }
-            case ParameterOperation.REMOVE: {
-              await statefulParameter.applyRemove(parameterChange, plan);
-              break;
-            }
-          }
+    const statefulParameterChanges = plan.changeSet.parameterChanges
+      .filter((pc: ParameterChange<T>) => this.statefulParameters.has(pc.name))
+    for (const parameterChange of statefulParameterChanges) {
+      const statefulParameter = this.statefulParameters.get(parameterChange.name)!;
+      await statefulParameter.applyAdd(parameterChange.newValue, plan);
+    }
+  }
+
+  private async _applyModify(plan: Plan<T>): Promise<void> {
+    const parameterChanges = plan
+      .changeSet
+      .parameterChanges
+      .filter((c: ParameterChange<T>) => c.operation !== ParameterOperation.NOOP);
+
+    const statelessParameterChanges = parameterChanges
+      .filter((pc: ParameterChange<T>) => !this.statefulParameters.has(pc.name))
+    for (const pc of statelessParameterChanges) {
+      // TODO: When stateful mode is added in the future. Dynamically choose if deletes are allowed
+      await this.applyModify(pc.name, pc.newValue, pc.previousValue, false, plan);
+    }
+
+    const statefulParameterChanges = parameterChanges
+      .filter((pc: ParameterChange<T>) => this.statefulParameters.has(pc.name))
+    for (const parameterChange of statefulParameterChanges) {
+      const statefulParameter = this.statefulParameters.get(parameterChange.name)!;
+
+      switch (parameterChange.operation) {
+        case ParameterOperation.ADD: {
+          await statefulParameter.applyAdd(parameterChange.newValue, plan);
+          break;
+        }
+        case ParameterOperation.MODIFY: {
+          // TODO: When stateful mode is added in the future. Dynamically choose if deletes are allowed
+          await statefulParameter.applyModify(parameterChange.newValue, parameterChange.previousValue, false, plan);
+          break;
+        }
+        case ParameterOperation.REMOVE: {
+          await statefulParameter.applyRemove(parameterChange.previousValue, plan);
+          break;
         }
+      }
+    }
+  }
 
-        return;
+  private async _applyDestroy(plan: Plan<T>): Promise<void> {
+    // If this option is set (defaults to false), then stateful parameters need to be destroyed
+    // as well. This means that the stateful parameter wouldn't have been normally destroyed with applyDestroy()
+    if (this.options.callStatefulParameterRemoveOnDestroy) {
+      const statefulParameterChanges = plan.changeSet.parameterChanges
+        .filter((pc: ParameterChange<T>) => this.statefulParameters.has(pc.name))
+      for (const parameterChange of statefulParameterChanges) {
+        const statefulParameter = this.statefulParameters.get(parameterChange.name)!;
+        await statefulParameter.applyRemove(parameterChange.previousValue, plan);
       }
-      case ResourceOperation.CREATE: {
-        await this.applyCreate(plan);
-        const statefulParameterChanges = plan.changeSet.parameterChanges
-          .filter((pc: ParameterChange) => this.statefulParameters.has(pc.name))
+    }
+
+    await this.applyDestroy(plan);
+  }
 
-        for (const parameterChange of statefulParameterChanges) {
-          const statefulParameter = this.statefulParameters.get(parameterChange.name)!;
-          await statefulParameter.applyAdd(parameterChange, plan);
+  private generateParameterConfigurations(
+    resourceConfiguration: ResourceConfiguration<T>
+  ): Record<keyof T, ParameterConfiguration>  {
+    const resourceParameters = Object.fromEntries(
+      Object.entries(resourceConfiguration.parameterConfigurations ?? {})
+        ?.map(([name, value]) => ([name, { ...value, isStatefulParameter: false }]))
+    ) as Record<keyof T, ParameterConfiguration>
+
+    const statefulParameters = resourceConfiguration.statefulParameters
+      ?.reduce((obj, sp) => {
+        return {
+          ...obj,
+          [sp.name]: {
+            ...sp.configuration,
+            isStatefulParameter: true,
+          }
         }
+      }, {}) ?? {}
 
-        return;
-      }
-      case ResourceOperation.RECREATE: return this.applyRecreate(plan);
-      case ResourceOperation.DESTROY: return this.applyDestroy(plan);
+    return {
+      ...resourceParameters,
+      ...statefulParameters,
     }
+
   }
 
-  protected registerStatefulParameter(parameter: StatefulParameter<T, keyof T>) {
-    this.statefulParameters.set(parameter.name as string, parameter);
+  private validateResourceConfiguration(data: ResourceConfiguration<T>) {
+    // A parameter cannot be both stateful and stateless
+    if (data.parameterConfigurations && data.statefulParameters) {
+      const parameters = [...Object.keys(data.parameterConfigurations)];
+      const statefulParameterSet = new Set(Object.keys(data.statefulParameters));
+
+      const intersection = parameters.some((p) => statefulParameterSet.has(p));
+      if (intersection) {
+        throw new Error(`Resource ${this.typeId} cannot declare a parameter as both stateful and non-stateful`);
+      }
+    }
   }
 
-  abstract validate(config: unknown): Promise<ErrorMessage[] | undefined>;
+  private validateRefreshResults(refresh: Partial<T> | null, desiredKeys: Set<keyof T>) {
+    if (!refresh) {
+      return;
+    }
+
+    const refreshKeys = new Set(Object.keys(refresh)) as Set<keyof T>;
+
+    if (!setsEqual(desiredKeys, refreshKeys)) {
+      throw new Error(
+        `Resource ${this.options.type}
+refresh() must return back exactly the keys that were provided
+Missing: ${[...desiredKeys].filter((k) => !refreshKeys.has(k))};
+Additional: ${[...refreshKeys].filter(k => !desiredKeys.has(k))};`
+      );
+    }
+  }
 
-  abstract getCurrentConfig(desiredConfig: T): Promise<T | null>;
+  abstract validate(config: unknown): Promise<ValidationResult>;
 
-  abstract calculateOperation(change: ParameterChange): ResourceOperation.MODIFY | ResourceOperation.RECREATE;
+  abstract refresh(keys: Set<keyof T>): Promise<Partial<T> | null>;
 
   abstract applyCreate(plan: Plan<T>): Promise<void>;
 
-  abstract applyModify(plan: Plan<T>): Promise<void>;
-
-  abstract applyRecreate(plan: Plan<T>): Promise<void>;
+  async applyModify(parameterName: keyof T, newValue: unknown, previousValue: unknown, allowDeletes: boolean, plan: Plan<T>): Promise<void> {};
 
-  abstract applyDestroy(plan:Plan<T>): Promise<void>;
+  abstract applyDestroy(plan: Plan<T>): Promise<void>;
 }

package/src/entities/stateful-parameter.ts

@@ -1,13 +1,61 @@
-import { ParameterChange } from './change-set.js';
 import { Plan } from './plan.js';
-import { ResourceConfig } from 'codify-schemas';
+import { StringIndexedObject } from 'codify-schemas';
 
-export abstract class StatefulParameter<T extends ResourceConfig, K extends keyof T> {
-  abstract get name(): K;
+export interface StatefulParameterConfiguration<T> {
+  name: keyof T;
+  isEqual?: (a: any, b: any) => boolean;
+}
+
+export abstract class StatefulParameter<T extends StringIndexedObject, V extends T[keyof T]> {
+  readonly name: keyof T;
+  readonly configuration: StatefulParameterConfiguration<T>;
+
+  protected constructor(configuration: StatefulParameterConfiguration<T>) {
+    this.name = configuration.name;
+    this.configuration = configuration
+  }
+
+  abstract refresh(previousValue: V | null): Promise<V | null>;
+
+  // TODO: Add an additional parameter here for what has actually changed.
+  abstract applyAdd(valueToAdd: V, plan: Plan<T>): Promise<void>;
+  abstract applyModify(newValue: V, previousValue: V, allowDeletes: boolean, plan: Plan<T>): Promise<void>;
+  abstract applyRemove(valueToRemove: V, plan: Plan<T>): Promise<void>;
+}
+
+export abstract class ArrayStatefulParameter<T extends StringIndexedObject, V> extends StatefulParameter<T, any>{
+  protected constructor(configuration: StatefulParameterConfiguration<T>) {
+    super(configuration);
+  }
+
+  async applyAdd(valuesToAdd: V[], plan: Plan<T>): Promise<void> {
+    for (const value of valuesToAdd) {
+      await this.applyAddItem(value, plan);
+    }
+  }
+
+  async applyModify(newValues: V[], previousValues: V[], allowDeletes: boolean, plan: Plan<T>): Promise<void> {
+    const valuesToAdd = newValues.filter((n) => !previousValues.includes(n));
+    const valuesToRemove = previousValues.filter((n) => !newValues.includes(n));
+
+    for (const value of valuesToAdd) {
+      await this.applyAddItem(value, plan)
+    }
+
+    if (allowDeletes) {
+      for (const value of valuesToRemove) {
+        await this.applyRemoveItem(value, plan)
+      }
+    }
+  }
 
-  abstract getCurrent(desiredValue: T[K]): Promise<T[K]>;
+  async applyRemove(valuesToRemove: V[], plan: Plan<T>): Promise<void> {
+    for (const value of valuesToRemove) {
+      await this.applyRemoveItem(value as V, plan);
+    }
+  }
 
-  abstract applyAdd(parameterChange: ParameterChange, plan: Plan<T>): Promise<void>;
-  abstract applyModify(parameterChange: ParameterChange, plan: Plan<T>): Promise<void>;
-  abstract applyRemove(parameterChange: ParameterChange, plan: Plan<T>): Promise<void>;
+  abstract refresh(previousValue: V[] | null): Promise<V[] | null>;
+  abstract applyAddItem(item: V, plan: Plan<T>): Promise<void>;
+  abstract applyRemoveItem(item: V, plan: Plan<T>): Promise<void>;
 }

package/src/index.ts

@@ -2,9 +2,11 @@ import { Plugin } from './entities/plugin.js';
 import { MessageHandler } from './messages/handlers.js';
 
 export * from './entities/resource.js'
+export * from './entities/resource-types.js'
 export * from './entities/plugin.js'
 export * from './entities/change-set.js'
 export * from './entities/plan.js'
+export * from './entities/plan-types.js'
 export * from './entities/stateful-parameter.js'
 
 export * from './utils/test-utils.js'
@@ -14,3 +16,4 @@ export async function runPlugin(plugin: Plugin) {
   const messageHandler = new MessageHandler(plugin);
   process.on('message', (message) => messageHandler.onMessage(message))
 }
+export { ErrorMessage } from './entities/resource-types.js';

package/src/utils/utils.ts

@@ -1,5 +1,6 @@
 import promiseSpawn from '@npmcli/promise-spawn';
 import { SpawnOptions } from 'child_process';
+import { ResourceConfig, StringIndexedObject } from 'codify-schemas';
 
 export enum SpawnStatus {
   SUCCESS = 'success',
@@ -78,3 +79,23 @@ export async function codifySpawn(
 export function isDebug(): boolean {
   return process.env.DEBUG != null && process.env.DEBUG.includes('codify'); // TODO: replace with debug library
 }
+
+export function splitUserConfig<T extends StringIndexedObject>(
+  config: T & ResourceConfig
+): { parameters: T;  resourceMetadata: ResourceConfig} {
+  const resourceMetadata = {
+    type: config.type,
+    ...(config.name && { name: config.name }),
+    ...(config.dependsOn && { dependsOn: config.dependsOn }),
+  };
+
+  const { type, name, dependsOn, ...parameters } = config;
+  return {
+    parameters: parameters as T,
+    resourceMetadata,
+  };
+}
+
+export function setsEqual(set1: Set<unknown>, set2: Set<unknown>): boolean {
+  return set1.size === set2.size && [...set1].every((v) => set2.has(v));
+}