Add integrations README

integrations/README.md

@@ -0,0 +1,39 @@
+# Integrations for async-graphql
+
+This directory provides various integrations for `async-graphql` to various crates in the ecosystem.
+
+## Requirements for an HTTP integration
+
+This is a list of criteria for HTTP integrations with `async-graphql` in order to make sure all
+integrations are implemented consistently. Currently not all integrations follow this criteria, but
+we are working on it.
+
+Integrations may provide additional functionality to better integrate with the specific library, but
+they must all internally use the below functions.
+
+- Conversion from HTTP library's request to `async_graphql::BatchRequest`:
+	1. If the request is a `GET` request:
+		1. Return the request's query parameters deserialized as an `async_graphql::Request`.
+	1. Otherwise:
+		1. Get the request's `Content-Type` header.
+		1. Call `async_graphql::http::receive_batch_body` on the request's body.
+		1. Convert `ParseRequestError::PayloadTooLarge` to a 413 Payload Too Large response.
+		1. Convert all other errors to a 400 Bad Request response.
+- Conversion from HTTP library's request to `async_graphql::Request`:
+	1. Call the above function to convert the request to an `async_graphql::BatchRequest`.
+	1. Call `BatchRequest::into_single` on the result.
+	1. Convert all errors to a 400 Bad Request response.
+- Conversion from `async_graphql::BatchResponse` to HTTP library's response:
+	1. Create a 200 OK response.
+	1. If the GraphQL response is ok, set the response's `Cache-Control` header to the response's
+	   cache control value.
+	1. Set the response's body to the GraphQL response serialized as JSON, also setting the
+	   `Content-Type` header to `application/json`.
+- GraphQL over websocket support:
+	1. Create an `async_graphql::http:WebSocket` using `async_graphql::http::WebSocket::with_data`.
+	1. Support the basics of the websocket protocol:
+		- Respond to ping messages with pong messages.
+		- Treat continuation messages identically to data messages.
+	1. Stream all websocket messages that send data (bytes/text/continuations) to the
+	   `async_graphql::http::WebSocket`.
+	1. Convert all responses to websocket text responses.