NAME

Apache2::API::Response - Apache2 Outgoing Response Access and Manipulation

SYNOPSIS

use Apache2::API::Response;
# $r is the Apache2::RequestRec object
my $resp = Apache2::API::Response->new( request => $r, debug => 1 );
# or, to test it outside of a modperl environment:
my $resp = Apache2::API::Response->new( request => $r, debug => 1, checkonly => 1 );

# Access-Control-Allow-Credentials
my $cred = $resp->allow_credentials;
# Access-Control-Allow-Headers
$resp->allow_headers( $custom_header );
# Access-Control-Allow-Methods
$resp->allow_methods( $method );
$reso->allow_origin( $origin );
# Alt-Svc
my $alt = $resp->alt_svc;
my $nbytes = $resp->bytes_sent;
# Cache-Control
my $cache = $resp->cache_control;
# Clear-Site-Data
my $clear = $resp->clear_site_data;

# Apache2::Connection object
my $conn = $resp->connection;
my $code = $resp->code;
# Content-Disposition
my $disp = $resp->content_disposition;
my $encoding = $resp->content_encoding;
# Content-Language
my $lang = $resp->content_language;
my $langs_array_ref = $resp->content_languages;
# Content-Length
my $len = $resp->content_length;
# Content-Location
my $location = $resp->content_location;
# Content-Range
my $range = $resp->content_range;
# Content-Security-Policy
my $policy = $resp->content_security_policy;
my $policy = $resp->content_security_policy_report_only;
my $ct = $resp->content_type;
my $cookie = $resp->cookie_new(
    name => $name,
    value => $some_value,
    value => 'sid1234567',
    path => '/',
    expires => '+10D',
    # or alternatively
    maxage => 864000
    # to make it exclusively accessible by regular http request and not javascript
    http_only => 1,
    same_site => 'Lax',
    # should it be used under ssl only?
    secure => 1
);
$resp->cookie_replace( $cookie );
$resp->cookie_set( $cookie );
# Cross-Origin-Embedder-Policy
my $policy = $resp->cross_origin_embedder_policy;
# Cross-Origin-Opener-Policy
my $policy = $resp->cross_origin_opener_policy;
# Cross-Origin-Resource-Policy
my $policy = $resp->cross_origin_resource_policy;
my $cspro = $resp->cspro;
$resp->custom_response( Apache2::Const::AUTH_REQUIRED, "Authenticate please" );
my $decoded = $resp->decode( $string );
# Digest
my $digest = $resp->digest;
my $encoded = $resp->encode( $string );
# APR::Table object
my $env = $resp->env;
my $headers = $resp->err_headers;
my $headers = $resp->err_headers_out;
my $escaped = $resp->escape( $string );
my $etag = $resp->etag;
# Expires
my $expires = $resp->expires;
# Access-Control-Expose-Headers
my $expose_headers = $resp->expose_headers;
$resp->flush;
my $msg = $resp->get_http_message( 429 => 'ja_JP' );
my $string = $resp->get_status_line;
my $content_type = $resp->headers( 'Content-Type' );
# or (since it is case insensitive)
my $content_type = $resp->headers( 'content-type' );
# or
my $content_type = $resp->headers->{'Content-Type'};
$resp->header( 'Content-Type' => 'text/plain' );
# or
$resp->headers->{'Content-Type'} = 'text/plain';
# APR::Table object
my $headers = $resp->headers;
my $headers = $resp->headers_out;
$resp->internal_redirect( $uri );
$resp->internal_redirect_handler( $uri );
my $rv = $resp->is_info(100);
my $rv = $resp->is_success(200);
my $rv = $resp->is_redirect(302);
my $rv = $resp->is_error(400);
my $rv = $resp->is_client_error(401);
my $rv = $resp->is_server_error(500);
# Keep-Alive
my $keep_alive = $resp->keep_alive;
# Last-Modified
my $http_date = $resp->last_modified;
# Last-Modified-Date
my $http_date = $resp->last_modified_date;
# Location
my $loc = $resp->location;
my $rv = $resp->lookup_uri( $uri );
my $etag = $resp->make_etag( $force_weak );
# Access-Control-Max-Age
my $max_age = $resp->max_age;
my $rv = $resp->meets_conditions;
# NEL
my $nel = $resp->nel;
$resp->no_cache(1);
$resp->no_local_copy(1);
$resp->print( @some_data );
$resp->printf( $template, $param1, $param2 );
my $puts = $resp->puts;
my $rv = $resp->redirect( $uri );
# Referrer-Policy
my $policy = $resp->referrer_policy;
my $r = $resp->request;
# Retry-After
my $retry_after = $resp->retry_after;
$resp->rflush;
$resp->send_cgi_header;
$resp->sendfile( $filename, $offset, $len );
$resp->sendfile( $filename );
# Server
my $server = $resp->server;
my $server_timing = $resp->server_timing;
$resp->set_content_length(1024);
# Set-Cookie
$resp->set_cookie( $cookie );
$resp->set_last_modified;
$resp->set_keepalive(1);
my $socket = $resp->socket;
my $sourcemap = $resp->sourcemap;
my $status = $resp->status;
my $status_line = $resp->status_line;
# Strict-Transport-Security
my $policy = $resp->strict_transport_security;
# APR::Table object
my $env = $resp->subprocess_env;
# Timing-Allow-Origin
my $origin = $resp->timing_allow_origin;
# Trailer
my $trailerv = $resp->trailer;
my $enc = $resp->transfer_encoding;
my $unescape = $resp->unescape( $string );
# Upgrade
my $upgrade = $resp->upgrade;
$resp->update_mtime( $seconds );
my $uri = $resp->uri_escape( $uri );
my $uri = $resp->uri_unescape( $uri );
my $decoded = $resp->url_decode( $uri );
my $encoded = $resp->url_encode( $uri );
# Vary
my $vary = $resp->vary;
# Via
my $via = $resp->via;
# Want-Digest
my $want = $resp->want_digest;
# Warning
my $warn = $resp->warning;
$resp->write( $buffer, $len, $offset );
# WWW-Authenticate
my $auth = $resp->www_authenticate;
# X-Content-Type-Options
my $opt = $resp->x_content_type_options;
# X-DNS-Prefetch-Control
my $proto = $resp->x_dns_prefetch_control;
# X-Frame-Options
my $opt = $resp->x_frame_options;
# X-XSS-Protection
my $xss = $resp->x_xss_protection;

