omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/projectors/model_projector_column.py

@@ -0,0 +1,289 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Projector Column Model.
+
+Defines the schema for individual columns within a projection table.
+Used by ModelProjectorSchema to describe table structure for validation
+and migration SQL generation.
+
+NOTE: This model is temporarily defined in omnibase_infra until omnibase_core
+provides it at omnibase_core.models.projectors. Once available, this should
+be moved there and re-exported from this module.
+
+Related Tickets:
+    - OMN-1168: ProjectorPluginLoader contract discovery loading
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from omnibase_infra.models.projectors.util_sql_identifiers import (
+    IDENT_PATTERN,
+    quote_identifier,
+)
+
+
+class ModelProjectorColumn(BaseModel):
+    """Definition of a single column in a projection table.
+
+    Describes the column name, data type, constraints, and default value.
+    Used by ProjectorSchemaValidator for schema validation and migration
+    SQL generation.
+
+    Attributes:
+        name: Column name (snake_case by convention).
+        column_type: PostgreSQL data type for the column.
+        nullable: Whether the column allows NULL values (default: True).
+        default: Optional default value expression (SQL literal or expression).
+        primary_key: Whether this column is part of the primary key (default: False).
+
+    Example:
+        >>> column = ModelProjectorColumn(
+        ...     name="entity_id",
+        ...     column_type="uuid",
+        ...     nullable=False,
+        ...     primary_key=True,
+        ... )
+        >>> print(column.name)
+        'entity_id'
+    """
+
+    name: str = Field(
+        ...,
+        description="Column name (snake_case by convention)",
+        min_length=1,
+        max_length=128,
+    )
+
+    column_type: Literal[
+        "uuid",
+        "varchar",
+        "text",
+        "integer",
+        "bigint",
+        "timestamp",
+        "timestamptz",
+        "jsonb",
+        "boolean",
+    ] = Field(
+        ...,
+        description="PostgreSQL data type for the column",
+    )
+
+    nullable: bool = Field(
+        default=True,
+        description="Whether the column allows NULL values",
+    )
+
+    default: str | None = Field(
+        default=None,
+        description=(
+            "Default value expression (SQL literal or expression). "
+            "TRUST BOUNDARY: This field accepts raw SQL expressions (e.g., 'now()', "
+            "'true', 'gen_random_uuid()') and must only come from trusted contract.yaml "
+            "sources. Do NOT populate from user input. Line breaks are rejected to "
+            "prevent multi-statement injection."
+        ),
+    )
+
+    primary_key: bool = Field(
+        default=False,
+        description="Whether this column is part of the primary key",
+    )
+
+    length: int | None = Field(
+        default=None,
+        description=(
+            "Length for varchar columns (e.g., 128 for VARCHAR(128)). "
+            "Required when column_type='varchar' to prevent schema drift. "
+            "PostgreSQL maximum is 10485760, but values above 65535 are rarely needed."
+        ),
+        ge=1,
+        le=10485760,  # PostgreSQL maximum varchar length
+    )
+
+    description: str | None = Field(
+        default=None,
+        description="Optional human-readable description for SQL COMMENT",
+        max_length=1024,
+    )
+
+    model_config = {
+        "extra": "forbid",
+        # NOTE: frozen=True provides shallow immutability only. Fields with mutable
+        # types (e.g., list, dict) are protected from reassignment but their contents
+        # can still be modified. For this model, all fields are primitives (str, bool,
+        # int, None), so this limitation does not apply.
+        "frozen": True,
+    }
+
+    @field_validator("name")
+    @classmethod
+    def validate_name_identifier(cls, v: str) -> str:
+        """Validate that the column name is a valid PostgreSQL identifier.
+
+        Prevents SQL injection by ensuring the name matches the safe identifier
+        pattern (letters, digits, underscores, starting with letter or underscore).
+
+        Args:
+            v: Column name to validate.
+
+        Returns:
+            Validated column name.
+
+        Raises:
+            ValueError: If the name contains invalid characters.
+        """
+        if not IDENT_PATTERN.match(v):
+            raise ValueError(
+                f"Invalid column name '{v}': must match pattern "
+                "[A-Za-z_][A-Za-z0-9_]* (letters, digits, underscores only, "
+                "starting with letter or underscore)"
+            )
+        return v
+
+    @field_validator("default")
+    @classmethod
+    def validate_default(cls, v: str | None) -> str | None:
+        """Validate default value for SQL safety.
+
+        Prevents SQL injection by rejecting line breaks in default values.
+        Default values are raw SQL expressions by design (e.g., 'now()', 'true'),
+        so contract sources must be trusted. This validator prevents accidental
+        line breaks that could enable multi-statement injection.
+
+        Args:
+            v: Default value to validate.
+
+        Returns:
+            Validated default value.
+
+        Raises:
+            ValueError: If the default contains line breaks.
+        """
+        if v is None:
+            return v
+        if "\n" in v or "\r" in v:
+            raise ValueError("default value must not contain line breaks")
+        return v
+
+    @field_validator("description")
+    @classmethod
+    def validate_description(cls, v: str | None) -> str | None:
+        """Validate description for SQL safety.
+
+        Prevents SQL injection by rejecting line breaks in description values.
+        Descriptions are used in SQL COMMENT statements.
+
+        Args:
+            v: Description value to validate.
+
+        Returns:
+            Validated description value.
+
+        Raises:
+            ValueError: If the description contains line breaks.
+        """
+        if v is None:
+            return v
+        if "\n" in v or "\r" in v:
+            raise ValueError("description must not contain line breaks")
+        return v
+
+    @model_validator(mode="after")
+    def validate_varchar_has_length(self) -> ModelProjectorColumn:
+        """Validate that varchar columns specify an explicit length.
+
+        Prevents schema drift by requiring explicit length specification for
+        varchar columns. Without this, different environments might use
+        different defaults, causing migration inconsistencies.
+
+        Returns:
+            Self if validation passes.
+
+        Raises:
+            ValueError: If column_type is 'varchar' but length is not specified.
+        """
+        if self.column_type == "varchar" and self.length is None:
+            raise ValueError(
+                f"Column '{self.name}' with type 'varchar' must specify an explicit "
+                "length to prevent schema drift (e.g., length=255)"
+            )
+        return self
+
+    def to_sql_definition(self) -> str:
+        """Generate SQL column definition for CREATE TABLE statement.
+
+        Uses quoted identifiers to prevent SQL injection. If a description
+        is provided, appends an inline SQL comment.
+
+        Returns:
+            SQL column definition string (e.g., '"entity_id" UUID NOT NULL').
+            If description is set, includes inline comment:
+            '"entity_id" UUID NOT NULL  -- Unique identifier'
+
+        Example:
+            >>> column = ModelProjectorColumn(
+            ...     name="entity_id",
+            ...     column_type="uuid",
+            ...     nullable=False,
+            ... )
+            >>> column.to_sql_definition()
+            '"entity_id" UUID NOT NULL'
+
+            >>> column_with_desc = ModelProjectorColumn(
+            ...     name="name",
+            ...     column_type="varchar",
+            ...     length=255,
+            ...     description="Display name for the entity",
+            ... )
+            >>> column_with_desc.to_sql_definition()
+            '"name" VARCHAR(255)  -- Display name for the entity'
+
+        Security Notes:
+            - Column name is validated against PostgreSQL identifier pattern
+              during model construction and quoted in SQL output.
+            - The default field is a **TRUST BOUNDARY**: It accepts raw SQL
+              expressions by design (e.g., 'now()', 'gen_random_uuid()').
+              Only accept default values from trusted sources (contract.yaml).
+            - The description field is validated to reject line breaks and
+              is only used in SQL comments (safe context).
+        """
+        # Map column_type to PostgreSQL type with length
+        type_map: dict[str, str] = {
+            "uuid": "UUID",
+            "varchar": f"VARCHAR({self.length or 255})",
+            "text": "TEXT",
+            "integer": "INTEGER",
+            "bigint": "BIGINT",
+            "timestamp": "TIMESTAMP",
+            "timestamptz": "TIMESTAMPTZ",
+            "jsonb": "JSONB",
+            "boolean": "BOOLEAN",
+        }
+
+        sql_type = type_map[self.column_type]
+        # Quote the column name to prevent SQL injection
+        quoted_name = quote_identifier(self.name)
+        parts = [quoted_name, sql_type]
+
+        if not self.nullable:
+            parts.append("NOT NULL")
+
+        if self.default is not None:
+            # Note: default is trusted SQL expression from contract.yaml
+            parts.append(f"DEFAULT {self.default}")
+
+        definition = " ".join(parts)
+
+        # Add inline comment if description is provided
+        if self.description:
+            definition = f"{definition}  -- {self.description}"
+
+        return definition
+
+
+__all__ = ["ModelProjectorColumn"]

