serve target server: Provide client the log of failed target builds

When the serve endpoint has all the information to analyse a
target, any analysis or build errors should be made available to
the client. This way the user can receive a relevant error report.

1 files changed, 18 insertions, 5 deletions

diff --git a/src/buildtool/serve_api/serve_service/target.hpp b/src/buildtool/serve_api/serve_service/target.hpp
index df42a87b..09b8657b 100644
--- a/src/buildtool/serve_api/serve_service/target.hpp
+++ b/src/buildtool/serve_api/serve_service/target.hpp
@@ -37,17 +37,30 @@
 class TargetService final : public justbuild::just_serve::Target::Service {
   public:
     // Given a target-level caching key, returns the computed value. In doing
-    // so, it can build on the associated end-point passing the
+    // so, it can build on the associated endpoint passing the
     // RemoteExecutionProperties contained in the ServeTargetRequest.
+    // The execution backend description, the resulting target cache value,
+    // and all other artifacts referenced therein MUST be made available in
+    // the CAS of the associated remote execution endpoint.
     //
-    // If the status has a code different from `OK`, the response MUST not be
-    // used.
+    // A failure to analyse or build a known target (i.e., a target for which
+    // we have all the needed information available) should NOT be reported as
+    // an error. Instead, the failure log should be uploaded as a blob to the
+    // CAS of the associated remote execution endpoint and its digest provided
+    // to the client in the response field `log`. In this case, the field
+    // `target_value` MUST not be set.
+    //
+    // If the status has a code different from `OK` or `NOT_FOUND`, the
+    // response MUST not be used.
     //
     // Errors:
-    // * `FAILED_PRECONDITION`: Failed to find required information in the CAS
-    //   or the target cache key is malformed.
+    // * `NOT_FOUND`: Unknown target or missing needed local information.
+    //   This should only be used for non-fatal failures.
+    // * `FAILED_PRECONDITION`: Required entries missing in the remote
+    //   execution endpoint.
     // * `UNAVAILABLE`: Could not communicate with the remote execution
     //   endpoint.
+    // * `INVALID_ARGUMENT`: The client provided invalid arguments in request.
     // * `INTERNAL`: Internally, something is very broken.
     auto ServeTarget(
         ::grpc::ServerContext* /*context*/,