Merge branch 'master' into add-tests

Author: swyxio

.github/stale.yml

@@ -20,7 +20,7 @@ exemptProjects: false
 exemptMilestones: false
 
 # Label to use when marking as stale
-staleLabel: wontfix
+staleLabel: stale
 
 # Comment to post when marking as stale. Set to `false` to disable
 markComment: >

README.md

@@ -1,41 +1,55 @@
-## Netlify Lambda CLI
+## Netlify Lambda
 
-This is a small CLI tool that helps with building or serving lambdas built with a simple webpack/babel setup.
+This is an optional tool that helps with building or locally developing [Netlify Functions](https://www.netlify.com/docs/functions/) with a simple webpack/babel build step.
 
-The goal is to make it easy to work with Lambda's with modern ES6 without being dependent on having the most state of the art node runtime available in the final deployment environment and with a build that can compile all modules into a single lambda file.
-
-Since v1.0.0 the dependencies were upgraded to Webpack 4 and Babel 7.
+The goal is to make it easy to write Lambda's with transpiled JS/Typescipt features and imported modules.
 
 ## Installation
 
-**We recommend installing locally** rather than globally: `yarn add -D netlify-lambda`. This will ensure your build scripts don't assume a global install which is better for your CI/CD (for example with Netlify's buildbot).
+**We recommend installing locally** rather than globally: 
+
+```bash
+yarn add -D netlify-lambda
+```
+
+This will ensure your build scripts don't assume a global install which is better for your CI/CD (for example with Netlify's buildbot).
+
+If you don't have a [`netlify.toml`](https://www.netlify.com/docs/netlify-toml-reference/) file, you'll need one ([example](https://github.com/netlify/create-react-app-lambda/blob/master/netlify.toml)). Define the `functions` field where the functions will be built to and served from, e.g. 
+
+```toml
+# example netlify.toml
+[build]
+  command = "yarn build"
+  functions = "lambda" #  netlify-lambda reads this
+  publish = "build"
+```
 
 ## Usage
 
-Netlify lambda installs two commands:
+We expose two commands:
 
 ```
 netlify-lambda serve <folder>
 netlify-lambda build <folder>
 ```
 
-**IMPORTANT**: Both commands depend on a `netlify.toml` file being present in your project and configuring functions for deployment.
+At a high level, `netlify-lambda` takes a source folder (e.g. `src/lambda`, specified in your command) and outputs it to a built folder, (e.g. `built-lambda`, specified in your `netlify.toml` file).
 
-The `serve` function will start a dev server and a file watcher for the specified folder and route requests to the relevant function at:
+The `build` function will run a single build of the functions in the folder.
+
+The `serve` function will start a dev server for the source folder and route requests with a `.netlify/functions/` prefix, with a default port of `9000`:
 
 ```
-http://localhost:9000/hello -> folder/hello.js (must export a handler(event, context callback) function)
+folder/hello.js -> http://localhost:9000/.netlify/functions/hello
 ```
 
-The `build` function will run a single build of the functions in the folder.
+It also watches your files and restarts the dev server on change. Note: if you add a new file you should kill and restart the process to pick up the new file.
 
-There are additional options, introduced later:
-```bash
--h --help
--c --config
--p --port
--s --static
-```
+**IMPORTANT**: 
+
+- You need a [`netlify.toml`](https://www.netlify.com/docs/netlify-toml-reference/) file with a `functions` field.
+- Every function needs to be a top-level js/ts/mjs file. You can have subfolders inside the `netlify-lambda` folder, but those are only for supporting files to be imported by your top level function.
+- Function signatures follow the [AWS event handler](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html) syntax but must be named `handler`. [We use Node v8](https://www.netlify.com/blog/2018/04/03/node.js-8.10-now-available-in-netlify-functions/) so `async` functions **are** supported ([beware common mistakes](https://serverless.com/blog/common-node8-mistakes-in-lambda/)!). Read [Netlify Functions docs](https://www.netlify.com/docs/functions/#javascript-lambda-functions) for more info.
 
 ## Using with `create-react-app`, Gatsby, and other development servers
 
@@ -53,9 +67,10 @@ When your function is deployed on Netlify, it will be available at `/.netlify/fu
 
 Say you are running `webpack-serve` on port 8080 and `netlify-lambda serve` on port 9000. Mounting `localhost:9000` to `/.netlify/functions/` on your `webpack-serve` server (`localhost:8080/.netlify/functions/`) will closely replicate what the final production environment will look like during development, and will allow you to assume the same function url path in development and in production.
 
-- If you are using with `create-react-app`, see [netlify/create-react-app-lambda](https://github.com/netlify/create-react-app-lambda/blob/f0e94f1d5a42992a2b894bfeae5b8c039a177dd9/src/setupProxy.js) for an example of how to do this with `create-react-app`. [setupProxy is partially documented in the CRA docs](https://facebook.github.io/create-react-app/docs/proxying-api-requests-in-development#configuring-the-proxy-manually).
-- If you are using Gatsby, see [their Advanced Proxying docs](https://www.gatsbyjs.org/docs/api-proxy/#advanced-proxying). This is implemented in the [JAMstack Hackathon Starter](https://github.com/sw-yx/jamstack-hackathon-starter).
+- If you are using with `create-react-app`, see [netlify/create-react-app-lambda](https://github.com/netlify/create-react-app-lambda/blob/f0e94f1d5a42992a2b894bfeae5b8c039a177dd9/src/setupProxy.js) for an example of how to do this with `create-react-app`. [setupProxy is partially documented in the CRA docs](https://facebook.github.io/create-react-app/docs/proxying-api-requests-in-development#configuring-the-proxy-manually). You can also learn how to do this from scratch in a video: https://www.youtube.com/watch?v=3ldSM98nCHI 
+- If you are using Gatsby, see [their Advanced Proxying docs](https://www.gatsbyjs.org/docs/api-proxy/#advanced-proxying). This is implemented in the [JAMstack Hackathon Starter](https://github.com/sw-yx/jamstack-hackathon-starter), and here is an accompanying blogpost: [Turning the Static Dynamic: Gatsby + Netlify Functions + Netlify Identity](https://www.gatsbyjs.org/blog/2018-12-17-turning-the-static-dynamic/).
 - If you are using Next.js, see [this issue for how to proxy](https://github.com/netlify/netlify-lambda/pull/28#issuecomment-439675503).
+- If you are using Vue CLI, you may just use https://github.com/netlify/vue-cli-plugin-netlify-lambda/.
 - If you are using with Angular CLI, see the instructions below.
 
 [Example webpack config](https://github.com/imorente/netlify-functions-example/blob/master/webpack.development.config):
@@ -74,8 +89,6 @@ module.exports = {
 };
 ```
 
-The serving port can be changed with the `-p`/`--port` option.
-
 <details>
   <summary>
 **Using with `Angular CLI`**
@@ -137,7 +150,9 @@ The additional webpack config will be merged into the default config via [webpac
 
 The default webpack configuration uses `babel-loader` with a [few basic settings](https://github.com/netlify/netlify-lambda/blob/master/lib/build.js#L19-L33).
 
-However, if any `.babelrc` is found in the directory `netlify-lambda` is run from, it will be used instead of the default one. If you need to run different babel versions for your lambda and for your app, [check this issue](https://github.com/netlify/netlify-lambda/issues/34) to override your webpack babel-loader.
+However, if any `.babelrc` is found in the directory `netlify-lambda` is run from, or [folders above it](https://github.com/netlify/netlify-lambda/pull/92) (useful for monorepos), it will be used instead of the default one.
+
+If you need to run different babel versions for your lambda and for your app, [check this issue](https://github.com/netlify/netlify-lambda/issues/34) to override your webpack babel-loader.
 
 ### Use with TypeScript
 
@@ -176,6 +191,23 @@ You may also want to add `typescript @types/node @types/aws-lambda`.
 
 3. (Optional) if you have `@types/aws-lambda` installed, your lambda functions can use the community typings for `Handler, Context, Callback`. See the typescript instructions in [create-react-app-lambda](https://github.com/netlify/create-react-app-lambda/blob/master/README.md#typescript) for an example.
 
+Check https://github.com/sw-yx/create-react-app-lambda-typescript for a CRA + Lambda full Typescript experience.
+
+## CLI flags/options
+
+There are additional CLI options:
+
+```bash
+-h --help
+-c --config
+-p --port
+-s --static
+```
+
+### --port option
+
+The serving port can be changed with the `-p`/`--port` option.
+
 ### --static option
 
 If you need an escape hatch and are building your lambda in some way that is incompatible with our build process, you can skip the build with the `-s` or `--static` flag. [More info here](https://github.com/netlify/netlify-lambda/pull/62).
@@ -193,15 +225,38 @@ Don't forget to search our issues in case someone has run into a similar problem
 
 ## Netlify Identity
 
-Netlify Identity is [not supported at the moment](https://github.com/netlify/netlify-lambda/issues/51) inside `netlify-lambda` function emulation, but for now you can [read the docs](https://www.netlify.com/docs/functions/#identity-and-functions) on how they should work.
+Make sure to [read the docs](https://www.netlify.com/docs/functions/#identity-and-functions) on how Netlify Functions and Netlify Identity work together. Basically you have to make your request with an `authorization` header and a `Bearer` token with your Netlify Identity JWT supplied. You can get this JWT from any of our Identity solutions from [gotrue-js](https://github.com/netlify/gotrue-js) to [netlify-identity-widget](https://github.com/netlify/netlify-identity-widget).
+
+Since for practical purposes we cannot fully emulate Netlify Identity locally, we provide [simple JWT decoding inside the `context` of your function](https://github.com/netlify/netlify-lambda/pull/57). This will give you back the `user` info you need to work with.
+
+Minor note: For the `identity` field, since we are not fully emulating Netlify Identity, we can't give you details on the Identity instance, so we give you [unambiguous strings](https://github.com/netlify/netlify-lambda/blob/master/lib/serve.js#L87) so you know not to rely on it locally: `NETLIFY_LAMBDA_LOCALLY_EMULATED_IDENTITY_URL` and `NETLIFY_LAMBDA_LOCALLY_EMULATED_IDENTITY_TOKEN`. In production, of course, Netlify Functions will give you the correct `identity.url` and `identity.token` fields. We find we dont use this info often in our functions so it is not that big of a deal in our judgment.
+
+## Example functions and Tutorials
+
+You can do a great deal with lambda functions! Here are some examples for inspiration:
+
+- Basic Netlify Functions tutorial: https://flaviocopes.com/netlify-functions/
+- Netlify's list of Function examples: https://functions-playground.netlify.com/ ([Even more in the README](https://github.com/netlify/functions))
+- Slack Notifications: https://css-tricks.com/forms-auth-and-serverless-functions-on-gatsby-and-netlify/#article-header-id-9
+- URL Shortener: https://www.netlify.com/blog/2018/03/19/create-your-own-url-shortener-with-netlifys-forms-and-functions/
+- Gatsby + Netlify Identity + Functions: [Turning the Static Dynamic: Gatsby + Netlify Functions + Netlify Identity](https://www.gatsbyjs.org/blog/2018-12-17-turning-the-static-dynamic/)
+- Raymond Camden's [Adding Serverless Functions to Your Netlify Static Site](https://www.raymondcamden.com/2019/01/08/adding-serverless-functions-to-your-netlify-static-site)
+- Travis Horn's [Netlify Lambda Functions from Scratch](https://travishorn.com/netlify-lambda-functions-from-scratch-1186f61c659e)
+- [**Submit your blogpost here!**](https://github.com/netlify/netlify-lambda/issues/new)
+
+These libraries pair very well for extending your functions capability:
+
+- Middleware: https://github.com/middyjs/middy
+- GraphQL: https://www.npmjs.com/package/apollo-server-lambda
+- [Any others to suggest?](https://github.com/netlify/netlify-lambda/issues/new)
 
 ## Other community approaches
 
 If you wish to serve the full website from lambda, [check this issue](https://github.com/netlify/netlify-lambda/issues/36).
 
 If you wish to run this server for testing, [check this issue](https://github.com/netlify/netlify-lambda/issues/49).
 
-If you wish to emulate more Netlify functionality locally, [check this repo](https://github.com/8eecf0d2/netlify-local).
+If you wish to emulate more Netlify functionality locally, check this repo: https://github.com/8eecf0d2/netlify-local. We are considering merging the projects [here](https://github.com/netlify/netlify-lambda/issues/75).
 
 All of the above are community maintained and not officially supported by Netlify.
 

bin/cmd.js

@@ -58,4 +58,21 @@ program
       });
   });
 
+// error on unknown commands
+// ref: https://github.com/tj/commander.js#custom-event-listeners
+program
+  .on('command:*', function () {
+    console.error('Invalid command: %s\nSee --help for a list of available commands.', program.args.join(' '));
+    process.exit(1);
+  });
+
 program.parse(process.argv);
+
+// check if no command line args are provided
+// ref: https://github.com/tj/commander.js/issues/7#issuecomment-32448653
+var NO_COMMAND_SPECIFIED = program.args.length === 0;
+
+if (NO_COMMAND_SPECIFIED) {
+  // user did not supply args, so show --help
+  program.help();
+}

lib/build.js

@@ -13,11 +13,27 @@ function getBabelTarget(envConfig) {
   return unknown ? "6.10" : current.replace(/^nodejs/, "");
 }
 
+function haveBabelrc(functionsDir) {
+  const cwd = process.cwd();
+
+  return (
+    fs.existsSync(path.join(cwd, ".babelrc")) ||
+    functionsDir.split("/").reduce((foundBabelrc, dir) => {
+      if (foundBabelrc) return foundBabelrc;
+
+      const indexOf = functionsDir.indexOf(dir);
+      const dirToSearch = functionsDir.substr(0, indexOf);
+
+      return fs.existsSync(path.join(cwd, dirToSearch, ".babelrc"));
+    }, false)
+  );
+}
+
 function webpackConfig(dir, additionalConfig) {
   var config = conf.load();
   var envConfig = conf.loadContext(config).environment;
   var babelOpts = { cacheDirectory: true };
-  if (!fs.existsSync(path.join(process.cwd(), ".babelrc"))) {
+  if (!haveBabelrc(dir)) {
     babelOpts.presets = [
       ["@babel/preset-env", { targets: { node: getBabelTarget(envConfig) } }]
     ];
@@ -48,7 +64,7 @@ function webpackConfig(dir, additionalConfig) {
   var webpackConfig = {
     mode: "production",
     resolve: {
-      extensions: ['.wasm', '.mjs', '.js', '.json', '.ts']
+      extensions: [".wasm", ".mjs", ".js", ".json", ".ts"]
     },
     module: {
       rules: [

lib/serve.js

@@ -4,6 +4,7 @@ var expressLogging = require("express-logging");
 var queryString = require("querystring");
 var path = require("path");
 var conf = require("./config");
+var jwtDecode = require("jwt-decode")
 
 function handleErr(err, response) {
   response.statusCode = 500;
@@ -76,7 +77,19 @@ function createHandler(dir, static) {
     };
 
     var callback = createCallback(response);
-    var promise = handler.handler(lambdaRequest, {}, callback);
+    
+    // inject a client context based on auth header https://github.com/netlify/netlify-lambda/pull/57
+    let clientContext = {}
+    if (request.headers['authorization']) {
+      const parts = request.headers['authorization'].split(' ')
+      if (parts.length === 2 && parts[0] === 'Bearer') {
+        clientContext = {
+          identity: { url: 'NETLIFY_LAMBDA_LOCALLY_EMULATED_IDENTITY_URL', token: 'NETLIFY_LAMBDA_LOCALLY_EMULATED_IDENTITY_TOKEN' },
+          user: jwtDecode(parts[1])
+        }
+      }
+    }
+    var promise = handler.handler(lambdaRequest, { clientContext }, callback);
     promiseCallback(promise, callback);
   };
 }

package.json

@@ -30,6 +30,7 @@
     "commander": "^2.17.1",
     "express": "^4.16.3",
     "express-logging": "^1.1.1",
+    "jwt-decode": "^2.2.0",
     "toml": "^2.3.3",
     "webpack": "^4.17.1",
     "webpack-merge": "^4.1.4"

yarn.lock

@@ -3384,16 +3384,6 @@ json5@^0.5.0, json5@^0.5.1:
   version "0.5.1"
   resolved "https://registry.yarnpkg.com/json5/-/json5-0.5.1.tgz#1eade7acc012034ad84e2396767ead9fa5495821"
 
-jsprim@^1.2.2:
-  version "1.4.1"
-  resolved "https://registry.yarnpkg.com/jsprim/-/jsprim-1.4.1.tgz#313e66bc1e5cc06e438bc1b7499c2e5c56acb6a2"
-  integrity sha1-MT5mvB5cwG5Di8G3SZwuXFastqI=
-  dependencies:
-    assert-plus "1.0.0"
-    extsprintf "1.3.0"
-    json-schema "0.2.3"
-    verror "1.10.0"
-
 kind-of@^3.0.2, kind-of@^3.0.3, kind-of@^3.2.0:
   version "3.2.2"
   resolved "https://registry.yarnpkg.com/kind-of/-/kind-of-3.2.2.tgz#31ea21a734bab9bbb0f32466d893aea51e4a3c64"