From 3a2ddd883fe1b92c63794897b407280fa166be3b Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Fri, 27 Jul 2018 14:01:18 +0200
Subject: Document submission simulation

---
 brep/submit/submit.in |  4 ++--
 doc/manual.cli        | 13 +++++++++++++
 mod/options.cli       | 12 +-----------
 3 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/brep/submit/submit.in b/brep/submit/submit.in
index fcc6a3f..c4ef08b 100644
--- a/brep/submit/submit.in
+++ b/brep/submit/submit.in
@@ -116,8 +116,8 @@ function result_manifest () # <status> <message> [<reference>]
 }
 
 if [ -n "$simulate" -a "$simulate" != "success" ]; then
-  trace "invalid simulate manifest value '$simulate'"
-  result_manifest 400 "invalid simulate manifest value"
+  trace "unrecognized simulation outcome '$simulate'"
+  result_manifest 400 "unrecognized simulation outcome"
   exit 0
 fi
 
diff --git a/doc/manual.cli b/doc/manual.cli
index 1aa01b6..0a798bb 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -126,6 +126,18 @@ mentioned above are always reported with the submission result manifest. Other
 errors (for example, internal server errors) might be reported with
 unformatted text, including HTML.
 
+If the submission request contains the \c{simulate} parameter, then the
+submission service simulates the specified outcome of the submission process
+without actually performing any externally visible actions (e.g., publishing
+the package, notifying the submitter, etc). Note that the package submission
+email (\c{submit-email}) is not sent for simulated submissions.
+
+Pre-defined simulation outcome values are \c{internal-error-text},
+\c{internal-error-html}, \c{duplicate-archive}, and \c{success}. The
+simulation outcome is included into the submission request manifest and the
+handler program must at least handle \c{success} but may recognize additional
+outcomes.
+
 
 \h#submit-request-manifest|Submission Request Manifest|
 
@@ -137,6 +149,7 @@ corresponding to the custom request parameters.
 archive: <name>
 sha256sum: <sum>
 timestamp: <datetime>
+[simulate]: <outcome>
 [client-ip]: <string>
 [user-agent]: <string>
 \
diff --git a/mod/options.cli b/mod/options.cli
index f939b52..992ffc4 100644
--- a/mod/options.cli
+++ b/mod/options.cli
@@ -643,17 +643,7 @@ namespace brep
       //
       string sha256sum;
 
-      // Submission simulation. The presence of this parameter instructs the
-      // submission service to simulate various outcomes of the submission
-      // process without actually performing any externally visible actions
-      // (e.g., publishing the package, notifying the submitter, etc).
-      //
-      // Pre-defined simulation outcome values are 'internal-error-text',
-      // 'internal-error-html', 'duplicate-archive', and 'success'. The
-      // handler program may recognize additional outcomes.
-      //
-      // Note that the package submission email (see submit-email for details)
-      // is not sent for the simulated submissions.
+      // Submission simulation outcome.
       //
       string simulate;
     };
-- 
cgit v1.1