VERSION

v0.1.0

DESCRIPTION

The purpose of this module is to provide an easy access to various method to process and manipulate incoming request.

This is designed to work under modperl.

Normally, one would need to know which method to access across various Apache2 mod perl modules, which makes development more time consuming and even difficult, because of the scattered documentation and even sometime outdated.

This module alleviate this problem by providing all the necessary methods in one place. Also, at the contrary of Apache2 modules suit, all the methods here are die safe. When an error occurs, it will always return undef() and the error will be able to be accessed using error object, which is a Module::Generic::Exception object.

Fo its alter ego to manipulate outgoing HTTP response, use the Apache2::API::Response module.

CONSTRUCTORS

new

This initiates the package and take the following parameters:

checkonly

If true, it will not perform the initialisation it would usually do under modperl.
debug

Optional. If set with a positive integer, this will activate verbose debugging message
request

This is a required parameter to be sent with a value set to a Apache2::RequestRec object

METHODS

allow_credentials

Sets or gets the HTTP header field Access-Control-Allow-Credentials

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials

allow_headers

Sets or gets the HTTP header field Access-Control-Allow-Credentials

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers

allow_methods

Sets or gets the HTTP header field Access-Control-Allow-Methods

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods

allow_origin

Sets or gets the HTTP header field Access-Control-Allow-Origin

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin

alt_svc

Sets or gets the HTTP header field Alt-Svc

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Alt-Svc

bytes_sent

The number of bytes sent to the client, handy for logging, etc.

This calls "bytes_sent" in Apache2::RequestRec

cache_control

Sets or gets the HTTP header field Cache-Control

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control

call

Provided with an Apache2 API method name, and optionally with some additional arguments, and this will call that Apache2 method and return its result.

This is designed to allow you to call arbitrary Apache2 method that, possibly, are not covered here.

For example:

$resp->call( 'send_error_response' );

It returns whatever value this call returns.

clear_site_data

Sets or gets the HTTP header field Clear-Site-Data

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Clear-Site-Data

code

Sets or gets the response status code, by calling "status" in Apache2::RequestRec

From the Apache2::RequestRec documentation:

Usually you will set this value indirectly by returning the status code as the handler's function result. However, there are rare instances when you want to trick Apache into thinking that the module returned an Apache2::Const::OK status code, but actually send the browser a non-OK status. This may come handy when implementing an HTTP proxy handler. The proxy handler needs to send to the client, whatever status code the proxied server has returned, while returning Apache2::Const::OK to Apache. e.g.:

$resp->status( $some_code );
return( Apache2::Const::OK );

connection

Returns a Apache2::Connection object.

content_disposition

Sets or gets the HTTP header field Content-Disposition

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition

content_encoding

Get or set content encoding (the Content-Encoding HTTP header). Content encodings are string like gzip or compress.

For example, here is how to send a gzip'ed response:

require Compress::Zlib;
$resp->content_type( "text/plain" );
$resp->content_encoding( "gzip" );
$resp->print( Compress::Zlib::memGzip( "some text to be gzipped" ) );

content_language

Sets or gets the HTTP header field Content-Language

content_languages

my $languages = $resp->content_languages();
my $prev_lang = $resp->content_languages( $nev_lang );

Sets or gets the value of the Content-Language HTTP header, by calling "content_languages" in Apache2::RequestRec

Content languages are string like en or fr.

It returns the language codes as an array reference.

content_length

Set the content length for this request, by calling "set_content_length" in Apache2::Response

See Apache2::Response for more information.

content_location

Sets or gets the HTTP header field Content-Location

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Location

content_range

Sets or gets the HTTP header field Content-Range

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range

content_security_policy

Sets or gets the HTTP header field Content-Security-Policy

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy

content_security_policy_report_only

Sets or gets the HTTP header field Content-Security-Policy-Report-Only

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy-Report-Only

content_type

Get or set the HTTP response Content-type header value.

For example, set the Content-type header to text/plain.

$resp->content_type('text/plain');

If you set this header via the headers_out table directly, it will be ignored by Apache. So do not do that.

See Apache2::RequestRec for more information.

cookie_new

Given a hash reference with the following properties, this will create a Cookie object that can be stringified and aded into a Set-Cookie HTTP header.

name
value
domain
expires
http_only
max_age
path
secure
same_site

See "make" in Cookie::Jar and Cookie for more information on those parameters.

cookie_replace

Given a cookie object, this either sets the given cookie in a Set-Cookie header or replace the existing one with the same cookie name, if any.

It returns the cookie object provided.

cookie_set

Given a cookie object, this set the Set-Cookie HTTP header for this cookie.

However, it does not check if another Set-Cookie header exists for this cookie.

cross_origin_embedder_policy

Sets or gets the HTTP header field Cross-Origin-Embedder-Policy

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy

cross_origin_opener_policy

Sets or gets the HTTP header field Cross-Origin-Opener-Policy

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy

cross_origin_resource_policy

Sets or gets the HTTP header field Cross-Origin-Resource-Policy

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Resource-Policy

cspro

Alias for "content_security_policy_report_only"

custom_response

Install a custom response handler for a given status.

$resp->custom_response( $status, $string );

The first argument is the status for which the custom response should be used (e.g. Apache2::Const::AUTH_REQUIRED)

The second argument is the custom response to use. This can be a static string, or a URL, full or just the uri path (/foo/bar.txt).

