codify-plugin-lib 1.0.0

package/src/entities/change-set.ts

@@ -0,0 +1,117 @@
+import { ParameterOperation, ResourceConfig, ResourceOperation } from 'codify-schemas';
+
+export interface ParameterChange {
+  name: string;
+  operation: ParameterOperation;
+  previousValue: string | null;
+  newValue: string | null;
+}
+
+export class ChangeSet {
+  operation: ResourceOperation
+  parameterChanges: Array<ParameterChange>
+
+  constructor(
+    operation: ResourceOperation,
+    parameterChanges: Array<ParameterChange>
+  ) {
+    this.operation = operation;
+    this.parameterChanges = parameterChanges;
+  }
+
+  static createForNullCurrentConfig(desiredConfig: ResourceConfig) {
+    const parameterChangeSet = Object.entries(desiredConfig)
+      .filter(([k,]) => k !== 'type' && k !== 'name')
+      .map(([k, v]) => {
+        return {
+          name: k,
+          operation: ParameterOperation.ADD,
+          previousValue: null,
+          newValue: v,
+        }
+      })
+
+    return new ChangeSet(ResourceOperation.CREATE, parameterChangeSet);
+  }
+
+  static calculateParameterChangeSet(prev: ResourceConfig, next: ResourceConfig): ParameterChange[] {
+    const parameterChangeSet = new Array<ParameterChange>();
+
+    const filteredPrev = Object.fromEntries(
+      Object.entries(prev)
+        .filter(([k,]) => k !== 'type' && k !== 'name')
+    );
+
+    const filteredNext = Object.fromEntries(
+      Object.entries(next)
+        .filter(([k,]) => k !== 'type' && k !== 'name')
+    );
+
+    for (const [k, v] of Object.entries(filteredPrev)) {
+      if (!filteredNext[k]) {
+        parameterChangeSet.push({
+          name: k,
+          previousValue: v,
+          newValue: null,
+          operation: ParameterOperation.REMOVE,
+        })
+
+        delete filteredPrev[k];
+        continue;
+      }
+
+      if (filteredPrev[k] !== filteredNext[k]) {
+        parameterChangeSet.push({
+          name: k,
+          previousValue: v,
+          newValue: filteredNext[k],
+          operation: ParameterOperation.MODIFY,
+        })
+
+        delete filteredPrev[k];
+        delete filteredNext[k];
+        continue;
+      }
+
+      parameterChangeSet.push({
+        name: k,
+        previousValue: v,
+        newValue: filteredNext[k],
+        operation: ParameterOperation.NOOP,
+      })
+
+      delete filteredPrev[k];
+      delete filteredNext[k];
+    }
+
+    if (Object.keys(filteredPrev).length !== 0) {
+      throw Error('Diff algorithm error');
+    }
+
+    for (const [k, v] of Object.entries(filteredNext)) {
+      parameterChangeSet.push({
+        name: k,
+        previousValue: null,
+        newValue: v,
+        operation: ParameterOperation.ADD,
+      })
+    }
+
+    return parameterChangeSet;
+  }
+
+  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)];
+  }
+}

package/src/entities/plan.ts

@@ -0,0 +1,40 @@
+import { ChangeSet } from './change-set';
+import {
+  PlanResponseData,
+  ResourceConfig,
+} from 'codify-schemas';
+import { randomUUID } from 'crypto';
+
+export class Plan {
+  id: string;
+  changeSet: ChangeSet;
+  resourceConfig: ResourceConfig
+
+  constructor(id: string, changeSet: ChangeSet, resourceConfig: ResourceConfig) {
+    this.id = id;
+    this.changeSet = changeSet;
+    this.resourceConfig = resourceConfig;
+  }
+
+  static create(changeSet: ChangeSet, resourceConfig: ResourceConfig) {
+    return new Plan(
+      randomUUID(),
+      changeSet,
+      resourceConfig,
+    )
+  }
+
+  getResourceType(): string {
+    return this.resourceConfig.type;
+  }
+
+  toResponse(): PlanResponseData {
+    return {
+      planId: this.id,
+      operation: this.changeSet.operation,
+      resourceName: this.resourceConfig.name,
+      resourceType: this.resourceConfig.type,
+      parameters: this.changeSet.parameterChanges,
+    }
+  }
+}

