cinchdb 0.1.15__py3-none-any.whl → 0.1.18__py3-none-any.whl

cinchdb/plugins/base.py

@@ -1,90 +1,73 @@
 """
-Base classes for CinchDB plugins.
+Simple base class for CinchDB plugins.
 """
 
-from abc import ABC, abstractmethod
-from typing import Any, Dict, List, Callable
-from enum import Enum
+from typing import Any, Dict, Optional
 
 
-class PluginHook(Enum):
-    """Available plugin hooks."""
-    # Database lifecycle hooks
-    DATABASE_INIT = "database_init"
-    DATABASE_CONNECT = "database_connect"
-    DATABASE_DISCONNECT = "database_disconnect"
+class Plugin:
+    """Simple base class for CinchDB plugins."""
     
-    # Query hooks
-    QUERY_BEFORE = "query_before"
-    QUERY_AFTER = "query_after"
-    QUERY_ERROR = "query_error"
+    # Plugin metadata - override in subclass
+    name: str = "unnamed_plugin"
+    version: str = "1.0.0"
+    description: str = ""
     
-    # Table hooks
-    TABLE_CREATE = "table_create"
-    TABLE_DROP = "table_drop"
-    TABLE_ALTER = "table_alter"
-    
-    # Tenant hooks
-    TENANT_CREATE = "tenant_create"
-    TENANT_DROP = "tenant_drop"
-    
-    # Branch hooks
-    BRANCH_CREATE = "branch_create"
-    BRANCH_SWITCH = "branch_switch"
-    BRANCH_MERGE = "branch_merge"
-    
-    # CLI hooks
-    CLI_COMMAND_BEFORE = "cli_command_before"
-    CLI_COMMAND_AFTER = "cli_command_after"
-
-
-class BasePlugin(ABC):
-    """Base class for all CinchDB plugins."""
-    
-    def __init__(self):
-        self.name = self.__class__.__name__
-        self.version = "1.0.0"
-        self.description = ""
-        self._hooks: Dict[PluginHook, List[Callable]] = {}
-        self._methods: Dict[str, Callable] = {}
+    def extend_database(self, db) -> None:
+        """Add methods or modify the database instance.
+        
+        Override this method to add custom methods to database instances:
         
-    @abstractmethod
-    def initialize(self, cinchdb_instance) -> None:
-        """Initialize the plugin with a CinchDB instance."""
+        Example:
+            def extend_database(self, db):
+                db.my_custom_method = self.my_custom_method
+        """
         pass
     
-    def register_hook(self, hook: PluginHook, callback: Callable) -> None:
-        """Register a callback for a specific hook."""
-        if hook not in self._hooks:
-            self._hooks[hook] = []
-        self._hooks[hook].append(callback)
-    
-    def register_method(self, method_name: str, method: Callable) -> None:
-        """Register a new method to be added to CinchDB instances."""
-        self._methods[method_name] = method
+    def before_query(self, sql: str, params: Optional[tuple] = None) -> tuple:
+        """Called before executing any SQL query.
+        
+        Args:
+            sql: The SQL statement to be executed
+            params: Parameters for the SQL statement
+            
+        Returns:
+            Tuple of (modified_sql, modified_params)
+        """
+        return sql, params
     
-    def get_hooks(self) -> Dict[PluginHook, List[Callable]]:
-        """Get all registered hooks."""
-        return self._hooks.copy()
+    def after_query(self, sql: str, params: Optional[tuple], result: Any) -> Any:
+        """Called after executing any SQL query.
+        
+        Args:
+            sql: The SQL statement that was executed
+            params: Parameters that were used
+            result: The query result
+            
+        Returns:
+            Modified result (or original result)
+        """
+        return result
     
-    def get_methods(self) -> Dict[str, Callable]:
-        """Get all registered methods."""
-        return self._methods.copy()
+    def on_connect(self, db_path: str, connection) -> None:
+        """Called when a database connection is established.
+        
+        Args:
+            db_path: Path to the database file
+            connection: SQLite connection object
+        """
+        pass
     
