codify-plugin-lib 1.0.76 → 1.0.77

package/dist/utils/utils.js

@@ -1,11 +1,27 @@
 import promiseSpawn from '@npmcli/promise-spawn';
+import os from 'node:os';
 export var SpawnStatus;
 (function (SpawnStatus) {
     SpawnStatus["SUCCESS"] = "success";
     SpawnStatus["ERROR"] = "error";
 })(SpawnStatus || (SpawnStatus = {}));
+/**
+ *
+ * @param cmd Command to run. Ex: `rm -rf`
+ * @param args Optional additional arguments to append
+ * @param opts Standard options for node spawn. Additional argument:
+ * throws determines if a shell will throw a JS error. Defaults to true
+ * @param extras From PromiseSpawn
+ *
+ * @see promiseSpawn
+ * @see spawn
+ *
+ * @returns SpawnResult { status: SUCCESS | ERROR; data: string }
+ */
 export async function codifySpawn(cmd, args, opts, extras) {
     try {
+        // TODO: Need to benchmark the effects of using sh vs zsh for shell.
+        //  Seems like zsh shells run slower
         const result = await promiseSpawn(cmd, args ?? [], { ...opts, stdio: 'pipe', stdioString: true, shell: opts?.shell ?? process.env.SHELL }, extras);
         if (isDebug()) {
             console.log(`codifySpawn result for: ${cmd}`);
@@ -34,20 +50,53 @@ export async function codifySpawn(cmd, args, opts, extras) {
     }
 }
 export function isDebug() {
-    return process.env.DEBUG != null && process.env.DEBUG.includes('codify');
+    return process.env.DEBUG != null && process.env.DEBUG.includes('codify'); // TODO: replace with debug library
 }
 export function splitUserConfig(config) {
-    const resourceMetadata = {
+    const coreParameters = {
         type: config.type,
         ...(config.name ? { name: config.name } : {}),
         ...(config.dependsOn ? { dependsOn: config.dependsOn } : {}),
     };
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const { type, name, dependsOn, ...parameters } = config;
     return {
         parameters: parameters,
-        resourceMetadata,
+        coreParameters,
     };
 }
 export function setsEqual(set1, set2) {
     return set1.size === set2.size && [...set1].every((v) => set2.has(v));
 }
+const homeDirectory = os.homedir();
+export function untildify(pathWithTilde) {
+    return homeDirectory ? pathWithTilde.replace(/^~(?=$|\/|\\)/, homeDirectory) : pathWithTilde;
+}
+export function areArraysEqual(parameter, desired, current) {
+    if (!Array.isArray(desired) || !Array.isArray(current)) {
+        throw new Error(`A non-array value:
+          
+Desired: ${JSON.stringify(desired, null, 2)}
+
+Current: ${JSON.stringify(desired, null, 2)}
+
+Was provided even though type array was specified.
+`);
+    }
+    if (desired.length !== current.length) {
+        return false;
+    }
+    const desiredCopy = [...desired];
+    const currentCopy = [...current];
+    // Algorithm for to check equality between two un-ordered; un-hashable arrays using
+    // an isElementEqual method. Time: O(n^2)
+    for (let counter = desiredCopy.length - 1; counter >= 0; counter--) {
+        const idx = currentCopy.findIndex((e2) => (parameter.isElementEqual ?? ((a, b) => a === b))(desiredCopy[counter], e2));
+        if (idx === -1) {
+            return false;
+        }
+        desiredCopy.splice(counter, 1);
+        currentCopy.splice(idx, 1);
+    }
+    return currentCopy.length === 0;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codify-plugin-lib",
-  "version": "1.0.76",
-  "description": "",
+  "version": "1.0.77",
+  "description": "Library plugin library",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
   "type": "module",
@@ -15,7 +15,8 @@
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",
     "codify-schemas": "1.0.45",
-    "@npmcli/promise-spawn": "^7.0.1"
+    "@npmcli/promise-spawn": "^7.0.1",
+    "uuid": "^10.0.0"
   },
   "devDependencies": {
     "@oclif/prettier-config": "^0.2.1",
@@ -24,6 +25,7 @@
     "@types/node": "^18",
     "@types/semver": "^7.5.4",
     "@types/sinon": "^17.0.3",
+    "@types/uuid": "^10.0.0",
     "chai-as-promised": "^7.1.1",
     "vitest": "^1.4.0",
     "vitest-mock-extended": "^1.3.1",

package/src/index.ts

@@ -1,16 +1,15 @@
-import { Plugin } from './entities/plugin.js';
 import { MessageHandler } from './messages/handlers.js';
+import { Plugin } from './plugin/plugin.js';
 
-export * from './entities/resource.js'
-export * from './entities/resource-types.js'
-export * from './entities/resource-options.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 './entities/errors.js'
-
+export * from './errors.js'
+export * from './plan/change-set.js'
+export * from './plan/plan.js'
+export * from './plan/plan-types.js'
+export * from './plugin/plugin.js'
+export * from './resource/parsed-resource-settings.js';
+export * from './resource/resource.js'
+export * from './resource/resource-settings.js'
+export * from './resource/stateful-parameter.js'
 export * from './utils/utils.js'
 
 export async function runPlugin(plugin: Plugin) {

package/src/messages/handlers.test.ts

@@ -1,10 +1,10 @@
 import { MessageHandler } from './handlers.js';
-import { Plugin } from '../entities/plugin.js';
+import { Plugin } from '../plugin/plugin.js';
 import { describe, expect, it } from 'vitest';
 import { mock } from 'vitest-mock-extended'
-import { Resource } from '../entities/resource.js';
-import { Plan } from '../entities/plan.js';
+import { Resource } from '../resource/resource.js';
 import { MessageStatus, ResourceOperation } from 'codify-schemas';
+import { TestResource } from '../utils/test-utils.test.js';
 
 describe('Message handler tests', () => {
   it('handles plan requests', async () => {
@@ -151,7 +151,7 @@ describe('Message handler tests', () => {
   })
 
   it('handles errors for plan', async () => {
-    const resource= testResource();
+    const resource = new TestResource()
     const plugin = testPlugin(resource);
 
     const handler = new MessageHandler(plugin);
@@ -179,7 +179,7 @@ describe('Message handler tests', () => {
   })
 
   it('handles errors for apply (create)', async () => {
-    const resource= testResource();
+    const resource = new TestResource()
     const plugin = testPlugin(resource);
 
     const handler = new MessageHandler(plugin);
@@ -188,7 +188,6 @@ describe('Message handler tests', () => {
       expect(message).toMatchObject({
         cmd: 'apply_Response',
         status: MessageStatus.ERROR,
-        data: 'Create error',
       })
       return true;
     }
@@ -206,7 +205,7 @@ describe('Message handler tests', () => {
   })
 
   it('handles errors for apply (destroy)', async () => {
-    const resource= testResource();
+    const resource = new TestResource()
     const plugin = testPlugin(resource);
 
     const handler = new MessageHandler(plugin);
@@ -215,7 +214,6 @@ describe('Message handler tests', () => {
       expect(message).toMatchObject({
         cmd: 'apply_Response',
         status: MessageStatus.ERROR,
-        data: 'Destroy error',
       })
       return true;
     }
@@ -231,33 +229,8 @@ describe('Message handler tests', () => {
       }
     })).rejects.to.not.throw;
   })
-
-
-  const testResource = () => new class extends Resource<any> {
-    constructor() {
-      super({ type: 'resourceA' });
-    }
-
-    async refresh(keys: Map<keyof any, any>): Promise<Partial<any> | null> {
-      throw new Error('Refresh error');
-    }
-
-    applyCreate(plan: Plan<any>): Promise<void> {
-      throw new Error('Create error');
-    }
-
-    applyDestroy(plan: Plan<any>): Promise<void> {
-      throw new Error('Destroy error');
-    }
-  }
-
-  const testPlugin = (resource: Resource<any>) => new class extends Plugin {
-    constructor() {
-      const map = new Map();
-      map.set('resourceA', resource);
-
-      super('name', map);
-    }
-  }
-
 });
+
+function testPlugin(resource: Resource<any>) {
+  return Plugin.create('plugin', [resource])
+}

package/src/messages/handlers.ts

@@ -15,8 +15,8 @@ import {
   ValidateResponseDataSchema
 } from 'codify-schemas';
 
-import { SudoError } from '../entities/errors.js';
-import { Plugin } from '../entities/plugin.js';
+import { SudoError } from '../errors.js';
+import { Plugin } from '../plugin/plugin.js';
 
 const SupportedRequests: Record<string, { handler: (plugin: Plugin, data: any) => Promise<unknown>; requestValidator: SchemaObject; responseValidator: SchemaObject }> = {
   'apply': {

package/src/plan/change-set.test.ts

@@ -0,0 +1,220 @@
+import { ChangeSet } from './change-set.js';
+import { ParameterOperation, ResourceOperation } from 'codify-schemas';
+import { describe, expect, it } from 'vitest';
+
+describe('Change set tests', () => {
+  it ('Correctly diffs two resource configs (modify)', () => {
+    const after = {
+      propA: 'before',
+      propB: 'before'
+    }
+
+    const before = {
+      propA: 'after',
+      propB: 'after'
+    }
+
+    const cs = ChangeSet.calculateModification(after, before);
+    expect(cs.parameterChanges.length).to.eq(2);
+    expect(cs.parameterChanges[0].operation).to.eq(ParameterOperation.MODIFY);
+    expect(cs.parameterChanges[1].operation).to.eq(ParameterOperation.MODIFY);
+    expect(cs.operation).to.eq(ResourceOperation.RECREATE)
+  })
+
+  it ('Correctly diffs two resource configs (add)', () => {
+    const after = {
+      propA: 'before',
+      propB: 'after'
+    }
+
+    const before = {
+      propA: 'after',
+    }
+
+    const cs = ChangeSet.calculateModification(after, before,);
+    expect(cs.parameterChanges.length).to.eq(2);
+    expect(cs.parameterChanges[0].operation).to.eq(ParameterOperation.MODIFY);
+    expect(cs.parameterChanges[1].operation).to.eq(ParameterOperation.ADD);
+    expect(cs.operation).to.eq(ResourceOperation.RECREATE)
+
+  })
+
+  it ('Correctly diffs two resource configs (remove)', () => {
+    const after = {
+      propA: 'after',
+    }
+
+    const before = {
+      propA: 'before',
+      propB: 'before'
+    }
+
+    const cs = ChangeSet.calculateModification(after, before);
+    expect(cs.parameterChanges.length).to.eq(2);
+    expect(cs.parameterChanges[0].operation).to.eq(ParameterOperation.MODIFY);
+    expect(cs.parameterChanges[1].operation).to.eq(ParameterOperation.REMOVE);
+    expect(cs.operation).to.eq(ResourceOperation.RECREATE)
+  })
+
+  it ('Correctly diffs two resource configs (no-op)', () => {
+    const after = {
+      propA: 'prop',
+    }
+
+    const before = {
+      propA: 'prop',
+    }
+
+    const cs = ChangeSet.calculateModification(after, before);
+    expect(cs.parameterChanges.length).to.eq(1);
+    expect(cs.parameterChanges[0].operation).to.eq(ParameterOperation.NOOP);
+    expect(cs.operation).to.eq(ResourceOperation.NOOP)
+  })
+
+  it('Correctly diffs two resource configs (create)', () => {
+    const cs = ChangeSet.create({
+      propA: 'prop',
+      propB: 'propB'
+    });
+
+    expect(cs.parameterChanges.length).to.eq(2);
+    expect(cs.parameterChanges[0].operation).to.eq(ParameterOperation.ADD);
+    expect(cs.parameterChanges[1].operation).to.eq(ParameterOperation.ADD);
+    expect(cs.operation).to.eq(ResourceOperation.CREATE)
+  })
+
+  it('Correctly diffs two resource configs (destory)', () => {
+    const cs = ChangeSet.destroy({
+      propA: 'prop',
+      propB: 'propB'
+    });
+
+    expect(cs.parameterChanges.length).to.eq(2);
+    expect(cs.parameterChanges[0].operation).to.eq(ParameterOperation.REMOVE);
+    expect(cs.parameterChanges[1].operation).to.eq(ParameterOperation.REMOVE);
+    expect(cs.operation).to.eq(ResourceOperation.DESTROY)
+  })
+
+  it ('handles simple arrays', () => {
+    const before = {
+      propA: ['a', 'b', 'c'],
+    }
+
+    const after = {
+      propA: ['b', 'a', 'c'],
+    }
+
+    const cs = ChangeSet.calculateModification(after, before, { propA: { type: 'array' } });
+    expect(cs.parameterChanges.length).to.eq(1);
+    expect(cs.parameterChanges[0].operation).to.eq(ParameterOperation.NOOP);
+    expect(cs.operation).to.eq(ResourceOperation.NOOP)
+  })
+
+  it('handles simple arrays 2', () => {
+    const after = {
+      propA: ['a', 'b', 'c'],
+    }
+
+    const before = {
+      propA: ['b', 'a'],
+    }
+
+    const cs = ChangeSet.calculateModification(after, before, { propA: { type: 'array' } });
+    expect(cs.parameterChanges.length).to.eq(1);
+    expect(cs.parameterChanges[0].operation).to.eq(ParameterOperation.MODIFY);
+    expect(cs.operation).to.eq(ResourceOperation.RECREATE)
+  })
+
+  it('determines the order of operations with canModify 1', () => {
+    const after = {
+      propA: 'after',
+    }
+
+    const before = {
+      propA: 'before',
+      propB: 'before'
+    }
+
+    const cs = ChangeSet.calculateModification(after, before, { propA: { canModify: true } });
+    expect(cs.parameterChanges.length).to.eq(2);
+    expect(cs.parameterChanges[0].operation).to.eq(ParameterOperation.MODIFY);
+    expect(cs.parameterChanges[1].operation).to.eq(ParameterOperation.REMOVE);
+    expect(cs.operation).to.eq(ResourceOperation.RECREATE)
+  })
+
+  it('determines the order of operations with canModify 2', () => {
+    const after = {
+      propA: 'after',
+    }
+
+    const before = {
+      propA: 'before',
+      propB: 'before'
+    }
+
+    const cs = ChangeSet.calculateModification<any>(after, before, {
+      propA: { canModify: true },
+      propB: { canModify: true }
+    });
+    expect(cs.parameterChanges.length).to.eq(2);
+    expect(cs.parameterChanges[0].operation).to.eq(ParameterOperation.MODIFY);
+    expect(cs.parameterChanges[1].operation).to.eq(ParameterOperation.REMOVE);
+    expect(cs.operation).to.eq(ResourceOperation.MODIFY)
+  })
+
+
+  it('correctly determines array equality', () => {
+    const arrA = ['a', 'b', 'd'];
+    const arrB = ['a', 'b', 'd'];
+
+    const result = ChangeSet.calculateModification({ propA: arrA }, { propA: arrB }, { propA: { type: 'array' } })
+
+    expect(result.operation).to.eq(ResourceOperation.NOOP);
+  })
+
+  it('correctly determines array equality 2', () => {
+    const arrA = ['a', 'b'];
+    const arrB = ['a', 'b', 'd'];
+
+    const result = ChangeSet.calculateModification({ propA: arrA }, { propA: arrB }, { propA: { type: 'array' } })
+
+    expect(result.parameterChanges[0].operation).to.eq(ParameterOperation.MODIFY);
+  })
+
+  it('correctly determines array equality 3', () => {
+    const arrA = ['b', 'a', 'd'];
+    const arrB = ['a', 'b', 'd'];
+
+    const result = ChangeSet.calculateModification({ propA: arrA }, { propA: arrB }, { propA: { type: 'array' } })
+
+    expect(result.parameterChanges[0].operation).to.eq(ParameterOperation.NOOP);
+  })
+
+  it('correctly determines array equality 4', () => {
+    const arrA = [{ key1: 'a' }, { key1: 'a' }, { key1: 'a' }];
+    const arrB = [{ key1: 'a' }, { key1: 'a' }, { key1: 'b' }];
+
+    const result = ChangeSet.calculateModification({ propA: arrA }, { propA: arrB }, {
+      propA: {
+        type: 'array',
+        isElementEqual: (a, b) => a.key1 === b.key1
+      }
+    })
+
+    expect(result.parameterChanges[0].operation).to.eq(ParameterOperation.MODIFY);
+  })
+
+  it('correctly determines array equality 5', () => {
+    const arrA = [{ key1: 'b' }, { key1: 'a' }, { key1: 'a' }];
+    const arrB = [{ key1: 'a' }, { key1: 'a' }, { key1: 'b' }];
+
+    const result = ChangeSet.calculateModification({ propA: arrA }, { propA: arrB }, {
+      propA: {
+        type: 'array',
+        isElementEqual: (a, b) => a.key1 === b.key1
+      }
+    })
+
+    expect(result.parameterChanges[0].operation).to.eq(ParameterOperation.NOOP);
+  })
+})

package/src/plan/change-set.ts

@@ -0,0 +1,225 @@
+import { ParameterOperation, ResourceOperation, StringIndexedObject } from 'codify-schemas';
+
+import { ArrayParameterSetting, ParameterSetting, StatefulParameterSetting } from '../resource/resource-settings.js';
+import { areArraysEqual } from '../utils/utils.js';
+
+/**
+ * A parameter change describes a parameter level change to a resource.
+ */
+export interface ParameterChange<T extends StringIndexedObject> {
+  /**
+   * The name of the parameter
+   */
+  name: keyof T & string;
+
+  /**
+   * The operation to be performed on the parameter.
+   */
+  operation: ParameterOperation;
+
+  /**
+   * The previous value of the resource (the current value on the system)
+   */
+  previousValue: any | null;
+
+  /**
+   * The new value of the resource (the desired value)
+   */
+  newValue: any | null;
+}
+
+// Change set will coerce undefined values to null because undefined is not valid JSON
+export class ChangeSet<T extends StringIndexedObject> {
+  operation: ResourceOperation
+  parameterChanges: Array<ParameterChange<T>>
+
+  constructor(
+    operation: ResourceOperation,
+    parameterChanges: Array<ParameterChange<T>>
+  ) {
+    this.operation = operation;
+    this.parameterChanges = parameterChanges;
+  }
+
+  get desiredParameters(): T {
+    return this.parameterChanges
+      .reduce((obj, pc) => ({
+        ...obj,
+        [pc.name]: pc.newValue,
+      }), {}) as T;
+  }
+
+  get currentParameters(): T {
+    return this.parameterChanges
+      .reduce((obj, pc) => ({
+        ...obj,
+        [pc.name]: pc.previousValue,
+      }), {}) as T;
+  }
+
+  static empty<T extends StringIndexedObject>(): ChangeSet<T> {
+    return new ChangeSet<T>(ResourceOperation.NOOP, []);
+  }
+
+  static create<T extends StringIndexedObject>(desired: Partial<T>): ChangeSet<T> {
+    const parameterChanges = Object.entries(desired)
+      .map(([k, v]) => ({
+        name: k,
+        operation: ParameterOperation.ADD,
+        previousValue: null,
+        newValue: v ?? null,
+      }))
+
+    return new ChangeSet(ResourceOperation.CREATE, parameterChanges);
+  }
+
+  static destroy<T extends StringIndexedObject>(current: Partial<T>): ChangeSet<T> {
+    const parameterChanges = Object.entries(current)
+      .map(([k, v]) => ({
+        name: k,
+        operation: ParameterOperation.REMOVE,
+        previousValue: v ?? null,
+        newValue: null,
+      }))
+
+    return new ChangeSet(ResourceOperation.DESTROY, parameterChanges);
+  }
+
+  static calculateModification<T extends StringIndexedObject>(
+    desired: Partial<T>,
+    current: Partial<T>,
+    parameterSettings: Partial<Record<keyof T, ParameterSetting>> = {},
+  ): ChangeSet<T> {
+    const pc = ChangeSet.calculateParameterChanges(desired, current, parameterSettings);
+
+    const statefulParameterKeys = new Set(
+      Object.entries(parameterSettings)
+        .filter(([, v]) => v?.type === 'stateful')
+        .map(([k]) => k)
+    )
+
+    const resourceOperation = pc
+      .filter((change) => change.operation !== ParameterOperation.NOOP)
+      .reduce((operation: ResourceOperation, curr: ParameterChange<T>) => {
+        let newOperation: ResourceOperation;
+        if (statefulParameterKeys.has(curr.name)) {
+          newOperation = ResourceOperation.MODIFY // All stateful parameters are modify only
+        } else if (parameterSettings[curr.name]?.canModify) {
+          newOperation = ResourceOperation.MODIFY
+        } else {
+          newOperation = ResourceOperation.RECREATE; // Default to Re-create. Should handle the majority of use cases
+        }
+
+        return ChangeSet.combineResourceOperations(operation, newOperation);
+      }, ResourceOperation.NOOP);
+
+    return new ChangeSet<T>(resourceOperation, pc);
+  }
+
+  private static calculateParameterChanges<T extends StringIndexedObject>(
+    desiredParameters: Partial<T>,
+    currentParameters: Partial<T>,
+    parameterOptions?: Partial<Record<keyof T, ParameterSetting>>,
+  ): ParameterChange<T>[] {
+    const parameterChangeSet = new Array<ParameterChange<T>>();
+
+    // Filter out null and undefined values or else the diff below will not work
+    const desired = Object.fromEntries(
+      Object.entries(desiredParameters).filter(([, v]) => v !== null && v !== undefined)
+    ) as Partial<T>
+
+    const current = Object.fromEntries(
+      Object.entries(currentParameters).filter(([, v]) => v !== null && v !== undefined)
+    ) as Partial<T>
+
+    for (const [k, v] of Object.entries(current)) {
+      if (desired?.[k] === null || desired?.[k] === undefined) {
+        parameterChangeSet.push({
+          name: k,
+          previousValue: v ?? null,
+          newValue: null,
+          operation: ParameterOperation.REMOVE,
+        })
+
+        delete current[k];
+        continue;
+      }
+
+      if (!ChangeSet.isSame(desired[k], current[k], parameterOptions?.[k])) {
+        parameterChangeSet.push({
+          name: k,
+          previousValue: v ?? null,
+          newValue: desired[k] ?? null,
+          operation: ParameterOperation.MODIFY,
+        })
+
+        delete current[k];
+        delete desired[k];
+        continue;
+      }
+
+      parameterChangeSet.push({
+        name: k,
+        previousValue: v ?? null,
+        newValue: desired[k] ?? null,
+        operation: ParameterOperation.NOOP,
+      })
+
+      delete current[k];
+      delete desired[k];
+    }
+
+    if (Object.keys(current).length > 0) {
+      throw new Error('Diff algorithm error');
+    }
+
+    for (const [k, v] of Object.entries(desired)) {
+      parameterChangeSet.push({
+        name: k,
+        previousValue: null,
+        newValue: v ?? null,
+        operation: ParameterOperation.ADD,
+      })
+    }
+
+    return parameterChangeSet;
+  }
+
+  private static combineResourceOperations(prev: ResourceOperation, next: ResourceOperation) {
+    const orderOfOperations = [
+      ResourceOperation.NOOP,
+      ResourceOperation.MODIFY,
+      ResourceOperation.RECREATE,
+      ResourceOperation.CREATE,
+      ResourceOperation.DESTROY,
+    ]
+
+    const indexPrev = orderOfOperations.indexOf(prev);
+    const indexNext = orderOfOperations.indexOf(next);
+
+    return orderOfOperations[Math.max(indexPrev, indexNext)];
+  }
+
+  private static isSame(
+    desired: unknown,
+    current: unknown,
+    setting?: ParameterSetting,
+  ): boolean {
+    switch (setting?.type) {
+      case 'stateful': {
+        const statefulSetting = (setting as StatefulParameterSetting).definition.getSettings()
+
+        return ChangeSet.isSame(desired, current, statefulSetting as ParameterSetting);
+      }
+
+      case 'array': {
+        const arrayParameter = setting as ArrayParameterSetting;
+        return areArraysEqual(arrayParameter, desired, current)
+      }
+
+      default: {
+        return (setting?.isEqual ?? ((a, b) => a === b))(desired, current)
+      }
+    }
+  }
+}