@suffolklitlab/alkiln 5.12.0 → 5.13.0-logs2

package/lib/docassemble/docassemble_api_interface.js

@@ -1,5 +1,5 @@
 const _da_REST = require('./docassemble_api_REST');
-const log = require('../utils/log');
+const Log = require('../utils/log');
 const session_vars = require('../utils/session_vars' );
 const time = require('../utils/time');
 
@@ -15,6 +15,9 @@ const time = require('../utils/time');
 // to specific functions, which can run in a very small
 // window.
 
+// TODO: Move get_dev_id() and such into here instead of in
+// docassemble_REST - args should be the same vals as the request expects
+
 /** Notes:
 * - Checking for a busy server is vulnerable to race conditions, but
 *    there's nothing we can do about that.
@@ -58,6 +61,10 @@ const time = require('../utils/time');
 let da_i = {};
 module.exports = da_i;
 
+const artifacts_path = session_vars.get_artifacts_path_name();
+const log = new Log({ path: artifacts_path, context: `api` });
+const context = `da api`;
+
 
 // Constants
 const DEFAULT_MAX_REQUEST_MS = session_vars.get_setup_timeout_ms();
@@ -89,7 +96,9 @@ da_i.throw_an_error_if_server_is_not_responding = async function ( options ) {
 
   // Defaults
   let { timeout } = options || { timeout: DEFAULT_MAX_REQUEST_MS };
-  log.info({ type: `da api`, code: `ALK0166`, pre: `Waiting for the docassemble server to respond. Will wait for ${ timeout/1000 } seconds at most.` });
+  log.info({ code: `ALK0166`, context: `da api`, },
+    `Waiting for the docassemble server to respond. Will wait for ${ timeout/1000 } seconds at most.`
+  );
   
   try {
     let start_time = Date.now()
@@ -97,7 +106,9 @@ da_i.throw_an_error_if_server_is_not_responding = async function ( options ) {
     let response = await _da_REST.get_dev_id( timeout );
     let end_time = Date.now()
     if ( response && response.data && response.data.id ) {
-      log.info({ type: `da api`, code: `ALK0167`, pre: `The docassemble server responded after ${ (end_time - start_time)/1000 } seconds.` });
+      log.info({ code: `ALK0167`, context: `da api`, },
+        `The docassemble server responded after ${ (end_time - start_time)/1000 } seconds.`
+      );
       return false;
     }
 
@@ -106,17 +117,16 @@ da_i.throw_an_error_if_server_is_not_responding = async function ( options ) {
     if ( is_timeout_error( error ) ) {
       // Anything that's waiting for the server to not be busy does not want
       // to move forward without a free server.
-      log.info({ type: `da api`, code: `ALK0168`, pre: `The docassemble server was still busy after ${ timeout/1000 } seconds.` });
+      log.info({ code: `ALK0168`, context: `da api`, },
+        `The docassemble server was still busy after ${ timeout/1000 } seconds.`
+      );
     } else {
       // Not sure what to do for other errors. It could be a server
       // error, like an 'Access Denied' error, which should be handled.
-      log.error({
-        type: `da api`,
-        code: `ALK0169`,
-        pre: `Tried to check if the docassemble server was busy, but `
-        + `ran into an unexpected error. The error didn't indicate a busy server, though. Error message:\n`
-        + error
-      });
+      log.warning({ code: `ALK0169`, context: `da api` },
+        `Checked if the server was busy and ran into a different error`,
+        error
+      );
     }
 
     throw error;
@@ -174,25 +184,222 @@ da_i.get_dev_id = async function ( dev_id_options ) {
   return dev_id;
 };  // Ends da_i.get_dev_id();
 
+da_i.get_api_key_access_status = async function ({ timeout = null, api_key = null }) {
+  /** Check if the API key has minimal authorization on the server.
+  *    See https://docassemble.org/docs/api.html#api_user_api_get.
+  *
+  * @param options {obj} Options for getting authorization of the API key
+  * @param options.api_key {str | null} Required. The API key to test.
+  * @param options.timeout {int | null} Optional. Max MS
+  *    to allow for server request.
+  */
+
+  let auth_data = {
+    codes: [ 1 ],
+    has_auth: null,
+    messages: [`API key authorization is not yet determined.`],
+    error: null
+  }
+
+  // Skip this for tests run from ALKilnInThePlayground
+  if ( session_vars.get_origin() === 'playground' ) {
+    auth_data.codes.push( 2 );
+    auth_data.messages.push( `API keys are unnecessary for tests run in the Playground.` );
+  }
+
+  if ( typeof api_key !== `string` ) {
+    auth_data.codes.push( 3 );
+    auth_data.messages.push( `The given API key is not a string. Type: ${ typeof api_key }`);
+  }
+
+  if ( auth_data.codes.length === 1 ) {
+    // Default timeouts
+    timeout = timeout || DEFAULT_MAX_REQUEST_MS;
+    try {
+      let response = await _da_REST.get_api_key_info( timeout, {
+        api_key,
+        server_url: session_vars.get_da_server_url(),
+      });
+      auth_data.has_auth = true;
+      auth_data.codes = [ 6 ];
+      auth_data.messages = [ `This API key has at least basic authorization on this server.` ];
+
+    } catch ( error ) {
+      auth_data.error = error;
+      if ( error.status === 403 ) {
+        auth_data.has_auth = false;
+        auth_data.codes = [ 4 ];
+        auth_data.messages = [ `This API is unverified on this server. It is probably missing or has been deleted.` ];
+      } else {
+        // Note on 404, non-existent key: 404 == 403 - Since we're using the
+        // key itself to get its own info, if it doesn't exist, we'll get 403
+        auth_data.codes = [ 5 ];
+        auth_data.messages = [ `This API key threw a non-403 error.` ];
+      }  // ends error status
+    }  // ends try
+  }  // ends auth_data.codes only has the first code
+
+  // log.debug({ type: `da api info`, code: `ALKx0202`,
+  //   pre: `API key authentication info`, data: auth_data });
+  log.debug({ code: `ALK0202`, context: `da api`, },
+    `API key authentication info`,
+    auth_data
+  );
+
+  return auth_data;
+};  // Ends da_i.get_api_key_access_status()
+
 // node -e 'require("./lib/docassemble/docassemble_api_interface.js").delete_project( "create1" )'
 da_i.delete_project = async function ( delete_options ) {
   /** Delete a project on the user's da server. Do we need to watch
   *   for a timeout? */
 
   // Defaults
-  let { timeout } = delete_options ||  { timeout: DEFAULT_MAX_REQUEST_MS };
+  let { timeout } = delete_options || { timeout: DEFAULT_MAX_REQUEST_MS };
 
   let project_name = session_vars.get_project_name()
-  log.info({ type: `da api`, code: `ALK0170`, pre: `Trying to delete Project ${ project_name }` });
+  log.info({ code: `ALK0170`, context: `da api`, },
+    `Trying to delete Project ${ project_name }`
+  );
 
   try {
     let response = await _da_REST.delete_project( timeout );
-    log.info({ type: `da api`, code: `ALK0171`, pre: `Deleted Project "${ project_name }"` });
+    log.info({ code: `ALK0171`, context: `da api`, },
+      `Deleted Project "${ project_name }"`
+    );
   } catch ( error ) {
-    let msg = `Ran into an error when deleting Project "${ project_name }". See https://docassemble.org/docs/api.html#playground_delete_project.`
-    log.error({ type: `da api`, code: `ALK0172`, pre: msg });
-    log.debug({ type: `da api`, code: `ALK0173`, pre: msg });
-    throw error;
+    log.throw({ code: `ALK0172`, context: `da api`, error: error },
+      `Ran into an error when deleting Project "${ project_name }". See https://docassemble.org/docs/api.html#playground_delete_project.`
+    );
+    // throw error;
   }
 
 };  // Ends da_i.delete_project()
