aboutsummaryrefslogtreecommitdiff
path: root/mod/module.cli
diff options
context:
space:
mode:
authorKaren Arutyunov <karen@codesynthesis.com>2020-03-18 22:17:49 +0300
committerKaren Arutyunov <karen@codesynthesis.com>2020-03-27 17:28:44 +0300
commit35359f038f571dc46de3d14af72a2bc911fb0a24 (patch)
treede3e89d678e78b9efc4d395274fd7ccc68f4a213 /mod/module.cli
parent8ad672cc7211952716ffe1fbf76c179b4f1149e3 (diff)
Implement brep-monitor
Diffstat (limited to 'mod/module.cli')
-rw-r--r--mod/module.cli811
1 files changed, 811 insertions, 0 deletions
diff --git a/mod/module.cli b/mod/module.cli
new file mode 100644
index 0000000..fa1d2cc
--- /dev/null
+++ b/mod/module.cli
@@ -0,0 +1,811 @@
+// file : mod/options.cli -*- C++ -*-
+// license : MIT; see accompanying LICENSE file
+
+include <libbpkg/manifest.hxx>; // repository_location
+
+include <web/xhtml/fragment.hxx>;
+
+include <libbrep/types.hxx>;
+
+include <mod/options-types.hxx>;
+
+namespace brep
+{
+ // Web handler configuration options.
+ //
+ namespace options
+ {
+ // Option groups.
+ //
+ class handler
+ {
+ string email
+ {
+ "<email>",
+ "Repository email. This email is used for the \cb{From:} header in
+ emails send by \cb{brep} (for example, build failure notifications)."
+ }
+
+ string host
+ {
+ "<host>",
+ "Repository host. It specifies the scheme and the host address (but
+ not the root path; see \cb{root} below) that will be used whenever
+ \cb{brep} needs to construct an absolute URL to one of its locations
+ (for example, a link to a build log that is being send via email)."
+ }
+
+ dir_path root = "/"
+ {
+ "<path>",
+ "Repository root. That is, this is the part of the URL between the
+ host name and the start of the repository. For example, root value
+ '\cb{/pkg}' means the repository URL is \cb{http://example.org/pkg/}.
+ Specify '\cb{/}' to use the web server root
+ (\cb{http://example.org/})."
+ }
+
+ string tenant-name = "tenant"
+ {
+ "<name>",
+ "Name to call the tenant values on web pages. If not specified, then
+ \cb{tenant} is used."
+ }
+
+ uint16_t verbosity = 0
+ {
+ "<level>",
+ "Trace verbosity level. Level 0 disables tracing, which is also the
+ default."
+ }
+ };
+
+ class openssl_options
+ {
+ 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{brep} 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."
+ }
+
+ strings openssl-envvar
+ {
+ "<name>[=value]",
+ "Environment variable to be set (<name>=<value>) or unset (just
+ <name>) for the openssl program (see \cb{openssl} for details).
+ Repeat this option to specify multiple openssl variables. Note
+ that unspecified variables are inherited from the web server
+ process.
+
+ You need to at least set the \cb{RANDFILE} environment variable
+ to change the default location of the openssl program seed file
+ and maybe also the \cb{OPENSSL_CONF} variable if you would like
+ to use a custom openssl configuration file."
+ }
+ };
+
+ class package_db
+ {
+ string package-db-user
+ {
+ "<user>",
+ "Package database login user name. If not specified, then operating
+ system (login) name is used. See also \c{package-db-role}."
+ }
+
+ string package-db-role = "brep"
+ {
+ "<user>",
+ "Package database execution user name. If not empty then the login
+ user will be switched (with \c{SET ROLE}) to this user prior to
+ executing any statements. If not specified, then \cb{brep} is used."
+ }
+
+ string package-db-password
+ {
+ "<pass>",
+ "Package database password. If not specified, then login without
+ password is expected to work."
+ }
+
+ string package-db-name = "brep_package"
+ {
+ "<name>",
+ "Package database name. If not specified, then \cb{brep_package} is
+ used by default."
+ }
+
+ string package-db-host
+ {
+ "<host>",
+ "Package database host name, address, or socket. If not specified, then
+ connect to \cb{localhost} using the operating system-default
+ mechanism (Unix-domain socket, etc)."
+ }
+
+ uint16_t package-db-port = 0
+ {
+ "<port>",
+ "Package database port number. If not specified, the default port is
+ used."
+ }
+
+ size_t package-db-max-connections = 5
+ {
+ "<num>",
+ "The maximum number of concurrent package database connections per web
+ server process. If 0, then no limitation is applied. The default is
+ 5."
+ }
+
+ size_t package-db-retry = 10
+ {
+ "<num>",
+ "The maximum number of times to retry package database transactions in
+ the face of recoverable failures (deadlock, loss of connection, etc).
+ The default is 10."
+ }
+ };
+
+ class build: openssl_options
+ {
+ path build-config
+ {
+ "<buildtab>",
+ "Build configuration file. If not specified, then the package building
+ functionality will be disabled. If specified, then the build database
+ must be configured (see \cb{build-db-*}). The \cb{brep} instance
+ needs to be restarted after modifying <buildtab> for the changes to
+ take effect."
+ }
+
+ dir_path build-bot-agent-keys
+ {
+ "<dir>",
+ "Directory containing build bot agent public keys. If specified, then
+ \cb{brep} will perform agent authentication and will reject build
+ results from unauthenticated ones. If not specified, then build
+ results are accepted from all agents (which will be a security
+ risk if the \cb{brep} instance is publicly accessible).
+
+ The directory is expected to contain one PEM-encoded public key
+ per file with the \cb{.pem} extension. All other files and
+ subdirectories are ignored. The \cb{brep} instance needs to be
+ restarted after adding new key files for the changes to take effect."
+ }
+
+ size_t build-forced-rebuild-timeout = 600
+ {
+ "<seconds>",
+ "Time to wait before considering a package for a forced rebuild. Must
+ be specified in seconds. Default is 10 minutes."
+ }
+
+ size_t build-normal-rebuild-timeout = 86400
+ {
+ "<seconds>",
+ "Time to wait before considering a package for a normal rebuild. Must
+ be specified in seconds. Default is 24 hours."
+ }
+ };
+
+ class build_db
+ {
+ string build-db-user
+ {
+ "<user>",
+ "Build database login user name. If not specified, then operating
+ system (login) name is used. See also \c{build-db-role}."
+ }
+
+ string build-db-role = "brep"
+ {
+ "<user>",
+ "Build database execution user name. If not empty then the login
+ user will be switched (with \c{SET ROLE}) to this user prior to
+ executing any statements. If not specified, then \cb{brep} is used."
+ }
+
+ string build-db-password
+ {
+ "<pass>",
+ "Build database password. If not specified, then login without
+ password is expected to work."
+ }
+
+ string build-db-name = "brep_build"
+ {
+ "<name>",
+ "Build database name. If not specified, then \cb{brep_build} is used
+ by default."
+ }
+
+ string build-db-host
+ {
+ "<host>",
+ "Build database host name, address, or socket. If not specified, then
+ connect to \cb{localhost} using the operating system-default
+ mechanism (Unix-domain socket, etc)."
+ }
+
+ uint16_t build-db-port = 0
+ {
+ "<port>",
+ "Build database port number. If not specified, the default port is
+ used."
+ }
+
+ size_t build-db-max-connections = 5
+ {
+ "<num>",
+ "The maximum number of concurrent build database connections per web
+ server process. If 0, then no limitation is applied. The default is
+ 5."
+ }
+
+ size_t build-db-retry = 10
+ {
+ "<num>",
+ "The maximum number of times to retry build database transactions in
+ the face of recoverable failures (deadlock, loss of connection, etc).
+ The default is 10."
+ }
+ };
+
+ class page
+ {
+ web::xhtml::fragment logo
+ {
+ "<xhtml>",
+ "Web page logo. It is displayed in the page header aligned to the left
+ edge. The value is treated as an XHTML5 fragment."
+ }
+
+ vector<page_menu> menu;
+ {
+ "<label=link>",
+ "Web page menu. Each entry is displayed in the page header in the
+ order specified and aligned to the right edge. A link target that
+ starts with '\cb{/}' or contains '\cb{:}' is used as is. Otherwise,
+ it is prefixed with the repository web interface root."
+ }
+ };
+
+ class search
+ {
+ uint16_t search-page-entries = 20
+ {
+ "<num>",
+ "Number of packages per page. The default is 20."
+ }
+
+ uint16_t search-pages = 5
+ {
+ "<num>",
+ "Number of pages in navigation (pager). The default is 5."
+ }
+ };
+
+ class package
+ {
+ uint16_t package-description = 500
+ {
+ "<len>",
+ "Number of package description characters to display in brief pages.
+ The default is 500 (~ 80 characters * 6 lines)."
+ }
+
+ uint16_t package-changes = 5000;
+ {
+ "<len>",
+ "Number of package changes characters to display in brief pages. The
+ default is 5000 (~ 80 chars x 60 lines)."
+ }
+ };
+
+ // Handler options.
+ //
+
+ class packages: search, package_db, page, handler
+ {
+ string search-title = "Packages"
+ {
+ "<text>",
+ "Package search page title. It is placed inside XHTML5 <title>
+ element."
+ }
+ };
+
+ class package_details: package, search, package_db, page, handler
+ {
+ };
+
+ class package_version_details: package, package_db,
+ build, build_db,
+ page,
+ handler
+ {
+ };
+
+ class repository_details: package_db, page, handler
+ {
+ };
+
+ class build_task: build, build_db, handler
+ {
+ size_t build-task-request-max-size = 102400
+ {
+ "<bytes>",
+ "The maximum size of the build task request manifest accepted. Note
+ that the HTTP POST request body is cached to retry database
+ transactions in the face of recoverable failures (deadlock, loss of
+ connection, etc). The default is 100K."
+ }
+
+ size_t build-result-timeout = 10800
+ {
+ "<seconds>",
+ "Time to wait before considering the expected task result lost. Must be
+ specified in seconds. The default is 3 hours."
+ }
+ };
+
+ class build_result: build, package_db, build_db, handler
+ {
+ size_t build-result-request-max-size = 10240000
+ {
+ "<bytes>",
+ "The maximum size of the build result manifest accepted. Note that the
+ HTTP POST request body is cached to retry database transactions in the
+ face of recoverable failures (deadlock, loss of connection, etc). The
+ default is 10M."
+ }
+ };
+
+ class build_log: build, build_db, handler
+ {
+ };
+
+ class build_force: build, build_db, handler
+ {
+ };
+
+ class builds: build, build_db, page, handler
+ {
+ uint16_t build-page-entries = 20
+ {
+ "<num>",
+ "Number of builds per page. The default is 20."
+ }
+
+ uint16_t build-pages = 5
+ {
+ "<num>",
+ "Number of pages in navigation (pager). The default is 5."
+ }
+ };
+
+ class build_configs: build, page, handler
+ {
+ uint16_t build-config-page-entries = 20
+ {
+ "<num>",
+ "Number of build configurations per page. The default is 20."
+ }
+
+ uint16_t build-config-pages = 5
+ {
+ "<num>",
+ "Number of pages in navigation (pager). The default is 5."
+ }
+ };
+
+ class submit: page, handler
+ {
+ dir_path submit-data
+ {
+ "<dir>",
+ "The directory to save final submission data to. If unspecified, the
+ package submission functionality will be disabled. If specified,
+ then \cb{submit-temp} must be specified as well. See \l{brep The
+ \cb{build2} Repository Interface Manual} for more information on
+ package submission.
+
+ Note that the directory path must be absolute and the directory
+ itself must exist and have read, write, and execute permissions
+ granted to the user that runs the web server."
+ }
+
+ dir_path submit-temp
+ {
+ "<dir>",
+ "The directory to save temporary submission data to. Must be specified
+ if the package submission functionality is enabled.
+
+ Note that this directory must be on the same filesystem and satisfy
+ the same requirements as \cb{submit-data}. It is also the user's
+ responsibility to clean it up after an unclean web server shutdown."
+ }
+
+ size_t submit-max-size = 10485760
+ {
+ "<bytes>",
+ "The maximum size of the submission data accepted. Note that currently
+ the entire submission request is read into memory. The default is
+ 10M."
+ }
+
+ path submit-form
+ {
+ "<file>",
+ "The package submission form fragment. If specified, then its contents
+ are treated as an XHTML5 fragment that is inserted into the <body>
+ element of the submission page. If unspecified, then no submission
+ page will be displayed. Note that the file path must be absolute."
+ }
+
+ string submit-email
+ {
+ "<email>",
+ "The package submission email. If specified, the submission request
+ and result manifests will be sent to this address. See \l{brep The
+ \cb{build2} Repository Interface Manual} for more information."
+ }
+
+ path submit-handler
+ {
+ "<path>",
+ "The handler program to be executed on package submission. The handler
+ is executed as part of the HTTP request and is passed additional
+ arguments that can be specified with \cb{submit-handler-argument}
+ followed by the absolute path to the submission directory. See
+ \l{brep The \cb{build2} Repository Interface Manual} for more
+ information. Note that the program path must be absolute."
+ }
+
+ strings submit-handler-argument
+ {
+ "<arg>",
+ "Additional arguments to be passed to the submission handler program
+ (see \cb{submit-handler} for details). Repeat this option to specify
+ multiple arguments."
+ }
+
+ size_t submit-handler-timeout
+ {
+ "<seconds>",
+ "The submission handler program timeout in seconds. If specified and
+ the handler does not exit in the allotted time, then it is killed and
+ its termination is treated as abnormal."
+ }
+ };
+
+ class ci: page, handler
+ {
+ dir_path ci-data
+ {
+ "<dir>",
+ "The directory to save CI request data to. If unspecified, the
+ package CI functionality will be disabled. See \l{brep The
+ \cb{build2} Repository Interface Manual} for more information on
+ package CI.
+
+ Note that the directory path must be absolute and the directory
+ itself must exist and have read, write, and execute permissions
+ granted to the user that runs the web server."
+ }
+
+ path ci-form
+ {
+ "<file>",
+ "The package CI form fragment. If specified, then its contents are
+ treated as an XHTML5 fragment that is inserted into the <body>
+ element of the CI page. If unspecified, then no CI page will be
+ displayed. Note that the file path must be absolute."
+ }
+
+ string ci-email
+ {
+ "<email>",
+ "The package CI email. If specified, the CI request and result
+ manifests will be sent to this address. See \l{brep The \cb{build2}
+ Repository Interface Manual} for more information."
+ }
+
+ path ci-handler
+ {
+ "<path>",
+ "The handler program to be executed on CI request. The handler is
+ executed as part of the HTTP request and is passed additional
+ arguments that can be specified with \cb{ci-handler-argument}
+ followed by the absolute path to the CI request directory. See
+ \l{brep The \cb{build2} Repository Interface Manual} for more
+ information. Note that the program path must be absolute."
+ }
+
+ strings ci-handler-argument
+ {
+ "<arg>",
+ "Additional arguments to be passed to the CI handler program (see
+ \cb{ci-handler} for details). Repeat this option to specify multiple
+ arguments."
+ }
+
+ size_t ci-handler-timeout
+ {
+ "<seconds>",
+ "The CI handler program timeout in seconds. If specified and the
+ handler does not exit in the allotted time, then it is killed and
+ its termination is treated as abnormal."
+ }
+ };
+
+ class repository_root: handler
+ {
+ string root-global-view = "packages"
+ {
+ "<service>",
+ "The default view to display for the global repository root. The
+ <service> argument is one of the supported services (\c{packages},
+ \c{builds}, \c{submit}, \c{ci}, etc). The default service is
+ packages."
+ }
+
+ string root-tenant-view = "packages"
+ {
+ "<service>",
+ "The default view to display for the tenant repository root. The
+ <service> argument is one of the supported services (\c{packages},
+ \c{builds}, \c{submit}, \c{ci}, etc). The default service is
+ packages."
+ }
+ };
+ }
+
+ // Web handler HTTP request parameters.
+ //
+ namespace params
+ {
+ // Use parameters long names in the C++ code, short aliases (if present)
+ // in HTTP URL.
+ //
+ class packages
+ {
+ // Display package search result list starting from this page.
+ //
+ uint16_t page | p;
+
+ // Package search criteria.
+ //
+ // Note that the packages parameter is renamed to '_' by the root
+ // handler (see the request_proxy class for details).
+ //
+ string q | _;
+ };
+
+ class package_details
+ {
+ // Display package version search result list starting from this page.
+ //
+ uint16_t page | p;
+
+ // Package version search criteria.
+ //
+ string query | q;
+
+ // Page form.
+ //
+ page_form form | f = page_form::brief;
+ };
+
+ class package_version_details
+ {
+ // Page form.
+ //
+ page_form form | f = page_form::brief;
+ };
+
+ class repository_details
+ {
+ // No parameters so far.
+ //
+ };
+
+ class build_task
+ {
+ // Package repository canonical name (note: including pkg: type).
+ //
+ vector<string> repository | r;
+ };
+
+ class build_result
+ {
+ // No parameters so far.
+ //
+ };
+
+ class build_log
+ {
+ // No parameters so far.
+ //
+ };
+
+ // All parameters are non-optional.
+ //
+ class build_force
+ {
+ // Package name.
+ //
+ string package | pn;
+
+ // Package version. May not be url-encoded, in which case the plus
+ // character is considered literally (rather than as the encoded space
+ // character). In other words, after url-decoding the space character is
+ // treated the same way as the plus character.
+ //
+ // @@ Make it of the version type? Maybe after it get moved to
+ // libbpkg/types.hxx or at least the second use case appear.
+ //
+ string version | pv;
+
+ // Package build configuration.
+ //
+ string configuration | cf;
+
+ // Toolchain name.
+ //
+ string toolchain_name | tn;
+
+ // Toolchain version. May not be url-encoded (see above).
+ //
+ string toolchain_version | tv;
+
+ // Package rebuild reason. Must not be empty.
+ //
+ string reason;
+ };
+
+ class builds
+ {
+ // Display packages build configurations list starting from this page.
+ //
+ uint16_t page | p;
+
+ // Package builds query filter options.
+ //
+
+ // Package name wildcard. An empty value is treated the same way as *.
+ //
+ // We used to generate URLs like:
+ //
+ // https://cppget.org/?builds&pn=bbot
+ //
+ // This looked a bit verbose, so now we produce URLs like:
+ //
+ // https://cppget.org/?builds=bbot
+ //
+ // To support the already distributed URLs the name_legacy (pn) parameter
+ // overrides the name (builds) parameter, if present. Note that the
+ // builds parameter is renamed to '_' by the root handler (see the
+ // request_proxy class for details).
+ //
+ string name | _;
+ string name_legacy | pn;
+
+ // Package version. If empty or *, then no version constraint is applied.
+ // Otherwise the build package version must match the value exactly.
+ //
+ string version | pv;
+
+ // Package build toolchain in the <name>-<version> form. If *, then no
+ // toolchain constraint is applied. Otherwise the build toolchain name
+ // and version must match the value exactly.
+ //
+ string toolchain | tc = "*";
+
+ // Package build configuration name wildcard. An empty value is treated
+ // the same way as *.
+ //
+ string configuration | cf;
+
+ // Package build machine name wildcard. An empty value is treated the
+ // same way as *.
+ //
+ string machine | mn;
+
+ // Package build target wildcard. An empty value is treated the same way
+ // as *.
+ //
+ string target | tg;
+
+ // Package build result. If *, then no build result constraint is
+ // applied. Otherwise the value is supposed to be the one of the
+ // following (ordered) statuses: pending, building, success, warning,
+ // error, abort, abnormal. The first 3 statuses are checked for equality,
+ // the rest - for being greater or equal.
+ //
+ string result | rs = "*";
+ };
+
+ class build_configs
+ {
+ // Note that the build-configs parameter is renamed to '_' by the root
+ // handler (see the request_proxy class for details).
+ //
+ string class_name | _ = "all";
+
+ // Display build configurations list starting from this page.
+ //
+ uint16_t page | p;
+ };
+
+ // Parameters, except simulate, must either be all present (actual
+ // submission) or absent (submission form request).
+ //
+ // Note also that besides these parameters there can be others. We don't
+ // recognize their semantics and just save them to the submission request
+ // manifest.
+ //
+ class submit
+ {
+ // Package archive file name. Must be <input type="file"/>.
+ //
+ // Note that it can potentially be not just a name but a file path and
+ // in the client's form (e.g., Windows).
+ //
+ string archive;
+
+ // Package archive file SHA256 checksum.
+ //
+ string sha256sum;
+
+ // Submission simulation outcome.
+ //
+ string simulate;
+ };
+
+ // Parameters, except simulate, must either be all present (actual CI
+ // request) or absent (CI form request).
+ //
+ // Note also that besides these parameters there can be others. We don't
+ // recognize their semantics and just save them to the CI request
+ // manifest.
+ //
+ class ci
+ {
+ // Package repository location.
+ //
+ // Note that the ci parameter is renamed to '_' by the root handler (see
+ // the request_proxy class for details).
+ //
+ bpkg::repository_location repository | _;
+
+ // Package names/versions.
+ //
+ strings package;
+
+ // Overrides file name. Must be <input type="file"/>.
+ //
+ // Note that we don't really need this name and only check if this
+ // parameter is specified to detect presence of the upload.
+ //
+ string overrides;
+
+ // Submission simulation outcome.
+ //
+ string simulate;
+ };
+ }
+}