codify-plugin-lib 1.0.75 → 1.0.77

package/dist/plan/plan.js

@@ -0,0 +1,228 @@
+import { ParameterOperation, ResourceOperation, } from 'codify-schemas';
+import { v4 as uuidV4 } from 'uuid';
+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 {
+    id;
+    changeSet;
+    coreParameters;
+    constructor(id, changeSet, resourceMetadata) {
+        this.id = id;
+        this.changeSet = changeSet;
+        this.coreParameters = resourceMetadata;
+    }
+    /**
+     * The desired config that a plan will achieve after executing all the actions.
+     */
+    get desiredConfig() {
+        if (this.changeSet.operation === ResourceOperation.DESTROY) {
+            return null;
+        }
+        return {
+            ...this.coreParameters,
+            ...this.changeSet.desiredParameters,
+        };
+    }
+    /**
+     * The current config that the plan is changing.
+     */
+    get currentConfig() {
+        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
+     */
+    static matchCurrentParameters(params) {
+        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() {
+        return this.coreParameters.type;
+    }
+    static calculate(params) {
+        const { desiredParameters, currentParametersArray, stateParameters, coreParameters, settings, statefulMode } = params;
+        const currentParameters = Plan.matchCurrentParameters({
+            desiredParameters,
+            currentParametersArray,
+            stateParameters,
+            settings,
+            statefulMode
+        });
+        const filteredCurrentParameters = Plan.filterCurrentParams({
+            desiredParameters,
+            currentParameters,
+            stateParameters,
+            settings,
+            statefulMode
+        });
+        // Empty
+        if (!filteredCurrentParameters && !desiredParameters) {
+            return new Plan(uuidV4(), ChangeSet.empty(), 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.
+     */
+    static filterCurrentParams(params) {
+        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() {
+            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)));
+            }
+            // Stateless mode
+            const keys = new Set(Object.keys(desired ?? {}));
+            return Object.fromEntries(Object.entries(current)
+                .filter(([k]) => keys.has(k)));
+        }
+        function isArrayStatefulParameter(k, v) {
+            return settings.parameterSettings?.[k]?.type === 'stateful'
+                && settings.parameterSettings[k].definition.getSettings().type === 'array'
+                && Array.isArray(v);
+        }
+        function filterArrayStatefulParameter(k, v) {
+            const desiredArray = desired[k];
+            const matcher = settings.parameterSettings[k]
+                .definition
+                .getSettings()
+                .isElementEqual;
+            return v.filter((cv) => desiredArray.find((dv) => (matcher ?? ((a, b) => 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(data, defaultValues) {
+        if (!data) {
+            throw new Error('Data is empty');
+        }
+        addDefaultValues();
+        return new Plan(uuidV4(), new ChangeSet(data.operation, data.parameters), {
+            type: data.resourceType,
+            name: data.resourceName,
+        });
+        function addDefaultValues() {
+            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() {
+        return {
+            planId: this.id,
+            operation: this.changeSet.operation,
+            resourceName: this.coreParameters.name,
+            resourceType: this.coreParameters.type,
+            parameters: this.changeSet.parameterChanges,
+        };
+    }
+}

package/dist/plugin/plugin.d.ts

@@ -0,0 +1,17 @@
+import { ApplyRequestData, InitializeResponseData, PlanRequestData, PlanResponseData, ResourceConfig, ValidateRequestData, ValidateResponseData } from 'codify-schemas';
+import { Plan } from '../plan/plan.js';
+import { Resource } from '../resource/resource.js';
+import { ResourceController } from '../resource/resource-controller.js';
+export declare class Plugin {
+    name: string;
+    resourceControllers: Map<string, ResourceController<ResourceConfig>>;
+    planStorage: Map<string, Plan<any>>;
+    constructor(name: string, resourceControllers: Map<string, ResourceController<ResourceConfig>>);
+    static create(name: string, resources: Resource<any>[]): Plugin;
+    initialize(): Promise<InitializeResponseData>;
+    validate(data: ValidateRequestData): Promise<ValidateResponseData>;
+    plan(data: PlanRequestData): Promise<PlanResponseData>;
+    apply(data: ApplyRequestData): Promise<void>;
+    private resolvePlan;
+    protected crossValidateResources(configs: ResourceConfig[]): Promise<void>;
+}

package/dist/plugin/plugin.js

@@ -0,0 +1,83 @@
+import { Plan } from '../plan/plan.js';
+import { ResourceController } from '../resource/resource-controller.js';
+import { splitUserConfig } from '../utils/utils.js';
+export class Plugin {
+    name;
+    resourceControllers;
+    planStorage;
+    constructor(name, resourceControllers) {
+        this.name = name;
+        this.resourceControllers = resourceControllers;
+        this.planStorage = new Map();
+    }
+    static create(name, resources) {
+        const controllers = resources
+            .map((resource) => new ResourceController(resource));
+        const controllersMap = new Map(controllers.map((r) => [r.typeId, r]));
+        return new Plugin(name, controllersMap);
+    }
+    async initialize() {
+        for (const controller of this.resourceControllers.values()) {
+            await controller.initialize();
+        }
+        return {
+            resourceDefinitions: [...this.resourceControllers.values()]
+                .map((r) => ({
+                dependencies: r.dependencies,
+                type: r.typeId,
+            }))
+        };
+    }
+    async validate(data) {
+        const validationResults = [];
+        for (const config of data.configs) {
+            if (!this.resourceControllers.has(config.type)) {
+                throw new Error(`Resource type not found: ${config.type}`);
+            }
+            const { parameters, coreParameters } = splitUserConfig(config);
+            const validation = await this.resourceControllers
+                .get(config.type)
+                .validate(parameters, coreParameters);
+            validationResults.push(validation);
+        }
+        await this.crossValidateResources(data.configs);
+        return {
+            resourceValidations: validationResults
+        };
+    }
+    async plan(data) {
+        const type = data.desired?.type ?? data.state?.type;
+        if (!type || !this.resourceControllers.has(type)) {
+            throw new Error(`Resource type not found: ${type}`);
+        }
+        const plan = await this.resourceControllers.get(type).plan(data.desired ?? null, data.state ?? null, data.isStateful);
+        this.planStorage.set(plan.id, plan);
+        return plan.toResponse();
+    }
+    async apply(data) {
+        if (!data.planId && !data.plan) {
+            throw new Error('For applies either plan or planId must be supplied');
+        }
+        const plan = this.resolvePlan(data);
+        const resource = this.resourceControllers.get(plan.getResourceType());
+        if (!resource) {
+            throw new Error('Malformed plan with resource that cannot be found');
+        }
+        await resource.apply(plan);
+    }
+    resolvePlan(data) {
+        const { plan: planRequest, planId } = data;
+        if (planId) {
+            if (!this.planStorage.has(planId)) {
+                throw new Error(`Plan with id: ${planId} was not found`);
+            }
+            return this.planStorage.get(planId);
+        }
+        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.resourceControllers.get(planRequest.resourceType);
+        return Plan.fromResponse(planRequest, resource.parsedSettings.defaultValues);
+    }
+    async crossValidateResources(configs) { }
+}

package/dist/resource/config-parser.d.ts

@@ -0,0 +1,14 @@
+import { ResourceConfig, StringIndexedObject } from 'codify-schemas';
+import { StatefulParameter } from './stateful-parameter.js';
+export declare class ConfigParser<T extends StringIndexedObject> {
+    private readonly desiredConfig;
+    private readonly stateConfig;
+    private statefulParametersMap;
+    constructor(desiredConfig: Partial<T> & ResourceConfig | null, stateConfig: Partial<T> & ResourceConfig | null, statefulParameters: Map<keyof T, StatefulParameter<T, T[keyof T]>>);
+    get coreParameters(): ResourceConfig;
+    get desiredParameters(): Partial<T> | null;
+    get stateParameters(): Partial<T> | null;
+    get allParameters(): Partial<T>;
+    get allNonStatefulParameters(): Partial<T>;
+    get allStatefulParameters(): Partial<T>;
+}

package/dist/resource/config-parser.js

@@ -0,0 +1,48 @@
+import { splitUserConfig } from '../utils/utils.js';
+export class ConfigParser {
+    desiredConfig;
+    stateConfig;
+    statefulParametersMap;
+    constructor(desiredConfig, stateConfig, statefulParameters) {
+        this.desiredConfig = desiredConfig;
+        this.stateConfig = stateConfig;
+        this.statefulParametersMap = statefulParameters;
+    }
+    get coreParameters() {
+        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() {
+        if (!this.desiredConfig) {
+            return null;
+        }
+        const { parameters } = splitUserConfig(this.desiredConfig);
+        return parameters;
+    }
+    get stateParameters() {
+        if (!this.stateConfig) {
+            return null;
+        }
+        const { parameters } = splitUserConfig(this.stateConfig);
+        return parameters;
+    }
+    get allParameters() {
+        return { ...this.desiredParameters, ...this.stateParameters };
+    }
+    get allNonStatefulParameters() {
+        const { allParameters, statefulParametersMap, } = this;
+        return Object.fromEntries(Object.entries(allParameters).filter(([key]) => !statefulParametersMap.has(key)));
+    }
+    get allStatefulParameters() {
+        const { allParameters, statefulParametersMap } = this;
+        return Object.fromEntries(Object.entries(allParameters).filter(([key]) => statefulParametersMap.has(key)));
+    }
+}

package/dist/resource/parsed-resource-settings.d.ts

@@ -0,0 +1,26 @@
+import { StringIndexedObject } from 'codify-schemas';
+import { ParameterSetting, ResourceSettings } from './resource-settings.js';
+import { StatefulParameter as StatefulParameterImpl } from './stateful-parameter.js';
+export declare class ParsedResourceSettings<T extends StringIndexedObject> implements ResourceSettings<T> {
+    private cache;
+    id: string;
+    schema?: unknown;
+    allowMultiple?: {
+        matcher: (desired: Partial<T>, current: Partial<T>[]) => Partial<T>;
+    } | undefined;
+    removeStatefulParametersBeforeDestroy?: boolean | undefined;
+    dependencies?: string[] | undefined;
+    inputTransformation?: ((desired: Partial<T>) => unknown) | undefined;
+    private settings;
+    constructor(settings: ResourceSettings<T>);
+    get typeId(): string;
+    get statefulParameters(): Map<keyof T, StatefulParameterImpl<T, T[keyof T]>>;
+    get parameterSettings(): Record<keyof T, ParameterSetting>;
+    get defaultValues(): Partial<Record<keyof T, unknown>>;
+    get inputTransformations(): Partial<Record<keyof T, (a: unknown) => unknown>>;
+    get statefulParameterOrder(): Map<keyof T, number>;
+    private validateSettings;
+    private validateParameterEqualsFn;
+    private resolveEqualsFn;
+    private getFromCacheOrCreate;
+}

package/dist/resource/parsed-resource-settings.js

@@ -0,0 +1,126 @@
+import { areArraysEqual } from '../utils/utils.js';
+import { ParameterEqualsDefaults } from './resource-settings.js';
+export class ParsedResourceSettings {
+    cache = new Map();
+    id;
+    schema;
+    allowMultiple;
+    removeStatefulParametersBeforeDestroy;
+    dependencies;
+    inputTransformation;
+    settings;
+    constructor(settings) {
+        this.settings = settings;
+        this.id = settings.id;
+        this.schema = settings.schema;
+        this.allowMultiple = settings.allowMultiple;
+        this.removeStatefulParametersBeforeDestroy = settings.removeStatefulParametersBeforeDestroy;
+        this.dependencies = settings.dependencies;
+        this.inputTransformation = settings.inputTransformation;
+        this.validateSettings();
+    }
+    get typeId() {
+        return this.id;
+    }
+    get statefulParameters() {
+        return this.getFromCacheOrCreate('statefulParameters', () => {
+            const statefulParameters = Object.entries(this.settings.parameterSettings ?? {})
+                .filter(([, p]) => p?.type === 'stateful')
+                .map(([k, v]) => [k, v.definition]);
+            return new Map(statefulParameters);
+        });
+    }
+    get parameterSettings() {
+        return this.getFromCacheOrCreate('parameterSetting', () => {
+            const settings = Object.entries(this.settings.parameterSettings ?? {})
+                .map(([k, v]) => [k, v])
+                .map(([k, v]) => {
+                v.isEqual = this.resolveEqualsFn(v, k);
+                return [k, v];
+            });
+            return Object.fromEntries(settings);
+        });
+    }
+    get defaultValues() {
+        return this.getFromCacheOrCreate('defaultValues', () => {
+            if (!this.settings.parameterSettings) {
+                return {};
+            }
+            const defaultValues = Object.fromEntries(Object.entries(this.settings.parameterSettings)
+                .filter(([, v]) => v.default !== undefined)
+                .map(([k, v]) => [k, v.default]));
+            const statefulParameterDefaultValues = Object.fromEntries(Object.entries(this.settings.parameterSettings)
+                .filter(([, v]) => v?.type === 'stateful')
+                .filter(([, v]) => v.definition.getSettings().default !== undefined)
+                .map(([k, v]) => [k, v.definition.getSettings().default]));
+            return { ...defaultValues, ...statefulParameterDefaultValues };
+        });
+    }
+    get inputTransformations() {
+        return this.getFromCacheOrCreate('inputTransformations', () => {
+            if (!this.settings.parameterSettings) {
+                return {};
+            }
+            return Object.fromEntries(Object.entries(this.settings.parameterSettings)
+                .filter(([, v]) => v.inputTransformation !== undefined)
+                .map(([k, v]) => [k, v.inputTransformation]));
+        });
+    }
+    get statefulParameterOrder() {
+        return this.getFromCacheOrCreate('stateParameterOrder', () => {
+            const entries = Object.entries(this.settings.parameterSettings ?? {})
+                .filter(([, v]) => v?.type === 'stateful')
+                .map(([k, v]) => [k, v]);
+            const orderedEntries = entries.filter(([, v]) => v.order !== undefined);
+            const unorderedEntries = entries.filter(([, v]) => v.order === undefined);
+            orderedEntries.sort((a, b) => a[1].order - b[1].order);
+            const resultArray = [
+                ...orderedEntries.map(([k]) => k),
+                ...unorderedEntries.map(([k]) => k)
+            ];
+            return new Map(resultArray.map((key, idx) => [key, idx]));
+        });
+    }
+    validateSettings() {
+        // validate parameter settings
+        if (this.settings.parameterSettings) {
+            for (const [k, v] of Object.entries(this.settings.parameterSettings)) {
+                if (!v) {
+                    throw new Error(`Resource: ${this.id}. Parameter setting ${k} was left undefined`);
+                }
+                this.validateParameterEqualsFn(v, k);
+            }
+        }
+        if (this.allowMultiple
+            && Object.values(this.parameterSettings).some((v) => v.type === 'stateful')) {
+            throw new Error(`Resource: ${this.id}. Stateful parameters are not allowed if multiples of a resource exist`);
+        }
+    }
+    validateParameterEqualsFn(parameter, key) {
+        if (parameter.type === 'stateful') {
+            const nestedSettings = parameter.definition.getSettings();
+            if (nestedSettings.type === 'stateful') {
+                throw new Error(`Nested stateful parameters are not allowed for ${key}`);
+            }
+            this.validateParameterEqualsFn(nestedSettings, key);
+        }
+        // The rest of the types have defaults set already
+    }
+    resolveEqualsFn(parameter, key) {
+        if (parameter.type === 'array') {
+            return parameter.isEqual ?? areArraysEqual.bind(areArraysEqual, parameter);
+        }
+        if (parameter.type === 'stateful') {
+            return this.resolveEqualsFn(parameter.definition.getSettings(), key);
+        }
+        return parameter.isEqual ?? ParameterEqualsDefaults[parameter.type] ?? (((a, b) => a === b));
+    }
+    getFromCacheOrCreate(key, create) {
+        if (this.cache.has(key)) {
+            return this.cache.get(key);
+        }
+        const result = create();
+        this.cache.set(key, result);
+        return result;
+    }
+}

package/dist/resource/resource-controller.d.ts

@@ -0,0 +1,30 @@
+import { Ajv, ValidateFunction } from 'ajv';
+import { ResourceConfig, StringIndexedObject, ValidateResponseData } from 'codify-schemas';
+import { Plan } from '../plan/plan.js';
+import { ParsedResourceSettings } from './parsed-resource-settings.js';
+import { Resource } from './resource.js';
+import { ResourceSettings } from './resource-settings.js';
+export declare class ResourceController<T extends StringIndexedObject> {
+    readonly resource: Resource<T>;
+    readonly settings: ResourceSettings<T>;
+    readonly parsedSettings: ParsedResourceSettings<T>;
+    readonly typeId: string;
+    readonly dependencies: string[];
+    protected ajv?: Ajv;
+    protected schemaValidator?: ValidateFunction;
+    constructor(resource: Resource<T>);
+    initialize(): Promise<void>;
+    validate(parameters: Partial<T>, resourceMetaData: ResourceConfig): Promise<ValidateResponseData['resourceValidations'][0]>;
+    plan(desiredConfig: Partial<T> & ResourceConfig | null, stateConfig?: Partial<T> & ResourceConfig | null, statefulMode?: boolean): Promise<Plan<T>>;
+    apply(plan: Plan<T>): Promise<void>;
+    private applyCreate;
+    private applyModify;
+    private applyDestroy;
+    private validateRefreshResults;
+    private applyTransformParameters;
+    private addDefaultValues;
+    private refreshNonStatefulParameters;
+    private refreshStatefulParameters;
+    private validatePlanInputs;
+    private getSortedStatefulParameterChanges;
+}