ironflock 1.3.0__tar.gz → 1.3.2__tar.gz

{ironflock-1.3.0 → ironflock-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ironflock
-Version: 1.3.0
+Version: 1.3.2
 Summary: IronFlock Python SDK for connecting to the IronFlock Platform
 License-Expression: MIT
 License-File: LICENSE
@@ -13,6 +13,7 @@ Provides-Extra: dev
 Provides-Extra: docs
 Requires-Dist: autobahn[asyncio,serialization] (==24.4.2)
 Requires-Dist: mypy ; extra == "dev"
+Requires-Dist: pydantic (>=2.0.0)
 Requires-Dist: pydantic ; extra == "dev"
 Requires-Dist: pytest ; extra == "dev"
 Requires-Dist: ruff ; extra == "dev"

{ironflock-1.3.0 → ironflock-1.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ironflock"
-version = "1.3.0"
+version = "1.3.2"
 description = "IronFlock Python SDK for connecting to the IronFlock Platform"
 authors = [
     {name = "Marko Petzold, IronFlock GmbH", email = "info@ironflock.com"}
@@ -13,7 +13,8 @@ classifiers = [
     "Intended Audience :: Developers",
 ]
 dependencies = [
-    "autobahn[asyncio,serialization]==24.4.2"
+    "autobahn[asyncio,serialization]==24.4.2",
+    "pydantic>=2.0.0"
 ]
 
 [project.urls]

{ironflock-1.3.0 → ironflock-1.3.2}/src/ironflock/CrossbarConnection.py

@@ -7,6 +7,12 @@ from autobahn.asyncio.component import Component
 from autobahn.wamp import auth
 from enum import Enum
 
+# Import Pydantic types for validation
+try:
+    from .types import CrossbarCallParams, SubscriptionParams
+except ImportError:
+    from ironflock.types import CrossbarCallParams, SubscriptionParams
+
 class Stage(Enum):
     """Stage enumeration for different deployment environments"""
     DEVELOPMENT = "DEV"
@@ -202,14 +208,22 @@ class CrossbarConnection:
         options: Optional[Dict[str, Any]] = None
     ) -> Any:
         """Call a remote procedure"""
+        # Validate parameters using Pydantic
+        try:
+            params = CrossbarCallParams(
+                topic=topic,
+                args=args or [],
+                kwargs=kwargs or {},
+                options=options
+            )
+        except Exception as e:
+            raise ValueError(f"Invalid call parameters: {e}")
+        
         await self._session_wait()
         if not self.session:
             raise RuntimeError("No active session")
             
-        args = args or []
-        kwargs = kwargs or {}
-        
-        result = await self.session.call(topic, *args, **kwargs, options=options)
+        result = await self.session.call(params.topic, *params.args, **params.kwargs, options=params.options)
         return result
         
     async def subscribe(
@@ -219,11 +233,20 @@ class CrossbarConnection:
         options: Optional[Dict[str, Any]] = None
     ) -> Optional[Any]:
         """Subscribe to a topic"""
+        # Validate parameters using Pydantic
+        try:
+            params = SubscriptionParams(
+                topic=topic,
+                options=options
+            )
+        except Exception as e:
+            raise ValueError(f"Invalid subscription parameters: {e}")
+        
         await self._session_wait()
         if not self.session:
             raise RuntimeError("No active session")
             
-        subscription = await self.session.subscribe(handler, topic, options=options)
+        subscription = await self.session.subscribe(handler, params.topic, options=params.options)
         if subscription:
             self.subscriptions.append(subscription)
         return subscription
@@ -236,14 +259,22 @@ class CrossbarConnection:
         options: Optional[Dict[str, Any]] = None
     ) -> Optional[Any]:
         """Publish to a topic"""
+        # Validate parameters using Pydantic
+        try:
+            params = CrossbarCallParams(  # Using CrossbarCallParams as it has the same structure
+                topic=topic,
+                args=args or [],
+                kwargs=kwargs or {},
+                options=options
+            )
+        except Exception as e:
+            raise ValueError(f"Invalid publish parameters: {e}")
+        
         await self._session_wait()
         if not self.session:
             raise RuntimeError("No active session")
             
-        args = args or []
-        kwargs = kwargs or {}
-        
-        result = await self.session.publish(topic, *args, options=options, **kwargs)
+        result = await self.session.publish(params.topic, *params.args, options=params.options, **params.kwargs)
         return result
         
     async def unsubscribe(self, subscription: Any) -> None:

{ironflock-1.3.0 → ironflock-1.3.2}/src/ironflock/__init__.py

@@ -7,4 +7,4 @@ __all__ = [
     "Stage"
 ]
 
-__version__ = "1.3.0"
+__version__ = "1.3.2"

{ironflock-1.3.0 → ironflock-1.3.2}/src/ironflock/ironflock.py

@@ -1,9 +1,11 @@
 import os
 import asyncio
-from typing import Optional, Any
+from typing import Optional, Any, Union
 
 from ironflock.CrossbarConnection import CrossbarConnection, Stage, getSerialNumber
+from ironflock.types import TableQueryParams, PublishParams, CallParams, LocationParams, TableParams, SubscriptionParams
 from autobahn.wamp.types import PublishOptions, RegisterOptions, SubscribeOptions, CallOptions
+import warnings
 
 
 class IronFlock:
@@ -34,10 +36,29 @@ class IronFlock:
         self._serial_number = getSerialNumber(serial_number)
         self._device_name = os.environ.get("DEVICE_NAME")
         self._device_key = os.environ.get("DEVICE_KEY")
+        self._app_name = os.environ.get("APP_NAME")
+        self._swarm_key = int(os.environ.get("SWARM_KEY"))
+        self._app_key = int(os.environ.get("APP_KEY"))
         self._connection = CrossbarConnection()
         self.mainFunc = mainFunc
         self._main_task = None
         self._is_configured = False
+        # Validate required environment variables
+        missing_vars = []
+        if not self._device_key:
+            missing_vars.append("DEVICE_KEY")
+        if not self._app_name:
+            missing_vars.append("APP_NAME")
+        if not self._serial_number:
+            missing_vars.append("DEVICE_SERIAL_NUMBER")
+        if not self._swarm_key:
+            missing_vars.append("SWARM_KEY")
+        if not self._app_key:
+            missing_vars.append("APP_KEY")
+
+        if missing_vars:
+            warning_msg = f"Warning: The following environment variables must be present: {', '.join(missing_vars)}"
+            warnings.warn(warning_msg, UserWarning, stacklevel=2)
 
     @property
     def connection(self) -> CrossbarConnection:
@@ -62,8 +83,6 @@ class IronFlock:
         if self._is_configured:
             return
             
-        swarm_key = int(os.environ.get("SWARM_KEY", 0))
-        app_key = int(os.environ.get("APP_KEY", 0))
         env_value = os.environ.get("ENV", "DEV").upper()
         
         # Map environment string to Stage enum
@@ -74,12 +93,22 @@ class IronFlock:
         stage = stage_map.get(env_value, Stage.DEVELOPMENT)
         
         await self._connection.configure(
-            swarm_key=swarm_key,
-            app_key=app_key,
+            swarm_key=int(self._swarm_key),
+            app_key=int(self._app_key),
             stage=stage,
             serial_number=self._serial_number
         )
         self._is_configured = True
+        
+    def getRemoteAccessUrlForPort(self, port: int) -> Optional[str]:
+        """Get the remote access URL for a given port from the CrossbarConnection
+
+        Args:
+            port (int): The port number to get the URL for
+        Returns:
+            Optional[str]: The remote access URL or None if not available
+        """
+        return f"https://{self._device_key}-{self._app_name.lower()}-{port}.app.ironflock.com" if self._device_key and self._app_name else None
 
     async def publish(self, topic: str, *args, **kwargs) -> Optional[Any]:
         """Publishes to the IronFlock Platform Message Router
@@ -93,6 +122,16 @@ class IronFlock:
             Optional[Any]: Object representing a publication
             (feedback from publishing an event when doing an acknowledged publish)
         """
+        # Validate parameters using Pydantic
+        try:
+            params = PublishParams(
+                topic=topic,
+                args=list(args),
+                kwargs=kwargs
+            )
+        except Exception as e:
+            raise ValueError(f"Invalid publish parameters: {e}")
+        
         if not self.is_connected:
             print("cannot publish, not connected")
             return None
@@ -105,15 +144,15 @@ class IronFlock:
         }
         
         # Merge device metadata with user kwargs
-        combined_kwargs = {**device_metadata, **kwargs}
+        combined_kwargs = {**device_metadata, **params.kwargs}
         
         # Use acknowledged publish with proper PublishOptions
         options = PublishOptions(acknowledge=True)
         
         try:
             pub = await self._connection.publish(
-                topic, 
-                args=list(args), 
+                params.topic, 
+                args=params.args, 
                 kwargs=combined_kwargs,
                 options=options
             )
@@ -134,13 +173,19 @@ class IronFlock:
             long (float): Longitude coordinate
             lat (float): Latitude coordinate
         """
+        # Validate parameters using Pydantic
+        try:
+            params = LocationParams(longitude=long, latitude=lat)
+        except Exception as e:
+            raise ValueError(f"Invalid location parameters: {e}")
+        
         if not self.is_connected:
             print("cannot set location, not connected")
             return None
 
         payload = {
-            "long": long,
-            "lat": lat
+            "long": params.longitude,
+            "lat": params.latitude
         }
         
         extra = {
@@ -227,20 +272,29 @@ class IronFlock:
         Returns:
             Any: The result of the remote procedure call
         """
+        # Validate parameters using Pydantic
+        try:
+            params = CallParams(
+                device_key=device_key,
+                topic=topic,
+                args=args or [],
+                kwargs=kwargs or {},
+                options=options
+            )
+        except Exception as e:
+            raise ValueError(f"Invalid call parameters: {e}")
+        
         if not self.is_connected:
             print("cannot call, not connected")
             return None
 
-        args = args or []
-        kwargs = kwargs or {}
-
         # Convert options dict to CallOptions if provided
-        call_options = CallOptions(**options) if options else None
+        call_options = CallOptions(**params.options) if params.options else None
 
-        call_topic = f"{device_key}.{topic}"
+        call_topic = f"{params.device_key}.{params.topic}"
 
         try:
-            result = await self._connection.call(call_topic, args=args, kwargs=kwargs, options=call_options)
+            result = await self._connection.call(call_topic, args=params.args, kwargs=params.kwargs, options=call_options)
             return result
         except Exception as e:
             print(f"Call failed: {e}")
@@ -267,23 +321,130 @@ class IronFlock:
             Optional[Any]: Object representing a publication
             (feedback from publishing an event when doing an acknowledged publish)
         """
+        # Validate parameters using Pydantic
+        try:
+            params = TableParams(
+                tablename=tablename,
+                args=list(args),
+                kwargs=kwargs
+            )
+        except Exception as e:
+            raise ValueError(f"Invalid table parameters: {e}")
 
-        if not tablename:
-            raise Exception("Tablename must not be None or empty string!")
+        if not self._swarm_key:
+            raise Exception("SWARM_KEY not set in environment variables!")
 
-        swarm_key = os.environ.get("SWARM_KEY")
-        app_key = os.environ.get("APP_KEY")
+        if not self._app_key:
+            raise Exception("APP_KEY not set in environment variables!")
 
-        if swarm_key is None:
-            raise Exception("Environment variable SWARM_KEY not set!")
+        topic = f"{self._swarm_key}.{self._app_key}.{params.tablename}"
 
-        if app_key is None:
-            raise Exception("Environment variable APP_KEY not set!")
+        pub = await self.publish(topic, *params.args, **params.kwargs)
+        return pub
 
-        topic = f"{swarm_key}.{app_key}.{tablename}"
+    async def subscribe_to_table(
+        self, tablename: str, handler, options: Optional[dict] = None
+    ) -> Optional[Any]:
+        """Subscribes to a Table in the IronFlock Platform. This is a convenience function.
+        
+        You can achieve the same results by simply subscribing to the topic
+        [SWARM_KEY].[APP_KEY].[your_table_name]
+        
+        The SWARM_KEY and APP_KEY are provided as environment variables to the device container.
+        The also provided ENV variable holds either PROD or DEV to decide which topic to use, above.
+        This function automatically detects the environment and subscribes to the correct table.
+        
+        Args:
+            tablename (str): The table name of the table to subscribe to, e.g. "sensordata"
+            handler: The function to call when a message is received
+            options (dict, optional): Subscription options
 
-        pub = await self.publish(topic, *args, **kwargs)
-        return pub
+        Returns:
+            Optional[Any]: Object representing a subscription
+        """
+        # Validate parameters using Pydantic  
+        try:
+            params = SubscriptionParams(
+                topic=tablename,  # We validate the tablename as a topic
+                options=options
+            )
+        except Exception as e:
+            raise ValueError(f"Invalid subscription parameters: {e}")
+
+        if not self._swarm_key:
+            raise Exception("SWARM_KEY not set in environment variables!")
+
+        if not self._app_key:
+            raise Exception("APP_KEY not set in environment variables!")
+
+        topic = f"{self._swarm_key}.{self._app_key}.{params.topic}"
+
+        sub = await self.subscribe(topic, handler, params.options)
+        return sub
+
+    async def getHistory(self, tablename: str, queryParams: Union[TableQueryParams, dict]) -> Optional[Any]:
+        """Get historical data from a table using the history service
+        
+        Calls the "history.table" topic with the specified table name and query parameters.
+        
+        Args:
+            tablename (str): The name of the table to query
+            queryParams (TableQueryParams | dict): Query parameters including:
+                - limit (int): Maximum number of rows (required, 1-10000)
+                - offset (int, optional): Offset for pagination (>=0)
+                - timeRange (ISOTimeRange, optional): Time range filter with start/end ISO dates
+                - filterAnd (List[SQLFilterAnd], optional): AND conditions for filtering
+        
+        Returns:
+            Optional[Any]: The query result data or None if the call fails
+            
+        Raises:
+            ValueError: If validation fails for any parameter
+            pydantic.ValidationError: If Pydantic validation fails
+        """
+        if not tablename:
+            raise ValueError("Tablename must not be None or empty string!")
+        
+        # Validate and convert parameters using Pydantic BEFORE checking connection
+        try:
+            if isinstance(queryParams, dict):
+                # Convert dict to Pydantic model (this triggers validation)
+                validated_params = TableQueryParams(**queryParams)
+            else:
+                # Already a Pydantic model, but validate again to be safe
+                validated_params = queryParams
+                
+        except Exception as e:
+            raise ValueError(f"Invalid query parameters: {e}")
+            
+        if not self.is_connected:
+            print("cannot get history, not connected")
+            return None
+            
+        # Prepare the call arguments
+        queryParams = validated_params.model_dump()
+        
+        topic = f"history.transformed.app.{self._app_key}.{tablename}"
+        try:
+            result = await self._connection.call(
+                topic,
+                args=[queryParams]
+            )
+            return result
+        except Exception as e:
+            # Check for specific WAMP errors indicating procedure not available
+            error_str = str(e)
+            if (hasattr(e, 'error') and 
+                ('no_such_procedure' in str(e.error) or 'runtime_error' in str(e.error))) or \
+               'no callee registered for procedure' in error_str:
+                print(f"Get history failed: History service procedure '{topic}' not registered in Crossbar")
+                print(f"  Error type: {getattr(e, 'error', 'Unknown')}")
+                print(f"  Error details: {e}")
+                print(f"  This indicates the history service is not available or not properly configured")
+                return None
+            else:
+                print(f"Get history failed: {e}")
+                return None
 
     async def start(self):
         """Start the connection and run the main function if provided"""

ironflock-1.3.2/src/ironflock/types.py

@@ -0,0 +1,262 @@
+"""
+Type definitions for IronFlock table query functionality.
+Contains Pydantic models for runtime validation of query parameters.
+"""
+
+from typing import List, Union, Optional, Any
+import warnings
+from pydantic import BaseModel, Field, field_validator, ValidationInfo
+
+
+class TableQueryCondition(BaseModel):
+    """Individual condition for table queries"""
+    field: str = Field(..., min_length=1, description="Field name to filter on")
+    operator: str = Field(..., min_length=1, description="Comparison operator (=, !=, >, <, >=, <=, IN, NOT IN, LIKE, etc.)")
+    value: Union[str, int, float, bool, List[Union[str, int, float]]] = Field(..., description="Value to compare against")
+    
+    @field_validator('operator')
+    @classmethod
+    def validate_operator(cls, v: str) -> str:
+        """Validate that operator is from a known set"""
+        valid_operators = ['=', '!=', '>', '<', '>=', '<=', 'IN', 'NOT IN', 'LIKE', 'NOT LIKE', 'IS NULL', 'IS NOT NULL']
+        v_upper = v.upper()
+        if v_upper not in valid_operators:
+            # Allow the operator but warn about potentially unsafe operators
+            warnings.warn(f"Operator '{v}' is not in standard list: {valid_operators}", UserWarning)
+        return v
+    
+    @field_validator('value')
+    @classmethod
+    def validate_value_for_operator(cls, v: Union[str, int, float, bool, List[Union[str, int, float]]], info: ValidationInfo) -> Union[str, int, float, bool, List[Union[str, int, float]]]:
+        """Validate that value type matches the operator"""
+        if info.data and 'operator' in info.data:
+            operator = info.data['operator'].upper()
+            if operator in ('IN', 'NOT IN'):
+                # IN operators should have list values
+                if not isinstance(v, list):
+                    raise ValueError(f"Operator '{operator}' requires a list of values")
+                if len(v) == 0:
+                    raise ValueError(f"Operator '{operator}' requires at least one value")
+            elif isinstance(v, list):
+                # Non-IN operators should not have list values
+                raise ValueError(f"Operator '{operator}' does not support list values")
+        return v
+
+
+class ISOTimeRange(BaseModel):
+    """ISO time range specification with validation"""
+    start: str = Field(..., description="ISO datetime string for range start")
+    end: str = Field(..., description="ISO datetime string for range end")
+    
+    @field_validator('start', 'end')
+    @classmethod
+    def validate_iso_datetime(cls, v: str) -> str:
+        """Validate that the datetime strings are valid ISO format"""
+        from datetime import datetime
+        try:
+            datetime.fromisoformat(v.replace('Z', '+00:00'))
+            return v
+        except ValueError:
+            raise ValueError(f"Invalid ISO datetime format: {v}")
+
+
+class SQLFilterAnd(BaseModel):
+    """SQL filter specification for AND conditions with validation"""
+    column: str = Field(..., min_length=1, description="Database column name")
+    operator: str = Field(..., description="SQL operator (=, >, <, LIKE, etc.)")
+    value: Union[str, int, float, bool, List[Union[str, int, float]]] = Field(..., description="Filter value or list of values for IN operator")
+    
+    @field_validator('operator')
+    @classmethod
+    def validate_operator(cls, v: str) -> str:
+        """Validate that operator is a known SQL operator"""
+        valid_operators = {'=', '!=', '<>', '>', '<', '>=', '<=', 'LIKE', 'ILIKE', 'IN', 'NOT IN', 'IS', 'IS NOT'}
+        if v.upper() not in valid_operators:
+            # Allow the operator but warn about potentially unsafe operators
+            warnings.warn(f"Operator '{v}' is not in standard list: {valid_operators}", UserWarning)
+        return v
+    
+    @field_validator('value')
+    @classmethod
+    def validate_value_for_operator(cls, v: Union[str, int, float, bool, List[Union[str, int, float]]], info: ValidationInfo) -> Union[str, int, float, bool, List[Union[str, int, float]]]:
+        """Validate that value type matches the operator"""
+        if info.data and 'operator' in info.data:
+            operator = info.data['operator'].upper()
+            if operator in ('IN', 'NOT IN'):
+                # IN operators should have list values
+                if not isinstance(v, list):
+                    raise ValueError(f"Operator '{operator}' requires a list of values")
+                if len(v) == 0:
+                    raise ValueError(f"Operator '{operator}' requires at least one value")
+            elif isinstance(v, list):
+                # Non-IN operators should not have list values
+                raise ValueError(f"Operator '{operator}' does not support list values")
+        return v
+
+
+class TableQueryParams(BaseModel):
+    """Parameters for table history queries with comprehensive validation
+    
+    Equivalent to TypeScript:
+    {
+      limit: number & tags.Type<"uint32"> & tags.Maximum<10000>;
+      offset?: number & tags.Type<"uint32">;
+      timeRange?: ISOTimeRange;
+      filterAnd?: SQLFilterAnd[];
+    }
+    """
+    limit: int = Field(..., gt=0, le=10000, description="Maximum number of rows (1-10000)")
+    offset: Optional[int] = Field(None, ge=0, description="Offset for pagination (>=0)")
+    timeRange: Optional[ISOTimeRange] = Field(None, description="Time range filter")
+    filterAnd: Optional[List[SQLFilterAnd]] = Field(None, description="AND conditions for filtering")
+    
+    @field_validator('limit')
+    @classmethod
+    def validate_limit_uint32(cls, v: int) -> int:
+        """Validate that limit fits in uint32 range"""
+        if v > 4294967295:  # 2^32 - 1
+            raise ValueError("limit exceeds uint32 maximum")
+        return v
+    
+    @field_validator('offset')
+    @classmethod
+    def validate_offset_uint32(cls, v: Optional[int]) -> Optional[int]:
+        """Validate that offset fits in uint32 range"""
+        if v is not None and v > 4294967295:  # 2^32 - 1
+            raise ValueError("offset exceeds uint32 maximum")
+        return v
+
+
+# Additional Pydantic models for other IronFlock functions
+
+class PublishParams(BaseModel):
+    """Parameters for publish operations"""
+    topic: str = Field(..., min_length=1, description="Topic URI (e.g., 'com.myapp.mytopic1')")
+    args: Optional[List[Any]] = Field(default_factory=list, description="Positional arguments")
+    kwargs: Optional[dict] = Field(default_factory=dict, description="Keyword arguments")
+    
+    @field_validator('topic')
+    @classmethod
+    def validate_topic_format(cls, v: str) -> str:
+        """Validate topic follows URI-like format"""
+        if not v or not isinstance(v, str):
+            raise ValueError("Topic must be a non-empty string")
+        # Basic topic format validation (can be enhanced as needed)
+        if len(v.strip()) != len(v):
+            raise ValueError("Topic cannot have leading/trailing whitespace")
+        return v
+
+
+class CallParams(BaseModel):
+    """Parameters for remote procedure calls"""
+    device_key: str = Field(..., min_length=1, description="Target device key")
+    topic: str = Field(..., min_length=1, description="Procedure topic URI")
+    args: Optional[List[Any]] = Field(default_factory=list, description="Positional arguments")
+    kwargs: Optional[dict] = Field(default_factory=dict, description="Keyword arguments")
+    options: Optional[dict] = Field(None, description="Call options")
+    
+    @field_validator('device_key', 'topic')
+    @classmethod
+    def validate_non_empty_strings(cls, v: str) -> str:
+        """Validate that string fields are non-empty"""
+        if not v or not isinstance(v, str):
+            raise ValueError("Field must be a non-empty string")
+        if len(v.strip()) != len(v):
+            raise ValueError("Field cannot have leading/trailing whitespace")
+        return v
+
+
+class LocationParams(BaseModel):
+    """Parameters for device location updates"""
+    longitude: float = Field(..., ge=-180.0, le=180.0, description="Longitude in decimal degrees")
+    latitude: float = Field(..., ge=-90.0, le=90.0, description="Latitude in decimal degrees")
+    
+    @field_validator('longitude', 'latitude')
+    @classmethod
+    def validate_coordinates(cls, v: float) -> float:
+        """Validate coordinate values are finite numbers"""
+        if not isinstance(v, (int, float)):
+            raise ValueError("Coordinates must be numeric")
+        if not (-1000 <= v <= 1000):  # Reasonable bounds check
+            raise ValueError("Coordinate value seems unrealistic")
+        return float(v)
+
+
+class TableParams(BaseModel):
+    """Parameters for table operations"""
+    tablename: str = Field(..., min_length=1, description="Table name")
+    args: Optional[List[Any]] = Field(default_factory=list, description="Positional arguments")
+    kwargs: Optional[dict] = Field(default_factory=dict, description="Keyword arguments")
+    
+    @field_validator('tablename')
+    @classmethod
+    def validate_tablename(cls, v: str) -> str:
+        """Validate table name format"""
+        if not v or not isinstance(v, str):
+            raise ValueError("Table name must be a non-empty string")
+        
+        # Remove leading/trailing whitespace
+        v = v.strip()
+        if not v:
+            raise ValueError("Table name cannot be empty or just whitespace")
+            
+        # Basic table name validation
+        if not v.replace('_', '').replace('-', '').isalnum():
+            raise ValueError("Table name should contain only alphanumeric characters, hyphens, and underscores")
+            
+        if len(v) > 100:  # Reasonable length limit
+            raise ValueError("Table name too long (max 100 characters)")
+            
+        return v
+
+
+class SubscriptionParams(BaseModel):
+    """Parameters for subscription operations"""
+    topic: str = Field(..., min_length=1, description="Topic URI to subscribe to")
+    options: Optional[Union[dict, Any]] = Field(None, description="Subscription options (dict or autobahn options object)")
+    
+    @field_validator('topic')
+    @classmethod
+    def validate_topic_format(cls, v: str) -> str:
+        """Validate topic follows URI-like format"""
+        if not v or not isinstance(v, str):
+            raise ValueError("Topic must be a non-empty string")
+        if len(v.strip()) != len(v):
+            raise ValueError("Topic cannot have leading/trailing whitespace")
+        return v
+    
+    @field_validator('options')
+    @classmethod
+    def validate_options(cls, v: Optional[Union[dict, Any]]) -> Optional[Union[dict, Any]]:
+        """Accept either dict or autobahn options objects"""
+        if v is None:
+            return v
+        # Accept any object that autobahn might pass (SubscribeOptions, etc.)
+        return v
+
+
+class CrossbarCallParams(BaseModel):
+    """Parameters for low-level Crossbar calls"""
+    topic: str = Field(..., min_length=1, description="Topic URI")
+    args: Optional[List[Any]] = Field(default_factory=list, description="Positional arguments")
+    kwargs: Optional[dict] = Field(default_factory=dict, description="Keyword arguments")
+    options: Optional[Union[dict, Any]] = Field(None, description="Call options (dict or autobahn options object)")
+    
+    @field_validator('options')
+    @classmethod
+    def validate_options(cls, v: Optional[Union[dict, Any]]) -> Optional[Union[dict, Any]]:
+        """Accept either dict or autobahn options objects"""
+        if v is None:
+            return v
+        # Accept any object that autobahn might pass (PublishOptions, CallOptions, etc.)
+        return v
+    
+    @field_validator('topic')
+    @classmethod
+    def validate_topic_format(cls, v: str) -> str:
+        """Validate topic follows URI-like format"""
+        if not v or not isinstance(v, str):
+            raise ValueError("Topic must be a non-empty string")
+        if len(v.strip()) != len(v):
+            raise ValueError("Topic cannot have leading/trailing whitespace")
+        return v