[taler-docs] branch master updated: nexus fetch: cli man & manual

[gnunet]

This is an automated email from the git hooks/post-receive script.

ms pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new ccc9e40c nexus fetch: cli man & manual
ccc9e40c is described below

commit ccc9e40c21915920e9d678ff0fa999302ccd1de4
Author: MS <ms@taler.net>
AuthorDate: Fri Nov 10 19:09:25 2023 +0100

    nexus fetch: cli man & manual
---
 libeufin/nexus-manual.rst          | 73 +++++++++++++++++++++++++-------------
 manpages/libeufin-nexus.1.rst      | 12 ++++---
 manpages/libeufin-nexus.conf.5.rst | 12 ++-----
 3 files changed, 59 insertions(+), 38 deletions(-)

diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
index a434e1dc..447637d3 100644
--- a/libeufin/nexus-manual.rst
+++ b/libeufin/nexus-manual.rst
@@ -108,10 +108,10 @@ Sending payments
 
 Sending payments must follow a successful `EBICS subscriber setup 
<ebics-setup>`_,
 where the bank obtained the subscriber keys, and the subscriber accepted the
-bank keys.  The responsible subcommand is ``ebics-submit``, and its
-configuration is a **superset** of core-config_.  On top of that, it
-expects the database connection string, and *optionally* a frequency to
-check for submittable payments in the database.
+bank keys.  The responsible subcommand for sending payments is 
``ebics-submit``,
+and its configuration is a **superset** of core-config_.  On top of that, it
+expects the database connection string, and *optionally* a frequency to check
+for submittable payments in the database.
 
 The connection string is specified as
 
@@ -145,7 +145,7 @@ For testing
 -----------
 
 The ``ebics-submit`` subcommand is **not** suitable to send arbitrary
-payments, but rather to *submit* initiated payments that may be found
+payments, but rather to submit initiated payments that may be found
 in the database.
 
 Such initiated payments may be refunds of incoming payments with a subject
@@ -183,18 +183,7 @@ the database, submit what is submittable, and return.
 For production
 --------------
 
-The ``ebics-submit`` subcommand can run in long-polling, fixed frequency, or
-transient mode.
-
-The long-polling mode causes the command to never return and to submit the 
payments
-to the bank *as soon as they arrive in the database*.  To activate this mode, 
set
-the frequency to ``0s`` in the configuration.  Assuming that 
``$config_long_polling``
-is set as described above, the following invocation would make 
``ebics-submit`` run
-in long-polling mode:
-
-.. code-block:: console
-
-  libeufin-nexus ebics-submit -c $config_file
+The ``ebics-submit`` subcommand can run in fixed frequency, or transient mode.
 
 The fixed frequency mode causes the command to check the database every time 
the
 frequency period expires.  To activate this mode, and -- for example -- set a 
frequency
@@ -203,21 +192,55 @@ of five minutes, set the configuration value 
``FREQUENCY`` to ``5m``.  Assuming
 make ``ebics-submit`` check the database every five minutes, and submit any 
initiated
 payment according to their submission state.
 
-.. note::
-
-  long-polling is still unsupported and resubmission of payments with a
-  ``transient_failure`` after a long-polled trigger is under discussion.
-
 .. code-block:: console
 
   libeufin-nexus ebics-submit -c $config_fixed_frequency
 
 
-Finally, transient mode causes ``ebics-submit`` to check the database only 
once,
-submit any initiated payment according to their submission state, and soon 
return.
+Transient mode causes ``ebics-submit`` to check the database only once, submit 
any
+initiated payment according to their submission state, and return.
 
 .. code-block:: console
 
   libeufin-nexus ebics-submit -c $config
 