-    def call_hook(self, hook: PluginHook, *args, **kwargs) -> Any:
-        """Call all callbacks for a specific hook."""
-        results = []
-        for callback in self._hooks.get(hook, []):
-            try:
-                result = callback(*args, **kwargs)
-                results.append(result)
-            except Exception as e:
-                # Log error but don't break other plugins
-                print(f"Plugin {self.name} hook {hook} failed: {e}")
-        return results
+    def on_disconnect(self, db_path: str) -> None:
+        """Called when a database connection is closed.
+        
+        Args:
+            db_path: Path to the database file
+        """
+        pass
     
     def cleanup(self) -> None:
-        """Cleanup when plugin is unloaded."""
+        """Called when plugin is being unloaded."""
         pass
     
     @property
@@ -94,6 +77,4 @@ class BasePlugin(ABC):
             "name": self.name,
             "version": self.version,
             "description": self.description,
-            "hooks": list(self._hooks.keys()),
-            "methods": list(self._methods.keys()),
         }

cinchdb/plugins/decorators.py

@@ -1,45 +1,49 @@
 """
-Decorators for plugin development.
+Simple decorators for plugin development.
 """
 
 from typing import Callable
 
-from .base import PluginHook
 
-
-def hook(hook_type: PluginHook):
-    """Decorator to register a method as a hook callback."""
-    def decorator(func: Callable) -> Callable:
-        func._plugin_hook = hook_type
-        return func
-    return decorator
-
-
-def plugin_method(method_name: str):
-    """Decorator to register a method to be added to CinchDB instances."""
+def database_method(method_name: str):
+    """Decorator to mark a method for database extension.
+    
+    Usage:
+        class Plugin:
+            @database_method("my_method")
+            def my_custom_method(self, db):
+                return "Hello from plugin!"
+    """
     def decorator(func: Callable) -> Callable:
-        func._plugin_method_name = method_name
+        func._database_method_name = method_name
         return func
     return decorator
 
 
-class PluginDecorators:
-    """Helper class to collect decorated methods from a plugin class."""
+def auto_extend(plugin_class):
+    """Class decorator to automatically extend databases with decorated methods.
+    
+    Usage:
+        @auto_extend
+        class Plugin:
+            @database_method("custom_query")
+            def custom_query_method(self, db, query):
+                # Method will be added to db instances as db.custom_query()
+                return "Custom result"
+    """
+    original_extend = getattr(plugin_class, 'extend_database', None)
     
-    @staticmethod
-    def collect_hooks(plugin_instance) -> None:
-        """Collect and register hook methods from a plugin instance."""
-        for attr_name in dir(plugin_instance):
-            attr = getattr(plugin_instance, attr_name)
-            if callable(attr) and hasattr(attr, '_plugin_hook'):
-                hook_type = attr._plugin_hook
-                plugin_instance.register_hook(hook_type, attr)
+    def new_extend_database(self, db):
+        # Call original extend_database if it exists
+        if original_extend:
+            original_extend(self, db)
+        
+        # Auto-add decorated methods
+        for attr_name in dir(self):
+            attr = getattr(self, attr_name)
+            if callable(attr) and hasattr(attr, '_database_method_name'):
+                method_name = attr._database_method_name
+                setattr(db, method_name, lambda *args, **kwargs: attr(db, *args, **kwargs))
     
-    @staticmethod
-    def collect_methods(plugin_instance) -> None:
-        """Collect and register plugin methods from a plugin instance."""
-        for attr_name in dir(plugin_instance):
-            attr = getattr(plugin_instance, attr_name)
-            if callable(attr) and hasattr(attr, '_plugin_method_name'):
-                method_name = attr._plugin_method_name
-                plugin_instance.register_method(method_name, attr)
+    plugin_class.extend_database = new_extend_database
+    return plugin_class

