@bitblit/epsilon
Tiny adapter to simplify building API gateway Lambda APIS
Last updated a month ago by bitblit .
Apache-2.0 · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @bitblit/epsilon 
SYNC missed versions from official npm registry.

Epsilon

A tiny library to simplify serving consistent apis from Lambda with OpenAPI

TODO:

  • Discuss pros/cons of single lambda for http/batch in this document
  • path/query var checking against open api doc
  • check compression handling

How better than just using straight Node?

  • Uses typescript instead of the Godforsaken straight javascript
  • Handles route mapping (multiple ends, single lambda)
  • Uses Promises and has a top level .catch to convert to 500
  • Adds compression
  • Adds CORS
  • Adds JWT handling
  • Consistent error handling
  • Can serve static content as well
  • Kinda-persistent objects allow for optimistic caching
  • Built in support for Non-HTTP (Batch) processing via SaltMint, SNS, SQS, Email, etc

How better than using Express?

  • Doesn't have req/res architecture to fake so much easier to test
  • Much lighter

Other service

  • Environmental service
  • Simple redirects

Version 0.3.0 Release Notes

  • Remapped CRON handler to be able to filter on more than just the incoming Event name. Given the new mapping, I'd recommend just setting up an "every minute" Cloudwatch event and using filters. Filters now allow running multiple Batch processors, eg Dev/QA/Prod
  • Adding logging of request ID to output errors
  • Added default error (to allow masking of 500 errors in prod and prevent information leakage)
  • Allow optional access to the request context for handlers (esp for the request id, remaining time)

GraphQL Support (v0.1.x and above)

If you are just doing straight GraphQL then you don't really need to use Epsilon at all (I'd recommend just going with straight https://www.npmjs.com/package/apollo-server-lambda). However, if you want to start messing with GraphQL while maintaining your existing OpenAPI 3.0 endpoints, Epsilon allows you to designate a regular expression for which all matching requests are delegated to a supplied ApolloServer, bypassing Epsilon.

