codify-plugin-lib 1.0.76 → 1.0.77

package/src/resource/resource-settings.test.ts

@@ -0,0 +1,494 @@
+import { describe, expect, it } from 'vitest';
+import { Plan } from '../plan/plan.js';
+import { spy } from 'sinon';
+import { ParameterOperation, ResourceOperation } from 'codify-schemas';
+import {
+  TestArrayStatefulParameter,
+  TestConfig,
+  testPlan,
+  TestResource,
+  TestStatefulParameter
+} from '../utils/test-utils.test.js';
+import { ArrayParameterSetting, ParameterSetting, ResourceSettings } from './resource-settings.js';
+import { ResourceController } from './resource-controller.js';
+
+describe('Resource parameter tests', () => {
+  it('Generates a resource plan that includes stateful parameters (create)', async () => {
+    const statefulParameter = spy(new class extends TestStatefulParameter {
+      async refresh(): Promise<string | null> {
+        return null;
+      }
+    })
+
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'type',
+          parameterSettings: {
+            propA: { type: 'stateful', definition: statefulParameter }
+          },
+        };
+      }
+
+      async refresh(): Promise<any> {
+        return null;
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan({
+      type: 'type',
+      propA: 'a',
+      propB: 10
+    })
+
+    expect(statefulParameter.refresh.notCalled).to.be.true;
+    expect(plan.currentConfig).to.be.null;
+    expect(plan.desiredConfig).toMatchObject({
+      type: 'type',
+      propA: 'a',
+      propB: 10
+    })
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.CREATE);
+  })
+
+  it('supports the creation of stateful parameters', async () => {
+
+    const statefulParameter = new class extends TestStatefulParameter {
+      async refresh(): Promise<string | null> {
+        return null;
+      }
+    }
+
+    const statefulParameterSpy = spy(statefulParameter);
+
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'type',
+          parameterSettings: {
+            propA: { type: 'stateful', definition: statefulParameterSpy }
+          },
+        }
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const resourceSpy = spy(resource);
+
+    await controller.apply(
+      testPlan<TestConfig>({
+        desired: { propA: 'a', propB: 0, propC: 'c' }
+      })
+    );
+
+    expect(statefulParameterSpy.add.calledOnce).to.be.true;
+    expect(resourceSpy.create.calledOnce).to.be.true;
+  })
+
+  it('supports the modification of stateful parameters', async () => {
+    const statefulParameter = new class extends TestStatefulParameter {
+      async refresh(): Promise<string | null> {
+        return 'b';
+      }
+    }
+
+    const statefulParameterSpy = spy(statefulParameter);
+
+    const resource = new class extends TestResource {
+
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'type',
+          parameterSettings: {
+            propA: { type: 'stateful', definition: statefulParameterSpy },
+            propB: { canModify: true },
+          }
+        };
+      }
+
+      async refresh(): Promise<Partial<TestConfig> | null> {
+        return { propB: -1, propC: 'b' }
+      }
+    }
+
+    const controller = new ResourceController(resource);
+
+    const plan = await controller.plan({ type: 'type', propA: 'a', propB: 0, propC: 'b' })
+
+    const resourceSpy = spy(resource);
+    await controller.apply(plan);
+
+    expect(statefulParameterSpy.modify.calledOnce).to.be.true;
+    expect(resourceSpy.modify.calledOnce).to.be.true;
+  })
+
+  it('Allows stateful parameters to have default values', async () => {
+    const statefulParameter = spy(new class extends TestStatefulParameter {
+      getSettings(): ParameterSetting {
+        return {
+          default: 'abc'
+        };
+      }
+
+      async refresh(): Promise<string | null> {
+        return null;
+      }
+    });
+
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'type',
+          parameterSettings: {
+            propA: { type: 'stateful', definition: statefulParameter }
+          },
+        }
+      }
+
+      async refresh(): Promise<any> {
+        return null;
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan({
+      type: 'type',
+    })
+
+    expect(statefulParameter.refresh.notCalled).to.be.true;
+    expect(plan.currentConfig).to.be.null;
+    expect(plan.desiredConfig).toMatchObject({
+      type: 'type',
+      propA: 'abc',
+    })
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.CREATE);
+  })
+
+  it('Filters array results in stateless mode to prevent modify from being called', async () => {
+    const statefulParameter = new class extends TestStatefulParameter {
+      getSettings(): ParameterSetting {
+        return { type: 'array' }
+      }
+
+      async refresh(): Promise<any | null> {
+        return ['a', 'b', 'c', 'd']
+      }
+    }
+
+    const statefulParameterSpy = spy(statefulParameter);
+
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'type',
+          parameterSettings: {
+            propA: { type: 'stateful', definition: statefulParameterSpy },
+          },
+        }
+      }
+
+      async refresh(): Promise<Partial<TestConfig> | null> {
+        return {};
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan({ type: 'type', propA: ['a', 'b'] } as any)
+
+    expect(plan).toMatchObject({
+      changeSet: {
+        operation: ResourceOperation.NOOP,
+      }
+    })
+  })
+
+  it('Filters array results in stateless mode to prevent modify from being called 2', async () => {
+    const statefulParameter = new class extends TestStatefulParameter {
+      async refresh(): Promise<any | null> {
+        return ['a', 'b']
+      }
+    }
+
+    const statefulParameterSpy = spy(statefulParameter);
+
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'type',
+          parameterSettings: {
+            propA: { type: 'stateful', definition: statefulParameterSpy }
+          },
+        }
+      }
+
+      async refresh(): Promise<Partial<TestConfig> | null> {
+        return {};
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan({ type: 'type', propA: ['a', 'b', 'c', 'd'] } as any)
+
+    expect(plan).toMatchObject({
+      changeSet: {
+        operation: ResourceOperation.MODIFY,
+      }
+    })
+  })
+
+  it('Uses isElementEqual for stateless mode filtering if available', async () => {
+    const statefulParameter = new class extends TestArrayStatefulParameter {
+      getSettings(): ArrayParameterSetting {
+        return {
+          type: 'array',
+          isElementEqual: (desired, current) => {
+            return current.includes(desired)
+          },
+        }
+      }
+
+      async refresh(): Promise<any | null> {
+        return ['3.11.9']
+      }
+    }
+
+    const statefulParameterSpy = spy(statefulParameter);
+
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'type',
+          parameterSettings: {
+            propA: { type: 'stateful', definition: statefulParameterSpy }
+          },
+        }
+      }
+
+      async refresh(): Promise<Partial<TestConfig> | null> {
+        return {};
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan({ type: 'type', propA: ['3.11'] } as any)
+
+    expect(plan).toMatchObject({
+      changeSet: {
+        operation: ResourceOperation.NOOP,
+      }
+    })
+  })
+
+  it('Plans stateful parameters in the order specified', async () => {
+    const statefulParameterA = spy(new class extends TestStatefulParameter {
+      async refresh(): Promise<any | null> {
+        return performance.now()
+      }
+    });
+
+    const statefulParameterB = spy(new class extends TestStatefulParameter {
+      async refresh(): Promise<any | null> {
+        return performance.now()
+      }
+    });
+
+    const statefulParameterC = spy(new class extends TestStatefulParameter {
+      async refresh(): Promise<any | null> {
+        return performance.now()
+      }
+    });
+
+    const statefulParameterD = spy(new class extends TestStatefulParameter {
+      async refresh(): Promise<any | null> {
+        return performance.now()
+      }
+    });
+
+    const statefulParameterE = spy(new class extends TestStatefulParameter {
+      async refresh(): Promise<any | null> {
+        return performance.now()
+      }
+    });
+
+    const resource = spy(new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'resourceType',
+          parameterSettings: {
+            propA: { type: 'stateful', definition: statefulParameterA, order: 3 },
+            propB: { type: 'stateful', definition: statefulParameterB, order: 1 },
+            propC: { type: 'stateful', definition: statefulParameterC, order: 2 },
+            propD: { type: 'stateful', definition: statefulParameterD },
+            propE: { type: 'stateful', definition: statefulParameterE }
+          },
+        }
+      }
+
+      async refresh(): Promise<Partial<TestConfig> | null> {
+        return {};
+      }
+    });
+
+    const controller = new ResourceController(resource)
+    const plan = await controller.plan({
+      type: 'resourceType',
+      propA: 'propA',
+      propB: 10,
+      propC: 'propC',
+      propD: 'propD',
+      propE: 'propE',
+    });
+
+    expect(plan.currentConfig?.propB).to.be.lessThan(plan.currentConfig?.propC as any);
+    expect(plan.currentConfig?.propC).to.be.lessThan(plan.currentConfig?.propA as any);
+    expect(plan.currentConfig?.propA).to.be.lessThan(plan.currentConfig?.propD as any);
+    expect(plan.currentConfig?.propD).to.be.lessThan(plan.currentConfig?.propE as any);
+  })
+
+  it('Applies stateful parameters in the order specified', async () => {
+    let timestampA;
+    const statefulParameterA = spy(new class extends TestStatefulParameter {
+      add = async (): Promise<void> => {
+        timestampA = performance.now();
+      }
+      modify = async (): Promise<void> => {
+        timestampA = performance.now();
+      }
+      remove = async (): Promise<void> => {
+        timestampA = performance.now();
+      }
+    });
+
+    let timestampB
+    const statefulParameterB = spy(new class extends TestStatefulParameter {
+      add = async (): Promise<void> => {
+        timestampB = performance.now();
+      }
+      modify = async (): Promise<void> => {
+        timestampB = performance.now();
+      }
+      remove = async (): Promise<void> => {
+        timestampB = performance.now();
+      }
+    });
+
+    let timestampC
+    const statefulParameterC = spy(new class extends TestStatefulParameter {
+      add = async (): Promise<void> => {
+        timestampC = performance.now();
+      }
+      modify = async (): Promise<void> => {
+        timestampC = performance.now();
+      }
+      remove = async (): Promise<void> => {
+        timestampC = performance.now();
+      }
+    });
+
+    const resource = spy(new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'resourceType',
+          parameterSettings: {
+            propA: { type: 'stateful', definition: statefulParameterA, order: 3 },
+            propB: { type: 'stateful', definition: statefulParameterB, order: 1 },
+            propC: { type: 'stateful', definition: statefulParameterC, order: 2 },
+          },
+          removeStatefulParametersBeforeDestroy: true,
+        }
+      }
+    });
+
+    const controller = new ResourceController(resource);
+    await controller.apply(
+      Plan.fromResponse({
+        resourceType: 'resourceType',
+        operation: ResourceOperation.CREATE,
+        parameters: [
+          { name: 'propA', operation: ParameterOperation.ADD, previousValue: null, newValue: null },
+          { name: 'propB', operation: ParameterOperation.ADD, previousValue: null, newValue: null },
+          { name: 'propC', operation: ParameterOperation.ADD, previousValue: null, newValue: null },
+        ]
+      }, {}) as any
+    );
+
+    if (!timestampB || !timestampC || !timestampA) {
+      throw new Error('Variable not initialized')
+    }
+
+    expect(timestampB).to.be.lessThan(timestampC as any);
+    expect(timestampC).to.be.lessThan(timestampA as any);
+    timestampA = 0;
+    timestampB = 0;
+    timestampC = 0;
+
+    await controller.apply(
+      Plan.fromResponse({
+        resourceType: 'resourceType',
+        operation: ResourceOperation.MODIFY,
+        parameters: [
+          { name: 'propA', operation: ParameterOperation.MODIFY, previousValue: null, newValue: null },
+          { name: 'propB', operation: ParameterOperation.MODIFY, previousValue: null, newValue: null },
+          { name: 'propC', operation: ParameterOperation.MODIFY, previousValue: null, newValue: null },
+        ]
+      }, {}) as any
+    );
+
+    expect(timestampB).to.be.lessThan(timestampC as any);
+    expect(timestampC).to.be.lessThan(timestampA as any);
+    timestampA = 0;
+    timestampB = 0;
+    timestampC = 0;
+
+    await controller.apply(
+      Plan.fromResponse({
+        resourceType: 'resourceType',
+        operation: ResourceOperation.DESTROY,
+        parameters: [
+          { name: 'propA', operation: ParameterOperation.REMOVE, previousValue: null, newValue: null },
+          { name: 'propB', operation: ParameterOperation.REMOVE, previousValue: null, newValue: null },
+          { name: 'propC', operation: ParameterOperation.REMOVE, previousValue: null, newValue: null },
+        ]
+      }, {}) as any
+    );
+
+    expect(timestampB).to.be.lessThan(timestampC as any);
+    expect(timestampC).to.be.lessThan(timestampA as any);
+  })
+
+  it('Supports transform parameters', async () => {
+    const resource = spy(new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'resourceType',
+          inputTransformation: (desired) => ({
+            propA: 'propA',
+            propB: 10,
+          })
+        }
+      }
+
+      async refresh(): Promise<Partial<TestConfig> | null> {
+        return {
+          propA: 'propA',
+          propB: 10,
+        }
+      }
+    });
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan({ type: 'resourceType', propC: 'abc' } as any);
+
+    expect(resource.refresh.called).to.be.true;
+    expect(resource.refresh.getCall(0).firstArg['propA']).to.exist;
+    expect(resource.refresh.getCall(0).firstArg['propB']).to.exist;
+    expect(resource.refresh.getCall(0).firstArg['propC']).to.not.exist;
+
+    expect(plan.desiredConfig?.propA).to.eq('propA');
+    expect(plan.desiredConfig?.propB).to.eq(10);
+    expect(plan.desiredConfig?.propC).to.be.undefined;
+
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.NOOP);
+  })
+})

