Add hashOnRef query param to support time travel on a named ref

clients/client/src/main/java/org/projectnessie/client/ClientContentsApi.java

@@ -33,24 +33,27 @@ public ClientContentsApi(HttpClient client) {
   }
 
   @Override
-  public Contents getContents(@NotNull ContentsKey key, String ref) throws NessieNotFoundException {
+  public Contents getContents(@NotNull ContentsKey key, String ref, String hashOnRef)
+      throws NessieNotFoundException {
     return client
         .newRequest()
         .path("contents")
         .path(key.toPathString())
         .queryParam("ref", ref)
+        .queryParam("hashOnRef", hashOnRef)
         .get()
         .readEntity(Contents.class);
   }
 
   @Override
   public MultiGetContentsResponse getMultipleContents(
-      @NotNull String ref, @NotNull MultiGetContentsRequest request)
+      @NotNull String ref, String hashOnRef, @NotNull MultiGetContentsRequest request)
       throws NessieNotFoundException {
     return client
         .newRequest()
         .path("contents")
         .queryParam("ref", ref)
+        .queryParam("hashOnRef", hashOnRef)
         .post(request)
         .readEntity(MultiGetContentsResponse.class);
   }

clients/client/src/main/java/org/projectnessie/client/ClientTreeApi.java

@@ -117,14 +117,15 @@ public Branch getDefaultBranch() {
 
   @Override
   public LogResponse getCommitLog(
-      String ref, Integer maxRecords, String pageToken, String queryExpression)
+      String ref, String hashOnRef, Integer maxRecords, String pageToken, String queryExpression)
       throws NessieNotFoundException {
     HttpRequest builder =
         client.newRequest().path("trees/tree/{ref}/log").resolveTemplate("ref", ref);
     return builder
         .queryParam("max", maxRecords != null ? maxRecords.toString() : null)
         .queryParam("pageToken", pageToken)
         .queryParam("query_expression", queryExpression)
+        .queryParam("hashOnRef", hashOnRef)
         .get()
         .readEntity(LogResponse.class);
   }
@@ -159,14 +160,19 @@ public void mergeRefIntoBranch(
 
   @Override
   public EntriesResponse getEntries(
-      @NotNull String refName, Integer maxRecords, String pageToken, String queryExpression)
+      @NotNull String refName,
+      String hashOnRef,
+      Integer maxRecords,
+      String pageToken,
+      String queryExpression)
       throws NessieNotFoundException {
     HttpRequest builder =
         client.newRequest().path("trees/tree/{ref}/entries").resolveTemplate("ref", refName);
     return builder
         .queryParam("max", maxRecords != null ? maxRecords.toString() : null)
         .queryParam("pageToken", pageToken)
         .queryParam("query_expression", queryExpression)
+        .queryParam("hashOnRef", hashOnRef)
         .get()
         .readEntity(EntriesResponse.class);
   }

clients/client/src/main/java/org/projectnessie/client/StreamingUtil.java