package/src/entities/plugin.ts

@@ -0,0 +1,53 @@
+import { Resource } from './resource';
+import {
+  ApplyRequestData,
+  PlanRequestData,
+  PlanResponseData,
+  ResourceConfig,
+  ValidateRequestData,
+  ValidateResponseData
+} from 'codify-schemas';
+
+export class Plugin {
+  planStorage: Map<string, any>;
+
+  constructor(
+    public resources: Map<string, Resource<ResourceConfig>>
+  ) {
+    this.planStorage = new Map();
+  }
+
+  async onInitialize(): Promise<void> {
+
+  }
+
+  async validate(data: ValidateRequestData): Promise<ValidateResponseData> {
+    for (const config of data.configs) {
+      if (!this.resources.has(config.type)) {
+        throw new Error(`Resource type not found: ${config.type}`);
+      }
+
+      await this.resources.get(config.type)!.validate(config);
+    }
+
+    await this.crossValidateResources(data.configs);
+    return null;
+  }
+
+  async plan(data: PlanRequestData): Promise<PlanResponseData> {
+    if (!this.resources.has(data.type)) {
+      throw new Error(`Resource type not found: ${data.type}`);
+    }
+
+    const plan = await this.resources.get(data.type)!.plan(data);
+    this.planStorage.set(plan.id, plan);
+
+    return plan.toResponse();
+  }
+
+  async apply(data: ApplyRequestData): Promise<void> {
+  }
+
+  protected async crossValidateResources(configs: ResourceConfig[]): Promise<void> {}
+
+}

package/src/entities/resource.test.ts

@@ -0,0 +1,146 @@
+import { describe } from 'mocha';
+import { Resource } from './resource';
+import { ResourceConfig, ResourceOperation } from 'codify-schemas';
+import { ChangeSet, ParameterChange } from './change-set';
+import { spy } from 'sinon';
+import { expect } from 'chai';
+
+class TestResource extends Resource<TestConfig> {
+  applyCreate(changeSet: ChangeSet): Promise<void> {
+    return Promise.resolve(undefined);
+  }
+
+  applyDestroy(changeSet: ChangeSet): Promise<void> {
+    return Promise.resolve(undefined);
+  }
+
+  applyModify(changeSet: ChangeSet): Promise<void> {
+    return Promise.resolve(undefined);
+  }
+
+  applyRecreate(changeSet: ChangeSet): Promise<void> {
+    return Promise.resolve(undefined);
+  }
+
+  calculateOperation(change: ParameterChange): ResourceOperation.RECREATE | ResourceOperation.MODIFY {
+    return ResourceOperation.MODIFY;
+  }
+
+  async getCurrentConfig(): Promise<TestConfig> {
+    return Promise.resolve(undefined);
+  }
+
+  validate(config: ResourceConfig): Promise<boolean> {
+    return Promise.resolve(false);
+  }
+
+  getTypeId(): string {
+    return '';
+  }
+}
+
+interface TestConfig extends ResourceConfig {
+  propA: string;
+  propB: number;
+  propC?: string;
+}
+
+describe('Resource tests', () => {
+  it('plans correctly', async () => {
+    const resource = new class extends TestResource {
+      calculateOperation(change: ParameterChange): ResourceOperation.RECREATE | ResourceOperation.MODIFY {
+        return ResourceOperation.MODIFY;
+      }
+
+      async getCurrentConfig(): Promise<TestConfig> {
+        return {
+          type: 'type',
+          name: 'name',
+          propA: "propABefore",
+          propB: 10,
+        };
+      }
+    }
+
+    const resourceSpy = spy(resource);
+    const result = await resourceSpy.plan({
+      type: 'type',
+      name: 'name',
+      propA: 'propA',
+      propB: 10,
+    })
+
+    expect(result.resourceConfig).to.deep.eq({
+      type: 'type',
+      name: 'name',
+      propA: 'propA',
+      propB: 10,
+    });
+    expect(result.changeSet.operation).to.eq(ResourceOperation.MODIFY);
+    expect(result.changeSet.parameterChanges[0]).to.deep.eq({
+      name: 'propA',
+      previousValue: 'propABefore',
+      newValue: 'propA',
+      operation: 'modify'
+    })
+    expect(result.changeSet.parameterChanges[1]).to.deep.eq(  {
+      name: 'propB',
+      previousValue: 10,
+      newValue: 10,
+      operation: 'noop'
+    })
+  })
+
+  it('calls calculateOperation for only modifications and recreates', async () => {
+    const resource = new class extends TestResource {
+      calculateOperation(change: ParameterChange): ResourceOperation.RECREATE | ResourceOperation.MODIFY {
+        return ResourceOperation.MODIFY;
+      }
+
+      async getCurrentConfig(): Promise<TestConfig> {
+        return {
+          type: 'type',
+          name: 'name',
+          propA: "propABefore",
+          propB: 10,
+          propC: 'somethingBefore'
+        };
+      }
+    }
+
+    const resourceSpy = spy(resource);
+    await resourceSpy.plan({
+      type: 'type',
+      name: 'name',
+      propA: 'propA',
+      propB: 10,
+      propC: 'somethingAfter'
+    })
+
+    expect(resourceSpy.calculateOperation.calledTwice).to.be.true;
+  })
+
+  it('creates the resource if it doesnt exist', async () => {
+    const resource = new class extends TestResource {
+      calculateOperation(change: ParameterChange): ResourceOperation.RECREATE | ResourceOperation.MODIFY {
+        return ResourceOperation.MODIFY;
+      }
+
+      async getCurrentConfig(): Promise<TestConfig> {
+        return null;
+      }
+    }
+
+    const resourceSpy = spy(resource);
+    const result = await resourceSpy.plan({
+      type: 'type',
+      name: 'name',
+      propA: 'propA',
+      propB: 10,
+      propC: 'somethingAfter'
+    })
+
+    expect(result.changeSet.operation).to.eq(ResourceOperation.CREATE);
+    expect(result.changeSet.parameterChanges.length).to.eq(3);
+  })
+})