cinchdb/plugins/manager.py

@@ -1,43 +1,31 @@
 """
-Plugin manager for CinchDB.
+Simple plugin manager for CinchDB.
 """
 
 import importlib
 import importlib.util
 import logging
 from pathlib import Path
-from typing import Dict, List, Optional, Any
-try:
-    from importlib.metadata import entry_points
-except ImportError:
-    # Fallback for Python < 3.8
-    from importlib_metadata import entry_points
+from typing import Dict, List, Optional, Any, Union
 
-from .base import BasePlugin, PluginHook
+from .base import Plugin
 
 logger = logging.getLogger(__name__)
 
 
 class PluginManager:
-    """Manages plugin lifecycle and hooks for CinchDB."""
+    """Simple plugin manager for CinchDB."""
     
     def __init__(self):
-        self.plugins: Dict[str, BasePlugin] = {}
-        self._cinchdb_instance = None
+        self.plugins: Dict[str, Plugin] = {}
+        self._database_instances: List[Any] = []
         
-    def set_cinchdb_instance(self, instance):
-        """Set the CinchDB instance for plugins."""
-        self._cinchdb_instance = instance
-        
-        # Initialize any already loaded plugins
-        for plugin in self.plugins.values():
-            try:
-                plugin.initialize(instance)
-            except Exception as e:
-                logger.error(f"Failed to initialize plugin {plugin.name}: {e}")
-    
-    def register_plugin(self, plugin: BasePlugin) -> None:
-        """Register a plugin instance."""
+    def register_plugin(self, plugin: Union[Plugin, type]) -> None:
+        """Register a plugin instance or class."""
+        # If it's a class, instantiate it
+        if isinstance(plugin, type):
+            plugin = plugin()
+            
         plugin_name = plugin.name
         
         if plugin_name in self.plugins:
@@ -45,13 +33,12 @@ class PluginManager:
         
         self.plugins[plugin_name] = plugin
         
-        # Initialize with CinchDB instance if available
-        if self._cinchdb_instance:
+        # Apply to existing database instances
+        for db_instance in self._database_instances:
             try:
-                plugin.initialize(self._cinchdb_instance)
-                self._apply_plugin_methods(plugin)
+                plugin.extend_database(db_instance)
             except Exception as e:
-                logger.error(f"Failed to initialize plugin {plugin_name}: {e}")
+                logger.error(f"Failed to extend database with plugin {plugin_name}: {e}")
         
         logger.info(f"Plugin {plugin_name} registered successfully")
     
@@ -72,18 +59,24 @@ class PluginManager:
         try:
             module = importlib.import_module(module_name)
             
-            # Look for plugin classes
+            # Look for Plugin class first
+            if hasattr(module, 'Plugin'):
+                plugin_instance = module.Plugin()
+                self.register_plugin(plugin_instance)
+                return
+            
+            # Fallback: look for any Plugin subclass
             for attr_name in dir(module):
                 attr = getattr(module, attr_name)
                 if (isinstance(attr, type) and 
-                    issubclass(attr, BasePlugin) and 
-                    attr != BasePlugin):
+                    issubclass(attr, Plugin) and 
+                    attr != Plugin):
                     
                     plugin_instance = attr()
                     self.register_plugin(plugin_instance)
                     return
             
-            logger.warning(f"No plugin class found in module {module_name}")
+            logger.warning(f"No Plugin class found in module {module_name}")
             
         except ImportError as e:
             logger.error(f"Failed to import plugin module {module_name}: {e}")
@@ -98,69 +91,108 @@ class PluginManager:
                 module = importlib.util.module_from_spec(spec)
                 spec.loader.exec_module(module)
                 
