policy-client-query: spec, and for taint check (in dgit-repos-server)

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

1 files changed, 20 insertions, 0 deletions

diff --git a/infra/dgit-repos-server b/infra/dgit-repos-server
index fd199ca..66ef098 100755
--- a/infra/dgit-repos-server
+++ b/infra/dgit-repos-server
@@ -154,8 +154,10 @@ setup_sigwarn();
 #         VERSION SUITE TAGNAME DELIBERATELIES [...]
 #   POLICY-HOOK-SCRIPT ... push-confirm PACKAGE \
 #         VERSION SUITE TAGNAME DELIBERATELIES FRESH-REPO|'' [...]
+#   POLICY-HOOK-SCRIPT ... policy-client-query PACKAGE POL-CL-QUERY [...]
 #
 # DELIBERATELIES is like this: --deliberately-foo,--deliberately-bar,...
+# POL-CL-QUERY is in the syntax of a package name
 #
 # Exit status of policy hook is a bitmask.
 # Bit weight constants are defined in Dgit.pm.
@@ -200,6 +202,24 @@ setup_sigwarn();
 # package), it should use DGIT-LIVE-DIR/dgit (etc.), or if that is
 # ENOENT, use the installed version.
 #
+# POL-CL-QUERY is one of the following:
+#
+#    tainted-objects <empty>
+#        => [ { "gitobjtype": "commit", # as from git-cat-file -t
+#               "gitobjid": "sha",
+#               "time": time_t, # integer, time the taint was noted
+#               "comment": $string, # in server"s native language, UTF-8
+#               "overrides": [ "--deliberately-include-q-h", ... ],
+#           } }
+#
+# Arguments after POL-CL-QUERY cannot contain `;` or whitespace;
+# they are obtained by dgit-ssh-dispatch by naive whitespace-splitting
+# a string from SSH_ORIGINAL_COMMAND.
+# 
+# (Response value is JSON unless otherwise specified.)
+# If POL-CL-QUERY is not supported, the server will exit successfully
+# producing no output.
+#
 # Mirror hook scripts are invoked like this:
 #   MIRROR-HOOK-SCRIPT DISTRO-DIR ACTION...
 # and currently there is only one action invoked by dgit-repos-server: