Merge pull request #460 from OpenFn/http-template

New template using HTTP utils
OpenFn · Jan 12, 2024 · 027b581 · 027b581
2 parents 427cc44 + ea525fc
commit 027b581
Show file tree

Hide file tree

Showing 9 changed files with 229 additions and 144 deletions.
diff --git a/README.md b/README.md
@@ -133,23 +133,22 @@ export function yourFunctionName(arguments) {
 ```
 
 The logic is where you will prepare your API request. Build the URL, passing in
-any arguments if needed. Next, return the fetch request, making sure you set the
-Authorization, passing in any secrets from `state.configuration`.
+any arguments if needed. Then, using a helper function in common, return the
+fetch request, making sure you set the Authorization, passing in any secrets
+from `state.configuration`.
 
 ```js
+import { get } from '@openfn/language-common/util';
+
 export function getTodaysWeather(latitude = 25.52, longitude = 13.41) {
   return state => {
     const url = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current_weather=true&hourly=temperature_2m,relativehumidity_2m,windspeed_10m`;
 
-    return (
-      fetch(url, {
-        headers: {
-          Authorization: `${state.configuration.username}:${state.configuration.password}`,
-        },
-      })
-        .then(response => response.json())
-        .then(data => ({ ...state, data }));
-    );
+    const headers = {
+      Authorization: `${state.configuration.username}:${state.configuration.password}`,
+    };
+    const result = await get(url, { headers });
+    return { ...state, data: result.body };
   };
 }
 ```
@@ -185,7 +184,7 @@ export function getTodaysWeather(latitude = 25.52, longitude = 13.41) {
 
 Import your newly defined function
 
-```
+```js
 import { functionName } from '../src/Adaptor.js';
 ```
 
@@ -194,7 +193,7 @@ to see how state should be passed to it).
 
 Make an assertion to check the result.
 
-```
+```js
 it('should xyz', async () => {
 const state = {
   configuration: {},

diff --git a/packages/common/src/util/http.js b/packages/common/src/util/http.js
@@ -4,6 +4,17 @@ import { Readable } from 'node:stream';
 
 const clients = new Map();
 
+export const makeBasicAuthHeader = (username, password) => {
+  const buff = Buffer.from(`${username}:${password}`);
+  const credentials = buff.toString('base64');
+  return { Authorization: `Basic ${credentials}` };
+};
+
+export const logResponse = response => {
+  const { method, url, statusCode, duration } = response;
+  console.log(`${method} ${url} - ${statusCode} in ${duration}ms`);
+};
+
 const getClient = (baseUrl, options) => {
   const { tls, timeout } = options;
   if (!clients.has(baseUrl)) {

diff --git a/packages/http/ast.json b/packages/http/ast.json
@@ -1,5 +1,78 @@
 {
   "operations": [
+    {
+      "name": "request",
+      "params": [
+        "method",
+        "path",
+        "params",
+        "callback"
+      ],
+      "docs": {
+        "description": "Make a HTTP request",
+        "tags": [
+          {
+            "title": "public",
+            "description": null,
+            "type": null
+          },
+          {
+            "title": "example",
+            "description": "get('/myEndpoint', {\n  query: {foo: 'bar', a: 1},\n  headers: {'content-type': 'application/json'},\n})"
+          },
+          {
+            "title": "function",
+            "description": null,
+            "name": null
+          },
+          {
+            "title": "param",
+            "description": "The HTTP method to use",
+            "type": {
+              "type": "NameExpression",
+              "name": "string"
+            },
+            "name": "method"
+          },
+          {
+            "title": "param",
+            "description": "Path to resource",
+            "type": {
+              "type": "NameExpression",
+              "name": "string"
+            },
+            "name": "path"
+          },
+          {
+            "title": "param",
+            "description": "Query, Headers and Authentication parameters",
+            "type": {
+              "type": "NameExpression",
+              "name": "RequestOptions"
+            },
+            "name": "params"
+          },
+          {
+            "title": "param",
+            "description": "(Optional) Callback function",
+            "type": {
+              "type": "NameExpression",
+              "name": "function"
+            },
+            "name": "callback"
+          },
+          {
+            "title": "returns",
+            "description": null,
+            "type": {
+              "type": "NameExpression",
+              "name": "Operation"
+            }
+          }
+        ]
+      },
+      "valid": true
+    },
     {
       "name": "get",
       "params": [

diff --git a/packages/http/src/Utils.js b/packages/http/src/Utils.js
@@ -2,13 +2,14 @@ import { composeNextState } from '@openfn/language-common';
 import {
   request as commonRequest,
   expandReferences,
+  logResponse,
+  makeBasicAuthHeader,
 } from '@openfn/language-common/util';
 
 export function addBasicAuth(configuration = {}, headers) {
   const { username, password } = configuration;
   if (username && password) {
-    const base64Encode = btoa(`${username}:${password}`);
-    headers['Authorization'] = `Basic ${base64Encode}`;
+    Object.assign(headers, makeBasicAuthHeader(username, password));
   }
 }
 
@@ -20,11 +21,6 @@ function encodeFormBody(data) {
   return form;
 }
 
-export function generateResponseLog(response) {
-  const { method, url, statusCode, duration } = response;
-  return `${method} ${url} - ${statusCode} in ${duration}ms`;
-}
-
 export function request(method, path, params, callback = s => s) {
   return state => {
     const [resolvedPath, resolvedParams = {}] = expandReferences(
@@ -73,8 +69,7 @@ export function request(method, path, params, callback = s => s) {
 
     return commonRequest(method, resolvedPath, options)
       .then(response => {
-        const log = generateResponseLog(response);
-        console.log(log);
+        logResponse(response);
 
         return {
           ...composeNextState(state, response.body),
@@ -83,8 +78,7 @@ export function request(method, path, params, callback = s => s) {
       })
       .then(callback)
       .catch(err => {
-        const log = generateResponseLog(err);
-        console.log(log);
+        logResponse(err);
 
         throw err;
       });

diff --git a/packages/template/ast.json b/packages/template/ast.json
@@ -35,7 +35,7 @@
           },
           {
             "title": "param",
-            "description": "The data to create the new resource",
+            "description": "The data to create the new resource from",
             "type": {
               "type": "NameExpression",
               "name": "object"

diff --git a/packages/template/src/Adaptor.js b/packages/template/src/Adaptor.js
@@ -2,9 +2,12 @@ import {
   execute as commonExecute,
   composeNextState,
 } from '@openfn/language-common';
-import { expandReferences } from '@openfn/language-common/util'
+import { expandReferences } from '@openfn/language-common/util';
 import { request } from './Utils';
 
+// TODO You can override the execute function to run code at the start
+//      and end of job execution. This is useful for initialising and destroying
+//      client objects. In this example we need it to create the references array.
 /**
  * Execute a sequence of operations.
  * Wraps `language-common/execute` to make working with this API easier.
@@ -32,45 +35,52 @@ export function execute(...operations) {
   };
 }
 
+// TODO this is example Opeartions which might create a resource on
+//      on a fictional service. It demonstrates best practice for how
+//      Operations should be written
 /**
  * Create some resource in some system
  * @public
  * @example
  * create("patient", {"name": "Bukayo"})
  * @function
  * @param {string} resource - The type of entity that will be created
- * @param {object} data - The data to create the new resource
+ * @param {object} data - The data to create the new resource from
  * @param {function} callback - An optional callback function
  * @returns {Operation}
  */
-export function create(resource, data, callback) {
-  return state => {
-    const [resolvedResource, resolvedData] = expandReferences(state, resource, data); 
-
-    const { baseUrl, username, password } = state.configuration;
+export function create(resource, data, callback = s => s) {
+  return async state => {
+    // Parameters like resource and data might be passed as functions, which
+    // allow us to lazily evaluate state references
+    // The expand function will either return the provided values back to us,
+    // or evaluate them first
+    const [resolvedResource, resolvedData] = expandReferences(
+      state,
+      resource,
+      data
+    );
 
-    const url = `${baseUrl}/api/${resolvedResource}`;
-    const auth = { username, password };
+    // Make the request to the service
+    // See src/Utils.js for the request implementation
+    const response = await request(
+      state,
+      'POST',
+      resolvedResource,
+      resolvedData
+    );
 
-    const options = {
-      auth,
-      body: resolvedData,
-      method: 'POST',
+    // Write the result to state.data, update the references array,  and save response metadata
+    const nextState = {
+      ...composeNextState(state, response.body),
+      response,
     };
 
-    return request(url, options).then(response => {
-      const nextState = {
-        ...composeNextState(state, response.data),
-        response,
-      };
-      if (callback) return callback(nextState);
-      return nextState;
-    });
+    // Invoke the callback (if passed) before returning
+    return callback(nextState);
   };
 }
 
-export { request } from './Utils';
-
 // TODO: Decide which functions to publish from @openfn/language-common
 export {
   dataPath,

diff --git a/packages/template/src/Utils.js b/packages/template/src/Utils.js
@@ -1,33 +1,47 @@
-// TODO: Determine how to authenticate for the target API
-function makeAuthHeader(auth) {
-  const { username, password } = auth;
-  const buff = Buffer.from(`${username}:${password}`);
-  const credentials = buff.toString('base64');
-  return { Authorization: `Basic ${credentials}` };
-}
-
-export async function request(url, options) {
-  const { auth } = options;
-  delete options.auth;
-
-  const response = await fetch(url, {
-    ...options,
+/**
+ * If you have any helper functions which are NOT operations,
+ * you should add them here
+ */
+
+import {
+  request as commonRequest,
+  makeBasicAuthHeader,
+} from '@openfn/language-common/util';
+
+// This helper function will call out to the backend service
+// And add authorisation headers
+export const request = (state, method, path, data) => {
+  // TODO This example adds basic auth from config data
+  //       you may need to support other auth strategies
+  const { baseUrl, username, password } = state.configuration;
+  const headers = makeBasicAuthHeader(username, password);
+
+  // TODO You can define custom error messages here
+  //      The request function will throw if it receives
+  //      an error code (<=400), terminating the workflow
+  const errors = {
+    404: 'Page not found',
+  };
+
+  const options = {
+    // Append data to the request body
+    body: data,
+
+    // You can dd extra headers here if yout want to
     headers: {
+      ...headers,
       'content-type': 'application/json',
-      ...makeAuthHeader(auth),
     },
-  });
-
-  // TODO: Handle errors based on the behavior of the target API
-  if (response.status === 404) {
-    throw new Error('Page not found');
-  } else if (response.status === 500) {
-    throw new Error('Server error');
-  } else if (!response.ok) {
-    throw new Error(`HTTP error! status: ${response.status}`);
-  }
-
-  // TODO: Extract data from response based on the target API
-  const data = await response.json();
-  return data;
-}
+
+    // Force the response to be parsed as JSON
+    parseAs: 'json',
+
+    // Include the error map
+    errors,
+  };
+
+  // Build the url base on the baseUrl in config and the path provided
+  const url = `${baseUrl}/api/${path}`;
+  // Make the actual request
+  return commonRequest(method, url, options);
+};