-                # Look for plugin classes
-                for attr_name in dir(module):
-                    attr = getattr(module, attr_name)
-                    if (isinstance(attr, type) and 
-                        issubclass(attr, BasePlugin) and 
-                        attr != BasePlugin):
-                        
-                        plugin_instance = attr()
-                        self.register_plugin(plugin_instance)
-                        return
+                # Look for Plugin class
+                if hasattr(module, 'Plugin'):
+                    plugin_instance = module.Plugin()
+                    self.register_plugin(plugin_instance)
+                    return
                 
-                logger.warning(f"No plugin class found in file {file_path}")
+                logger.warning(f"No Plugin class found in file {file_path}")
         
         except Exception as e:
             logger.error(f"Failed to load plugin from file {file_path}: {e}")
     
+    def load_plugins_from_directory(self, plugins_dir: Path) -> None:
+        """Load all plugins from a directory."""
+        if not plugins_dir.exists():
+            logger.info(f"Plugins directory {plugins_dir} does not exist")
+            return
+            
+        for plugin_file in plugins_dir.glob("*.py"):
+            if plugin_file.name == "__init__.py":
+                continue
+            self.load_plugin_from_file(plugin_file)
+    
     def discover_plugins(self) -> None:
-        """Discover plugins using entry points."""
+        """Discover plugins using entry points and plugins directory."""
+        # Try entry points for installed plugins
         try:
+            try:
+                from importlib.metadata import entry_points
+            except ImportError:
+                from importlib_metadata import entry_points
+                
             eps = entry_points()
-            # Handle both old and new entry_points API
             if hasattr(eps, 'select'):
-                # New API (Python 3.10+)
                 plugin_eps = eps.select(group='cinchdb.plugins')
             else:
-                # Old API
                 plugin_eps = eps.get('cinchdb.plugins', [])
             
             for entry_point in plugin_eps:
                 try:
                     plugin_class = entry_point.load()
-                    if issubclass(plugin_class, BasePlugin):
-                        plugin_instance = plugin_class()
-                        self.register_plugin(plugin_instance)
+                    self.register_plugin(plugin_class)
                 except Exception as e:
                     logger.error(f"Failed to load plugin {entry_point.name}: {e}")
         except Exception as e:
-            logger.error(f"Failed to discover plugins: {e}")
+            logger.debug(f"Entry points not available: {e}")
+        
+        # Also check for local plugins directory
+        plugins_dir = Path("plugins")
+        if plugins_dir.exists():
+            self.load_plugins_from_directory(plugins_dir)
     
-    def _apply_plugin_methods(self, plugin: BasePlugin) -> None:
-        """Apply plugin methods to the CinchDB instance."""
-        if not self._cinchdb_instance:
-            return
-            
-        for method_name, method in plugin.get_methods().items():
-            # Bind method to the instance
-            bound_method = method.__get__(self._cinchdb_instance, type(self._cinchdb_instance))
-            setattr(self._cinchdb_instance, method_name, bound_method)
-    
-    def call_hook(self, hook: PluginHook, *args, **kwargs) -> List[Any]:
-        """Call all plugin hooks for a specific event."""
-        results = []
+    def register_database(self, db_instance) -> None:
+        """Register a database instance with all plugins."""
+        self._database_instances.append(db_instance)
         
+        # Apply all plugins to this database instance
         for plugin in self.plugins.values():
             try:
-                plugin_results = plugin.call_hook(hook, *args, **kwargs)
-                results.extend(plugin_results)
+                plugin.extend_database(db_instance)
             except Exception as e:
