merge with master branch

Author: mmacai

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added possibility to set response code for `response_from` messages in reverse proxy (`kafka` and `http_async`). [#321](https://github.com/Accenture/reactive-interaction-gateway/pull/321)
 - Added new version - `v3` - for internal endpoints to support response code in the `/responses` endpoint
 - Added Helm v3 template to the `deployment` folder [#288](https://github.com/Accenture/reactive-interaction-gateway/issues/288)
+- Added detailed features summary on the website with architecture diagrams. [#284](https://github.com/Accenture/reactive-interaction-gateway/issues/284)
 - Added [documentation section](https://accenture.github.io/reactive-interaction-gateway/docs/jwt-blacklisting.html) for the JWT Blacklist feature. [#156](https://github.com/Accenture/reactive-interaction-gateway/issues/156)
 
 ### Changed
@@ -32,6 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     ```
 
   More information, follow the [deployment Readme](./deployment/README.md). [#319](https://github.com/Accenture/reactive-interaction-gateway/issues/319)
+- make README smaller, easier to read and highlight features. [#284](https://github.com/Accenture/reactive-interaction-gateway/issues/284)
 
 ### Fixed
 

CONTRIBUTING.md

@@ -7,6 +7,20 @@ in the [Accenture Organization](https://github.com/accenture) on GitHub. These a
 guidelines, not rules. Use your best judgment, and feel free to propose changes to this document
 in a pull request.
 
+## TL;DR
+
+- **Use issues for everything.**
+- For a small change, just send a PR.
+- For bigger changes open an issue for discussion before sending a PR.
+- PR should have:
+  - Test case
+  - Documentation (e.g., moduledoc, developer's guide, operator's guide)
+  - Changelog entry
+- You can also contribute by:
+  - Reporting issues
+  - Suggesting new features or enhancements
+  - Improve/fix documentation
+
 ## Code of Conduct
 
 This project and everyone participating in it is governed by our

README.md

@@ -2,92 +2,39 @@
 
 # RIG - Reactive Interaction Gateway
 
-Create low-latency, interactive user experiences for stateless microservices.
+Makes frontend<->backend communication reactive and event-driven.
 
 [![Build Status](https://travis-ci.org/Accenture/reactive-interaction-gateway.svg?branch=master)](https://travis-ci.org/Accenture/reactive-interaction-gateway)
 [![DockerHub](https://img.shields.io/docker/pulls/accenture/reactive-interaction-gateway)](https://hub.docker.com/r/accenture/reactive-interaction-gateway)
-[![Slack](https://rig-slackin.herokuapp.com/badge.svg)](https://rig-slackin.herokuapp.com)
-
-Take a look at the [documentation](https://accenture.github.io/reactive-interaction-gateway/docs/intro.html) and get in touch with us on [Slack](https://rig-slackin.herokuapp.com)!
-
-- [About](#about)
-- [Getting Started](#getting-started)
-  - [API Documentation](#api-documentation)
-  - [Metrics](#metrics)
-- [Contribute](#contribute)
-- [License](#license)
-- [Acknowledgments](#acknowledgments)
 
 ## About
 
-How RIG makes asynchronous backend<->frontend communication easier:
-
-- RIG takes care of client connection state so you don't have to.
-- RIG picks up back-end events and forwards them to clients based on subscriptions.
-- RIG forwards client requests to backend services either synchronously or asynchronously.
-
-Built on open standards, RIG is very easy to integrate – and easy to _replace_ – which means low-cost, low-risk adoption. Unlike other solutions, RIG does not leak into your application – no libraries or SDKs required.
-
-Features:
-
-- Easy to use and scalable by design:
-  - Supports tens of thousands stable connections per node even on low-end machines.
-  - Easy to add additional nodes.
-  - Built on the battle-proven [Erlang/OTP](http://www.erlang.org/) distribution model.
-  - Only uses in-memory data structures - no external dependencies to configure or scale.
-- Connect using standard protocols:
-  - Firewall friendly and future proof using Server-Sent Events (SSE)
-    - [HTML5 standard](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events).
-    - Regular HTTP requests, so no issues with proxy servers or firewalls.
-    - Connection multiplexing with HTTP/2 out of the box.
-    - SSE implementation (browser) keeps track of connection drops and restores the connection automatically.
-    - Polyfills available for older browsers.
-  - WebSocket connections are supported, too.
-  - HTTP long polling for situations where SSE and WS are not supported.
-- Publish events from various sources:
-  - Kafka
-  - NATS
-  - Amazon Kinesis
-  - or publish via HTTP
-- Convert a HTTP request to a message for asynchronous processing:
-  - produce to Kafka topic, optionally wait for the result on another Kafka topic
-  - produce to a NATS topic, optionally using NATS request-response to wait for the result
-  - produce to Amazon Kinesis
-- Uses the CNCF [CloudEvents specification](https://cloudevents.io/).
-- Flexible event subscription model based on event types.
-- Use existing services for authentication and authorization of users and subscriptions.
-- JWT signature verification for APIs as a simple authentication check.
-- Session blacklist with immediate session invalidation.
-
-For more details take a look at the [documentation](https://accenture.github.io/reactive-interaction-gateway/docs/intro.html).
-
-## Getting Started
+The Reactive Interaction Gateway (RIG) is the glue between your client (frontend) and your backend. It makes communication between them easier by (click the links to learn more)
 
-Take a look at the [getting-started tutorial](https://accenture.github.io/reactive-interaction-gateway/docs/tutorial.html).
+- picking up backend events and forwarding them to clients based on subscriptions: this makes your frontend apps **reactive and eliminates the need for polling**. You can do this
+  - [asynchronously](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#picking-up-backend-events-and-forwarding-them-to-clients-based-on-subscriptions#asynchronously) - using Kafka, Nats or Kinesis.
+  - [synchronously](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#picking-up-backend-events-and-forwarding-them-to-clients-based-on-subscriptions#synchronously) - if you don't want to manage a (potentially complex) message broker system like Kafka.
+- forwarding client requests to backend services either synchronously, asynchronously or a mix of both:
+  - [synchronously](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#synchronously) - if requests are being sent synchronously, RIG acts as a reverse proxy: RIG forwards the request to an HTTP endpoint of a backend service, waits for the response and sends it to the client.
+  - [asynchronously - fire&forget](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#asynchronously---fireforget) - RIG transforms a HTTP request to a message for asynchronous processing and forwards it to the backend asynchronously using either Kafka, NATS or Amazon Kinesis.
+  - [synchronously with asynchronous response](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#synchronously---asnychronous-response) - a pseudo-synchronous request: RIG forwards the client request to the backend synchronously via HTTP and waits for the backend response by listening to Kafka/NATS and forwarding it to the still open HTTP connection to the frontend.
+  - [asynchronously with asynchronous response](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#asynchronously---asnychronous-response) - a pseudo-synchronous request: RIG forwards the client request to the backend asynchronously via Kafka or NATS and waits for the backend response by listening to Kafka/NATS and forwarding it to the still open HTTP connection to the frontend.
 
-### API Documentation
+Built on open standards, RIG is very easy to integrate – and easy to replace – which means low-cost, low-risk adoption. Unlike other solutions, RIG does not leak into your application – no libraries or SDKs required. Along with handling client requests and publishing events from backend to the frontend, RIG provides [many out-of-the-box features](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#out-of-the-box-features).
 
-RIG exposes its API documentation on its API endpoint under [/swagger-ui](http://localhost:4010/swagger-ui). For integration into an existing swagger UI, the related JSON document can either be [retrieved at runtime](http://localhost:4010/swagger-ui/rig_api_swagger.json) or [found on disk](./priv/static/rig_api_swagger.json) after compiling RIG at least once.
+This is just a basic summary of what RIG can do. There is a comprehensive documentation available on our [website](https://accenture.github.io/reactive-interaction-gateway/docs/intro.html). If you have any unanswered question, check out the [FAQ](https://accenture.github.io/reactive-interaction-gateway/docs/faq.html) section to get them answered.
 
-### Metrics
-
-RIG exposes Metrics in [Prometheus](https://prometheus.io/) format on its API endpoint under [/metrics](http:localhost:4010/metrics)
+## Getting Started
 
-## Contribute
+- Take a look at the [getting-started tutorial](https://accenture.github.io/reactive-interaction-gateway/docs/tutorial.html) for a simple walkthrough using docker
+- For deploying RIG on Kubernetes, check out the [Kubernetes deployment instructions](https://github.com/Accenture/reactive-interaction-gateway/tree/284-document-sync-async-http-to-kafka/deployment)
 
-- **Use issues for everything.**
-- For a small change, just send a PR.
-- For bigger changes open an issue for discussion before sending a PR.
-- PR should have:
-  - Test case
-  - Documentation (e.g., moduledoc, developer's guide, operator's guide)
-  - Changelog entry
-- You can also contribute by:
-  - Reporting issues
-  - Suggesting new features or enhancements
-  - Improve/fix documentation
+## Get Involved
 
-See the [developer's guide](https://accenture.github.io/reactive-interaction-gateway/docs/rig-dev-guide.html) and [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+- discuss RIG on [Slack](https://rig-slackin.herokuapp.com)
+- Follow us on [Twitter](https://twitter.com/reactivegateway)
+- Start contributing: refer to our [contributing guide](./CONTRIBUTING.md)
+- Develop RIG: refer to our [developer's guide](https://accenture.github.io/reactive-interaction-gateway/docs/rig-dev-guide.html)
 
 ## License
 
@@ -105,5 +52,3 @@ Kudos to these awesome projects:
 - Phoenix Framework
 - Brod
 - Distillery
-
-.

ct.yaml

@@ -2,4 +2,3 @@
 remote: origin
 chart-dirs:
   - deployment
-debug: true

deployment/README.md

@@ -20,8 +20,11 @@ Check out the [Helm v2 README](./reactive-interaction-gateway-helm-v2/README.md)
 kubectl apply -f kubectl/rig.yaml
 ```
 
+
 ## Some Additional information
 
+Check out the [getting-started tutorial](https://accenture.github.io/reactive-interaction-gateway/docs/tutorial.html), the [examples](https://accenture.github.io/reactive-interaction-gateway/docs/examples.html) and the [features](https://accenture.github.io/reactive-interaction-gateway/docs/features.html) for more information what you can do with RIG.
+
 ### Communication
 
 Both `kubectl` and `helm` deploy bunch of Kubernetes resources:

docs/api-documentation.md

@@ -0,0 +1,7 @@
+---
+id: api-documentation
+title: API Documentation
+sidebar_label: API Documentation
+---
+
+RIG exposes its API documentation on its API endpoint under [/swagger-ui](http://localhost:4010/swagger-ui). For integration into an existing swagger UI, the related JSON document can either be [retrieved at runtime](http://localhost:4010/swagger-ui/rig_api_swagger.json) or found on disk at `priv/static/rig_api_swagger.json` after compiling RIG at least once.

docs/api-gateway.md

@@ -180,7 +180,7 @@ The endpoint expects the following request format:
 ### Wait for response
 
 Sometimes it makes sense to provide a simple request-response API to something that runs asynchronously on the backend. For example, let's say there's a ticket reservation process that takes 10 seconds in total and involves three different services that communicate via message passing. For an external client, it may be simpler to wait 10 seconds for the response instead of polling for a response every other second.
-A behavior like this can be configured using an endpoints' `response_from` property. When set to `kafka`, the response to the request is not taken from the `target` (e.g., for `target` = `http` this means the backend's HTTP response is ignored), but instead it's read from a Kafka topic. In order to enable RIG to correlate the response from the topic with the original request, RIG adds a correlation ID to the request (using a query parameter in case of `target` = `http`, or backed into the produced CloudEvent otherwise). **Backend services that work with the request need to include that correlation ID in their response; otherwise, RIG won't be able to forward it to the client (and times out).**
+A behavior like this can be configured using an endpoints' `response_from` property. When set to `kafka`, the response to the request is not necessarily taken from the `target`, e.g., for `target` = `http` this means the backend's HTTP response might be ignored - it's the responsibility of the backend service where to read the response from: If the backend returns with the HTTP code `202 Accepted`, the response will be read from a Kafka topic. If the backend returns a different HTTP code (can be `200` or `400` or whatever makes sense), only then the response will be read synchronously from the http target directly (this allows the backend to return cached responses). In order to enable RIG to correlate the response from the kafka topic with the original request, RIG adds a correlation ID to the request (using a query parameter in case of `target` = `http`, or baked into the produced CloudEvent otherwise). Backend services that work with the request need to include that correlation ID in their response; otherwise, RIG won't be able to forward it to the client (and times out).
 
 Configuration of such API endpoint might look like this:
 

docs/architecture.md

@@ -21,7 +21,7 @@ Why not introduce (connection) state for microservices? Two reasons. First, it m
 
 ## Event-Driven Architecture and the UI
 
-Forwarding events to frontends enables and event-driven UX design, effectively extending the idea of [event-driven architecture](https://en.wikipedia.org/wiki/Event-driven_architecture) to the UI.
+Forwarding events to frontends enables an event-driven UX design, effectively extending the idea of [event-driven architecture](https://en.wikipedia.org/wiki/Event-driven_architecture) to the UI.
 
 We believe that hiding asynchronism by turning it into a fake synchronous process is an anti-pattern. For example, sending money from one bank account to another doesn't happen instantaneously, but with at least two events: "transfer requested" and "transfer completed" (or "transfer failed"). Acknowledging this when designing the UI leads to a more natural user experience and less loading indicators.