You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@knox.apache.org by kr...@apache.org on 2019/11/26 20:24:09 UTC
svn commit: r1870474 - in /knox: site/books/knox-1-3-0/dev-guide.html
site/books/knox-1-4-0/dev-guide.html trunk/books/1.3.0/dev-guide/book.md
trunk/books/1.4.0/dev-guide/book.md
Author: krisden
Date: Tue Nov 26 20:24:08 2019
New Revision: 1870474
URL: http://svn.apache.org/viewvc?rev=1870474&view=rev
Log:
KNOX-2055 - Document ConfigurableDispatch (Sandor Molnar via Kevin Risden)
Modified:
knox/site/books/knox-1-3-0/dev-guide.html
knox/site/books/knox-1-4-0/dev-guide.html
knox/trunk/books/1.3.0/dev-guide/book.md
knox/trunk/books/1.4.0/dev-guide/book.md
Modified: knox/site/books/knox-1-3-0/dev-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-1-3-0/dev-guide.html?rev=1870474&r1=1870473&r2=1870474&view=diff
==============================================================================
--- knox/site/books/knox-1-3-0/dev-guide.html (original)
+++ knox/site/books/knox-1-3-0/dev-guide.html Tue Nov 26 20:24:08 2019
@@ -829,6 +829,7 @@ rewrite.xml
<p><em>ha-classname</em> : This attribute can be used to specify a custom dispatch class with HA functionality.</p>
<p>Only one of contributor-name or classname should be specified and one of ha-contributor-name or ha-classname should be specified.</p>
<p>If providing a custom dispatch, either a jar should be provided, see <a href="#Class+Path">Class Path</a> or a <a href="#Maven+Module">Maven Module</a> should be created.</p>
+<p>Check out <a href="#ConfigurableDispatch">ConfigurableDispatch</a> about configurable dispatch type. </p>
<dl>
<dt><strong>policies</strong></dt>
<dd>This is a wrapper tag for <em>policy</em> elements and can be a child of the <em>service</em> tag or the <em>route</em> tag. Once again, just like with dispatch, the route level policies defined override the ones at the service level.</dd>
@@ -863,6 +864,35 @@ rewrite.xml
<dispatch contributor-name="custom-client" ha-contributor-name="ha-client"/>
</service>
</code></pre>
+<h5><a id="ConfigurableDispatch">ConfigurableDispatch</a> <a href="#ConfigurableDispatch"><img src="markbook-section-link.png"/></a></h5>
+<p>The <code>ConfigurableDispatch</code> allows service definition writers to:</p>
+<ul>
+ <li>exclude certain header(s) from the outbound HTTP request</li>
+ <li>exclude certain header(s) from the outbound HTTP response</li>
+ <li>declares whether parameters should be URL-encoded or not</li>
+</ul>
+<p>This dispatch type can be set in <code>service.xml</code> as follows:</p>
+<pre><code><dispatch classname="org.apache.knox.gateway.dispatch.ConfigurableDispatch" ha-classname="org.apache.knox.gateway.ha.dispatch.ConfigurableHADispatch">
+ <param>
+ <name>requestExcludeHeaders</name>
+ <value>Authorization,Content-Length</value>
+ </param>
+ <param>
+ <name>responseExcludeHeaders</name>
+ <value>SET-COOKIE,WWW-AUTHENTICATE</value>
+ </param>
+ <param>
+ <name>removeUrlEncoding</name>
+ <value>true</value>
+ </param>
+</dispatch>
+</code></pre>
+<p>The default values of these parameters are:</p>
+<ul>
+ <li><code>requestExcludeHeaders</code> = <code>Host,Authorization,Content-Length,Transfer-Encoding</code></li>
+ <li><code>responseExcludeHeaders</code> = <code>SET-COOKIE,WWW-AUTHENTICATE</code></li>
+ <li><code>removeUrlEncoding</code> = <code>false</code></li>
+</ul>
<h5><a id="rewrite.xml">rewrite.xml</a> <a href="#rewrite.xml"><img src="markbook-section-link.png"/></a></h5>
<p>The rewrite.xml file that accompanies the service.xml file follows the same rules as described in the section <a href="#Rewrite+Provider">Rewrite Provider</a>.</p>
<h4><a id="Service+Definition+Directory+Structure">Service Definition Directory Structure</a> <a href="#Service+Definition+Directory+Structure"><img src="markbook-section-link.png"/></a></h4>
Modified: knox/site/books/knox-1-4-0/dev-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-1-4-0/dev-guide.html?rev=1870474&r1=1870473&r2=1870474&view=diff
==============================================================================
--- knox/site/books/knox-1-4-0/dev-guide.html (original)
+++ knox/site/books/knox-1-4-0/dev-guide.html Tue Nov 26 20:24:08 2019
@@ -829,6 +829,7 @@ rewrite.xml
<p><em>ha-classname</em> : This attribute can be used to specify a custom dispatch class with HA functionality.</p>
<p>Only one of contributor-name or classname should be specified and one of ha-contributor-name or ha-classname should be specified.</p>
<p>If providing a custom dispatch, either a jar should be provided, see <a href="#Class+Path">Class Path</a> or a <a href="#Maven+Module">Maven Module</a> should be created.</p>
+<p>Check out <a href="#ConfigurableDispatch">ConfigurableDispatch</a> about configurable dispatch type. </p>
<dl>
<dt><strong>policies</strong></dt>
<dd>This is a wrapper tag for <em>policy</em> elements and can be a child of the <em>service</em> tag or the <em>route</em> tag. Once again, just like with dispatch, the route level policies defined override the ones at the service level.</dd>
@@ -863,6 +864,43 @@ rewrite.xml
<dispatch contributor-name="custom-client" ha-contributor-name="ha-client"/>
</service>
</code></pre>
+<h5><a id="ConfigurableDispatch">ConfigurableDispatch</a> <a href="#ConfigurableDispatch"><img src="markbook-section-link.png"/></a></h5>
+<p>The <code>ConfigurableDispatch</code> allows service definition writers to:</p>
+<ul>
+ <li>exclude certain header(s) from the outbound HTTP request</li>
+ <li>exclude certain header(s) from the outbound HTTP response</li>
+ <li>declares whether parameters should be URL-encoded or not</li>
+</ul>
+<p>This dispatch type can be set in <code>service.xml</code> as follows:</p>
+<pre><code><dispatch classname="org.apache.knox.gateway.dispatch.ConfigurableDispatch" ha-classname="org.apache.knox.gateway.ha.dispatch.ConfigurableHADispatch">
+ <param>
+ <name>requestExcludeHeaders</name>
+ <value>Authorization,Content-Length</value>
+ </param>
+ <param>
+ <name>responseExcludeHeaders</name>
+ <value>SET-COOKIE,WWW-AUTHENTICATE</value>
+ </param>
+ <param>
+ <name>removeUrlEncoding</name>
+ <value>true</value>
+ </param>
+</dispatch>
+</code></pre>
+<p>The default values of these parameters are:</p>
+<ul>
+ <li><code>requestExcludeHeaders</code> = <code>Host,Authorization,Content-Length,Transfer-Encoding</code></li>
+ <li><code>responseExcludeHeaders</code> = <code>SET-COOKIE,WWW-AUTHENTICATE</code></li>
+ <li><code>removeUrlEncoding</code> = <code>false</code></li>
+</ul>
+<p>The <code>responseExcludeHeaders</code> handling allows excluding only certain directives of the <code>SET-COOKIE</code> HTTP header. The following sample shows how to ecxlude only the <code>HttpOnly</code> directive from <code>SET-COOKIE</code> and the <code>WWW-AUTHENTICATE</code> header entirely in the routbound response HTTP header:</p>
+<pre><code><dispatch classname="org.apache.knox.gateway.dispatch.ConfigurableDispatch" ha-classname="org.apache.knox.gateway.ha.dispatch.ConfigurableHADispatch">>
+ <param>
+ <name>responseExcludeHeaders</name>
+ <value>WWW-AUTHENTICATE,SET-COOKIE:HttpOnly</value>
+ </param>
+</dispatch>
+</code></pre>
<h5><a id="rewrite.xml">rewrite.xml</a> <a href="#rewrite.xml"><img src="markbook-section-link.png"/></a></h5>
<p>The rewrite.xml file that accompanies the service.xml file follows the same rules as described in the section <a href="#Rewrite+Provider">Rewrite Provider</a>.</p>
<h4><a id="Service+Definition+Directory+Structure">Service Definition Directory Structure</a> <a href="#Service+Definition+Directory+Structure"><img src="markbook-section-link.png"/></a></h4>
Modified: knox/trunk/books/1.3.0/dev-guide/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.3.0/dev-guide/book.md?rev=1870474&r1=1870473&r2=1870474&view=diff
==============================================================================
--- knox/trunk/books/1.3.0/dev-guide/book.md (original)
+++ knox/trunk/books/1.3.0/dev-guide/book.md Tue Nov 26 20:24:08 2019
@@ -960,6 +960,8 @@ Only one of contributor-name or classnam
If providing a custom dispatch, either a jar should be provided, see #[Class Path] or a #[Maven Module] should be created.
+Check out #[ConfigurableDispatch] about configurable dispatch type.
+
**policies**
: This is a wrapper tag for *policy* elements and can be a child of the *service* tag or the *route* tag. Once again, just like with
dispatch, the route level policies defined override the ones at the service level.
@@ -999,6 +1001,39 @@ For example,
</service>
```
+##### ConfigurableDispatch ####
+
+The `ConfigurableDispatch` allows service definition writers to:
+
+ - exclude certain header(s) from the outbound HTTP request
+ - exclude certain header(s) from the outbound HTTP response
+ - declares whether parameters should be URL-encoded or not
+
+This dispatch type can be set in `service.xml` as follows:
+
+```
+<dispatch classname="org.apache.knox.gateway.dispatch.ConfigurableDispatch" ha-classname="org.apache.knox.gateway.ha.dispatch.ConfigurableHADispatch">
+ <param>
+ <name>requestExcludeHeaders</name>
+ <value>Authorization,Content-Length</value>
+ </param>
+ <param>
+ <name>responseExcludeHeaders</name>
+ <value>SET-COOKIE,WWW-AUTHENTICATE</value>
+ </param>
+ <param>
+ <name>removeUrlEncoding</name>
+ <value>true</value>
+ </param>
+</dispatch>
+```
+
+The default values of these parameters are:
+
+ - `requestExcludeHeaders` = `Host,Authorization,Content-Length,Transfer-Encoding`
+ - `responseExcludeHeaders` = `SET-COOKIE,WWW-AUTHENTICATE`
+ - `removeUrlEncoding` = `false`
+
##### rewrite.xml #####
The rewrite.xml file that accompanies the service.xml file follows the same rules as described in the section #[Rewrite Provider].
Modified: knox/trunk/books/1.4.0/dev-guide/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/dev-guide/book.md?rev=1870474&r1=1870473&r2=1870474&view=diff
==============================================================================
--- knox/trunk/books/1.4.0/dev-guide/book.md (original)
+++ knox/trunk/books/1.4.0/dev-guide/book.md Tue Nov 26 20:24:08 2019
@@ -960,6 +960,8 @@ Only one of contributor-name or classnam
If providing a custom dispatch, either a jar should be provided, see #[Class Path] or a #[Maven Module] should be created.
+Check out #[ConfigurableDispatch] about configurable dispatch type.
+
**policies**
: This is a wrapper tag for *policy* elements and can be a child of the *service* tag or the *route* tag. Once again, just like with
dispatch, the route level policies defined override the ones at the service level.
@@ -999,6 +1001,50 @@ For example,
</service>
```
+##### ConfigurableDispatch ####
+
+The `ConfigurableDispatch` allows service definition writers to:
+
+ - exclude certain header(s) from the outbound HTTP request
+ - exclude certain header(s) from the outbound HTTP response
+ - declares whether parameters should be URL-encoded or not
+
+This dispatch type can be set in `service.xml` as follows:
+
+```
+<dispatch classname="org.apache.knox.gateway.dispatch.ConfigurableDispatch" ha-classname="org.apache.knox.gateway.ha.dispatch.ConfigurableHADispatch">
+ <param>
+ <name>requestExcludeHeaders</name>
+ <value>Authorization,Content-Length</value>
+ </param>
+ <param>
+ <name>responseExcludeHeaders</name>
+ <value>SET-COOKIE,WWW-AUTHENTICATE</value>
+ </param>
+ <param>
+ <name>removeUrlEncoding</name>
+ <value>true</value>
+ </param>
+</dispatch>
+```
+
+The default values of these parameters are:
+
+ - `requestExcludeHeaders` = `Host,Authorization,Content-Length,Transfer-Encoding`
+ - `responseExcludeHeaders` = `SET-COOKIE,WWW-AUTHENTICATE`
+ - `removeUrlEncoding` = `false`
+
+The `responseExcludeHeaders` handling allows excluding only certain directives of the `SET-COOKIE` HTTP header. The following sample shows how to ecxlude only the `HttpOnly` directive from `SET-COOKIE` and the `WWW-AUTHENTICATE` header entirely in the routbound response HTTP header:
+
+```
+<dispatch classname="org.apache.knox.gateway.dispatch.ConfigurableDispatch" ha-classname="org.apache.knox.gateway.ha.dispatch.ConfigurableHADispatch">>
+ <param>
+ <name>responseExcludeHeaders</name>
+ <value>WWW-AUTHENTICATE,SET-COOKIE:HttpOnly</value>
+ </param>
+</dispatch>
+```
+
##### rewrite.xml #####
The rewrite.xml file that accompanies the service.xml file follows the same rules as described in the section #[Rewrite Provider].