fix: merge with main and re-add serialization parameters

Resolved merge conflicts with PR #208 (SanitizationStrategy) by:
- Adopting new SanitizationStrategy infrastructure from main
- Re-adding key, collection, and version parameters to serialization
- Updating all 12 store implementations to pass metadata
- Running codegen to generate sync versions

Changes:
- SerializationAdapter.dump_dict() and dump_json() now accept key, collection, version
- All async stores updated to pass key/collection to serialization
- All sync stores regenerated via codegen
- Elasticsearch mapping includes version field

This preserves both PR #208's sanitization improvements and our PR #204's
enumeration support for stores that sanitize/hash keys.

Co-authored-by: William Easton <strawgate@users.noreply.github.com>

Author: github-actions[bot]

key-value/key-value-aio/src/key_value/aio/stores/elasticsearch/store.py

@@ -7,11 +7,12 @@
 from elastic_transport import SerializationError as ElasticsearchSerializationError
 from key_value.shared.errors import DeserializationError, SerializationError
 from key_value.shared.utils.managed_entry import ManagedEntry
+from key_value.shared.utils.sanitization import AlwaysHashStrategy, HashFragmentMode, HybridSanitizationStrategy
 from key_value.shared.utils.sanitize import (
     ALPHANUMERIC_CHARACTERS,
     LOWERCASE_ALPHABET,
     NUMBERS,
-    sanitize_string,
+    UPPERCASE_ALPHABET,
 )
 from key_value.shared.utils.serialization import SerializationAdapter
 from key_value.shared.utils.time_to_live import now_as_epoch
