Merge pull request #9 from wdpypere/17.2.0

17.2.0 documentation

docs/CAF/Download::LWP.md

@@ -0,0 +1,67 @@
+
+### NAME
+
+`CAF::Download::LWP` class to use `LWP` (and `Net::HTTPS`).
+
+### DESCRIPTION
+
+`CAF::Download::LWP` prepares `LWP` (and `Net::HTTPS`) and
+provides interface to `LWP::UserAgent`.
+
+Remarks wrt SSL/TLS:
+
+- If LWP is recent enough (v8.333, e.g. on EL6+),
+the choice of SSL module will be the system default
+(typically `IO::Socket::SSL` when available, `Net::SSL` otherwise).
+
+    The usual environment variable will not be honoured
+    (this module will typically be executed in a minimal environment anyway).
+
+    When LWP is too old, `Net::SSL` will be forced (e.g. on EL5).
+
+- If LWP is recent enough and `IO::Socket::SSL` is the default,
+hostname verification is forced.
+
+### METHODS
+
+- `_initialize`
+
+    Initialize the object.
+
+    Optional arguments:
+
+    - `log`
+
+        A [Reporter](../CAF/Reporter.md) object to log to.
+
+- \_get\_ua
+
+    Prepare the environment and initialise `LWP::UserAgent`.
+    Best-effort to handle ssl setup, `Net::SSL` vs `IO::Socket::SSL`
+    and `verify_hostname`.
+
+    Example usage
+        ...
+        my $ua = $self->\_get\_ua(%opts);
+
+        local %ENV = %ENV;
+        $self->update_env(\%ENV);
+        ...
+
+    Returns the `LWP::UserAgent` instance or undef.
+
+    Options
+
+    - cacert: the CA file
+    - cadir: the CA path
+    - cert: the client certificate filename
+    - key: the client certificate private key filename
+    - ccache: the kerberos crednetial cache
+    - timeout: set timeout
+
+- \_do\_ua
+
+    Initialise `LWP::UserAgent` using `_get_ua` method
+    and run `method` with arrayref `args`.
+
+    All named options are passed to `_get_ua`.

docs/CAF/Kerberos.md

@@ -19,7 +19,7 @@ To create a new ticket for principal SERVICE/host@REALM
 
     # set environment to temporary credential cache
     # temporary cache is cleaned-up during destroy of $krb
-    local %ENV;
+    local %ENV = %ENV;
     $krb->update_env(\%ENV);
 
 #### Methods

docs/CAF/Object.md

@@ -80,7 +80,7 @@ In particular, one should avoid to return the `$self` instance at the end of
 
     To be used as
         # Setup local environment
-        local %ENV;
+        local %ENV = %ENV;
         $self->update\_env(\\%ENV);
 
     Example:
@@ -97,7 +97,7 @@ In particular, one should avoid to return the `$self` instance at the end of
         {
            ...
            # Setup local environment
-           local %ENV;
+           local %ENV = %ENV;
            $self->update_env(\%ENV);
 
            # everything in the remainder of the method runs in modified environment

docs/CAF/Path.md

@@ -79,18 +79,20 @@ undef on failure and store the error message in the `fail` attribute.
     This is basically the perl builtin `-d`,
     wrapped in a method to allow unittesting.
 
-    A broken symlink is not a directory. (As `-d` follows a symlink,
-    a broken symlink either exists with `-l` or not.)
+    If  `directory` is a symlink, the symlink target
+    is tested. If the symlink is broken (no target), 
+    `directory_exists` returns false.
 
 - file\_exists
 
-    Test if `filename` exists ans is a directory.
+    Test if `filename` exists and is a file.
 
     This is basically the perl builtin `-f`,
     wrapped in a method to allow unittesting.
 
-    A broken symlink is not a file. (As `-f` follows a symlink,
-    a broken symlink either exists with `-l` or not.)
+    If  `filename` is a symlink, the symlink target
+    is tested. If the symlink is broken (no target), 
+    `file_exists` returns false.
 
 - any\_exists
 
@@ -99,8 +101,8 @@ undef on failure and store the error message in the `fail` attribute.
     This is basically the perl builtin `-e || -l`,
     wrapped in a method to allow unittesting.
 
-    A broken symlink exists. As `-e` follows a symlink,
-    a broken symlink either exists with `-l` or not.
+    A broken symlink (symlink whose target doesn't
+    exist) exists: `any_exists` returns true.
 
 - cleanup
 

docs/CAF/Reporter.md

@@ -13,8 +13,7 @@
 
     sub new {
         ...
-        $self->setup_reporter(2, 0, 1);
-        $self->set_report_logfile($logger);
+        $self->config_reporter(debuglvl => 2, verbose => 1, logfile => $logger);
         ...
     }
 
@@ -45,43 +44,65 @@ with the `set_logfile` method.
 
     Setup default/initial values for reporter. Returns success.
 
-- `setup_reporter ($debuglvl, $quiet, $verbose, $facility)`: boolean
+- config\_reporter
 
-    Reporter setup:
+    Reporter configuration:
 
-    - `$debuglvl` sets the (highest) debug level, for messages reported with
+    Following options are supported
+
+    - debuglvl
+
+        Set the (highest) debug level, for messages reported with
         the 'debug' method.
         The following recommendations apply:
             0: no debug information
             1: main package
             2: main libraries/functions
             3: helper libraries
             4: core functions (constructors, destructors)
-    - `$quiet`: if set to a true value (eg. 1), stops any output to console.
-    - `$verbose`: if set to a true value (eg. 1), produce verbose output
-                (with the `verbose` method). Implied by debug >= 1.
-    - `$facility`: syslog facility the messages will be sent to
-    - `$verbose_logfile`: reporting to logfiles will be verbose
 
-    If any of these arguments is `undef`, current application settings
-    will be preserved.
+    - quiet
 
-- `set_report_logfile($loginstance)`: bool
+        If set to a true value (eg. 1), stops any output to console.
 
-    If `$loginstance` is defined, it will be used as log file. `$loginstance` can be
-    any type of class object reference, but the object must support a
-    `print(@array)` method. Typically, it should be an `CAF::Log`
-    instance. If `$loginstance` is undefined, no log file will be used.
+    - verbose
 
-    Returns SUCCESS on success, undef otherwise.
+        If set to a true value (eg. 1), produce verbose output
+        (with the `verbose` method). Implied by debug >= 1.
 
-    (The method name is slightly misleading, because is it does not set the logfile's
-    filename, but the internal `$LOGFILE` attribute).
+    - facility
+
+        The syslog facility the messages will be sent to
+
+    - verbose\_logfile
+
+        All reporting to logfiles will be verbose
+
+    - logfile
+
+        `logfile` can be any type of class object reference,
+        but the object must support a `print(@array)` method.
+        Typically, it should be an [Log](../CAF/Log.md) instance.
+
+        If `logfile` is defined but false, no logfile will be used.
+
+        (The name is slightly misleading, because is it does not set the logfile's
+        filename, but the internal `$LOGFILE` attribute).
+
+    - struct
+
+        Enable the structured logging type `struct` (implemented by method
+        ` <_struct_<struct` >>).
+
+        If `struct` is defined but false, structured logging will be disabled.
+
+    If any of these arguments is `undef`, current application settings
+    will be preserved.
 
 - `init_logfile($filename, $options)`: bool
 
     Create a new **CAF::Log** instance with `$filename` and `$options` and
-    set it using `set_report_logfile`.
+    set it using `config_reporter`.
     Returns SUCCESS on success, undef otherwise.
 
     (The method name is slightly misleading, because is it does
@@ -133,13 +154,13 @@ with the `set_logfile` method.
 
 - `verbose(@array)`: boolean
 
-    If `verbose` is enabled (via `setup_reporter`), the `verbose` method
+    If `verbose` is enabled (via `config_reporter`), the `verbose` method
     logs using [syslog](../components/syslog.md) method with `notice` priority
     and reports `@array` using the `report` method, but with a `[VERB]` prefix.
 
 - `debug($debuglvl, @array)`: boolean
 
-    If `$debuglvl` is higher or equal than then one set via `setup_reporter`,
+    If `$debuglvl` is higher or equal than then one set via `config_reporter`,
     the `debug` method
     logs to syslog with `debug` priority
     and reports `@array` using the `report` method, but with a `[DEBUG]` prefix.
@@ -150,7 +171,12 @@ with the `set_logfile` method.
 - `log(@array)`: boolean
 
     Writes `@array` as a concatenated string with added newline
-    to the log file, if one is setup (via `set_report_logfile`).
+    to the log file, if one is setup
+    (via `<config_reporter(logfile =` $loginst) >>).
+
+    If the last argument is a hashref and structured logging is enabled
+    (via `<config_reporter(struct =` $type) >>), call the structured
+    logging method with this hashref as argument.
 
 - `syslog($priority, @array)`
 
