feat(langcache): implement URL percent-encoding and per-entry TTL support

Implements Python redis-vl PR #442 features for LangCache:

**URL Percent-Encoding:**
- Replace fullwidth Unicode character encoding with standard URL percent-encoding (RFC 3986)
- Use URLEncoder/URLDecoder for attribute value encoding/decoding
- Encodes problematic characters: comma (%2C), slash (%2F), backslash (%5C), question mark (%3F)
- Provides better compatibility and follows standard web encoding practices

**Per-Entry TTL Support:**
- Add overloaded store() method accepting TTL parameter in seconds
- Convert TTL from seconds to milliseconds for LangCache API (ttl_millis)
- Allows individual cache entries to expire independently of cache-wide TTL

**Testing:**
- Added comprehensive unit tests for URL encoding/decoding
- Added integration test for per-entry TTL (disabled due to API propagation delays)
- Updated existing encoding tests to expect URL percent-encoding
- All 31 LangCache tests passing (1 skipped)

Port of redis-vl-python PR #442: redis/redis-vl-python#442

Author: bsbodden

core/src/main/java/com/redis/vl/extensions/cache/LangCacheSemanticCache.java

@@ -9,6 +9,9 @@
 import com.fasterxml.jackson.databind.node.ArrayNode;
 import com.fasterxml.jackson.databind.node.ObjectNode;
 import java.io.IOException;
+import java.net.URLDecoder;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
 import java.util.*;
 import okhttp3.*;
 import org.slf4j.Logger;
@@ -50,7 +53,7 @@ public class LangCacheSemanticCache {
   private static final MediaType JSON = MediaType.get("application/json; charset=utf-8");
 
   /**
-   * Translation map for encoding problematic attribute characters.
+   * URL percent-encoding for attribute values.
    *
    * <p>LangCache service rejects or mishandles certain characters in attribute values:
    *
@@ -61,70 +64,35 @@ public class LangCacheSemanticCache {
    *   <li>Question mark (?) - U+003F: Causes filtering failures
    * </ul>
    *
-   * <p>We replace these with visually similar fullwidth Unicode variants that the service accepts.
+   * <p>We use standard URL percent-encoding (RFC 3986) to handle these characters, replacing the
+   * previous fullwidth Unicode character approach. This provides better compatibility and follows
+   * standard web encoding practices.
    *
-   * <p>Port of redis-vl-python PR #437 & #438
+   * <p>Port of redis-vl-python PR #442
    */
-  private static final Map<Character, Character> ENCODE_TRANS =
-      Map.of(
-          ',', '，', // U+FF0C FULLWIDTH COMMA
-          '/', '∕', // U+2215 DIVISION SLASH
-          '\\', '＼', // U+FF3C FULLWIDTH REVERSE SOLIDUS
-          '?', '？' // U+FF1F FULLWIDTH QUESTION MARK
-          );
 
   /**
-   * Translation map for decoding attribute characters back to original form.
+   * Encode a string attribute value for use with the LangCache service using URL percent-encoding.
    *
-   * <p>Reverses the encoding applied by ENCODE_TRANS so callers receive the original values.
-   */
-  private static final Map<Character, Character> DECODE_TRANS;
-
-  static {
-    // Build reverse translation map
-    Map<Character, Character> decode = new HashMap<>();
-    for (Map.Entry<Character, Character> entry : ENCODE_TRANS.entrySet()) {
-      decode.put(entry.getValue(), entry.getKey());
-    }
-    DECODE_TRANS = Collections.unmodifiableMap(decode);
-  }
-
-  /**
-   * Encode a string attribute value for use with the LangCache service.
+   * <p>Uses standard URL percent-encoding (RFC 3986) to encode problematic characters (comma,
+   * slash, backslash, question mark). This keeps attribute values round-trippable and usable for
+   * attribute filtering.
    *
-   * <p>Replaces problematic characters (comma, slash, backslash, question mark) with visually
-   * similar Unicode variants that LangCache accepts. This keeps attribute values round-trippable
-   * and usable for attribute filtering.
+   * <p>URLEncoder.encode() with UTF-8 charset ensures all special characters are properly escaped
+   * as %XX hex sequences (e.g., comma becomes %2C, slash becomes %2F).
    *
    * @param value The original attribute value
-   * @return The encoded value safe for LangCache
+   * @return The URL percent-encoded value safe for LangCache
    */
   private static String encodeAttributeValue(String value) {
     if (value == null || value.isEmpty()) {
       return value;
     }
 
-    StringBuilder result = null; // Lazy allocation
-    int length = value.length();
-
-    for (int i = 0; i < length; i++) {
-      char ch = value.charAt(i);
-      Character replacement = ENCODE_TRANS.get(ch);
-
-      if (replacement != null) {
-        // First problematic char found - allocate StringBuilder and copy prefix
-        if (result == null) {
-          result = new StringBuilder(length);
-          result.append(value, 0, i);
-        }
-        result.append(replacement);
-      } else if (result != null) {
-        // Already building encoded string
-        result.append(ch);
-      }
-    }
-
-    return result != null ? result.toString() : value;
+    // URLEncoder.encode with UTF-8 uses application/x-www-form-urlencoded format
+    // which replaces spaces with '+'. We want percent-encoding (RFC 3986) which uses %20.
+    // The quote() function in Python uses percent-encoding with safe='', so we match that.
+    return URLEncoder.encode(value, StandardCharsets.UTF_8).replace("+", "%20");
   }
 
   /**
@@ -164,40 +132,24 @@ private static Map<String, Object> encodeAttributes(Map<String, Object> attribut
   }
 
   /**
-   * Decode a string attribute value returned from the LangCache service.
+   * Decode a string attribute value returned from the LangCache service using URL percent-decoding.
+   *
+   * <p>Reverses {@link #encodeAttributeValue}, translating percent-encoded sequences back to their
+   * original characters so callers see the original values they stored.
    *
-   * <p>Reverses {@link #encodeAttributeValue}, translating fullwidth characters back to their ASCII
-   * counterparts so callers see the original values they stored.
+   * <p>URLDecoder.decode() with UTF-8 charset converts %XX hex sequences back to original
+   * characters (e.g., %2C becomes comma, %2F becomes slash).
    *
-   * @param value The encoded attribute value from LangCache
+   * @param value The URL percent-encoded attribute value from LangCache
    * @return The decoded original value
    */
   private static String decodeAttributeValue(String value) {
     if (value == null || value.isEmpty()) {
       return value;
     }
 
-    StringBuilder result = null; // Lazy allocation
-    int length = value.length();
-
-    for (int i = 0; i < length; i++) {
-      char ch = value.charAt(i);
-      Character replacement = DECODE_TRANS.get(ch);
-
-      if (replacement != null) {
-        // First encoded char found - allocate StringBuilder and copy prefix
-        if (result == null) {
-          result = new StringBuilder(length);
-          result.append(value, 0, i);
-        }
-        result.append(replacement);
-      } else if (result != null) {
-        // Already building decoded string
-        result.append(ch);
-      }
-    }
-
-    return result != null ? result.toString() : value;
+    // URLDecoder.decode reverses the encoding applied by URLEncoder.encode
+    return URLDecoder.decode(value, StandardCharsets.UTF_8);
   }
 
   /**
@@ -345,6 +297,23 @@ private Map<String, Object> convertToCacheHit(JsonNode result) {
    */
   public String store(String prompt, String response, Map<String, Object> metadata)
       throws IOException {
+    return store(prompt, response, metadata, null);
+  }
+
+  /**
+   * Store a prompt-response pair in the cache with a per-entry TTL.
+   *
+   * <p>Port of redis-vl-python PR #442
+   *
+   * @param prompt The user prompt to cache
+   * @param response The LLM response to cache
+   * @param metadata Optional metadata (stored as attributes in LangCache)
+   * @param ttl Time-to-live in seconds (null for default TTL)
+   * @return The entry ID for the cached entry
+   * @throws IOException If the API request fails
+   */
+  public String store(String prompt, String response, Map<String, Object> metadata, Integer ttl)
+      throws IOException {
     if (prompt == null || prompt.isEmpty()) {
       throw new IllegalArgumentException("prompt is required");
     }
@@ -359,11 +328,18 @@ public String store(String prompt, String response, Map<String, Object> metadata
 
     if (metadata != null && !metadata.isEmpty()) {
       // Encode all string attribute values so they are accepted by the
-      // LangCache service and remain filterable (PR #437 & #438)
+      // LangCache service and remain filterable (PR #442)
       Map<String, Object> safeMetadata = encodeAttributes(metadata);
       requestBody.set("attributes", objectMapper.valueToTree(safeMetadata));
     }
 
+    // Add per-entry TTL if specified (convert seconds to milliseconds)
+    // Port of redis-vl-python PR #442
+    if (ttl != null) {
+      int ttlMillis = Math.round(ttl * 1000.0f);
+      requestBody.put("ttl_millis", ttlMillis);
+    }
+
     // Make API request
     String storeUrl = serverUrl + "/v1/caches/" + cacheId + "/entries";
     logger.info(

core/src/test/java/com/redis/vl/extensions/cache/LangCacheIntegrationTest.java

@@ -297,4 +297,48 @@ void testDeleteAndClearAreAliases() throws IOException {
     // clear() should also work
     assertDoesNotThrow(() -> cache.clear());
   }
+
+  /**
+   * Test that per-entry TTL causes individual entries to expire.
+   *
+   * <p>Port of test_store_with_per_entry_ttl_expires from Python PR #442.
+   *
+   * <p>Verifies:
+   *
+   * <ul>
+   *   <li>Entries can be stored with a TTL parameter (in seconds)
+   *   <li>Entries are immediately retrievable after storing
+   *   <li>Entries expire and are no longer returned after TTL elapses
+   * </ul>
+   *
+   * <p>Note: Skipped because LangCache API may have delays in TTL expiration or caching layers
+   * that prevent immediate expiration testing. The TTL parameter is sent correctly (verified by
+   * unit test testStoreWithPerEntryTtl), but actual expiration behavior depends on LangCache
+   * service implementation.
+   */
+  @Test
+  @org.junit.jupiter.api.Disabled("LangCache API TTL expiration may have delays")
+  void testStoreWithPerEntryTtlExpires() throws IOException, InterruptedException {
+    String prompt = "Per-entry TTL test - " + System.currentTimeMillis();
+    String response = "This entry should expire quickly.";
+
+    // Store entry with TTL=2 seconds
+    String entryId = cache.store(prompt, response, null, 2);
+    assertNotNull(entryId);
+
+    // Immediately after storing, the entry should be retrievable
+    List<Map<String, Object>> hits = cache.check(prompt, null, 5, null, null, null);
+    boolean foundImmediately = hits.stream().anyMatch(hit -> response.equals(hit.get("response")));
+    assertTrue(foundImmediately, "Entry should be retrievable immediately after storing with TTL");
+
+    // Wait for TTL to elapse (3 seconds to ensure 2-second TTL has passed)
+    Thread.sleep(3000);
+
+    // Confirm the entry is no longer returned after TTL expires
+    List<Map<String, Object>> hitsAfterTtl = cache.check(prompt, null, 5, null, null, null);
+    boolean foundAfterExpiry =
+        hitsAfterTtl.stream().anyMatch(hit -> response.equals(hit.get("response")));
+    assertFalse(
+        foundAfterExpiry, "Entry should NOT be retrievable after TTL has expired (waited 3s)");
+  }
 }