custom_response() does not alter the response code, but is used to replace the standard response body. For example, here is how to change the response body for the access handler failure:

package MyApache2::MyShop;
use Apache2::Response ();
use Apache2::Const -compile => qw(FORBIDDEN OK);
sub access {
    my $r = shift;

    if (MyApache2::MyShop::tired_squirrels()) {
        $resp->custom_response(Apache2::Const::FORBIDDEN,
            "It is siesta time, please try later");
        return Apache2::Const::FORBIDDEN;
    }

    return Apache2::Const::OK;
}
...

# httpd.conf
PerlModule MyApache2::MyShop
<Location /TestAPI__custom_response>
    AuthName dummy
    AuthType none
    PerlAccessHandler   MyApache2::MyShop::access
    PerlResponseHandler MyApache2::MyShop::response
</Location>

When squirrels cannot run any more, the handler will return 403, with the custom message:

It is siesta time, please try later

decode

Given a url-encoded string, this returns the decoded string

This uses APR::Request XS method.

digest

Sets or gets the HTTP header field Digest

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Digest

encode

Given a string, this returns its url-encoded version

This uses APR::Request XS method.

env

my $val = $resp->env( $name );
$resp->env( $name, $value );

Using the Apache subprocess_env table, this sets or gets environment variables. This is the equivalent of this:

             $resp->subprocess_env;
$env_table = $resp->subprocess_env;

       $resp->subprocess_env( $key => $val );
$val = $resp->subprocess_env( $key );

where $resp is this module object.

If one argument is provided, it will return the corresponding environment value.

If one or more sets of key-value pair are provided, they are set accordingly.

If nothing is provided, it returns a APR::Table object.

err_headers

Given one or more name => value pair, this will set them in the HTTP header using the "err_headers_out" method.

err_headers_out

Get or sets HTTP response headers, which are printed out even on errors and persist across internal redirects.

According to the Apache2::RequestRec documentation:

The difference between "headers_out" ("headers_out" in Apache2::RequestRec) and "err_headers_out" ("err_headers_out" in Apache2::RequestRec), is that the latter are printed even on error, and persist across internal redirects (so the headers printed for ErrorDocument handlers will have them).

For example, if a handler wants to return a 404 response, but nevertheless to set a cookie, it has to be:

$resp->err_headers_out->add( 'Set-Cookie' => $cookie );
return( Apache2::Const::NOT_FOUND );

If the handler does:

$resp->headers_out->add( 'Set-Cookie' => $cookie );
return( Apache2::Const::NOT_FOUND );

the Set-Cookie header will not be sent.

See Apache2::RequestRec for more information.

escape

Provided with a value and this will return it uri escaped by calling "uri_escape" in URI::Escape.

etag

Sets or gets the HTTP header field Etag

expires

Sets or gets the HTTP header field Expires

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires

expose_headers

Sets or gets the HTTP header field Access-Control-Expose-Headers

e.g.: Access-Control-Expose-Headers: Content-Encoding, X-Kuma-Revision

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers

flush

Flush any buffered data to the client, by calling "rflush" in Apache2::RequestIO

$resp->flush();

Unless STDOUT stream's $| is false, data sent via $resp->print() is buffered. This method flushes that data to the client.

For example if your script needs to perform a relatively long-running operation (e.g. a slow db lookup) and the client may timeout if it receives nothing right away, you may want to start the handler by setting the Content-Type header, following by an immediate flush[1]:

$resp->content_type('text/html');
$resp->flush; # send the headers out

$resp->print( long_operation() );
return( Apache2::Const::OK );

[1] mod_perl2 documentation https://perl.apache.org/docs/2.0/user/coding/coding.html#toc_Forcing_HTTP_Response_Headers_Out

get_http_message

Given an HTTP code integer, and optionally a language code, this returns the HTTP status message in the language given.

If no language is provided, this returns the message by default in en_GB, i.e. British English.

get_status_line

Return the Status-Line for a given status code (excluding the HTTP-Version field), by calling "status_line" in Apache2::RequestRec

