[demo] mod_xlate

[Greg Stein <gs...@lyra.org>]

Here is a demo of a character set translation filter. I have no idea how to
actually set up an environment to *do* translations, so I have not been able
to test this whatsoever. I built it by examining code in mod_charset_lite
and buff.c. I am hoping that Jeff or somebody could test it, but even
without that, it is a valid and complete example.

In posting this, I hope to instead demonstrate how a filter would be written
against my proposed patch.

The key to this kind of filter is how to transform a list of buckets into
usable bytes. For example, having a FILE bucket does no good when the xlate
APIs take an input and output buffer. To manage the transformation of
buckets into usuable data, I defined a structure and two functions:

ap_bucket_scan_t:
  This structure holds the context of a scan across a bucket list.

  To get this done, it manages a working buffer, a sub-pool, and an array of
  string pointers to name a few things. The "output" of this structure is
  a pointer/length pair to the current data chunk.

ap_bucket_scan_first():
  Initialize the scan context for a list of buckets, and prepare the ptr/len
  pair for the first chunk of data.

ap_bucket_scan_next():
  Get the next chunk of data (ptr/len pair) for processing.

When the returned pointer is NULL, then the processing is complete.

I've attached three files to this message. An updated ap_filter.h and
filters.c files, and a new mod_xlate.c module.

[ note: these updates to ap_filter.h and filters.c are not in consideration
  for my initial patch. I propose to add them later after their own review
  cycle. While I welcome feedback and discussion on them, please do so while
  considering they are for a second round. Also keep in mind that the
  purpose of this demonstration is to validate the utility of the filtering
  patch. it answers the "does this patch enable filtering?" question. ]

On mod_xlate itself: the filter is implemented in xlate_callback. It simply
sets up a scan and calls xlate_buffer() with each chunk of data. These
chunks are processed into a working buffer (allocated when the filter was
first inserted into the request). Partial input characters are handled by
another smaller buffer.

The scan context manages the "input" buffers for the translation. No copying
occurs in there, but we do allocate a working buffer to hold "printf" style
output and file data. We create a sub-pool for that working buffer and also
to contain an ap_array_header_t of char pointers for ap_rvputs' set of
string arguments.

The printf formatting can theoretically allocate a large buffer. A future
extension would be to rebuild the first/next scan into a callback approach
which builds on ap_vformatter()'s flush function (called when a formatting
buffer is full). Basically, we could format a chunk, call the callback,
format another chunk, etc. That approach does not work with the first/next
style of iteration, but must use a callback. I avoided that for now to avoid
the additional complexity of ap_vformatter, and because that change is
pretty straight-forward from the existing first/next.

Cheers,
-g

-- 
Greg Stein, http://www.lyra.org/