| 1 |
NAME |
| 2 |
LWP::Online - Does your process have access to the web |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use LWP::Online 'online'; |
| 6 |
|
| 7 |
# "Is the internet working?" |
| 8 |
die "NO INTARWWEB!!!" unless online(); |
| 9 |
|
| 10 |
# The above means something like this |
| 11 |
unless ( online('http') ) { |
| 12 |
die "No basic http access to the web"; |
| 13 |
} |
| 14 |
|
| 15 |
# Special syntax for use in test scripts that need |
| 16 |
# "real" access to the internet. Scripts will automatically |
| 17 |
# skip if connection fails. |
| 18 |
use LWP::Online ':skip_all'; |
| 19 |
use Test::More tests => 4; #after LWP::Online |
| 20 |
|
| 21 |
DESCRIPTION |
| 22 |
This module attempts to answer, as accurately as it can, one of the |
| 23 |
nastiest technical questions there is. |
| 24 |
|
| 25 |
Am I on the internet? |
| 26 |
|
| 27 |
The answer is useful in a wide range of decisions. For example... |
| 28 |
|
| 29 |
*Should my test scripts run the online portion of the tests or just skip |
| 30 |
them?* |
| 31 |
|
| 32 |
*Do I try to fetch fresh data from the server?* |
| 33 |
|
| 34 |
*If my request to the server breaks, is it because I'm offline, or |
| 35 |
because the server is offline?* |
| 36 |
|
| 37 |
And so on, and so forth. |
| 38 |
|
| 39 |
But a host of networking and security issues make this problem very |
| 40 |
difficult. There are firewalls, proxies (both well behaved and badly |
| 41 |
behaved). We might not have DNS. We might not have a network card at |
| 42 |
all! |
| 43 |
|
| 44 |
You might have network access, but only to a for-money wireless network |
| 45 |
that responds to ever HTTP request with a page asking you to enter your |
| 46 |
credit card details for paid access. Which means you don't "REALLY" have |
| 47 |
access. |
| 48 |
|
| 49 |
The mere nature of the question makes it practically unsolvable. |
| 50 |
|
| 51 |
But with the answer being so useful, and the only other alternative |
| 52 |
being to ask the user "duh... are you online?" (when you might not have |
| 53 |
a user at all) it's my gut feeling that it is worthwhile at least making |
| 54 |
an attempt to solve the problem, if only in a limited way. |
| 55 |
|
| 56 |
Why LWP::Online? Why not Net::Online? |
| 57 |
The nice thing about LWP::Online is that LWP deals with a whole range of |
| 58 |
different transports, and is very commonly installed. HTTP, HTTPS, FTP, |
| 59 |
and so on and so forth. |
| 60 |
|
| 61 |
Attempting to do a more generalised Net::Online that might also check |
| 62 |
for SSH and so on would end up most likely having to install a whole |
| 63 |
bunch of modules that you most likely will never use. |
| 64 |
|
| 65 |
So LWP forms a nice base on which to write a module that covers most of |
| 66 |
the situations in which you might care, while keeping the dependency |
| 67 |
overhead down to a minimum. |
| 68 |
|
| 69 |
Scope |
| 70 |
"Am I online?" is inherently an Open Problem. |
| 71 |
|
| 72 |
That is, it's a problem that had no clean permanent solution, and for |
| 73 |
which you could just keep writing more and more functionality |
| 74 |
indefinitely, asymtopically approaching 100% correctness but never |
| 75 |
reaching it. |
| 76 |
|
| 77 |
And so this module is intended to do as good a job as possible, without |
| 78 |
having to resort to asking any human questions (who may well get it |
| 79 |
wrong anyway), and limiting itself to a finite amount of programming |
| 80 |
work and a reasonable level of memory overhead to load the code. |
| 81 |
|
| 82 |
It is thus understood the module will never be perfect, and that if any |
| 83 |
new functionality is desired, it needs to be able to implemented by the |
| 84 |
person that desires the new behaviour, and in a reasonably small amount |
| 85 |
of additional code. |
| 86 |
|
| 87 |
This module is also not intended to compensate for malicious behaviour |
| 88 |
of any kind, it is quite possible that some malicious person might proxy |
| 89 |
fake versions of sites that pass our content checks and then proceed to |
| 90 |
show you other bad pages. |
| 91 |
|
| 92 |
Test Mode |
| 93 |
use LWP::Online ':skip_all'; |
| 94 |
|
| 95 |
As a convenience when writing tests scripts base on Test::More, the |
| 96 |
special ':skip_all' param can be provided when loading LWP::Online. |
| 97 |
|
| 98 |
This implements the functional equivalent of the following. |
| 99 |
|
| 100 |
BEGIN { |
| 101 |
require Test::More; |
| 102 |
unless ( LWP::Online::online() ) { |
| 103 |
Test::More->import( |
| 104 |
skip_all => 'Test requires a working internet connection' |
| 105 |
); |
| 106 |
} |
| 107 |
} |
| 108 |
|
| 109 |
The :skip_all special import flag can be mixed with regular imports. |
| 110 |
|
| 111 |
FUNCTIONS |
| 112 |
online |
| 113 |
# Default check (uses http) |
| 114 |
online() or die "No Internet"; |
| 115 |
|
| 116 |
# The above is equivalent to |
| 117 |
online('http') or die "No Internet"; |
| 118 |
|
| 119 |
The importable online function is the main functionality provided by |
| 120 |
LWP::Online. It takes a single optional transport name ('http' by |
| 121 |
default) and checks that LWP connectivity is available for that |
| 122 |
transport. |
| 123 |
|
| 124 |
Because it is intended as a Do What You Mean function, it checks not |
| 125 |
only that a network connection is available, and http requests return |
| 126 |
content, but also that it returns the CORRECT content instead of |
| 127 |
unexpected content supplied by a man in the middle. |
| 128 |
|
| 129 |
For example, many wireless connections require login or payment, and |
| 130 |
will return a service provider page for any URI that you attempt to |
| 131 |
fetch. |
| 132 |
|
| 133 |
The set of websites used for the testing is the Google, Amazon, Yahoo |
| 134 |
and CNN websites. The check is for a copyright statement on their |
| 135 |
homepage, and the function returns true as soon as two of the website |
| 136 |
return correctly, making the method relatively redundant. |
| 137 |
|
| 138 |
Returns true if the computer is "online" (has a working connection via |
| 139 |
LWP) or false if not. |
| 140 |
|
| 141 |
offline |
| 142 |
The importable offline function is provided as a convenience. |
| 143 |
|
| 144 |
It provides a simple pass-through (including any params) to the online |
| 145 |
function, but with a negated result. |
| 146 |
|
| 147 |
TO DO |
| 148 |
- Add more transport types that can be checked, somehow keeping the code |
| 149 |
growth under control. |
| 150 |
|
| 151 |
SUPPORT |
| 152 |
This module is stored in an Open Repository at the following address. |
| 153 |
|
| 154 |
<http://svn.ali.as/cpan/trunk/LWP-Online> |
| 155 |
|
| 156 |
Write access to the repository is made available automatically to any |
| 157 |
published CPAN author, and to most other volunteers on request. |
| 158 |
|
| 159 |
If you are able to submit your bug report in the form of new (failing) |
| 160 |
unit tests (which for this module will be extremely difficult), or can |
| 161 |
apply your fix directly instead of submitting a patch, you are strongly |
| 162 |
encouraged to do so as the author currently maintains over 100 modules |
| 163 |
and it can take some time to deal with non-Critical bug reports or |
| 164 |
patches. |
| 165 |
|
| 166 |
This will guarentee that your issue will be addressed in the next |
| 167 |
release of the module. |
| 168 |
|
| 169 |
If you cannot provide a direct test or fix, or don't have time to do so, |
| 170 |
then regular bug reports are still accepted and appreciated via the CPAN |
| 171 |
bug tracker. |
| 172 |
|
| 173 |
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LWP-Online> |
| 174 |
|
| 175 |
For other issues, for commercial enhancement or support, or to have your |
| 176 |
write access enabled for the repository, contact the author at the email |
| 177 |
address above. |
| 178 |
|
| 179 |
AUTHOR |
| 180 |
Adam Kennedy <[email protected]> |
| 181 |
|
| 182 |
SEE ALSO |
| 183 |
LWP::Simple |
| 184 |
|
| 185 |
COPYRIGHT |
| 186 |
Copyright 2006 - 2011 Adam Kennedy. |
| 187 |
|
| 188 |
This program is free software; you can redistribute it and/or modify it |
| 189 |
under the same terms as Perl itself. |
| 190 |
|
| 191 |
The full text of the license can be found in the LICENSE file included |
| 192 |
with this module. |
| 193 |
|