https://github.com/serverless/serverless-event-gateway-plugin
Event Gateway plugin for Serverless Framework
https://github.com/serverless/serverless-event-gateway-plugin
api-gateway event-gateway serverless
Last synced: about 2 months ago
JSON representation
Event Gateway plugin for Serverless Framework
- Host: GitHub
- URL: https://github.com/serverless/serverless-event-gateway-plugin
- Owner: serverless
- License: apache-2.0
- Created: 2018-01-29T12:16:21.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-11-09T12:45:33.000Z (over 6 years ago)
- Last Synced: 2024-10-28T17:36:40.679Z (7 months ago)
- Topics: api-gateway, event-gateway, serverless
- Language: JavaScript
- Homepage:
- Size: 528 KB
- Stars: 29
- Watchers: 34
- Forks: 7
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Event Gateway plugin for Serverless Framework
Serverless plugin that publishes your functions and subscriptions to Hosted Event Gateway.
[](https://travis-ci.org/serverless/serverless-event-gateway-plugin)
[](https://snyk.io/test/github/serverless/serverless-event-gateway-plugin)
## Setup
This is best used with the [hosted version of the Event Gateway](https://dashboard.serverless.com/) 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`:
```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**](https://github.com/serverless/event-gateway-getting-started) 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+)
```bash
$ npm install --save-dev @serverless/serverless-event-gateway-plugin
```
3. Enter the necessary plugin and config in `serverless.yml`:
```yml
# serverless.yml
service: my-service
custom:
eventTypes:
http.request:
eventgateway:
url: myorg-app.slsgateway.com
accessKey:
# 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:
```yml
# 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):
```bash
$ 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`:
```bash
$ 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*](https://github.com/serverless/event-gateway/blob/master/docs/subscription-types.md).
**Event concepts:**
- **HTTP Request Event:** In the Event Gateway, an [HTTP request event](https://github.com/serverless/event-gateway/blob/master/docs/api.md#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.