// file      : bbot/agent.cli
// license   : MIT; see accompanying LICENSE file

include <libbbot/manifest.hxx>;

include <bbot/common.cli>;

"\section=1"
"\name=bbot-agent"
"\summary=build bot agent"

namespace bbot
{
  {
    "<options> <url>",

    "
    \h|SYNOPSIS|

    \c{\b{bbot-agent --help}\n
       \b{bbot-agent --version}\n
       \b{bbot-agent} [<options>] <url>...}

    \h|DESCRIPTION|

    \cb{bbot-agent} @@ TODO.

    Note that on termination \cb{bbot-agent} may leave behind a machine lock
    and working machine snapshot. It is expected that the caller (normally
    Build OS monitor) cleans them up before restarting the agent.
    "
  }

  class agent_options
  {
    "\h|OPTIONS|"

    bool --help {"Print usage information and exit."}
    bool --version {"Print version and exit."}

    uint16_t --verbose = 1
    {
      "<level>",
      "Set the diagnostics verbosity to <level> between 0 and 6 with level 1
       being the default."
    }

    bool --systemd-daemon
    {
      "Run as a simple systemd daemon."
    }

    string --toolchain-name = "default"
    {
      "<str>",
      "Toolchain name, \cb{default} by default."
    }

    uint16_t --toolchain-num = 1
    {
      "<num>",
      "Toolchain number, 1 by default. If agents are running for several
       toolchains, then each of them should have a unique toolchain number
       between 1 and 99. This number is used as an offset for network ports,
       interfaces, etc."
    }

    string --toolchain-lock // Note: string to allow empty path.
    {
      "<path>",
      "Absolute path to the global toolchain lock file. If unspecified, then
       \c{\b{/var/lock/bbot-agent-}\i{toolchain-name}\b{.lock}} is used by
       default. If empty path is specified then no global locking is
       performed. If one of the \cb{--fake-*} options is specified, then no
       locking is performed by default."
    }

    standard_version --toolchain-ver
    {
      "<stdver>",
      "Toolchain version. If unspecified, then the agent's version will be
       used (which will be imprecise for snapshot versions)."
    }

    string --toolchain-id
    {
      "<str>",
      "Toolchain id. If unspecified or empty, then no re-bootstrapping on
       toolchain changes will be performed (which is primarily useful for
       testing)."
    }

    interactive_mode --interactive = interactive_mode::false_
    {
      "<mode>",
      "Interactive build support. Valid values for this option are \cb{false}
       (only non-interactive), \cb{true} (only interactive), and \cb{both}.
       If this option is not specified, then only non-interactive builds
       are supported."
    }

    // We reserve 0 in case in the future we want to distinguish a single-
    // instance mode or some such.
    //
    uint16_t --instance = 1
    {
      "<num>",
      "Instance number, 1 by default. If several instances of an agent are
       running for the same toolchain, then each of them should have a unique
       instance number between 1 and 99. This number is used as an offset for
       network ports, interfaces, etc."
    }

    uint16_t --instance-max = 0
    {
      "<num>",
      "Maximum number of instances that can perform tasks concurrently. If the
       number of instances that have been started is greater than this number
       (normally by just one), then when the maximum number of tasks is
       already being performed, the extra instances operate in the \i{priority
       monitor} mode: they only query controller URLs with priorities higher
       than of the existing tasks and can only perform a task by interrupting
       one of them. If the maximum number of instances is \cb{0} (default),
       then it is assumed the number of instances started is the maximum
       number, essentially disabling the priority monitor functionality."
    }

    size_t --cpu = 1
    {
      "<num>",
      "Number of CPUs (threads) to use, 1 by default."
    }

    size_t --ram (1024 * 1024) // 1G
    {
      "<num>",
      "Amount of RAM (in kB) to use, 1G by default."
    }

    string --bridge = "br1"
    {
      "<iface>",
      "Bridge interface to use for machine networking, \cb{br1} by default."
    };

