sebito91 / event-gateway-getting-started

Walkthrough application for using the Event Gateway. -- https://www.serverless.com

Getting Started with the Event Gateway

This example shows a simple way to deploy a service to the Event Gateway. It uses the hosted version provided by Serverless, Inc. -- sign up here!

This service will deploy three functions:

• createUser: an HTTP endpoint for creating and storing a User in a DynamoDB table;
• getUser: an HTTP endpoint for retrieving a User from DynamoDB; and
• addUserToCRM: a function that is triggered by a user.created event and stores new users in a CRM system.

The createUser function allows you to create a new User by sending a JSON payload to /users, and the getUser function lets you retrieve that User by making a GET request to /users/{id}.

In the createUser function, we're using the Event Gateway SDK to emit a custom event of user.created into the Event Gateway. You can then subscribe functions to react to this custom event. The addUserToCRM function is subscribed to this event as an example -- imagine a Marketing department that wants to store newly-created Users in a CRM.

Let's get started!

Setup

This is best used with the hosted version of the Event Gateway provided by Serverless, Inc. as a fully-managed service.

After you create an account, you'll need two things: an Access Key and an Application URL.

Get an Access Key in the secure > access keys section, and set it as an environment variable:

$ export EVENT_GATEWAY_ACCESS_KEY=<paste your key here>

Then, grab the URL for one of your applications (develop > applications section) and save it as an environment variable:

$ export EVENT_GATEWAY_APPLICATION=<paste your application here>

You're all set!

Usage

1. Clone this repository and install the packages:

   $ git clone https://github.com/serverless/event-gateway-getting-started.git
   $ cd event-gateway-getting-started
   $ npm install
   $ npm install -g serverless

2. Set the environment variables as described in the Setup section above.

3. Deploy your service

   $ serverless deploy
   ...
   Service Information
   service: eg-quickstart
   stage: dev
   region: us-east-1
   stack: eg-quickstart-dev
   api keys:
     None
   endpoints:
     None
   functions:
     getUser: eg-quickstart-dev-getUser
     createUser: eg-quickstart-dev-createUser
     addUserToCRM: eg-quickstart-dev-addUserToCRM
   
   Event Gateway Plugin
   EventGateway: Event type "http.request" created.
   EventGateway: Event type "user.created" created.
   EventGateway: Function "createUser" registered. (ID: eg-quickstart-dev-createUser)
   EventGateway: Function "getUser" registered. (ID: eg-quickstart-dev-getUser)
   EventGateway: Function "addUserToCRM" registered. (ID: eg-quickstart-dev-addUserToCRM)
   EventGateway: Function "createUser" subscribed to "http.request" event.
   EventGateway: Function "addUserToCRM" subscribed to "user.created" event.
   EventGateway: Function "getUser" subscribed to "http.request" event.

4. Create a new user by hitting the createUser endpoint:

   $ APP="<appURL>"
   $ curl -X POST -H "Content-Type: application/json" https://${APP}/users \
       --data '{
       	"id": "10",
       	"firstName": "Donald",
       	"lastName": "Duck",
       	"email": "[e-mail]"
       }'
   {"id":10,"firstName":"Donald","lastName":"Duck","email":"[e-mail]"}

5. You can now retrieve your user by using the getUser endpoint:

   $ APP="<appURL>"
   $ curl -X GET https://${APP}/users/10
   {"id":"10","email":"[e-mail]","firstName":"Donald","lastName":"Duck"}

6. In your createUser code, it emits a user.created event to the Event Gateway, which triggers the addUserToCRM function. You can check the logs for that function to see that it ran:

   $ sls logs -f addUserToCRM
   START RequestId: 0ccf992b-39dc-11e8-b35d-735763392802 Version: $LATEST
   2018-04-06 20:49:50.917 (+00:00)	0ccf992b-39dc-11e8-b35d-735763392802
   Received user.created event with user:
   { email: '[e-mail]',
     firstName: 'Donald',
     id: '10',
     lastName: 'Duck' }
   END RequestId: 0ccf992b-39dc-11e8-b35d-735763392802
   REPORT RequestId: 0ccf992b-39dc-11e8-b35d-735763392802 Duration: 5.15 ms	Billed Duration: 100 ms 	Memory Size: 1024 MB	Max Memory Used: 32 MB

   Nice! We can see our logs from the triggered function.

7. If you'd like to test emitting events into the Gateway, you can use the sls gateway emit command:

   $ sls gateway emit --event "user.created" --data "$(cat event.json)"
   Event emitted: user.created
   Run `serverless logs -f <functionName>` to verify your subscribed function was triggered.

   Again, you can check your logs with sls logs -f addUserToCRM to check the behavior of your function.

Event Gateway Concepts

Now that you know the basics of using the Event Gateway, let's cover some concepts:

• Events: Events are bits of data that indicate something happened. This could be an HTTP request ("a client requested the resource at path /users/15") or it could be a custom event emitted from your application ("a user was created with the following details...").

• Functions: Functions are bits of logic that operate on individual events. A function may be a Lambda function that reads the event and posts a message in Slack. It could also be a "connector" function that sends your event directly to another system, such as into Firehose for analytics or into SQS for transactional message processing.

• Subscriptions: Subscriptions tie functions and events together. Think "If this, then that" for data and compute. "If I get a user.created event, then execute my function to save a new user to our CRM."

• Space: Spaces are a logical unit of isolation within the Event Gateway. Your functions and subscriptions are registered within a particular space and may only interact with other elements in their space.

  With the hosted Event Gateway, you will create Apps. Each App receives a fully-qualified domain name to be used with the Event Gateway, such as https://myorg-dev.slsgateway.com. Each App maps to a Space within the Event Gateway and will be fully isolated from all other Apps.

Additional Resources:

• Event Gateway Repository
• Event Gateway plugin for the Serverless Framework
• Event Gateway SDK for interacting with the Event Gateway in your application code