@@ -34,51 +34,57 @@ private StreamingUtil() {
 
   /**
    * Default implementation to return a stream of objects for a ref, functionally equivalent to
-   * calling {@link TreeApi#getEntries(String, Integer, String, String)} with manual paging.
+   * calling {@link TreeApi#getEntries(String, String, Integer, String, String)} with manual paging.
    *
    * <p>The {@link Stream} returned by {@code getEntriesStream(ref, OptionalInt.empty())}, if not
    * limited, returns all commit-log entries.
    *
-   * @param ref a named reference (branch or tag name) or a commit-hash
+   * @param ref a named reference (branch or tag name)
+   * @param hashOnRef the hash on the given ref
    * @param pageSizeHint page-size hint for the backend
    * @param queryExpression The query expression to filter by
    * @return stream of {@link Entry} objects
    */
   public static Stream<Entry> getEntriesStream(
       @NotNull TreeApi treeApi,
       @NotNull String ref,
+      String hashOnRef,
       OptionalInt pageSizeHint,
       String queryExpression)
       throws NessieNotFoundException {
     return new ResultStreamPaginator<>(
             EntriesResponse::getEntries,
-            (ref1, pageSize, token) -> treeApi.getEntries(ref1, pageSize, token, queryExpression))
+            (ref1, pageSize, token) ->
+                treeApi.getEntries(ref1, hashOnRef, pageSize, token, queryExpression))
         .generateStream(ref, pageSizeHint);
   }
 
   /**
    * Default implementation to return a stream of commit-log entries, functionally equivalent to
-   * calling {@link TreeApi#getCommitLog(String, Integer, String, String)} with manual paging.
+   * calling {@link TreeApi#getCommitLog(String, String, Integer, String, String)} with manual
+   * paging.
    *
    * <p>The {@link Stream} returned by {@code getCommitLogStream(ref, OptionalInt.empty())}, if not
    * limited, returns all commit-log entries.
    *
    * @param treeApi The {@link TreeApi} to use
-   * @param ref a named reference (branch or tag name) or a commit-hash
+   * @param ref a named reference (branch or tag name)
+   * @param hashOnRef the hash on the given ref
    * @param pageSizeHint page-size hint for the backend
    * @param queryExpression The query expression to filter by
    * @return stream of {@link CommitMeta} objects
    */
   public static Stream<CommitMeta> getCommitLogStream(
       @NotNull TreeApi treeApi,
       @NotNull String ref,
+      String hashOnRef,
       OptionalInt pageSizeHint,
       String queryExpression)
       throws NessieNotFoundException {
     return new ResultStreamPaginator<>(
             LogResponse::getOperations,
             (reference, pageSize, token) ->
-                treeApi.getCommitLog(reference, pageSize, token, queryExpression))
+                treeApi.getCommitLog(reference, hashOnRef, pageSize, token, queryExpression))
         .generateStream(ref, pageSizeHint);
   }
 }

clients/deltalake/core/src/main/scala/org/projectnessie/deltalake/NessieLogStore.scala

