Support EXPIRETIME and PEXPIRETIME (#2083)

Adds support for https://redis.io/commands/expiretime/ https://redis.io/commands/pexpiretime/ (#2055)


Co-authored-by: Nick Craver <[email protected]>

Author: Avital-Fine

docs/ReleaseNotes.md

@@ -15,6 +15,8 @@
 - Adds: Support for `SINTERCARD` with `.SetIntersectionLength()`/`.SetIntersectionLengthAsync()` ([#2078 by Avital-Fine](https://github.com/StackExchange/StackExchange.Redis/pull/2078))
 - Adds: Support for `LPOS` with `.ListPosition()`/`.ListPositionAsync()` and `.ListPositions()`/`.ListPositionsAsync()` ([#2080 by slorello89](https://github.com/StackExchange/StackExchange.Redis/pull/2080))
 - Adds: Support for `ZMSCORE` with `.SortedSetScores()`/.`SortedSetScoresAsync()` ([#2082 by ttingen](https://github.com/StackExchange/StackExchange.Redis/pull/2082))
+- Adds: Support for `NX | XX | GT | LT` to `EXPIRE`, `EXPIREAT`, `PEXPIRE`, and `PEXPIREAT` with `.KeyExpire()`/`.KeyExpireAsync()` ([#2083 by Avital-Fine](https://github.com/StackExchange/StackExchange.Redis/pull/2083))
+- Adds: Support for `EXPIRETIME`, and `PEXPIRETIME` with `.KeyExpireTime()`/`.KeyExpireTimeAsync()` ([#2083 by Avital-Fine](https://github.com/StackExchange/StackExchange.Redis/pull/2083))
 - Fix: For streams, properly hash `XACK`, `XCLAIM`, and `XPENDING` in cluster scenarios to eliminate `MOVED` retries ([#2085 by nielsderdaele](https://github.com/StackExchange/StackExchange.Redis/pull/2085))
 - Adds: Support for `OBJECT REFCOUNT` with `.KeyRefCount()`/`.KeyRefCountAsync()` ([#2087 by Avital-Fine](https://github.com/StackExchange/StackExchange.Redis/pull/2087))
 - Adds: Support for `OBJECT ENCODING` with `.KeyEncoding()`/`.KeyEncodingAsync()` ([#2088 by Avital-Fine](https://github.com/StackExchange/StackExchange.Redis/pull/2088))

src/StackExchange.Redis/Enums/ExpireWhen.cs

@@ -0,0 +1,42 @@
+using System;
+
+namespace StackExchange.Redis;
+
+/// <summary>
+/// Specifies when to set the expiry for a key.
+/// </summary>
+public enum ExpireWhen
+{
+    /// <summary>
+    /// Set expiry whether or not there is an existing expiry.
+    /// </summary>
+    Always,
+    /// <summary>
+    /// Set expiry only when the new expiry is greater than current one.
+    /// </summary>
+    GreaterThanCurrentExpiry,
+    /// <summary>
+    /// Set expiry only when the key has an existing expiry.
+    /// </summary>
+    HasExpiry,
+    /// <summary>
+    /// Set expiry only when the key has no expiry.
+    /// </summary>
+    HasNoExpiry,
+    /// <summary>
+    /// Set expiry only when the new expiry is less than current one
+    /// </summary>
+    LessThanCurrentExpiry,
+}
+
+internal static class ExpiryOptionExtensions
+{
+    public static RedisValue ToLiteral(this ExpireWhen op) => op switch
+    {
+        ExpireWhen.HasNoExpiry => RedisLiterals.NX,
+        ExpireWhen.HasExpiry => RedisLiterals.XX,
+        ExpireWhen.GreaterThanCurrentExpiry => RedisLiterals.GT,
+        ExpireWhen.LessThanCurrentExpiry => RedisLiterals.LT,
+        _ => throw new ArgumentOutOfRangeException(nameof(op))
+    };
+}

src/StackExchange.Redis/Enums/RedisCommand.cs

@@ -37,6 +37,7 @@ internal enum RedisCommand
         EXISTS,
         EXPIRE,
         EXPIREAT,
+        EXPIRETIME,
 
         FLUSHALL,
         FLUSHDB,
@@ -110,6 +111,7 @@ internal enum RedisCommand
         PERSIST,
         PEXPIRE,
         PEXPIREAT,
+        PEXPIRETIME,
         PFADD,
         PFCOUNT,
         PFMERGE,

src/StackExchange.Redis/Interfaces/IDatabase.cs

@@ -641,7 +641,8 @@ public interface IDatabase : IRedis, IDatabaseAsync
         long KeyExists(RedisKey[] keys, CommandFlags flags = CommandFlags.None);
 
         /// <summary>
-        /// Set a timeout on key. After the timeout has expired, the key will automatically be deleted.
+        /// Set a timeout on <paramref name="key"/>.
+        /// After the timeout has expired, the key will automatically be deleted.
         /// A key with an associated timeout is said to be volatile in Redis terminology.
         /// </summary>
         /// <param name="key">The key to set the expiration for.</param>
@@ -665,7 +666,22 @@ public interface IDatabase : IRedis, IDatabaseAsync
         bool KeyExpire(RedisKey key, TimeSpan? expiry, CommandFlags flags = CommandFlags.None);
 
         /// <summary>
-        /// Set a timeout on key. After the timeout has expired, the key will automatically be deleted.
+        /// Set a timeout on <paramref name="key"/>.
+        /// After the timeout has expired, the key will automatically be deleted.
+        /// A key with an associated timeout is said to be volatile in Redis terminology.
+        /// </summary>
+        /// <param name="key">The key to set the expiration for.</param>
+        /// <param name="expiry">The timeout to set.</param>
+        /// <param name="when">Since Redis 7.0.0, you can choose under which condition the expiration will be set using <see cref="ExpireWhen"/>.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <returns><see langword="true"/> if the timeout was set. <see langword="false"/> if key does not exist or the timeout could not be set.</returns>
+        /// <remarks>https://redis.io/commands/expire</remarks>
+        /// <remarks>https://redis.io/commands/pexpire</remarks>
+        bool KeyExpire(RedisKey key, TimeSpan? expiry, ExpireWhen when, CommandFlags flags = CommandFlags.None);
+
+        /// <summary>
+        /// Set a timeout on <paramref name="key"/>.
+        /// After the timeout has expired, the key will automatically be deleted.
         /// A key with an associated timeout is said to be volatile in Redis terminology.
         /// </summary>
         /// <param name="key">The key to set the expiration for.</param>
@@ -688,6 +704,30 @@ public interface IDatabase : IRedis, IDatabaseAsync
         /// <remarks>https://redis.io/commands/persist</remarks>
         bool KeyExpire(RedisKey key, DateTime? expiry, CommandFlags flags = CommandFlags.None);
 
+        /// <summary>
+        /// Set a timeout on <paramref name="key"/>.
+        /// After the timeout has expired, the key will automatically be deleted.
+        /// A key with an associated timeout is said to be volatile in Redis terminology.
+        /// </summary>
+        /// <param name="key">The key to set the expiration for.</param>
+        /// <param name="expiry">The timeout to set.</param>
+        /// <param name="when">Since Redis 7.0.0, you can choose under which condition the expiration will be set using <see cref="ExpireWhen"/>.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <returns><see langword="true"/> if the timeout was set. <see langword="false"/> if key does not exist or the timeout could not be set.</returns>
+        /// <remarks>https://redis.io/commands/expire</remarks>
+        /// <remarks>https://redis.io/commands/pexpire</remarks>
+        bool KeyExpire(RedisKey key, DateTime? expiry, ExpireWhen when, CommandFlags flags = CommandFlags.None);
+
+        /// <summary>
+        /// Returns the absolute time at which the given <paramref name="key"/> will expire, if it exists and has an expiration.
+        /// </summary>
+        /// <param name="key">The key to get the expiration for.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <returns>The time at which the given key will expire, or <see langword="null"/> if the key does not exist or has no associated expiration time.</returns>
+        /// <remarks>https://redis.io/commands/expiretime</remarks>
+        /// <remarks>https://redis.io/commands/pexpiretime</remarks>
+        DateTime? KeyExpireTime(RedisKey key, CommandFlags flags = CommandFlags.None);
+
         /// <summary>
         /// Returns the time since the object stored at the specified key is idle (not requested by read or write operations).
         /// </summary>

src/StackExchange.Redis/Interfaces/IDatabaseAsync.cs

@@ -617,7 +617,8 @@ public interface IDatabaseAsync : IRedisAsync
         Task<long> KeyExistsAsync(RedisKey[] keys, CommandFlags flags = CommandFlags.None);
 
         /// <summary>
-        /// Set a timeout on key. After the timeout has expired, the key will automatically be deleted.
+        /// Set a timeout on <paramref name="key"/>.
+        /// After the timeout has expired, the key will automatically be deleted.
         /// A key with an associated timeout is said to be volatile in Redis terminology.
         /// </summary>
         /// <param name="key">The key to set the expiration for.</param>
@@ -632,7 +633,8 @@ public interface IDatabaseAsync : IRedisAsync
         /// </para>
         /// <para>
         /// Since Redis 2.1.3, you can update the timeout of a key.
-        /// It is also possible to remove the timeout using the PERSIST command. See the page on key expiry for more information.
+        /// It is also possible to remove the timeout using the PERSIST command.
+        /// See the page on key expiry for more information.
         /// </para>
         /// </remarks>
         /// <remarks>https://redis.io/commands/expire</remarks>
@@ -641,7 +643,22 @@ public interface IDatabaseAsync : IRedisAsync
         Task<bool> KeyExpireAsync(RedisKey key, TimeSpan? expiry, CommandFlags flags = CommandFlags.None);
 
         /// <summary>
-        /// Set a timeout on key. After the timeout has expired, the key will automatically be deleted.
+        /// Set a timeout on <paramref name="key"/>.
+        /// After the timeout has expired, the key will automatically be deleted.
+        /// A key with an associated timeout is said to be volatile in Redis terminology.
+        /// </summary>
+        /// <param name="key">The key to set the expiration for.</param>
+        /// <param name="expiry">The timeout to set.</param>
+        /// <param name="when">Since Redis 7.0.0, you can choose under which condition the expiration will be set using <see cref="ExpireWhen"/>.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <returns><see langword="true"/> if the timeout was set. <see langword="false"/> if key does not exist or the timeout could not be set.</returns>
+        /// <remarks>https://redis.io/commands/expire</remarks>
+        /// <remarks>https://redis.io/commands/pexpire</remarks>
+        Task<bool> KeyExpireAsync(RedisKey key, TimeSpan? expiry, ExpireWhen when, CommandFlags flags = CommandFlags.None);
+
+        /// <summary>
+        /// Set a timeout on <paramref name="key"/>.
+        /// After the timeout has expired, the key will automatically be deleted.
         /// A key with an associated timeout is said to be volatile in Redis terminology.
         /// </summary>
         /// <param name="key">The key to set the expiration for.</param>
@@ -656,14 +673,39 @@ public interface IDatabaseAsync : IRedisAsync
         /// </para>
         /// <para>
         /// Since Redis 2.1.3, you can update the timeout of a key.
-        /// It is also possible to remove the timeout using the PERSIST command. See the page on key expiry for more information.
+        /// It is also possible to remove the timeout using the PERSIST command.
+        /// See the page on key expiry for more information.
         /// </para>
         /// </remarks>
         /// <remarks>https://redis.io/commands/expireat</remarks>
         /// <remarks>https://redis.io/commands/pexpireat</remarks>
         /// <remarks>https://redis.io/commands/persist</remarks>
         Task<bool> KeyExpireAsync(RedisKey key, DateTime? expiry, CommandFlags flags = CommandFlags.None);
 
+        /// <summary>
+        /// Set a timeout on <paramref name="key"/>.
+        /// After the timeout has expired, the key will automatically be deleted.
+        /// A key with an associated timeout is said to be volatile in Redis terminology.
+        /// </summary>
+        /// <param name="key">The key to set the expiration for.</param>
+        /// <param name="expiry">The timeout to set.</param>
+        /// <param name="when">Since Redis 7.0.0, you can choose under which condition the expiration will be set using <see cref="ExpireWhen"/>.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <returns><see langword="true"/> if the timeout was set. <see langword="false"/> if key does not exist or the timeout could not be set.</returns>
+        /// <remarks>https://redis.io/commands/expire</remarks>
+        /// <remarks>https://redis.io/commands/pexpire</remarks>
+        Task<bool> KeyExpireAsync(RedisKey key, DateTime? expiry, ExpireWhen when, CommandFlags flags = CommandFlags.None);
+
+        /// <summary>
+        /// Returns the absolute time at which the given <paramref name="key"/> will expire, if it exists and has an expiration.
+        /// </summary>
+        /// <param name="key">The key to get the expiration for.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <returns>The time at which the given key will expire, or <see langword="null"/> if the key does not exist or has no associated expiration time.</returns>
+        /// <remarks>https://redis.io/commands/expiretime</remarks>
+        /// <remarks>https://redis.io/commands/pexpiretime</remarks>
+        Task<DateTime?> KeyExpireTimeAsync(RedisKey key, CommandFlags flags = CommandFlags.None);
+
         /// <summary>
         /// Returns the time since the object stored at the specified key is idle (not requested by read or write operations).
         /// </summary>

src/StackExchange.Redis/KeyspaceIsolation/DatabaseWrapper.cs

@@ -170,9 +170,18 @@ public long KeyExists(RedisKey[] keys, CommandFlags flags = CommandFlags.None) =
         public bool KeyExpire(RedisKey key, DateTime? expiry, CommandFlags flags = CommandFlags.None) =>
             Inner.KeyExpire(ToInner(key), expiry, flags);
 
+        public bool KeyExpire(RedisKey key, DateTime? expiry, ExpireWhen when, CommandFlags flags = CommandFlags.None) =>
+            Inner.KeyExpire(ToInner(key), expiry, when, flags);
+
         public bool KeyExpire(RedisKey key, TimeSpan? expiry, CommandFlags flags = CommandFlags.None) =>
             Inner.KeyExpire(ToInner(key), expiry, flags);
 
+        public bool KeyExpire(RedisKey key, TimeSpan? expiry, ExpireWhen when, CommandFlags flags = CommandFlags.None) =>
+            Inner.KeyExpire(ToInner(key), expiry, when, flags);
+
+        public DateTime? KeyExpireTime(RedisKey key, CommandFlags flags = CommandFlags.None) =>
+            Inner.KeyExpireTime(ToInner(key), flags);
+
         public TimeSpan? KeyIdleTime(RedisKey key, CommandFlags flags = CommandFlags.None) =>
             Inner.KeyIdleTime(ToInner(key), flags);
 

src/StackExchange.Redis/KeyspaceIsolation/WrapperBase.cs

@@ -181,9 +181,18 @@ public Task<long> KeyExistsAsync(RedisKey[] keys, CommandFlags flags = CommandFl
         public Task<bool> KeyExpireAsync(RedisKey key, DateTime? expiry, CommandFlags flags = CommandFlags.None) =>
             Inner.KeyExpireAsync(ToInner(key), expiry, flags);
 
+        public Task<bool> KeyExpireAsync(RedisKey key, DateTime? expiry, ExpireWhen when, CommandFlags flags = CommandFlags.None) =>
+            Inner.KeyExpireAsync(ToInner(key), expiry, when, flags);
+
         public Task<bool> KeyExpireAsync(RedisKey key, TimeSpan? expiry, CommandFlags flags = CommandFlags.None) =>
             Inner.KeyExpireAsync(ToInner(key), expiry, flags);
 
+        public Task<bool> KeyExpireAsync(RedisKey key, TimeSpan? expiry, ExpireWhen when, CommandFlags flags = CommandFlags.None) =>
+            Inner.KeyExpireAsync(ToInner(key), expiry, when, flags);
+
+        public Task<DateTime?> KeyExpireTimeAsync(RedisKey key, CommandFlags flags = CommandFlags.None) =>
+            Inner.KeyExpireTimeAsync(ToInner(key), flags);
+
         public Task<TimeSpan?> KeyIdleTimeAsync(RedisKey key, CommandFlags flags = CommandFlags.None) =>
             Inner.KeyIdleTimeAsync(ToInner(key), flags);