+
+// node -e 'require("./lib/docassemble/docassemble_api_interface.js").quietly_try_to_delete_interviews(...)'
+da_i.quietly_try_to_delete_interviews = async function ({ interviews = {}, api_keys = [], options = {} }) {
+  /** Try to delete the given interviews. Fail silently. Example failure: the test
+   *    did not log in any users and the testing account's role prevents
+   *    access to other user's interviews. Do we need to watch for a timeout? */
+
+  // Defaults
+  let { timeout } = options || { timeout: DEFAULT_MAX_REQUEST_MS };
+
+  let responses = [];
+  for ( let id in interviews ) {
+    let interview = interviews[ id ];
+    if ( interview && interview.uid ) {
+      let sub_responses = await da_i.quietly_delete_one_interview( timeout, {
+        interview,
+        api_keys
+      });
+      responses.push( sub_responses );
+    } else {
+      log.debug({ code: `ALK0191`, context: `da api` },
+        `There is no interview to delete.`
+      );
+    }
+  }
+  return responses;
+};  // Ends da_i.quietly_try_to_delete_interviews()
+
+// node -e 'require("./lib/docassemble/docassemble_api_interface.js").quietly_delete_one_interview(...)'
+da_i.quietly_delete_one_interview = async function ( timeout, { interview = {}, api_keys = [] }) {
+  /** Try to delete an interview using all available API keys. Fail silently.
+   *    Example failure: the test did not log in any users and the testing
+   *    account's role prevents access to other user's interviews. */
+
+  let responses = [];
+  for ( let api_key of api_keys ) {
+    try {
+      log.debug({ code: `ALK0188`, context: `da api` },
+        `Trying to delete the interview with the id ${ interview.uid } and an API key.`
+      );
+
+      // Actual work:
+      let response = await _da_REST.delete_interview( timeout, {
+        session: interview.uid,
+        api_key
+      });
+      responses.push( response );
+
+      log.debug({ code: `ALK0189`, context: `da api` },
+        `No error when trying to delete interview ${ interview.uid } at ${ interview.i }.`
+      );
+    } catch ( error ) {
+      error.interview = interview;
+      log.debug({ code: `ALK0190`, context: `da api` },
+        `Error when deleting the interview. See https://docassemble.org/docs/api.html#session_delete.`,
+        error
+      );
+    }
+  }  // ends for api keys
+  return responses;
+};  // Ends da_i.quietly_delete_one_interview()
+
+// node -e 'require("./lib/docassemble/docassemble_api_interface.js").get_interviews(...)'
+da_i.get_interviews = async function ({ interviews = {}, api_keys = [], options = {} }) {
+  /** Return an object of interviews that exist on the server
+   *    that match the given interviews. Keys are the session ids. */
+
+  let fetched_interviews = {};
+  if ( interviews ) {
+    for ( let id in interviews ) {
+      let interview = interviews[ id ];
+      let fetched = await da_i.get_interview({ interview, api_keys, options });
+      if ( fetched && fetched.session ) {
+        fetched_interviews[ fetched.session ] = fetched;
+      }
+    }
+  }  // ends if interviews
+
+  return fetched_interviews;
+};  // Ends da_i.get_interviews()
+
+// node -e 'require("./lib/docassemble/docassemble_api_interface.js").get_interview(...)'
+da_i.get_interview = async function ({ interview = {}, api_keys = [], options = {} }) {
+  /** Try to get an interview from the server that matches the given interview data. */
+
+  // Defaults
+  let { timeout } = options || { timeout: DEFAULT_MAX_REQUEST_MS };
+
+  if ( interview && interview.uid ) {
+    for ( let api_key of api_keys ) {
+      try {
+        log.debug({ code: `ALK0192`, context: `da api` },
+          `Trying to get the interview with the id ${ interview.uid } and an API key.`
+        );
+
+        // Actual work:
+        let response = await _da_REST.get_interview( timeout, {
+          session: interview.uid,
+          api_key
+        });
+
+        if ( response && response.data && response.data.items && response.data.items[0] && response.data.items[0].session ) {
+          log.debug({ code: `ALK0193`, context: `da api` },
+            `Status ${ response.status }. Got ${ response.data.items[0].session }.`
+          );
+          return response.data.items[0];
+        } else {
+          log.debug({ code: `ALK0194`, context: `da api` },
+            `Status ${ response.status }. Cannot find ${ interview.uid }`
+          );
+        }
+
+      } catch ( error ) {
+        error.interview = interview;
+        log.debug({ code: `ALK0195`, context: `da api` },
+          `${ error.status || `No error.status.` } ${ error.statusText || error.data || `No error.statusText.` } Ran into an error when getting the interview ${ interview.uid }. See https://docassemble.org/docs/api.html#interviews.`,
+          error
+        );
+      }
+    }  // ends for api_keys
+  } else {
+    log.debug({ code: `ALK0196`, context: `da api` },
+      `There is no interview to get.`
+    );
+  }
+
+  return null;
+};  // Ends da_i.get_interview()

