fix: security hardening, correctness fixes and modernization

.github/wordlist.txt

@@ -1,24 +1,27 @@
 aspell
-async
 Async
+async
 Codecov
-falkordb
+Cypher
 FalkorDB
+falkordb
 faq
 Formatter
+hostname
 html
 https
 isort
 linter
 mypy
 openCypher
 Pre
+py
 pycodestyle
 Pyflakes
-py
 pyspelling
 pytest
 sexualized
 socio
+TLS
 wordlist
 www

AGENTS.md

@@ -63,11 +63,12 @@ falkordb/
   cluster.py         # Redis Cluster support
   sentinel.py        # Redis Sentinel support
   _version.py        # Package version via importlib.metadata
+  py.typed           # PEP 561 marker — ships inline type information
   asyncio/           # Async mirror (see below)
-  lite/              # Lightweight variant
 tests/
   test_*.py          # Sync tests
   test_async_*.py    # Async tests (mirror sync tests)
+  plan_utils.py      # Helpers for version-agnostic execution-plan assertions
 ```
 
 ## Architecture Patterns
@@ -76,12 +77,16 @@ tests/
 Every sync class in `falkordb/` has an async counterpart in `falkordb/asyncio/`:
 | Sync | Async |
 |------|-------|
-| `falkordb.py` → `FalkorDB` | `asyncio/falkordb.py` → `AsyncFalkorDB` |
+| `falkordb.py` → `FalkorDB` | `asyncio/falkordb.py` → `FalkorDB` (imported as `AsyncFalkorDB`) |
 | `graph.py` → `Graph` | `asyncio/graph.py` → `AsyncGraph` |
 | `query_result.py` → `QueryResult` | `asyncio/query_result.py` → `AsyncQueryResult` |
 
 When modifying sync code, always check if the async counterpart needs the same change.
 
+Known parity gaps (not yet implemented on the async side): `sentinel.py` has no
+async counterpart, and `asyncio/falkordb.py` accepts fewer constructor
+parameters than the sync client.
+
 ### Redis Integration
 - `FalkorDB` wraps a `redis.Redis` (or `redis.asyncio.Redis`) connection
 - `Graph` receives the client and delegates commands via `client.execute_command()`

README.md

@@ -105,3 +105,48 @@ async def main():
 if __name__ == "__main__":
     asyncio.run(main())
 ```
+
+### Query Parameters
+
+Always pass user-supplied values as parameters rather than building query
+strings — parameters are serialized safely and cannot inject Cypher.
+
+```python
+g.query("MATCH (p:Person) WHERE p.name = $name RETURN p", {"name": name})
+```
+
+Supported parameter types: `str`, `bytes`, `bool`, `int`, `float`, `Decimal`,
+`None`, `list`, `tuple`, `dict`, `datetime`, `date` and `time`. Any other type
+raises `TypeError` instead of being coerced with `str()`.
+
+### Connection Management
+
+Both clients are context managers and release their connection pool on exit:
+
+```python
+with FalkorDB(host="localhost", port=6379) as db:
+    g = db.select_graph("social")
+    g.query("MATCH (n) RETURN count(n)")
+```
+
+The async client (`from falkordb.asyncio import FalkorDB`) supports the async
+form:
+
+```python
+async with FalkorDB(host="localhost", port=6379) as db:
+    g = db.select_graph("social")
+    await g.query("MATCH (n) RETURN count(n)")
+```
+
+You can also call `db.close()` (or `await db.aclose()`) explicitly.
+
+### TLS
+
+```python
+db = FalkorDB(host="my-instance.falkordb.cloud", port=6379, password="...", ssl=True)
+```
+
+TLS connections verify the server certificate and hostname by default. Set
+`ssl_check_hostname=False` only when connecting to an instance whose
+certificate does not match its hostname.
+

falkordb/asyncio/cluster.py

@@ -23,6 +23,13 @@ def Is_Cluster(conn: redis.Redis):
     if pool.connection_class is redis.UnixDomainSocketConnection:
         kwargs["unix_socket_path"] = kwargs.pop("path")
 
+    # These carry asyncio-specific objects (awaitable Retry/credential provider
+    # /connect hooks). They are valid parameter *names* on the sync client, so
+    # the signature filter below keeps them, but handing it the asyncio objects
+    # makes it return un-awaited coroutines. This probe is a single INFO call.
+    for async_only in ("retry", "credential_provider", "redis_connect_func"):
+        kwargs.pop(async_only, None)
+
     # Keep only the parameters the synchronous constructor actually accepts.
     # redis-py stores internal state in ``connection_kwargs`` that is not part
     # of the ``Redis.__init__`` signature — redis 8.1.0 added ``himport_registry``
@@ -32,7 +39,11 @@ def Is_Cluster(conn: redis.Redis):
 
     # Create a synchronous Redis client with the same parameters
     # as the connection pool just to keep Is_Cluster synchronous
-    info = sync_redis.Redis(**kwargs).info(section="server")
+    probe = sync_redis.Redis(**kwargs)
+    try:
+        info = probe.info(section="server")
+    finally:
+        probe.close()
 
     return "redis_mode" in info and info["redis_mode"] == "cluster"
 
@@ -47,8 +58,11 @@ def Cluster_Conn(
     reinitialize_steps=5,
     read_from_replicas=False,
     address_remap=None,
+    load_balancing_strategy=None,
 ):
