opencode-skills-collection 4.1.14 → 4.1.16

package/bundled-skills/azure-cosmos-db-py/references/error-handling.md

@@ -0,0 +1,382 @@
+# Error Handling Patterns
+
+## Table of Contents
+
+1. [Cosmos Exception Types](#cosmos-exception-types)
+2. [Client-Level Error Handling](#client-level-error-handling)
+3. [Service-Level Error Handling](#service-level-error-handling)
+4. [Router-Level Error Mapping](#router-level-error-mapping)
+5. [Logging Patterns](#logging-patterns)
+6. [Retry Strategies](#retry-strategies)
+
+---
+
+## Cosmos Exception Types
+
+### Common Exceptions
+
+```python
+from azure.cosmos.exceptions import (
+    CosmosResourceNotFoundError,    # 404 - Document not found
+    CosmosResourceExistsError,      # 409 - Conflict (duplicate ID)
+    CosmosHttpResponseError,        # Base class for HTTP errors
+)
+```
+
+| Exception | HTTP Status | Common Cause |
+|-----------|-------------|--------------|
+| `CosmosResourceNotFoundError` | 404 | Document/container doesn't exist |
+| `CosmosResourceExistsError` | 409 | Document with ID already exists |
+| `CosmosHttpResponseError` | 429 | Rate limiting (too many RU) |
+| `CosmosHttpResponseError` | 503 | Service unavailable |
+
+---
+
+## Client-Level Error Handling
+
+Handle exceptions in the Cosmos client module:
+
+```python
+from azure.cosmos.exceptions import CosmosResourceNotFoundError, CosmosHttpResponseError
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+async def get_document(doc_id: str, partition_key: str) -> dict | None:
+    """Read a document. Returns None if not found."""
+    container = get_container()
+    if container is None:
+        return None
+
+    try:
+        result = await run_in_threadpool(
+            container.read_item,
+            item=doc_id,
+            partition_key=partition_key,
+        )
+        return result
+    except CosmosResourceNotFoundError:
+        # Expected case: document doesn't exist
+        return None
+    except CosmosHttpResponseError as e:
+        # Log unexpected errors but don't crash
+        logger.error(f"Cosmos error reading {doc_id}: {e.status_code} - {e.message}")
+        raise
+
+
+async def delete_document(doc_id: str, partition_key: str) -> bool:
+    """Delete a document. Returns True if deleted, False if not found."""
+    container = get_container()
+    if container is None:
+        return False
+
+    try:
+        await run_in_threadpool(
+            container.delete_item,
+            item=doc_id,
+            partition_key=partition_key,
+        )
+        return True
+    except CosmosResourceNotFoundError:
+        # Already deleted or never existed
+        return False
+
+
+async def upsert_document(doc: dict, partition_key: str) -> dict:
+    """Insert or update a document."""
+    container = get_container()
+    if container is None:
+        raise RuntimeError("Cosmos DB not initialized")
+
+    try:
+        result = await run_in_threadpool(container.upsert_item, doc)
+        return result
+    except CosmosResourceExistsError:
+        # Shouldn't happen with upsert, but handle just in case
+        logger.warning(f"Unexpected conflict upserting {doc.get('id')}")
+        raise
+```
+
+### Return Value Conventions
+
+| Scenario | Return Value |
+|----------|--------------|
+| Document found | `dict` (the document) |
+| Document not found | `None` |
+| Delete succeeded | `True` |
+| Delete target not found | `False` |
+| Cosmos unavailable | `None` or `False` (graceful) |
+| Unexpected error | Raise exception |
+
+---
+
+## Service-Level Error Handling
+
+Services interpret client results and apply business logic:
+
+```python
+class ProjectService:
+
+    async def get_by_id(self, project_id: str, workspace_id: str) -> Project | None:
+        """Get project. Returns None if not found or unavailable."""
+        if not self._use_cosmos():
+            return None
+
+        doc = await get_document(project_id, partition_key=workspace_id)
+        if doc is None:
+            return None
+
+        return self._doc_to_model(doc)
+
+    async def create(self, data: ProjectCreate, author_id: str) -> Project:
+        """Create project. Raises RuntimeError if Cosmos unavailable."""
+        if not self._use_cosmos():
+            raise RuntimeError("Database unavailable")
+
+        # ... create logic ...
+
+    async def update(
+        self, project_id: str, workspace_id: str, data: ProjectUpdate
+    ) -> Project | None:
+        """Update project. Returns None if not found."""
+        if not self._use_cosmos():
+            return None
+
+        doc = await get_document(project_id, partition_key=workspace_id)
+        if doc is None:
+            return None  # Not found
+
+        # ... update logic ...
+```
+
+### Graceful Degradation Pattern
+
+```python
+def _use_cosmos(self) -> bool:
+    """Check if Cosmos is available for use."""
+    return get_container() is not None
+
+async def list_projects(self, workspace_id: str) -> list[Project]:
+    """List projects. Returns empty list if unavailable."""
+    if not self._use_cosmos():
+        return []  # Graceful empty response
+
+    docs = await query_documents(
+        doc_type="project",
+        partition_key=workspace_id,
+    )
+    return [self._doc_to_model(doc) for doc in docs]
+```
+
+---
+
+## Router-Level Error Mapping
+
+Convert service results to HTTP responses:
+
+```python
+from fastapi import APIRouter, HTTPException, status, Depends
+
+router = APIRouter(prefix="/api/projects", tags=["projects"])
+
+
+@router.get("/{project_id}")
+async def get_project(
+    project_id: str,
+    workspace_id: str,
+    current_user: User = Depends(get_current_user_required),
+) -> Project:
+    """Get project by ID."""
+    project = await project_service.get_by_id(project_id, workspace_id)
+
+    if project is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Project not found",
+        )
+
+    return project
+
+
+@router.post("/", status_code=status.HTTP_201_CREATED)
+async def create_project(
+    data: ProjectCreate,
+    current_user: User = Depends(get_current_user_required),
+) -> Project:
+    """Create a new project."""
+    try:
+        return await project_service.create(data, author_id=current_user.id)
+    except RuntimeError as e:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=str(e),
+        )
+
+
+@router.put("/{project_id}")
+async def update_project(
+    project_id: str,
+    workspace_id: str,
+    data: ProjectUpdate,
+    current_user: User = Depends(get_current_user_required),
+) -> Project:
+    """Update project."""
+    project = await project_service.update(project_id, workspace_id, data)
+
+    if project is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Project not found",
+        )
+
+    return project
+
+
+@router.delete("/{project_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_project(
+    project_id: str,
+    workspace_id: str,
+    current_user: User = Depends(get_current_user_required),
+) -> None:
+    """Delete project."""
+    deleted = await project_service.delete(project_id, workspace_id)
+
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Project not found",
+        )
+```
+
+### HTTP Status Code Mapping
+
+| Service Result | HTTP Status | Response |
+|----------------|-------------|----------|
+| Success with data | 200 OK | JSON body |
+| Created | 201 Created | JSON body |
+| Deleted | 204 No Content | Empty |
+| Not found (`None`) | 404 Not Found | Error detail |
+| Validation error | 422 Unprocessable | Pydantic errors |
+| Database unavailable | 503 Service Unavailable | Error detail |
+
+---
+
+## Logging Patterns
+
+### Structured Logging
+
+```python
+import logging
+import traceback
+
+logger = logging.getLogger(__name__)
+
+
+def get_container() -> ContainerProxy | None:
+    global _cosmos_container, _init_attempted
+
+    if _init_attempted:
+        return _cosmos_container
+
+    _init_attempted = True
+
+    try:
+        client = _create_client(settings)
+        database = client.get_database_client(settings.cosmos_database_name)
+        _cosmos_container = database.get_container_client(settings.cosmos_container_id)
+        _cosmos_container.read()  # Verify connection
+
+        logger.info(
+            "Cosmos DB connected",
+            extra={
+                "database": settings.cosmos_database_name,
+                "container": settings.cosmos_container_id,
+                "endpoint": settings.cosmos_endpoint[:30] + "...",
+            }
+        )
+
+    except Exception as e:
+        logger.error(
+            "Cosmos DB connection failed",
+            extra={
+                "error_type": type(e).__name__,
+                "error_message": str(e),
+                "endpoint": settings.cosmos_endpoint[:30] + "...",
+            },
+            exc_info=True,  # Include stack trace
+        )
+        _cosmos_container = None
+
+    return _cosmos_container
+```
+
+### Log Levels
+
+| Scenario | Level | Example |
+|----------|-------|---------|
+| Connection established | INFO | "Cosmos DB connected" |
+| Document not found | DEBUG | "Project proj-123 not found" |
+| Validation error | WARNING | "Invalid partition key" |
+| Connection failed | ERROR | "Cosmos DB connection failed" |
+| Unexpected exception | ERROR | Full traceback |
+
+---
+
+## Retry Strategies
+
+### Azure SDK Built-in Retry
+
+The Cosmos SDK has built-in retry for transient errors (429, 503):
+
+```python
+from azure.cosmos import CosmosClient
+
+client = CosmosClient(
+    url=endpoint,
+    credential=credential,
+    connection_retry_policy={
+        "retry_total": 3,
+        "retry_backoff_factor": 0.8,
+    }
+)
+```
+
+### Custom Retry for Application Logic
+
+```python
+import asyncio
+from typing import TypeVar, Callable
+
+T = TypeVar("T")
+
+
+async def with_retry(
+    operation: Callable[[], T],
+    max_retries: int = 3,
+    base_delay: float = 0.5,
+) -> T:
+    """Execute operation with exponential backoff retry."""
+    last_error = None
+
+    for attempt in range(max_retries + 1):
+        try:
+            return await operation()
+        except CosmosHttpResponseError as e:
+            if e.status_code == 429:  # Rate limited
+                last_error = e
+                delay = base_delay * (2 ** attempt)
+                logger.warning(f"Rate limited, retrying in {delay}s (attempt {attempt + 1})")
+                await asyncio.sleep(delay)
+            else:
+                raise
+
+    raise last_error
+
+
+# Usage
+result = await with_retry(
+    lambda: upsert_document(doc, partition_key),
+    max_retries=3,
+)
+```

package/bundled-skills/azure-cosmos-db-py/references/partitioning.md

@@ -0,0 +1,270 @@
+# Partition Key Strategies
+
+## Table of Contents
+
+1. [Partition Key Fundamentals](#partition-key-fundamentals)
+2. [Common Strategies](#common-strategies)
+3. [Cross-Partition Queries](#cross-partition-queries)
+4. [Move Operations](#move-operations)
+5. [Query Optimization](#query-optimization)
+
+---
+
+## Partition Key Fundamentals
+
+### What is a Partition Key?
+
+The partition key determines data distribution and query efficiency:
+
+- **Same partition key** → Data co-located → Fast queries, transactional writes
+- **Different partition keys** → Data distributed → Cross-partition queries required
+
+### Choosing a Partition Key
+
+Good partition keys have:
+
+1. **High cardinality** — Many distinct values to distribute load
+2. **Even distribution** — No single value dominates storage/throughput
+3. **Query alignment** — Most queries filter by partition key
+
+---
+
+## Common Strategies
+
+### Strategy 1: Self-Partitioned Entities
+
+Use the entity's own ID when entities are accessed individually:
+
+```python
+# Workspaces partition by their own ID
+class WorkspaceInDB(BaseModel):
+    id: str                    # Also used as partition key
+    name: str
+    doc_type: str = "workspace"
+
+# Query always includes the workspace ID
+doc = await get_document(workspace_id, partition_key=workspace_id)
+```
+
+**Use for**: Top-level entities with no parent (workspaces, users)
+
+### Strategy 2: Parent-Scoped Partitioning
+
+Use parent entity ID for child entities accessed together:
+
+```python
+# Projects partition by workspace_id
+class ProjectInDB(BaseModel):
+    id: str
+    workspace_id: str          # Partition key
+    name: str
+    doc_type: str = "project"
+
+# All projects in a workspace are co-located
+projects = await query_documents(
+    doc_type="project",
+    partition_key=workspace_id,  # Efficient single-partition query
+)
+```
+
+**Use for**: Child entities frequently queried with parent (projects→workspace, flows→workspace)
+
+### Strategy 3: Global Partition
+
+Use a constant for cross-cutting entities:
+
+```python
+# Users and groups use "global" partition
+GLOBAL_PARTITION = "global"
+
+class UserInDB(BaseModel):
+    id: str
+    email: str
+    doc_type: str = "user"
+
+# Users are queried by email across all partitions
+user = await query_documents(
+    doc_type="user",
+    partition_key=GLOBAL_PARTITION,
+    extra_filter="AND c.email = @email",
+    parameters=[{"name": "@email", "value": email}],
+)
+```
+
+**Use for**: Entities accessed independently of hierarchy (users, groups, permissions)
+
+### Strategy Summary
+
+| Entity Type | Partition Key | Rationale |
+|-------------|---------------|-----------|
+| **Workspace** | `workspace.id` (self) | Independent top-level entity |
+| **User** | `"global"` | Accessed by email across workspaces |
+| **Group** | `"global"` | Cross-workspace access control |
+| **Project** | `workspace_id` | Always accessed within workspace context |
+| **Flow** | `workspace_id` | Co-located with parent project |
+| **Asset** | `owner_id` | User-scoped media assets |
+
+---
+
+## Cross-Partition Queries
+
+When partition key is unknown, enable cross-partition queries:
+
+```python
+async def query_documents(
+    doc_type: str,
+    partition_key: str | None = None,
+    extra_filter: str | None = None,
+    parameters: list[dict] | None = None,
+) -> list[dict]:
+    """Query documents, optionally across partitions."""
+    container = get_container()
+
+    query = "SELECT * FROM c WHERE c.docType = @docType"
+    query_params = [{"name": "@docType", "value": doc_type}]
+
+    if extra_filter:
+        query += f" {extra_filter}"
+        query_params.extend(parameters or [])
+
+    if partition_key:
+        # Efficient single-partition query
+        items = container.query_items(
+            query=query,
+            parameters=query_params,
+            partition_key=partition_key,
+        )
+    else:
+        # Cross-partition query (slower, higher RU cost)
+        items = container.query_items(
+            query=query,
+            parameters=query_params,
+            enable_cross_partition_query=True,
+        )
+
+    return await run_in_threadpool(list, items)
+```
+
+### When to Use Cross-Partition Queries
+
+| Scenario | Approach |
+|----------|----------|
+| Search by email | Cross-partition (email not in partition key) |
+| List user's workspaces | Cross-partition (user owns multiple workspaces) |
+| Admin dashboard | Cross-partition (aggregate across all) |
+| Project by ID in workspace | Single-partition (workspace_id known) |
+
+### Performance Considerations
+
+- **Single-partition**: ~1-5 RU per query
+- **Cross-partition**: ~N × single-partition RU (N = physical partitions)
+- Index cross-partition query fields for better performance
+
+---
+
+## Move Operations
+
+Moving entities between partitions requires delete + insert:
+
+```python
+async def move_project_to_workspace(
+    self,
+    project_id: str,
+    old_workspace_id: str,
+    new_workspace_id: str,
+) -> Project | None:
+    """Move project to a different workspace."""
+    # 1. Read from old partition
+    doc = await get_document(project_id, partition_key=old_workspace_id)
+    if doc is None:
+        return None
+
+    # 2. Update partition key value
+    model_in_db = self._doc_to_model_in_db(doc)
+    model_in_db.workspace_id = new_workspace_id
+    model_in_db.updated_at = datetime.now(timezone.utc)
+
+    # 3. Insert into new partition
+    new_doc = self._model_in_db_to_doc(model_in_db)
+    await upsert_document(new_doc, partition_key=new_workspace_id)
+
+    # 4. Delete from old partition
+    await delete_document(project_id, partition_key=old_workspace_id)
+
+    return self._model_in_db_to_model(model_in_db)
+```
+
+### Atomic Move with Transaction
+
+For critical moves, use transactional batch (same partition only):
+
+```python
+# Note: Batch only works within single partition
+# For cross-partition moves, implement saga pattern with compensation
+```
+
+---
+
+## Query Optimization
+
+### Index Policy Configuration
+
+Ensure frequently queried fields are indexed:
+
+```json
+{
+  "indexingMode": "consistent",
+  "includedPaths": [
+    { "path": "/docType/?" },
+    { "path": "/workspaceId/?" },
+    { "path": "/authorId/?" },
+    { "path": "/slug/?" },
+    { "path": "/email/?" },
+    { "path": "/tags/[]" }
+  ],
+  "excludedPaths": [
+    { "path": "/content/*" },
+    { "path": "/nodes/*" }
+  ]
+}
+```
+
+### Composite Indexes
+
+For queries with multiple filters and ORDER BY:
+
+```json
+{
+  "compositeIndexes": [
+    [
+      { "path": "/docType", "order": "ascending" },
+      { "path": "/createdAt", "order": "descending" }
+    ],
+    [
+      { "path": "/workspaceId", "order": "ascending" },
+      { "path": "/docType", "order": "ascending" },
+      { "path": "/name", "order": "ascending" }
+    ]
+  ]
+}
+```
+
+### Query Patterns
+
+```python
+# Efficient: Uses partition key + indexed field
+docs = await query_documents(
+    doc_type="project",
+    partition_key=workspace_id,
+    extra_filter="AND c.visibility = @visibility ORDER BY c.createdAt DESC",
+    parameters=[{"name": "@visibility", "value": "public"}],
+)
+
+# Less efficient: Cross-partition with unindexed field
+docs = await query_documents(
+    doc_type="project",
+    partition_key=None,  # Cross-partition
+    extra_filter="AND CONTAINS(c.description, @search)",  # Unindexed scan
+    parameters=[{"name": "@search", "value": "keyword"}],
+)
+```