package/src/entities/resource.ts

@@ -0,0 +1,72 @@
+import { ParameterOperation, ResourceConfig, ResourceOperation } from 'codify-schemas';
+import { ChangeSet, ParameterChange } from './change-set';
+import { Plan } from './plan';
+
+export abstract class Resource<T extends ResourceConfig> {
+
+  constructor(
+    private dependencies: Resource<any>[] = [],
+  ) {}
+
+  abstract getTypeId(): string;
+
+  async onInitialize(): Promise<void> {}
+
+  // TODO: Add state in later.
+  //  Calculate change set from current config -> state -> desired in the future
+  async plan(desiredConfig: T): Promise<Plan> {
+    await this.validate(desiredConfig);
+
+    const currentConfig = await this.getCurrentConfig();
+    if (!currentConfig) {
+      return Plan.create(ChangeSet.createForNullCurrentConfig(desiredConfig), desiredConfig);
+    }
+
+    // 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.calculateOperation(curr);
+        return ChangeSet.combineResourceOperations(operation, newOperation);
+      }, ResourceOperation.NOOP);
+
+    return Plan.create(
+      new ChangeSet(resourceOperation, parameterChangeSet),
+      desiredConfig
+    );
+  }
+
+  async apply(plan: Plan): Promise<any> {
+    if (plan.getResourceType()) {
+      throw new Error('Internal error: Plan set to wrong resource during apply');
+    }
+
+    const changeSet = plan.changeSet;
+    switch (plan.changeSet.operation) {
+      case ResourceOperation.CREATE: return this.applyCreate(changeSet);
+      case ResourceOperation.MODIFY: return this.applyModify(changeSet);
+      case ResourceOperation.RECREATE: return this.applyRecreate(changeSet);
+      case ResourceOperation.DESTROY: return this.applyDestroy(changeSet);
+    }
+  }
+
+  abstract validate(config: ResourceConfig): Promise<boolean>;
+
+  abstract getCurrentConfig(): Promise<T | null>;
+
+  abstract calculateOperation(change: ParameterChange): ResourceOperation.MODIFY | ResourceOperation.RECREATE;
+
+  abstract applyCreate(changeSet: ChangeSet): Promise<void>;
+
+  abstract applyModify(changeSet: ChangeSet): Promise<void>;
+
+  abstract applyRecreate(changeSet: ChangeSet): Promise<void>;
+
+  abstract applyDestroy(changeSet: ChangeSet): Promise<void>;
+}