For example:

print( $resp->get_status_line( 400 ) );

will print:

400 Bad Request

headers

Gets or sets the HTTP response headers using APR::Table by calling "Apache2::RequestRec/err_headers_out"

This takes zero, one or sets or key => value pairs.

When no argument is provided, this returns the APR::Object.

When one argument is provided, it returns the corresponding HTTP header value, if any.

You can set multiple key-value pairs, like so:

$resp->headers( $var1 => $val1, $var2 => $val2 );

If a value provided is undef, it will remove the corresponding HTTP headers.

With the APR::Table object, you can access and set header fields directly, such as:

my $accept = $resp->headers->{Accept};
$resp->headers->{Accept} = 'application/json';
$resp->headers->{Accept} = undef; # unset it

my $accept = $resp->headers->get( 'Accept' );
$resp->headers->set( Accept => 'application/json' );
$resp->headers->unset( 'Accept' );
$resp->headers->add( Vary => 'Accept-Encoding' );
# Very useful for this header
$resp->headers->merge( Vary => 'Accept-Encoding' );
# Empty the headers
$resp->headers->clear;
use Apache2::API;
# to merge: multiple values for the same key are flattened into a comma-separated list.
$resp->headers->compress( APR::Const::OVERLAP_TABLES_MERGE );
# to overwrite: each key will be set to the last value seen for that key.
$resp->headers->compress( APR::Const::OVERLAP_TABLES_SET );
my $table = $resp->headers->copy( $resp2->pool );
my $headers = $resp->headers;
$resp->headers->do(sub
{
    my( $key, $val ) = @_;
    # Do something
    # return(0) to abort
}, keys( %$headers ) );
# or without any filter keys
$resp->headers->do(sub
{
    my( $key, $val ) = @_;
    # Do something
    # return(0) to abort
});
# To prepare a table of 20 elements, but the table can still grow
my $table = APR::Table::make( $resp->pool, 20 );
my $table2 = $resp2->headers;
# overwrite any existing keys in our table $table
$table->overlap( $table2, APR::Const::OVERLAP_TABLES_SET );
# key, value pairs are added, regardless of whether there is another element with the same key in $table
$table->overlap( $table2, APR::Const::OVERLAP_TABLES_MERGE );
my $table3 = $table->overlay( $table2, $pool3 );

See APR::Table for more information.

headers_out

Returns or sets the key => value pairs of outgoing HTTP headers, only on 2xx responses.

See also "err_headers_out", which allows to set headers for non-2xx responses and persist across internal redirects.

More information at Apache2::RequestRec

internal_redirect

Given a URI object or a uri path string, this redirect the current request to some other uri internally.

If a URI object is given, its path method will be used to get the path string.

$resp->internal_redirect( $new_uri );

In case that you want some other request to be served as the top-level request instead of what the client requested directly, call this method from a handler, and then immediately return Apache2::Const::OK. The client will be unaware the a different request was served to her behind the scenes.

See Apache2::SubRequest for more information.

internal_redirect_handler

Identical to "internal_redirect", plus automatically sets $resp->content_type is of the sub-request to be the same as of the main request, if $resp->handler is true.

is_info

Given a HTTP code integer, this will return true if the code is comprised between 100 and less than 200, false otherwise.

is_success

Given a HTTP code integer, this will return true if the code is comprised between 200 and less than 300, false otherwise.

is_redirect

Given a HTTP code integer, this will return true if the code is comprised between 300 and less than 400, false otherwise.

is_error

Given a HTTP code integer, this will return true if the code is comprised between 400 and less than 600, false otherwise.

is_client_error

Given a HTTP code integer, this will return true if the code is comprised between 400 and less than 500, false otherwise.

is_server_error

Given a HTTP code integer, this will return true if the code is comprised between 500 and less than 600, false otherwise.

keep_alive

Sets or gets the HTTP header field Keep-Alive

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Keep-Alive

last_modified

Sets or gets the HTTP header field Last-Modified

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified

