diff options
Diffstat (limited to 'mod/module.cli')
| -rw-r--r-- | mod/module.cli | 811 |
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; + }; + } +} |