serverless/event-gateway-sdk

Event Gateway JavaScript SDK

Website • Docs • Community Slack • Forum • Twitter • Meetups

The Serverless Framework – Build applications on AWS Lambda and other next-gen cloud services, that auto-scale and only charge you when they run. This lowers the total cost of running and operating your apps, enabling you to build more and manage less.

The Serverless Framework is a command-line tool with an easy and approachable YAML syntax to deploy both your code and cloud infrastructure needed to make tons of serverless application use-cases. It's a multi-language framework that supports Node.js, Typescript, Python, Go, Java, and more. It's also completely extensible via over 1,000 plugins which add more serverless use-cases and workflows to the Framework.

Actively maintained by Serverless Inc.

Contents

• Features
• Quick Start
• Plugins
• Contributing
• Community
• Licensing

Features

• Hyper-Productive - Build more and manage less with serverless architectures.
• Multiple Use-Cases - Choose from tons of efficient serverless use-cases (APIs, Scheduled Tasks, Event Handlers, Streaming Data Pipelines, Web Sockets & more).
• Infra & Code - Deploys both code and infrastructure together, resulting in out-of-the-box serverless apps.
• Easy - Enjoy simple syntax to safely deploy deploy AWS Lambda functions, event sources and more without being a cloud expert.
• Multi-Language - Supports Node.js, Python, Java, Go, C#, Ruby, Swift, Kotlin, PHP, Scala, & F#
• Full Lifecycle - Manages the lifecycle of your serverless architecture (build, deploy, update, monitor, troubleshoot).
• Multi-Domains - Group domains into Serverless Services for easy management of code, resources & processes, across large projects & teams.
• Multi-Environments - Built-in support for multiple stages (e.g. development, staging, production).
• Guardrails - Loaded with automation, optimization and best practices.
• Extensible - Extend or modify the Framework and its operations via Plugins.
• Plugin Ecosystem - Extend or modify the Framework and its operations via Plugins.
• Welcoming - A passionate and welcoming community!

Quick Start

Here's how to get started quickly, as well as some recommended development workflows.

Installation

Install serverless module via NPM:

npm install -g serverless

If you don’t already have Node.js on your machine, install it first. If you don't want to install Node or NPM, you can install serverless as a standalone binary.

Creating A Service

To create your first project (known as a Serverless Framework "Service"), run the serverless command below, then follow the prompts.

# Create a new serverless project
serverless

# Move into the newly created directory
cd your-service-name

The serverless command will guide you to:

1. Create a new project
2. Configure your AWS credentials
3. Optionally set up a free Serverless Framework account with additional features.

Your new serverless project will contain a serverless.yml file. This file features simple syntax for deploying infrastructure to AWS, such as AWS Lambda functions, infrastructure that triggers those functions with events, and additional infrastructure your AWS Lambda functions may need for various use-cases. You can learn more about this in the Core Concepts documentation.

The serverless command will give you a variety of templates to choose from. If those do not fit your needs, check out the project examples from Serverless Inc. and our community. You can install any example by passing a GitHub URL using the --template-url option:

serverless --template-url=https://github.com/serverless/examples/tree/v3/...

Please note that you can use serverless or sls to run Serverless Framework commands.

Deploying

If you haven't done so already within the serverless command, you can deploy the project at any time by running:

sls deploy

The deployed AWS Lambda functions and other essential information such as API Endpoint URLs will be displayed in the command output.

More details on deploying can be found here.

Developing On The Cloud

Many Serverless Framework users choose to develop on the cloud, since it matches reality and emulating Lambda locally can be complex. To develop on the cloud quickly, without sacrificing speed, we recommend the following workflow...

To deploy code changes quickly, skip the serverless deploy command which is much slower since it triggers a full AWS CloudFormation update. Instead, deploy code and configuration changes to individual AWS Lambda functions in seconds via the deploy function command, with -f [function name in serverless.yml] set to the function you want to deploy.

sls deploy function -f my-api

More details on the deploy function command can be found here.

To invoke your AWS Lambda function on the cloud, you can find URLs for your functions w/ API endpoints in the serverless deploy output, or retrieve them via serverless info. If your functions do not have API endpoints, you can use the invoke command, like this:

sls invoke -f hello

# Invoke and display logs:
serverless invoke -f hello --log

