feat(orchestrator): form widgets templating, SchemaUpdater and retrigger (#697)

* feat(orchestrator): add templating and request composition tooling

Signed-off-by: Marek Libra <marek.libra@gmail.com>

* evaluateTemplate

* yarn.lock

* set backstage-plugin-orchestrator-form-widgets pckg to public

* Introduce useTemplateUnitEvaluator()

* API reports

---------

Signed-off-by: Marek Libra <marek.libra@gmail.com>

Author: mareklibra

workspaces/orchestrator/plugins/README.md

@@ -2,7 +2,6 @@
   "name": "@red-hat-developer-hub/backstage-plugin-orchestrator-form-widgets",
   "version": "0.1.0",
   "license": "Apache-2.0",
-  "private": true,
   "main": "src/index.ts",
   "types": "src/index.ts",
   "publishConfig": {
@@ -62,6 +61,7 @@
     "@red-hat-developer-hub/backstage-plugin-orchestrator-form-api": "workspace:^",
     "@rjsf/utils": "^5.21.2",
     "json-schema": "^0.4.0",
+    "lodash": "^4.17.21",
     "react-use": "^17.2.4"
   },
   "peerDependencies": {

workspaces/orchestrator/plugins/orchestrator-form-widgets/package.json

@@ -13,7 +13,7 @@ export const orchestratorFormWidgetsPlugin: BackstagePlugin<    {}, {}, {}>;
 
 // Warnings were encountered during analysis:
 //
-// src/plugin.d.ts:6:22 - (ae-undocumented) Missing documentation for "orchestratorFormWidgetsPlugin".
+// src/plugin.d.ts:5:22 - (ae-undocumented) Missing documentation for "orchestratorFormWidgetsPlugin".
 
 // (No @packageDocumentation comment for this package)
 

workspaces/orchestrator/plugins/orchestrator-form-widgets/report.api.md

@@ -23,6 +23,7 @@ import {
 } from '@red-hat-developer-hub/backstage-plugin-orchestrator-form-api';
 import { ErrorSchema, FormValidation } from '@rjsf/utils';
 import { JsonObject, JsonValue } from '@backstage/types';
+
 import { SchemaUpdater, ActiveTextInput } from './widgets';
 
 const sleep = (ms: number) => {
@@ -33,7 +34,7 @@ const customValidate = (
   _formData: JsonObject | undefined,
   errors: FormValidation<JsonObject>,
 ): FormValidation<JsonObject> => {
-  // Trigger field validation
+  // TODO: Trigger field validation
   // Called synchronously
   return errors;
 };
@@ -86,23 +87,19 @@ const safeSet: (errors: JsonObject, path: string, value: JsonValue) => void = (
     safeSet(safeObject, steps[1], value);
   }
 };
-export class FormWidgetsApi implements OrchestratorFormApi {
-  // private readonly configApi: ConfigApi;
-  // private readonly fetchApi: FetchApi;
 
-  // public constructor(options: { configApi: ConfigApi; fetchApi: FetchApi }) {
-  //   this.configApi = options.configApi;
-  //   this.fetchApi = options.fetchApi;
-  // }
+const widgets = {
+  SchemaUpdater,
+  ActiveTextInput,
+};
 
+export class FormWidgetsApi implements OrchestratorFormApi {
   getFormDecorator: OrchestratorFormApi['getFormDecorator'] = () => {
     return (FormComponent: React.ComponentType<FormDecoratorProps>) => {
       return () => {
         const { formData, setFormData, uiSchema } =
           useWrapperFormPropsContext();
 
-        const widgets = { SchemaUpdater, ActiveTextInput };
-
         const onChange = useCallback(
           (data: JsonObject | undefined) => {
             if (data) {
@@ -118,6 +115,8 @@ export class FormWidgetsApi implements OrchestratorFormApi {
           currentFormData: JsonObject,
         ) => {
           // Asynchronous validation on wizard step transition or submit
+
+          // TODO
           return sleep(1000 /* The sleep mimics async fetch, remove it */).then(
             () => {
               const errors: ErrorSchema<JsonObject> = {};

workspaces/orchestrator/plugins/orchestrator-form-widgets/src/FormWidgetsApi.tsx

@@ -13,19 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import {
-  configApiRef,
-  createApiFactory,
-  createPlugin,
-  fetchApiRef,
-} from '@backstage/core-plugin-api';
+import { createApiFactory, createPlugin } from '@backstage/core-plugin-api';
 import { orchestratorFormApiRef } from '@red-hat-developer-hub/backstage-plugin-orchestrator-form-api';
 import { FormWidgetsApi } from './FormWidgetsApi';
 
 export const formApiFactory = createApiFactory({
   api: orchestratorFormApiRef,
-  deps: { configApi: configApiRef, fetchApi: fetchApiRef },
-  factory(_options) {
+  deps: {},
+  factory() {
     return new FormWidgetsApi();
   },
 });

workspaces/orchestrator/plugins/orchestrator-form-widgets/src/plugin.ts

@@ -0,0 +1,78 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { evaluateTemplate, evaluateTemplateProps } from './evaluateTemplate';
+
+const unitEvaluator: evaluateTemplateProps['unitEvaluator'] = async (
+  unit,
+  _,
+) => {
+  if (!unit) {
+    throw new Error('Template unit can not be empty');
+  }
+
+  // Just a copy for testing purposes
+  return Promise.resolve(unit);
+};
+
+describe('evaluate template', () => {
+  const props = { unitEvaluator, key: 'myKey', formData: {} };
+
+  it('fails on incorrect input', async () => {
+    const cases = [
+      { input: '', throws: 'Template can be a string only, key: myKey' },
+      { input: undefined, throws: 'Template can be a string only, key: myKey' },
+      { input: '$${{}}', throws: 'Template unit can not be empty' },
+      { input: '$${{foo', throws: 'Template unit is not closed by }}' },
+    ];
+
+    await Promise.all(
+      cases.map(c =>
+        expect(
+          evaluateTemplate({ ...props, template: c.input }),
+        ).rejects.toThrow(c.throws),
+      ),
+    );
+  });
+
+  it('can parse input template to units', async () => {
+    const cases = [
+      { input: 'zz', expected: 'zz' },
+      { input: '}}', expected: '}}' },
+      { input: '${{foo}}', expected: '${{foo}}' },
+      { input: '$${{foo}}', expected: 'foo' },
+      { input: '$${{foo}} $${{bar}}', expected: 'foo bar' },
+      { input: '$${{foo}}$${{bar}}', expected: 'foobar' },
+      { input: ' $${{foo}}$${{bar}} ', expected: ' foobar ' },
+      { input: 'a$${{foo}}$${{bar}} b', expected: 'afoobar b' },
+      { input: 'a$${{foo}}$${{bar}} b$${{zz}}', expected: 'afoobar bzz' },
+    ];
+
+    await Promise.all(
+      cases.map(c =>
+        expect(evaluateTemplate({ ...props, template: c.input })).resolves.toBe(
+          c.expected,
+        ),
+      ),
+    );
+  });
+
+  it('can parse input template to units without nesting', async () => {
+    await expect(
+      evaluateTemplate({ ...props, template: 'a$${{foo}}$${{$${{xx}}}}b' }),
+    ).resolves.toBe('afoo$${{xx}}b');
+  });
+});

workspaces/orchestrator/plugins/orchestrator-form-widgets/src/utils/evaluateTemplate.test.ts

@@ -0,0 +1,61 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { JsonObject, JsonValue } from '@backstage/types';
+
+export type evaluateTemplateProps = {
+  template?: JsonValue;
+  key: string;
+  unitEvaluator: (
+    unit: string,
+    formData: JsonObject,
+  ) => Promise<JsonValue | undefined>;
+  formData: JsonObject;
+};
+
+export const evaluateTemplate = async (
+  props: evaluateTemplateProps,
+): Promise<string> => {
+  const { template, key, unitEvaluator, formData } = props;
+
+  if (!template || typeof template !== 'string') {
+    throw new Error(`Template can be a string only, key: ${key}`);
+  }
+
+  let evaluated;
+  const startIndex = template.indexOf('$${{');
+  if (startIndex < 0) {
+    evaluated = template;
+  } else {
+    evaluated = template.substring(0, startIndex);
+    const stopIndex = template.indexOf('}}');
+    if (stopIndex < 0) {
+      throw new Error(`Template unit is not closed by }}`);
+    }
+    evaluated += await unitEvaluator(
+      template.substring(startIndex + 4, stopIndex),
+      formData,
+    );
+    if (template.length > stopIndex + 2) {
+      evaluated += await evaluateTemplate({
+        ...props,
+        template: template.substring(stopIndex + 2),
+      });
+    }
+  }
+
+  return evaluated;
+};

workspaces/orchestrator/plugins/orchestrator-form-widgets/src/utils/evaluateTemplate.ts

@@ -0,0 +1,99 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { JsonObject } from '@backstage/types';
+import { evaluateTemplate, evaluateTemplateProps } from './evaluateTemplate';
+
+const ALLOWED_METHODS = ['GET', 'POST'];
+
+export const getRequestInit = async (
+  uiProps: JsonObject,
+  prefix: string,
+  unitEvaluator: evaluateTemplateProps['unitEvaluator'],
+  formData: JsonObject,
+): Promise<RequestInit> => {
+  const requestInit: RequestInit = {};
+
+  const method = uiProps[`${prefix}:method`]?.toString().toLocaleUpperCase();
+  if (method) {
+    if (!ALLOWED_METHODS.includes(method)) {
+      throw new Error(
+        `Unsupported HTTP method, use one of ${ALLOWED_METHODS.join(', ')}`,
+      );
+    }
+    requestInit.method = method;
+  }
+
+  const body = uiProps[`${prefix}:body`];
+  if (body) {
+    if (method === 'POST') {
+      if (typeof body === 'object') {
+        const bodyObject = body as JsonObject;
+        const evaluated: JsonObject = {};
+
+        const keys = Object.keys(body);
+        const values = await Promise.all(
+          keys.map(key =>
+            evaluateTemplate({
+              unitEvaluator,
+              key,
+              formData,
+              template: bodyObject[key],
+            }),
+          ),
+        );
+        keys.forEach((key, idx) => {
+          evaluated[key] = values[idx];
+        });
+
+        const bodyInit: BodyInit = JSON.stringify(evaluated);
+        requestInit.body = bodyInit;
+      } else {
+        throw new Error(`${prefix}:body must be object`);
+      }
+    } else {
+      throw new Error(`${prefix}:body can be used with POST requests only`);
+    }
+  }
+
+  const headers = uiProps[`${prefix}:headers`];
+  if (headers) {
+    if (typeof headers === 'object') {
+      const headersObject = headers as JsonObject;
+      const headersInit: HeadersInit = {};
+
+      const keys = Object.keys(headers);
+      const values = await Promise.all(
+        keys.map(key =>
+          evaluateTemplate({
+            unitEvaluator,
+            key,
+            formData,
+            template: headersObject[key],
+          }),
+        ),
+      );
+      keys.forEach((key, idx) => {
+        headersInit[key] = values[idx];
+      });
+
+      requestInit.headers = headersInit;
+    } else {
+      throw new Error('fetch:body must be object for POST requests');
+    }
+  }
+
+  return requestInit;
+};

workspaces/orchestrator/plugins/orchestrator-form-widgets/src/utils/getRequestInit.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from './getRequestInit';
+export * from './evaluateTemplate';
+export * from './useRetriggerEvaluate';
+export * from './useTemplateUnitEvaluator';