feat(logger): possibility to override debug mode's default logging mechanism. See README.md

Author: KaiSchwarz-cnic

README.md

@@ -20,6 +20,7 @@ This module is a connector library for the insanely fast HEXONET Backend API. Fo
 * Automatic IDN Domain name conversion to punycode (our API accepts only punycode format in commands)
 * Allows nested associative arrays in API commands to improve for bulk parameters
 * Connecting and communication with our API
+* Possibility to use a custom mechanism for debug mode
 * Several ways to access and deal with response data
 * Getting the command again returned together with the response
 * Sessionless communication
@@ -113,6 +114,27 @@ e.g. `$cl->setURL('http://127.0.0.1:8765/api/call.cgi');` would change the port.
 
 Don't use `https` for that setup as it leads to slowing things down as of the https `overhead` of securing the connection. In this setup we just connect to localhost, so no direct outgoing network traffic using `http`. The apache configuration finally takes care passing it to `https` for the final communication to the HEXONET API.
 
+### Customize Logging / Outputs
+
+When having the debug mode activated `WebService::Hexonet::Connector::Logger` will be internally used for doing outputs.
+Of course it could be of interest for integrators to look for a way of getting this replaced by a custom mechanism like forwarding things to a 3rd-party software, logging into file or whatever.
+
+```perl
+use 5.026_000;
+use strict;
+use warnings;
+use WebService::Hexonet::Connector;
+use MyCustomLogger::Logger;
+
+my $cl = WebService::Hexonet::Connector::APIClient->new();
+$cl->enableDebugMode() # activate debug outputs/logging
+$cl->setCustomLogger(MyCustomLogger::Logger->new()) # set your own mechanism by providing your own class
+$cl->setCredentials('test.user', 'test.passw0rd');
+my $response = $cl->request({ COMMAND => "StatusAccount" });
+```
+
+NOTE: Find an example for a logger class implementation plus POD documentation in `lib/WebService/Hexonet/Connector/Logger.pm`. If you have questions, feel free to open a github issue.
+
 ### Usage Examples
 
 Please have an eye on our [HEXONET Backend API documentation](https://github.com/hexonet/hexonet-api-documentation/tree/master/API). Here you can find information on available Commands and their response data.

lib/WebService/Hexonet/Connector/APIClient.pm

@@ -4,6 +4,7 @@ use 5.026_000;
 use strict;
 use warnings;
 use utf8;
+use WebService::Hexonet::Connector::Logger;
 use WebService::Hexonet::Connector::Response;
 use WebService::Hexonet::Connector::ResponseTemplateManager;
 use WebService::Hexonet::Connector::SocketConfig;
@@ -31,10 +32,28 @@ sub new {
         debugMode    => 0,
         socketConfig => WebService::Hexonet::Connector::SocketConfig->new(),
         ua           => q{},
-        curlopts     => {}
+        curlopts     => {},
+        logger       => WebService::Hexonet::Connector::Logger->new()
     }, $class;
     $self->setURL($ISPAPI_CONNECTION_URL);
     $self->useLIVESystem();
+    $self->setDefaultLogger();
+    return $self;
+}
+
+
+sub setDefaultLogger {
+    my $self = shift;
+    $self->{logger} = WebService::Hexonet::Connector::Logger->new();
+    return $self;
+}
+
+
+sub setCustomLogger {
+    my ( $self, $logger ) = shift;
+    if ( defined($logger) && $logger->can('log') ) {
+        $self->{logger} = $logger;
+    }
     return $self;
 }
 