@@ -148,7 +149,7 @@ class ElasticsearchStore(
 
     _native_storage: bool
 
-    _adapter: SerializationAdapter
+    _serializer: SerializationAdapter
 
     @overload
     def __init__(
@@ -210,12 +211,31 @@ def __init__(
         LessCapableJsonSerializer.install_default_serializer(client=self._client)
         LessCapableNdjsonSerializer.install_serializer(client=self._client)
 
-        self._index_prefix = index_prefix
+        self._index_prefix = index_prefix.lower()
         self._native_storage = native_storage
         self._is_serverless = False
-        self._adapter = ElasticsearchSerializationAdapter(native_storage=native_storage)
 
-        super().__init__(default_collection=default_collection)
+        # We have 240 characters to work with
+        # We need to account for the index prefix and the hyphen.
+        max_index_length = MAX_INDEX_LENGTH - (len(self._index_prefix) + 1)
+
+        self._serializer = ElasticsearchSerializationAdapter(native_storage=native_storage)
+
+        # We allow uppercase through the sanitizer so we can lowercase them instead of them
+        # all turning into underscores.
+        collection_sanitization = HybridSanitizationStrategy(
+            replacement_character="_",
+            max_length=max_index_length,
+            allowed_characters=UPPERCASE_ALPHABET + ALLOWED_INDEX_CHARACTERS,
+            hash_fragment_mode=HashFragmentMode.ALWAYS,
+        )
+        key_sanitization = AlwaysHashStrategy()
+
+        super().__init__(
+            default_collection=default_collection,
+            collection_sanitization_strategy=collection_sanitization,
+            key_sanitization_strategy=key_sanitization,
+        )
 
     @override
     async def _setup(self) -> None:
@@ -225,32 +245,22 @@ async def _setup(self) -> None:
 
     @override
     async def _setup_collection(self, *, collection: str) -> None:
-        index_name = self._sanitize_index_name(collection=collection)
+        index_name = self._get_index_name(collection=collection)
 
         if await self._client.options(ignore_status=404).indices.exists(index=index_name):
             return
 
         _ = await self._client.options(ignore_status=404).indices.create(index=index_name, mappings=DEFAULT_MAPPING, settings={})
 
-    def _sanitize_index_name(self, collection: str) -> str:
-        return sanitize_string(
-            value=self._index_prefix + "-" + collection,
-            replacement_character="_",
-            max_length=MAX_INDEX_LENGTH,
-            allowed_characters=ALLOWED_INDEX_CHARACTERS,
-        )
+    def _get_index_name(self, collection: str) -> str:
+        return self._index_prefix + "-" + self._sanitize_collection(collection=collection).lower()
 
-    def _sanitize_document_id(self, key: str) -> str:
-        return sanitize_string(
-            value=key,
-            replacement_character="_",
-            max_length=MAX_KEY_LENGTH,
-            allowed_characters=ALLOWED_KEY_CHARACTERS,
-        )
+    def _get_document_id(self, key: str) -> str:
+        return self._sanitize_key(key=key)
 
     def _get_destination(self, *, collection: str, key: str) -> tuple[str, str]:
-        index_name: str = self._sanitize_index_name(collection=collection)
-        document_id: str = self._sanitize_document_id(key=key)
+        index_name: str = self._get_index_name(collection=collection)
+        document_id: str = self._get_document_id(key=key)
 
         return index_name, document_id
 
@@ -266,7 +276,7 @@ async def _get_managed_entry(self, *, key: str, collection: str) -> ManagedEntry
             return None
 
         try:
-            return self._adapter.load_dict(data=source)
+            return self._serializer.load_dict(data=source)
         except DeserializationError:
             return None
 
@@ -276,8 +286,8 @@ async def _get_managed_entries(self, *, collection: str, keys: Sequence[str]) ->
             return []
 
         # Use mget for efficient batch retrieval
-        index_name = self._sanitize_index_name(collection=collection)
-        document_ids = [self._sanitize_document_id(key=key) for key in keys]
+        index_name = self._get_index_name(collection=collection)
+        document_ids = [self._get_document_id(key=key) for key in keys]
         docs = [{"_id": document_id} for document_id in document_ids]
 
         elasticsearch_response = await self._client.options(ignore_status=404).mget(index=index_name, docs=docs)
@@ -299,7 +309,7 @@ async def _get_managed_entries(self, *, collection: str, keys: Sequence[str]) ->
                 continue
 
             try:
-                entries_by_id[doc_id] = self._adapter.load_dict(data=source)
+                entries_by_id[doc_id] = self._serializer.load_dict(data=source)
             except DeserializationError as e:
                 logger.error(
                     "Failed to deserialize Elasticsearch document in batch operation",
@@ -327,10 +337,10 @@ async def _put_managed_entry(
         collection: str,
         managed_entry: ManagedEntry,
     ) -> None:
-        index_name: str = self._sanitize_index_name(collection=collection)
-        document_id: str = self._sanitize_document_id(key=key)
+        index_name: str = self._get_index_name(collection=collection)
+        document_id: str = self._get_document_id(key=key)
 
-        document: dict[str, Any] = self._adapter.dump_dict(entry=managed_entry, key=key, collection=collection)
+        document: dict[str, Any] = self._serializer.dump_dict(entry=managed_entry, key=key, collection=collection)
 
         try:
             _ = await self._client.index(
@@ -361,14 +371,14 @@ async def _put_managed_entries(
 
         operations: list[dict[str, Any]] = []
 
-        index_name: str = self._sanitize_index_name(collection=collection)
+        index_name: str = self._get_index_name(collection=collection)
 
         for key, managed_entry in zip(keys, managed_entries, strict=True):
-            document_id: str = self._sanitize_document_id(key=key)
+            document_id: str = self._get_document_id(key=key)
 
             index_action: dict[str, Any] = new_bulk_action(action="index", index=index_name, document_id=document_id)
 
-            document: dict[str, Any] = self._adapter.dump_dict(entry=managed_entry, key=key, collection=collection)
+            document: dict[str, Any] = self._serializer.dump_dict(entry=managed_entry, key=key, collection=collection)
 
             operations.extend([index_action, document])
 
@@ -382,8 +392,8 @@ async def _put_managed_entries(
 
     @override
     async def _delete_managed_entry(self, *, key: str, collection: str) -> bool:
-        index_name: str = self._sanitize_index_name(collection=collection)
-        document_id: str = self._sanitize_document_id(key=key)
+        index_name: str = self._get_index_name(collection=collection)
+        document_id: str = self._get_document_id(key=key)
 
         elasticsearch_response: ObjectApiResponse[Any] = await self._client.options(ignore_status=404).delete(
             index=index_name, id=document_id
@@ -431,7 +441,7 @@ async def _get_collection_keys(self, *, collection: str, limit: int | None = Non
         limit = min(limit or DEFAULT_PAGE_SIZE, PAGE_LIMIT)
 
         result: ObjectApiResponse[Any] = await self._client.options(ignore_status=404).search(
-            index=self._sanitize_index_name(collection=collection),
+            index=self._get_index_name(collection=collection),
             fields=[{"key": None}],
             body={
                 "query": {
@@ -447,7 +457,15 @@ async def _get_collection_keys(self, *, collection: str, limit: int | None = Non
         if not (hits := get_hits_from_response(response=result)):
             return []
 
-        return [key for hit in hits if (key := get_first_value_from_field_in_hit(hit=hit, field="key", value_type=str))]
+        all_keys: list[str] = []
+
+        for hit in hits:
+            if not (key := get_first_value_from_field_in_hit(hit=hit, field="key", value_type=str)):
+                continue
+
+            all_keys.append(key)
+
+        return all_keys
 
     @override
     async def _get_collection_names(self, *, limit: int | None = None) -> list[str]:
@@ -478,7 +496,7 @@ async def _get_collection_names(self, *, limit: int | None = None) -> list[str]:
     @override
     async def _delete_collection(self, *, collection: str) -> bool:
         result: ObjectApiResponse[Any] = await self._client.options(ignore_status=404).delete_by_query(
-            index=self._sanitize_index_name(collection=collection),
+            index=self._get_index_name(collection=collection),
             body={
                 "query": {
                     "term": {

key-value/key-value-aio/src/key_value/aio/stores/keyring/store.py

@@ -2,7 +2,8 @@
 
 from key_value.shared.utils.compound import compound_key
 from key_value.shared.utils.managed_entry import ManagedEntry
-from key_value.shared.utils.sanitize import ALPHANUMERIC_CHARACTERS, sanitize_string
+from key_value.shared.utils.sanitization import HybridSanitizationStrategy
+from key_value.shared.utils.sanitize import ALPHANUMERIC_CHARACTERS
 from typing_extensions import override
 
 from key_value.aio.stores.base import BaseStore
@@ -15,11 +16,9 @@
     raise ImportError(msg) from e
 
 DEFAULT_KEYCHAIN_SERVICE = "py-key-value"
-MAX_KEY_LENGTH = 256
-ALLOWED_KEY_CHARACTERS: str = ALPHANUMERIC_CHARACTERS
 
-MAX_COLLECTION_LENGTH = 256
-ALLOWED_COLLECTION_CHARACTERS: str = ALPHANUMERIC_CHARACTERS
+MAX_KEY_COLLECTION_LENGTH = 256
+ALLOWED_KEY_COLLECTION_CHARACTERS: str = ALPHANUMERIC_CHARACTERS
 
 
 class KeyringStore(BaseStore):
@@ -48,25 +47,19 @@ def __init__(
         """
         self._service_name = service_name
 
-        super().__init__(default_collection=default_collection)
-
-    def _sanitize_collection_name(self, collection: str) -> str:
-        return sanitize_string(
-            value=collection,
-            max_length=MAX_COLLECTION_LENGTH,
-            allowed_characters=ALLOWED_COLLECTION_CHARACTERS,
+        sanitization_strategy = HybridSanitizationStrategy(
+            replacement_character="_", max_length=MAX_KEY_COLLECTION_LENGTH, allowed_characters=ALLOWED_KEY_COLLECTION_CHARACTERS
         )
 
-    def _sanitize_key(self, key: str) -> str:
-        return sanitize_string(
-            value=key,
-            max_length=MAX_KEY_LENGTH,
-            allowed_characters=ALLOWED_KEY_CHARACTERS,
+        super().__init__(
+            default_collection=default_collection,
+            collection_sanitization_strategy=sanitization_strategy,
+            key_sanitization_strategy=sanitization_strategy,
         )
 
     @override
     async def _get_managed_entry(self, *, key: str, collection: str) -> ManagedEntry | None:
-        sanitized_collection = self._sanitize_collection_name(collection=collection)
+        sanitized_collection = self._sanitize_collection(collection=collection)
         sanitized_key = self._sanitize_key(key=key)
 
         combo_key: str = compound_key(collection=sanitized_collection, key=sanitized_key)
@@ -83,7 +76,7 @@ async def _get_managed_entry(self, *, key: str, collection: str) -> ManagedEntry
 
     @override
     async def _put_managed_entry(self, *, key: str, collection: str, managed_entry: ManagedEntry) -> None:
-        sanitized_collection = self._sanitize_collection_name(collection=collection)
+        sanitized_collection = self._sanitize_collection(collection=collection)
         sanitized_key = self._sanitize_key(key=key)
 
         combo_key: str = compound_key(collection=sanitized_collection, key=sanitized_key)
@@ -94,7 +87,7 @@ async def _put_managed_entry(self, *, key: str, collection: str, managed_entry:
 
     @override
     async def _delete_managed_entry(self, *, key: str, collection: str) -> bool:
-        sanitized_collection = self._sanitize_collection_name(collection=collection)
+        sanitized_collection = self._sanitize_collection(collection=collection)
         sanitized_key = self._sanitize_key(key=key)
 
         combo_key: str = compound_key(collection=sanitized_collection, key=sanitized_key)

key-value/key-value-aio/src/key_value/aio/stores/memcached/store.py

@@ -4,6 +4,7 @@
 
 from key_value.shared.utils.compound import compound_key
 from key_value.shared.utils.managed_entry import ManagedEntry
+from key_value.shared.utils.sanitization import HashExcessLengthStrategy
 from typing_extensions import override
 
 from key_value.aio.stores.base import BaseContextManagerStore, BaseDestroyStore, BaseStore
@@ -46,7 +47,12 @@ def __init__(
         """
         self._client = client or Client(host=host, port=port)
 
-        super().__init__(default_collection=default_collection)
+        sanitization_strategy = HashExcessLengthStrategy(max_length=MAX_KEY_LENGTH)
+
+        super().__init__(
+            default_collection=default_collection,
+            key_sanitization_strategy=sanitization_strategy,
+        )
 
     def sanitize_key(self, key: str) -> str:
         if len(key) > MAX_KEY_LENGTH: