view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

It will deflate if if the HTTP client acceptable encoding is `deflate` and [IO::Compress::Deflate](https://metacpan.org/pod/IO%3A%3ACompress%3A%3ADeflate) is installed.

If none of the above is possible, the data will be returned uncompressed.

Note that the HTTP header `Vary` will be added the `Accept-Encoding` value.

## push\_handlers

Returns the values from ["push\_handlers" in Apache2::Server](https://metacpan.org/pod/Apache2%3A%3AServer#push_handlers) by passing it whatever arguments were provided.

## reply

This takes an HTTP code and a message, or an exception object such as [Module::Generic::Exception](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3AException) or any other object that supports the `code` and `message` method, or just a hash referenc...

    { "error": { "code": 400, "message": "Some error" } }

It will json encode the returned data and print it out back to the client after setting the HTTP returned code.

If a `cleanup` hash property is provided with a callback code reference as a value, it will be set as a cleanup callback by calling `$r->pool->cleanup_register`. See [https://perl.apache.org/docs/2.0/user/handlers/http.html#PerlCleanupHandler](https:...

The [Apache2::API](https://metacpan.org/pod/Apache2%3A%3AAPI) object will be passed as the first and only argument to the callback routine.

## reply\_sse

Special reply for Server-Sent Event that need to close the connection if there was an error.

It takes the same arguments as ["reply"](#reply), call ["reply"](#reply), and if the return code is an HTTP error, it will close the HTTP connection.

## request()

Returns the [Apache2::API::Request](https://metacpan.org/pod/Apache2%3A%3AAPI%3A%3ARequest) object. This object is set upon instantiation.

## response

Returns the [Apache2::API::Response](https://metacpan.org/pod/Apache2%3A%3AAPI%3A%3AResponse) object. This object is set upon instantiation.

## server()

Returns a [Apache2::Server](https://metacpan.org/pod/Apache2%3A%3AServer) object

## server\_version

Tries hard to find out the version number of the Apache server. This returns the value from ["server\_version" in Apache2::API::Request](https://metacpan.org/pod/Apache2%3A%3AAPI%3A%3ARequest#server_version)

## set\_handlers()

Returns the values from ["set\_handlers" in Apache2::Server](https://metacpan.org/pod/Apache2%3A%3AServer#set_handlers) by passing it whatever arguments were provided.

## use\_rfc\_error

Boolean. When true, this will return rfc9457 style error [https://www.rfc-editor.org/rfc/rfc9457.html](https://www.rfc-editor.org/rfc/rfc9457.html)

## warn( @list )

Given a list of string, this sends a warning using ["warn" in Apache2::Log](https://metacpan.org/pod/Apache2%3A%3ALog#warn)

## \_try( $object\_type, $method\_name, @\_ )

Given an object type, a method name and optional parameters, this attempts to call it, passing it whatever arguments were provided and return its return values.

Apache2 methods are designed to die upon error, whereas our model is based on returning `undef` and setting an exception with [Module::Generic::Exception](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3AException), because we believe that only the ...

# CLASS FUNCTIONS

## apr1\_md5

    my $md5_password = apr1_md5( $clear_password );
    my $md5_password = apr1_md5( $clear_password, $salt );

This class function is exported by default.

It takes a clear password, and optionally a salt, and returns an Apache md5 encoded password.

This function merely instantiates a new [Apache2::API::Password](https://metacpan.org/pod/Apache2%3A%3AAPI%3A%3APassword) object, and calls the method [hash](https://metacpan.org/pod/Apache2%3A%3AAPI%3A%3APassword#hash) to return the encoded password...

The password returned is suitable to be used and saved in an Apache password file used in web basic authentication.

Upon error, this will die.

# CONSTANTS

`mod_perl` provides constants through [Apache2::Constant](https://metacpan.org/pod/Apache2%3A%3AConstant) and [APR::Constant](https://metacpan.org/pod/APR%3A%3AConstant). [Apache2::API](https://metacpan.org/pod/Apache2%3A%3AAPI) makes all those const...

    use Apache2::API;
    say Apache2::Const::HTTP_BAD_REQUEST; # 400

You can import constants into your namespace by specifying them when loading [Apache2::API](https://metacpan.org/pod/Apache2%3A%3AAPI), such as:

    use Apache2::API qw( HTTP_BAD_REQUEST );
    say HTTP_BAD_REQUEST; # 400

Be careful, however, that there are over 400 Apache2 constants and some common constant names in [Apache2::Constant](https://metacpan.org/pod/Apache2%3A%3AConstant) and [APR::Constant](https://metacpan.org/pod/APR%3A%3AConstant), so it is recommended...

Some constants are special like `OK`, `DECLINED` or `DECLINE_CMD`

Apache [underlines](https://perl.apache.org/docs/2.0/user/handlers/http.html#toc_HTTP_Request_Cycle_Phases) that "all handlers in the chain will be run as long as they return Apache2::Const::OK or Apache2::Const::DECLINED. Because stacked handlers is...

- `Apache2::Const::OK`

    The only value that can be returned by all handlers is `Apache2::Const::OK`, which tells Apache that the handler has successfully finished its execution.

- `Apache2::Const::DECLINED`

    This indicates success, but it's only relevant for phases of type RUN\_FIRST (`PerlProcessConnectionHandler`, `PerlTransHandler`, `PerlMapToStorageHandler`, `PerlAuthenHandler`, `PerlAuthzHandler`, `PerlTypeHandler`, `PerlResponseHandler`

    Apache2 [documentation explains](https://perl.apache.org/docs/2.0/api/Apache2/RequestRec.html#toc_C_allowed_) that "generally modules should `Apache2::Const::DECLINED` any request methods they do not handle."

- `Apache2::Const::DONE`

    This "tells Apache to stop the normal HTTP request cycle and fast forward to the PerlLogHandler,"

Check [Apache documentation on handler return value](https://perl.apache.org/docs/2.0/user/handlers/intro.html#toc_Handler_Return_Values) for more information.

# INSTALLATION

As usual, to install this module, you can do:

    perl Makefile.PL
    make
    make test
    # or