[Named min timestamp leases] Client API (#7324)

atlasdb-impl-shared/src/main/java/com/palantir/atlasdb/transaction/impl/InstrumentedTimelockService.java

@@ -18,6 +18,8 @@
 import com.codahale.metrics.Meter;
 import com.palantir.atlasdb.AtlasDbMetricNames;
 import com.palantir.atlasdb.util.MetricsManager;
+import com.palantir.lock.annotations.ReviewedRestrictedApiUsage;
+import com.palantir.lock.v2.AcquireNamedMinTimestampLeaseResult;
 import com.palantir.lock.v2.ClientLockingOptions;
 import com.palantir.lock.v2.LockImmutableTimestampResponse;
 import com.palantir.lock.v2.LockRequest;
@@ -131,6 +133,20 @@ public long currentTimeMillis() {
         return executeWithRecord(timelockService::currentTimeMillis);
     }
 
+    @ReviewedRestrictedApiUsage
+    @Override
+    public AcquireNamedMinTimestampLeaseResult acquireNamedMinTimestampLease(
+            String timestampName, int numFreshTimestamps) {
+        return executeWithRecord(
+                () -> timelockService.acquireNamedMinTimestampLease(timestampName, numFreshTimestamps));
+    }
+
+    @ReviewedRestrictedApiUsage
+    @Override
+    public long getMinLeasedTimestampForName(String timestampName) {
+        return executeWithRecord(() -> timelockService.getMinLeasedTimestampForName(timestampName));
+    }
+
     private <T> T executeWithRecord(Supplier<T> method) {
         try {
             T result = method.get();

lock-api-objects/src/main/java/com/palantir/lock/annotations/ReviewedRestrictedApiUsage.java

@@ -0,0 +1,23 @@
+/*
+ * (c) Copyright 2024 Palantir Technologies Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.palantir.lock.annotations;
+
+/**
+ * Annotation to be used to indicate that usage of a restricted method is intentional and all the nuances about it
+ * are understood.
+ */
+public @interface ReviewedRestrictedApiUsage {}

lock-api-objects/src/main/java/com/palantir/lock/v2/AcquireNamedMinTimestampLeaseResult.java

@@ -0,0 +1,32 @@
+/*
+ * (c) Copyright 2024 Palantir Technologies Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.palantir.lock.v2;
+
+import java.util.List;
+import org.immutables.value.Value;
+
+@Value.Immutable
+public interface AcquireNamedMinTimestampLeaseResult {
+    @Value.Parameter
+    long minLeasedTimestamp();
+
+    @Value.Parameter
+    LockToken lock();
+
+    @Value.Parameter
+    List<Long> freshTimestamps();
+}

lock-api-objects/src/main/java/com/palantir/lock/v2/TimelockService.java

@@ -15,6 +15,8 @@
  */
 package com.palantir.lock.v2;
 
+import com.google.errorprone.annotations.RestrictedApi;
+import com.palantir.lock.annotations.ReviewedRestrictedApiUsage;
 import com.palantir.logsafe.Safe;
 import com.palantir.processors.AutoDelegate;
 import com.palantir.processors.DoNotDelegate;
@@ -110,4 +112,28 @@ default List<StartIdentifiedAtlasDbTransactionResponse> startIdentifiedAtlasDbTr
     void tryUnlock(Set<LockToken> tokens);
 
     long currentTimeMillis();
+
+    /**
+     * Acquires a lease on a named timestamp. The lease is taken out with a new fresh timestamp.
+     * The returned timestamps are fresh timestamps obtained strictly after the lease is taken out.
+     */
+    @RestrictedApi(
+            explanation =
+                    "This method is for internal Atlas and internal library use only. Clients MUST NOT use it unless"
+                        + " given explicit approval. Mis-use can result in SEVERE DATA CORRUPTION and the API contract"
+                        + " is subject to change at any time.",
+            allowlistAnnotations = ReviewedRestrictedApiUsage.class)
+    AcquireNamedMinTimestampLeaseResult acquireNamedMinTimestampLease(String timestampName, int numFreshTimestamps);
+
+    /**
+     * Returns the smallest leased timestamp in the associated named collection at the time of the call.
+     * If there are no active leases, a fresh timestamp is obtained and returned.
+     */
+    @RestrictedApi(
+            explanation =
+                    "This method is for internal Atlas and internal library use only. Clients MUST NOT use it unless"
+                        + " given explicit approval. Mis-use can result in SEVERE DATA CORRUPTION and the API contract"
+                        + " is subject to change at any time.",
+            allowlistAnnotations = ReviewedRestrictedApiUsage.class)
+    long getMinLeasedTimestampForName(String timestampName);
 }

lock-api/src/main/java/com/palantir/lock/client/ProfilingTimelockService.java

@@ -20,6 +20,8 @@
 import com.google.common.base.Stopwatch;
 import com.google.common.util.concurrent.RateLimiter;
 import com.palantir.common.base.Throwables;
+import com.palantir.lock.annotations.ReviewedRestrictedApiUsage;
+import com.palantir.lock.v2.AcquireNamedMinTimestampLeaseResult;
 import com.palantir.lock.v2.ClientLockingOptions;
 import com.palantir.lock.v2.LockImmutableTimestampResponse;
 import com.palantir.lock.v2.LockRequest;
@@ -169,6 +171,21 @@ public long currentTimeMillis() {
         return runTaskTimed("currentTimeMillis", delegate::currentTimeMillis);
     }
 
+    @ReviewedRestrictedApiUsage
+    @Override
+    public AcquireNamedMinTimestampLeaseResult acquireNamedMinTimestampLease(
+            String timestampName, int numFreshTimestamps) {
+        return runTaskTimed(
+                "acquireNamedMinTimestampLease",
+                () -> delegate.acquireNamedMinTimestampLease(timestampName, numFreshTimestamps));
+    }
+
+    @ReviewedRestrictedApiUsage
+    @Override
+    public long getMinLeasedTimestampForName(String timestampName) {
+        return runTaskTimed("getMinLeasedNamedTimestamp", () -> delegate.getMinLeasedTimestampForName(timestampName));
+    }
+
     private <T> T runTaskTimed(String actionName, Supplier<T> action) {
         Stopwatch stopwatch = stopwatchSupplier.get();
         try {

lock-api/src/main/java/com/palantir/lock/client/RemoteTimelockServiceAdapter.java

@@ -20,6 +20,8 @@
 import com.palantir.atlasdb.timelock.api.ConjureGetFreshTimestampsResponseV2;
 import com.palantir.atlasdb.timelock.api.ConjureTimestampRange;
 import com.palantir.atlasdb.timelock.api.Namespace;
+import com.palantir.lock.annotations.ReviewedRestrictedApiUsage;
+import com.palantir.lock.v2.AcquireNamedMinTimestampLeaseResult;
 import com.palantir.lock.v2.ClientLockingOptions;
 import com.palantir.lock.v2.LockImmutableTimestampResponse;
 import com.palantir.lock.v2.LockRequest;
@@ -168,6 +170,21 @@ public long currentTimeMillis() {
         return rpcClient.currentTimeMillis();
     }
 
+    @ReviewedRestrictedApiUsage
+    @Override
+    public AcquireNamedMinTimestampLeaseResult acquireNamedMinTimestampLease(
+            String timestampName, int numFreshTimestamps) {
+        // TODO(aalouane): implement!
+        throw new UnsupportedOperationException("Not implemented yet!");
+    }
+
+    @ReviewedRestrictedApiUsage
+    @Override
+    public long getMinLeasedTimestampForName(String timestampName) {
+        // TODO(aalouane): implement!
+        throw new UnsupportedOperationException("Not implemented yet!");
+    }
+
     @Override
     public void close() {
         transactionStarter.close();

lock-api/src/main/java/com/palantir/lock/client/TimeLockClient.java

@@ -21,6 +21,8 @@
 import com.palantir.common.concurrent.NamedThreadFactory;
 import com.palantir.common.concurrent.PTExecutors;
 import com.palantir.leader.NotCurrentLeaderException;
+import com.palantir.lock.annotations.ReviewedRestrictedApiUsage;
+import com.palantir.lock.v2.AcquireNamedMinTimestampLeaseResult;
 import com.palantir.lock.v2.ClientLockingOptions;
 import com.palantir.lock.v2.LockImmutableTimestampResponse;
 import com.palantir.lock.v2.LockLeaseRefresher;
@@ -180,6 +182,19 @@ public long currentTimeMillis() {
         return executeOnTimeLock(delegate::currentTimeMillis);
     }
 
+    @ReviewedRestrictedApiUsage
+    @Override
+    public AcquireNamedMinTimestampLeaseResult acquireNamedMinTimestampLease(
+            String timestampName, int numFreshTimestamps) {
+        return delegate.acquireNamedMinTimestampLease(timestampName, numFreshTimestamps);
+    }
+
+    @ReviewedRestrictedApiUsage
+    @Override
+    public long getMinLeasedTimestampForName(String timestampName) {
+        return delegate.getMinLeasedTimestampForName(timestampName);
+    }
+
     private static <T> T executeOnTimeLock(Callable<T> callable) {
         try {
             return callable.call();

lock-api/src/main/java/com/palantir/lock/client/UnreliableTimeLockService.java

@@ -19,6 +19,8 @@
 import com.google.common.collect.Sets;
 import com.palantir.atlasdb.buggify.api.BuggifyFactory;
 import com.palantir.atlasdb.buggify.impl.DefaultBuggifyFactory;
+import com.palantir.lock.annotations.ReviewedRestrictedApiUsage;
+import com.palantir.lock.v2.AcquireNamedMinTimestampLeaseResult;
 import com.palantir.lock.v2.ClientLockingOptions;
 import com.palantir.lock.v2.LockImmutableTimestampResponse;
 import com.palantir.lock.v2.LockRequest;
@@ -155,6 +157,19 @@ public long currentTimeMillis() {
         return delegate.currentTimeMillis();
     }
 
+    @ReviewedRestrictedApiUsage
+    @Override
+    public AcquireNamedMinTimestampLeaseResult acquireNamedMinTimestampLease(
+            String timestampName, int numFreshTimestamps) {
+        return delegate.acquireNamedMinTimestampLease(timestampName, numFreshTimestamps);
+    }
+
+    @ReviewedRestrictedApiUsage
+    @Override
+    public long getMinLeasedTimestampForName(String timestampName) {
+        return delegate.getMinLeasedTimestampForName(timestampName);
+    }
+
     private void maybeRandomlyIncreaseTimestamp() {
         buggify.maybe(INCREASE_TIMESTAMP_PROBABILITY).run(timestampManager::randomlyIncreaseTimestamp);
     }

lock-impl/src/main/java/com/palantir/lock/impl/LegacyTimelockService.java

@@ -24,6 +24,7 @@
 import com.palantir.lock.LockRefreshToken;
 import com.palantir.lock.LockService;
 import com.palantir.lock.SimpleTimeDuration;
+import com.palantir.lock.v2.AcquireNamedMinTimestampLeaseResult;
 import com.palantir.lock.v2.ClientLockingOptions;
 import com.palantir.lock.v2.LockImmutableTimestampResponse;
 import com.palantir.lock.v2.LockRequest;
@@ -181,6 +182,19 @@ public long currentTimeMillis() {
         return lockService.currentTimeMillis();
     }
 
+    @Override
+    public AcquireNamedMinTimestampLeaseResult acquireNamedMinTimestampLease(
+            String timestampName, int numFreshTimestamps) {
+        // TODO(aalouane): implement!
+        throw new UnsupportedOperationException("Not implemented yet!");
+    }
+
+    @Override
+    public long getMinLeasedTimestampForName(String timestampName) {
+        // TODO(aalouane): implement!
+        throw new UnsupportedOperationException("Not implemented yet!");
+    }
+
     private long getImmutableTimestampInternal(long ts) {
         Long minLocked = lockService.getMinLockedInVersionId(immutableTsLockClient.getClientId());
         return minLocked == null ? ts : minLocked;