@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

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

• Install the plugin: (needs Node version 7+)

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

• 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
  ...
  

• 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
  

• Deploy, then invoke your function(s):

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

• 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.