@serverless/serverless-event-gateway-plugin

Event Gateway plugin for Serverless Framework

Serverless plugin that publishes your functions and subscriptions to Hosted Event Gateway.

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 Access Control section, and save it to your clipboard:

Then, grab the URL for one of your Applications:

Finally, save both of these to your serverless.yml:

# serverless.yml

custom:
  eventgateway:
    url: tenant-yourapp.slsgateway.com
    accessKey: AKmyKey1234

...

You're all set!

Example

Looking for an example to get started? Check out the Getting Started Example to deploy your first service to the Event Gateway.

Usage

1. Create a new Serverless service and change into the directory.

2. Install the plugin: (needs Node version 7+)

   $ npm install --save-dev @serverless/serverless-event-gateway-plugin
   

3. Enter the necessary plugin and config in serverless.yml:

   # serverless.yml
   
   service: my-service
   
   custom:
     eventTypes:
       http.request:
     eventgateway:
       url: myorg-app.slsgateway.com
       accessKey: <yourkey>
     # To use self-hosted Event Gateway, use the following
     #  url: http://localhost:4000
   
   plugins:
     - "@serverless/serverless-event-gateway-plugin"
   
   provider:
     name: aws
     runtime: python3.6
     stage: dev
     region: us-west-2
   ...
   

4. Wire up functions with an eventgateway event type:

   # serverless.yml
   
   functions:
     hello:
       handler: handler.hello
       events:
         - eventgateway:
             type: sync
             eventType: http.request
             path: /hello
             method: GET
     goodbye:
       handler: handler.goodbye
       events:
         - eventgateway:
             type: sync
             eventType: http.request
             path: /goodbye
             method: GET
   

5. Deploy, then invoke your function(s):

   $ sls deploy
   ....
   
   $ curl -X GET https://myspace.slsgateway.com/hello
   ...
   
   $ curl -X GET https://myspace.slsgateway.com/goodbye
   ...
   

6. View your space configuration with sls gateway dashboard:

   $ sls gateway dashboard
   
   Event Gateway
   
    space: myspace
    endpoint: https://myspace.slsgateway.com
   
   Functions
   ┌─────────────────────────────────┬───────────┬────────────────────────────────────────────────────────────────────────────────┐
   │ Function Id                     │ Region    │ ARN                                                                            │
   ├─────────────────────────────────┼───────────┼────────────────────────────────────────────────────────────────────────────────┤
   │ my-service-dev-hello            │ us-east-1 │ arn:aws:lambda:us-east-1:111111111111:function:my-service-dev-hello            │
   ├─────────────────────────────────┼───────────┼────────────────────────────────────────────────────────────────────────────────┤
   │ my-service-dev-goodbye          │ us-east-1 │ arn:aws:lambda:us-east-1:111111111111:function:my-service-dev-goodbye          │
   └─────────────────────────────────┴───────────┴────────────────────────────────────────────────────────────────────────────────┘
   
   Subscriptions
   ┌────────┬─────────────────────────────────┬────────┬───────────────────────┐
   │ Event  │ Function ID                     │ Method │ Path                  │
   ├────────┼─────────────────────────────────┼────────┼───────────────────────┤
   │ http   │ my-service-dev-hello            │ GET    │ /myspace/hello        │
   ├────────┼─────────────────────────────────┼────────┼───────────────────────┤
   │ http   │ my-service-dev-goodbye          │ GET    │ /myspace/goodbye      │
   └────────┴─────────────────────────────────┴────────┴───────────────────────┘
   

Concepts

Core concepts:

• Function: A function is a piece of compute + logic that is ready to respond to an event. Currently, functions can be AWS Lambda functions or HTTP-accessible endpoints.
• Events: Events are bits of data indicating something happened -- a user was created, a email was sent, or a client requested made an HTTP request.
• Subscriptions: Events are routed to functions via subscriptions. Subscriptions may be synchronous or asynchronous.

Event concepts:

• HTTP Request Event: In the Event Gateway, an HTTP request event is an event which represents raw HTTP request. It's especially helpful for building REST APIs or supporting legacy payloads.
• Custom Events: All non-HTTP request events are custom events. You may have multiple functions subscribed asynchronously to the same custom event.

Auth concepts:

• Space: A space is a name-spacing mechanism within the Event Gateway. All functions and subscriptions in a space are completely isolated from all other spaces. When using with the hosted Event Gateway, each Application will get its own Space with a unique domain -- https://myorg-my-app.slsgateway.com.
• Access key: The Access key is the security mechanism for a space within the hosted Event Gateway. A request must have the proper Access key to modify functions and subscriptions in a space.