Merge pull request #36 from conduktor/docs/how-interceptor-raise-retu…

…rn-error-to-gateway

PXY-498-document-test-how-we-raise-and-return-errors-in-interceptors-for

README.md

@@ -16,7 +16,7 @@ See what you can already do with Conduktor Gateway on the [interceptor marketpla
 
 # How to start?
 
-Conduktor Gateway comes with an included interceptor which writes log lines and information about the Kakfka traffic to stdout.
+Conduktor Gateway comes with an included interceptor which writes log lines and information about the Kafka traffic to stdout.
 
 If this is your first time starting Gateway, the [Quick Start Guide](https://docs.conduktor.io/platform/gateway/installation/opensource-install/) describes how to get setup and try the logging interceptor. Go here first!
 
@@ -55,6 +55,11 @@ conduktor-gateway
 │   └── src/test/resources - docker setup for integration tests 
 ```
 
+# Interceptor
+
+It will add some extra logic for Kafka request or response.
+
+
 # Building
 
 Conduktor Gateway is a simple maven project and can be built with:

interceptor-framework/README.md

@@ -161,6 +161,11 @@ public class LoggerInterceptorPlugin implements Plugin {
 
 You should intercept `AbstractRequestResponse` if the interceptor needs to work on all requests and responses.  For example, you might want to write an audit record for all requests and responses passing through the gateway.
 
+### Intercept but want to break the flow
+
+For some reasons, we might want to fast return the response to client without send the request to Kafka server.
+Interceptor can throw a **InterceptorIntentionException**. See [Error handling](#error-handling) for more detail.
+
 ### CompletionStage
 
 The `intercept` method on the `Interceptor.java` interface returns a `CompletionStage` to the Gateway.  This holds the Kafka request or response that was passed in to the intercept method.  The request or response may have been updated if this interceptor is one that manipulates the Kafka data, or it may remain unchanged if the interceptor does not manipulate the data.
@@ -216,6 +221,19 @@ For example, a Kafka `FetchRequest` API request arriving with the Gateway will t
 
 The next interceptor in the prioritised list of applicable interceptors will not run until the previous interceptor’s `CompletionStage` has run and the associated `Future` has completed.
 
+### Error handling
+
+Conduktor Gateway catch exception from interceptor by two ways:
+
+* try catch as normal flow
+* using exceptionally callback of CompletionStage
+
+So, we can be sure that if an interceptor get exception while executing, only current request get affected.
+
+Beside of unexpected exception, we have **InterceptorIntentionException**. This is a special exception, which has a response inside. 
+When Conduktor Gateway encounters this type of exception, it will get the response inside and return that to client.
+
+
 ## `Plugin.java`
 
 `Plugin` defines one method:
@@ -270,4 +288,4 @@ java.lang.ClassNotFoundException: io.conduktor.example.MyPlugin
 This means that the jar file for the interceptor is not available on the classpath of the running JVM.
 
 Ensure you are not running using the java -jar command, as this overwrites any classpath settings you have included.
-Check you have specified the fully qualified class name of the Plugin correctly.
+Check you have specified the fully qualified class name of the Plugin correctly.