dce-expresskit 4.0.0-beta-logreviewer.1

package/src/helpers/getLogReviewerLogs.ts

@@ -0,0 +1,259 @@
+// Import dce-reactkit
+import {  
+  DAY_IN_MS,
+  Log,
+  LogReviewerFilterState, 
+  LogType 
+} from 'dce-reactkit';
+
+// Import shared types
+import LOG_REVIEW_PAGE_SIZE from '../constants/LOG_REVIEW_PAGE_SIZE';
+import { Collection } from 'dce-mango';
+
+/**
+ * Get logs for the log reviewer interface
+ * @author Yuen Ler Chow
+ * @param opts object containing all arguments
+ * @param opts.pageNumber the page number to retrieve (1-indexed)
+ * @param opts.filters filter criteria for logs
+ * @param opts.countDocuments if true, count number of documents matching
+ *   filters and return num pages (not always required because if changing pages,
+ *   we don't need to recount documents)
+ * @param opts.logCollection MongoDB collection containing logs
+ * @returns object with logs for the requested page and optionally total number of pages
+ */
+const getLogReviewerLogs = async (
+  opts: {
+    pageNumber: number,
+    filters: LogReviewerFilterState,
+    countDocuments: boolean,
+    logCollection: Collection<Log>,
+  },
+) => {
+
+  // Destructure opts
+  const {
+    pageNumber,
+    filters,
+    countDocuments,
+    logCollection,
+  } = opts;
+  
+
+  // Destructure filters
+  const {
+    dateFilterState,
+    contextFilterState,
+    tagFilterState,
+    actionErrorFilterState,
+    advancedFilterState,
+  } = filters as LogReviewerFilterState;
+
+  // Build MongoDB query based on filters
+  const query: { [k: string]: any } = {};
+
+  /* -------------- Date Filter ------------- */
+
+  // Convert start and end dates from the dateFilterState into timestamps
+  const { startDate, endDate } = dateFilterState;
+  const startTimestamp = new Date(
+    `${startDate.month}/${startDate.day}/${startDate.year}`,
+  ).getTime();
+  const endTimestamp = (
+    (new Date(`${endDate.month}/${endDate.day}/${endDate.year}`)).getTime()
+    + DAY_IN_MS
+  );
+
+  // Add a date range condition to the query
+  query.timestamp = {
+    $gte: startTimestamp,
+    $lt: endTimestamp,
+  };
+
+  /* ------------ Context Filter ------------ */
+
+  // Process context filters to include selected contexts and subcontexts
+  const contextConditions: { [k: string]: any }[] = [];
+  Object.keys(contextFilterState).forEach((context) => {
+    const value = contextFilterState[context];
+    if (typeof value === 'boolean') {
+      if (value) {
+        // The entire context is selected
+        contextConditions.push({ context });
+      }
+    } else {
+      // The context has subcontexts
+      const subcontexts = Object.keys(value).filter((subcontext) => {
+        return value[subcontext];
+      });
+
+      if (subcontexts.length > 0) {
+        contextConditions.push({
+          context,
+          subcontext: { $in: subcontexts },
+        });
+      }
+    }
+  });
+  if (contextConditions.length > 0) {
+    query.$or = contextConditions;
+  }
+
+  /* -------------- Tag Filter -------------- */
+
+  const selectedTags = Object.keys(tagFilterState).filter((tag) => { return tagFilterState[tag]; });
+  if (selectedTags.length > 0) {
+    query.tags = { $in: selectedTags };
+  }
+
+  /* --------- Action/Error Filter ---------- */
+
+  if (actionErrorFilterState.type) {
+    query.type = actionErrorFilterState.type;
+  }
+
+  if (actionErrorFilterState.type === LogType.Error) {
+    if (actionErrorFilterState.errorMessage) {
+      // Add error message to the query.
+      // $i is used for case-insensitive search, and $regex is used for partial matching
+      query.errorMessage = {
+        $regex: actionErrorFilterState.errorMessage,
+        $options: 'i',
+      };
+    }
+
+    if (actionErrorFilterState.errorCode) {
+      query.errorCode = {
+        $regex: actionErrorFilterState.errorCode,
+        $options: 'i',
+      };
+    }
+  }
+
+  if (actionErrorFilterState.type === LogType.Action) {
+    const selectedTargets = (
+      Object.keys(actionErrorFilterState.target)
+        .filter((target) => {
+          return actionErrorFilterState.target[target];
+        })
+    );
+    const selectedActions = (
+      Object.keys(actionErrorFilterState.action)
+        .filter((action) => {
+          return actionErrorFilterState.action[action];
+        })
+    );
+    if (selectedTargets.length > 0) {
+      query.target = { $in: selectedTargets };
+    }
+    if (selectedActions.length > 0) {
+      query.action = { $in: selectedActions };
+    }
+  }
+
+  /* ------------ Advanced Filter ----------- */
+
+  if (advancedFilterState.userFirstName) {
+    query.userFirstName = {
+      $regex: advancedFilterState.userFirstName,
+      $options: 'i',
+    };
+  }
+
+  if (advancedFilterState.userLastName) {
+    query.userLastName = {
+      $regex: advancedFilterState.userLastName,
+      $options: 'i',
+    };
+  }
+
+  if (advancedFilterState.userEmail) {
+    query.userEmail = {
+      $regex: advancedFilterState.userEmail,
+      $options: 'i',
+    };
+  }
+
+  if (advancedFilterState.userId) {
+    query.userId = Number.parseInt(advancedFilterState.userId, 10);
+  }
+
+  const roles: {
+    isLearner?: boolean,
+    isTTM?: boolean,
+    isAdmin?: boolean,
+  }[] = [];
+  if (advancedFilterState.includeLearners) {
+    roles.push({ isLearner: true });
+  }
+  if (advancedFilterState.includeTTMs) {
+    roles.push({ isTTM: true });
+  }
+  if (advancedFilterState.includeAdmins) {
+    roles.push({ isAdmin: true });
+  }
+  // If any roles are selected, add them to the query
+  if (roles.length > 0) {
+    // The $or operator is used to match any of the roles
+    // The $and operator is to ensure that other conditions in the query are met
+    query.$and = [{ $or: roles }];
+  }
+
+  if (advancedFilterState.courseId) {
+    query.courseId = Number.parseInt(advancedFilterState.courseId, 10);
+  }
+
+  if (advancedFilterState.courseName) {
+    query.courseName = {
+      $regex: advancedFilterState.courseName,
+      $options: 'i',
+    };
+  }
+
+  if (advancedFilterState.isMobile !== undefined) {
+    query['device.isMobile'] = Boolean(advancedFilterState.isMobile);
+  }
+
+  if (advancedFilterState.source) {
+    query.source = advancedFilterState.source;
+  }
+
+  if (advancedFilterState.routePath) {
+    query.routePath = {
+      $regex: advancedFilterState.routePath,
+      $options: 'i',
+    };
+  }
+
+  if (advancedFilterState.routeTemplate) {
+    query.routeTemplate = {
+      $regex: advancedFilterState.routeTemplate,
+      $options: 'i',
+    };
+  }
+
+  // Query for logs
+  const response = await logCollection.findPaged({
+    query,
+    perPage: LOG_REVIEW_PAGE_SIZE,
+    pageNumber,
+    sortDescending: true,
+  });
+
+  // Count documents if requested
+  if (countDocuments) {
+    const numPages = Math.ceil(
+      await logCollection.count(query)
+      / LOG_REVIEW_PAGE_SIZE
+  );
+    return {
+      ...response,
+      numPages,
+    };
+  }
+
+  // Return response
+  return response;
+};
+
+export default getLogReviewerLogs;