omnibase_infra/models/projectors/model_projector_discovery_result.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Projector discovery result model.
+
+Provides structured results for projector contract discovery operations,
+containing both successfully loaded projectors and any validation errors.
+
+Part of OMN-1168: ProjectorPluginLoader contract discovery loading.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+if TYPE_CHECKING:
+    from omnibase_infra.models.projectors.model_projector_validation_error import (
+        ModelProjectorValidationError,
+    )
+    from omnibase_infra.protocols.protocol_event_projector import (
+        ProtocolEventProjector,
+    )
+
+
+class ModelProjectorDiscoveryResult:
+    """Result of projector contract discovery.
+
+    Contains successfully loaded projectors and any validation errors
+    encountered during discovery.
+
+    Attributes:
+        projectors: List of successfully loaded projectors.
+        validation_errors: List of errors for failed contracts.
+        discovery_correlation_id: Correlation ID for the entire discovery operation.
+    """
+
+    def __init__(
+        self,
+        projectors: list[ProtocolEventProjector],
+        validation_errors: list[ModelProjectorValidationError],
+        discovery_correlation_id: UUID | None = None,
+    ) -> None:
+        """Initialize discovery result.
+
+        Args:
+            projectors: List of successfully loaded projectors.
+            validation_errors: List of errors for failed contracts.
+            discovery_correlation_id: Correlation ID for the entire discovery operation.
+        """
+        self.projectors = projectors
+        self.validation_errors = validation_errors
+        self.discovery_correlation_id = discovery_correlation_id
+
+    @property
+    def success_count(self) -> int:
+        """Number of successfully loaded projectors."""
+        return len(self.projectors)
+
+    @property
+    def error_count(self) -> int:
+        """Number of validation errors."""
+        return len(self.validation_errors)
+
+
+__all__ = ["ModelProjectorDiscoveryResult"]

