fix(s3): resolve vcon path via lookup pointer to support date-based key structure (#145)

S3 stores vcons under YYYY/MM/DD/<uuid>.vcon but the get/delete interface
only receives a UUID. Introduce a lookup pointer file at lookup/<uuid>.txt
(written on save) that contains the date prefix, allowing get and delete to
resolve the full key without any schema changes.

- Add _date_prefix() helper to centralise YYYY/MM/DD formatting
- Add _build_lookup_key() to build the lookup/<uuid>.txt path
- Update _build_s3_key() to accept a pre-computed date_path instead of created_at
- save(): write lookup pointer alongside the vcon object (2 puts total)
- get(): fetch lookup pointer to resolve date path, then fetch vcon (2 gets total)
- delete(): resolve via lookup pointer, delete both vcon and lookup objects
- Add .txt extension to lookup files for easy viewing in AWS Console
- 43 tests covering all helpers, save, get, and delete paths

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: pavanputhra

server/storage/s3/__init__.py

@@ -36,23 +36,40 @@ def _create_s3_client(opts: dict):
     return boto3.client("s3", **client_kwargs)
 
 
-def _build_s3_key(vcon_uuid: str, created_at: Optional[str] = None, s3_path: Optional[str] = None) -> str:
-    """Build the S3 object key for a vCon with date-based folder structure.
-    
+def _date_prefix(created_at: str) -> str:
+    """Return the YYYY/MM/DD folder prefix derived from an ISO timestamp."""
+    return datetime.fromisoformat(created_at).strftime("%Y/%m/%d")
+
+
+def _build_lookup_key(vcon_uuid: str, s3_path: Optional[str] = None) -> str:
+    """Build the S3 key for the lookup pointer file.
+
     Args:
         vcon_uuid: The vCon UUID
-        created_at: ISO format timestamp from the vCon's created_at field.
-                    If provided, creates date-based folder structure (YYYY/MM/DD).
         s3_path: Optional prefix path in the S3 bucket
-    
+
+    Returns:
+        S3 key in format: [s3_path/]lookup/<uuid>
+    """
+    key = f"lookup/{vcon_uuid}.txt"
+    if not s3_path:
+        return key
+    return f"{s3_path.rstrip('/')}/{key}"
+
+
+def _build_s3_key(vcon_uuid: str, date_path: Optional[str] = None, s3_path: Optional[str] = None) -> str:
+    """Build the S3 object key for a vCon.
+
+    Args:
+        vcon_uuid: The vCon UUID
+        date_path: Pre-computed YYYY/MM/DD prefix (from _date_prefix).
+                   If provided, creates date-based folder structure.
+        s3_path: Optional prefix path in the S3 bucket
+
     Returns:
         S3 key in format: [s3_path/][YYYY/MM/DD/]uuid.vcon
     """
-    if created_at:
-        timestamp = datetime.fromisoformat(created_at).strftime("%Y/%m/%d")
-        key = f"{timestamp}/{vcon_uuid}.vcon"
-    else:
-        key = f"{vcon_uuid}.vcon"
+    key = f"{date_path}/{vcon_uuid}.vcon" if date_path else f"{vcon_uuid}.vcon"
     if not s3_path:
         return key
     return f"{s3_path.rstrip('/')}/{key}"
@@ -68,10 +85,16 @@ def save(
         vcon = vcon_redis.get_vcon(vcon_uuid)
         s3 = _create_s3_client(opts)
 
-        destination_directory = _build_s3_key(vcon_uuid, vcon.created_at, opts.get("s3_path"))
+        date_path = _date_prefix(vcon.created_at)
+        destination_directory = _build_s3_key(vcon_uuid, date_path, opts.get("s3_path"))
         s3.put_object(
             Bucket=opts["aws_bucket"], Key=destination_directory, Body=vcon.dumps()
         )
+
+        lookup_key = _build_lookup_key(vcon_uuid, opts.get("s3_path"))
+        s3.put_object(
+            Bucket=opts["aws_bucket"], Key=lookup_key, Body=date_path.encode()
+        )
         logger.info(f"Finished S3 storage for vCon: {vcon_uuid}")
     except Exception as e:
         logger.error(
@@ -80,15 +103,49 @@ def save(
         raise e
 
 def get(vcon_uuid: str, opts=default_options) -> Optional[dict]:
-    """Get a vCon from S3 by UUID."""
+    """Get a vCon from S3 by UUID.
+
+    Uses a lookup pointer file (lookup/<uuid>) to resolve the date-based path
+    before fetching the actual vCon object.
+    """
     try:
         s3 = _create_s3_client(opts)
 
-        key = _build_s3_key(vcon_uuid, s3_path=opts.get("s3_path"))
+        lookup_key = _build_lookup_key(vcon_uuid, opts.get("s3_path"))
+        lookup_response = s3.get_object(Bucket=opts["aws_bucket"], Key=lookup_key)
+        date_path = lookup_response['Body'].read().decode('utf-8').strip()
+
+        key = _build_s3_key(vcon_uuid, date_path, opts.get("s3_path"))
 
         response = s3.get_object(Bucket=opts["aws_bucket"], Key=key)
         return json.loads(response['Body'].read().decode('utf-8'))
-        
+
     except Exception as e:
         logger.error(f"s3 storage plugin: failed to get vCon: {vcon_uuid}, error: {e}")
         return None
+
+
+def delete(vcon_uuid: str, opts=default_options) -> bool:
+    """Delete a vCon and its lookup pointer from S3.
+
+    Returns True if deleted, False if not found or on error.
+    """
+    try:
+        s3 = _create_s3_client(opts)
+        bucket = opts["aws_bucket"]
+        s3_path = opts.get("s3_path")
+
+        lookup_key = _build_lookup_key(vcon_uuid, s3_path)
+        lookup_response = s3.get_object(Bucket=bucket, Key=lookup_key)
+        date_path = lookup_response['Body'].read().decode('utf-8').strip()
+
+        vcon_key = _build_s3_key(vcon_uuid, date_path, s3_path)
+        s3.delete_object(Bucket=bucket, Key=vcon_key)
+        s3.delete_object(Bucket=bucket, Key=lookup_key)
+
+        logger.info(f"s3 storage plugin: deleted vCon {vcon_uuid}")
+        return True
+
+    except Exception as e:
+        logger.error(f"s3 storage plugin: failed to delete vCon: {vcon_uuid}, error: {e}")
+        return False