-                logger.error(f"Plugin {plugin.name} hook {hook} failed: {e}")
-        
-        return results
+                logger.error(f"Failed to extend database with plugin {plugin.name}: {e}")
+    
+    def unregister_database(self, db_instance) -> None:
+        """Unregister a database instance."""
+        if db_instance in self._database_instances:
+            self._database_instances.remove(db_instance)
+    
+    def before_query(self, sql: str, params: Optional[tuple] = None) -> tuple:
+        """Call before_query on all plugins."""
+        for plugin in self.plugins.values():
+            try:
+                sql, params = plugin.before_query(sql, params)
+            except Exception as e:
+                logger.error(f"Plugin {plugin.name} before_query failed: {e}")
+        return sql, params
+    
+    def after_query(self, sql: str, params: Optional[tuple], result: Any) -> Any:
+        """Call after_query on all plugins."""
+        for plugin in self.plugins.values():
+            try:
+                result = plugin.after_query(sql, params, result)
+            except Exception as e:
+                logger.error(f"Plugin {plugin.name} after_query failed: {e}")
+        return result
+    
+    def on_connect(self, db_path: str, connection) -> None:
+        """Call on_connect on all plugins."""
+        for plugin in self.plugins.values():
+            try:
+                plugin.on_connect(db_path, connection)
+            except Exception as e:
+                logger.error(f"Plugin {plugin.name} on_connect failed: {e}")
+    
+    def on_disconnect(self, db_path: str) -> None:
+        """Call on_disconnect on all plugins."""
+        for plugin in self.plugins.values():
+            try:
+                plugin.on_disconnect(db_path)
+            except Exception as e:
+                logger.error(f"Plugin {plugin.name} on_disconnect failed: {e}")
     
-    def get_plugin(self, name: str) -> Optional[BasePlugin]:
+    def get_plugin(self, name: str) -> Optional[Plugin]:
         """Get a plugin by name."""
         return self.plugins.get(name)
     

cinchdb/utils/name_validator.py

@@ -7,8 +7,9 @@ and follow consistent naming conventions.
 import re
 
 