-There's no need to set the frequency in the configuration.
+Downloading records
+===================
+
+Downloading records must follow a successful `EBICS subscriber setup 
<ebics-setup>`_,
+where the bank obtained the subscriber keys, and the subscriber accepted the 
bank keys.
+
+The following configuration sets the (mandatory) database connection and a log 
directory
+where any downloaded record would be stored.
+
+.. code-block:: console
+  
+  [nexus-postgres]
+  config = postgres:///nexus
+  [nexus-fetch]
+  statement_log_directory = $LIBEUFIN_DATA_HOME/camt
+
+Assuming that ``$config_file`` contains any required option, the following 
command
+would download any unseen notifications (as camt.054 files).
+
+.. code-block:: console
+
+  libeufin-nexus ebics-fetch -c $config_file --transient
+
+The ``--transient`` flag makes the command to download only once and return.  
If the
+bank returned any records, look in ``$LIBEUFIN_DATA_HOME/cat/YYYY-MM-DD`` to 
find them.
+YYYY-MM-DD is the date when the download took place.
+
+To activate periodic downloads, add the following setting to the 
``nexus-fetch``
+configuration section in ``$config_file``:
+
+.. code-block:: console
+
+   frequency = 5m
+
+The following invocation would then download records every five minutes, 
asking the bank
+to only return documents that are timestamped *from* (inclusive) the last 
incoming transaction.
+
+.. code-block:: console
+
+  libeufin-nexus ebics-fetch -c $config_file
diff --git a/manpages/libeufin-nexus.1.rst b/manpages/libeufin-nexus.1.rst
index f4df6558..aee26e65 100644
--- a/manpages/libeufin-nexus.1.rst
+++ b/manpages/libeufin-nexus.1.rst
@@ -89,8 +89,7 @@ Its options are as follows:
 **-c** \| **--config** \ ‌\ *FILENAME*
    Specifies the configuration file.
 **--transient**
-   This flag, enabled by default, causes the command to run only once without 
any long-polling behaviour.
-   The configuration value FREQUENCY gets therefore ignored.
+   This flag, enabled by default, causes the command to check the database and 
submit only once, and then return.
 
 ebics-fetch
 -----------
@@ -102,10 +101,15 @@ This subcommands download banking records via EBICS.  By 
default it downloads no
 **-c** \| **--config** \ ‌\ *FILENAME*
    Specifies the configuration file.
 **--transient**
-   This flag, enabled by default, causes the command to run only once without 
any long-polling behaviour.
-   The configuration value FREQUENCY gets therefore ignored.
+   This flag, enabled by default, causes the command to perform one download 
and return.
 **--only-statements**
    It downloads statements (instead of notifications) in the form of camt.053 
documents.
+**--only-ack**
+   It downloads payment submissions acknowledgements (instead of 
notifications) in the form of pain.002 documents.
+**--only-reports**
+   It downloads only intraday reports (instead of notifications) in the form 
of camt.052 documents.
+**--pinned-start**
+  Only supported in --transient mode, this option lets specify the earliest 
timestamp of the downloaded documents.  The latest timestamp is always the 
current time.
 
 
 SEE ALSO
diff --git a/manpages/libeufin-nexus.conf.5.rst 
b/manpages/libeufin-nexus.conf.5.rst
index e5a712a8..14161918 100644
--- a/manpages/libeufin-nexus.conf.5.rst
+++ b/manpages/libeufin-nexus.conf.5.rst
@@ -101,12 +101,8 @@ FREQUENCY
   Duration value to instruct the ``ebics-submit`` subcommand how much to wait
   before checking the database again to find new unsubmitted payments.  The 
duration
   must be expressed with a number followed by the time unit.  The following 
time
-  units are supported: 's' (seconds), 'm' (minutes), 'h' (hours).
-  For example, the value *5m* causes retries to be run every five minutes.  
Whenever
-  the given number is zero, the retries are long-polled.  Note: the current 
version
-  does NOT support long-polling but would instead run in transient mode, 
whenever
-  the duration number is zero.  Finally, even with a duration number of zero, 
the
-  duration unit must be specified.
+  units are supported: 's' (seconds), 'm' (minutes), 'h' (hours).  For example,
+  the value *5m* causes retries to be run every five minutes.
 
 SUBMISSIONS_LOG_DIRECTORY
   Optional value to define the path where the pain.001 documents would be 
stored
@@ -128,9 +124,7 @@ FREQUENCY
   download from the bank.  The duration must be expressed with a number 
followed
   by the time unit.  The following time units are supported: 's' (seconds), 'm'
   (minutes), 'h' (hours).  For example, the value *5m* causes downloads to be 
run
-  every five minutes.  Whenever the given number is zero, the retries are 
long-polled.
-  Note: the current version does NOT support long-polling but would instead 
run in
-  transient mode.  Note: long polling depends also by the bank offering it.
+  every five minutes.
 
 STATEMENT_LOG_DIRECTORY
   Optional value to define the path where the downloaded documents would be 
stored

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.