Introduce mod_reflector, a handler capable of reflecting POSTed

request bodies back within the response through the output filter
stack. Can be used to turn an output filter into a web service.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@910017 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 105 insertions, 0 deletions

diff --git a/docs/manual/filter.xml b/docs/manual/filter.xml
index 9c35c0c6ba..2e85f4d4ee 100644
--- a/docs/manual/filter.xml
+++ b/docs/manual/filter.xml
@@ -37,6 +37,7 @@
         <module>mod_ext_filter</module>
         <module>mod_include</module>
         <module>mod_charset_lite</module>
+        <module>mod_reflector</module>
       </modulelist>
       <directivelist>
         <directive module="mod_filter">FilterChain</directive>
@@ -47,6 +48,7 @@
         <directive module="mod_mime">AddOutputFilter</directive>
         <directive module="mod_mime">RemoveInputFilter</directive>
         <directive module="mod_mime">RemoveOutputFilter</directive>
+        <directive module="mod_reflector">ReflectorHeader</directive>
         <directive module="mod_ext_filter">ExtFilterDefine</directive>
         <directive module="mod_ext_filter">ExtFilterOptions</directive>
         <directive module="core">SetInputFilter</directive>
@@ -118,6 +120,25 @@ document is not already in the desired charset</li>
 </ul>
 </section>
 
+<section id="service">
+
+<title>Exposing Filters as an HTTP Service</title>
+<p>Filters can be used to process content originating from the client in
+addition to processing content originating on the server using the
+<module>mod_reflector</module> module.</p>
+
+<p><module>mod_reflector</module> accepts POST requests from clients, and reflects
+the content request body received within the POST request back in the response,
+passing through the output filter stack on the way back to the client.</p>
+
+<p>This technique can be used as an alternative to a web service running within
+an application server stack, where an output filter provides the transformation
+required on the request body. For example, the <module>mod_deflate</module>
+module might be used to provide a general compression service, or an image
+transformation filter might be turned into an image transformation service.</p>
+    
+</section>
+  
 <section id="using">
 <title>Using Filters</title>
 <p>There are two ways to use filtering: Simple and Dynamic.
diff --git a/docs/manual/mod/allmodules.xml b/docs/manual/mod/allmodules.xml
index 39a51eef65..4edbb86bdd 100644
--- a/docs/manual/mod/allmodules.xml
+++ b/docs/manual/mod/allmodules.xml
@@ -75,6 +75,7 @@
   <modulefile>mod_proxy_ftp.xml</modulefile>
   <modulefile>mod_proxy_http.xml</modulefile>
   <modulefile>mod_proxy_scgi.xml</modulefile>
+  <modulefile>mod_reflector.xml</modulefile>
   <modulefile>mod_remoteip.xml</modulefile>
   <modulefile>mod_reqtimeout.xml</modulefile>
   <modulefile>mod_request.xml</modulefile>
diff --git a/docs/manual/mod/mod_reflector.xml b/docs/manual/mod/mod_reflector.xml
new file mode 100644
index 0000000000..947a6f9baa
--- /dev/null
+++ b/docs/manual/mod/mod_reflector.xml
@@ -0,0 +1,83 @@
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 894290 $ -->
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<modulesynopsis metafile="mod_reflector.xml.meta">
+
+<name>mod_reflector</name>
+<description>Reflect a request body as a response via the output filter stack.</description>
+<status>Base</status>
+<sourcefile>mod_reflector.c</sourcefile>
+<identifier>reflector_module</identifier>
+<compatibility>Version 2.3 and later</compatibility>
+
+<summary>
+    <p>This module allows request bodies to be reflected back to the
+    client, in the process passing the request through the output filter
+    stack. A suitably configured chain of filters can be used to transform
+    the request into a response. This module can used to turn an output
+    filter into an HTTP service.</p>
+</summary>
+
+<section id="examples"><title>Examples</title>
+    <dl>
+    <dt>Compression service</dt>
+    <dd>Pass the request body through the DEFLATE filter to compress the
+    body. This request requires a Content-Encoding request header containing
+    "gzip" for the filter to return compressed data.
+    <example>
+      &lt;Location /compress&gt;<br/>
+        SetHandler reflector<br/>
+        SetOutputFilter DEFLATE<br/>
+      &lt;/Location&gt;
+    </example>
+    </dd>
+
+    <dt>Image downsampling service</dt>
+    <dd>Pass the request body through an image downsampling filter, and reflect
+    the results to the caller.
+    <example>
+      &lt;Location /downsample&gt;<br/>
+        SetHandler reflector<br/>
+        SetOutputFilter DOWNSAMPLE<br/>
+      &lt;/Location&gt;
+    </example>
+    </dd>
+    </dl>
+</section>
+
+<directivesynopsis>
+<name>ReflectorHeader</name>
+<description>Reflect an input header to the output headers</description>
+<syntax>ReflectorHeader <var>inputheader</var> <var>[outputheader]</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+<context>directory</context><context>.htaccess</context></contextlist>
+<override>Options</override>
+
+<usage>
+    <p>This directive controls the reflection of request headers to the response.
+    The first argument is the name of the request header to copy. If the optional
+    second argument is specified, it will be used as the name of the response
+    header, otherwise the original request header name will be used.</p>
+</usage>
+</directivesynopsis>
+
+</modulesynopsis>