@@ -484,7 +484,7 @@ class NessieLogStore(sparkConf: SparkConf, hadoopConf: Configuration)
   }
 
   private def getTable(path: Path, branch: String): Option[DeltaLakeTable] = {
-    Try(client.getContentsApi.getContents(pathToKey(path), branch))
+    Try(client.getContentsApi.getContents(pathToKey(path), branch, null))
       .filter(x => x != null && x.isInstanceOf[DeltaLakeTable])
       .map(_.asInstanceOf[DeltaLakeTable])
       .toOption

clients/deltalake/core/src/test/java/org/projectnessie/deltalake/ITDeltaLogBranches.java

@@ -133,7 +133,7 @@ void testCheckpoint() throws NessieNotFoundException {
 
     String tableName = tempPath.getAbsolutePath() + "/_delta_log";
     Contents contents =
-        client.getContentsApi().getContents(ContentsKey.of(tableName.split("/")), "main");
+        client.getContentsApi().getContents(ContentsKey.of(tableName.split("/")), "main", null);
     Optional<DeltaLakeTable> table = contents.unwrap(DeltaLakeTable.class);
     Assertions.assertTrue(table.isPresent());
     Assertions.assertEquals(1, table.get().getCheckpointLocationHistory().size());

clients/hmsbridge/core/src/main/java/org/projectnessie/hms/TransactionStore.java

@@ -74,7 +74,7 @@ Optional<Item> getItemForRef(String ref, ContentsKey contentsKey) throws NoSuchO
     }
 
     try {
-      Item item = Item.fromContents(contents.getContents(contentsKey, ref));
+      Item item = Item.fromContents(contents.getContents(contentsKey, ref, null));
       cachedItems.put(key, item);
       return Optional.ofNullable(item);
     } catch (NessieNotFoundException e) {
@@ -105,7 +105,9 @@ List<Optional<Item>> getItemsForRef(List<RefKey> refKeys) throws NessieNotFoundE
           keysByRef.get(ref).stream().map(RefKey::getKey).collect(Collectors.toList());
       MultiGetContentsResponse response =
           contents.getMultipleContents(
-              ref, ImmutableMultiGetContentsRequest.builder().addAllRequestedKeys(keys).build());
+              ref,
+              null,
+              ImmutableMultiGetContentsRequest.builder().addAllRequestedKeys(keys).build());
       response
           .getContents()
           .forEach(
@@ -123,7 +125,7 @@ public List<Reference> getReferences() {
   }
 
   public Stream<Entry> getEntriesForDefaultRef() throws NessieNotFoundException {
-    List<Entry> entries = tree.getEntries(reference.getName(), null, null, null).getEntries();
+    List<Entry> entries = tree.getEntries(reference.getName(), null, null, null, null).getEntries();
     Supplier<Stream<RefKey>> defaultRefKeys =
         () -> cachedItems.keySet().stream().filter(k -> k.getRef().equals(reference.getName()));
     Set<ContentsKey> toRemove =

clients/hmsbridge/core/src/test/java/org/projectnessie/hms/BaseDelegateOps.java

@@ -52,14 +52,16 @@ public void crossNessieDelegateQuery() throws NessieNotFoundException {
     assertEquals(4, results.size());
 
     // make sure we created the database and single table object in the nessie db.
-    Contents db = client.getContentsApi().getContents(ContentsKey.of("mytestdb"), null);
+    Contents db = client.getContentsApi().getContents(ContentsKey.of("mytestdb"), null, null);
     assertNotNull(db);
     assertTrue(HiveDatabase.class.isAssignableFrom(db.getClass()));
-    Contents tbl = client.getContentsApi().getContents(ContentsKey.of("mytestdb", "nessie"), null);
+    Contents tbl =
+        client.getContentsApi().getContents(ContentsKey.of("mytestdb", "nessie"), null, null);
     assertNotNull(tbl);
     assertTrue(HiveTable.class.isAssignableFrom(tbl.getClass()));
 
     // ensure only one table was created in Nessie.
-    assertEquals(2, client.getTreeApi().getEntries("main", null, null, null).getEntries().size());
+    assertEquals(
+        2, client.getTreeApi().getEntries("main", null, null, null, null).getEntries().size());
   }
 }

clients/spark-extensions/src/main/scala/org/apache/spark/sql/execution/datasources/v2/NessieUtils.scala

@@ -50,6 +50,7 @@ object NessieUtils {
           .getCommitLogStream(
             nessieClient.getTreeApi,
             branch,
+            null,
             OptionalInt.empty(),
             String
               .format(

clients/spark-extensions/src/main/scala/org/apache/spark/sql/execution/datasources/v2/ShowLogExec.scala

@@ -43,6 +43,7 @@ case class ShowLogExec(
     val stream = StreamingUtil.getCommitLogStream(
       nessieClient.getTreeApi,
       refName,
+      null,
       OptionalInt.empty(),
       null
     )

model/src/main/java/org/projectnessie/api/ContentsApi.java

@@ -15,6 +15,7 @@
  */
 package org.projectnessie.api;
 
+import javax.annotation.Nullable;
 import javax.validation.Valid;
 import javax.validation.constraints.NotNull;
 import javax.validation.constraints.Pattern;
@@ -69,14 +70,19 @@ Contents getContents(
               examples = {@ExampleObject(ref = "ContentsKey")})
           @PathParam("key")
           ContentsKey key,
-      @Pattern(
-              regexp = Validation.REF_NAME_OR_HASH_REGEX,
-              message = Validation.REF_NAME_OR_HASH_MESSAGE)
+      @Pattern(regexp = Validation.REF_NAME_REGEX, message = Validation.REF_NAME_MESSAGE)
           @Parameter(
               description = "Reference to use. Defaults to default branch if not provided.",
               examples = {@ExampleObject(ref = "ref")})
           @QueryParam("ref")
-          String ref)
+          String ref,
+      @Nullable
+          @Pattern(regexp = Validation.HASH_REGEX, message = Validation.HASH_MESSAGE)
+          @Parameter(
+              description = "a particular hash on the given ref",
+              examples = {@ExampleObject(ref = "hash")})
+          @QueryParam("hashOnRef")
+          String hashOnRef)
       throws NessieNotFoundException;
 
   @POST
@@ -94,14 +100,19 @@ Contents getContents(
     @APIResponse(responseCode = "404", description = "Provided ref doesn't exists")
   })
   MultiGetContentsResponse getMultipleContents(
-      @Pattern(
-              regexp = Validation.REF_NAME_OR_HASH_REGEX,
-              message = Validation.REF_NAME_OR_HASH_MESSAGE)
+      @Pattern(regexp = Validation.REF_NAME_REGEX, message = Validation.REF_NAME_MESSAGE)
           @Parameter(
               description = "Reference to use. Defaults to default branch if not provided.",
               examples = {@ExampleObject(ref = "ref")})
           @QueryParam("ref")
           String ref,
+      @Nullable
+          @Pattern(regexp = Validation.HASH_REGEX, message = Validation.HASH_MESSAGE)
+          @Parameter(
+              description = "a particular hash on the given ref",
+              examples = {@ExampleObject(ref = "hash")})
+          @QueryParam("hashOnRef")
+          String hashOnRef,
       @Valid @NotNull @RequestBody(description = "Keys to retrieve.")
           MultiGetContentsRequest request)
       throws NessieNotFoundException;

model/src/main/java/org/projectnessie/api/TreeApi.java

@@ -16,6 +16,7 @@
 package org.projectnessie.api;
 
 import java.util.List;
+import javax.annotation.Nullable;
 import javax.validation.Valid;
 import javax.validation.constraints.NotNull;
 import javax.validation.constraints.Pattern;
@@ -203,14 +204,19 @@ Reference getReferenceByName(
   })
   public EntriesResponse getEntries(
       @NotNull
-          @Pattern(
-              regexp = Validation.REF_NAME_OR_HASH_REGEX,
-              message = Validation.REF_NAME_OR_HASH_MESSAGE)
+          @Pattern(regexp = Validation.REF_NAME_REGEX, message = Validation.REF_NAME_MESSAGE)
           @Parameter(
               description = "name of ref to fetch from",
               examples = {@ExampleObject(ref = "ref")})
           @PathParam("ref")
           String refName,
+      @Nullable
+          @Pattern(regexp = Validation.HASH_REGEX, message = Validation.HASH_MESSAGE)
+          @Parameter(
+              description = "a particular hash on the given ref",
+              examples = {@ExampleObject(ref = "hash")})
+          @QueryParam("hashOnRef")
+          String hashOnRef,
       @Parameter(description = "maximum number of entries to return, just a hint for the server")
           @QueryParam("max")
           Integer maxRecords,
@@ -290,14 +296,19 @@ public EntriesResponse getEntries(
   })
   LogResponse getCommitLog(
       @NotNull
-          @Pattern(
-              regexp = Validation.REF_NAME_OR_HASH_REGEX,
-              message = Validation.REF_NAME_OR_HASH_MESSAGE)
+          @Pattern(regexp = Validation.REF_NAME_REGEX, message = Validation.REF_NAME_MESSAGE)
           @Parameter(
               description = "ref to show log from",
               examples = {@ExampleObject(ref = "ref")})
           @PathParam("ref")
           String ref,
+      @Nullable
+          @Pattern(regexp = Validation.HASH_REGEX, message = Validation.HASH_MESSAGE)
+          @Parameter(
+              description = "a particular hash on the given ref",
+              examples = {@ExampleObject(ref = "hash")})
+          @QueryParam("hashOnRef")
+          String hashOnRef,
       @Parameter(
               description =
                   "maximum number of commit-log entries to return, just a hint for the server")

python/pynessie/_log.py

@@ -17,20 +17,13 @@ def show_log(
     Note:
         limiting by path is not yet supported.
     """
-    start = filtering_args.pop("start", None)
     end = filtering_args.pop("end", None)
     raw_log = nessie.get_log(start_ref=start_ref, **filtering_args)
 
     def generator() -> Generator[CommitMeta, Any, None]:
-        # start returning data if we don't have a start point, otherwise
-        # only start returning data when the start point was found
-        start_yielding = start is None
         for i in raw_log:
-            if start and i.hash_ == start:
-                start_yielding = True
             if end and i.hash_ == end:
                 break
-            if start_yielding:
-                yield i
+            yield i
 
     return generator()

python/pynessie/cli.py

@@ -253,7 +253,7 @@ def log(  # noqa: C901
     if number:
         filtering_args["max"] = str(number)
     if start:
-        filtering_args["start"] = start
+        filtering_args["hashOnRef"] = start
     if end:
         filtering_args["end"] = end
     # TODO: we should eventually move "start..end" filtering to the server