Apache2-API
view release on metacpan or search on metacpan
lib/Apache2/API.pm view on Meta::CPAN
{
my $self = shift( @_ );
my $txt = join( '', map( ref( $_ ) eq 'CODE' ? $_->() : $_, @_ ) );
my( $pkg, $file, $line, @otherInfo ) = caller;
my $sub = ( caller( 1 ) )[3];
my $sub2 = substr( $sub, rindex( $sub, '::' ) + 2 );
my $trace = $self->_get_stack_trace();
my $frame = $trace->next_frame;
my $frame2 = $trace->next_frame;
my $r = $self->apache_request;
$txt = sprintf( "$txt called from %s in package %s in file %s at line %d\n%s\n", $frame2->subroutine, $frame->package, $frame->filename, $frame->line, $trace->as_string );
return( $r->warn( $txt ) ) if( $r );
return( CORE::warn( $txt ) );
}
sub _try
{
my $self = shift( @_ );
my $pack = shift( @_ ) || return( $self->error( "No Apache package name was provided to call method" ) );
my $meth = shift( @_ ) || return( $self->error( "No method name was provided to try!" ) );
my $r = Apache2::RequestUtil->request;
# $r->log_error( "Apache2::API::_try to call method \"$meth\" in package \"$pack\"." );
# try-catch
local $@;
my $rv = eval
{
return( $self->$pack->$meth ) if( !scalar( @_ ) );
return( $self->$pack->$meth( @_ ) );
};
if( $@ )
{
return( $self->error( "An error occurred while trying to call Apache ", ucfirst( $pack ), " method \"$meth\": $@" ) );
}
return( $rv );
}
# NOTE: sub FREEZE is inherited
sub STORABLE_freeze { CORE::return( CORE::shift->FREEZE( @_ ) ); }
sub STORABLE_thaw { CORE::return( CORE::shift->THAW( @_ ) ); }
# NOTE: sub THAW is inherited
# NOTE: Apache2::API::Password
package Apache2::API::Password;
use parent qw( Module::Generic );
use strict;
use warnings;
use vars qw( $VERSION $APR1_RE $BCRYPT_RE $SHA_RE );
# Compile the regular expression once
our $APR1_RE = qr/\$apr1\$(?<salt>[.\/0-9A-Za-z]{1,8})\$[.\/0-9A-Za-z]{22}/;
our $BCRYPT_RE = qr/\$2[aby]\$(?<bcrypt_cost>\d{2})\$(?<salt>[A-Za-z0-9.\/]{22})[A-Za-z0-9.\/]{31}/;
our $SHA_RE = qr/\$(?<sha_size>[56])\$(?:rounds=(?<rounds>\d+)\$)?(?<salt>[A-Za-z0-9.\/]{1,16})\$[A-Za-z0-9.\/]+/;
our $VERSION = 'v0.1.1';
sub init
{
my $self = shift( @_ );
my $pwd = shift( @_ );
return( $self->error( "No password was provided." ) ) if( !defined( $pwd ) );
$self->{create} = 0 if( !exists( $self->{create} ) );
# md5 | bcrypt | sha256 | sha512
$self->{algo} = 'md5' if( !exists( $self->{algo} ) );
# 04..31
$self->{bcrypt_cost} = 12 if( !exists( $self->{bcrypt_cost} ) );
# undef => default (5000)
$self->{sha_rounds} = undef if( !exists( $self->{sha_rounds} ) );
# By default, like Apache does, we use Apache md5 algorithm
# Other possibilities are bcrypt (Blowfish)
$self->SUPER::init( @_ ) ||
return( $self->pass_error );
if( $self->{create} )
{
my $hash = $self->make( $pwd ) ||
return( $self->pass_error );
$self->hash( $hash );
}
# Existing hash path: validate by known prefixes, also extract salt into ->salt
elsif( $pwd =~ /\A$APR1_RE\z/ ||
$pwd =~ /\A$BCRYPT_RE\z/ ||
$pwd =~ /\A$SHA_RE\z/ )
{
$self->hash( $pwd );
}
else
{
return( $self->error(
"Value provided is not a recognized hash (APR1/bcrypt/SHA-crypt). " .
"If you want to create one from clear text, use the 'create' option."
) );
}
return( $self );
}
sub algo { return( shift->_set_get_enum({
field => 'algo',
allowed => [qw( md5 bcrypt sha256 sha512 )],
}, @_ ) ); }
sub bcrypt_cost { return( shift->_set_get_scalar({
field => 'bcrypt_cost',
check => sub
{
my( $self, $v ) = @_;
return(1) unless( defined( $v ) );
unless( $v =~ /^\d+$/ &&
$v >= 4 &&
$v <= 31 )
{
return( $self->error( "bcrypt_cost must be between 4 and 31" ) );
}
return(1);
},
}, @_ ) ); }
sub create { return( shift->_set_get_boolean( 'create', @_ ) ); }
sub hash { return( shift->_set_get_scalar({
field => 'hash',
callbacks =>
lib/Apache2/API.pm view on Meta::CPAN
return( $ppr->as_crypt );
}
# Fallback 2: Crypt::Bcrypt
elsif( $self->_load_class( 'Crypt::Bcrypt' ) )
{
my $bc = eval
{
Crypt::Bcrypt->new( cost => $cost, salt => $salt );
};
if( $@ )
{
return( $self->error( "Error instantiating a new Crypt::Bcrypt object for the bcrypt hash: $@" ) );
}
# returns $2b/$2y$...
return( $bc->hash( $passwd ) );
}
# Fallback 3: Crypt::Eksblowfish::Bcrypt (settings must have bcrypt-base64 salt)
elsif( $self->_load_class( 'Crypt::Eksblowfish::Bcrypt' ) )
{
$hash = eval
{
Crypt::Eksblowfish::Bcrypt::bcrypt( $passwd, $setting );
};
if( $@ )
{
return( $self->error( "Error generating bcrypt hash with Crypt::Eksblowfish::Bcrypt: $@" ) );
}
return( $hash );
}
elsif( $crypt_error )
{
return( $self->error( "Error generating bcrypt hash, and alternative modules (Authen::Passphrase::BlowfishCrypt, Crypt::Bcrypt, Crypt::Eksblowfish::Bcrypt) are not installed: $@" ) );
}
else
{
return( $self->error( "System crypt() does not support bcrypt, and alternative modules (Authen::Passphrase::BlowfishCrypt, Crypt::Bcrypt, Crypt::Eksblowfish::Bcrypt) are not installed." ) );
}
}
sub make_md5
{
my $self = shift( @_ );
my $passwd = shift( @_ );
my $salt = shift( @_ ) || $self->{salt};
# salt: max 8 chars, allowed ./0-9A-Za-z
$salt //= $self->_make_salt(8);
if( !defined( $salt ) )
{
return( $self->pass_error );
}
elsif( $salt =~ m,[^./0-9A-Za-z], )
{
return( $self->error( "Salt value provided contains illegal characters." ) );
}
$salt = substr( $salt, 0, 8 );
$self->_load_class( 'Digest::MD5' ) ||
return( $self->pass_error );
my $magic = '$apr1$';
# 1) initial ctx: password + magic + salt
my $ctx = Digest::MD5->new;
local $@;
# try-catch
eval
{
$ctx->add( $passwd, $magic, $salt );
};
if( $@ )
{
return( $self->error( "Error adding string to create MD5 hash: $@" ) );
}
# 2) alternate sum: md5(password + salt + password)
my $alt = Digest::MD5->new;
eval
{
$alt->add( $passwd, $salt, $passwd );
};
if( $@ )
{
return( $self->error( "Error adding string to create MD5 hash: $@" ) );
}
# 16 bytes
my $alt_result = $alt->digest;
# 3) append to ctx as many full 16-byte blocks of alt_result
my $plen = length( $passwd );
for( my $i = $plen; $i > 0; $i -= 16 )
{
eval
{
$ctx->add( substr( $alt_result, 0, $i < 16 ? $i : 16 ) );
};
if( $@ )
{
return( $self->error( "Error adding string to create MD5 hash: $@" ) );
}
}
# 4) mix in bytes based on bits of password length
for( my $i = $plen; $i > 0; $i >>= 1 )
{
eval
{
if( $i & 1 )
{
$ctx->add( pack( 'C', 0 ) );
}
else
{
$ctx->add( substr( $passwd, 0, 1 ) );
}
};
if( $@ )
{
return( $self->error( "Error adding string to create MD5 hash: $@" ) );
}
}
# 16 bytes
my $final = $ctx->digest;
# 5) 1000 iterations "rounds"
for( my $i = 0; $i < 1000; $i++ )
{
my $t = Digest::MD5->new;
eval
{
if( $i & 1 )
{
$t->add( $passwd );
}
else
{
$t->add( $final );
}
if( $i % 3 )
{
$t->add( $salt );
}
if( $i % 7 )
{
$t->add( $passwd );
}
if( $i & 1 )
{
$t->add( $final );
}
else
{
$t->add( $passwd );
}
};
if( $@ )
{
return( $self->error( "Error adding string to create MD5 hash: $@" ) );
lib/Apache2/API.pm view on Meta::CPAN
my $hash = $self->{hash};
return(0) unless( defined( $pwd ) && defined( $hash ) );
local $@;
if( $hash =~ /^\$apr1\$/ )
{
my $salt;
# If the 'salt' is already set, we use it.
unless( $salt = $self->{salt} )
{
if( $hash =~ /\A$APR1_RE\z/ )
{
$salt = $+{salt};
}
else
{
return(0);
}
}
my $calc = $self->make_md5( $pwd, $salt ) ||
return( $self->pass_error );
return( $hash eq $calc );
}
# bcrypt
elsif( $hash =~ /\A$BCRYPT_RE\z/ )
{
# crypt() verification: use the stored hash as the salt spec
# try-catch
my $out = eval
{
crypt( $pwd, $hash );
};
if( $@ || !defined( $out ) || $out !~ /^\$2[aby]\$/ )
{
# Save it, if any.
my $crypt_error = $@;
# Fallback 1: Authen::Passphrase::BlowfishCrypt
if( $self->_load_class( 'Authen::Passphrase::BlowfishCrypt' ) )
{
# try-catch
my $ppr = eval
{
Authen::Passphrase::BlowfishCrypt->from_crypt( $hash );
};
if( $@ )
{
return( $self->error( "Error instantiating a new Authen::Passphrase::BlowfishCrypt object for the bcrypt hash: $@" ) );
}
return( $ppr->match( $pwd ) );
}
# Fallback 2: Crypt::Bcrypt
elsif( $self->_load_class( 'Crypt::Bcrypt' ) )
{
# try-catch
my $bool = eval
{
Crypt::Bcrypt::bcrypt_check( $pwd => $hash );
};
if( $@ )
{
return( $self->error( "Error checking if password matches using Crypt::Bcrypt: $@" ) );
}
return( $bool );
}
# Fallback 3: Crypt::Eksblowfish::Bcrypt (settings must have bcrypt-base64 salt)
elsif( $self->_load_class( 'Crypt::Eksblowfish::Bcrypt' ) )
{
# try-catch
$out = eval
{
Crypt::Eksblowfish::Bcrypt::bcrypt( $pwd, $hash );
};
if( $@ )
{
return( $self->error( "Error generating bcrypt hash with Crypt::Eksblowfish::Bcrypt: $@" ) );
}
return( defined( $out ) && $out eq $hash );
}
elsif( $crypt_error )
{
return( $self->error( "Error checking bcrypt password: $crypt_error" ) );
}
}
return( defined( $out ) && $out eq $hash );
}
elsif( $hash =~ /\A$SHA_RE\z/ )
{
# try-catch
my $out = eval
{
crypt( $pwd, $hash );
};
if( defined( $out ) && $out eq $hash )
{
return(1);
}
# Save it, if any.
my $crypt_error = $@;
if( $self->_load_class( 'Crypt::Passwd::XS' ) )
{
# try-catch
$out = eval
{
Crypt::Passwd::XS::crypt( $pwd, $hash );
};
if( $@ )
{
return( $self->error( "Error checking the password using Crypt::Passwd::XS: $@" ) );
}
return( defined( $out ) && $out eq $hash );
}
elsif( $crypt_error )
{
return( $self->error( "Error checking SHA password: $crypt_error" ) );
}
return(0);
}
else
{
return(0);
}
}
sub salt { return( shift->_set_get_scalar( 'salt', @_ ) ); }
sub sha_rounds { return( shift->_set_get_number({
field => 'sha_rounds',
check => sub
{
my( $self, $n ) = @_;
unless( $n =~ /^\d+$/ &&
$n >= 1000 &&
$n <= 999999999 )
{
return( $self->error( "sha_rounds must be between 1000 and 999999999" ) )
}
return(1);
},
}, @_ ) ); }
sub _make_salt
{
my $self = shift( @_ );
# Default to 8 for MD5, 16 for bcrypt/SHA-2
my $len = shift( @_ ) || 8;
if( $len !~ /^\d+$/ )
{
return( $self->error( "Length provided is not an integer." ) );
}
my @chars = ( '.', '/', 0..9, 'A'..'Z', 'a'..'z' );
if( $self->_load_class( 'Crypt::URandom' ) )
{
my $raw = Crypt::URandom::urandom( $len );
my $salt = '';
for my $byte ( unpack( 'C*', $raw ) )
{
$salt .= $chars[ $byte % @chars ];
}
return( substr( $salt, 0, $len ) );
}
elsif( $self->_load_class( 'Bytes::Random::Secure' ) )
{
return( Bytes::Random::Secure::random_string_from( join( '', @chars ), $len ) );
}
else
{
return( $self->error( "Neither Crypt::URandom nor Bytes::Random::Secure are installed on the system to generate a salt." ) );
}
}
# 16 raw bytes -> 22-char bcrypt base64, using either the module helper
# or a tiny built-in encoder if the module isn't present.
sub _make_salt_bcrypt
lib/Apache2/API.pm view on Meta::CPAN
use Apache2::API;
my $r = shift( @_ );
my $api = Apache2::API->new( $r );
# for example:
return( $api->reply( Apache2::Const::HTTP_OK => { message => "Hello world" } ) );
my $r = $api->apache_request;
return( $api->bailout({
message => "Oops",
code => Apache2::Const::BAD_REQUEST,
public_message => "An unexpected error occurred.",
}) );
# or
return( $api->bailout( @some_reasons ) );
# 100kb
$api->compression_threshold(102400);
my $decoded = $api->decode_base64( $b64_string );
my $ref = $api->decode_json( $json_data );
my $decoded = $api->decode_url;
my $perl_utf8 = $api->decode_utf8( $data );
my $b64_string = $api->encode_base64( $data );
my $json_data = $api->encode_json( $ref );
my $encoded = $api->encode_url( $uri );
my $utf8 = $api->encode_utf8( $data );
my $uuid = $api->generate_uuid;
my $auth = $api->get_auth_bearer;
my $handlers = $api->get_handlers;
my $dt = $api->header_datetime( $http_datetime );
my $bool = $api->is_perl_option_enabled;
# JSON object
my $json = $api->json( pretty => 1, sorted => 1, relaxed => 1 );
my $lang = $api->lang( 'en_GB' );
# en_GB
my $lang = $api->lang_unix;
# en-GB
my $lang = $api->lang_web;
$api->log_error( "Oops" );
$api->print( @some_data );
$api->push_handlers( $name => $code_reference );
return( $api->reply( Apache2::Const::HTTP_OK => {
message => "All good!",
# arbitrary property
client_id => "efe4bcf3-730c-4cb2-99df-25d4027ec404",
# special property
cleanup => sub
{
# Some code here to be executed after the reply is sent out to the client.
}
}) );
# Apache2::API::Request
my $req = $api->request;
# Apache2::API::Response
my $req = $api->response;
my $server = $api->server;
my $version = $api->server_version;
$api->set_handlers( $name => $code_reference );
$api->warn( @some_warnings );
my $hash = apr1_md5( $clear_password );
my $hash = apr1_md5( $clear_password, $salt );
my $ht = $api->htpasswd( $clear_password );
my $ht = $api->htpasswd( $clear_password, salt => $salt );
my $hash = $ht->hash;
say "Does our password match ? ", $ht->matches( $user_clear_password ) ? "yes" : "not";
=head1 VERSION
v0.5.4
=head1 DESCRIPTION
This module provides a comprehensive, powerful, yet simple framework to access L<Apache mod_perl's API|https://perl.apache.org/docs/2.0/api/> and documented appropriately.
Apache mod_perl is an awesome framework, but quite complexe with a steep learning curve and methods all over the place. So much so that L<they have developed a module dedicated to find appropriate methods|https://perl.apache.org/docs/2.0/user/coding/...
=head1 METHODS
=head2 new
my $api = Apache2::API->new( $r, $hash_ref_of_options );
# or
my $api = Apache2::API->new( apache_request => $r, compression_threshold => 102400 );
This initiates the package and takes an L<Apache2::RequestRec> object and an hash or hash reference of parameters, or only an hash or hash reference of parameters:
=over 4
=item * C<apache_request>
See L</apache_request>
=item * C<compression_threshold>
See L</compression_threshold>
=item * C<debug>
Optional. If set with a positive integer, this will activate debugging message
=back
=head2 apache_request
Returns the L<Apache2::RequestRec> object that was provided upon object instantiation.
=head2 bailout
$api->bailout( $error_string );
$api->bailout( { code => 400, message => $internal_message } );
$api->bailout( { code => 400, message => $internal_message, public_message => "Sorry!" } );
Given an error message, this will prepare the HTTP header and response accordingly.
It will call L</gettext> to get the localised version of the error message, so this method is expected to be overriden by inheriting package.
If the outgoing content type set is C<application/json> then this will return a properly formatted standard json error, such as:
{ "error": { "code": 401, "message": "Something went wrong" } }
Otherwise, it will send to the client the message as is.
=head2 compression_threshold( $integer )
The number of bytes threshold beyond which, the L</reply> method will gzip compress the data returned to the client.
lib/Apache2/API.pm view on Meta::CPAN
Decode some data from ut8 into perl internal utf8 representation using L<Encode>
If an error occurs, it will return undef and set an exception that can be accessed with the L<error|Module::Generic/errir> method.
=head2 encode_base64( $data )
Given some data, this will encode it using base64 algorithm. It uses L<APR::Base64/encode>.
=head2 encode_json( $hash_reference )
Given a hash reference, this will encode it into a json data representation.
However, this will not utf8 encode it, because this is done upon printing the data and returning it to the client.
The JSON object has the following properties enabled: C<allow_nonref>, C<allow_blessed>, C<convert_blessed> and C<relaxed>
=head2 encode_url( $string )
Given a string, this returns its url-encoded version using L<APR::Request/encode>
=head2 encode_utf8( $data )
This encode in ut8 the data provided and return it.
If an error occurs, it will return undef and set an exception that can be accessed with the B<error> method.
=head2 generate_uuid
Generates an uuid string and return it. This uses L<APR::UUID>
=head2 get_auth_bearer
Checks whether an C<Authorization> HTTP header was provided, and get the Bearer value.
If no header was found, it returns an empty string.
If an error occurs, it will return undef and set an exception that can be accessed with the B<error> method.
=head2 get_handlers
Returns a reference to a list of handlers enabled for a given phase.
$handlers_list = $res->get_handlers( $hook_name );
A list of handlers configured to run at the child_exit phase:
@handlers = @{ $res->get_handlers( 'PerlChildExitHandler' ) || []};
=head2 gettext( 'string id' )
Get the localised version of the string passed as an argument.
This is supposed to be superseded by the package inheriting from L<Apache2::API>, if any.
=head2 header_datetime( DateTime or DateTime::Lite object )
Given a L<DateTime> or L<DateTime::Lite> object, this sets it to GMT time zone and set the proper formatter (L<Apache2::API::DateTime>) so that the stringification is compliant with HTTP headers standard.
=head2 htpasswd
my $ht = $api->htpasswd( $clear_password, create => 1 );
my $ht = $api->htpasswd( $clear_password, create => 1, salt => $salt );
my $ht = $api->htpasswd( $md5_password );
my $bool = $ht->matches( $user_input_password );
This instantiates a new L<Apache2::API::Password> object by providing its constructor whatever arguments was received.
It returns a new L<Apache2::API::Password> object, or, upon error, C<undef> in scalar context, or an empty list in list context.
=head2 is_perl_option_enabled
Checks if perl option is enabled in the Virtual Host and returns a boolean value
=head2 json
Returns a JSON object.
You can provide an optional hash or hash reference of properties to enable or disable:
my $J = $api->json( pretty => 1, relaxed => 1 );
Each property corresponds to one that is supported by L<JSON>
It also supports C<ordered>, C<order> and C<sort> as an alias to C<canonical>
=head2 lang( $string )
Set or get the language for the API. This would typically be the HTTP preferred language.
=head2 lang_unix( $string )
Given a language, this returns a language code formatted the unix way, ie en-GB would become en_GB
=head2 lang_web( $string )
Given a language, this returns a language code formatted the web way, ie en_GB would become en-GB
=head2 log
$api->log->emerg( "Urgent message." );
$api->log->alert( "Alert!" );
$api->log->crit( "Critical message." );
$api->log->error( "Error message." );
$api->log->warn( "Warning..." );
$api->log->notice( "You should know." );
$api->log->info( "This is for your information." );
$api->log->debug( "This is debugging message." );
Returns a L<Apache2::Log::Request> object.
=head2 log_error( $string )
Given a string, this will log the data into the error log.
When log_error is accessed with the L<Apache2::RequestRec> the error gets logged into the Virtual Host log, but when log_error gets accessed via the L<Apache2::ServerUtil> object, the error get logged into the Apache main error log.
=head2 print( @list )
print out the list of strings and returns the number of bytes sent.
The data will possibly be compressed if the HTTP client L<acceptable encoding|HTTPs://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding> and if the data exceeds the value set in L</compression_threshold>
It will gzip it if the HTTP client acceptable encoding is C<gzip> and if L<IO::Compress::Gzip> is installed.
lib/Apache2/API.pm view on Meta::CPAN
=head2 push_handlers
Returns the values from L<Apache2::Server/push_handlers> by passing it whatever arguments were provided.
=head2 reply
This takes an HTTP code and a message, or an exception object such as L<Module::Generic::Exception> or any other object that supports the C<code> and C<message> method, or just a hash reference, B<reply> will find out if the code provided is an error...
{ "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 C<cleanup> hash property is provided with a callback code reference as a value, it will be set as a cleanup callback by calling C<< $r->pool->cleanup_register >>. See L<https://perl.apache.org/docs/2.0/user/handlers/http.html#PerlCleanupHandler>
The L<Apache2::API> object will be passed as the first and only argument to the callback routine.
=head2 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 L</reply>, call L</reply>, and if the return code is an HTTP error, it will close the HTTP connection.
=head2 request()
Returns the L<Apache2::API::Request> object. This object is set upon instantiation.
=head2 response
Returns the L<Apache2::API::Response> object. This object is set upon instantiation.
=head2 server()
Returns a L<Apache2::Server> object
=head2 server_version
Tries hard to find out the version number of the Apache server. This returns the value from L<Apache2::API::Request/server_version>
=head2 set_handlers()
Returns the values from L<Apache2::Server/set_handlers> by passing it whatever arguments were provided.
=head2 use_rfc_error
Boolean. When true, this will return rfc9457 style error L<https://www.rfc-editor.org/rfc/rfc9457.html>
=head2 warn( @list )
Given a list of string, this sends a warning using L<Apache2::Log/warn>
=head2 _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 C<undef> and setting an exception with L<Module::Generic::Exception>, because we believe that only the main program should be in control of the flow and decide wh...
=head1 CLASS FUNCTIONS
=head2 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 L<Apache2::API::Password> object, and calls the method L<hash|Apache2::API::Password/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.
=head1 CONSTANTS
C<mod_perl> provides constants through L<Apache2::Constant> and L<APR::Constant>. L<Apache2::API> makes all those constants available using their respective package name, such as:
use Apache2::API;
say Apache2::Const::HTTP_BAD_REQUEST; # 400
You can import constants into your namespace by specifying them when loading L<Apache2::API>, 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 L<Apache2::Constant> and L<APR::Constant>, so it is recommended to use the fully qualified constant names rather than importing them into your namespace.
Some constants are special like C<OK>, C<DECLINED> or C<DECLINE_CMD>
Apache L<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...
=over 4
=item * C<Apache2::Const::OK>
The only value that can be returned by all handlers is C<Apache2::Const::OK>, which tells Apache that the handler has successfully finished its execution.
=item * C<Apache2::Const::DECLINED>
This indicates success, but it's only relevant for phases of type RUN_FIRST (C<PerlProcessConnectionHandler>, C<PerlTransHandler>, C<PerlMapToStorageHandler>, C<PerlAuthenHandler>, C<PerlAuthzHandler>, C<PerlTypeHandler>, C<PerlResponseHandler>
Apache2 L<documentation explains|https://perl.apache.org/docs/2.0/api/Apache2/RequestRec.html#toc_C_allowed_> that "generally modules should C<Apache2::Const::DECLINED> any request methods they do not handle."
=item * C<Apache2::Const::DONE>
This "tells Apache to stop the normal HTTP request cycle and fast forward to the PerlLogHandler,"
=back
Check L<Apache documentation on handler return value|https://perl.apache.org/docs/2.0/user/handlers/intro.html#toc_Handler_Return_Values> for more information.
=head1 INSTALLATION
As usual, to install this module, you can do:
perl Makefile.PL
make
make test
# or
# t/TEST
sudo make install
If you have Apache/modperl2 installed, this will also prepare the Makefile and run test under modperl.
The Makefile.PL tries hard to find your Apache configuration, but you can give it a hand by specifying some command line parameters.
For example:
perl Makefile.PL -apxs /usr/bin/apxs -port 1234
# which will also set the path to httpd_conf, otherwise
( run in 2.583 seconds using v1.01-cache-2.11-cpan-13bb782fe5a )