Stream API

.github/codecov.yml

@@ -0,0 +1,7 @@
+coverage:
+  status:
+    project:
+      default:
+        target: auto   # Use previous coverage as the baseline
+        threshold: 100 # Allow a 100% drop without failing
+        informational: true  # Do not cause CI to fail

README.md

@@ -0,0 +1,27 @@
+# MaxZip
+
+C++ compression framework.
+
+## About
+
+This project is intended to provide an abstract C++ frontend for various 
+compression libraries. Each implementation is exposed through a common 
+API, along with configuration parameters.
+
+## Usage
+
+The API is designed to provide common interfaces for compressing and 
+decompressing data.
+
+### Block API
+
+The block API provides the `compressor` and `decompressor` interfaces, 
+which can be used for one shot processing. This is a clean and simple 
+API, best suited for small to medium payloads where memory usage and 
+IO complexity are not a major concern.
+
+### Streaming API
+
+The streaming API provides the `encoder` and `decoder` interfaces, to 
+allow for incremental data processing. This is preferable when input 
+is either too large, or the underlying IO is segmented.

include/maxzip.hpp

@@ -31,7 +31,6 @@
 
 #include <maxzip/compressor.hpp>
 #include <maxzip/decompressor.hpp>
-#include <maxzip/encoder.hpp>
-#include <maxzip/decoder.hpp>
+#include <maxzip/stream.hpp>
 
 #endif

include/maxzip/common.hpp

@@ -25,6 +25,12 @@
 
 #include <cstdint>
 #include <cstddef>
+#include <functional>
 #include <optional>
 
+namespace maxzip
+{
+
+}
+
 #endif

include/maxzip/compressor.hpp

@@ -29,16 +29,16 @@ namespace maxzip
 {
     /**
      * @class compressor
-     * @brief Abstract base class for block compression
+     * @brief Abstract base class for block compression.
      */
     class compressor
     {
     public:
         /**
-         * @brief Compress a block of data
-         * @param input Pointer to the input data
-         * @param input_size Size of the input data in bytes
-         * @param output Pointer to the output buffer (can be nullptr)
+         * @brief Compress a block of data.
+         * @param input Pointer to the input data.
+         * @param input_size Size of the input data in bytes.
+         * @param output Pointer to the output buffer (can be nullptr).
          * @param output_size Reference to the size of the output buffer on input. If
          * output is nullptr, this will be set to the maximum compressed size.
          * @return The size of the compressed data in bytes, or 0 if output is nullptr.

include/maxzip/decoder.hpp

@@ -35,15 +35,30 @@ namespace maxzip
     class decoder
     {
     public:
-        void init();
-        void update(
-            const uint8_t* input,
+        /**
+         * @brief Initialize the decoder.
+         * @param flush if set, may flush incomplete frames. This is typically ignored,
+         * with the exception of zlib.
+         */
+        virtual void init(bool flush = false) = 0;
+
+        /**
+         * @brief Decompress data stream.
+         *
+         * @param input_func Function to retrieve input buffer.
+         * @param output_func Function to retrieve output buffer.
+         * @param notify_func Function to notify actual output size.
+         * @param flush Whether to flush incomplete frames. This is typically
+         * ignored, with the exception of zlib.
+         */
+        virtual bool decode(
+            const uint8_t *input, 
             size_t input_size,
-            uint8_t* output,
-            size_t& output_size);
-        void finish(
-            uint8_t* output,
-            size_t& output_size);
+            size_t &read_size,
+            uint8_t *output,
+            size_t output_size,
+            size_t &write_size
+        ) = 0;
     };
 
 }

include/maxzip/encoder.hpp

@@ -35,16 +35,31 @@ namespace maxzip
     class encoder
     {
     public:
-        void init();
-        void update(
-            const uint8_t* input, 
-            size_t input_size, 
-            uint8_t* output, 
-            size_t& output_size);
-        void finish(
-            uint8_t* output, 
-            size_t& output_size);
-    };
+        /**
+         * @brief Initialize the encoder state.
+         */
+        virtual void init(bool flush = false) = 0;
+
+        /**
+         * @brief Advance encoder state.
+         * @param input Pointer to input data. If no input is available, this should be nullptr.
+         * @param input_size Size of input data. If no input is available, this should be 0.
+         * @param read_size Size of input data processed.
+         * @param output Pointer to output buffer.
+         * @param output_size Size of output buffer.
+         * @param write_size Size of output data written.
+         * @return true if still processing, false if compression is complete.
+         */
+        virtual bool encode(
+            const uint8_t *input, 
+            size_t input_size,
+            size_t &read_size,
+            uint8_t *output,
+            size_t output_size,
+            size_t &write_size) = 0;
+};
+
+
 }
 
 #endif

include/maxzip/stream.hpp

@@ -0,0 +1,56 @@
+#ifndef MAXZIP_STREAM_HPP
+#define MAXZIP_STREAM_HPP
+
+#include "common.hpp"
+
+namespace maxzip
+{
+    class stream
+    {
+    public:
+        virtual void initialize(
+            bool flush = false) = 0;
+
+        virtual std::pair<size_t, size_t> update(
+            const uint8_t *input,
+            size_t input_size,
+            uint8_t *output,
+            size_t output_size) = 0;
+
+        virtual bool finalize(
+            uint8_t *output,
+            size_t output_size,
+            size_t &write_size) = 0;
+
+        virtual std::pair<size_t, size_t> block_sizes() const = 0;
+    };
+
+    struct brotli_encoder_params
+    {
+        std::optional<int> mode;
+        std::optional<int> quality;
+        std::optional<int> window_size;
+        std::optional<int> block_size;
+        std::optional<bool> literal_context_modeling;
+        std::optional<int> size_hint;
+        std::optional<bool> large_window;
+        std::optional<int> postfix_bits;
+        std::optional<int> num_direct_distance_codes;
+        std::optional<int> stream_offset;
+    };
+
+    struct brotli_decoder_params
+    {
+        std::optional<bool> disable_ring_buffer_reallocation;
+        std::optional<bool> large_window;
+    };
+
+    stream *create_brotli_encoder(
+        const brotli_encoder_params &params);
+
+    stream *create_brotli_decoder(
+        const brotli_decoder_params &params);
+
+}
+
+#endif