package/src/helpers/handleError.ts

@@ -0,0 +1,66 @@
+// Import shared types
+import { ReactKitErrorCode } from 'dce-reactkit';
+import ExpressKitErrorCode from '../types/ExpressKitErrorCode';
+
+/**
+ * Handle an error and respond to the client
+ * @author Gabe Abrams
+ * @param res express response
+ * @param error error info
+ * @param opts.err the error to send to the client
+ *   or the error message
+ * @param [opts.code] an error code (only used if err.code is not
+ *   included)
+ * @param [opts.status=500] the https status code to use
+ *   defined)
+ */
+const handleError = (
+  res: any,
+  error: (
+    | {
+      message: any,
+      code?: string,
+      status?: number,
+    }
+    | Error
+    | string
+    | any
+  ),
+): undefined => {
+  // Get the error message
+  let message;
+  if (error && (error as any).message) {
+    message = (error.message || 'An unknown error occurred.');
+  } else if (typeof error === 'string') {
+    message = (
+      error.trim().length > 0
+        ? error
+        : 'An unknown error occurred.'
+    );
+  } else {
+    message = 'An unknown error occurred.';
+  }
+
+  // Get the error code
+  const code = (error.code || ReactKitErrorCode.NoCode);
+
+  // Get the status code
+  const status = (error.status || 500);
+
+  // Respond to user
+  res
+    // Set the http status code
+    .status(status)
+    // Send a JSON response
+    .json({
+      // Error message
+      message,
+      // Error code
+      code,
+      // Success = false flag so client can detect server-side errors
+      success: false,
+    });
+  return undefined;
+};
+
+export default handleError;

