Add ZStandard compression

Author: thekid

src/main/php/io/streams/Compression.class.php

@@ -1,6 +1,6 @@
 <?php namespace io\streams;
 
-use io\streams\compress\{Algorithm, Algorithms, None, Brotli, Bzip2, Gzip};
+use io\streams\compress\{Algorithm, Algorithms, None, Brotli, Bzip2, Gzip, ZStandard};
 use lang\MethodNotImplementedException;
 
 /**
@@ -22,7 +22,7 @@ static function __static() {
     self::$NONE= new None();
 
     // Register known algorithms included in this library
-    self::$algorithms= (new Algorithms())->add(new Gzip(), new Bzip2(), new Brotli());
+    self::$algorithms= (new Algorithms())->add(new Gzip(), new Bzip2(), new Brotli(), new ZStandard());
   }
 
   /**

src/main/php/io/streams/compress/ZStandard.class.php

@@ -0,0 +1,34 @@
+<?php namespace io\streams\compress;
+
+use io\streams\{InputStream, OutputStream, Compression};
+
+class ZStandard extends Algorithm {
+
+  /** Returns whether this algorithm is supported in the current setup */
+  public function supported(): bool { return extension_loaded('zstd'); }
+
+  /** Returns the algorithm's name */
+  public function name(): string { return 'zstandard'; }
+
+  /** Returns the algorithm's HTTP Content-Encoding token */
+  public function token(): string { return 'zstd'; }
+
+  /** Returns the algorithm's common file extension, including a leading "." */
+  public function extension(): string { return '.zstd'; }
+
+  /** Maps fastest, default and strongest levels */
+  public function level(int $select): int {
+    static $levels= [Compression::FASTEST => 1, Compression::DEFAULT => 3, Compression::STRONGEST => 22];
+    return $levels[$select] ?? $select;
+  }
+
+  /** Opens an input stream for reading */
+  public function open(InputStream $in): InputStream {
+    return new ZStandardInputStream($in);
+  }
+
+  /** Opens an output stream for writing */
+  public function create(OutputStream $out, int $level= Compression::DEFAULT): OutputStream {
+    return new ZStandardOutputStream($out, $this->level($level));
+  }
+}

src/main/php/io/streams/compress/ZStandardInputStream.class.php

@@ -0,0 +1,82 @@
+<?php namespace io\streams\compress;
+
+use io\IOException;
+use io\streams\InputStream;
+
+/**
+ * ZStandard input stream
+ *
+ * @ext  zstd
+ * @test io.streams.compress.unittest.BrotliInputStreamTest
+ * @see  https://github.com/kjdev/php-ext-zstd
+ */
+class ZStandardInputStream implements InputStream {
+  private $in;
+  private $buffer= null, $position= 0;
+
+  /**
+   * Creates a new compressing output stream
+   *
+   * @param  io.streams.InputStream $in The stream to read from
+   */
+  public function __construct(InputStream $in) {
+    $this->in= $in;
+  }
+
+  /** @see https://github.com/kjdev/php-ext-zstd/issues/64 */
+  private function buffer() {
+    if (null === $this->buffer) {
+      $compressed= '';
+      while ($this->in->available()) {
+        $compressed.= $this->in->read();
+      }
+
+      $this->buffer= zstd_uncompress($compressed);
+      if (false === $this->buffer) {
+        $e= new IOException('Failed to uncompress');
+        \xp::gc(__FILE__);
+        throw $e;
+      }
+    }
+    return $this->buffer;
+  }
+
+  /**
+   * Read a string
+   *
+   * @param   int limit default 8192
+   * @return  string
+   */
+  public function read($limit= 8192) {
+    $chunk= substr($this->buffer(), $this->position, $limit);
+    $this->position+= strlen($chunk);
+    return $chunk;
+  }
+
+  /**
+   * Returns the number of bytes that can be read from this stream 
+   * without blocking.
+   *
+   * @return int
+   */
+  public function available() {
+    return strlen($this->buffer()) - $this->position;
+  }
+
+  /**
+   * Close this buffer.
+   *
+   * @return void
+   */
+  public function close() {
+    $this->buffer= null;
+    $this->in->close();
+  }
+  
+  /**
+   * Destructor. Ensures output stream is closed.
+   */
+  public function __destruct() {
+    $this->close();
+  }
+}

