django-cfg 1.4.62__py3-none-any.whl → 1.4.64__py3-none-any.whl

django_cfg/apps/centrifugo/codegen/discovery.py

@@ -0,0 +1,246 @@
+"""
+Method discovery for code generation.
+
+Scans registered RPC handlers and extracts type information.
+"""
+
+import inspect
+import logging
+from dataclasses import dataclass
+from typing import Type, List, Optional, Any, get_type_hints, Dict
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+# For type checking in warnings
+try:
+    from typing import _GenericAlias  # For Dict[str, Any] checks
+except ImportError:
+    _GenericAlias = type(None)
+
+
+@dataclass
+class RPCMethodInfo:
+    """
+    Information about discovered RPC method.
+
+    Attributes:
+        name: Method name (e.g., "send_notification")
+        handler_func: Handler function reference
+        param_type: Pydantic model for parameters (if available)
+        return_type: Pydantic model for return value (if available)
+        docstring: Method documentation
+    """
+
+    name: str
+    handler_func: Any
+    param_type: Optional[Type[BaseModel]]
+    return_type: Optional[Type[BaseModel]]
+    docstring: Optional[str]
+
+
+def discover_rpc_methods_from_router(router: Any) -> List[RPCMethodInfo]:
+    """
+    Discover RPC methods from MessageRouter instance.
+
+    Args:
+        router: MessageRouter instance with registered handlers
+
+    Returns:
+        List of discovered method information
+
+    Example:
+        >>> # Legacy router import removed
+        >>> router = MessageRouter(connection_manager)
+        >>>
+        >>> @router.register("echo")
+        >>> async def handle_echo(conn, params: EchoParams) -> EchoResult:
+        ...     return EchoResult(message=params.message)
+        >>>
+        >>> methods = discover_rpc_methods_from_router(router)
+        >>> methods[0].name
+        'echo'
+        >>> methods[0].param_type
+        <class 'EchoParams'>
+    """
+    methods = []
+
+    # Get registered handlers from router
+    handlers = getattr(router, "_handlers", {})
+
+    if not handlers:
+        logger.warning("No handlers found in router._handlers")
+        return methods
+
+    logger.info(f"Discovering {len(handlers)} RPC methods from router")
+
+    for method_name, handler_func in handlers.items():
+        try:
+            method_info = _extract_method_info(method_name, handler_func)
+            methods.append(method_info)
+            logger.debug(f"Discovered method: {method_name}")
+        except Exception as e:
+            logger.error(f"Failed to extract info for {method_name}: {e}")
+
+    return methods
+
+
+def _extract_method_info(method_name: str, handler_func: Any) -> RPCMethodInfo:
+    """
+    Extract type information from handler function.
+
+    Args:
+        method_name: Name of the method
+        handler_func: Handler function
+
+    Returns:
+        RPCMethodInfo with extracted type information
+    """
+    # Get function signature
+    signature = inspect.signature(handler_func)
+
+    # Get type hints
+    try:
+        hints = get_type_hints(handler_func)
+    except Exception as e:
+        logger.debug(f"Could not get type hints for {method_name}: {e}")
+        hints = {}
+
+    # Extract parameter type
+    # Handler signature: async def handler(conn: ActiveConnection, params: Dict[str, Any])
+    # We're looking for the 'params' parameter type
+    param_type = None
+    params_list = list(signature.parameters.values())
+
+    if len(params_list) >= 2:
+        # Second parameter should be params
+        params_param = params_list[1]
+        param_type_hint = hints.get(params_param.name)
+
+        # Check if it's a Pydantic model
+        if param_type_hint and _is_pydantic_model(param_type_hint):
+            param_type = param_type_hint
+        elif param_type_hint and not _is_generic_dict(param_type_hint):
+            # Warn if using non-Pydantic type (but not dict/Dict[str, Any])
+            logger.warning(
+                f"⚠️  Method '{method_name}' uses '{param_type_hint}' for params instead of Pydantic model. "
+                f"Type-safe client generation requires Pydantic models."
+            )
+
+    # Extract return type
+    return_type = None
+    return_type_hint = hints.get("return")
+
+    if return_type_hint and _is_pydantic_model(return_type_hint):
+        return_type = return_type_hint
+
+    # Get docstring
+    docstring = inspect.getdoc(handler_func)
+
+    return RPCMethodInfo(
+        name=method_name,
+        handler_func=handler_func,
+        param_type=param_type,
+        return_type=return_type,
+        docstring=docstring,
+    )
+
+
+def _is_pydantic_model(type_hint: Any) -> bool:
+    """
+    Check if type hint is a Pydantic model.
+
+    Args:
+        type_hint: Type hint to check
+
+    Returns:
+        True if it's a Pydantic BaseModel subclass
+    """
+    try:
+        return (
+            inspect.isclass(type_hint)
+            and issubclass(type_hint, BaseModel)
+        )
+    except (TypeError, AttributeError):
+        return False
+
+
+def _is_generic_dict(type_hint: Any) -> bool:
+    """
+    Check if type hint is dict or Dict[str, Any].
+
+    Args:
+        type_hint: Type hint to check
+
+    Returns:
+        True if it's dict or Dict type
+    """
+    if type_hint is dict:
+        return True
+
+    # Check for Dict[str, Any] or similar generic dict types
+    type_str = str(type_hint)
+    if 'dict' in type_str.lower() or 'Dict' in type_str:
+        return True
+
+    return False
+
+
+def extract_all_models(methods: List[RPCMethodInfo]) -> List[Type[BaseModel]]:
+    """
+    Extract all unique Pydantic models from discovered methods.
+
+    Args:
+        methods: List of discovered method information
+
+    Returns:
+        List of unique Pydantic models (both params and returns)
+    """
+    models = set()
+
+    for method in methods:
+        if method.param_type:
+            models.add(method.param_type)
+        if method.return_type:
+            models.add(method.return_type)
+
+    return sorted(list(models), key=lambda m: m.__name__)
+
+
+def get_method_summary(methods: List[RPCMethodInfo]) -> str:
+    """
+    Get human-readable summary of discovered methods.
+
+    Args:
+        methods: List of discovered method information
+
+    Returns:
+        Formatted summary string
+    """
+    lines = [f"Discovered {len(methods)} RPC methods:\n"]
+
+    for method in methods:
+        param_name = method.param_type.__name__ if method.param_type else "Dict[str, Any]"
+        return_name = method.return_type.__name__ if method.return_type else "Dict[str, Any]"
+
+        lines.append(f"  • {method.name}({param_name}) -> {return_name}")
+
+        if method.docstring:
+            # First line of docstring
+            doc_first_line = method.docstring.split("\n")[0].strip()
+            lines.append(f"    └─ {doc_first_line}")
+
+    return "\n".join(lines)
+
+
+# Backward compatibility: support importing from old path
+discover_rpc_methods = discover_rpc_methods_from_router
+
+
+__all__ = [
+    "RPCMethodInfo",
+    "discover_rpc_methods_from_router",
+    "discover_rpc_methods",
+    "extract_all_models",
+    "get_method_summary",
+]

django_cfg/apps/centrifugo/codegen/generators/go_thin/__init__.py

@@ -0,0 +1,5 @@
+"""Go thin wrapper generator."""
+
+from .generator import GoThinGenerator
+
+__all__ = ['GoThinGenerator']

django_cfg/apps/centrifugo/codegen/generators/go_thin/generator.py

@@ -0,0 +1,174 @@
+"""
+Go thin wrapper client generator.
+
+Generates Go structs + thin wrapper over CentrifugoRPCClient.
+"""
+
+import logging
+from pathlib import Path
+from typing import List, Type
+from pydantic import BaseModel
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from ...discovery import RPCMethodInfo
+from ...utils import to_go_method_name, pydantic_to_go
+
+logger = logging.getLogger(__name__)
+
+
+class GoThinGenerator:
+    """
+    Generator for Go thin wrapper clients.
+
+    Creates:
+    - types.go: Go struct definitions
+    - rpc_client.go: Base CentrifugoRPCClient
+    - client.go: Thin wrapper with typed methods
+    - go.mod: Go module file
+    - README.md: Usage documentation
+    """
+
+    def __init__(
+        self,
+        methods: List[RPCMethodInfo],
+        models: List[Type[BaseModel]],
+        output_dir: Path,
+        package_name: str = "centrifugo_client",
+        module_path: str = "example.com/centrifugo_client",
+    ):
+        """
+        Initialize generator.
+
+        Args:
+            methods: List of discovered RPC methods
+            models: List of Pydantic models
+            output_dir: Output directory for generated files
+            package_name: Go package name
+            module_path: Go module path for go.mod
+        """
+        self.methods = methods
+        self.models = models
+        self.output_dir = Path(output_dir)
+        self.package_name = package_name
+        self.module_path = module_path
+
+        # Setup Jinja2 environment
+        templates_dir = Path(__file__).parent / "templates"
+        self.jinja_env = Environment(
+            loader=FileSystemLoader(str(templates_dir)),
+            autoescape=select_autoescape(),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+    def generate(self):
+        """Generate all Go files."""
+        # Create output directory
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate types
+        self._generate_types()
+
+        # Generate RPC client base
+        self._generate_rpc_client()
+
+        # Generate thin wrapper
+        self._generate_client()
+
+        # Generate config files
+        self._generate_go_mod()
+        self._generate_readme()
+
+        logger.info(f"✅ Generated Go client in {self.output_dir}")
+
+    def _generate_types(self):
+        """Generate types.go file with Go struct definitions."""
+        template = self.jinja_env.get_template("types.go.j2")
+
+        # Convert Pydantic models to Go struct info
+        types_data = []
+        for model in self.models:
+            struct_info = pydantic_to_go(model)
+            types_data.append(struct_info)
+
+        content = template.render(
+            package_name=self.package_name,
+            types=types_data,
+        )
+
+        output_file = self.output_dir / "types.go"
+        output_file.write_text(content)
+        logger.debug(f"Generated {output_file}")
+
+    def _generate_rpc_client(self):
+        """Generate rpc_client.go base class."""
+        template = self.jinja_env.get_template("rpc_client.go.j2")
+        content = template.render(package_name=self.package_name)
+
+        output_file = self.output_dir / "rpc_client.go"
+        output_file.write_text(content)
+        logger.debug(f"Generated {output_file}")
+
+    def _generate_client(self):
+        """Generate client.go thin wrapper."""
+        template = self.jinja_env.get_template("client.go.j2")
+
+        # Prepare methods for template
+        methods_data = []
+        for method in self.methods:
+            param_type = method.param_type.__name__ if method.param_type else "map[string]interface{}"
+            return_type = method.return_type.__name__ if method.return_type else "map[string]interface{}"
+
+            # Convert method name to valid Go identifier (PascalCase)
+            method_name_go = to_go_method_name(method.name)
+
+            methods_data.append({
+                'name': method.name,  # Original name for RPC call
+                'name_go': method_name_go,  # Go-safe name
+                'param_type': param_type,
+                'return_type': return_type,
+                'docstring': method.docstring or f"Call {method.name} RPC method",
+            })
+
+        content = template.render(
+            package_name=self.package_name,
+            methods=methods_data,
+        )
+
+        output_file = self.output_dir / "client.go"
+        output_file.write_text(content)
+        logger.debug(f"Generated {output_file}")
+
+    def _generate_go_mod(self):
+        """Generate go.mod file."""
+        template = self.jinja_env.get_template("go.mod.j2")
+        content = template.render(module_path=self.module_path)
+
+        output_file = self.output_dir / "go.mod"
+        output_file.write_text(content)
+        logger.debug(f"Generated {output_file}")
+
+    def _generate_readme(self):
+        """Generate README.md file."""
+        template = self.jinja_env.get_template("README.md.j2")
+
+        # Prepare methods for examples
+        methods_data = []
+        for method in self.methods[:3]:  # First 3 methods for examples
+            methods_data.append({
+                'name': method.name,
+                'name_go': to_go_method_name(method.name),
+            })
+
+        content = template.render(
+            package_name=self.package_name,
+            module_path=self.module_path,
+            methods=methods_data,
+        )
+
+        output_file = self.output_dir / "README.md"
+        output_file.write_text(content)
+        logger.debug(f"Generated {output_file}")
+
+
+__all__ = ['GoThinGenerator']

django_cfg/apps/centrifugo/codegen/generators/go_thin/templates/README.md.j2

@@ -0,0 +1,182 @@
+# Centrifugo Go RPC Client
+
+Auto-generated Go client for Centrifugo WebSocket RPC communication.
+
+## Installation
+
+```bash
+# Dependencies are fetched via Go module proxy (proxy.golang.org by default)
+go mod tidy
+```
+
+### Dependencies
+
+This client uses **nhooyr.io/websocket** - a pure Go WebSocket library with no GitHub dependencies:
+
+- `nhooyr.io/websocket` v1.8.10 - WebSocket client library
+- Standard library: `crypto/rand`, `encoding/json`, `context`, `sync`, `time`
+
+All dependencies are fetched via Go module proxy (proxy.golang.org) by default.
+
+### Using Custom Go Proxy
+
+If you need to use a custom proxy or private registry:
+
+```bash
+# Set custom proxy
+export GOPROXY=https://your-proxy.com,direct
+
+# Or use Athens, JFrog Artifactory, etc.
+export GOPROXY=https://athens.your-company.com
+
+# Then install
+go mod tidy
+```
+
+### Offline/Air-gapped Installation
+
+For offline environments:
+
+```bash
+# On a machine with internet, vendor dependencies
+go mod vendor
+
+# Copy the entire directory (including vendor/) to offline machine
+# Then build with vendor
+go build -mod=vendor
+```
+
+### Why nhooyr.io/websocket?
+
+This client uses `nhooyr.io/websocket` instead of GitHub-hosted libraries for several reasons:
+
+- ✅ **No GitHub dependencies** - hosted at nhooyr.io, not github.com
+- ✅ **Clean module path** - better for enterprise proxies and air-gapped environments
+- ✅ **Minimal dependencies** - only one external dependency
+- ✅ **Modern API** - context-aware, clean concurrent design
+- ✅ **Production ready** - used by major projects
+
+UUID generation uses `crypto/rand` from stdlib (no external UUID library needed).
+
+## Usage
+
+### Basic Example
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "{{ module_path }}"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Create client
+    client := {{ package_name }}.NewAPIClient(
+        "ws://localhost:8000/connection/websocket",
+        "your-jwt-token",
+        "user123",
+    )
+
+    // Connect
+    if err := client.Connect(ctx); err != nil {
+        log.Fatalf("Failed to connect: %v", err)
+    }
+    defer client.Disconnect()
+
+    fmt.Println("✅ Connected to Centrifugo")
+
+    {% if methods %}
+    // Example RPC calls
+    {% for method in methods %}
+
+    // Call {{ method.name }}
+    result{{ loop.index }}, err := client.{{ method.name_go }}(ctx, params)
+    if err != nil {
+        log.Printf("Error calling {{ method.name }}: %v", err)
+    } else {
+        fmt.Printf("Result: %+v\n", result{{ loop.index }})
+    }
+    {% endfor %}
+    {% endif %}
+}
+```
+
+### With Context Timeout
+
+```go
+ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+defer cancel()
+
+result, err := client.SomeMethod(ctx, params)
+if err != nil {
+    log.Printf("RPC call failed: %v", err)
+}
+```
+
+### Error Handling
+
+```go
+result, err := client.SomeMethod(ctx, params)
+if err != nil {
+    if rpcErr, ok := err.(*{{ package_name }}.RPCError); ok {
+        fmt.Printf("RPC error %d: %s\n", rpcErr.Code, rpcErr.Message)
+    } else {
+        fmt.Printf("Connection error: %v\n", err)
+    }
+    return
+}
+
+fmt.Printf("Success: %+v\n", result)
+```
+
+## Architecture
+
+### Files
+
+- `types.go` - Generated Go structs from Pydantic models
+- `rpc_client.go` - Base RPC client with correlation ID pattern
+- `client.go` - Thin wrapper with typed methods
+- `go.mod` - Go module dependencies
+
+### How It Works
+
+1. **Connect**: Establishes WebSocket connection to Centrifugo
+2. **Subscribe**: Subscribes to user-specific reply channel
+3. **Call**: Publishes RPC request with correlation ID
+4. **Wait**: Waits for response on reply channel
+5. **Return**: Returns typed result or error
+
+### Type Safety
+
+All RPC methods are fully typed:
+
+```go
+// Request and response types are generated from Pydantic models
+func (api *APIClient) GetUserProfile(ctx context.Context, params UserProfileRequest) (*UserProfileResponse, error)
+```
+
+### Correlation ID Pattern
+
+Each RPC call:
+1. Generates unique correlation ID (UUID)
+2. Publishes request to `rpc.requests` channel
+3. Waits for response on `user#{userID}` channel
+4. Matches response by correlation ID
+5. Returns result or error
+
+## Dependencies
+
+- `github.com/centrifugal/centrifuge-go` - Centrifugo Go client
+- `github.com/google/uuid` - UUID generation
+
+## Generated Code
+
+This client was auto-generated by django-cfg centrifugo codegen.
+Do not edit generated files manually - regenerate instead.