-    connection_kwargs = conn.connection_pool.connection_kwargs
+    # copy, popping from the live pool dict would strip host/port/credentials
+    # from a pool the caller may still be using
+    connection_kwargs = dict(conn.connection_pool.connection_kwargs)
     host = connection_kwargs.pop("host")
     port = connection_kwargs.pop("port")
     username = connection_kwargs.pop("username")
@@ -65,6 +79,17 @@ def Cluster_Conn(
             redis_exceptions.ConnectionError,
         ],
     )
+
+    # redis-py deprecated these and warns for every one it receives, only
+    # forward them when the caller actually diverged from the default
+    optional: dict = {}
+    if cluster_error_retry_attempts != 3:
+        optional["cluster_error_retry_attempts"] = cluster_error_retry_attempts
+    if read_from_replicas:
+        optional["read_from_replicas"] = read_from_replicas
+    if load_balancing_strategy is not None:
+        optional["load_balancing_strategy"] = load_balancing_strategy
+
     return RedisCluster(
         host=host,
         port=port,
@@ -76,8 +101,7 @@ def Cluster_Conn(
         retry_on_error=retry_on_error,
         require_full_coverage=require_full_coverage,
         reinitialize_steps=reinitialize_steps,
-        read_from_replicas=read_from_replicas,
         address_remap=address_remap,
         startup_nodes=startup_nodes,
-        cluster_error_retry_attempts=cluster_error_retry_attempts,
+        **optional,
     )

falkordb/asyncio/falkordb.py

@@ -1,4 +1,4 @@
-from typing import List, Optional, Union
+import contextlib
 
 import redis.asyncio as redis  # type: ignore[import-not-found]
 from redis.driver_info import DriverInfo
@@ -57,7 +57,7 @@ def __init__(
         ssl_cert_reqs="required",
         ssl_ca_certs=None,
         ssl_ca_data=None,
-        ssl_check_hostname=False,
+        ssl_check_hostname=True,
         max_connections=None,
         single_connection_client=False,
         health_check_interval=0,
@@ -76,6 +76,7 @@ def __init__(
         reinitialize_steps=5,
         read_from_replicas=False,
         address_remap=None,
+        load_balancing_strategy=None,
     ):
 
         conn = redis.Redis(
@@ -119,12 +120,15 @@ def __init__(
             conn = Cluster_Conn(
                 conn,
                 ssl,
-                cluster_error_retry_attempts,
-                startup_nodes,
-                require_full_coverage,
-                reinitialize_steps,
-                read_from_replicas,
-                address_remap,
+                # keyword arguments, the sync and async helpers do not take the
+                # same positional order
+                cluster_error_retry_attempts=cluster_error_retry_attempts,
+                startup_nodes=startup_nodes,
+                require_full_coverage=require_full_coverage,
+                reinitialize_steps=reinitialize_steps,
+                read_from_replicas=read_from_replicas,
+                address_remap=address_remap,
+                load_balancing_strategy=load_balancing_strategy,
             )
 
         self.connection = conn
@@ -160,7 +164,12 @@ def from_url(cls, url: str, **kwargs) -> "FalkorDB":
         kwargs["decode_responses"] = True
         conn = redis.from_url(url, **kwargs)
 
-        return cls(connection_pool=conn.connection_pool)
+        # carry TLS through, otherwise a cluster topology would be
+        # re-dialed in plaintext by Cluster_Conn
+        pool = conn.connection_pool
+        ssl = pool.connection_class is redis.SSLConnection
+
+        return cls(connection_pool=pool, ssl=ssl)
 
     def select_graph(self, graph_id: str) -> AsyncGraph:
         """
@@ -179,7 +188,7 @@ def select_graph(self, graph_id: str) -> AsyncGraph:
 
         return AsyncGraph(self, graph_id)
 
-    async def list_graphs(self) -> List[str]:
+    async def list_graphs(self) -> list[str]:
         """
         Lists all graph names.
         See: https://docs.falkordb.com/commands/graph.list.html
@@ -191,7 +200,7 @@ async def list_graphs(self) -> List[str]:
 
         return await self.connection.execute_command(LIST_CMD)
 
-    async def config_get(self, name: str) -> Union[int, str]:
+    async def config_get(self, name: str) -> int | str:
         """
         Retrieve a DB level configuration.
         For a list of available configurations see: https://docs.falkordb.com/configuration.html#falkordb-configuration-parameters
@@ -228,11 +237,9 @@ async def aclose(self) -> None:
         Close the underlying connection(s).
         """
 
-        try:
+        # best-effort close, don't raise on Redis errors
+        with contextlib.suppress(RedisError):
             await self.connection.aclose()
-        except RedisError:
-            # best-effort close — don't raise on Redis errors
-            pass
 
     async def __aenter__(self) -> "FalkorDB":
         """Return self to support async with-statement usage."""
@@ -274,7 +281,7 @@ async def udf_load(self, name: str, script: str, replace: bool = False):
         return resp
 
     # GRAPH.UDF LIST [LIBRARYNAME] [WITHCODE]
-    async def udf_list(self, lib: Optional[str] = None, with_code: bool = False):
+    async def udf_list(self, lib: str | None = None, with_code: bool = False):
         """
         List User Defined Function (UDF) libraries.