More details on the invoke command can be found here.

To stream your logs while you work, use the sls logs command in a separate terminal window:

sls logs -f [Function name in serverless.yml] -t

Target a specific function via the -f option and enable streaming via the -t option.

Developing Locally

Many Serverless Framework users rely on local emulation to develop more quickly. Please note, emulating AWS Lambda and other cloud services is never accurate and the process can be complex. We recommend the following workflow to develop locally...

Use the invoke local command to invoke your function locally:

sls invoke local -f my-api

You can also pass data to this local invocation via a variety of ways. Here's one of them:

serverless invoke local --function functionName --data '{"a":"bar"}'

More details on the invoke local command can be found here

Serverless Framework also has a great plugin that allows you to run a server locally and emulate AWS API Gateway. This is the serverless-offline command.

More details on the serverless-offline plugins command can be found here

Monitoring, Secrets & Collaboration

If you're looking for easy, out-of-the-box monitoring, secrets management and collaboration features, sign into the Serverless Framework Dashboard. It's free!

sls login

Remove your service

If you want to delete your service, run remove. This will delete all the AWS resources created by your project and ensure that you don't incur any unexpected charges. It will also remove the service from Serverless Dashboard.

sls remove

More details on the remove command can be found here.

What's Next

Here are some helpful resources for continuing with the Serverless Framework:

• Study Serverless Framework's core concepts
• Get inspiration from these Serverless Framework templates
• Discover all of the events that can trigger Lambda functions
• Bookmark Serverless Framework's serverless.yml guide
• Search the plugins registry to extend Serverless Framework

Contributing

We love our contributors! Please read our Contributing Document to learn how you can start working on the Framework yourself.

Check out our help wanted or good first issue labels to find issues we want to move forward on with your help.

Community

• Twitter
• Community Slack
• Serverless Meetups
• Stackoverflow
• Facebook
• Contact Us

Licensing

Serverless is licensed under the MIT License.

All files located in the node_modules and external directories are externally maintained libraries used by this software which have their own licenses; we recommend you read them, as their terms may differ from the terms in the MIT License.

event-gateway-sdk's Issues

Information on EG integrations is hard to find

I'm trying to build tooling on top of the Event Gateway, but I'm unaware of the sinks that the EG can leverage and what their configuration needs are since there is no documentation on them. The EG OpenAPI is neat, but not super convenient as you have to follow a lot of the references.

Please add they types of functions the Event Gateway can interact with and what their configuration params are to this repo w/ examples.

CloudEvent object

Since the Event Gateway is CloudEvents friendly, it'd be nice to have an easy way to make a CloudEvent for use with the emit() functionality.

For example:

import {SDK, Event} from '@serverless/event-gateway-sdk';

const eventGateway = new SDK({
  url: 'http://myeventgateway.io',
  space: 'prod'
})

// Create your CloudEvent
let event = new Event({
  eventType: 'user.created',
  eventTypeVersion: "1.0",
  source: 'dashboard.serverless.com'
})

// Emit your event
eventGateway.emit(event)

Emit method does not work with sync subscription

The EG appears to return a 202 status code when the subscription is set to async and a 200 status code when the subscription is set to sync.

The SDK currently only supports a 202 response, so it doesn't work with sync subscriptions.

I tried to implement a quick fix, but ran into some other strange behavior. When you create both an async and sync subscription on the same path+method within the Event Gateway, the async subscription suddenly starts returning a 200 status code instead of a 202.

Also ran into an issue where async events are firing twice via the SDK. Ran out of time before I could figure this out.

All of this can be discovered by playing with these tests in Event Gateway & SDK, which are currently failing due to the above:

https://github.com/serverless/event-gateway-sdk/tree/support-200

updateSubscription method is missing

This appears available in the hosted Event Gateway, but this is missing from the SDK.

This method is very necessary when building tooling that uses the SDK.

Python sdk support

Hi, great project ! Is it possible to write serverless functions in python, with Event gateway plugin out of the box? And will you eventually plan to create a python sdk ? I can help.

Get / Show Specific Resource

When you have a lot of resources, listing them to find the record you are looking for is slow.

It would be faster to have getEventType(type) getSubscription(id) getFunction(id).

Enable CORS

I'm having hard time enabling CORS for my POST http endpoint. Here is my function snippet from yml