django_cfg/apps/centrifugo/codegen/generators/go_thin/templates/client.go.j2

@@ -0,0 +1,64 @@
+// Code generated by django-cfg centrifugo codegen. DO NOT EDIT.
+
+package {{ package_name }}
+
+import (
+	"context"
+	"time"
+)
+
+// APIClient is a thin wrapper over CentrifugoRPCClient with typed methods.
+type APIClient struct {
+	rpc *CentrifugoRPCClient
+}
+
+// NewAPIClient creates a new typed API client.
+//
+// Args:
+//   - url: Centrifugo WebSocket URL
+//   - token: JWT token for authentication
+//   - userID: User ID for reply channel
+//
+// Example:
+//
+//	client := NewAPIClient("ws://localhost:8000/connection/websocket", token, "user123")
+//	if err := client.Connect(ctx); err != nil {
+//	    log.Fatal(err)
+//	}
+//	defer client.Disconnect()
+func NewAPIClient(url, token, userID string) *APIClient {
+	return &APIClient{
+		rpc: NewCentrifugoRPCClient(url, token, userID, 30*time.Second),
+	}
+}
+
+// Connect establishes connection to Centrifugo.
+func (api *APIClient) Connect(ctx context.Context) error {
+	return api.rpc.Connect(ctx)
+}
+
+// Disconnect closes the connection.
+func (api *APIClient) Disconnect() error {
+	return api.rpc.Disconnect()
+}
+
+{% for method in methods %}
+// {{ method.name_go }}{% if method.docstring %} {{ method.docstring.split('\n')[0] }}{% endif %}
+
+{% if method.docstring and method.docstring.split('\n')|length > 1 %}
+{% for line in method.docstring.split('\n')[1:] %}
+{% if line.strip() %}
+// {{ line.strip() }}
+{% endif %}
+{% endfor %}
+{% endif %}
+func (api *APIClient) {{ method.name_go }}(ctx context.Context, params {{ method.param_type }}) (*{{ method.return_type }}, error) {
+	var result {{ method.return_type }}
+	err := api.rpc.Call(ctx, "{{ method.name }}", params, &result)
+	if err != nil {
+		return nil, err
+	}
+	return &result, nil
+}
+
+{% endfor %}

django_cfg/apps/centrifugo/codegen/generators/go_thin/templates/go.mod.j2

@@ -0,0 +1,10 @@
+// Auto-generated Go module for Centrifugo WebSocket RPC client
+// Dependencies are fetched via Go module proxy (proxy.golang.org by default)
+// To use custom proxy: export GOPROXY=https://your-proxy.com
+module {{ module_path }}
+
+go 1.21
+
+require (
+	nhooyr.io/websocket v1.8.10
+)