src/main/php/io/streams/compress/ZStandardOutputStream.class.php

@@ -0,0 +1,65 @@
+<?php namespace io\streams\compress;
+
+use io\streams\OutputStream;
+use lang\IllegalArgumentException;
+
+/**
+ * ZStandard output stream
+ *
+ * @ext  zstd
+ * @test io.streams.compress.unittest.ZStandardOutputStreamTest
+ * @see  https://github.com/kjdev/php-ext-zstd
+ */
+class ZStandardOutputStream implements OutputStream {
+  private $out, $level;
+  private $buffer= '';
+
+  /**
+   * Creates a new compressing output stream
+   *
+   * @param  io.streams.OutputStream $out The stream to write to
+   * @param  int $level
+   * @throws lang.IllegalArgumentException
+   */
+  public function __construct(OutputStream $out, $level= ZSTD_COMPRESS_LEVEL_DEFAULT) {
+    if ($level < ZSTD_COMPRESS_LEVEL_MIN || $level > ZSTD_COMPRESS_LEVEL_MAX) {
+      throw new IllegalArgumentException('Level must be between '.ZSTD_COMPRESS_LEVEL_MIN.' and '.ZSTD_COMPRESS_LEVEL_MAX);
+    }
+
+    $this->out= $out;
+    $this->level= $level;
+  }
+
+  /**
+   * Write a string
+   *
+   * @param  var $arg
+   * @return void
+   */
+  public function write($arg) {
+    $this->buffer.= $arg;
+  }
+
+  /**
+   * Flush this buffer
+   *
+   * @return void
+   */
+  public function flush() {
+    // NOOP
+  }
+
+  /**
+   * Closes this object. May be called more than once, which may
+   * not fail - that is, if the object is already closed, this 
+   * method should have no effect.
+   *
+   * @return void
+   */
+  public function close() {
+    if (null !== $this->buffer) {
+      $this->out->write(zstd_compress($this->buffer, $this->level));
+      $this->buffer= null;
+    }
+  }
+}

src/test/php/io/streams/compress/unittest/CompressionTest.class.php

@@ -14,14 +14,17 @@ private function names() {
     yield ['gzip', 'gzip'];
     yield ['bzip2', 'bzip2'];
     yield ['brotli', 'brotli'];
+    yield ['zstandard', 'zstandard'];
 
     // File extensions
     yield ['.gz', 'gzip'];
     yield ['.bz2', 'bzip2'];
     yield ['.br', 'brotli'];
+    yield ['.zstd', 'zstandard'];
 
     // HTTP Content-Encoding aliases
     yield ['br', 'brotli'];    
+    yield ['zstd', 'zstandard'];
   }
 
   /** @return iterable */
@@ -38,7 +41,7 @@ public function enumerating_included_algorithms() {
     foreach (Compression::algorithms() as $name => $algorithm) {
       $names[]= $name;
     }
-    Assert::equals(['gzip', 'bzip2', 'brotli'], $names);
+    Assert::equals(['gzip', 'bzip2', 'brotli', 'zstandard'], $names);
   }
 
   #[Test]
@@ -61,17 +64,17 @@ public function algorithms_named($name, $expected) {
     Assert::equals($expected, Compression::algorithms()->named($name)->name());
   }
 
-  #[Test, Values([['gzip', 'zlib'], ['bzip2', 'bzip2'], ['brotli', 'brotli']])]
+  #[Test, Values([['gzip', 'zlib'], ['bzip2', 'bzip2'], ['brotli', 'brotli'], ['zstandard', 'zstd']])]
   public function supported($compression, $extension) {
     Assert::equals(extension_loaded($extension), Compression::algorithms()->named($compression)->supported());
   }
 
