URLVerify.pm; docs / cleanup

Signed-off-by: Bill Erickson <berick@esilibrary.com>

diff --git a/Open-ILS/src/perlmods/lib/OpenILS/Application/URLVerify.pm b/Open-ILS/src/perlmods/lib/OpenILS/Application/URLVerify.pm
index 2d727d2..4e65410 100644 (file)
--- a/Open-ILS/src/perlmods/lib/OpenILS/Application/URLVerify.pm
+++ b/Open-ILS/src/perlmods/lib/OpenILS/Application/URLVerify.pm
@@ -5,8 +5,9 @@ use OpenSRF::Utils::Logger qw(:logger);
 use OpenSRF::MultiSession;
 use OpenILS::Utils::Fieldmapper;
 use OpenILS::Utils::CStoreEditor q/:funcs/;
-use Net::HTTP::NB;
 use OpenILS::Application::AppUtils;
+use Net::HTTP::NB;
+
 my $U = 'OpenILS::Application::AppUtils';
 
 
@@ -21,9 +22,28 @@ __PACKAGE__->register_method(
         params => [
             {desc => 'Authentication token', type => 'string'},
             {desc => 'Session ID (url_verify.session.id)', type => 'number'},
-            {desc => 'URL ID list (optional)', type => 'array'}
+            {desc => 'URL ID list (optional).  An empty list will result in no URLs being processed', type => 'array'},
+            {
+                desc => q/
+                    Options (optional).
+                        report_all => bypass response throttling and receive all URL sub-process responses.
+                            Not recommened for remote clients, because it can be a lot of data.
+                    /,
+                type => 'hash'
+            }
         ],
-        return => {desc => 'TODO'}
+        return => {desc => q/
+            Stream of objects containing the number of URLs to be processed (url_count), 
+            the number processed thus far including redirects (total_processed), 
+            and the current url_verification object (current_verification).  
+            
+            Note that total_processed may ultimately exceed url_count, since it 
+            includes non-anticipate-able redirects.
+
+            The final response contains url_count, total_processed, and the 
+            verification_attempt object (attempt).
+            /
+        }
     }
 );
 
@@ -51,10 +71,10 @@ sub validate_session {
                         join => { cbreb => { # bucket
                             join => { uvs => { # session
                                 filter => {id => $session_id}
-                            }}
-                        }}
-                    }
-                }
+                            }} # noisses
+                        }} # tekcub
+                    } # meti tekcub
+                } # lru
             }
         });
 
@@ -87,12 +107,12 @@ sub validate_session {
         success_handler => sub {
             my ($self, $req) = @_;
 
-            # API call streams fleshed url_verification objects.  We wrap 
+            # API call streams fleshed url_verification objects.  We wrap
             # those up with some extra info and pass them on to the caller.
 
             for my $resp (@{$req->{response}}) {
                 my $content = $resp->content;
-                
+
                 if ($content) {
 
                     $num_processed++;
@@ -105,14 +125,14 @@ sub validate_session {
                         });
                     }
 
-                    # start off responding quickly, then throttle 
+                    # start off responding quickly, then throttle
                     # back to only relaying every 256 messages.
                     $resp_window *= 2 unless $resp_window == 256;
                 }
             }
 
             # insert the per-thread delay, which keeps this thread
-            # active, which prevents a new thread from firing up to 
+            # active, which prevents a new thread from firing up to
             # replace it. (thread = multisession session)
             sleep $delay;
         },
@@ -127,8 +147,8 @@ sub validate_session {
 
     # Queue up the requests and let them fly
     $multises->request(
-        'open-ils.url_verify.verify_url', 
-        $auth, $attempt->id, $_) for @$url_ids; 
+        'open-ils.url_verify.verify_url',
+        $auth, $attempt->id, $_) for @$url_ids;
 
     # Wait for all requests to be completed
     $multises->session_wait(1);
@@ -193,14 +213,14 @@ sub validate_url {
     my $url = $e->retrieve_url_verify_url($url_id) or return $e->event;
 
     my $attempt = $e->retrieve_url_verify_verification_attempt([
-        $attempt_id, { 
-            flesh => 1, 
+        $attempt_id, {
+            flesh => 1,
             flesh_fields => {uvva => ['session']}
         }
     ]) or return $e->event;
 
     my $session = $attempt->session;
-    
+
     return $e->event unless $e->allowed('VERIFY_URL');
 
     my $depth = 0;
@@ -218,7 +238,7 @@ sub validate_url {
         }
 
         $seen_urls{$cur_url->url} = $cur_url;
-         
+
         my $url_resp = validate_one_url($e, $attempt, $cur_url, $timeout);
 
         # something tragic happened
@@ -249,7 +269,7 @@ sub validate_url {
             $vcation->res_text('Max Redirects');
         }
 
-        $e->xact_begin; 
+        $e->xact_begin;
         $e->create_url_verify_url_verification($vcation) or return $e->die_event;
         $e->xact_commit;
     }
@@ -272,7 +292,7 @@ sub validate_one_url {
     my $url_text = $url->url;
     my $redir_url;
 
-    # first, create the verification object so we can a) indicate that 
+    # first, create the verification object so we can a) indicate that
     # we're working on this URL and b) get the DB to set the req_time.
 
     my $vcation = Fieldmapper::url_verify::url_verification->new;
@@ -282,7 +302,7 @@ sub validate_one_url {
 
     # begin phase-I DB communication
 
-    $e->xact_begin; 
+    $e->xact_begin;
     $e->create_url_verify_url_verification($vcation) or return $e->die_event;
     $e->xact_commit;
 
@@ -299,7 +319,7 @@ sub validate_one_url {
 
         my $sel = IO::Select->new($req);
 
-        if ($sel->can_read($timeout)) { 
+        if ($sel->can_read($timeout)) {
 
             # request headers are ready for reading
 
@@ -334,7 +354,7 @@ sub validate_one_url {
                     } else {
                         $logger->info("url: server returned 3XX but no 'Location' header for url $url_text");
                     }
-                } 
+                }
             }
 
         } else {
@@ -343,7 +363,7 @@ sub validate_one_url {
             $logger->info("url: request timed out for $url_text");
         }
 
-    } else { 
+    } else {
 
         # Error building connection.  Invalid hostname, etc.