package/src/index.test.ts

@@ -0,0 +1,6 @@
+import { describe } from 'mocha';
+
+describe('Library integration tests', () => {
+  it('does something', async () => {
+  })
+});

package/src/index.ts

@@ -0,0 +1,17 @@
+import { Plugin } from './entities/plugin';
+import { MessageHandler } from './messages/handlers';
+
+export * from './entities/resource'
+export * from './entities/plugin'
+export * from './entities/change-set'
+export * from './entities/plan'
+export * from './utils/test-utils'
+export * from './utils/utils'
+
+
+export async function runPlugin(plugin: Plugin) {
+  await plugin.onInitialize();
+
+  const messageHandler = new MessageHandler(plugin);
+  process.on('message', (message) => messageHandler.onMessage(message))
+}

package/src/messages/handlers.test.ts

@@ -0,0 +1,124 @@
+import { MessageHandler } from './handlers';
+import { createStubInstance } from 'sinon';
+import { Plugin } from '../entities/plugin';
+import { expect } from 'chai';
+
+describe('Message handler tests', () => {
+  it('handles plan requests', async () => {
+    const plugin = createStubInstance(Plugin);
+    const handler = new MessageHandler(plugin);
+
+    // Message handler also validates the response. That part does not need to be tested
+    try {
+      await handler.onMessage({
+        cmd: 'plan',
+        data: {
+          type: 'resourceType',
+          name: 'name',
+          prop1: 'A',
+          prop2: 'B',
+        }
+      })
+    } catch (e) {}
+
+    expect(plugin.plan.calledOnce).to.be.true;
+  })
+
+  it('rejects bad plan requests', async () => {
+    const plugin = createStubInstance(Plugin);
+    const handler = new MessageHandler(plugin);
+
+    // Message handler also validates the response. That part does not need to be tested
+    try {
+      await handler.onMessage({
+        cmd: 'plan',
+        data: {
+          type: 'resourceType',
+          name: '1name',
+          prop1: 'A',
+          prop2: 'B',
+        }
+      })
+    } catch (e) {}
+
+    expect(plugin.plan.called).to.be.false;
+  })
+
+  it('handles apply requests', async () => {
+    const plugin = createStubInstance(Plugin);
+    const handler = new MessageHandler(plugin);
+
+    // Message handler also validates the response. That part does not need to be tested
+    try {
+      await handler.onMessage({
+        cmd: 'apply',
+        data: {
+          planId: '1803fff7-a378-4006-95bb-7c97cba02c82'
+        }
+      })
+    } catch (e) {}
+
+    expect(plugin.apply.calledOnce).to.be.true;
+  })
+
+  it('rejects bad plan requests', async () => {
+    const plugin = createStubInstance(Plugin);
+    const handler = new MessageHandler(plugin);
+
+    // Message handler also validates the response. That part does not need to be tested
+    try {
+      await handler.onMessage({
+        cmd: 'apply',
+        data: {}
+      })
+    } catch (e) {}
+
+    expect(plugin.apply.called).to.be.false;
+  })
+
+  it('handles validate requests', async () => {
+    const plugin = createStubInstance(Plugin);
+    const handler = new MessageHandler(plugin);
+
+    // Message handler also validates the response. That part does not need to be tested
+    try {
+      await handler.onMessage({
+        cmd: 'validate',
+        data: {
+          configs: [
+            {
+              type: 'type1',
+              name: 'name1'
+            },
+            {
+              type: 'type2',
+              name: 'name2'
+            },
+            {
+              type: 'type2',
+              name: 'name3'
+            }
+          ]
+        }
+      })
+    } catch (e) {}
+
+    expect(plugin.validate.calledOnce).to.be.true;
+  })
+
+  it('rejects bad validate requests', async () => {
+    const plugin = createStubInstance(Plugin);
+    const handler = new MessageHandler(plugin);
+
+    // Message handler also validates the response. That part does not need to be tested
+    try {
+      await handler.onMessage({
+        cmd: 'validate',
+        data: {}
+      })
+    } catch (e) {}
+
+    expect(plugin.apply.called).to.be.false;
+  })
+
+});

