EDSC-4351: Adds comments to local env scripts

bin/api.mjs

@@ -1,3 +1,15 @@
+/**
+ * This script creates a Fastify server that proxies requests to Lambda functions.
+ *
+ * It will use `getApiResources` to get the API Gateway resources and associated Lambda functions.
+ * Then it will create routes for each of the resources and call the associated Lambda function.
+ *
+ * If the lambda function has an authorizer, it will call the authorizer before calling the Lambda function.
+ * If the authorizer fails, it will return a 401 Unauthorized response. It the authorizer succeeds, it will add the authorizer response to the request context.
+ *
+ * If the Lambda function returns a base64 encoded response, it will return the response as a buffer. This is necessary for the scale image lambda.
+ */
+
 import Fastify from 'fastify'
 import cors from '@fastify/cors'
 

bin/generateQueueConfig.mjs

@@ -1,3 +1,14 @@
+/**
+ * This script generates an elasticmq.conf file based on the CDK template provided.
+ *
+ * In the future if we add more queues this should allow us the run SQS locally without needing to
+ * do any configurations outside of the CDK projects.
+ *
+ * This does not implement dead letter queues.
+ * It will only apply the visibilityTimeout property to the queues. If more properties are needed
+ * in the future, they can be added.
+ */
+
 import fs from 'fs'
 
 import { getQueuesFromTemplate } from './getQueuesFromTemplate.mjs'

bin/getApiResources.mjs

@@ -1,3 +1,16 @@
+/**
+ * This file parses a CDK template and extracts the API Gateway resources and
+ * associated Lambda functions. It will navigate into nested stacks to find the
+ * resources if necessary.
+ *
+ * It returns the API Gateway resources and the associated Lambda functions for the
+ * `api` script.
+ *
+ * In the future if we add more API Gateway resources this should allow us to run
+ * the API Gateway locally without needing to do any configurations outside of the
+ * CDK projects.
+ */
+
 import fs from 'fs'
 import path from 'path'
 

bin/getQueuesFromTemplate.mjs

@@ -1,3 +1,14 @@
+/**
+ * This file parses a CDK template and extracts the SQS queues and their associated Lambda functions.
+ * It will navigate into nested stacks to find the resources if necessary.
+ *
+ * It returns the queue URLs and the associated Lambda functions for the `generateQueueConfig`
+ * and `receiveMessages` scripts.
+ *
+ * In the future if we add more queues this should allow us the run SQS locally without needing to
+ * do any configurations outside of the CDK projects.
+ */
+
 import fs from 'fs'
 import path from 'path'
 

bin/invokeLocal.mjs

@@ -1,3 +1,12 @@
+/**
+ * This script will invoke a lambda function locally with a given payload. This
+ * can be useful for calling the `migrateDatabase` function, or calling a fetch order
+ * lambda outside of a step function. But it will work for any lambda function.
+ *
+ * Usage:
+ * npm run invoke-local <lambdaName> <eventPath>
+ */
+
 import fs from 'fs'
 
 // Get the payload from command line arguments

bin/receiveMessages.mjs

@@ -1,3 +1,12 @@
+/**
+ * This file polls the SQS queues and triggers the correct Lambda functions.
+ *
+ * The `getQueuesFromTemplate` function is used to get the queues from the CDK template.
+ *
+ * After triggering the Lambda function, the message is deleted from the queue.
+ * There is no dead letter queue functionality with this script.
+ */
+
 import {
   SQSClient,
   ReceiveMessageCommand,

bin/s3.mjs

@@ -1,3 +1,10 @@
+/**
+ * This file runs s3rver to mock AWS S3. We use this so that we can run the `generateNotebook`
+ * lambda function locally.
+ *
+ * If more buckets are needed in the future, add more values to the `configureBuckets` array.
+ */
+
 import S3rver from 's3rver'
 
 const server = new S3rver({

bin/start.js

@@ -1,3 +1,19 @@
+/**
+ * This file runs the services needed to run the application locally. It is executed by running `npm run start`, or `npm run start:optionals`.
+ *
+ * The script will run `npm run synth` if the CDK template file does not exist.
+ *
+ * By default the script runs the following services:
+ * - Vite (frontend)
+ * - Watch (watches the serverless files and rebuilts the backend)
+ * - API (backend)
+ * - S3 (mocked S3)
+ *
+ * Optionals services:
+ * - ElasticMQ (mocked SQS queues)
+ * - SQS (mocked SQS triggers)
+ */
+
 const fs = require('fs')
 const childProcess = require('child_process')
 const concurrently = require('concurrently')
@@ -14,24 +30,31 @@ let sqsCommands = []
 const setupSqs = process.env.SKIP_SQS !== 'true'
 if (setupSqs) {
   sqsCommands = [{
+    // Run the ElasticMQ server
     command: 'npm run start:elasticmq',
     name: 'elasticmq'
   }, {
+    // Run the SQS script to trigger lambda functions
     command: 'npm run start:sqs',
     name: 'sqs'
   }]
 }
 
 const defaultCommands = [{
+  // Run the React code
   command: 'npm run start:app',
   name: 'vite'
 }, {
+  // Watch the serverless code for changes. This will rebuild the lambdas.
   command: 'npm run watch:api',
   name: 'watch'
 }, {
+  // Run the API. This script watches the serverless/dist directory and will reload the API
+  // when the lambdas are rebuilt by the `watch` service.
   command: 'npm run start:api',
   name: 'api'
 }, {
+  // Run the S3 server
   command: 'npm run start:s3',
   name: 's3'
 }]

esbuild.js

@@ -1,3 +1,10 @@
+/**
+ * This esbuild config will bundle all the lambda functions in the serverless/src directory
+ * and output them to the serverless/dist directory.
+ *
+ * This is currently only used for the local development environment.
+ */
+
 const { build } = require('esbuild')
 
 build({