From 414d09135b06f16cc2ad02051db3a6bdbdbab984 Mon Sep 17 00:00:00 2001 From: Marc Cromme Date: Fri, 8 Sep 2006 14:12:28 +0000 Subject: [PATCH] adderet extra doc info on bounce filter --- doc/Makefile.am | 10 +++++--- doc/book.xml | 72 +++++++++++++++++++++++++++++++++++++++++-------------- doc/bounce.xml | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 127 insertions(+), 21 deletions(-) create mode 100644 doc/bounce.xml diff --git a/doc/Makefile.am b/doc/Makefile.am index 94a3671..05fbf57 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ -## $Id: Makefile.am,v 1.27 2006-09-07 10:00:43 adam Exp $ +## $Id: Makefile.am,v 1.28 2006-09-08 14:12:28 marc Exp $ docdir=$(datadir)/doc/@PACKAGE@ SUBDIRS = common @@ -9,10 +9,14 @@ XMLFILES = book.xml manref.xml copyright.xml MAINXML = $(srcdir)/book.xml -XMLMAN = metaproxy.xml auth_simple.xml backend_test.xml frontend_net.xml \ +XMLMAN = metaproxy.xml \ + auth_simple.xml backend_test.xml bounce.xml \ + frontend_net.xml \ http_file.xml log.xml multi.xml query_rewrite.xml \ session_shared.xml template.xml virt_db.xml z3950_client.xml -MANFILES = auth_simple.3mp backend_test.3mp frontend_net.3mp \ + +MANFILES = auth_simple.3mp backend_test.3mp bounce.3mp \ + frontend_net.3mp \ http_file.3mp log.3mp multi.3mp query_rewrite.3mp \ session_shared.3mp template.3mp virt_db.3mp z3950_client.3mp \ metaproxy.1 diff --git a/doc/book.xml b/doc/book.xml index 406e7bf..ce1b5b6 100644 --- a/doc/book.xml +++ b/doc/book.xml @@ -17,19 +17,19 @@ --> ]> - + Metaproxy - User's Guide and Reference - MikeTaylor - - AdamDickmeiss MarcCromme + + MikeTaylor + 2006 Index Data ApS @@ -615,7 +615,7 @@ as part of Metaproxy, and others may be provided by third parties and dynamically loaded. They all conform to the same simple API of essentially two methods: configure() is - called at startup time, and is passed a DOM tree representing that + called at startup time, and is passed an XML DOM tree representing that part of the configuration file that pertains to this filter instance: it is expected to walk that tree extracting relevant information; and process() is called every @@ -629,6 +629,7 @@ others are sinks: they consume packages and return a result (z3950_client, backend_test, + bounce, http_file); the others are true filters, that read, process and pass on the packages they are fed @@ -712,7 +713,7 @@ Figure out what additional information we need in: <literal>backend_test</literal> (mp::filter::Backend_test) - A sink that provides dummy responses in the manner of the + A partial sink that provides dummy responses in the manner of the yaz-ztest Z39.50 server. This is useful only for testing. Seriously, you don't need this. Pretend you didn't even read this section. @@ -720,6 +721,24 @@ Figure out what additional information we need in:
+ <literal>bounce</literal> + (mp::filter::Bounce) + + A sink that swallows all packages, + and returns them almost unprocessed. + It never sends any package of any type further down the row, but + sets Z39.50 packages to Z_Close, and HTTP_Request packages to + HTTP_Response err code 400 packages, and adds a suitable bounce + message. + The bounce filter is usually added at end of each filter chain + config.xml to prevent infinite hanging of for example HTTP + requests packages when only the Z39.50 client partial sink + filter is found in the + route. + +
+ +
<literal>frontend_net</literal> (mp::filter::FrontendNet) @@ -734,8 +753,12 @@ Figure out what additional information we need in: <literal>http_file</literal> (mp::filter::HttpFile) - A sink that returns the contents of files from the local - filesystem in response to HTTP requests. (Yes, Virginia, this + A partial sink which swallows only HTTP_Request packages, and + returns the contents of files from the local + filesystem in response to HTTP requests. + It lets Z39.50 packages and all other forthcoming package types + pass untouched. + (Yes, Virginia, this does mean that Metaproxy is also a Web-server in its spare time. So far it does not contain either an email-reader or a Lisp interpreter, but that day is surely coming.) @@ -747,7 +770,8 @@ Figure out what additional information we need in: (mp::filter::Log) Writes logging information to standard output, and passes on - the package unchanged. + the package unchanged. A log file name can be specified, as well + as multiple different logging formats.
@@ -825,13 +849,16 @@ Figure out what additional information we need in: <literal>z3950_client</literal> (mp::filter::Z3950Client) - Performs Z39.50 searching and retrieval by proxying the + A partial sink which swallows only Z39.50 packages. + It performs Z39.50 searching and retrieval by proxying the packages that are passed to it. Init requests are sent to the address specified in the VAL_PROXY otherInfo attached to the request: this may have been specified by client, or generated by a virt_db filter earlier in the route. Subsequent requests are sent to the same address, which is remembered at Init time in a Session object. + HTTP_Request packages and all other forthcoming package types + are passed untouched. @@ -1000,7 +1027,7 @@ Figure out what additional information we need in: The following is a small, but complete, Metaproxy configuration file (included in the distribution as - metaproxy/etc/config0.xml). + metaproxy/etc/config1.xml). This file defines a very simple configuration that simply proxies to whatever back-end server the client requests, but logs each request and response. This can be useful for debugging complex @@ -1021,13 +1048,14 @@ Figure out what additional information we need in: + ]]> It works by defining a single route, called - start, which consists of a sequence of three + start, which consists of a sequence of four filters. The first and last of these are included by reference: their <filter> elements have refid attributes that refer to filters defined @@ -1035,16 +1063,23 @@ Figure out what additional information we need in: middle filter is included inline in the route. - The three filters in the route are as follows: first, a + The four filters in the route are as follows: first, a frontend_net filter accepts Z39.50 requests from any host on port 9000; then these requests are passed through a log filter that emits a message for each request; they are then fed into a z3950_client - filter, which forwards the requests to the client-specified - back-end Z39.509 server. When the response arrives, it is handed + filter, which forwards all Z39.50 requests to the client-specified + back-end Z39.509 server. Those Z39.50 packages are returned by the + z3950_client filter, with the response data + filled by the external Z39.50 server targeted. + All non-Z39.50 packages are passed through to the + bounce filter, which defitely bounces + everything, including fish, bananas, cold pyjamas, + mutton, beef and trout packages. + When the response arrives, it is handed back to the log filter, which emits another - message; and then to the front-end filter, which returns the - response to the client. + message; and then to the frontend_net filter, + which returns the response to the client. @@ -1166,6 +1201,7 @@ Figure out what additional information we need in: 30 + ]]> @@ -1518,7 +1554,7 @@ Z> The virtual base class of all filters. The filter API is, on the surface at least, extremely simple: two methods. - configure() is passed a DOM tree representing + configure() is passed an XML DOM tree representing that part of the configuration file that pertains to this filter instance, and is expected to walk that tree extracting relevant information. And process() processes a diff --git a/doc/bounce.xml b/doc/bounce.xml new file mode 100644 index 0000000..bdeeab1 --- /dev/null +++ b/doc/bounce.xml @@ -0,0 +1,66 @@ + +]> + + + + bounce + 3mp + Metaproxy Module + + + + bounce + bouncing package sink for all kind of metaproxy packages + + + DESCRIPTION + + A sink that swallows all packages, and returns them almost + unprocessed. It never sends any package of any type further down + the row, but sets Z39.50 packages to Z_Close, and HTTP_Request + packages to HTTP_Response err code 400 packages, and adds a + suitable bounce message. The bounce filter is added at the end of + filter routes to prevent infinite hanging of yet unprocessed + packages. When a package is bounced, the client connection is + closed as well. + + + + EXAMPLES + + A typical configuration looks like this: + +]]> + + + + + SEE ALSO + + + metaproxy + 1 + + + + + ©right; + + + -- 1.7.10.4