@@ -314,22 +333,17 @@ sub request {
 
     my $r = $ua->post( $cfg->{CONNECTION_URL}, $post );
     if ( $r->is_success ) {
-        $r = $r->decoded_content;
+        $r = WebService::Hexonet::Connector::Response->new( $r->decoded_content, $newcmd, $cfg );
         if ( $self->{debugMode} ) {
-            print {*STDOUT} Dumper($newcmd);
-            print {*STDOUT} Dumper($secured);
-            print {*STDOUT} Dumper($r);
+            $self->{logger}->log( $secured, $r );
         }
     } else {
-        my $err = $r->status_line;
-        $r = $rtm->getTemplate('httperror')->getPlain();
+        $r = WebService::Hexonet::Connector::Response->new( $rtm->getTemplate('httperror')->getPlain(), $newcmd, $cfg );
         if ( $self->{debugMode} ) {
-            print {*STDERR} Dumper($newcmd);
-            print {*STDERR} Dumper($secured);
-            print {*STDERR} Dumper($r);
+            $self->{logger}->log( $secured, $r, $r->status_line );
         }
     }
-    return WebService::Hexonet::Connector::Response->new( $r, $newcmd, $cfg );
+    return $r;
 }
 
 

lib/WebService/Hexonet/Connector/Logger.pm

@@ -0,0 +1,90 @@
+package WebService::Hexonet::Connector::Logger;
+
+use 5.026_000;
+use strict;
+use warnings;
+use Data::Dumper;
+
+use version 0.9917; our $VERSION = version->declare('v2.8.1');
+
+
+sub new {
+    my ($class) = @_;
+    return bless {}, $class;
+}
+
+
+sub log {
+    my ( $self, $post, $r, $error ) = @_;
+    if ( defined $error ) {
+        print {*STDERR} Dumper($post);
+        print {*STDERR} 'HTTP communication failed: ' . $error;
+        print {*STDERR} Dumper( $r->getCommandPlain() );
+        print {*STDERR} Dumper( $r->getPlain() );
+    } else {
+        print {*STDOUT} Dumper($post);
+        print {*STDOUT} Dumper( $r->getCommandPlain() );
+        print {*STDOUT} Dumper( $r->getPlain() );
+    }
+    return $self->{data};
+}
+
+1;
+
+__END__
+
+=pod
+
+=head1 NAME
+
+WebService::Hexonet::Connector::Logger - Library to cover API request and response data output / logging.
+
+=head1 SYNOPSIS
+
+This module is internally used by the L<WebService::Hexonet::Connector::APIClient|WebService::Hexonet::Connector::APIClient> module.
+To be used in the way:
+
+    # create a new instance by
+    $logger = WebService::Hexonet::Connector::Logger->new();
+
+    # Log API Request / Response Data
+    # * specify request data in $data in string format
+    # * specify an instance of WebService::Hexonet::Connector::Response in $r.    
+    # * specify an error message as string in $error (optional parameter)
+    $logger->log( $data, $r, $error );
+    #  vs.
+    $logger->log( $data, $r );    
+
+=head1 DESCRIPTION
+
+HEXONET Backend API communication will be printed to STDOUT/STDERR by default.
+This mechanism can be overwritten by a CustomLogger implementation.
+Use method setCustomLogger of WebService::Hexonet::Connector::APIClient for this.
+Important is that a custom implementation provides method `log` and supports all the arguments explained.
+
+=head2 Methods
+
+=over
+
+=item C<new>
+
+Returns a new L<WebService::Hexonet::Connector::Logger|WebService::Hexonet::Connector::Logger> object.
+
+=item C<log($post, $r, $error)>
+
+Log API Request / Response Data
+Specify request data in $data in string format
+Specify an instance of WebService::Hexonet::Connector::Response in $r.
+Specify an error message as string in $error. Optional. Thought for forwarding HTTP errors.
+
+=back
+
+=head1 LICENSE AND COPYRIGHT
+
+This program is licensed under the L<MIT License|https://raw.githubusercontent.com/hexonet/perl-sdk/master/LICENSE>.
+
+=head1 AUTHOR
+
+L<HEXONET GmbH|https://www.hexonet.net>
+
+=cut

scripts/generatedocs.sh

@@ -5,6 +5,7 @@ perldoc -oHTML -ddocs/connector.html WebService::Hexonet::Connector
 perldoc -oHTML -ddocs/apiclient.html WebService::Hexonet::Connector::APIClient
 perldoc -oHTML -ddocs/column.html WebService::Hexonet::Connector::Column
 perldoc -oHTML -ddocs/record.html WebService::Hexonet::Connector::Record
