@the_pixelport/aws-lambda-graphql

# aws-lambda-graphql [![CircleCI](https://img.shields.io/circleci/project/github/michalkvasnicak/aws-lambda-graphql/master.svg?style=flat-square)](https://circleci.com/gh/michalkvasnicak/aws-lambda-graphql) [![aws-lambda-graphql package version](https://img.shields.io/npm/v/aws-lambda-graphql?color=green&label=aws-lambda-graphql&style=flat-square)](https://www.npmjs.com/package/aws-lambda-graphql) **⚠️ This documentation is currently for 1.0.0-alpha.X package which supports only [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) and drops the legacy protocol and client support! To use old version that supports legacy protocol and client see the link 0.13.0 below.** [**📖Documentation for `aws-lambda-graphql0.13.0`**](https://github.com/michalkvasnicak/aws-lambda-graphql/tree/aws-lambda-graphql%400.13.0) Use [Apollo Server Lambda](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-lambda) with GraphQL subscriptions over WebSocket (AWS API Gateway v2). With this library you can do: - same things as with [apollo-server-lambda](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-lambda) by utiizing AWS API Gateway v1 - GraphQL subscriptions over WebSocket by utilizing AWS API Gateway v2 and [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) ## Table of contents - [Installation](#installation) - [Usage](#usage) - [API](#api) - [Examples](#examples) ## Installation ```console yarn add aws-lambda-graphql graphql graphql-subscriptions # or npm install aws-lamda-graphql graphql graphql-subscriptions ``` ## Usage There is a [quick start guide](https://github.com/michalkvasnicak/aws-lambda-graphql#quick-start). ## API ### `Server` Creates an [Apollo Lambda server](https://www.npmjs.com/package/apollo-server-lambda). #### Options All options from Apollo Lambda Server and - **connectionManager** (`IConnectionManager`, `required`) - **eventProcessor** (`IEventProcessor`, `required`) - **onError** (`(err: any) => void`, `optional`) - use to log errors from websocket handler on unknown error - **subscriptionManager** (`ISubscriptionManager`, `required`) - **subscriptions** (`optional`) - **`onWebsocketConnect(connection: IConnection, event: APIGatewayWebSocketEvent, context: LambdaContext): Promise<boolean|object> | object | boolean`** (`optional`) - onWebsocketConnect is called when the Websocket connection is initialized ($connect route). Return an object to set a context to your connection object saved in the database e.g. for saving authentication details. This is especially useful to get authentication details (API GW authorizers only run in $connect route) - **`onConnect(messagePayload: object, connection: IConnection, event: APIGatewayWebSocketEvent, context: LambdaContext): Promise<boolean|object> | object | boolean`** (`optional`) - onConnect is called when the GraphQL connection is initialized (connection_init message). Return an object to set a context to your connection object saved in the database e.g. for saving authentication details. NOTE: This is not the websocket $connect route, see onWebsocketConnect for the $connect route. - **`onOperation(message: OperationRequest, params: ExecutionParams, connection: IConnection): Promise<ExecutionParams>|ExecutionParams`** (`optional`) - **`onOperationComplete(connection: IConnection, operationId: string): void`** (`optional`) - **`onDisconnect(connection: IConnection): void`** (`optional`) - **waitForInitialization** (`optional`) - if connection is not initialized on GraphQL operation, wait for connection to be initialized or throw prohibited connection error. If `onConnect` is specified then we wait for initialization otherwise we don't wait. (this is usefull if you're performing authentication in `onConnect`). - **retryCount** (`number`, `optional`, `default 10`) - how many times should we try to check the connection state? - **timeout** (`number`, `optional`, `default 50ms`) - how long should we wait (in milliseconds) until we try to check the connection state again? - **connectionEndpoint** (`string`, `optional`) - if specified, the connection endpoint will be registered with this value as opposed to extracted from the event payload (as `${domainName}/${stage}`) #### `createHttpHandler()` Creates an AWS Lambda API Gateway v1 handler. Events are handled by [apollo-server-lambda](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-lambda) #### `createWebSocketHandler()` Creates an AWS Lambda API Gateway v2 handler that supports GraphQL subscriptions over WebSocket. #### `createEventHandler()` Creates an AWS Lambda handler for events from events source (for example DynamoDBEventStore). This method internally work with `IEventProcessor`. ### `DynamoDBEventProcessor: IEventProcessor` AWS Lambda DynamoDB stream handler. DynamoDBEventProcessor is used internally by Server. #### Options (`optional`) - **onError** (`(err: any) => void`, `optional`) - **debug** (`boolean, default: false`) - optional debug mode to add logs in Cloudwatch ### `DynamoDBConnectionManager: IConnectionManager` `IConnectionManager` implementation that stores information about connections to DynamoDB table, performs communication with them, etc. Each connection is stored as [`IConnection` object](#iconnection). #### Options - **connectionsTable** (`string`, `optional`, `default: 'Connections'`) - name of DynamoDB table used to store connections - **subscriptions** (`ISubscriptionManager`, `required`) - subscription manager used to register subscriptions for connections. - **ttl** (`number`, `optional`, `default: 2 hours`) - optional TTL for connections set in seconds - the value is stored as `ttl` field on the row (you are responsible for enabling TTL on given field) - **debug** (`boolean,optional,default: false`) - optional debug mode to add logs in Cloudwatch ### `DynamoDBEventStore: IEventStore` `IEventStore` implemenation that used AWS DynamoDB as storage for published events. #### Options - **eventsTable** (`string`, `optional`, `default: 'Events'`) - events DynamoDB table name - **ttl** (`number`, `optional`, `default: 2 hours`) - optional TTL for events set in seconds - the value is stored as `ttl` field on the row (you are responsible for enabling TTL on given field) ### `DynamoDBSubscriptionManager: ISubscriptionManager` `ISubscriptionManager` implementation that used AWS DynamoDB as storage for subscriptions. Stores subscriptions to a subscriptions table as `event: string` and `subscriptionId: string`.Make sure to set up the key schema as `event: HASH` and `subscriptionId: RANGE`. Stores subscription operations to a subscription operations table as `subscriptionId: string`. Make sure to set up the key schema as `subscriptionId: HASH`. #### Options - **subscriptionsTableName** (`string`, `optional`, `default: 'Subscriptions'`) - **subscriptionOperationsTableName** - (`string`, `optional`, `default: 'SubscriptionOperations'`) - **ttl** (`number`, `optional`, `default: 2 hours`) - optional TTL for subscriptions and subscriptionOperations set in seconds - the value is stored as `ttl` field on the row (you are responsible for enabling TTL on given field) - **getSubscriptionNameFromEvent** (`function`, `optional`, `default: '(event: ISubscriptionEvent) => event.event'`) - Get the subscription name from the event - **getSubscriptionNameFromConnection** (`function`, `optional`, `default: '(name: string, connection: IConnection) => name'`) - Get the subscription name from the subscription connection ### `DynamoDBRangeSubscriptionManager: ISubscriptionManager` - This one allow you to subscribe to multiple events `ISubscriptionManager` implementation that used AWS DynamoDB as storage for subscriptions. Stores subscriptions to a subscriptions table as `event: string` and `subscriptionId: string`.Make sure to set up the key schema as `event: HASH` and `subscriptionId: RANGE`. Stores subscription operations to a subscription operations table as `subscriptionId: string`. Make sure to set up the key schema as `subscriptionId: HASH` and `event: RANGE`. #### Options - **subscriptionsTableName** (`string`, `optional`, `default: 'Subscriptions'`) - **subscriptionOperationsTableName** - (`string`, `optional`, `default: 'SubscriptionOperations'`) - **ttl** (`number`, `optional`, `default: 2 hours`) - optional TTL for subscriptions and subscriptionOperations set in seconds - the value is stored as `ttl` field on the row (you are responsible for enabling TTL on given field) ### `IConnection` - **id: string** - connection id - **connectionData** [`IConnectionData`](#iconnectiondata) ### `IConnectionData` - **context** (`object`) - connection context data provided from `GQL_CONNECTION_INIT` or `onConnect`. This data is passed to graphql resolvers' context. All values should be JSON seriablizable. - **isInitialized** (`boolean`) - is connection initialized? Basically if you use `onConnect` then this value is `false` until the `onConnect` successfully resolves with non `false` value. ### Context creator function Context creator function accepts [`IContext`](#icontext) and returns an `object` or `Promise` that resolves to an `object`. ### `IContext` Internal context passed to the [`Context creator function`](#context-creator-function). **Structure:** - **event** - AWS Lambda event that invoked the handler - **lambdaContext** - AWS Lambda handler context - **\$\$internal** - internal object passed by this library - **connection** (`IConnection`) - current connection that invoked the execution or is associated with an operation - **connectionManager** (`IConnectionManager`) - **operation** (`OperationRequest`) - operation associated with current invokation - **pubSub** (`PubSub`) - PubSub instance used by event store - **subscriptionManager** (`ISubscriptionManager`) ### `PubSub` PubSub implementation that publishes events / subscribes to events using underlying event store. #### Options - **eventStore: IEventStore** - event store used to publish events / subscribe to events - **serializeEventPayload** (`boolean, default: true`) - Serialize event payload to JSON - **debug** (`boolean, default: false`) - optional debug mode to add logs in Cloudwatch ## Examples - [Chat App](https://github.com/michalkvasnicak/aws-lambda-graphql/tree/master/packages/chat-example-app) - React app - [Chat Server](https://github.com/michalkvasnicak/aws-lambda-graphql/tree/master/packages/chat-example-server) - contains AWS Lambda that handles HTTP, WebSocket and DynamoDB streams - also includes serverless.yaml file for easy deployment