NAME
    LWP::Online - Does your process have access to the web

SYNOPSIS
      use LWP::Online 'online';
  
      # "Is the internet working?"
      unless ( online() ) {
          die "NO INTARWEB!!!";
      }
  
      # The above means something like this
      unless ( online('http') ) {
          die "No basic http access to the web";
      }

DESCRIPTION
    This module attempts to answer, as accurately as it can, one of the
    nastiest technical questions there is.

    Am I on the internet?

    The answer is useful in a wide range of decisions. For example...

    *Should my test scripts run the online portion of the tests or just skip
    them?*

    *Do I try to fetch fresh data from the server?*

    *If my request to the server breaks, is it because I'm offline, or
    because the server is offline?*

    And so on, and so forth.

    But a host of networking and security issues make this problem very
    difficult. There are firewalls, proxies (both well behaved and badly
    behaved). We might not have DNS. We might not have a network card at
    all!

    You might have network access, but only to a for-money wireless network
    that responds to ever HTTP request with a page asking you to enter your
    credit card details for paid access. Which means you don't "REALLY" have
    access.

    The mere nature of the question makes it practically unsolvable.

    But with the answer being so useful, and the only other alternative
    being to ask the user "duh... are you online?" (when you might not have
    a user at all) it's my gut feeling that it is worthwhile at least making
    an attempt to solve the problem, if only in a limited way.

  Why LWP::Online? Why not Net::Online?
    The nice thing about LWP::Online is that LWP deals with a whole range of
    different transports, and is very commonly installed. HTTP, HTTPS, FTP,
    and so on and so forth.

    Attempting to do a more generalised Net::Online that might also check
    for SSH and so on would end up most likely having to install a whole
    bunch of modules that you most likely will never use.

    So LWP forms a nice base on which to write a module that covers most of
    the situations in which you might care, while keeping the dependency
    overhead down to a minimum.

  Scope
    "Am I online?" is inherently an Open Problem.

    That is, it's a problem that had no clean permanent solution, and for
    which you could just keep writing more and more functionality
    indefinitely, asymtopically approaching 100% correctness but never
    reaching it.

    And so this module is intended to do as good a job as possible, without
    having to resort to asked a human questions (who may well get it wrong
    anyway), and limiting itself to a finite amount of programming work and
    a reasonable level of memory overhead to load the code.

    It is thus understood the module will never be perfect, and that if any
    new functionality is desired, it need to be able to implemented by the
    person that desires the new behaviour, and in a reasonably small amount
    of additional code.

    This module is also not intended to deal with malicious behaviour of any
    kind, it is quite possible that some malicious person might proxy fake
    versions of sites that pass our content checks and then proceed to show
    you other bad pages.

FUNCTIONS
TO DO
    - I'm writing this offline. Write better site checkers once I get online
    and can get hold of the actual front pages.

    - Add more transport types that can be checked, somehow keeping the code
    growth under control.

SUPPORT
    This module is stored in an Open Repository at the following address.

    <http://svn.phase-n.com/svn/cpan/trunk/LWP-Online>

    Write access to the repository is made available automatically to any
    published CPAN author, and to most other volunteers on request.

    If you are able to submit your bug report in the form of new (failing)
    unit tests (which for this module will be extremely difficult), or can
    apply your fix directly instead of submitting a patch, you are strongly
    encouraged to do so as the author currently maintains over 100 modules
    and it can take some time to deal with non-Critical bug reports or
    patches.

    This will guarentee that your issue will be addressed in the next
    release of the module.

    If you cannot provide a direct test or fix, or don't have time to do so,
    then regular bug reports are still accepted and appreciated via the CPAN
    bug tracker.

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LWP-Online>

    For other issues, for commercial enhancement or support, or to have your
    write access enabled for the repository, contact the author at the email
    address above.

AUTHOR
    Adam Kennedy <adamk@cpan.org>

SEE ALSO
    LWP::Simple

COPYRIGHT
    Copyright 2006 Adam Kennedy.

    Some parts copyright 2000 Sean M. Burke.

    Some parts copyright 2006 Chris Nandor.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.

