Support for invocations based on websocket messages

[mhamann]

Provide a mechanism by which API invocations (e.g. to a Whisk action) may be triggered by a message to a websocket.

The basic approach could be something like:

• Client attempts to make a websocket connection to the API gateway on a path (e.g. /tenant/basepath/api)
• Gateway enforces pre-request policies (e.g. client id/secret, oauth, rate limit, etc).
• Assuming pre-request checks succeed, gateway allows a websocket upgrade and accepts the connection
• When the client sends a message, the gateway will invoke the target endpoint defined in the API doc, passing the message in the request body. If security policies were run as part of the initial connection, then any API key or user identity information would be included in the headers to the backend endpoint.
• Once the backend request is complete, the gateway will pass any response body to the client via a websocket message.

There may also be a case where the API developer may wish the gateway to proxy the entire websocket connection through to the backend. This could be detected via the proxy policy having a ws:// or wss:// protocol in the target URL. Some work would still need to be done there to define how that works, but that would enable push messages from a backend. This is a more advanced use-case that probably needs addition design.

[jthomas]

This would be an excellent feature of the API Gateway 👏. Websocket support is something developers ask about a lot...

• We would need to define the error handling process when the the triggers are unavailable or rate-limited. How would we signify to a client that a message wasn't delivered?

Another (more difficult) thing to consider is how to make it possible for messages to be sent to listening clients outside of responding to an incoming event. If we take one of the most common examples for a websocket application, a chat application, how could we enable this feature?

Ideally, an action could call the API Gateway service with a message to pass to one or more clients currently connected to pass messages that arrived from other sources.

[mdeuser]

@mhamann - can you describe the web socket use case(s) being addressed? i've been thinking that web sockets and serverless are kind of at odds with each other... but there may be a use case that bridges this gap.

[mhamann]

@jthomas all very good points.

Since the WebSocket RFC doesn't provide any mechanism by which to supply message headers, I think we might have to implement something custom.

One option would be to define a precise error format (e.g. always JSON with certain properties) that clients must be able to check for and process if something goes wrong.

Another possibility would be to allow the API creator to specify another action / URL that could process an error message and return a message in any format. Even so, something could go wrong with that invocation that would require falling back to the first option.

The chat scenario is interesting as well. A few things have occurred to me as to how we might handle that type of flow, but I'm going to think about it a bit further before writing anything down.

@mdeuser I think there are potentially a number of desirable use cases around this. If the notion of serverless computing is designed to replace many traditional application models, then WebSockets would be integral to the platform.

James already mentioned the chat app example, which would be really cool to duplicate in a serverless context.

Other examples:

• IoT devices that send a constant stream of telemetry back to an aggregator
• Collaborative editing (e.g. Google Docs)
• Real-time stock ticker
• Gaming

[jthomas]

One option would be to define a precise error format

This seems like the most sensible option. Returning the message with an error identifer and message to indicate they need to re-send?

If we can support both in-bound and out-bound messages this would be a huge feature that the other platforms do not support.

[mdeuser]

@mhamann - taking the real-time stock ticker as an example.. are you thinking that the api gw would handle the connection and connection keep alives to the client and periodically invoke the backend action to obtain the latest stock quote and then sending that result to the client inside a websocket message?

[rabbah]

AWS just announced this.

[mhamann]

Is there a link to the announcement?

[jthomas]

I can't find any documentation about this feature in AWS at the moment. We'll have to wait and see what their implementation looks like. It'll be interesting to see how they handle errors and whether they support sending messages back outside of the invocation response.

[mhamann]

Here's a great overview of how this works. Very similar to what we proposed, but with a couple of missing pieces filled in: https://serverless.com/blog/api-gateway-websockets-support/

[jthomas]

More details now available: https://aws.amazon.com/blogs/compute/announcing-websocket-apis-in-amazon-api-gateway/

[csantanapr]

Here is an example of web chat app https://serverlessrepo.aws.amazon.com/applications/arn:aws:serverlessrepo:us-east-1:729047367331:applications~simple-websockets-chat-app