omnibase_infra/models/projectors/model_projector_index.py

@@ -0,0 +1,270 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Projector Index Model.
+
+Defines the schema for database indexes on projection tables.
+Used by ModelProjectorSchema to describe index requirements for
+validation and migration SQL generation.
+
+NOTE: This model is temporarily defined in omnibase_infra until omnibase_core
+provides it at omnibase_core.models.projectors. Once available, this should
+be moved there and re-exported from this module.
+
+Related Tickets:
+    - OMN-1168: ProjectorPluginLoader contract discovery loading
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from omnibase_infra.models.projectors.util_sql_identifiers import (
+    IDENT_PATTERN,
+    quote_identifier,
+    validate_identifier,
+)
+
+
+class ModelProjectorIndex(BaseModel):
+    """Definition of a database index on a projection table.
+
+    Describes the index name, columns, type, and optional partial index
+    predicate. Used by ProjectorSchemaValidator for schema validation and
+    migration SQL generation.
+
+    Attributes:
+        name: Index name (must be unique within the database).
+        columns: List of column names included in the index.
+        index_type: PostgreSQL index type (btree, gin, hash).
+        unique: Whether the index enforces uniqueness (default: False).
+        where_clause: Optional partial index predicate (SQL expression).
+        description: Optional human-readable description for documentation.
+
+    Example:
+        >>> index = ModelProjectorIndex(
+        ...     name="idx_registration_capability_tags",
+        ...     columns=["capability_tags"],
+        ...     index_type="gin",
+        ... )
+        >>> print(index.name)
+        'idx_registration_capability_tags'
+    """
+
+    name: str = Field(
+        ...,
+        description="Index name (must be unique within the database)",
+        min_length=1,
+        max_length=128,
+    )
+
+    columns: list[str] = Field(
+        ...,
+        description="List of column names included in the index",
+        min_length=1,
+    )
+
+    index_type: Literal["btree", "gin", "hash"] = Field(
+        default="btree",
+        description="PostgreSQL index type",
+    )
+
+    unique: bool = Field(
+        default=False,
+        description="Whether the index enforces uniqueness",
+    )
+
+    where_clause: str | None = Field(
+        default=None,
+        description=(
+            "Optional partial index predicate (SQL expression). "
+            "TRUST BOUNDARY: This field accepts raw SQL and must only come from "
+            "trusted contract.yaml sources. Do NOT populate from user input. "
+            "Line breaks are rejected to prevent multi-statement injection."
+        ),
+    )
+
+    description: str | None = Field(
+        default=None,
+        description="Optional human-readable description for documentation purposes",
+        max_length=1024,
+    )
+
+    model_config = {
+        "extra": "forbid",
+        # NOTE: frozen=True provides shallow immutability only. The `columns` field
+        # is a list which is protected from reassignment, but list elements could
+        # theoretically be modified via index access (e.g., idx.columns[0] = "x").
+        # In practice, string elements are immutable, so this is not a concern.
+        # For deep immutability, use tuple instead of list.
+        "frozen": True,
+    }
+
+    @field_validator("name")
+    @classmethod
+    def validate_name_identifier(cls, v: str) -> str:
+        """Validate that the index name is a valid PostgreSQL identifier.
+
+        Prevents SQL injection by ensuring the name matches the safe identifier
+        pattern (letters, digits, underscores, starting with letter or underscore).
+
+        Args:
+            v: Index name to validate.
+
+        Returns:
+            Validated index name.
+
+        Raises:
+            ValueError: If the name contains invalid characters.
+        """
+        if not IDENT_PATTERN.match(v):
+            raise ValueError(
+                f"Invalid index name '{v}': must match pattern "
+                "[A-Za-z_][A-Za-z0-9_]* (letters, digits, underscores only, "
+                "starting with letter or underscore)"
+            )
+        return v
+
+    @field_validator("columns")
+    @classmethod
+    def validate_columns_not_empty(cls, v: list[str]) -> list[str]:
+        """Validate that columns list is not empty and contains valid names.
+
+        Validates each column name against the PostgreSQL identifier pattern
+        to prevent SQL injection.
+
+        Args:
+            v: List of column names.
+
+        Returns:
+            Validated list of column names.
+
+        Raises:
+            ValueError: If the list is empty or any column name is invalid.
+        """
+        if not v:
+            raise ValueError("Index must have at least one column")
+        for col in v:
+            if not col or not col.strip():
+                raise ValueError("Column name cannot be empty")
+            if not IDENT_PATTERN.match(col):
+                raise ValueError(
+                    f"Invalid column name '{col}': must match pattern "
+                    "[A-Za-z_][A-Za-z0-9_]* (letters, digits, underscores only, "
+                    "starting with letter or underscore)"
+                )
+        return v
+
+    @field_validator("where_clause")
+    @classmethod
+    def validate_where_clause(cls, v: str | None) -> str | None:
+        """Validate where_clause for SQL safety.
+
+        Prevents multi-statement injection by rejecting line breaks. The where_clause
+        is a trust boundary that accepts raw SQL expressions by design (for partial
+        index predicates), so contract sources must be trusted. This validator
+        prevents accidental line breaks that could enable multi-statement injection.
+
+        Args:
+            v: Where clause to validate.
+
+        Returns:
+            Validated where clause.
+
+        Raises:
+            ValueError: If the where_clause contains line breaks.
+        """
+        if v is None:
+            return v
+        if "\n" in v or "\r" in v:
+            raise ValueError("where_clause must not contain line breaks")
+        return v
+
+    @field_validator("description")
+    @classmethod
+    def validate_description(cls, v: str | None) -> str | None:
+        """Validate description for SQL safety.
+
+        Prevents potential injection by rejecting line breaks in description values.
+
+        Args:
+            v: Description value to validate.
+
+        Returns:
+            Validated description value.
+
+        Raises:
+            ValueError: If the description contains line breaks.
+        """
+        if v is None:
+            return v
+        if "\n" in v or "\r" in v:
+            raise ValueError("description must not contain line breaks")
+        return v
+
+    def to_sql_definition(self, table_name: str) -> str:
+        """Generate SQL CREATE INDEX statement.
+
+        Uses quoted identifiers for index name, table name, and column names
+        to prevent SQL injection. Validates table_name for defense-in-depth.
+
+        Args:
+            table_name: Name of the table to create the index on. Must be a valid
+                PostgreSQL identifier (letters, digits, underscores only).
+
+        Returns:
+            SQL CREATE INDEX statement with properly quoted identifiers.
+
+        Raises:
+            ValueError: If table_name is not a valid PostgreSQL identifier.
+
+        Example:
+            >>> index = ModelProjectorIndex(
+            ...     name="idx_registration_state",
+            ...     columns=["current_state"],
+            ...     index_type="btree",
+            ... )
+            >>> index.to_sql_definition("registration_projections")
+            'CREATE INDEX IF NOT EXISTS "idx_registration_state" ON "registration_projections" USING BTREE ("current_state")'
+
+        Security Notes:
+            - All identifiers (index name, table name, columns) are validated
+              against the PostgreSQL identifier pattern and quoted.
+            - The where_clause field is a **TRUST BOUNDARY**: It accepts raw SQL
+              expressions by design for partial index predicates. Only accept
+              where_clause values from trusted sources (contract.yaml files).
+              Untrusted input in where_clause could enable SQL injection.
+        """
+        # Defense-in-depth: validate table_name even though callers should validate
+        validate_identifier(table_name, "table name")
+
+        unique_clause = "UNIQUE " if self.unique else ""
+        # Always emit USING clause for explicitness, even for btree (the default)
+        # This makes the intent clear and prevents ambiguity in migrations
+        using_clause = f"USING {self.index_type.upper()}"
+        # Quote all column names to prevent SQL injection
+        columns_sql = ", ".join(quote_identifier(col) for col in self.columns)
+
+        # Quote index name and table name
+        quoted_index_name = quote_identifier(self.name)
+        quoted_table_name = quote_identifier(table_name)
+
+        parts = [
+            f"CREATE {unique_clause}INDEX IF NOT EXISTS {quoted_index_name}",
+            f"ON {quoted_table_name}",
+            using_clause,
+            f"({columns_sql})",
+        ]
+
+        if self.where_clause:
+            # TRUST BOUNDARY: where_clause is raw SQL from contract.yaml
+            # This enables partial index predicates like "deleted_at IS NULL"
+            # SECURITY: Only accept where_clause from trusted contract sources
+            # Do NOT accept user input here - it would enable SQL injection
+            parts.append(f"WHERE {self.where_clause}")
+
+        return " ".join(parts)
+
+
+__all__ = ["ModelProjectorIndex"]