Debian Codegraph @

README

raw
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