package/src/messages/handlers.ts

@@ -0,0 +1,100 @@
+import Ajv2020, { SchemaObject, ValidateFunction } from 'ajv/dist/2020';
+import { Plugin } from '../entities/plugin';
+import addFormats from 'ajv-formats';
+import {
+  IpcMessage,
+  IpcMessageSchema,
+  ResourceSchema,
+  ValidateRequestDataSchema,
+  ValidateResponseDataSchema,
+  MessageStatus,
+  PlanRequestDataSchema,
+  PlanResponseDataSchema,
+  ApplyRequestDataSchema
+} from 'codify-schemas';
+
+const SupportedRequests: Record<string, { requestValidator: SchemaObject; responseValidator: SchemaObject; handler: (plugin: Plugin, data: any) => Promise<unknown> }> = {
+  'validate': {
+    requestValidator: ValidateRequestDataSchema,
+    responseValidator: ValidateResponseDataSchema,
+    handler: async (plugin: Plugin, data: any) => plugin.validate(data)
+  },
+  'plan': {
+    requestValidator: PlanRequestDataSchema,
+    responseValidator: PlanResponseDataSchema,
+    handler: async (plugin: Plugin, data: any) => plugin.plan(data)
+  },
+  'apply': {
+    requestValidator: ApplyRequestDataSchema,
+    responseValidator: ApplyRequestDataSchema, // Replace with response validator
+    handler: async (plugin: Plugin, data: any) => plugin.apply(data)
+  }
+}
+
+export class MessageHandler {
+  private ajv: Ajv2020;
+  private readonly plugin: Plugin;
+  private messageSchemaValidator: ValidateFunction;
+  private requestValidators: Map<string, ValidateFunction>;
+  private responseValidators: Map<string, ValidateFunction>;
+
+  constructor(plugin: Plugin) {
+    this.ajv = new Ajv2020({ strict: true });
+    addFormats(this.ajv);
+    this.ajv.addSchema(ResourceSchema);
+    this.plugin = plugin;
+
+    this.messageSchemaValidator = this.ajv.compile(IpcMessageSchema);
+    this.requestValidators = new Map(
+      Object.entries(SupportedRequests)
+        .map(([k, v]) => [k, this.ajv.compile(v.requestValidator)])
+    )
+    this.responseValidators = new Map(
+      Object.entries(SupportedRequests)
+        .map(([k, v]) => [k, this.ajv.compile(v.responseValidator)])
+    )
+  }
+
+  async onMessage(message: unknown): Promise<void> {
+    if (!this.validateMessage(message)) {
+      throw new Error(`Message is malformed: ${JSON.stringify(this.messageSchemaValidator.errors, null, 2)}`);
+    }
+
+    if (!this.requestValidators.has(message.cmd)) {
+      throw new Error(`Unsupported message: ${message.cmd}`);
+    }
+
+    const requestValidator = this.requestValidators.get(message.cmd)!;
+    if (!requestValidator(message.data)) {
+      throw new Error(`Malformed message data: ${JSON.stringify(requestValidator.errors, null, 2)}`)
+    }
+
+    let result: unknown;
+    try {
+      result = await SupportedRequests[message.cmd].handler(this.plugin, message.data);
+    } catch(e: any) {
+      process.send!({
+        cmd: message.cmd + '_Response',
+        status: MessageStatus.ERROR,
+        data: e.message,
+      })
+
+      return;
+    }
+
+    const responseValidator = this.responseValidators.get(message.cmd);
+    if (responseValidator && !responseValidator(result)) {
+      throw new Error(`Malformed response data: ${JSON.stringify(responseValidator.errors, null, 2)}`)
+    }
+
+    process.send!({
+      cmd: message.cmd + '_Response',
+      status: MessageStatus.SUCCESS,
+      data: result,
+    })
+  }
+
+  private validateMessage(message: unknown): message is IpcMessage {
+    return this.messageSchemaValidator(message);
+  }
+}