To do this, you must include the following libraries (They aren't marked as dependencies of Epsilon since they aren't required if you don't support GraphQL)

    "apollo-server-lambda": "2.8.1",
    "graphql": "14.4.2",

Then, in your router-config, you must set an ApolloServer and an Apollo Regex:

const typeDefs = gql`
  type Query {
    hello: String
  }
`;

// Provide resolver functions for your schema fields
const resolvers = {
  Query: {
    hello: () => 'Hello world!'
  }
};

const server: ApolloServer = new ApolloServer({ typeDefs, resolvers });

// ...

const cfg: RouterConfig = RouterUtil.openApiYamlToRouterConfig(yamlString, handlers, authorizers, options);

// ...
cfg.apolloServer = server;
cfg.apolloCreateHandlerOptions = {
  origin: '*',
  credentials: true
} as CreateHandlerOptions;
cfg.apolloRegex = new RegExp('.*graphql.*');

Usage

Using WebHandler to simplify the Lambda

You will configure a RouterConfig, and then create a WebHandler from that. Your lambda function should look like:

const handler: Handler = (event: APIGatewayEvent, context: Context, callback: Callback) => {
    const routerConfig: RouterConfig = getMyRouterConfig(); // Implement this function
    const commonHandler: WebHandler = new WebHandler(routerConfig);
    commonHandler.lambdaHandler(event, context, callback);
};

export {handler};

Using auth/AuthHandler to simplify a JWT token based auth

Your auth lambda should look like this (I here assume you are storing your encryption key in AWS System Manager so you can keep it encrypted at rest, which you definitely should be doing):


import {AuthHandler} from '@bitblit/epsilon/dist/auth/auth-handler';
import {Callback, Context, CustomAuthorizerEvent, Handler} from 'aws-lambda';
import {EnvironmentService} from '@bitblit/ratchet/dist/aws/environment-service';
import 'reflect-metadata';

const handler: Handler = (event: CustomAuthorizerEvent, context: Context, callback: Callback) => {

    EnvironmentService.getConfig('MyConfigurationName').then(cfg => {
        const commonAuth: AuthHandler = new AuthHandler('api.mycompany.com', cfg['encryptionKey']);
        commonAuth.lambdaHandler(event, context, callback);
    });
};

export {handler};

This will pass through anyone with a valid JWT token. Note that Epsilon doesn't yet support role based filtering in this version.

To create valid JWT tokens, your authentication endpoint can use the auth/WebTokenManipulator class like so (after you have verified the users principal/credentials pair) :

  // Other authentication stuff happens up here.
  const email: string = 'user-email@test.com';
  const roles: string[] = ['USER','NOT-AN-ADMIN'];
  const userData: any = {'other': 'stuff'};
  const myConfig: any = await EnvironmentService.getConfig('MyConfigurationName'); // same as above
  const encryptionKey: string =  cfg['encryptionKey'];
  const adminUser: any = null; // Set this if the user is an admin doing run-as (this is the admin user)
  const expSec: number = 3600; // How long until this token expires in seconds

  const tokenHandler: WebTokenManipulator = new WebTokenManipulator(encryptionKey, 'api.mycompany.com');
  const token: string = tokenHandler.createJWTString(email, userData, roles, expSec, admin);

Notes on adding a new gateway/stage

You'll need to auth the gateway to hit the lambda (yes, as of 2018-10-13 this is still ugly) :

aws lambda add-permission --function-name "arn:aws:lambda:us-east-1:{accountId}:function:{lambda-function-name}"
  --source-arn "arn:aws:execute-api:us-east-1:{account number}:{api id}/*/*/*"
    --principal apigateway.amazonaws.com
      --statement-id b57d8a0f-08e5-407c-9093-47d7e8e840bc
        --action lambda:InvokeFunction

And you'll need to remember to go to IAM / Keys and authorize the new stack user to use your KMS key (if you are using KMS to encrypt your config via SystemManager, which you should be doing)

Current Tags

  • 0.3.5                                ...           latest (a month ago)

122 Versions

  • 0.3.5                                ...           a month ago
  • 0.3.4                                ...           a month ago
  • 0.3.2                                ...           a month ago
  • 0.3.1                                ...           a month ago
  • 0.2.15                                ...           2 months ago
  • 0.2.14                                ...           2 months ago
  • 0.2.13                                ...           2 months ago
  • 0.2.12                                ...           2 months ago
  • 0.2.11                                ...           2 months ago
  • 0.2.10                                ...           2 months ago
  • 0.2.9                                ...           2 months ago
  • 0.2.8                                ...           2 months ago
  • 0.2.7                                ...           2 months ago
  • 0.2.6                                ...           3 months ago
  • 0.2.5                                ...           3 months ago
  • 0.2.4                                ...           3 months ago
  • 0.2.3                                ...           4 months ago
  • 0.2.2                                ...           4 months ago
  • 0.2.1                                ...           4 months ago
  • 0.1.24                                ...           4 months ago
  • 0.1.23                                ...           4 months ago
  • 0.1.22                                ...           5 months ago
  • 0.1.21                                ...           5 months ago
  • 0.1.20                                ...           7 months ago
  • 0.1.19                                ...           7 months ago
  • 0.1.18                                ...           8 months ago
  • 0.1.17                                ...           8 months ago
  • 0.1.16                                ...           8 months ago
  • 0.1.15                                ...           8 months ago
  • 0.1.14                                ...           8 months ago
  • 0.1.13                                ...           9 months ago
  • 0.1.12                                ...           9 months ago
  • 0.1.11                                ...           9 months ago
  • 0.1.10                                ...           9 months ago
  • 0.1.9                                ...           9 months ago
  • 0.1.8                                ...           9 months ago
  • 0.1.7                                ...           9 months ago
  • 0.1.6                                ...           10 months ago
  • 0.1.5                                ...           10 months ago
  • 0.1.4                                ...           10 months ago
  • 0.1.3                                ...           10 months ago
  • 0.1.2                                ...           10 months ago
  • 0.1.1                                ...           10 months ago
  • 0.0.87                                ...           10 months ago
  • 0.0.85                                ...           a year ago
  • 0.0.84                                ...           a year ago
  • 0.0.83                                ...           a year ago
  • 0.0.82                                ...           a year ago
  • 0.0.81                                ...           a year ago
  • 0.0.80                                ...           a year ago
  • 0.0.79                                ...           a year ago
  • 0.0.78                                ...           a year ago
  • 0.0.77                                ...           a year ago
  • 0.0.76                                ...           a year ago
  • 0.0.75                                ...           a year ago
  • 0.0.74                                ...           a year ago
  • 0.0.73                                ...           a year ago
  • 0.0.72                                ...           a year ago
  • 0.0.71                                ...           2 years ago
  • 0.0.70                                ...           2 years ago
  • 0.0.69                                ...           2 years ago
  • 0.0.68                                ...           2 years ago
  • 0.0.67                                ...           2 years ago
  • 0.0.66                                ...           2 years ago
  • 0.0.65                                ...           2 years ago
  • 0.0.64                                ...           2 years ago
  • 0.0.63                                ...           2 years ago
  • 0.0.62                                ...           2 years ago
  • 0.0.60                                ...           2 years ago
  • 0.0.59                                ...           2 years ago
  • 0.0.58                                ...           2 years ago
  • 0.0.57                                ...           2 years ago
  • 0.0.56                                ...           2 years ago
  • 0.0.55                                ...           2 years ago
  • 0.0.54                                ...           2 years ago
  • 0.0.53                                ...           2 years ago
  • 0.0.52                                ...           2 years ago
  • 0.0.51                                ...           2 years ago
  • 0.0.50                                ...           2 years ago
  • 0.0.49                                ...           2 years ago
  • 0.0.47                                ...           2 years ago
  • 0.0.46                                ...           2 years ago
  • 0.0.45                                ...           2 years ago
  • 0.0.44                                ...           2 years ago
  • 0.0.43                                ...           2 years ago
  • 0.0.42                                ...           2 years ago
  • 0.0.41                                ...           2 years ago
  • 0.0.40                                ...           2 years ago
  • 0.0.39                                ...           2 years ago
  • 0.0.38                                ...           2 years ago
  • 0.0.37                                ...           2 years ago
  • 0.0.36                                ...           2 years ago
  • 0.0.35                                ...           2 years ago
  • 0.0.34                                ...           2 years ago
  • 0.0.33                                ...           2 years ago
  • 0.0.32                                ...           2 years ago
  • 0.0.31                                ...           2 years ago
  • 0.0.30                                ...           2 years ago
  • 0.0.29                                ...           2 years ago
  • 0.0.28                                ...           2 years ago
  • 0.0.27                                ...           2 years ago
  • 0.0.26                                ...           2 years ago
  • 0.0.25                                ...           2 years ago
  • 0.0.24                                ...           2 years ago
  • 0.0.23                                ...           2 years ago
  • 0.0.22                                ...           2 years ago
  • 0.0.21                                ...           2 years ago
  • 0.0.20                                ...           2 years ago
  • 0.0.19                                ...           2 years ago
  • 0.0.18                                ...           2 years ago
  • 0.0.17                                ...           2 years ago
  • 0.0.16                                ...           2 years ago
  • 0.0.15                                ...           2 years ago
  • 0.0.11                                ...           2 years ago
  • 0.0.10                                ...           2 years ago
  • 0.0.9                                ...           2 years ago
  • 0.0.8                                ...           2 years ago
  • 0.0.7                                ...           2 years ago
  • 0.0.6                                ...           2 years ago
  • 0.0.5                                ...           2 years ago
  • 0.0.4                                ...           2 years ago
  • 0.0.3                                ...           2 years ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 122
Last Month 307
Dependencies (11)
Dev Dependencies (17)
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |