NAME

    Net::ICAP::Client - A client implementation of the ICAP (RFC 3507)
    protocol

VERSION

    Version 0.08

SYNOPSIS

        use Net::ICAP::Client;
    
        my $icap = Net::ICAP::Client->new('icap://icap-proxy.example.com/');
        my $request = HTTP::Request->new( 'POST' => 'https://www.example.com/path' );
        my ( $headers, $body ) = $icap->request( $request );
        if ($headers->isa('HTTP::Request') {
            # forward request to intended destination
        } elsif ($headers->isa('HTTP::Response') {
            # return response to original requestor
        }

DESCRIPTION

    This module provides a client interface to an ICAP (RFC 3507) Server
    <http://tools.ietf.org/html/rfc3507>. ICAP Servers are designed to
    inspect and modify HTTP Request and Responses before the Request is
    passed to backend systems or the Response goes back to the user.

SUBROUTINES/METHODS

 new

        my $icap = Net::ICAP::Client->new('icap://icap-proxy.example.com/');
        my $icap = Net::ICAP::Client->new('icaps://icap-proxy.example.com/', SSL_ca_path => '/path/to/ca-bundle.crt', %other_IO_SSL_Socket_options);

    By default, the SSL_verifycn_scheme, SSL_verifycn_name and
    SSL_verify_mode parameters are automatically set for icaps URIs, but
    these parameters may be overridden.

 debug

    $icap->debug() accepts an optional debug value and returns the current
    debug value

 allow_204

    $icap->allow_204() accepts an optional value to set whether the client
    will send an Allow: 204
    <https://tools.ietf.org/html/rfc3507#section-4.6> and returns the
    current setting

 allow_preview

    $icap->allow_preview() accepts an optional value to set whether the
    client will send an Preview
    <https://tools.ietf.org/html/rfc3507#section-4.5> and returns the
    current setting

 agent

    $icap->agent() accepts an optional User Agent string and returns the
    current User Agent string

 server_allows_204

    $icap->server_allows_204() returns true if the remote ICAP server can
    return a 204 (No modification needed) response. This method will issue
    an OPTIONS call to the remote server unless another OPTIONS call has
    been sent in the last ttl seconds.

 is_tag

    $icap->is_tag() returns the value of the remote ICAP server's ISTag
    <https://tools.ietf.org/html/rfc3507#section-4.7> header. This method
    will issue an OPTIONS call to the remote server unless another OPTIONS
    call has been sent in the last ttl seconds.

 service

    $icap->service() returns the value of the remote ICAP server's Service
    <https://tools.ietf.org/html/rfc3507#section-4.10.2> header. This
    method will issue an OPTIONS call to the remote server unless another
    OPTIONS call has been sent in the last ttl seconds.

 ttl

    $icap->ttl() returns the value of the remote ICAP server's Options-TTL
    <https://tools.ietf.org/html/rfc3507#section-4.10.2> header. This
    method will issue an OPTIONS call to the remote server unless another
    OPTIONS call has been sent in the last ttl seconds.

 max_connections

    $icap->max_connections() returns the value of the remote ICAP server's
    Max-Connections <https://tools.ietf.org/html/rfc3507#section-4.10.2>
    header. This method will issue an OPTIONS call to the remote server
    unless another OPTIONS call has been sent in the last ttl seconds.

 preview_size

    $icap->preview_size() returns the value of the remote ICAP server's
    Preview <https://tools.ietf.org/html/rfc3507#section-4.10.2> header.
    This method will issue an OPTIONS call to the remote server unless
    another OPTIONS call has been sent in the last ttl seconds.

 uri

    $icap->uri() returns the current URI of the remote ICAP server as a URI
    object.

 request

        my $icap = Net::ICAP::Client->new('icap://icap-proxy.example.com/');
        my $request_headers = HTTP::Headers->new();
        my $request = HTTP::Request->new( 'POST' => "https://www.example.com/path?name=value", $request_headers, "name2=value2" );
        my ( $request_or_response_headers, $filehandle_containing_possibly_updated_body ) = $icap->request( $request, $filehandle_containing_request_body );

    $icap->request() expects an HTTP::Request object and an optional
    filehandle. It will return an HTTP::Request or an HTTP::Response object
    containing the request or response without the body and a filehandle
    containing the body.

 response

        my $icap = Net::ICAP::Client->new('icap://icap-proxy.example.com/');
        my $response = HTTP::Response->new( '200', 'OK' );
        my ( $response_headers, $filehandle_containing_possibly_updated_body ) = $icap->response( $optional_request_or_undef, $response, $filehandle_containing_response_body );

    $icap->response() expects an HTTP::Request object (if available), an
    HTTP::Response object and an optional filehandle. It will return an
    HTTP::Response object containing the response without the response body
    and a filehandle containing the response body.

AUTHOR

    David Dick, <ddick at cpan.org>

DIAGNOSTICS

    Failed to write to icap server at %s

      Failed to write to the remote icap server. Check network status.

    Failed to write to STDERR

      Failed to write to STDERR. Check local machine settings.

    Incorrectly formatted debug line

      A debug call was made without being prefixed with a '>> ' or '<< '.
      This is a bug in Net::ICAP::Client

    Failed to connect to %s on port %s

      The connection to the remote icap server failed. Check
      network/SSL/TLS settings and status

    Failed to read from %s

      Failed to read from the remote icap server. Check network status

    Failed to seek to start of temporary file

      Failed to do a disk operation. Check disk settings for the mount
      point belonging to where temp files are being created

    Failed to seek to start of content handle

      Failed to do a disk operation. Check disk settings for the mount
      point belonging to the file that are passed into the request/response
      method

    ICAP Server returned a %s error

      The remote ICAP server returned an error. The TCP connection to the
      remote ICAP server will be automatically disconnected. Capture the
      network traffic and enter a bug report

    Failed to parse chunking length

      This is a bug in Net::ICAP::Client

    Unable to parse Encapsulated header

      The remote ICAP server did not return an Encapsulated header that
      could be understood by Net::ICAP::Client. Capture the network traffic
      and enter a bug report

    Unable to parse ICAP header

      The remote ICAP server did not return an ICAP header that could be
      understood by Net::ICAP::Client. Capture the network traffic and
      enter a bug report

    Failed to read from content handle

      Failed to do a disk operation. Check disk settings for the mount
      point belonging to the file that are passed into the request/response
      method

CONFIGURATION AND ENVIRONMENT

    Net::ICAP::Client requires no configuration files or environment
    variables.

DEPENDENCIES

    Net::ICAP::Client requires the following non-core modules

      HTTP::Request
      HTTP::Response
      IO::Socket::INET
      IO::Socket::SSL
      URI

INCOMPATIBILITIES

    None reported

BUGS AND LIMITATIONS

    To report a bug, or view the current list of bugs, please visit
    https://github.com/david-dick/net-icap-client/issues

LICENSE AND COPYRIGHT

    Copyright 2016 David Dick.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.