last_modified_date

Sets or gets the HTTP header field Last-Modified-Date

location

Sets or gets the HTTP header field Location

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location

lookup_uri

Create a sub request from the given URI, by calling "lookup_uri" in Apache2::SubRequest

This sub request can be inspected to find information about the requested URI.

$ret = $resp->lookup_uri( $new_uri );
$ret = $resp->lookup_uri( $new_uri, $next_filter );
$ret = $resp->lookup_uri( $new_uri, $next_filter, $handler );

See Apache2::SubRequest for more information.

make_etag

Provided with a boolean value, this constructs an entity tag from the resource information, by calling "make_etag" in Apache2::Response

If it is a real file, build in some of the file characteristics.

$etag = $resp->make_etag( $force_weak );

It returns the etag as a string.

max_age

Sets or gets the HTTP header field Access-Control-Max-Age

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age

meets_conditions

Implements condition GET rules for HTTP/1.1 specification. This function inspects the client headers and determines if the response fulfills the specified requirements.

$status = $resp->meets_conditions();

It returns Apache2::Const::OK if the response fulfils the condition GET rules. Otherwise some other status code (which should be returned to Apache).

nel

Sets or gets the HTTP header field NEL

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/NEL

no_cache

Add or remove cache control headers:

$prev_no_cache = $resp->no_cache( $boolean );

A true value sets the no_cache request record member to a true value and inserts:

Pragma: no-cache
Cache-control: no-cache

into the response headers, indicating that the data being returned is volatile and the client should not cache it.

A false value unsets the no_cache request record member and the mentioned headers if they were previously set.

This method should be invoked before any response data has been sent out.

no_local_copy

my $status = $resp->no_local_copy();

Used internally in certain sub-requests to prevent sending Apache2::Const::HTTP_NOT_MODIFIED for a fragment or error documents.

Also affect "meets_conditions". If set to a true value, the conditions are always met.

It returns a status integer.

print

Provided with a list of data, and this sends it to the client, by calling "print" in Apache2::RequestIO

$cnt = $resp->print( @msg );

It returns how many bytes were sent (or buffered). If zero bytes were sent, print will return 0E0, or zero but true, which will still evaluate to 0 in a numerical context.

The data is flushed only if STDOUT stream's $| is true. Otherwise it is buffered up to the size of the buffer, flushing only excessive data.

printf

