1 files changed, 24 insertions, 11 deletions

diff --git a/src/buildtool/serve_api/remote/source_tree_client.hpp b/src/buildtool/serve_api/remote/source_tree_client.hpp
index 3ea1058b..24b2654a 100644
--- a/src/buildtool/serve_api/remote/source_tree_client.hpp
+++ b/src/buildtool/serve_api/remote/source_tree_client.hpp
@@ -17,6 +17,7 @@
 
 #include <memory>
 #include <string>
+#include <variant>
 
 #include "justbuild/just_serve/just_serve.grpc.pb.h"
 #include "src/buildtool/common/remote/port.hpp"
@@ -29,42 +30,54 @@ class SourceTreeClient {
   public:
     SourceTreeClient(std::string const& server, Port port) noexcept;
 
-    /// \brief Retrieve the Git tree of a given commit, if known by the remote.
+    // An error + data union type
+    using result_t = std::variant<bool, std::string>;
+
+    /// \brief Retrieve the Git tree of a given commit, if known by the
+    /// endpoint. It is a fatal error if the commit is known to the endpoint but
+    /// no tree is able to be returned.
     /// \param[in] commit_id Hash of the Git commit to look up.
     /// \param[in] subdir Relative path of the tree inside commit.
     /// \param[in] sync_tree Sync tree to the remote-execution endpoint.
-    /// \returns The hash of the tree if commit found, nullopt otherwise.
+    /// \returns An error + data union, where at index 0 we return a fatal flag,
+    /// with false meaning non-fatal failure (commit or subtree not found), and
+    /// at index 1 the tree identifier on success.
     [[nodiscard]] auto ServeCommitTree(std::string const& commit_id,
                                        std::string const& subdir,
-                                       bool sync_tree)
-        -> std::optional<std::string>;
+                                       bool sync_tree) -> result_t;
 
-    /// \brief Retrieve the Git tree of an archive content, if known by remote.
+    /// \brief Retrieve the Git tree of an archive content, if known by the
+    /// endpoint. It is a fatal error if the content blob is known to the
+    /// endpoint but no tree is able to be returned.
     /// \param[in] content Hash of the archive content to look up.
     /// \param[in] archive_type Type of archive ("archive"|"zip").
     /// \param[in] subdir Relative path of the tree inside archive.
     /// \param[in] resolve_symlinks Optional enum to state how symlinks in the
     /// archive should be handled if the tree has to be actually computed.
     /// \param[in] sync_tree Sync tree to the remote-execution endpoint.
-    /// \returns The hash of the tree if content blob found, nullopt otherwise.
+    /// \returns An error + data union, where at index 0 we return a fatal flag,
+    /// with false meaning non-fatal failure (content blob not found), and at
+    /// index 1 the tree identifier on success.
     [[nodiscard]] auto ServeArchiveTree(
         std::string const& content,
         std::string const& archive_type,
         std::string const& subdir,
         std::optional<PragmaSpecial> const& resolve_symlinks,
-        bool sync_tree) -> std::optional<std::string>;
+        bool sync_tree) -> result_t;
 
     /// \brief Retrieve the Git tree of a directory of distfiles, if all the
-    /// content blobs are known by serve remote.
+    /// content blobs are known by the endpoint. It is a fatal error if all
+    /// content blobs are known but no tree is able to be returned.
     /// \param[in] distfiles Mapping from distfile names to content blob ids.
     /// \param[in] sync_tree Sync tree and all ditfile blobs to the
     /// remote-execution endpoint.
-    /// \returns The hash of the resulting tree if all distfile blobs found,
-    /// nullopt otherwise.
+    /// \returns An error + data union, where at index 0 we return a fatal flag,
+    /// with false meaning non-fatal failure (at least one distfile blob
+    /// missing), and at index 1 the tree identifier on success.
     [[nodiscard]] auto ServeDistdirTree(
         std::shared_ptr<std::unordered_map<std::string, std::string>> const&
             distfiles,
-        bool sync_tree) -> std::optional<std::string>;
+        bool sync_tree) -> result_t;
 
     /// \brief Make a given content blob available in remote CAS, if known by
     /// serve remote.