package/src/helpers/handleSuccess.ts

@@ -0,0 +1,18 @@
+/**
+ * Send successful API response
+ * @author Gabe Abrams
+ * @param res express response
+ * @param body the body of the response to send to the client
+ */
+const handleSuccess = (res: any, body: any): undefined => {
+  // Send a http 200 json response
+  res.json({
+    // Include the body as a parameter
+    body,
+    // Success = true flag so client can detect successful responses
+    success: true,
+  });
+  return undefined;
+};
+
+export default handleSuccess;

package/src/helpers/initCrossServerCredentialCollection.ts

@@ -0,0 +1,19 @@
+// Import dce-mango
+import { Collection as MangoCollection } from 'dce-mango';
+
+/**
+ * Initialize a cross-server credential collection given the dce-mango Collection class
+ * @author Gabe Abrams
+ * @param Collection the Collection class from dce-mango
+ * @returns initialized logCollection
+ */
+const initCrossServerCredentialCollection = (Collection: typeof MangoCollection) => {
+  return new Collection(
+    'CrossServerCredential',
+    {
+      uniqueIndexKey: 'key',
+    },
+  );
+};
+
+export default initCrossServerCredentialCollection;

package/src/helpers/initLogCollection.ts

@@ -0,0 +1,30 @@
+// Import dce-mango
+import { Collection as MangoCollection } from 'dce-mango';
+
+/**
+ * Initialize a log collection given the dce-mango Collection class
+ * @author Gabe Abrams
+ * @param Collection the Collection class from dce-mango
+ * @returns initialized logCollection
+ */
+const initLogCollection = (Collection: typeof MangoCollection) => {
+  return new Collection(
+    'Log',
+    {
+      uniqueIndexKey: 'id',
+      indexKeys: [
+        'courseId',
+        'context',
+        'subcontext',
+        'tags',
+        'year',
+        'month',
+        'day',
+        'hour',
+        'type',
+      ],
+    },
+  );
+};
+
+export default initLogCollection;

package/src/helpers/initServer.ts

@@ -0,0 +1,283 @@
+// Import express
+import express from 'express';
+
+// Import dce-mango
+import { Collection } from 'dce-mango';
+
+// Import dce-reactkit
+import {
+  ParamType,
+  LogFunction,
+  LOG_ROUTE_PATH,
+  LOG_REVIEW_STATUS_ROUTE,
+  Log,
+  LOG_REVIEW_GET_LOGS_ROUTE,
+  ErrorWithCode,
+} from 'dce-reactkit';
+
+// Import shared helpers
+import genRouteHandler from './genRouteHandler';
+import getLogReviewerLogs from './getLogReviewerLogs';
+
+// Import shared types
+import ExpressKitErrorCode from '../types/ExpressKitErrorCode';
+import CrossServerCredential from '../types/CrossServerCredential';
+
+// Stored copy of dce-mango log collection
+let _logCollection: Collection<Log>;
+
+// Stored copy of dce-mango cross-server credential collection
+let _crossServerCredentialCollection: Collection<CrossServerCredential>;
+
+/*------------------------------------------------------------------------*/
+/*                                 Helpers                                */
+/*------------------------------------------------------------------------*/
+
+/**
+ * Get log collection
+ * @author Gabe Abrams
+ * @returns log collection if one was included during launch or null if we don't
+ *   have a log collection (yet)
+ */
+export const internalGetLogCollection = () => {
+  return _logCollection ?? null;
+};
+
+/**
+ * Get cross-server credential collection
+ * @author Gabe Abrams
+ * @return cross-server credential collection if one was included during launch or null
+ *   if we don't have a cross-server credential collection (yet)
+ */
+export const internalGetCrossServerCredentialCollection = () => {
+  return _crossServerCredentialCollection ?? null;
+};
+
+/*------------------------------------------------------------------------*/
+/*                                  Main                                  */
+/*------------------------------------------------------------------------*/
+
+/**
+ * Prepare dce-reactkit to run on the server
+ * @author Gabe Abrams
+ * @param opts object containing all arguments
+ * @param opts.app express app from inside of the postprocessor function that
+ *   we will add routes to
+ * @param opts.getLaunchInfo CACCL LTI's get launch info function
+ * @param [opts.logCollection] mongo collection from dce-mango to use for
+ *   storing logs. If none is included, logs are written to the console
+ * @param [opts.logReviewAdmins=all] info on which admins can review
+ *   logs from the client. If not included, all Canvas admins are allowed to
+ *   review logs. If null, no Canvas admins are allowed to review logs.
+ *   If an array of Canvas userIds (numbers), only Canvas admins with those
+ *   userIds are allowed to review logs. If a dce-mango collection, only
+ *   Canvas admins with entries in that collection ({ userId, ...}) are allowed
+ *   to review logs
+ * @param [opts.crossServerCredentialCollection] mongo collection from dce-mango to use for
+ *   storing cross-server credentials. If none is included, cross-server credentials
+ *   are not supported
+ */
+const initServer = (
+  opts: {
+    app: express.Application,
+    logReviewAdmins?: (number[] | Collection<any>),
+    logCollection?: Collection<Log>,
+    crossServerCredentialCollection?: Collection<CrossServerCredential>,
+  },
+) => {
+  _logCollection = opts.logCollection;
+  _crossServerCredentialCollection = opts.crossServerCredentialCollection;
+
+  /*----------------------------------------*/
+  /*                Logging                 */
+  /*----------------------------------------*/
+
+  /**
+   * Log an event
+   * @author Gabe Abrams
+   * @param {string} context Context of the event (each app determines how to
+   *   organize its contexts)
+   * @param {string} subcontext Subcontext of the event (each app determines
+   *   how to organize its subcontexts)
+   * @param {string} tags stringified list of tags that apply to this action
+   *   (each app determines tag usage)
+   * @param {string} metadata stringified object containing optional custom metadata
+   * @param {string} level log level
+   * @param {string} [errorMessage] error message if type is an error
+   * @param {string} [errorCode] error code if type is an error
+   * @param {string} [errorStack] error stack if type is an error
+   * @param {string} [target] Target of the action (each app determines the list
+   *   of targets) These are usually buttons, panels, elements, etc.
+   * @param {LogAction} [action] the type of action performed on the target
+   * @returns {Log}
+   */
+  opts.app.post(
+    LOG_ROUTE_PATH,
+    genRouteHandler({
+      paramTypes: {
+        context: ParamType.String,
+        subcontext: ParamType.String,
+        tags: ParamType.JSON,
+        level: ParamType.String,
+        metadata: ParamType.JSON,
+        errorMessage: ParamType.StringOptional,
+        errorCode: ParamType.StringOptional,
+        errorStack: ParamType.StringOptional,
+        target: ParamType.StringOptional,
+        action: ParamType.StringOptional,
+      },
+      handler: ({ params, logServerEvent }) => {
+        // Create log info
+        const logInfo: Parameters<LogFunction>[0] = (
+          (params.errorMessage || params.errorCode || params.errorStack)
+            // Error
+            ? {
+              context: params.context,
+              subcontext: params.subcontext,
+              tags: params.tags,
+              level: params.level,
+              metadata: params.metadata,
+              error: {
+                message: params.errorMessage,
+                code: params.errorCode,
+                stack: params.errorStack,
+              },
+            }
+            // Action
+            : {
+              context: params.context,
+              subcontext: params.subcontext,
+              tags: params.tags,
+              level: params.level,
+              metadata: params.metadata,
+              target: params.target,
+              action: params.action,
+            }
+        );
+
+        // Add hidden boolean to change source to "client"
+        const logInfoForcedFromClient = {
+          ...logInfo,
+          overrideAsClientEvent: true,
+        };
+
+        // Write the log
+        const log = logServerEvent(logInfoForcedFromClient);
+
+        // Return
+        return log;
+      },
+    }),
+  );
+
+  /*----------------------------------------*/
+  /*              Log Reviewer              */
+  /*----------------------------------------*/
+
+  /**
+   * Check if a given user is allowed to review logs
+   * @author Gabe Abrams
+   * @param userId the id of the user
+   * @param isAdmin if true, the user is an admin
+   * @returns true if the user can review logs
+   */
+  const canReviewLogs = async (
+    userId: number,
+    isAdmin: boolean,
+  ): Promise<boolean> => {
+    // Immediately deny access if user is not an admin
+    if (!isAdmin) {
+      return false;
+    }
+
+    // If all admins are allowed, we're done
+    if (!opts.logReviewAdmins) {
+      return true;
+    }
+
+    // Do a dynamic check
+    try {
+      // Array of userIds
+      if (Array.isArray(opts.logReviewAdmins)) {
+        return opts.logReviewAdmins.some((allowedId) => {
+          return (userId === allowedId);
+        });
+      }
+
+      // Must be a collection
+      const matches = await opts.logReviewAdmins.find({ userId });
+
+      // Make sure at least one entry matches
+      return matches.length > 0;
+    } catch (err) {
+      // If an error occurred, simply return false
+      return false;
+    }
+  };
+
+  /**
+   * Check if the current user has access to logs
+   * @author Gabe Abrams
+   * @returns {boolean} true if user has access
+   */
+  opts.app.get(
+    LOG_REVIEW_STATUS_ROUTE,
+    genRouteHandler({
+      handler: async ({ params }) => {
+        const { userId, isAdmin } = params;
+        const canReview = await canReviewLogs(userId, isAdmin);
+        return canReview;
+      },
+    }),
+  );
+
+  /**
+   * Get filtered logs based on provided filters
+   * @author Gabe Abrams, Yuen Ler Chow
+   * @param pageNumber the page number to get
+   * @param filters the filters to apply to the logs
+   * @returns {Log[]} list of logs that match the filters
+   */
+  opts.app.get(
+    LOG_REVIEW_GET_LOGS_ROUTE,
+    genRouteHandler({
+      paramTypes: {
+        pageNumber: ParamType.Int,
+        filters: ParamType.JSON,
+        countDocuments: ParamType.Boolean,
+      },
+      handler: async ({ params }) => {
+        // Destructure params
+        const {
+          pageNumber,
+          userId,
+          isAdmin,
+          filters,
+          countDocuments,
+        } = params;
+
+        // Validate user
+        const canReview = await canReviewLogs(userId, isAdmin);
+        if (!canReview) {
+          throw new ErrorWithCode(
+            'You cannot access this resource because you do not have the appropriate permissions.',
+            ExpressKitErrorCode.NotAllowedToReviewLogs,
+          );
+        }
+
+        // Get logs
+        const response = await getLogReviewerLogs({
+          pageNumber,
+          filters,
+          countDocuments,
+          logCollection: _logCollection,
+        });
+
+        // Return response
+        return response;
+      },
+    }),
+  );
+};
+
+export default initServer;