refactor(api): extract file system logic from API layer (#8)

**Breaking changes**:

Meaning of `path` in serverless resources changed from filePath to URL path changed.
Additionally, `name` configuration was added.

fix #7

Author: stefanjudis

packages/serverless-api/README.md

@@ -91,6 +91,31 @@ Unless a deployConfig. serviceSid is specified, it will try to create one. If a
 
 Updates to the deployment will be emitted as events to status-update.
 
+```js
+const result = await client.deployProject({
+  env: {},
+  pkgJson: {},
+  serviceName: 'serverless-example',
+  functionsEnv: 'dev',
+  functions: [
+    {
+      name: 'hello-world',
+      path: '/hello-world-path',
+      content: await readFile(path.join(__dirname, 'some-dir', 'handler.js')),
+      access: 'public',
+    },
+  ],
+  assets: [
+    {
+      name: 'image',
+      path: '/foo/image.jpg',
+      access: 'public',
+      content: await readFile(path.join(__dirname, 'another-dir', 'image.jpg')),
+    },
+  ]
+});
+```
+
 [More in the Docs](https://serverless-api.twilio-labs.com/classes/_twilio_labs_serverless_api.twilioserverlessapiclient.html#deployproject)
 
 ### `client.getClient(): GotClient`

packages/serverless-api/src/api/assets.ts

@@ -8,14 +8,12 @@ import {
   AssetApiResource,
   AssetList,
   AssetResource,
-  FileInfo,
   GotClient,
-  RawAssetWithPath,
+  ServerlessResourceConfig,
   Sid,
   VersionResource,
 } from '../types';
 import { uploadToAws } from '../utils/aws-upload';
-import { getPathAndAccessFromFileInfo, readFile } from '../utils/fs';
 
 const log = debug('twilio-serverless-api:assets');
 
@@ -53,7 +51,10 @@ async function createAssetResource(
  * @param {GotClient} client API client
  * @returns {Promise<AssetApiResource[]>}
  */
-export async function listAssetResources(serviceSid: string, client: GotClient) {
+export async function listAssetResources(
+  serviceSid: string,
+  client: GotClient
+) {
   try {
     const resp = await client.get(`/Services/${serviceSid}/Assets`);
     const content = (resp.body as unknown) as AssetList;
@@ -73,26 +74,23 @@ export async function listAssetResources(serviceSid: string, client: GotClient)
  * @returns {Promise<AssetResource[]>}
  */
 export async function getOrCreateAssetResources(
-  assets: FileInfo[],
+  assets: ServerlessResourceConfig[],
   serviceSid: string,
   client: GotClient
 ): Promise<AssetResource[]> {
   const output: AssetResource[] = [];
   const existingAssets = await listAssetResources(serviceSid, client);
-  const assetsToCreate: RawAssetWithPath[] = [];
+  const assetsToCreate: ServerlessResourceConfig[] = [];
 
   assets.forEach(asset => {
-    const { path: assetPath, access } = getPathAndAccessFromFileInfo(asset);
     const existingAsset = existingAssets.find(
-      x => assetPath === x.friendly_name
+      x => asset.name === x.friendly_name
     );
     if (!existingAsset) {
-      assetsToCreate.push({ ...asset, assetPath, access });
+      assetsToCreate.push(asset);
     } else {
       output.push({
         ...asset,
-        assetPath,
-        access,
         sid: existingAsset.sid,
       });
     }
@@ -101,7 +99,7 @@ export async function getOrCreateAssetResources(
   const createdAssets = await Promise.all(
     assetsToCreate.map(async asset => {
       const newAsset = await createAssetResource(
-        asset.assetPath,
+        asset.name,
         serviceSid,
         client
       );
@@ -134,7 +132,7 @@ async function createAssetVersion(
       {
         form: true,
         body: {
-          Path: asset.assetPath,
+          Path: asset.path,
           Visibility: asset.access,
         },
       }
@@ -161,22 +159,12 @@ export async function uploadAsset(
   serviceSid: string,
   client: GotClient
 ): Promise<Sid> {
-  let content: Buffer | string | undefined;
-  if (typeof asset.content !== 'undefined') {
-    content = asset.content;
-  } else if (typeof asset.path !== 'undefined') {
-    const encoding = extname(asset.path) === '.js' ? 'utf8' : undefined;
-    content = await readFile(asset.path, encoding);
-  } else {
-    throw new Error('Missing either content or path for file');
-  }
-
   const version = await createAssetVersion(asset, serviceSid, client);
   const { pre_signed_upload_url: awsData } = version;
   const awsResult = await uploadToAws(
     awsData.url,
     awsData.kmsARN,
-    content,
+    asset.content,
     asset.name
   );
   return version.sid;

packages/serverless-api/src/api/functions.ts

@@ -1,19 +1,16 @@
 /** @module @twilio-labs/serverless-api/dist/api */
 
 import debug from 'debug';
-import { extname } from 'path';
 import {
-  FileInfo,
   FunctionApiResource,
+  ServerlessResourceConfig,
   FunctionList,
   FunctionResource,
   GotClient,
-  RawFunctionWithPath,
   Sid,
   VersionResource,
 } from '../types';
 import { uploadToAws } from '../utils/aws-upload';
-import { getPathAndAccessFromFileInfo, readFile } from '../utils/fs';
 
 const log = debug('twilio-serverless-api:functions');
 
@@ -76,29 +73,21 @@ export async function listFunctionResources(
  * @returns {Promise<FunctionResource[]>}
  */
 export async function getOrCreateFunctionResources(
-  functions: FileInfo[],
+  functions: ServerlessResourceConfig[],
   serviceSid: string,
   client: GotClient
 ): Promise<FunctionResource[]> {
   const output: FunctionResource[] = [];
   const existingFunctions = await listFunctionResources(serviceSid, client);
-  const functionsToCreate: RawFunctionWithPath[] = [];
+  const functionsToCreate: ServerlessResourceConfig[] = [];
 
   functions.forEach(fn => {
-    const { path: functionPath, access } = getPathAndAccessFromFileInfo(
-      fn,
-      '.js'
-    );
-    const existingFn = existingFunctions.find(
-      f => functionPath === f.friendly_name
-    );
+    const existingFn = existingFunctions.find(f => fn.name === f.friendly_name);
     if (!existingFn) {
-      functionsToCreate.push({ ...fn, functionPath, access });
+      functionsToCreate.push({ ...fn });
     } else {
       output.push({
         ...fn,
-        functionPath,
-        access,
         sid: existingFn.sid,
       });
     }
@@ -107,7 +96,7 @@ export async function getOrCreateFunctionResources(
   const createdFunctions = await Promise.all(
     functionsToCreate.map(async fn => {
       const newFunction = await createFunctionResource(
-        fn.functionPath,
+        fn.name,
         serviceSid,
         client
       );
@@ -135,19 +124,16 @@ async function createFunctionVersion(
   client: GotClient
 ): Promise<VersionResource> {
   if (fn.access === 'private') {
-    throw new Error(`Function ${fn.functionPath} cannnot be "private". 
-Please rename the file "${fn.name}" to "${fn.name.replace(
-      '.private.',
-      '.protected.'
-    )}" or deploy it as an asset.`);
+    throw new Error(`Function ${fn.name} cannnot be "private".
+Please change it to have 'protected' access or deploy it as an asset.`);
   }
   try {
     const resp = await client.post(
       `/Services/${serviceSid}/Functions/${fn.sid}/Versions`,
       {
         form: true,
         body: {
-          Path: fn.functionPath,
+          Path: fn.path,
           Visibility: fn.access,
         },
       }
@@ -156,7 +142,7 @@ Please rename the file "${fn.name}" to "${fn.name.replace(
     return (resp.body as unknown) as VersionResource;
   } catch (err) {
     log('%O', err);
-    throw new Error(`Failed to upload Function ${fn.functionPath}`);
+    throw new Error(`Failed to upload Function ${fn.name}`);
   }
 }
 
@@ -174,22 +160,12 @@ export async function uploadFunction(
   serviceSid: string,
   client: GotClient
 ): Promise<Sid> {
-  let content: Buffer | string | undefined;
-  if (typeof fn.content !== 'undefined') {
-    content = fn.content;
-  } else if (typeof fn.path !== 'undefined') {
-    const encoding = extname(fn.path) === '.js' ? 'utf8' : undefined;
-    content = await readFile(fn.path, encoding);
-  } else {
-    throw new Error('Missing either content or path for file');
-  }
-
   const version = await createFunctionVersion(fn, serviceSid, client);
   const { pre_signed_upload_url: awsData } = version;
   const awsResult = await uploadToAws(
     awsData.url,
     awsData.kmsARN,
-    content,
+    fn.content,
     fn.name
   );
   return version.sid;

packages/serverless-api/src/types/deploy.ts

@@ -6,7 +6,7 @@ import { DeployStatus } from './consts';
 import {
   AssetResource,
   EnvironmentVariables,
-  FileInfo,
+  ServerlessResourceConfig,
   FunctionResource,
 } from './generic';
 import { Sid } from './serverless-api';
@@ -53,11 +53,11 @@ export type DeployProjectConfig = ClientConfig &
     /**
      * List of functions that should be deployed
      */
-    functions: FileInfo[];
+    functions: ServerlessResourceConfig[];
     /**
      * List of assets that should be deployed
      */
-    assets: FileInfo[];
+    assets: ServerlessResourceConfig[];
   };
 
 /**

packages/serverless-api/src/types/generic.ts

@@ -8,43 +8,47 @@ export type EnvironmentVariables = {
   [key: string]: string | undefined;
 };
 
+export type FileInfo = {
+  name: string;
+  path: string;
+};
+
 /**
- * Necessary info to deploy a function or asset
+ * Necessary info to deploy a function
  */
-export type FileInfo = {
+export type ServerlessResourceConfig = {
   /**
-   * Relative file name/path. Will be used to create the Serverless paths. Example:
-   * `example.js` => `/example`
-   * `sms/reply.protected.js` => `/sms/reply`
-   * `index.html` => `/index.html`
+   * Access for the function
    */
-  name: string;
+  access: AccessOptions;
   /**
-   * Path on file system to read the contents from
+   * Content of the uploaded function
    */
-  path?: string;
+  content: string | Buffer;
   /**
-   * Alternantive to `path` if you want to specify the content directly.
-   * Can be a string or a `Buffer` instance representing the content.
+   * Function name
    */
-  content?: string | Buffer;
-};
-
-export type RawFunctionWithPath = FileInfo & {
-  functionPath: string;
-  access: AccessOptions;
+  name: string;
+  /**
+   * Path for the serverless resource
+   * Functions: '/some-function'
+   * Assets: '/some-assets.jpg'
+   */
+  path: string;
 };
 
-export type RawAssetWithPath = FileInfo & {
-  assetPath: string;
-  access: AccessOptions;
+export type ServerlessResourceConfigWithFilePath = ServerlessResourceConfig & {
+  /**
+   * Path to the actual file on the file system.
+   */
+  filePath: string;
 };
 
-export type FunctionResource = RawFunctionWithPath & {
+export type FunctionResource = ServerlessResourceConfig & {
   sid: string;
 };
 
-export type AssetResource = RawAssetWithPath & {
+export type AssetResource = ServerlessResourceConfig & {
   sid: string;
 };
 
@@ -66,6 +70,6 @@ export type ResourcePathAndAccess = {
 };
 
 export type DirectoryContent = {
-  assets: FileInfo[];
-  functions: FileInfo[];
+  assets: ServerlessResourceConfigWithFilePath[];
+  functions: ServerlessResourceConfigWithFilePath[];
 };