package/src/resource/resource-settings.ts

@@ -0,0 +1,192 @@
+import { StringIndexedObject } from 'codify-schemas';
+import path from 'node:path';
+
+import { untildify } from '../utils/utils.js';
+import { StatefulParameter } from './stateful-parameter.js';
+
+/**
+ * The configuration and settings for a resource.
+ */
+export interface ResourceSettings<T extends StringIndexedObject> {
+
+  /**
+   * The typeId of the resource.
+   */
+  id: string;
+
+  /**
+   * Schema to validate user configs with. Must be in the format JSON Schema draft07
+   */
+  schema?: unknown;
+
+  /**
+   * Allow multiple of the same resource to unique. Set truthy if
+   * multiples are allowed, for example for applications, there can be multiple copy of the same application installed
+   * on the system. Or there can be multiple git repos. Defaults to false.
+   */
+  allowMultiple?: {
+
+    /**
+     * If multiple copies are allowed then a matcher must be defined to match the desired
+     * config with one of the resources currently existing on the system. Return null if there is no match.
+     *
+     * @param current An array of resources found installed on the system
+     * @param desired The desired config to match.
+     *
+     * @return The matched resource.
+     */
+    matcher: (desired: Partial<T>, current: Partial<T>[],) => Partial<T>
+  }
+
+  /**
+   * If true, {@link StatefulParameter} remove() will be called before resource destruction. This is useful
+   * if the stateful parameter needs to be first uninstalled (cleanup) before the overall resource can be
+   * uninstalled. Defaults to false.
+   */
+  removeStatefulParametersBeforeDestroy?: boolean;
+
+  /**
+   * An array of type ids of resources that this resource depends on. This affects the order in which multiple resources are
+   * planned and applied.
+   */
+  dependencies?: string[];
+
+  /**
+   * Options for configuring parameters operations including overriding the equals function, adding default values
+   * and applying any input transformations. Use parameter settings to define stateful parameters as well.
+   */
+  parameterSettings?: Partial<Record<keyof T, ParameterSetting>>;
+
+  /**
+   * A config level transformation that is only applied to the user supplied desired config. This transformation is allowed
+   * to add, remove or modify keys as well as values. Changing this transformation for existing libraries will mess up existing states.
+   *
+   * @param desired
+   */
+  inputTransformation?: (desired: Partial<T>) => Promise<unknown> | unknown;
+}
+
+/**
+ * The type of parameter. This value is mainly used to determine a pre-set equality method for comparing the current
+ * config with desired config. Certain types will have additional options to help support it. For example the type
+ * stateful requires a stateful parameter definition and type array takes an isElementEqual method.
+ */
+export type ParameterSettingType =
+  'any'
+  | 'array'
+  | 'boolean'
+  | 'directory'
+  | 'number'
+  | 'stateful'
+  | 'string'
+  | 'version';
+
+/**
+ * Typing information for the parameter setting. This represents a setting on a specific parameter within a
+ * resource. Options for configuring parameters operations including overriding the equals function, adding default values
+ * and applying any input transformations. See {@link DefaultParameterSetting } for more information.
+ * Use parameter settings to define stateful parameters as well.
+ */
+
+export type ParameterSetting =
+  ArrayParameterSetting
+  | DefaultParameterSetting
+  | StatefulParameterSetting
+
+/**
+ * The parent class for parameter settings. The options are applicable to array parameter settings
+ * as well.
+ */
+export interface DefaultParameterSetting {
+  /**
+   * The type of the value of this parameter. See {@link ParameterSettingType} for the available options. This value
+   * is mainly used to determine the equality method when performing diffing.
+   */
+  type?: ParameterSettingType;
+
+  /**
+   * Default value for the parameter. If a value is not provided in the config, then this value will be used.
+   */
+  default?: unknown;
+
+  /**
+   * A transformation of the input value for this parameter. This transformation is only applied to the desired parameter
+   * value supplied by the user.
+   *
+   * @param input The original parameter value from the desired config.
+   */
+  inputTransformation?: (input: any) => Promise<any> | unknown;
+
+  /**
+   * Customize the equality comparison for a parameter. This is used in the diffing algorithm for generating the plan.
+   * This value will override the pre-set equality function from the type. Return true if the desired value is
+   * equivalent to the current value.
+   *
+   * @param desired The desired value.
+   * @param current The current value.
+   *
+   * @return Return true if equal
+   */
+  isEqual?: (desired: any, current: any) => boolean;
+
+  /**
+   * Chose if the resource can be modified instead of re-created when there is a change to this parameter.
+   * Defaults to false (re-create).
+   *
+   * Examples:
+   * 1. Settings like git user name and git user email that have setter calls and don't require the re-installation of git
+   * 2. AWS profile secret keys that can be updated without the re-installation of AWS CLI
+   */
+  canModify?: boolean
+}
+
+/**
+ * Array type specific settings. See {@link DefaultParameterSetting } for a full list of options.
+ */
+export interface ArrayParameterSetting extends DefaultParameterSetting {
+  type: 'array'
+
+  /**
+   * An element level equality function for arrays. The diffing algorithm will take isElementEqual and use it in a
+   * O(n^2) equality comparison to determine if the overall array is equal. This value will override the pre-set equality
+   * function for arrays (desired === current). Return true if the desired element is equivalent to the current element.
+   *
+   * @param desired An element of the desired array
+   * @param current An element of the current array
+   *
+   * @return Return true if desired is equivalent to current.
+   */
+  isElementEqual?: (desired: any, current: any) => boolean
+}
+
+/**
+ * Stateful parameter type specific settings. A stateful parameter is a sub-resource that can hold its own
+ * state but is still tied to the overall state of the resource. For example 'homebrew' is represented
+ * as a resource and taps, formulas and casks are represented as a stateful parameter. A formula can be installed,
+ * modified and removed (has state) but it is still tied to the overall lifecycle of homebrew.
+ *
+ */
+export interface StatefulParameterSetting extends DefaultParameterSetting {
+  type: 'stateful',
+
+  /**
+   * The stateful parameter definition. A stateful parameter is a sub-resource that can hold its own
+   * state but is still tied to the overall state of the resource. For example 'homebrew' is represented
+   * as a resource and taps, formulas and casks are represented as a stateful parameter. A formula can be installed,
+   * modified and removed (has state) but it is still tied to the overall lifecycle of homebrew.
+   */
+  definition: StatefulParameter<any, unknown>,
+
+  /**
+   * The order multiple stateful parameters should be applied in. The order is applied in ascending order (1, 2, 3...).
+   */
+  order?: number,
+}
+
+export const ParameterEqualsDefaults: Partial<Record<ParameterSettingType, (a: unknown, b: unknown) => boolean>> = {
+  'boolean': (a: unknown, b: unknown) => Boolean(a) === Boolean(b),
+  'directory': (a: unknown, b: unknown) => path.resolve(untildify(String(a))) === path.resolve(untildify(String(b))),
+  'number': (a: unknown, b: unknown) => Number(a) === Number(b),
+  'string': (a: unknown, b: unknown) => String(a) === String(b),
+  'version': (desired: unknown, current: unknown) => String(current).includes(String(desired))
+}