Merge pull request #2 from probot/update-readme

Update to Probot 7 and add readme

Author: tcbyrd

README.md

@@ -1,19 +1,31 @@
-## Lambda Handler for Probot
+## AWS Lambda Extension for Probot
+A [Probot](https://github.com/probot/probot) extension to make it easier to run your Probot Apps in AWS Lambda.
 
-
-
-<details>
-<summary>TODO: Not published yet. Coming soon.</summary>
+## Usage
 
 ```shell
 $ npm install @probot/serverless-lambda
 ```
 
 ```javascript
 # handler.js
-const serverless = require('@probot/serverless-lambda');
-const plugin = require('./')
-module.exports.probot = serverless(plugin)
+const serverless = require('@probot/serverless-lambda')
+const appFn = require('./')
+module.exports.probot = serverless(appFn)
 ```
 
-</details>
+## Configuration
+This package moves the functionality of `probot run` into a handler suitable for usage on AWS Lambda + API Gateway. Follow the documentation on [Environment Configuration](https://probot.github.io/docs/configuration/) to setup your app's environment variables. You can add these to `.env`, but for security reasons you may want to use the [AWS CLI](https://aws.amazon.com/cli/) or [Serverless Framework](https://github.com/serverless/serverless) to set Environment Variables for the function so you don't have to include any secrets in the deployed package.
+
+For the private key, since AWS environment variables cannot be multiline strings, you could [Base64 encode](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) the `.pem` file you get from the GitHub App or use [KMS](https://aws.amazon.com/kms/) to encrypt and store the key.
+
+## Differences from `probot run`
+
+#### Local Development
+Since Lambda functions do not start a normal node process, the best way we've found to test this out locally is to use [`serverless-offline`](https://github.com/dherault/serverless-offline). This plugin for the serverless framework emulates AWS Lambda and API Gateway on your local machine, allowing you to continue working from `https://localhost:3000/probot` before deploying your function to AWS.
+
+#### Long running tasks
+Some Probot Apps that depend on long running processes or intervals will not work with this extension. This is due to the inherent architecture of serverless functions, which are designed to respond to events and stop running as quickly as possible. For longer running apps we recommend using [other deployment options](https://probot.github.io/docs/deployment).
+
+#### Only responds to Webhooks from GitHub
+This extension is designed primarily for receiving webhooks from GitHub and responding back as a GitHub App. If you are using [HTTP Routes](https://probot.github.io/docs/http/) in your app to serve additional pages, you should take a look at [`serverless-http`](https://github.com/dougmoscrop/serverless-http), which can be used with Probot's [express server](https://github.com/probot/probot/blob/master/src/server.ts) by wrapping `probot.server`.

index.js

@@ -1,10 +1,13 @@
-const createProbot = require('probot');
+const { Application } = require('probot')
 const { resolve } = require('probot/lib/resolver')
 const { findPrivateKey } = require('probot/lib/private-key')
 const { template } = require('./views/probot')
 
+let app
+let probot
+
 const loadProbot = (plugin) => {
-  const probot = createProbot({
+  app = app || new Application({
     id: process.env.APP_ID,
     secret: process.env.WEBHOOK_SECRET,
     cert: findPrivateKey()
@@ -14,16 +17,13 @@ const loadProbot = (plugin) => {
     plugin = resolve(plugin)
   }
 
-  probot.load(plugin)
+  app.load(plugin)
 
-  return probot
+  return app
 }
 
-
 module.exports.serverless = (plugin) => {
-
   return async (event, context) => {
-
     // 🤖 A friendly homepage if there isn't a payload
     if (event.httpMethod === 'GET' && event.path === '/probot') {
       const res = {
@@ -37,7 +37,7 @@ module.exports.serverless = (plugin) => {
     }
 
     // Otherwise let's listen handle the payload
-    const probot = loadProbot(plugin)
+    probot = probot || loadProbot(plugin)
 
     // Ends function immediately after callback
     context.callbackWaitsForEmptyEventLoop = false
@@ -53,25 +53,31 @@ module.exports.serverless = (plugin) => {
     console.log(`Received event ${e}${event.body.action ? ('.' + event.body.action) : ''}`)
     if (event) {
       try {
-        await probot.receive({
+        await app.receive({
           event: e,
           payload: event.body
         })
         const res = {
           statusCode: 200,
           body: JSON.stringify({
-            message: 'Hi Node8!'
+            message: `Received ${e}.${event.body.action}`
           })
         }
         return context.done(null, res)
       } catch (err) {
         console.error(err)
-        return err
+        return context.done(null, {
+          statusCode: 500,
+          body: JSON.stringify(err)
+        })
       }
     } else {
       console.error({ event, context })
-      callback('unknown error')
+      context.done(null, 'unknown error')
     }
+    return context.done(null, {
+      statusCode: 200,
+      body: 'Nothing to do.'
+    })
   }
-
 }