Implement Time-To-Live (TTL) Support (#23)

* set support for TTL

* TTL support for get/set

* remove debug statements

* update doc comments

* keep our main example the same

* naming consistancy in test

* PR comment fixes

* refactored flags to hold TimeToLive

* indefinitely test

* naming consistency

* TTL conformance for Eq + Hash

* refactored MemcachedConnection

* soundness

* remove flgs from set

* clean up remaining PR cmnts

* no longer using these

* closes #17

Author: dkz2

Package.swift

@@ -18,10 +18,10 @@ import PackageDescription
 let package = Package(
     name: "swift-memcache-gsoc",
     platforms: [
-        .macOS(.v10_15),
-        .iOS(.v13),
-        .watchOS(.v6),
-        .tvOS(.v13),
+        .macOS(.v13),
+        .iOS(.v16),
+        .watchOS(.v9),
+        .tvOS(.v16),
     ],
     products: [
         .library(

Sources/SwiftMemcache/Extensions/ByteBuffer+SwiftMemcache.swift

@@ -12,6 +12,7 @@
 //
 //===----------------------------------------------------------------------===//
 
+import Foundation
 import NIOCore
 
 extension ByteBuffer {
@@ -30,13 +31,13 @@ extension ByteBuffer {
     /// Reads an integer from ASCII characters directly from this `ByteBuffer`.
     /// The reading stops as soon as a non-digit character is encountered.
     ///
-    /// - Returns: A `UInt64` integer read from the buffer.
+    /// - Returns: A `T` integer read from the buffer.
     /// If the buffer does not contain any digits at the current reading position, returns `nil`.
-    mutating func readIntegerFromASCII() -> UInt64? {
-        var value: UInt64 = 0
+    mutating func readIntegerFromASCII<T: FixedWidthInteger>() -> T? {
+        var value: T = 0
         while self.readableBytes > 0, let currentByte = self.readInteger(as: UInt8.self),
               currentByte >= UInt8.zero && currentByte <= UInt8.nine {
-            value = (value * 10) + UInt64(currentByte - UInt8.zero)
+            value = (value * 10) + T(currentByte - UInt8.zero)
         }
         return value > 0 ? value : nil
     }
@@ -56,6 +57,35 @@ extension ByteBuffer {
             self.writeInteger(UInt8.whitespace)
             self.writeInteger(UInt8.v)
         }
+
+        if let timeToLive = flags.timeToLive {
+            switch timeToLive {
+            case .indefinitely:
+                self.writeInteger(UInt8.whitespace)
+                self.writeInteger(UInt8.T)
+                self.writeInteger(UInt8.zero)
+            case .expiresAt(let instant):
+                let now = ContinuousClock.now
+                let duration = now.duration(to: instant)
+                let ttlSeconds = duration.components.seconds
+                let maximumOffset = 60 * 60 * 24 * 30
+
+                if ttlSeconds > maximumOffset {
+                    // The Time-To-Live is treated as Unix time.
+                    var timespec = timespec()
+                    timespec_get(&timespec, TIME_UTC)
+                    let timeIntervalNow = Double(timespec.tv_sec) + Double(timespec.tv_nsec) / 1_000_000_000
+                    let ttlUnixTime = Int32(timeIntervalNow) + Int32(ttlSeconds)
+                    self.writeInteger(UInt8.whitespace)
+                    self.writeInteger(UInt8.T)
+                    self.writeIntegerAsASCII(ttlUnixTime)
+                } else {
+                    self.writeInteger(UInt8.whitespace)
+                    self.writeInteger(UInt8.T)
+                    self.writeIntegerAsASCII(ttlSeconds)
+                }
+            }
+        }
     }
 }
 

Sources/SwiftMemcache/Extensions/UInt8+Characters.swift

@@ -20,6 +20,7 @@ extension UInt8 {
     static var s: UInt8 = .init(ascii: "s")
     static var g: UInt8 = .init(ascii: "g")
     static var v: UInt8 = .init(ascii: "v")
+    static var T: UInt8 = .init(ascii: "T")
     static var zero: UInt8 = .init(ascii: "0")
     static var nine: UInt8 = .init(ascii: "9")
 }

Sources/SwiftMemcache/MemcachedConnection.swift

@@ -136,21 +136,13 @@ public actor MemcachedConnection {
         }
     }
 
-    /// Fetch the value for a key from the Memcache server.
-    ///
-    /// - Parameter key: The key to fetch the value for.
-    /// - Returns: A `Value` containing the fetched value, or `nil` if no value was found.
-    public func get<Value: MemcachedValue>(_ key: String, as valueType: Value.Type = Value.self) async throws -> Value? {
+    /// Send a request to the Memcached server and returns a `MemcachedResponse`.
+    private func sendRequest(_ request: MemcachedRequest) async throws -> MemcachedResponse {
         switch self.state {
         case .initial(_, _, _, let requestContinuation),
              .running(_, _, _, let requestContinuation):
 
-            var flags = MemcachedFlags()
-            flags.shouldReturnValue = true
-            let command = MemcachedRequest.GetCommand(key: key, flags: flags)
-            let request = MemcachedRequest.get(command)
-
-            let response = try await withCheckedThrowingContinuation { continuation in
+            return try await withCheckedThrowingContinuation { continuation in
                 switch requestContinuation.yield((request, continuation)) {
                 case .enqueued:
                     break
@@ -159,7 +151,31 @@ public actor MemcachedConnection {
                 default:
                     break
                 }
-            }.value
+            }
+
+        case .finished:
+            throw MemcachedConnectionError.connectionShutdown
+        }
+    }
+
+    // MARK: - Fetching Values
+
+    /// Fetch the value for a key from the Memcache server.
+    ///
+    /// - Parameter key: The key to fetch the value for.
+    /// - Returns: A `Value` containing the fetched value, or `nil` if no value was found.
+    public func get<Value: MemcachedValue>(_ key: String, as valueType: Value.Type = Value.self) async throws -> Value? {
+        switch self.state {
+        case .initial(_, _, _, _),
+             .running:
+
+            var flags = MemcachedFlags()
+            flags.shouldReturnValue = true
+
+            let command = MemcachedRequest.GetCommand(key: key, flags: flags)
+            let request = MemcachedRequest.get(command)
+
+            let response = try await sendRequest(request).value
 
             if var unwrappedResponse = response {
                 return Value.readFromBuffer(&unwrappedResponse)
@@ -171,31 +187,61 @@ public actor MemcachedConnection {
         }
     }
 
-    /// Set the value for a key on the Memcache server.
+    // MARK: - Touch
+
+    /// Update the time-to-live for a key.
+    ///
+    /// This method changes the expiration time of an existing item without fetching it. If the key does not exist or if the new expiration time is already passed, the operation will not succeed.
     ///
     /// - Parameters:
-    ///   - key: The key to set the value for.
-    ///   - value: The `Value` to set for the key.
-    public func set(_ key: String, value: some MemcachedValue) async throws {
+    ///   - key: The key to update the time-to-live for.
+    ///   - newTimeToLive: The new time-to-live.
+    /// - Throws: A `MemcachedConnectionError` if the connection is shutdown or if there's an unexpected nil response.
+    public func touch(_ key: String, newTimeToLive: TimeToLive) async throws {
         switch self.state {
-        case .initial(_, let bufferAllocator, _, let requestContinuation),
-             .running(let bufferAllocator, _, _, let requestContinuation):
+        case .initial(_, _, _, _),
+             .running:
+
+            var flags = MemcachedFlags()
+            flags.timeToLive = newTimeToLive
+
+            let command = MemcachedRequest.GetCommand(key: key, flags: flags)
+            let request = MemcachedRequest.get(command)
+
+            _ = try await self.sendRequest(request)
+
+        case .finished:
+            throw MemcachedConnectionError.connectionShutdown
+        }
+    }
+
+    // MARK: - Setting a Value
+
+    /// Sets a value for a specified key in the Memcache server with an optional Time-to-Live (TTL) parameter.
+    ///
+    /// - Parameters:
+    ///   - key: The key for which the value is to be set.
+    ///   - value: The `MemcachedValue` to set for the key.
+    ///   - expiration: An optional `TimeToLive` value specifying the TTL (Time-To-Live) for the key-value pair.
+    ///     If provided, the key-value pair will be removed from the cache after the specified TTL duration has passed.
+    ///     If not provided, the key-value pair will persist indefinitely in the cache.
+    /// - Throws: A `MemcachedConnectionError` if the connection to the Memcached server is shut down.
+    public func set(_ key: String, value: some MemcachedValue, timeToLive: TimeToLive = .indefinitely) async throws {
+        switch self.state {
+        case .initial(_, let bufferAllocator, _, _),
+             .running(let bufferAllocator, _, _, _):
 
             var buffer = bufferAllocator.buffer(capacity: 0)
             value.writeToBuffer(&buffer)
-            let command = MemcachedRequest.SetCommand(key: key, value: buffer)
+            var flags: MemcachedFlags?
+
+            flags = MemcachedFlags()
+            flags?.timeToLive = timeToLive
+
+            let command = MemcachedRequest.SetCommand(key: key, value: buffer, flags: flags)
             let request = MemcachedRequest.set(command)
 
-            _ = try await withCheckedThrowingContinuation { continuation in
-                switch requestContinuation.yield((request, continuation)) {
-                case .enqueued:
-                    break
-                case .dropped, .terminated:
-                    continuation.resume(throwing: MemcachedConnectionError.connectionShutdown)
-                default:
-                    break
-                }
-            }.value
+            _ = try await self.sendRequest(request)
 
         case .finished:
             throw MemcachedConnectionError.connectionShutdown

Sources/SwiftMemcache/MemcachedFlags.swift

@@ -14,17 +14,32 @@
 
 /// Struct representing the flags of a Memcached command.
 ///
-/// Flags for the 'mg' (meta get) command are represented in this struct.
-/// Currently, only the 'v' flag for the meta get command is supported,
-/// which dictates whether the item value should be returned in the data block.
+/// Flags for the 'mg' (meta get) and 'ms' (meta set) commands are represented in this struct.
+/// The 'v' flag for the meta get command dictates whether the item value should be returned in the data block.
+/// The 'T' flag is used for both the meta get and meta set commands to specify the Time-To-Live (TTL) for an item.
+/// The 't' flag for the meta get command indicates whether the Time-To-Live (TTL) for the item should be returned.
 struct MemcachedFlags {
     /// Flag 'v' for the 'mg' (meta get) command.
     ///
     /// If true, the item value is returned in the data block.
     /// If false, the data block for the 'mg' response is optional, and the response code changes from "HD" to "VA <size>".
     var shouldReturnValue: Bool?
 
+    /// Flag 'T' for the 'mg' (meta get) and 'ms' (meta set) commands.
+    ///
+    /// Represents the Time-To-Live (TTL) for an item, in seconds.
+    /// If set, the item is considered to be expired after this number of seconds.
+    var timeToLive: TimeToLive?
+
     init() {}
 }
 
+/// Enum representing the Time-To-Live (TTL) of a Memcached value.
+public enum TimeToLive: Equatable, Hashable {
+    /// The value should never expire.
+    case indefinitely
+    /// The value should expire after a specified time.
+    case expiresAt(ContinuousClock.Instant)
+}
+
 extension MemcachedFlags: Hashable {}

Sources/SwiftMemcache/MemcachedRequest.swift

@@ -13,11 +13,11 @@
 //===----------------------------------------------------------------------===//
 
 import NIOCore
-
 enum MemcachedRequest {
     struct SetCommand {
         let key: String
         var value: ByteBuffer
+        var flags: MemcachedFlags?
     }
 
     struct GetCommand {

Sources/SwiftMemcache/MemcachedRequestEncoder.swift

@@ -34,6 +34,11 @@ struct MemcachedRequestEncoder: MessageToByteEncoder {
             let length = command.value.readableBytes
             out.writeIntegerAsASCII(length)
 
+            // write flags if there are any
+            if let flags = command.flags {
+                out.writeMemcachedFlags(flags: flags)
+            }
+
             // write separator
             out.writeInteger(UInt8.carriageReturn)
             out.writeInteger(UInt8.newline)

Sources/SwiftMemcache/MemcachedResponse.swift

@@ -21,6 +21,7 @@ struct MemcachedResponse {
         case EX
         case NF
         case VA
+        case EN
 
         init(_ bytes: UInt16) {
             switch bytes {
@@ -34,6 +35,8 @@ struct MemcachedResponse {
                 self = .NF
             case 0x5641:
                 self = .VA
+            case 0x454E:
+                self = .EN
             default:
                 preconditionFailure("Unrecognized response code.")
             }

Sources/SwiftMemcache/MemcachedResponseDecoder.swift

@@ -134,7 +134,7 @@ struct MemcachedResponseDecoder: NIOSingleStepByteToMessageDecoder {
                     buffer.moveReaderIndex(forwardBy: 1)
                 }
 
-                guard let dataLength = buffer.readIntegerFromASCII() else {
+                guard let dataLength: UInt64 = buffer.readIntegerFromASCII() else {
                     throw MemcachedDecoderError.unexpectedCharacter(buffer.readableBytesView[buffer.readerIndex])
                 }