Add FFI binding for SessionManager C API (#6)

Create ctypes bindings for gopher_auth_session_* functions providing
GopherSessionManager class for per-client session management with
token storage, expiry tracking, and secure ID generation.

New session_manager.py:
- GopherSessionManager with handle-based lifecycle
- store_token(), get_access_token(), get_refresh_token()
- has_valid_token() with 5s buffer, cleanup() for expired sessions
- Static generate_session_id() returns 32-char hex string
- Context manager support

Changes:
- Create GopherSessionManager class
- Add 9 unit tests: store/retrieve, valid/expired, unknown session,
  hex ID, unique IDs, cleanup, destroy lifecycle

Author: RahulHere

gopher_mcp_python/ffi/auth/session_manager.py

@@ -0,0 +1,136 @@
+"""
+GopherSessionManager - FFI wrapper for per-client session management.
+
+Thread-safe session manager with OAuth token storage, expiry tracking,
+and secure session ID generation.
+"""
+
+from ctypes import POINTER, byref, c_bool, c_char_p, c_void_p
+from typing import Optional
+
+from gopher_mcp_python.ffi.auth.loader import get_auth_functions, is_auth_available, load_library
+from gopher_mcp_python.ffi.auth.types import GopherAuthError
+
+
+class GopherSessionManager:
+    """Per-client session manager via native C API."""
+
+    def __init__(self, timeout_seconds: int = 300) -> None:
+        if not is_auth_available():
+            load_library()
+        funcs = get_auth_functions()
+        create = funcs.get("session_manager_create")
+        if not create:
+            raise RuntimeError("Session manager functions not available")
+        self._handle = c_void_p()
+        result = create(byref(self._handle), timeout_seconds)
+        if result != GopherAuthError.SUCCESS:
+            raise RuntimeError(f"Failed to create session manager: error {result}")
+        self._destroyed = False
+
+    def store_token(self, session_id: str, access_token: str,
+                    refresh_token: str, expires_in: int) -> None:
+        self._ensure_not_destroyed()
+        funcs = get_auth_functions()
+        fn = funcs.get("session_store_token")
+        if fn:
+            fn(self._handle, session_id.encode("utf-8"), access_token.encode("utf-8"),
+               refresh_token.encode("utf-8"), expires_in)
+
+    def get_access_token(self, session_id: str) -> Optional[str]:
+        self._ensure_not_destroyed()
+        funcs = get_auth_functions()
+        fn = funcs.get("session_get_access_token")
+        if not fn:
+            return None
+        out = c_char_p()
+        result = fn(self._handle, session_id.encode("utf-8"), byref(out))
+        if result != GopherAuthError.SUCCESS:
+            return None
+        if out.value:
+            val = out.value.decode("utf-8")
+            free = funcs.get("free_string")
+            if free:
+                free(out)
+            return val
+        return None
+
+    def get_refresh_token(self, session_id: str) -> Optional[str]:
+        self._ensure_not_destroyed()
+        funcs = get_auth_functions()
+        fn = funcs.get("session_get_refresh_token")
+        if not fn:
+            return None
+        out = c_char_p()
+        result = fn(self._handle, session_id.encode("utf-8"), byref(out))
+        if result != GopherAuthError.SUCCESS:
+            return None
+        if out.value:
+            val = out.value.decode("utf-8")
+            free = funcs.get("free_string")
+            if free:
+                free(out)
+            return val
+        return None
+
+    def has_valid_token(self, session_id: str) -> bool:
+        self._ensure_not_destroyed()
+        funcs = get_auth_functions()
+        fn = funcs.get("session_has_valid_token")
+        if not fn:
+            return False
+        out = c_bool(False)
+        fn(self._handle, session_id.encode("utf-8"), byref(out))
+        return out.value
+
+    def cleanup(self) -> None:
+        self._ensure_not_destroyed()
+        funcs = get_auth_functions()
+        fn = funcs.get("session_cleanup")
+        if fn:
+            fn(self._handle)
+
+    @staticmethod
+    def generate_session_id() -> str:
+        if not is_auth_available():
+            load_library()
+        funcs = get_auth_functions()
+        fn = funcs.get("session_generate_id")
+        if not fn:
+            raise RuntimeError("Function not available")
+        out = c_char_p()
+        result = fn(byref(out))
+        if result != GopherAuthError.SUCCESS or not out.value:
+            raise RuntimeError("Failed to generate session ID")
+        val = out.value.decode("utf-8")
+        free = funcs.get("free_string")
+        if free:
+            free(out)
+        return val
+
+    def get_handle(self) -> c_void_p:
+        self._ensure_not_destroyed()
+        return self._handle
+
+    def destroy(self) -> None:
+        if self._destroyed:
+            return
+        funcs = get_auth_functions()
+        d = funcs.get("session_manager_destroy")
+        if d and self._handle:
+            d(self._handle)
+        self._handle = None
+        self._destroyed = True
+
+    def is_destroyed(self) -> bool:
+        return self._destroyed
+
+    def __enter__(self) -> "GopherSessionManager":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.destroy()
+
+    def _ensure_not_destroyed(self) -> None:
+        if self._destroyed:
+            raise RuntimeError("GopherSessionManager has been destroyed")

tests/ffi/auth/test_session_manager.py

@@ -0,0 +1,68 @@
+"""Tests for GopherSessionManager FFI binding."""
+import time
+import pytest
+from gopher_mcp_python.ffi.auth.loader import is_auth_available
+
+pytestmark = pytest.mark.skipif(not is_auth_available(), reason="Native library not available")
+
+from gopher_mcp_python.ffi.auth.session_manager import GopherSessionManager
+from gopher_mcp_python.ffi.auth.auth_client import gopher_init_auth_library
+
+@pytest.fixture(autouse=True)
+def init_lib():
+    gopher_init_auth_library()
+
+class TestSessionManager:
+    def test_store_and_retrieve(self):
+        mgr = GopherSessionManager(300)
+        mgr.store_token("s1", "access", "refresh", 3600)
+        assert mgr.get_access_token("s1") == "access"
+        assert mgr.get_refresh_token("s1") == "refresh"
+        mgr.destroy()
+
+    def test_has_valid_token_true(self):
+        mgr = GopherSessionManager(300)
+        mgr.store_token("s1", "tok", "ref", 3600)
+        assert mgr.has_valid_token("s1") is True
+        mgr.destroy()
+
+    def test_has_valid_token_expired(self):
+        mgr = GopherSessionManager(300)
+        mgr.store_token("s1", "tok", "ref", -10)
+        assert mgr.has_valid_token("s1") is False
+        mgr.destroy()
+
+    def test_unknown_session(self):
+        mgr = GopherSessionManager(300)
+        assert mgr.get_access_token("nonexistent") is None
+        mgr.destroy()
+
+    def test_generate_id_hex(self):
+        sid = GopherSessionManager.generate_session_id()
+        assert len(sid) == 32
+        assert all(c in "0123456789abcdef" for c in sid)
+
+    def test_generate_id_unique(self):
+        ids = {GopherSessionManager.generate_session_id() for _ in range(10)}
+        assert len(ids) == 10
+
+    def test_cleanup(self):
+        mgr = GopherSessionManager(1)
+        mgr.store_token("s1", "t1", "r1", 3600)
+        time.sleep(2.1)
+        mgr.store_token("s2", "t2", "r2", 3600)
+        mgr.cleanup()
+        assert mgr.get_access_token("s1") is None
+        assert mgr.get_access_token("s2") == "t2"
+        mgr.destroy()
+
+    def test_destroy(self):
+        mgr = GopherSessionManager(300)
+        mgr.destroy()
+        assert mgr.is_destroyed()
+
+    def test_double_destroy(self):
+        mgr = GopherSessionManager(300)
+        mgr.destroy()
+        mgr.destroy()
+        assert mgr.is_destroyed()