+perldoc -oHTML -ddocs/logger.html WebService::Hexonet::Connector::Logger
 perldoc -oHTML -ddocs/response.html WebService::Hexonet::Connector::Response
 perldoc -oHTML -ddocs/responseparser.html WebService::Hexonet::Connector::ResponseParser
 perldoc -oHTML -ddocs/responsetemplate.html WebService::Hexonet::Connector::ResponseTemplate

scripts/perltidy.sh

@@ -4,6 +4,7 @@ perltidy -pro=.perltidyrc lib/WebService/Hexonet.pm
 perltidy -pro=.perltidyrc lib/WebService/Hexonet/Connector.pm
 perltidy -pro=.perltidyrc lib/WebService/Hexonet/Connector/APIClient.pm
 perltidy -pro=.perltidyrc lib/WebService/Hexonet/Connector/Column.pm
+perltidy -pro=.perltidyrc lib/WebService/Hexonet/Connector/Logger.pm
 perltidy -pro=.perltidyrc lib/WebService/Hexonet/Connector/Record.pm
 perltidy -pro=.perltidyrc lib/WebService/Hexonet/Connector/Response.pm
 perltidy -pro=.perltidyrc lib/WebService/Hexonet/Connector/ResponseParser.pm

scripts/podchecker.sh

@@ -1,4 +1,4 @@
 #!/bin/bash
 cd lib/WebService || exit
-podchecker Hexonet.pm Hexonet/Connector.pm Hexonet/Connector/APIClient.pm Hexonet/Connector/Column.pm Hexonet/Connector/Record.pm Hexonet/Connector/Response.pm Hexonet/Connector/ResponseParser.pm Hexonet/Connector/ResponseTemplate.pm Hexonet/Connector/ResponseTemplateManager.pm Hexonet/Connector/SocketConfig.pm 
+podchecker Hexonet.pm Hexonet/Connector.pm Hexonet/Connector/APIClient.pm Hexonet/Connector/Column.pm Hexonet/Connector/Logger.pm Hexonet/Connector/Record.pm Hexonet/Connector/Response.pm Hexonet/Connector/ResponseParser.pm Hexonet/Connector/ResponseTemplate.pm Hexonet/Connector/ResponseTemplateManager.pm Hexonet/Connector/SocketConfig.pm 
 cd ../.. || exit

updateVersion.sh

@@ -12,6 +12,7 @@ sed -i "s/declare('v[0-9]\\+\\.[0-9]\\+\\.[0-9]\\+')/declare('v${newversion}')/g
 sed -i "s/declare('v[0-9]\\+\\.[0-9]\\+\\.[0-9]\\+')/declare('v${newversion}')/g" lib/WebService/Hexonet/Connector.pm
 sed -i "s/declare('v[0-9]\\+\\.[0-9]\\+\\.[0-9]\\+')/declare('v${newversion}')/g" lib/WebService/Hexonet/Connector/APIClient.pm
 sed -i "s/declare('v[0-9]\\+\\.[0-9]\\+\\.[0-9]\\+')/declare('v${newversion}')/g" lib/WebService/Hexonet/Connector/Column.pm
+sed -i "s/declare('v[0-9]\\+\\.[0-9]\\+\\.[0-9]\\+')/declare('v${newversion}')/g" lib/WebService/Hexonet/Connector/Logger.pm
 sed -i "s/declare('v[0-9]\\+\\.[0-9]\\+\\.[0-9]\\+')/declare('v${newversion}')/g" lib/WebService/Hexonet/Connector/Record.pm
 sed -i "s/declare('v[0-9]\\+\\.[0-9]\\+\\.[0-9]\\+')/declare('v${newversion}')/g" lib/WebService/Hexonet/Connector/Response.pm
 sed -i "s/declare('v[0-9]\\+\\.[0-9]\\+\\.[0-9]\\+')/declare('v${newversion}')/g" lib/WebService/Hexonet/Connector/ResponseParser.pm