Format and send data to the client (same as perl's printf), by calling "printf" in Apache2::RequestIO

$cnt = $resp->printf( $format, @args );

It returns how many bytes were sent (or buffered).

The data is flushed only if STDOUT stream's $| is true. Otherwise it is buffered up to the size of the buffer, flushing only excessive data.

puts

$cnt = $req->puts( @msg );

Provided with values, this sends it to the client, by calling "puts" in Apache2::RequestIO

It returns how many bytes were sent (or buffered).

redirect

Given an URI, this will prepare the HTTP headers and return the proper code for a 301 temporary HTTP redirect.

It should be used like this in your code:

return( $resp->redirect( "https://example.com/somewhere/" ) );

referrer_policy

Sets or gets the HTTP header field Referrer-Policy

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy

request

Returns the Apache2::API::Request object.

retry_after

Sets or gets the HTTP header field Retry-After

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After

rflush

Flush any buffered data to the client, by calling "rflush" in Apache2::RequestIO

Unless STDOUT stream's $| is false, data sent via $resp->print() is buffered. This method flushes that data to the client.

It does not return any value.

send_cgi_header

Parse the header, by calling "send_cgi_header" in Apache2::Response

$resp->send_cgi_header( $buffer );

This method is really for back-compatibility with mod_perl 1.0. It is very inefficient to send headers this way, because of the parsing overhead.

If there is a response body following the headers it will be handled too (as if it was sent via "print").

Notice that if only HTTP headers are included they will not be sent until some body is sent (again the send part is retained from the mod_perl 1.0 method).

See Apache2::Response for more information.

sendfile

Provided with a file path, an optional offset and an optional length, and this will send a file or a part of it, by calling "sendfile" in Apache2::RequestIO

$rc = $resp->sendfile( $filename );
$rc = $resp->sendfile( $filename, $offset );
$rc = $resp->sendfile( $filename, $offset, $len );

It returns a APR::Const constant.

On success, APR::Const::SUCCESS is returned.

In case of a failure, a failure code is returned, in which case normally it should be returned to the caller

server

Sets or gets the HTTP header field Server

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server

server_timing

Sets or gets the HTTP header field Server-Timing

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing

set_content_length

Set the content length for this request, by calling "set_content_length" in Apache2::Response

$resp->set_content_length( $length );

It does not return any value.

set_cookie

Sets or gets the HTTP header field Set-Cookie

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie

set_etag

$resp->set_etag;

Set automatically the E-tag outgoing header.

It does not return any value.

set_keepalive

$ret = $resp->set_keepalive;

Returns the keepalive status for this request, by calling "set_keepalive" in Apache2::Response

It returns true if keepalive can be set, false otherwise.

set_last_modified

Sets the Last-Modified response header field to the value of the mtime field in the request structure, rationalized to keep it from being in the future, by calling "set_last_modified" in Apache2::Response

$resp->set_last_modified( $mtime );

If the $mtime argument is passed, $resp->update_mtime will be first run with that argument.

socket

my $socket      = $resp->socket;
my $prev_socket = $resp->socket( $new_socket );

Get or set the client socket and returns a APR::Socket object, by calling "client_socket" in Apache2::Connection

sourcemap

Sets or gets the HTTP header field SourceMap

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/SourceMap

status

Get or set the reply status for the client request, by calling "status" in Apache2::RequestRec

Normally you would use some Apache2::Const constant, e.g. Apache2::Const::REDIRECT.

From the Apache2::RequestRec documentation:

Usually you will set this value indirectly by returning the status code as the handler's function result. However, there are rare instances when you want to trick Apache into thinking that the module returned an Apache2::Const:OK status code, but actually send the browser a non-OK status. This may come handy when implementing an HTTP proxy handler. The proxy handler needs to send to the client, whatever status code the proxied server has returned, while returning Apache2::Const::OK to Apache. e.g.:

$resp->status( $some_code );
return( Apache2::Const::OK );

See also $resp->status_line, which. if set, overrides $resp->status.

status_line

my $status_line      = $resp->status_line();
my $prev_status_line = $resp->status_line( $new_status_line );

Get or sets the response status line. The status line is a string like 200 Document follows and it will take precedence over the value specified using the $resp->status() described above.

According to the Apache2::RequestRec documentation:

When discussing $resp->status we have mentioned that sometimes a handler runs to a successful completion, but may need to return a different code, which is the case with the proxy server. Assuming that the proxy handler forwards to the client whatever response the proxied server has sent, it will usually use status_line(), like so:

$resp->status_line( $response->code() . ' ' . $response->message() );
return( Apache2::Const::OK );

In this example $response could be for example an HTTP::Response object, if LWP::UserAgent was used to implement the proxy.

This method is also handy when you extend the HTTP protocol and add new response codes. For example you could invent a new error code and tell Apache to use that in the response like so:

$resp->status_line( "499 We have been FooBared" );
return( Apache2::Const::OK );

Here 499 is the new response code, and We have been FooBared is the custom response message.

strict_transport_security

Sets or gets the HTTP header field Strict-Transport-Security

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security

subprocess_env

Get or sets the Apache2::RequestRec subprocess_env table, or optionally set the value of a named entry.

From the Apache2::RequestRec documentation:

When called in void context with no arguments, it populate %ENV with special variables (e.g. $ENV{QUERY_STRING}) like mod_cgi does.

When called in a non-void context with no arguments, it returns an APR::Table object.

When the $key argument (string) is passed, it returns the corresponding value (if such exists, or undef. The following two lines are equivalent:

$val = $resp->subprocess_env( $key );
$val = $resp->subprocess_env->get( $key );

When the $key and the $val arguments (strings) are passed, the value is set. The following two lines are equivalent:

$resp->subprocess_env( $key => $val );
$resp->subprocess_env->set( $key => $val );

The subprocess_env table is used by Apache2::SubProcess, to pass environment variables to externally spawned processes. It is also used by various Apache modules, and you should use this table to pass the environment variables. For example if in PerlHeaderParserHandler you do:

$resp->subprocess_env( MyLanguage => "de" );

you can then deploy mod_include and write in .shtml document:

<!--#if expr="$MyLanguage = en" -->
English
<!--#elif expr="$MyLanguage = de" -->
Deutsch
<!--#else -->
Sorry
<!--#endif -->

timing_allow_origin

Sets or gets the HTTP header field Timing-Allow-Origin

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Timing-Allow-Origin

trailer

Sets or gets the HTTP header field Trailer

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Trailer

transfer_encoding

Sets or gets the HTTP header field Transfer-Encoding

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding

unescape

Unescape the given data chunk by calling "uri_unescape" in URI::Escape

update_mtime

Set the $resp->mtime field to the specified value if it is later than what is already there, by calling "update_mtime" in Apache2::Response

$resp->update_mtime( $mtime );

upgrade

Sets or gets the HTTP header field Upgrade

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Upgrade

uri_escape

Provided with a string and this uses URI::Escape to return an uri-escaped string.

uri_unescape

Provided with an uri-escaped string and this will decode it and return its original string, by calling "uri_unescape" in URI::Escape

url_decode

Provided with an url-encoded string and this will return its decoded version, by calling "decode" in APR::Request

url_encode

Provided with a string and this will return an url-encoded version, by calling "encode" in APR::Request

vary

Sets or gets the HTTP header field Vary

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary

via

Sets or gets the HTTP header field Via

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Via

want_digest

Sets or gets the HTTP header field Want-Digest

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Want-Digest

warning

Sets or gets the HTTP header field Warning

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Warning

write

Send partial string to the client, by calling "write" in Apache2::RequestIO

$cnt = $resp->write( $buffer );
$cnt = $resp->write( $buffer, $len );
$cnt = $resp->write( $buffer, $len, $offset );

It returns How many bytes were sent (or buffered).

See Apache2::RequestIO for more information.

www_authenticate

Sets or gets the HTTP header field WWW-Authenticate

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate

x_content_type_options

Sets or gets the HTTP header field X-Content-Type-Options

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options

x_dns_prefetch_control

Sets or gets the HTTP header field X-DNS-Prefetch-Control

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control

x_frame_options

Sets or gets the HTTP header field X-Frame-Options

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options

x_xss_protection

Sets or gets the HTTP header field X-XSS-Protection

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection

_request

Returns the embedded Apache2::RequestRec

_set_get_multi

$self->_set_get_multi( 'SomeHeader' => $some_value );

Sets or gets a header with multiple values. The value provided for the header can be either an array reference and it will be used as is (after being copied), or a regular string, which will be converted into an array reference by splitting it by comma.

If the value is undefined, it will remove the corresponding header.

$self->_set_get_multi( 'SomeHeader' => undef() );

If no value is provided, it returns the current value for this header as a Module::Generic::Array object.

_set_get_one

Sets or gets a header with the provided value. If the value is undefined, the header will be removed.

If no value is provided, it returns the current value as an array object (Module::Generic::Array) or as a scalar object (Module::Generic::Scalar) if it is not a reference.

_try( object accessor, method, [ arguments ] )

Given an object type, a method name and optional parameters, this attempts to call it.

Apache2 methods are designed to die upon error, whereas our model is based on returning undef and setting an exception with Module::Generic::Exception, because we believe that only the main program should be in control of the flow and decide whether to interrupt abruptly the execution, not some sub routines.

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.

To install Apache2::API, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Apache2::API

CPAN shell

perl -MCPAN -e shell
install Apache2::API

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)