@@ -161,6 +187,11 @@ with the `set_logfile` method.
 
     (Return value is always undef.)
 
+- \_struct\_CEEsyslog
+
+    A structured logging method that uses CEE `Common Event Expression` format
+    and reports it via syslog with info facility.
+
 - `set_report_history($historyinstance)`: bool
 
     Set `$historyinstance` as the reporter's history
@@ -183,3 +214,27 @@ with the `set_logfile` method.
     - `$WHOAMI`
 
         Current class name `ref($self)`.
+
+#### Deprecated/legacy methods
+
+- setup\_reporter
+
+    Deprecated method to configure the reporter.
+
+    The configure options `debuglvl`, `quiet`, `verbose`, `facility`, `verbose_logfile`
+    are passed as postional arguments in that order.
+        $self->setup\_reporter(2, 0, 1);
+    is equal to
+        $self->config\_reporter(debuglvl => 2, quiet => 0, verbose => 1);
+
+- set\_report\_logfile
+
+    Deprecated method to configure the reporter `LOGFILE` attribute:
+        $self->setup\_report\_logfile($instance);
+    is equal to
+        $self->config\_reporter(logfile => $instance);
+
+    Returns SUCCESS on success, undef otherwise.
+
+    (The method name is slightly misleading, because is it does not set the logfile's
+    filename, but the internal `$LOGFILE` attribute).

docs/Unittesting/Quattor.md

@@ -21,7 +21,7 @@ as `target/test/profiles/foo.json`, while the cache will be stored in
 under `target/test/profiles/foo/`.
 
 This binary cache may be converted in an
-[EDG::WP4::CCM::Configuration](../CCM/Configuration.md) object using the
+`EDG::WP4::CCM::CacheManager::Configuration` object using the
 `get_config_for_profile` function.
 
 ### INTERNAL INFRASTRUCTURE
@@ -309,10 +309,6 @@ The following functions are exported by default:
 
     Reset `caf_path` ref. If `name` is defined, only reset that cache.
 
-- warn\_is\_ok
-
-    By default, Perl warnings are mapped to failing tests.
-
 ### BUGS
 
 Probably many. It does quite a lot of internal black magic to make

docs/Unittesting/Quattor::Doc.md

@@ -28,6 +28,12 @@ Should be used mainly as follows:
 
         Array reference of podfiles to test (default empty)
 
+    - emptypoddirs
+
+        Array reference of poddirs that must be empty (or non-existing).
+        If a directory is in both `poddirs` and `emptypoddirs`,
+        if is considered an empty poddir.
+
     - panpaths
 
         Array reference of paths that hold pan files to check for annotations.

docs/Unittesting/Quattor::Object.md

@@ -1,5 +1,9 @@
 
-####  add\_loghist
+####  warn\_is\_ok
+
+By default, Perl warnings are mapped to failing tests.
+
+#### add\_loghist
 
 Add a log `message` for `type` to the log history.
 

docs/Unittesting/Quattor::Panc.md

@@ -26,6 +26,11 @@ If undef is passed, remove the 'includepath' option.
 
 Return an array reference with the 'includepath' directories.
 
+#### is\_object\_template
+
+Given profile name (and optional resourcesdir for relative profile filename),
+test if the profile is a valid object template.
+
 #### Compile pan object template into JSON profile
 
 Compile the pan [profile](../components/profile.md) (file '`profile`.pan' in `resourcesdir`)

docs/Unittesting/Quattor::ProfileCache.md

@@ -43,7 +43,7 @@ will return the `panc` exitcode upon `panc` failure.
 
 Returns a configuration object for the profile given as an
 argument. The profile should be one of the arguments given to
-[Test::Quattor](Quattor.md) when loading it.
+`Test::Quattor` when loading it.
 
 If the configuration cannot be found, an error is reported, and
 a test fails.