-# Regex pattern for valid names: lowercase letters, numbers, dash, underscore, period
-VALID_NAME_PATTERN = re.compile(r"^[a-z0-9][a-z0-9\-_\.]*[a-z0-9]$|^[a-z0-9]$")
+# Regex pattern for valid names: lowercase letters, numbers, dash, underscore
+# Period removed to prevent directory traversal attempts like "../"
+VALID_NAME_PATTERN = re.compile(r"^[a-z0-9][a-z0-9\-_]*[a-z0-9]$|^[a-z0-9]$")
 
 # Reserved names that cannot be used
 RESERVED_NAMES = {
@@ -52,6 +53,7 @@ def validate_name(name: str, entity_type: str = "entity") -> None:
     - Be at least 1 character long
     - Not exceed 255 characters (filesystem limit)
     - Not be a reserved name
+    - Not contain path traversal sequences
 
     Args:
         name: The name to validate
@@ -67,6 +69,19 @@ def validate_name(name: str, entity_type: str = "entity") -> None:
         raise InvalidNameError(
             f"{entity_type.capitalize()} name cannot exceed 255 characters"
         )
+    
+    # Critical: Check for path traversal attempts
+    if ".." in name or "/" in name or "\\" in name or "~" in name:
+        raise InvalidNameError(
+            f"Security violation: {entity_type} name '{name}' contains "
+            f"forbidden path traversal characters"
+        )
+    
+    # Check for null bytes and other control characters
+    if "\x00" in name or any(ord(c) < 32 for c in name):
+        raise InvalidNameError(
+            f"Security violation: {entity_type} name contains invalid control characters"
+        )
 
     # Check for lowercase requirement
     if name != name.lower():
@@ -80,7 +95,7 @@ def validate_name(name: str, entity_type: str = "entity") -> None:
         raise InvalidNameError(
             f"Invalid {entity_type} name '{name}'. "
             f"Names must contain only lowercase letters (a-z), numbers (0-9), "
-            f"dash (-), underscore (_), and period (.). "
+            f"dash (-), and underscore (_). "
             f"Names must start and end with alphanumeric characters."
         )
 
@@ -90,11 +105,6 @@ def validate_name(name: str, entity_type: str = "entity") -> None:
         or "__" in name
         or "-_" in name
         or "_-" in name
-        or ".." in name
-        or ".-" in name
-        or "-." in name
-        or "._" in name
-        or "_." in name
     ):
         raise InvalidNameError(
             f"Invalid {entity_type} name '{name}'. "
@@ -132,14 +142,14 @@ def clean_name(name: str) -> str:
     # Replace spaces with dashes
     cleaned = cleaned.replace(" ", "-")
 
-    # Remove invalid characters
-    cleaned = re.sub(r"[^a-z0-9\-_\.]", "", cleaned)
+    # Remove invalid characters (period no longer allowed)
+    cleaned = re.sub(r"[^a-z0-9\-_]", "", cleaned)
 
     # Remove consecutive special characters
-    cleaned = re.sub(r"[-_\.]{2,}", "-", cleaned)
+    cleaned = re.sub(r"[-_]{2,}", "-", cleaned)
 
     # Remove leading/trailing special characters
-    cleaned = cleaned.strip("-_.")
+    cleaned = cleaned.strip("-_")
 
     return cleaned
 

{cinchdb-0.1.15.dist-info → cinchdb-0.1.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cinchdb
-Version: 0.1.15
+Version: 0.1.18
 Summary: A Git-like SQLite database management system with branching and multi-tenancy
 Project-URL: Homepage, https://github.com/russellromney/cinchdb
 Project-URL: Documentation, https://russellromney.github.io/cinchdb
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: requests>=2.28.0
 Requires-Dist: rich>=13.0.0
@@ -31,6 +32,10 @@ Description-Content-Type: text/markdown
 
 **Git-like SQLite database management with branching and multi-tenancy**
 
+[![PyPI version](https://badge.fury.io/py/cinchdb.svg)](https://badge.fury.io/py/cinchdb)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+
 NOTE: CinchDB is in early alpha. This is project to test out an idea. Do not use this in production.
 
 CinchDB is for projects that need fast queries, isolated data per-tenant [or even per-user](https://turso.tech/blog/give-each-of-your-users-their-own-sqlite-database-b74445f4), and a branchable database that makes it easy to merge changes between branches.
@@ -64,6 +69,10 @@ cinch branch merge-into-main feature
 cinch tenant create customer_a
 cinch query "SELECT * FROM users" --tenant customer_a
 
+# Tenant encryption (bring your own keys)
+cinch tenant create secure_customer --encrypt --key="your-secret-key"
+cinch query "SELECT * FROM users" --tenant secure_customer --key="your-secret-key"
+
 # Future: Remote connectivity planned for production deployment
 
 # Autogenerate Python SDK from database
@@ -153,6 +162,35 @@ db.update("posts", post_id, {"content": "Updated content"})
 
 ## Architecture
 
+### Storage Architecture
+
+CinchDB uses a **tenant-first storage model** where database and branch are organizational metadata concepts, while tenants represent the actual isolated data stores:
+
+```
+.cinchdb/
+├── metadata.db                    # Organizational metadata
+└── {database}-{branch}/           # Context root (e.g., main-main, prod-feature)
+    ├── {shard}/                   # SHA256-based sharding (first 2 chars)
+    │   ├── {tenant}.db            # Actual SQLite database
+    │   └── {tenant}.db-wal        # WAL file
+    └── ...
+```
+
+**Key Design Decisions:**
+- **Tenant-first**: Each tenant gets its own SQLite database file
+- **Flat hierarchy**: Database/branch form a single context root, avoiding deep nesting
+- **Hash sharding**: Tenants are distributed across 256 shards using SHA256 for scalability
+- **Lazy initialization**: Tenant databases are created on first access, not on tenant creation
+- **WAL mode**: All databases use Write-Ahead Logging for better concurrency
+
+This architecture enables:
+- True multi-tenant isolation at the file system level
+- Efficient branching without duplicating tenant data
+- Simple backup/restore per tenant
+- Horizontal scaling through sharding
+
+### Components
+
 - **Python SDK**: Core functionality for local development
 - **CLI**: Full-featured command-line interface