-  #[Test, Values([['gzip', 'gzip'], ['bzip2', 'bzip2'], ['brotli', 'br']])]
+  #[Test, Values([['gzip', 'gzip'], ['bzip2', 'bzip2'], ['brotli', 'br'], ['zstandard', 'zstd']])]
   public function token($compression, $expected) {
     Assert::equals($expected, Compression::algorithms()->named($compression)->token());
   }
 
-  #[Test, Values([['gzip', '.gz'], ['bzip2', '.bz2'], ['brotli', '.br']])]
+  #[Test, Values([['gzip', '.gz'], ['bzip2', '.bz2'], ['brotli', '.br'], ['zstandard', '.zstd']])]
   public function extension($compression, $expected) {
     Assert::equals($expected, Compression::algorithms()->named($compression)->extension());
   }

src/test/php/io/streams/compress/unittest/ZStandardInputStreamTest.class.php

@@ -0,0 +1,59 @@
+<?php namespace io\streams\compress\unittest;
+
+use io\IOException;
+use io\streams\MemoryInputStream;
+use io\streams\compress\ZStandardInputStream;
+use test\verify\Runtime;
+use test\{Assert, Test, Values};
+
+#[Runtime(extensions: ['zstd'])]
+class ZStandardInputStreamTest {
+
+  /** @return iterable */
+  private function compressable() {
+    foreach ([ZSTD_COMPRESS_LEVEL_MIN, ZSTD_COMPRESS_LEVEL_DEFAULT, ZSTD_COMPRESS_LEVEL_MAX] as $level) {
+      yield [$level, ''];
+      yield [$level, 'Test'];
+      yield [$level, "GIF89a\x14\x12\x77..."];
+    }
+  }
+
+  #[Test]
+  public function can_create() {
+    new ZStandardInputStream(new MemoryInputStream(''));
+  }
+
+  #[Test]
+  public function read_plain() {
+    $in= new ZStandardInputStream(new MemoryInputStream('Test'));
+    Assert::throws(IOException::class, function() use($in) {
+      $in->read();
+    });
+    $in->close();
+  }
+
+  #[Test, Values(from: 'compressable')]
+  public function read_compressed($level, $bytes) {
+    $in= new ZStandardInputStream(new MemoryInputStream(zstd_compress($bytes, $level)));
+    $read= $in->read();
+    $rest= $in->available();
+    $in->close();
+
+    Assert::equals($bytes, $read);
+    Assert::equals(0, $rest);
+  }
+
+  #[Test, Values([1, 8192, 16384])]
+  public function read_all($length) {
+    $bytes= random_bytes($length);
+    $in= new ZStandardInputStream(new MemoryInputStream(zstd_compress($bytes)));
+
+    $read= '';
+    while ($in->available()) {
+      $read.= $in->read();
+    }
+    $in->close();
+
+    Assert::equals($bytes, $read);
+  }
+}

src/test/php/io/streams/compress/unittest/ZStandardOutputStreamTest.class.php

@@ -0,0 +1,34 @@
+<?php namespace io\streams\compress\unittest;
+
+use io\streams\MemoryOutputStream;
+use io\streams\compress\ZStandardOutputStream;
+use lang\IllegalArgumentException;
+use test\verify\Runtime;
+use test\{Assert, Expect, Test, Values};
+
+#[Runtime(extensions: ['zstd'])]
+class ZStandardOutputStreamTest {
+
+  #[Test]
+  public function can_create() {
+    new ZStandardOutputStream(new MemoryOutputStream());
+  }
+
+  #[Test, Expect(IllegalArgumentException::class)]
+  public function using_invalid_compression_level() {
+    new ZStandardOutputStream(new MemoryOutputStream(), -1);
+  }
+
+  #[Test, Values([1, 3, 22])]
+  public function write($level) {
+    $out= new MemoryOutputStream();
+
+    $fixture= new ZStandardOutputStream($out, $level);
+    $fixture->write('Hello');
+    $fixture->write(' ');
+    $fixture->write('World');
+    $fixture->close();
+
+    Assert::equals('Hello World', zstd_uncompress($out->bytes()));
+  }
+}