Add support for build artifacts upload in agent

2 files changed, 28 insertions, 10 deletions

diff --git a/doc/cli.sh b/doc/cli.sh
index 22fe0c2..404e4d6 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -96,6 +96,7 @@ function compile_doc () # <file> <prefix> <suffix>
 --html-epilogue-file doc-epilogue.xhtml \
 --link-regex '%bpkg([-.].+)%../../bpkg/doc/bpkg$1%' \
 --link-regex '%bpkg(#.+)?%../../bpkg/doc/build2-package-manager-manual.xhtml$1%' \
+--link-regex '%brep(#.+)?%../../brep/doc/build2-repository-interface-manual.xhtml$1%' \
 --output-prefix "$2" \
 --output-suffix "$3" \
 "$1"
diff --git a/doc/manual.cli b/doc/manual.cli
index eb48a31..e61e6ef 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -45,8 +45,8 @@ Let's now examine the workflow in the other direction, that is, from a worker
 to a controller. Once a build machine is booted (by the agent), the worker
 inside connects to the TFTP server running on the build host and downloads the
 \i{build task manifest}. It then proceeds to perform the build task and
-uploads the \i{build result manifest} (which includes build logs) to the TFTP
-server.
+uploads the \i{build artifacts archive}, if any, followed by the \i{build
+result manifest} (which includes build logs) to the TFTP server.
 
 Once an agent receives a build task for a specific build machine, it goes
 through the following steps. First, it creates a directory on its TFTP server
@@ -79,14 +79,18 @@ agents. In this case we say that the \i{controller act as an agent}. The
 controller may also be configured to monitor build sources, such as SCM
 repositories, directly in which case it generates build tasks itself.
 
-In this architecture the build results are propagated up the chain: from a
-worker, to its agent, to its controller, and so on. A controller that is the
-final destination of a build result uses email to notify interested parties of
-the outcome. For example, \c{brep} would send a notification to the package
-owner if the build failed. Similarly, a \c{bbot} controller that monitors a
-\cb{git} repository would send an email to a committer if their commit caused a
-build failure. The email would include a link (normally HTTP/HTTPS) to the
-build logs hosted by the controller.
+In this architecture the build results and optional build artifacts are
+propagated up the chain: from a worker, to its agent, to its controller, and
+so on. A controller that is the final destination of a build result uses email
+to notify interested parties of the outcome. For example, \c{brep} would send
+a notification to the package owner if the build failed. Similarly, a \c{bbot}
+controller that monitors a \cb{git} repository would send an email to a
+committer if their commit caused a build failure. The email would include a
+link (normally HTTP/HTTPS) to the build logs hosted by the controller. The
+build artifacts, such as generated binary distribution packages, are normally
+made available for the interested parties to download. See \l{brep#upload
+Build Artifacts Upload} for details on the \c{brep} controller's
+implementation of the build artifacts upload handling.
 
 \h#arch-machine-config|Configurations|
 
@@ -851,6 +855,7 @@ subsequent sections.
 session: <id>
 [challenge]: <text>
 [result-url]: <url>
+[*-upload-url]: <url>
 [agent-checksum]: <checksum>
 \
 
@@ -889,6 +894,18 @@ private key and then \c{base64}-encoding the result.
 The URL to POST (upload) the result request to.
 
 
+\h2#arch-task-res-upload-url|\c{*-upload-url}|
+
+\
+[*-upload-url]: <url>
+\
+
+The URLs to upload the build artifacts to, if any, via the HTTP \c{POST}
+method using the \c{multipart/form-data} content type (see \l{brep#upload
+Build Artifacts Upload} for details on the upload protocol). The substring
+matched by \c{*} in \c{*-upload-url} denotes the upload type.
+
+
 \h2#arch-task-res-agent-checksum|\c{agent-checksum}|
 
 \