functions:
  sendMessage:
    handler: handler.send
    events:
      - eventgateway:
          type: sync
          eventType: http.request
          path: /send/message
          method: POST
          cors: true

I'm using 0.6.1 version of event-gateway-sdk. I also tried to pass back the Access-Control-Allow-Origin from my function but for OPTIONS my function wasn't getting called. I think the gateway is handling it but not sure how to set the right header via the yml file

Getting "process is undefined" error when using unpack build

In headers.js we're using process.env to extract the Event Gateway access key -->

event-gateway-sdk/lib/utils/headers.js

Line 6 in 39bc74e

const accessKey = key || process.env.EVENT_GATEWAY_ACCESS_KEY

Using process will cause browser usage to fail since it's undefined.

We should add a check here to determine in which environment we're working and skip the process.env setting of the accessKey if we're in a browser

CORS is getting set for wrong path

I was setting up CORS for my POST endpoint /send/message. Initially I tried with cors:true but what I found was that it was not setting OPTIONS in allowedMethods. So on suggestion by @alexdebrie I used the below configuration:

sendMessage:
    handler: handler.send
    events:
      - eventgateway:
          type: sync
          eventType: http.request
          path: /send/message
          method: POST
          cors:
            origins: 
              - "*"
            methods:
              - GET
              - POST
              - OPTIONS
            headers:
              - Content-Type
              - Authorization
            allowCredentials: true

Now when I hit the config endpoint:
curl -X GET https://config.slsgateway.com/v1/spaces/padmaraj-appmail/cors -H 'Authorization: Bearer '

{
  "cors": [
    {
      "space": "padmaraj-appmail",
      "corsId": "POST%2Fpadmaraj-appmail%2Fsend%2Fmessage",
      "method": "POST",
      "path": "/tenant-app/send/message",
      "allowedOrigins": [
        "*"
      ],
      "allowedMethods": [
        "GET",
        "POST",
        "OPTIONS"
      ],
      "allowedHeaders": [
        "Content-Type",
        "Authorization"
      ],
      "allowCredentials": true,
      "metadata": {
        "service": "send-notification",
        "stage": "dev"
      }
    }
  ]
}

the path for which CORS is set is for /tenant-app/send/message while the URL that is configured on the gateway(which I was able to hit to get results) is /send/message.
I have 2 questions:

1. Is there a way to make CORS: true to include OPTIONS method also?
2. How can tweak the above configuration so that it sets the path without the tenant and the app name?
   Any help is highly appreciated!

Follow proper casing for API key config parameter

Right now we follow camelCase, however the API key config follows lower case which might introduce confusion.

I'd propose to change this from apikey to apiKey.

Add ability to specify path and/or additional headers for "emit" request.

Subscriptions are set up on a path, so events may need to be emitted on a path.

Further, a user may want to include additional headers with the emit() request, such as an Authorization header used for Auth.

A proposed update to the emit() signature could be:

eventGateway.emit(<CloudEvents object>, <Options>)

The usage would look like:

eventGateway.emit({
  eventID: '1',
  eventType: 'user.created',
  cloudEventsVersion: '0.1',
  source: '/services/users',
  contentType: 'application/json',
  data: {
    userID: 'foo'
  }}, {
  path: /users,
  headers: {
    "Authorization": "Bearer 1234"
  }
})

Golang SDK support

I'm sure you guys are already thinking about this, but for those of us who have chosen Golang for our serverless applications, adoption of the event gateway wont be possible until there is a Golang SDK...

Cannot set CORS configuration. Error will also not parse.

SDK Method:

createCORS

Params:

{
    method: 'POST',
    path: '/ac360-webappdemo/',
    allowedOrigins: ['*'],
    allowedMethods: ['POST', 'GET', 'PUT', 'DELETE']
}

Error:

Error: Failed to create CORS configuration and couldn't parse error body.

Bug: Invoking functions seems to be broken.

I get the following error when I try to invoke a function with the invoke method:

Failed to invoke function eg-test due the error: function or subscription not found

I've confirmed that both the function and the subscription exists by running the listFunctions and listSubscriptions methods.

Wrong url set with multiple applications

I initially had Application appmail. I deployed to AWS with this app. Later I decided to create a new application sendmail. Now when I created and deployed the app for some reason the url that was set up was against the first app appmail.