    path --auth-key
    {
      "<file>",
      "Private key for the public key-based agent authentication. If not
       specified, then the agent will not be able to request tasks from
       controllers that require authentication.

       The file is expected to contain a single PEM-encoded private key
       without a password. A suitable key can be generated using the
       following command:

       \
       $ openssl genrsa 4096 >key.pem
       \
       "
    }

    strings --trust
    {
      "<fingerprint>",
      "Trust repository certificate with a SHA256 <fingerprint>."
    }

    dir_path --machines = "/build/machines/"
    {
      "<dir>",
      "The location of the build machines, \cb{/build/machines/} by default."
    }

    dir_path --tftp = "/build/tftp/"
    {
      "<dir>",
      "The location of the TFTP server root, \cb{/build/tftp/} by default."
    }

    // Low 23401+, 23501+, 23601+, etc., all look good collision-wise with
    // with anything useful.
    //
    uint16_t --tftp-port = 23400
    {
      "<num>",
      "TFTP server port base, 23400 by default. The actual port is calculated
       by adding an offset calculated based on the toolchain and instance
       numbers."
    }

    size_t --bootstrap-timeout = 3600
    {
      "<sec>",
      "Maximum number of seconds to wait for machine bootstrap completion,
       3600 (60 minutes) by default."
    }

    size_t --bootstrap-retries = 2
    {
      "<num>",
      "Number of times to retry a mis-booted bootstrap, 2 (3 attempts total)
       by default."
    }

    size_t --build-timeout = 5400
    {
      "<sec>",
      "Maximum number of seconds to wait for build completion, 5400 (90
       minutes) by default."
    }

    size_t --build-retries = 2
    {
      "<num>",
      "Number of times to retry a mis-booted build, 2 (3 attempts total) by
       default."
    }

    size_t --intactive-timeout = 10800
    {
      "<sec>",
      "Maximum number of seconds to wait for interactive build completion,
       10800 (3 hours) by default."
    }

    size_t --connect-timeout = 60
    {
      "<sec>",
      "Maximum number of seconds to wait for controller request connection,
       60 (1 minute) by default."
    }

    size_t --request-timeout = 300
    {
      "<sec>",
      "Maximum number of seconds to wait for controller request completion,
       300 (5 minutes) by default."
    }

    size_t --request-retries = 4
    {
      "<num>",
      "Number of times to retry a controller request, 4 (5 attempts total) by
       default. Note that both the total time for all retries as well as the
       time of each retry are limited by the same \c{--request-timeout}
       value. This means that a successful request may take up to twice as
       long if a connection was established at the end of the retry window
       and took just as long to complete."
    }

    path --openssl = "openssl"
    {
      "<path>",
      "The openssl program to be used for crypto operations. You can also
       specify additional options that should be passed to the openssl program
       with \cb{--openssl-option}. If the openssl program is not explicitly
       specified, then \cb{bbot-agent} will use \cb{openssl} by default."
    }

    strings --openssl-option
    {
      "<opt>",
      "Additional option to be passed to the openssl program (see
       \cb{--openssl} for details). Repeat this option to specify multiple
       openssl options."
    }

    // Testing options.
    //
    bool --dump-machines
    {
      "Dump the available machines to \cb{stdout}, (re)-bootstrapping any if
       necessary, and exit."
    }

    bool --dump-task
    {
      "Dump the received build task to \cb{stdout} and exit."
    }

    bool --dump-result
    {
      "Dump the obtained build result to \cb{stdout} and exit."
    }

    bool --fake-bootstrap
    {
      "Fake the machine bootstrap process by creating the expected bootstrapped
       machine manifest."
    }

    bool --fake-build
    {
      "Fake the package building process by creating the aborted build result."
    }

    path --fake-machine
    {
      "<file>",
      "Fake the machine enumeration process by reading the machine header
       manifest from <file> (or \cb{stdin} if <file> is '\cb{-}')."
    }

    path --fake-request
    {
      "<file>",
      "Fake the task request process by reading the task manifest from <file>
       (or \cb{stdin} if <file> is '\cb{-}')."
    }
  };

  "
  \h|EXIT STATUS|

  Non-zero exit status is returned in case of an error.
  "
}