small commenting on uploadutils

1 files changed, 30 insertions, 3 deletions

diff --git a/src/server/DashUploadUtils.ts b/src/server/DashUploadUtils.ts
index 2af816df8..ab3564ebb 100644
--- a/src/server/DashUploadUtils.ts
+++ b/src/server/DashUploadUtils.ts
@@ -160,6 +160,11 @@ export namespace DashUploadUtils {
     export const InspectImage = async (source: string): Promise<Upload.InspectionResults | Error> => {
         let rawMatches: RegExpExecArray | null;
         let filename: string | undefined;
+        /**
+         * Just more edge case handling: this if clause handles the case where an image onto the canvas that
+         * is represented by a base64 encoded data uri, rather than a proper file. We manually write it out
+         * to the server and then carry on as if it had been put there by the Formidable form / file parser.
+         */
         if ((rawMatches = /^data:image\/([a-z]+);base64,(.*)/.exec(source)) !== null) {
             const [ext, data] = rawMatches.slice(1, 3);
             const resolved = filename = `upload_${Utils.GenerateGuid()}.${ext}`;
@@ -172,21 +177,35 @@ export namespace DashUploadUtils {
             source = `http://localhost:1050${clientPathToFile(Directory.images, resolved)}`;
         }
         let resolvedUrl: string;
+        /**
+         * At this point, we want to take whatever url we have and make sure it's requestable.
+         * Anything that's hosted by some other website already is, but if the url is a local file url
+         * (locates the file on this server machine), we have to resolve the client side url by cutting out the
+         * basename subtree (i.e. /images/<some_guid>.<ext>) and put it on the end of the server's url.
+         * 
+         * This can always be localhost, regardless of whether this is on the server or not, since we (the server, not the client)
+         * will be the ones making the request, and from the perspective of dash-release or dash-web, localhost:1050 refers to the same thing
+         * as the full dash-release.eastus.cloudapp.azure.com:1050.
+         */
         const matches = isLocal().exec(source);
         if (matches === null) {
             resolvedUrl = source;
         } else {
             resolvedUrl = `http://localhost:1050/${matches[1].split("\\").join("/")}`;
         }
+        // See header comments: not all image files have exif data (I believe only JPG is the only format that can have it)
         const exifData = await parseExifData(resolvedUrl);
         const results = {
             exifData,
             requestable: resolvedUrl
         };
+        // Use the request library to parse out file level image information in the headers
         const { headers } = (await new Promise<any>((resolve, reject) => {
             request.head(resolvedUrl, (error, res) => error ? reject(error) : resolve(res));
         }).catch(error => console.error(error)));
+        // Compute the native width and height ofthe image with an npm module
         const { width: nativeWidth, height: nativeHeight }: RequestedImageSize = await requestImageSize(resolvedUrl);
+        // Bundle up the information into an object
         return {
             source,
             contentSize: parseInt(headers[size]),
@@ -198,6 +217,16 @@ export namespace DashUploadUtils {
         };
     };
 
+    /**
+     * Basically just a wrapper around rename, which 'deletes'
+     * the file at the old path and 'moves' it to the new one. For simplicity, the
+     * caller just has to pass in the name of the target directory, and this function
+     * will resolve the actual target path from that.
+     * @param file The file to move
+     * @param destination One of the specific media asset directories into which to move it
+     * @param suffix If the file doesn't have a suffix and you want to provide it one
+     * to appear in the new location
+     */
     export async function MoveParsedFile(file: File, destination: Directory, suffix: string | undefined = undefined): Promise<Upload.FileResponse> {
         const { path: sourcePath } = file;
         let name = path.basename(sourcePath);
@@ -211,10 +240,8 @@ export namespace DashUploadUtils {
                         accessPaths: {
                             agnostic: getAccessPaths(destination, name)
                         }
-
                     }
-                }
-                );
+                });
             });
         });
     }