NAME

Bio::Das::HTTP::Fetch - Manage the HTTP protocol for DAS transactions

SYNOPSIS

 my $fetcher      = Bio::Das::HTTP::Fetch->new(
                                    -request   => $request,
                                    -headers   => {'Accept-encoding' => 'gzip'},
                                    -proxy     => $proxy,
                                    -norfcwarn => $nowarn,
                  );

 $fetcher->send_request();
 $fetcher->read();

 my $request          = $fetcher->request;
 my $socket           = $fetcher->socket;
 my $error            = $fetcher->error;
 my $url              = $fetcher->url;
 my $path             = $fetcher->path;
 my $outgoing_args    = $fetcher->outgoing_args;
 my $outgoing_headers = $fetcher->outgoing_headers;
 my $auth             = $fetcher->auth;
 my $incoming_header  = $fetcher->incoming_header;
 my $method           = $fetcher->method;

 my $protocol         = $fetcher->mode([$new_protocol]);
 my $status           = $fetcher->status([$new_status]);
 my $debug            = $fetcher->debug([$new_debug]);

 my ($protocol,$host,$port,$path,$user,$pass) = $fetcher->parse_url($url);

DESCRIPTION

This is a low-level class that is used for managing multiplexed connections to DAS HTTP servers. It is used internally by Bio::Das and it is unlikely that application programs will ever interact with it directly. The exception is when writing custom authentication subroutines to fetch username/password information for password-protected servers, in which case an Bio::Das::HTTP::Fetch is passed to the authentication subroutine.

METHODS

Following is a complete list of methods implemented by Bio::Das::HTTP::Fetch.

$fetcher = Bio::Das::HTTP::Request->new(@args)

Create a new fetcher object. At the time the object is created, it will attempt to establish a non-blocking connection with the remote server. This means that the call to new() may be returned before the connection is established.

Arguments are as follows:

  Name         Description
  ----         -----------

  -request     The Bio::Das::Request to run.

  -headers     A hashref containing additional
               headers to attach to the HTTP request.
               Typically used to enable data stream compression.

  -proxy       An HTTP proxy to use.

  -norfcwarn   Disable the warning that appears when the request
               contains username/password information attached to
               the URL.

  -debug       Activate verbose debugging messages

$socket = $fetcher->socket

Return the IO::Socket associated with the HTTP request. The socket is marked nonblocking and may not yet be in a connected state.

$path = $fetcher->path

Return the path part of the HTTP request.

$request = $fetcher->request

Return the Bio::Das::Request object that the fetcher will attempt to satisfy.

$args = $fetcher->args

Returns a hashref containing the CGI arguments to be passed to the HTTP server. This is simply delegated to the request's args() method.

$url = $fetcher->url

Returns the URL for the HTTP request. This is simply delegated to the request's url() method.

$headers = $fetcher->outgoing_headers

Returns a hashref containing the HTTP headers that will be sent in the request.

$host = $fetcher->host

Returns the host to which the fetcher will connect. Note that this is not necessarily the same host as the DAS server, as this method will return the name of the proxy if an HTTP proxy has been specified. To get the DAS server hostname, call $fetcher->request->host.

$credentials = $fetcher->auth

Return the authentication credentials as a base64-encoded string.

$header = $fetcher->incoming_header

Retrieve the incoming HTTP header. Depending on the state of the connection, the header may be empty or incomplete.

$mode = $fetcher->mode([$new_mode])

This misnamed method gets or sets the protocol, which is one of 'http' for regular cleartext transactions or 'https' for transactions using the encrypting SSL/TLS protocol. Note that you must have IO::Socket::SSL and its associated libraries in order to use SSL/TLS.

$mode = $fetcher->mode([$new_mode])

This misnamed method gets or sets the protocol, which is one of 'http' for regular cleartext transactions or 'https' for transactions using the encrypting SSL/TLS protocol. Note that you must have IO::Socket::SSL and its associated libraries in order to use SSL/TLS.

$status = $fetcher->status([$new_status])

This method is used to interrogate or change the status of the transaction. The status keeps track of what has been done so far, and is one of:

  waiting          # request not yet sent
  reading header   # request sent, waiting for HTTP header
  reading body     # HTTP header received, waiting for HTTP body
  parsing body     # HTTP body partially received, parsing it
  0                # transaction finished normally, EOF.

$debug = $fetcher->debug([$new_debug])

Get or set the debug flag, which enables verbose diagnostic messages.

($protocol,$host,$port,$path,$user,$pass) = Bio::Das::HTTP::Fetch->parse_url($url,$norfcwarn)

This method is invoked as a class method (as Bio::Das::HTTP::Fetch->parse_url) to parse a URL into its components. The $norfcwarn flag inhibits a warning about the unsafe nature of embedding username/password information in the URL of unencrypted transactions.

$socket = Bio::Das::HTTP::Fetch->connect($protocol,$host,$port)

This method is used to make a nonblocking connection to the indicated host and port. $protocol is one of 'http' or 'https'. The resulting IO::Socket will be returned in case of success. Undef will be returned in case of other errors.

$status = $fetcher->send_request()

This method sends the HTTP request and returns the resulting status. Because of the vagaries of nonblocking IO, the complete request can be sent in one shot, in which case the returned status will be "reading header", or only a partial request might have been written, in which case the returned status will be "waiting." In the latter case, send_request() should be called again until the complete request has been submitted.

If a communications error occurs, send_request() will return undef, in which case it should not be called again.

$status = $fetcher->read()

This method is called when the fetcher is in one of the read states (reading header, reading body or parsing body). If successful, it returns the new status. If unsuccessful, it returns undef.

On the end of the transaction read() will return numeric 0.

$http_request_string = $fetcher->format_request

This method generates the appropriate GET or POST HTTP request and the HTTP request headers.

$cgi_query_string = $fetcher->format_args

This method generates the CGI query string.

$headers = $fetcher->format_headers

This method generates the outgoing HTTP request headers, for use by format_request().

$escaped_string = $fetcher->escape($unescaped_string)

This method performs URL escaping on the passed string.

$canonicalized_string = $fetcher->canonicalize($uncanonicalized_string)

This method canonicalizes the case of HTTP headers.

$fetcher->do_headers(@header_lines)

This method parses the incoming HTTP header and saves the fields internally where they can be accessed using the headers() method.

$result = $fetcher->do_body($body_data)

This method handles the parsing of the DAS document data by sending it to the Bio::Das::Request object. It returns a true result if parsing was successful, or false otherwise.

$error = $fetcher->error([$new_error])

When called without arguments, error() returns the last error message generated by the module. When called with arguments, error() sets the error message and returns undef.

$fetcher->load_ssl

This method performs initialization needed to use SSL/TLS transactions.

$fetcher->complete_ssl_handshake($sock)

This method is called to complete the SSL handshake, which must be performed in blocking mode. After completing the connection, the socket is set back to nonblocking.

AUTHOR

Lincoln Stein <lstein@cshl.org>.

Copyright (c) 2001 Cold Spring Harbor Laboratory

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.

SEE ALSO

Bio::Das::Request, Bio::Das::HTTP::Fetch, Bio::Das::Segment, Bio::Das::Type, Bio::Das::Stylesheet, Bio::Das::Source, Bio::RangeI