NAME

HTTP::Promise::Stream::Brotli - Stream Encoder for Brotli Encoding

SYNOPSIS

    use HTTP::Promise::Stream::Brotli;
    my $s = HTTP::Promise::Stream::Brotli->new || 
        die( HTTP::Promise::Stream::Brotli->error, "\n" );
    $s->encode( $input => $output ) ||
        die( $s->error );
    $s->decode( $input => $output ) || die( $s->error );
    HTTP::Promise::Stream::Brotli::encode_bro( $input => $output ) ||
        die( $HTTP::Promise::Stream::Brotli::BrotliError );
    HTTP::Promise::Stream::Brotli::decode_bro( $input => $output ) ||
        die( $HTTP::Promise::Stream::Brotli::BrotliError );

VERSION

    v0.2.0

DESCRIPTION

This implements an encoding and decoding mechanism for Brotli compression using either of the following on input and output:

filepath

If the parameter is neither a scalar reference nor a file handle, it will be assumed to be a file path.

file handle

This can be a native file handle, or an object oriented one as long as it implements the print or write, and read methods. The read method is expected to return the number of bytes read or undef upon error. The print and write methods are expected to simply return true upon success and undef upon error.

Alternatively, those methods can die and those exceptions wil be caught.

scalar reference

This can be a simple scalar reference, or an object scalar reference.

This module requires IO::Compress::Brotli and IO::Uncompress::Brotli to be installed or it will return an error.

Brotli is described as "Brotli is a generic-purpose lossless compression algorithm that compresses data using a combination of a modern variant of the LZ77 algorithm, Huffman coding and 2nd order context modeling" that is "similar in speed with deflate" and "supported by most web browsers, major web servers, and some CDNs". The specification of its Compressed Data Format is defined in rfc7932.

According to Mozilla, "Brotli provides better compression ratios than gzip and deflate speeds are comparable, but brotli compressing is a slower process than Gzip"

CONSTRUCTOR

new

Creates a new HTTP::Promise::Stream::Brotli object and returns it.

METHODS

decode

This takes 2 arguments: an input and an output. Each one can be either a file path, a file handle, or a scalar reference.

It will decode the Brotli encoded data and write the result into the output.

It returns true upon success and sets an error and return undef upon error.

encode

This takes 2 arguments: an input and an output. Each one can be either a file path, a file handle, or a scalar reference.

It will encode the data into Brotli encoded data and write the result into the output.

It returns true upon success and sets an error and return undef upon error.

CLASS FUNCTIONS

The following class functions are available and can also be exported, such as:

    use HTTP::Promise::Stream::Brotli qw( decode_bro encode_bro );

decode_bro

This takes the same 2 arguments used in "decode": an input and an output. Each one can be either a file path, a file handle, or a scalar reference.

It will decode the Brotli encoded data and write the result into the output.

It returns true upon success, and upon error, it will set the error in the global variable $BrotliError and return undef

    my $decoded = HTTP::Promise::Stream::Brotli::decode_bro( $encoded );
    die( "Something went wrong: $HTTP::Promise::Stream::Brotli::BrotliError\n" if( !defined( $decoded ) );
    print( "Decoded data is: $decoded\n" );

encode_bro

This takes the same 2 arguments used in "encode": an input and an output. Each one can be either a file path, a file handle, or a scalar reference.

It will encode the data into Brotli encoded data and write the result into the output.

It returns true upon success, and upon error, it will set the error in the global variable $BrotliError and return undef

    my $encoded = HTTP::Promise::Stream::Brotli::encode_bro( $data );
    die( "Something went wrong: $HTTP::Promise::Stream::Brotli::BrotliError\n" if( !defined( $encoded ) );
    print( "Encoded data is: $encoded\n" );

is_decoder_installed

Returns true if the module IO::Uncompress::Brotli is installed, false otherwise.

is_encoder_installed

Returns true if the module IO::Compress::Brotli is installed, false otherwise.

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

IO::Compress::Brotli, IO::Uncompress::Brotli

Brotli web page, Brotli Github page

rfc7932

Wikipedia page

caniuse

HTTP::Promise, HTTP::Promise::Request, HTTP::Promise::Response, HTTP::Promise::Message, HTTP::Promise::Entity, HTTP::Promise::Headers, HTTP::Promise::Body, HTTP::Promise::Body::Form, HTTP::Promise::Body::Form::Data, HTTP::Promise::Body::Form::Field, HTTP::Promise::Status, HTTP::Promise::MIME, HTTP::Promise::Parser, HTTP::Promise::IO, HTTP::Promise::Stream, HTTP::Promise::Exception

COPYRIGHT & LICENSE

Copyright(c) 2022 DEGUEST Pte. Ltd.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm HTTP::Promise

perl -MCPAN -e shell
install HTTP::Promise