package/lib/docassemble/server_install.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
 const session_vars = require('../utils/session_vars');
-const log = require('../utils/log');
+const Log = require('../utils/log');
 const fg = require('fast-glob');
 
 const server_install = async () => {
+  /** Finds out where in this directory the package's folders are. */
   session_vars.save_install_method(`server`);
 
   // Get path to folders inside repo main "docassemble" folder
@@ -23,20 +24,33 @@ const server_install = async () => {
   // Get names of all folders in repo "docassemble" folder
   let chosen_folder = folders[0];
   if ( folders.length === 0 ) {
-    let msg = `There are 0 folders at ${path}. Stopping tests.`;
-    log.error({ type: `setup`, code: `ALK0044`, data: msg })
-    throw new ReferenceError( msg );
+    let msg = `ALKiln cannot find the package's files. There are 0 folders at "${ path }". Stopping tests.`;
+    log.throw({ code: `ALK0044`, context: `server_install`,
+      error: new ReferenceError( msg );  // no logs
+    });
   }
 
   if ( folders.length > 1 ) {
-    log.warn({
-      type: `setup`,
-      code: `ALK0045`,
-      data: `There are ${folders.length} folders at ${path}: "${folders.join('", "')}". ALKiln chose to use the folder "${chosen_folder}".`
-    })
+    log.warn({ code: `ALK0045`, context: `setup`, },
+      `There are ${ folders.length } folders at "${ path }": "${ folders.join('", "') }". ALKiln chose to use the folder "${ chosen_folder }".`
+    );
+  } else {
+    log.info({ code: `ALK0218`, context: `setup`, },
+      `ALKiln found the package folder at "${ chosen_folder }".`
+    );
   }
   
   session_vars.save_repo_folder_name( chosen_folder );
 };  // Ends server_install();
 
+// 1. session_vars - make sure all the required env vars exist
+session_vars.validateEnvironment();
+
+// 2. Prepare logs
+// Local devs: This will be separate from your test paths
+// unless you pass a `path` argument into the cucumber run command
+const argv = require(`minimist`)(process.argv.slice(2));
+const log = new Log({ path: argv.path, context: `server_install` });
+
+// 3. run
 server_install();

package/lib/docassemble/setup.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
-// TODO: Rename to playground_install?
-
 const child_process = require(`child_process`);
 
-const log = require(`../utils/log`);
+const Log = require(`../utils/log`);
 const session_vars = require(`../utils/session_vars` );
+const files = require(`../utils/files` );
+const time = require(`../utils/time` );
 
 const setup = async () => {
   /** In the docassemble testing account identified by the
@@ -18,9 +18,14 @@ const setup = async () => {
   let project_name = session_vars.get_project_base_name().replace(/[^A-Za-z0-9]/g, '') + `${Date.now()}`;
   session_vars.save_project_name( project_name );
 
-  log.info({ type: `setup`, code: `ALK0046`, pre: `Starting to upload this package to `
+  const starting_msg = `Starting to upload this package to `
     + `a new Project called ${project_name} in the Playground `
-    + `of your server's testing account. It may take a couple of minutes.` });
+    + `of your server's testing account. It may take a couple of minutes.`;
+  log.info({ code: `ALK0046`, context: `setup` },
+    starting_msg
+  );
+
+  // TODO: 1. Start listening to the normal console here (for debug logging)
 
   // dainstall . --apiurl https://site.org --apikey $API_KEY --playground --project=name
   // I think this won't run on windows? Why do I think this? Where on the
@@ -34,29 +39,37 @@ const setup = async () => {
       `--playground`, `--project=${ project_name }`
     ],
     // Prints messages from the process to the console while it's running
+    // result.stderr, result.stdout, etc. will be `null`
     { stdio: 'inherit', }
   );
 
-  // 403 is invalid API key, but I'm not sure how to output
-  // the response to find out the error code
+  // TODO: 2. Stop listening to the normal console here
 
+  // 403 is invalid API key, but I'm not sure how to output
+  // the response to find out the error code. stderr is `null`.
   if ( result.status !== 0 ) {
-    log.error({
-      type: `setup`,
-      code: `ALK0047`,
-      pre: `Status code ${ result.status }. Could not dainstall this package on your server. See above for more details.`
-    });
-    throw(result.stderr);
+    const install_err_msg = `Status code ${ result.status }. Could not `
+      + `dainstall this package on your server. See above for more details.`;
+    log.throw({ code: `ALK0047`, context: `setup`,
+      before: `☝️ ☝️ ☝️  Error data ☝️ ☝️ ☝️\n`,
+      error: `Error while installing project` },
+      install_err_msg
+    );
   }
 
-  log.success({
-    type: `setup`,
-    code: `ALK0048`,
-    pre: `ALKiln created a Project in your Playground named "${ project_name }"!`
-  });
+  log.success({ code: `ALK0048`, context: `setup`, },
+    `ALKiln created a Project in your Playground named "${ project_name }"!`
+  );
 };  // Ends setup();
 
-
-// Before everything, make sure all the required env vars exist
+// 1. session_vars - make sure all the required env vars exist
 session_vars.validateEnvironment();
+
+// 2. Prepare logs
+// Local devs: This will be separate from your test paths
+// unless you pass a `path` argument into the cucumber run command
+const argv = require(`minimist`)(process.argv.slice(2));
+const log = new Log({ path: argv.path, context: `setup` });
+
+// 3. run
 setup();

package/lib/docassemble/takedown.js

@@ -1,26 +1,46 @@
 #!/usr/bin/env node
 
 const da_i = require('./docassemble_api_interface');
-const log = require('../utils/log');
-const session_vars = require('../utils/session_vars' );
+const session_vars = require('../utils/session_vars');
+const Log = require('../utils/log');
 
 const takedown = async () => {
-  /* In the docassemble testing account identified by the
+  /** In the docassemble testing account identified by the
   *   DOCASSEMBLE_DEVELOPER_API_KEY secret, delete the
   *   Project created for this test.
   *   For local development, clean up project name file. */
-  log.info({ type: `takedown`, code: `ALK0177`, pre: `Trying to remove the docassemble Project from the testing account.` });
+  log.info({ code: `ALK0177`, context: `takedown`, },
+    `Trying to remove the docassemble Project from the testing account.`
+  );
   // Explicit try-catch prevents "Unhandled promise rejection error"
   // avoids showing confusing node errors to users that they shouldn't have to fix
   try {
     await da_i.delete_project();
     session_vars.delete_project_name();
-    log.success({ type: `takedown`, code: `ALK0178`, pre: `Test takedown has finished successfully!` });
+    log.info({ code: `ALK0178`, context: `takedown`, },
+      `Test takedown finished successfully!`
+    );
   } catch (error) {
-    log.error({type: `takedown`, code: `ALK0179`, pre: `Could not delete project`, data: JSON.stringify(error, null, 4)})
-    // we don't re-throw the exception, so make sure to exit with 1 to let GitHub Actions know the script failed
+    log.throw({ code: `ALK0179`, context: `takedown`, error: error },
+      `Unable to delete project`,
+    );
+    // we don't re-throw the exception, so make sure to exit
+    // with 1 to let GitHub Actions know the script failed
     process.exitCode = 1;
   }
+
+  // TODO: ? Build the final setup, run, & takedown verbose log
+  // file in here. Add to it in the GitHub action ?
 };
 
+// 1. session_vars - make sure all the required env vars exist
+session_vars.validateEnvironment();
+
+// 2. Prepare logs
+// Local devs: This will be separate from your test artifacts paths
+// unless you pass a `path` argument into the `cucumber` run command
+const argv = require(`minimist`)( process.argv.slice(2) );
+const log = new Log({ path: argv.path, context: `takedown` });
+
+// 3. run
 takedown();