Remove Transform base class

With sufficient squinting, Transform provided an abstract base
interface that covered both cipher modes and compression algorithms.
However it mapped on neither of them particularly well. In addition
this API had the same problem that has made me dislike the Pipe/Filter
API: given a Transform&, what does it do when you put bits in? Maybe
it encrypts. Maybe it compresses. It's a floor wax and a dessert topping!

Currently the Cipher_Mode interface is left mostly unchanged, with the
APIs previously on Transform just moved down the type hierarchy.  I
think there are some definite improvements possible here, wrt handling
of in-place encryption, but left for a later commit.

The compression API is split into two types, Compression_Algorithm and
Decompression_Algorithm. Compression_Algorithm's start() call takes
the compression level, allowing varying compressions with a single
object. And flushing the compression state is moved to a bool param on
`Compression_Algorithm::update`. All the nonsense WRT compression
algorithms having zero length nonces, input granularity rules, etc
as a result of using the Transform interface goes away.

1 files changed, 63 insertions, 27 deletions

diff --git a/doc/manual/compression.rst b/doc/manual/compression.rst
index c58ba58a6..808b7f0dc 100644
--- a/doc/manual/compression.rst
+++ b/doc/manual/compression.rst
@@ -9,39 +9,75 @@ formats), bzip2, and lzma.
    You should always compress *before* you encrypt, because encryption seeks to
    hide the redundancy that compression is supposed to try to find and remove.
 
-All compressors provide the `Transform` interface through a subclass
-`Compression_Transform` (defined in compression.h). The compression algorithms
-have some limitations in terms of the standard API, in particular the
-`output_length` function simply throws an exception since the value cannot be
-determined merely from the input length for such an algorithm.
-
-The transformations work much like any other - calling `update` on a vector
-returns the (de)compressed result, calling `finish` completes the computation.
-All (de)compression algorithms will accept inputs of any size
-(update_granularity is 1) and do not require any final data be saved to be
-passed to `finish`.
-
-On `Compression_Transform` an additional function function `flush` is available
-which (in addition to always acting as equivalent to an `update`) signals the
-compression function to flush as much output as possible immediately, regardless
-of considerations of compression ratio. Any compressor or decompressor may
-ignore this and treat it as equivalent to a normal update.
+Compression is done through the ``Compression_Algorithm`` and
+``Decompression_Algorithm`` classes, both defined in `compression.h`
+
+Compression and decompression both work in three stages: starting a
+message (``start``), continuing to process it (``update``), and then
+finally completing processing the stream (``finish``).
+
+.. cpp:class:: Compression_Algorithm
+
+  .. cpp:function:: void start(size_t level)
+
+       Initialize the compression engine. This must be done before calling
+       ``update`` or ``finish``. The meaning of the `level` parameter varies by
+       the algorithm but generally takes a value between 1 and 9, with higher
+       values implying typically better compression from and more memory and/or
+       CPU time consumed by the compression process. The decompressor can always
+       handle input from any compressor.
+
+  .. cpp:function::  void update(secure_vector<byte>& buf, \
+                                 size_t offset = 0, bool flush = false)
+
+       Compress the material in the in/out parameter ``buf``. The leading
+       ``offset`` bytes of ``buf`` are ignored and remain untouched; this can be
+       useful for ignoring packet headers.  If ``flush`` is true, the
+       compression state is flushed, allowing the decompressor to recover the
+       entire message up to this point without having the see the rest of the
+       compressed stream.
+
+   .. cpp::function:: void finish(secure_vector<byte>& buf, size_t offset = 0)
+
+       Finish compressing a message. The ``buf`` and ``offset`` parameters are
+       treated as in ``update``. It is acceptable to call ``start`` followed by
+       ``finish`` with the entire message, without any intervening call to
+       ``update``.
+
+.. cpp:class:: Decompression_Algorithm
+
+  .. cpp:function:: void start()
+
+       Initialize the decompression engine. This must be done before calling
+       ``update`` or ``finish``. No level is provided here; the decompressor
+       can accept input generated by any compression parameters.
+
+  .. cpp:function::  void update(secure_vector<byte>& buf, \
+                                 size_t offset = 0)
+
+       Decompress the material in the in/out parameter ``buf``. The leading
+       ``offset`` bytes of ``buf`` are ignored and remain untouched; this can be
+       useful for ignoring packet headers.
+
+       This function may throw if the data seems to be invalid.
+
+   .. cpp::function:: void finish(secure_vector<byte>& buf, size_t offset = 0)
+
+       Finish decompressing a message. The ``buf`` and ``offset`` parameters are
+       treated as in ``update``. It is acceptable to call ``start`` followed by
+       ``finish`` with the entire message, without any intervening call to
+       ``update``.
+
+       This function may throw if the data seems to be invalid.
 
 The easiest way to get a compressor is via the functions
 
-.. cpp:function:: Compression_Transform* make_compressor(std::string type, size_t level)
-.. cpp:function:: Compression_Transform* make_decompressor(std::string type)
+.. cpp:function:: Compression_Algorithm* make_compressor(std::string type)
+.. cpp:function:: Decompression_Algorithm* make_decompressor(std::string type)
 
 Supported values for `type` include `zlib` (raw zlib with no checksum),
 `deflate` (zlib's deflate format), `gzip`, `bz2`, and `lzma`. A null pointer
-will be returned if the algorithm is unavailable. The meaning of the `level`
-parameter varies by the algorithm but generally takes a value between 1 and 9,
-with higher values implying typically better compression from and more memory
-and/or CPU time consumed by the compression process. The decompressor can always
-handle input from any compressor.
-
-As with any consumer of complex formats, a decompressor may throw an exception
-(from either `update` or `finish`) if the input is invalid or corrupt.
+will be returned if the algorithm is unavailable.
 
 To use a compression algorithm in a `Pipe` use the adaptor types
 `Compression_Filter` and `Decompression_Filter` from `comp_filter.h`. The