ruby-brs 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 779dc2709fa1dc4c1316cafb41ec7ca289ddab6e3e93302c8c9d730d5e13062c
+  data.tar.gz: b9e44118ae67ccc3ddc80a4976c946ef1b4d0801192b5b2f7f286bbf7b6f1446
+SHA512:
+  metadata.gz: fd2f3127fa61d8e5d1523c331edbb96823976622d81ba61ff4d10965ed9f536773a2abbea59c3fd1a03b9d6df9b4fbe9662a0d47cdaed5aa19e481544cc9952a
+  data.tar.gz: d487532c19995e7307f68b1b5ccc091e9445e02b8a53c3c9039765e8fbb6dd11960563d6860aaba236dc7b7b424674d12f471163cd52940511dbd4803799a250

data/AUTHORS

@@ -0,0 +1 @@
+Andrew Aladjev

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 AUTHORS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,339 @@
+# Ruby bindings for brotli library
+
+[![Travis build status](https://travis-ci.org/andrew-aladev/ruby-brs.svg?branch=master)](https://travis-ci.org/andrew-aladev/ruby-brs)
+[![AppVeyor build status](https://ci.appveyor.com/api/projects/status/github/andrew-aladev/ruby-brs?branch=master&svg=true)](https://ci.appveyor.com/project/andrew-aladev/ruby-brs/branch/master)
+
+See [brotli library](https://github.com/google/brotli).
+
+## Installation
+
+Please install brotli library first.
+
+```sh
+gem install ruby-brs
+```
+
+You can build it from source.
+
+```sh
+rake gem
+gem install pkg/ruby-brs-*.gem
+```
+
+## Usage
+
+There are simple APIs: `String` and `File`. Also you can use generic streaming API: `Stream::Writer` and `Stream::Reader`.
+
+```ruby
+require "brs"
+
+data = BRS::String.compress "sample string"
+puts BRS::String.decompress(data)
+
+BRS::File.compress "file.txt", "file.txt.br"
+BRS::File.decompress "file.txt.br", "file.txt"
+
+BRS::Stream::Writer.open("file.txt.br") { |writer| writer << "sample string" }
+puts BRS::Stream::Reader.open("file.txt.br") { |reader| reader.read }
+```
+
+You can create and read `tar.br` archives with `minitar` for example.
+
+```ruby
+require "brs"
+require "minitar"
+
+BRS::Stream::Writer.open "file.tar.br" do |writer|
+  Minitar::Writer.open writer do |tar|
+    tar.add_file_simple "file", :data => "sample string"
+  end
+end
+
+BRS::Stream::Reader.open "file.tar.br" do |reader|
+  Minitar::Reader.open reader do |tar|
+    tar.each_entry do |entry|
+      puts entry.name
+      puts entry.read
+    end
+  end
+end
+```
+
+## Options
+
+Each API supports several options:
+
+```
+:source_buffer_length
+:destination_buffer_length
+```
+
+There are internal buffers for compressed and decompressed data.
+For example you want to use 1 KB as source buffer length for compressor - please use 256 B as destination buffer length.
+You want to use 256 B as source buffer length for decompressor - please use 1 KB as destination buffer length.
+
+Values: 0 - infinity, default value: 0.
+0 means automatic buffer length selection.
+
+```
+:mode
+```
+
+Values: [`:text`, `:font`, `:generic`], default value: `:generic`.
+
+```
+:quality
+```
+
+Values: 0 - 11, default value: 11.
+
+```
+:lgwin
+```
+
+Values: 10 - 24, default value: 22.
+
+```
+:lgblock
+```
+
+Values: 16 - 24, default value: none.
+
+```
+:disable_literal_context_modeling
+```
+
+Values: true/false, default value: false.
+
+```
+:disable_ring_buffer_reallocation
+```
+
+Values: true/false, default value: false.
+
+```
+:size_hint
+```
+
+Values: 0 - infinity, default value: 0.
+
+```
+:large_window
+```
+
+Values: true/false, default value: false.
+
+Please read brotli docs for more info about options.
+
+Possible compressor options:
+```
+:mode
+:quality
+:lgwin
+:lgblock
+:disable_literal_context_modeling
+:size_hint
+:large_window
+```
+
+Possible decompressor options:
+```
+:disable_ring_buffer_reallocation
+:large_window
+```
+
+Example:
+
+```ruby
+require "brs"
+
+data = BRS::String.compress "sample string", :quality => 5
+puts BRS::String.decompress(data, :disable_ring_buffer_reallocation => true)
+```
+
+Default options are compatible with HTTP (`Content-Encoding: br`):
+
+```ruby
+require "brs"
+require "sinatra"
+
+get "/" do
+  headers["Content-Encoding"] = "br"
+  BRS::String.compress "sample string"
+end
+```
+
+## String
+
+String maintains destination buffer only, so it accepts `destination_buffer_length` option only.
+
+```
+::compress(source, options = {})
+::decompress(source, options = {})
+```
+
+`source` is a source string.
+
+## File
+
+File maintains both source and destination buffers, it accepts both `source_buffer_length` and `destination_buffer_length` options.
+
+```
+::compress(source, destination, options = {})
+::decompress(source, destination, options = {})
+```
+
+`source` and `destination` are file pathes.
+
+## Stream::Writer
+
+Its behaviour is similar to builtin [`Zlib::GzipWriter`](https://ruby-doc.org/stdlib-2.6.1/libdoc/zlib/rdoc/Zlib/GzipWriter.html).
+
+Writer maintains destination buffer only, so it accepts `destination_buffer_length` option only.
+
+```
+::open(file_path, options = {}, :external_encoding => nil, :transcode_options => {}, &block)
+```
+
+Open file path and create stream writer associated with opened file.
+Data will be transcoded to `:external_encoding` using `:transcode_options` before compressing.
+
+```
+::new(destination_io, options = {}, :external_encoding => nil, :transcode_options => {})
+```
+
+Create stream writer associated with destination io.
+Data will be transcoded to `:external_encoding` using `:transcode_options` before compressing.
+
+```
+#set_encoding(external_encoding, nil, transcode_options)
+```
+
+Set another encodings, `nil` is just for compatibility with `IO`.
+
+```
+#io
+#to_io
+#stat
+#external_encoding
+#transcode_options
+#pos
+#tell
+```
+
+See [`IO`](https://ruby-doc.org/core-2.6.1/IO.html) docs.
+
+```
+#write(*objects)
+#flush
+#rewind
+#close
+#closed?
+```
+
+See [`Zlib::GzipWriter`](https://ruby-doc.org/stdlib-2.6.1/libdoc/zlib/rdoc/Zlib/GzipWriter.html) docs.
+
+```
+#write_nonblock(object, *options)
+#flush_nonblock(*options)
+#rewind_nonblock(*options)
+#close_nonblock(*options)
+```
+
+Special asynchronous methods missing in `Zlib::GzipWriter`.
+`rewind` wants to `close`, `close` wants to `write` something and `flush`, `flush` want to `write` something.
+So it is possible to have asynchronous variants for these synchronous methods.
+Behaviour is the same as `IO#write_nonblock` method.
+
+```
+#<<(object)
+#print(*objects)
+#printf(*args)
+#putc(object, encoding: ::Encoding::BINARY)
+#puts(*objects)
+```
+
+Typical helpers, see [`Zlib::GzipWriter`](https://ruby-doc.org/stdlib-2.6.1/libdoc/zlib/rdoc/Zlib/GzipWriter.html) docs.
+
+## Stream::Reader
+
+Its behaviour is similar to builtin [`Zlib::GzipReader`](https://ruby-doc.org/stdlib-2.6.1/libdoc/zlib/rdoc/Zlib/GzipReader.html).
+
+Reader maintains both source and destination buffers, it accepts both `source_buffer_length` and `destination_buffer_length` options.
+
+```
+::open(file_path, options = {}, :external_encoding => nil, :internal_encoding => nil, :transcode_options => {}, &block)
+```
+
+Open file path and create stream reader associated with opened file.
+Data will be force encoded to `:external_encoding` and transcoded to `:internal_encoding` using `:transcode_options` after decompressing.
+
+```
+::new(source_io, options = {}, :external_encoding => nil, :internal_encoding => nil, :transcode_options => {})
+```
+
+Create stream reader associated with source io.
+Data will be force encoded to `:external_encoding` and transcoded to `:internal_encoding` using `:transcode_options` after decompressing.
+
+```
+#set_encoding(external_encoding, internal_encoding, transcode_options)
+```
+
+Set another encodings.
+
+```
+#io
+#to_io
+#stat
+#external_encoding
+#internal_encoding
+#transcode_options
+#pos
+#tell
+```
+
+See [`IO`](https://ruby-doc.org/core-2.6.1/IO.html) docs.
+
+```
+#read(bytes_to_read = nil, out_buffer = nil)
+#eof?
+#rewind
+#close
+#closed?
+```
+
+See [`Zlib::GzipReader`](https://ruby-doc.org/stdlib-2.6.1/libdoc/zlib/rdoc/Zlib/GzipReader.html) docs.
+
+```
+#readpartial(bytes_to_read = nil, out_buffer = nil)
+#read_nonblock(bytes_to_read, out_buffer = nil, *options)
+```
+
+See [`IO`](https://ruby-doc.org/core-2.6.1/IO.html) docs.
+
+```
+#getbyte
+#each_byte(&block)
+#readbyte
+#ungetbyte(byte)
+
+#getc
+#readchar
+#each_char(&block)
+#ungetc(char)
+
+#lineno
+#lineno=
+#gets(separator = $OUTPUT_RECORD_SEPARATOR, limit = nil)
+#readline
+#readlines
+#each(&block)
+#each_line(&block)
+#ungetline(line)
+```
+
+Typical helpers, see [`Zlib::GzipReader`](https://ruby-doc.org/stdlib-2.6.1/libdoc/zlib/rdoc/Zlib/GzipReader.html) docs.
+
+## License
+
+MIT license, see LICENSE and AUTHORS.

data/ext/brs_ext/buffer.c

@@ -0,0 +1,16 @@
+// Ruby bindings for brotli library.
+// Copyright (c) 2019 AUTHORS, MIT License.
+
+#include "brs_ext/buffer.h"
+
+#include "ruby.h"
+
+void brs_ext_buffer_exports(VALUE root_module)
+{
+  VALUE option = rb_define_module_under(root_module, "Buffer");
+
+  rb_define_const(option, "DEFAULT_SOURCE_BUFFER_LENGTH_FOR_COMPRESSOR", UINT2NUM(BRS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_COMPRESSOR));
+  rb_define_const(option, "DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_COMPRESSOR", UINT2NUM(BRS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_COMPRESSOR));
+  rb_define_const(option, "DEFAULT_SOURCE_BUFFER_LENGTH_FOR_DECOMPRESSOR", UINT2NUM(BRS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_DECOMPRESSOR));
+  rb_define_const(option, "DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_DECOMPRESSOR", UINT2NUM(BRS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_DECOMPRESSOR));
+}

data/ext/brs_ext/buffer.h

@@ -0,0 +1,17 @@
+// Ruby bindings for brotli library.
+// Copyright (c) 2019 AUTHORS, MIT License.
+
+#if !defined(BRS_EXT_BUFFER_H)
+#define BRS_EXT_BUFFER_H
+
+#include "ruby.h"
+
+#define BRS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_COMPRESSOR (1 << 18)      // 256 KB
+#define BRS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_COMPRESSOR (1 << 16) // 64 KB
+
+#define BRS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_DECOMPRESSOR (1 << 16)      // 64 KB
+#define BRS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_DECOMPRESSOR (1 << 18) // 256 KB
+
+void brs_ext_buffer_exports(VALUE root_module);
+
+#endif // BRS_EXT_BUFFER_H

data/ext/brs_ext/common.h

@@ -0,0 +1,13 @@
+// Ruby bindings for brotli library.
+// Copyright (c) 2019 AUTHORS, MIT License.
+
+#if !defined(BRS_EXT_COMMON_H)
+#define BRS_EXT_COMMON_H
+
+#include <stdint.h>
+
+#define BRS_EXT_MODULE_NAME "BRS"
+
+typedef uint_fast8_t brs_ext_result_t;
+
+#endif // BRS_EXT_COMMON_H

data/ext/brs_ext/error.c

@@ -0,0 +1,78 @@
+// Ruby bindings for brotli library.
+// Copyright (c) 2019 AUTHORS, MIT License.
+
+#include "brs_ext/error.h"
+
+#include <brotli/decode.h>
+
+#include "brs_ext/common.h"
+#include "ruby.h"
+
+brs_ext_result_t brs_ext_get_decompressor_error(BrotliDecoderErrorCode error_code)
+{
+  switch (error_code) {
+    case BROTLI_DECODER_ERROR_FORMAT_EXUBERANT_NIBBLE:
+    case BROTLI_DECODER_ERROR_FORMAT_RESERVED:
+    case BROTLI_DECODER_ERROR_FORMAT_EXUBERANT_META_NIBBLE:
+    case BROTLI_DECODER_ERROR_FORMAT_SIMPLE_HUFFMAN_ALPHABET:
+    case BROTLI_DECODER_ERROR_FORMAT_SIMPLE_HUFFMAN_SAME:
+    case BROTLI_DECODER_ERROR_FORMAT_CL_SPACE:
+    case BROTLI_DECODER_ERROR_FORMAT_HUFFMAN_SPACE:
+    case BROTLI_DECODER_ERROR_FORMAT_CONTEXT_MAP_REPEAT:
+    case BROTLI_DECODER_ERROR_FORMAT_BLOCK_LENGTH_1:
+    case BROTLI_DECODER_ERROR_FORMAT_BLOCK_LENGTH_2:
+    case BROTLI_DECODER_ERROR_FORMAT_TRANSFORM:
+    case BROTLI_DECODER_ERROR_FORMAT_DICTIONARY:
+    case BROTLI_DECODER_ERROR_FORMAT_WINDOW_BITS:
+    case BROTLI_DECODER_ERROR_FORMAT_PADDING_1:
+    case BROTLI_DECODER_ERROR_FORMAT_PADDING_2:
+    case BROTLI_DECODER_ERROR_FORMAT_DISTANCE:
+      return BRS_EXT_ERROR_DECOMPRESSOR_CORRUPTED_SOURCE;
+    case BROTLI_DECODER_ERROR_ALLOC_CONTEXT_MODES:
+    case BROTLI_DECODER_ERROR_ALLOC_TREE_GROUPS:
+    case BROTLI_DECODER_ERROR_ALLOC_CONTEXT_MAP:
+    case BROTLI_DECODER_ERROR_ALLOC_RING_BUFFER_1:
+    case BROTLI_DECODER_ERROR_ALLOC_RING_BUFFER_2:
+    case BROTLI_DECODER_ERROR_ALLOC_BLOCK_TYPE_TREES:
+      return BRS_EXT_ERROR_ALLOCATE_FAILED;
+    default:
+      return BRS_EXT_ERROR_UNEXPECTED;
+  }
+}
+
+static inline NORETURN(void raise(const char* name, const char* description))
+{
+  VALUE module = rb_define_module(BRS_EXT_MODULE_NAME);
+  VALUE error  = rb_const_get(module, rb_intern(name));
+  rb_raise(error, "%s", description);
+}
+
+void brs_ext_raise_error(brs_ext_result_t result)
+{
+  switch (result) {
+    case BRS_EXT_ERROR_ALLOCATE_FAILED:
+      raise("AllocateError", "allocate error");
+    case BRS_EXT_ERROR_VALIDATE_FAILED:
+      raise("ValidateError", "validate error");
+
+    case BRS_EXT_ERROR_USED_AFTER_CLOSE:
+      raise("UsedAfterCloseError", "used after closed");
+    case BRS_EXT_ERROR_NOT_ENOUGH_SOURCE_BUFFER:
+      raise("NotEnoughSourceBufferError", "not enough source buffer");
+    case BRS_EXT_ERROR_NOT_ENOUGH_DESTINATION_BUFFER:
+      raise("NotEnoughDestinationBufferError", "not enough destination buffer");
+    case BRS_EXT_ERROR_DECOMPRESSOR_CORRUPTED_SOURCE:
+      raise("DecompressorCorruptedSourceError", "decompressor received corrupted source");
+
+    case BRS_EXT_ERROR_ACCESS_IO:
+      raise("AccessIOError", "failed to access IO");
+    case BRS_EXT_ERROR_READ_IO:
+      raise("ReadIOError", "failed to read IO");
+    case BRS_EXT_ERROR_WRITE_IO:
+      raise("WriteIOError", "failed to write IO");
+
+    default:
+      // BRS_EXT_ERROR_UNEXPECTED
+      raise("UnexpectedError", "unexpected error");
+  }
+}

data/ext/brs_ext/error.h

@@ -0,0 +1,34 @@
+// Ruby bindings for brotli library.
+// Copyright (c) 2019 AUTHORS, MIT License.
+
+#if !defined(BRS_EXT_ERROR_H)
+#define BRS_EXT_ERROR_H
+
+#include <brotli/decode.h>
+
+#include "brs_ext/common.h"
+#include "ruby.h"
+
+// Results for errors listed in "lib/brs/error" used in c extension.
+
+enum {
+  BRS_EXT_ERROR_ALLOCATE_FAILED = 1,
+  BRS_EXT_ERROR_VALIDATE_FAILED,
+
+  BRS_EXT_ERROR_USED_AFTER_CLOSE,
+  BRS_EXT_ERROR_NOT_ENOUGH_SOURCE_BUFFER,
+  BRS_EXT_ERROR_NOT_ENOUGH_DESTINATION_BUFFER,
+  BRS_EXT_ERROR_DECOMPRESSOR_CORRUPTED_SOURCE,
+
+  BRS_EXT_ERROR_ACCESS_IO,
+  BRS_EXT_ERROR_READ_IO,
+  BRS_EXT_ERROR_WRITE_IO,
+
+  BRS_EXT_ERROR_UNEXPECTED
+};
+
+brs_ext_result_t brs_ext_get_decompressor_error(BrotliDecoderErrorCode error_code);
+
+NORETURN(void brs_ext_raise_error(brs_ext_result_t result));
+
+#endif // BRS_EXT_ERROR_H