Add PersistDriver.getWithTTL (#842)

* Add PersistDriver.getWithTTL

* Add memory driver implementation, add tests

* Return optional tuple instead of optional object

* Fix documentation

Author: adam-fowler

Sources/Hummingbird/Storage/MemoryPersistDriver.swift

@@ -72,6 +72,18 @@ public actor MemoryPersistDriver<C: Clock>: PersistDriver where C.Duration == Du
         return object
     }
 
+    /// get value and time to live for key
+    public func getWithTTL<Object: Codable & Sendable>(key: String, as type: Object.Type) async throws -> (object: Object, ttl: Duration?)? {
+        guard let item = self.values[key] else { return nil }
+        if let expires = item.expires {
+            guard self.clock.now <= expires else { return nil }
+            guard let object = item.value as? Object else { throw PersistError.invalidConversion }
+            return (object, self.clock.now.duration(to: expires))
+        }
+        guard let object = item.value as? Object else { throw PersistError.invalidConversion }
+        return (object, nil)
+    }
+
     public func remove(key: String) async throws {
         self.values[key] = nil
     }

Sources/Hummingbird/Storage/PersistDriver.swift

@@ -35,6 +35,16 @@ public protocol PersistDriver: Service {
     ///   - as: Type you want value to be returned as. If it cannot be returned as this value then nil will be returned
     func get<Object: Codable & Sendable>(key: String, as: Object.Type) async throws -> Object?
 
+    /// get value and time to live for key
+    ///
+    /// There is a default version of this function which only returns the value. Persist drivers have to opt
+    /// into providing the time to live. Both Valkey and Postgres drivers will return the time to live.
+    ///
+    /// - Parameters:
+    ///   - key: Key used to look for value
+    ///   - as: Type you want value to be returned as. If it cannot be returned as this value then nil will be returned
+    func getWithTTL<Object: Codable & Sendable>(key: String, as: Object.Type) async throws -> (object: Object, ttl: Duration?)?
+
     /// remove value associated with key
     /// - Parameters:
     ///   - key: Key used to look for value
@@ -62,6 +72,15 @@ extension PersistDriver {
         try await self.set(key: key, value: value, expires: nil)
     }
 
+    /// get value and time to live for key
+    /// - Parameters:
+    ///   - key: Key used to look for value
+    ///   - type: Type you want value to be returned as. If it cannot be returned as this value then nil will be returned
+    public func getWithTTL<Object: Codable & Sendable>(key: String, as type: Object.Type) async throws -> (object: Object, ttl: Duration?)? {
+        let value = try await get(key: key, as: type)
+        return value.map { ($0, nil) }
+    }
+
     public func run() async throws {
         // ignore cancellation error as we need to shutdown
         try? await gracefulShutdown()

Tests/HummingbirdTests/PersistTests.swift

@@ -37,6 +37,10 @@ struct PersistTests {
             guard let tag = context.parameters.get("tag", as: String.self) else { throw HTTPError(.badRequest) }
             return try await persist.get(key: tag, as: String.self)
         }
+        router.get("/persist/:tag/ttl") { _, context -> String? in
+            guard let tag = context.parameters.get("tag", as: String.self) else { throw HTTPError(.badRequest) }
+            return try await persist.getWithTTL(key: tag, as: String.self)?.ttl.map { String($0.components.seconds) }
+        }
         router.delete("/persist/:tag") { _, context -> HTTPResponse.Status in
             guard let tag = context.parameters.get("tag", as: String.self) else { throw HTTPError(.badRequest) }
             try await persist.remove(key: tag)
@@ -136,6 +140,21 @@ struct PersistTests {
         }
     }
 
+    @Test func testTTL() async throws {
+        let (router, _) = try createRouter()
+        let app = Application(responder: router.buildResponder())
+        try await app.test(.router) { client in
+
+            let tag1 = UUID().uuidString
+
+            try await client.execute(uri: "/persist/\(tag1)/10", method: .put, body: ByteBufferAllocator().buffer(string: "ThisIsTest2")) { _ in }
+            try await client.execute(uri: "/persist/\(tag1)/ttl", method: .get) { response in
+                let ttl = try #require(Int(String(buffer: response.body)))
+                #expect(ttl <= 10 && ttl > 1)
+            }
+        }
+    }
+
     @Test func testCodable() async throws {
         struct TestCodable: Codable {
             let buffer: String