Chapter 4. The Metaproxy Architecture

The Metaproxy architecture is based on three concepts: the package, the route, and the filter.


A package is a request or response, encoded in some protocol, issued by a client, making its way through Metaproxy, sent to or received from a server, or sent back to the client.

The core of a package is the protocol unit - for example, a Z39.50 Init Request or Search Response, or an SRU searchRetrieve URL or Explain Response. In addition to this core, a package also carries some extra information added and used by Metaproxy itself.

In general, packages are doctored as they pass through Metaproxy. For example, when the proxy performs authentication and authorization on a Z39.50 Init request, it removes the authentication credentials from the package so that they are not passed onto the back-end server; and when search-response packages are obtained from multiple servers, they are merged into a single unified package that makes its way back to the client.


Packages make their way through routes, which can be thought of as programs that operate on the package data-type. Each incoming package initially makes its way through a default route, but may be switched to a different route based on various considerations. Routes are made up of sequences of filters (see below).


Filters provide the individual instructions within a route, and effect the necessary transformations on packages. A particular configuration of Metaproxy is essentially a set of filters, described by configuration details and arranged in order, in one or more routes. There are many kinds of filter - about a dozen at the time of writing with more appearing all the time - each performing a specific function and configured by different information.

The word "filter" is sometimes used rather loosely, in two different ways: it may be used to mean a particular type of filter, as when we speak of "the auth_simple filter" or "the multi filter"; or it may be used to be a specific instance of a filter within a Metaproxy configuration. For example, a single configuration will often contain multiple instances of the z3950_client filter. In operational terms, each of these is a separate filter. In practice, context always make it clear which sense of the word "filter" is being used.

Extensibility of Metaproxy is primarily through the creation of plugins that provide new filters. The filter API is small and conceptually simple, but there are many details to master. See the section below on Filters.

Since packages are created and handled by the system itself, and routes are conceptually simple, most of the remainder of this document concentrates on filters. After a brief overview of the filter types follows, along with some thoughts on possible future directions.