hexastack-graphql 0.0.0__py3-none-any.whl

hexastack_graphql/__init__.py

@@ -0,0 +1,7 @@
+from hexastack_graphql import adapters, domain, infra
+
+__all__ = [
+    "adapters",
+    "domain",
+    "infra",
+]

hexastack_graphql/adapters/fastapi.py

@@ -0,0 +1,122 @@
+import importlib.util
+from typing import Any
+
+import strawberry
+from rodi import Container
+
+from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_cqrs.ports.buses import CommandBusPort, QueryBusPort
+from hexastack_graphql.domain.context import GraphQLContext
+
+__all__ = [
+    "create_graphql_router",
+    "mount_graphql_router",
+]
+
+
+def _require_fastapi() -> None:
+    """Guard against missing FastAPI installation.
+
+    Raises:
+        MissingDependencyError: If fastapi is not installed.
+    """
+    if importlib.util.find_spec("fastapi") is None:
+        raise MissingDependencyError(
+            "fastapi is required for FastAPI GraphQL integration. "
+            "Install via 'pip install hexastack-graphql[fastapi]'."
+        )
+
+
+def create_graphql_router(
+    schema: strawberry.Schema,
+    container: Container,
+    *,
+    command_bus: CommandBusPort | None = None,
+    query_bus: QueryBusPort | None = None,
+    graphiql: bool = True,
+) -> Any:
+    """Construct a Strawberry GraphQLRouter for FastAPI.
+
+    Notes/Architectural Intent:
+        Creates a FastAPI APIRouter subclass (GraphQLRouter) that dynamically
+        injects the rodi Container and CQRS message buses into Info.context for
+        every HTTP execution.
+
+    Args:
+        schema: Compiled strawberry.Schema instance.
+        container: rodi DI Container.
+        command_bus: Optional CommandBusPort instance.
+        query_bus: Optional QueryBusPort instance.
+        graphiql: If True, enables the GraphiQL interactive playground.
+
+    Returns:
+        Configured strawberry.fastapi.GraphQLRouter instance.
+
+    Raises:
+        MissingDependencyError: If fastapi is not installed.
+    """
+    _require_fastapi()
+    from starlette.requests import Request
+    from strawberry.fastapi import GraphQLRouter
+
+    async def get_context(request: Request) -> GraphQLContext:
+        # Dynamically resolve buses from container if not passed explicitly
+        c_bus = command_bus
+        if c_bus is None and container is not None:
+            try:
+                c_bus = container.resolve(CommandBusPort)
+            except Exception:  # noqa: BLE001
+                c_bus = None
+
+        q_bus = query_bus
+        if q_bus is None and container is not None:
+            try:
+                q_bus = container.resolve(QueryBusPort)
+            except Exception:  # noqa: BLE001
+                q_bus = None
+
+        ctx = GraphQLContext(
+            container=container,
+            command_bus=c_bus,
+            query_bus=q_bus,
+        )
+        ctx.request = request
+        return ctx
+
+    return GraphQLRouter(
+        schema=schema,
+        context_getter=get_context,
+        graphql_ide="graphiql" if graphiql else None,
+    )
+
+
+def mount_graphql_router(
+    app: Any,
+    schema: strawberry.Schema,
+    container: Container,
+    *,
+    path: str = "/graphql",
+    graphiql: bool = True,
+) -> None:
+    """Mount Strawberry GraphQL router directly onto a FastAPI application instance.
+
+    Args:
+        app: Target FastAPI application instance.
+        schema: Compiled strawberry.Schema.
+        container: rodi DI Container.
+        path: Route prefix for GraphQL endpoints. Defaults to "/graphql".
+        graphiql: If True, enables GraphiQL playground.
+
+    Returns:
+        None.
+
+    Raises:
+        MissingDependencyError: If fastapi is not installed.
+    """
+    _require_fastapi()
+    router = create_graphql_router(
+        schema=schema,
+        container=container,
+        graphiql=graphiql,
+    )
+    app.include_router(router, prefix=path)

hexastack_graphql/domain/context.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from strawberry.fastapi.context import BaseContext
+
+
+@dataclass
+class GraphQLContext(BaseContext):
+    """Execution context injected into Strawberry GraphQL resolvers.
+
+    Notes/Architectural Intent:
+        Carries the rodi DI container and CQRS command/query buses into
+        field resolvers, enabling clean dispatching from GraphQL queries
+        and mutations. Inherits from Strawberry's BaseContext for full
+        FastAPI router integration.
+    """
+
+    container: Any | None = None
+    command_bus: Any | None = None
+    query_bus: Any | None = None
+    request: Any | None = None
+    properties: dict[str, Any] = field(default_factory=dict)
+
+
+__all__ = [
+    "GraphQLContext",
+]

hexastack_graphql/domain/exceptions.py

@@ -0,0 +1,25 @@
+from hexastack_core.domain.exceptions import HexastackError
+
+
+class GraphQLError(HexastackError):
+    """Base exception for all GraphQL adapter errors.
+
+    Notes/Architectural Intent:
+        Inherits from HexastackError to maintain unified exception hierarchy
+        across core and adapter layers.
+    """
+
+
+class SchemaBuildingError(GraphQLError):
+    """Exception raised when GraphQL schema construction or validation fails.
+
+    Notes/Architectural Intent:
+        Raised when no queries or mutations are registered, or when invalid
+        field definitions conflict during schema compilation.
+    """
+
+
+__all__ = [
+    "GraphQLError",
+    "SchemaBuildingError",
+]

hexastack_graphql/infra/autodiscovery.py

@@ -0,0 +1,106 @@
+import inspect
+from collections.abc import Sequence
+from types import ModuleType
+from typing import Any
+
+from hexastack_core.infra.autodiscovery import (
+    DiscoveryVisitor,
+    scan_modules,
+)
+from hexastack_graphql.infra.registries.schema import GraphQLSchemaRegistry
+
+_GRAPHQL_TYPE_ATTR = "__hexastack_graphql_type__"
+_GRAPHQL_FIELD_ATTR = "__hexastack_graphql_field__"
+
+
+class GraphQLTypeMetadata:
+    """Metadata container for decorated GraphQL root types."""
+
+    def __init__(self, kind: str) -> None:
+        self.kind = kind  # "query" or "mutation"
+
+
+class GraphQLFieldMetadata:
+    """Metadata container for decorated standalone GraphQL fields."""
+
+    def __init__(self, kind: str, name: str | None = None) -> None:
+        self.kind = kind  # "query" or "mutation"
+        self.name = name
+
+
+__all__ = [
+    "autodiscover_graphql_schema",
+    "create_graphql_visitor",
+    "GraphQLFieldMetadata",
+    "GraphQLTypeMetadata",
+]
+
+
+def _register_graphql_field(
+    obj: Any,
+    registry: GraphQLSchemaRegistry,
+) -> None:
+    """Register decorated GraphQL query or mutation field."""
+    field_meta: GraphQLFieldMetadata | None = getattr(obj, _GRAPHQL_FIELD_ATTR, None)
+    if field_meta is not None:
+        field_name = field_meta.name or getattr(obj, "__name__", "field")
+        if field_meta.kind == "query":
+            registry.register_query_field(field_name, obj)
+        elif field_meta.kind == "mutation":
+            registry.register_mutation_field(field_name, obj)
+
+
+def _register_graphql_type(
+    obj: type[Any],
+    registry: GraphQLSchemaRegistry,
+) -> None:
+    """Register decorated GraphQL query or mutation type."""
+    type_meta: GraphQLTypeMetadata | None = getattr(obj, _GRAPHQL_TYPE_ATTR, None)
+    if type_meta is not None:
+        if type_meta.kind == "query":
+            registry.register_query_type(obj)
+        elif type_meta.kind == "mutation":
+            registry.register_mutation_type(obj)
+
+
+def autodiscover_graphql_schema(
+    packages_to_scan: Sequence[str | ModuleType],
+    registry: GraphQLSchemaRegistry,
+) -> GraphQLSchemaRegistry:
+    """Discover decorated GraphQL components and register them into the schema registry.
+
+    Args:
+        packages_to_scan: Sequence of package names or module objects to inspect.
+        registry: Target GraphQLSchemaRegistry instance.
+
+    Returns:
+        The populated GraphQLSchemaRegistry instance.
+    """
+    visitor = create_graphql_visitor(registry)
+    scan_modules(packages_to_scan, [visitor])
+    return registry
+
+
+def create_graphql_visitor(
+    registry: GraphQLSchemaRegistry,
+) -> DiscoveryVisitor:
+    """Create a DiscoveryVisitor callback for single-pass GraphQL schema element discovery.
+
+    Notes/Architectural Intent:
+        Inspects discovered classes and functions for GraphQL decorator metadata,
+        registering query/mutation types and fields into the supplied schema registry
+        during single-pass reflection.
+
+    Args:
+        registry: Target GraphQLSchemaRegistry instance.
+
+    Returns:
+        DiscoveryVisitor callable accepting (member, module).
+    """
+
+    def visitor(obj: Any, module: ModuleType) -> None:
+        if inspect.isclass(obj):
+            _register_graphql_type(obj, registry)
+        _register_graphql_field(obj, registry)
+
+    return visitor

hexastack_graphql/infra/bootstrap.py

@@ -0,0 +1,113 @@
+import importlib.util
+from dataclasses import dataclass
+from typing import Any
+
+import strawberry
+
+from hexastack_core.infra.bootstrap import BootstrapContext
+from hexastack_core.infra.registries.config import ConfigRegistry
+from hexastack_core.ports.bootstrap import BootstrapperPort
+from hexastack_graphql.infra.autodiscovery import create_graphql_visitor
+from hexastack_graphql.infra.config import (
+    HexastackGraphQLConfig,
+    register_graphql_config,
+)
+from hexastack_graphql.infra.decorators import get_schema_registry
+from hexastack_graphql.infra.extensions import CorrelationExtension
+
+
+@dataclass(frozen=True)
+class GraphQLBootstrapResult:
+    """Dataclass holding compiled GraphQL schema and configuration."""
+
+    config: HexastackGraphQLConfig
+    schema: strawberry.Schema
+    router: Any | None = None
+
+
+class GraphQLBootstrapper(BootstrapperPort):
+    """Bootstrap extension compiling Strawberry schema and mounting FastAPI router.
+
+    Notes/Architectural Intent:
+        Implements BootstrapperPort with order=35 (executing after CQRS order=20
+        and FastAPI order=30), registering the autodiscovery visitor, assembling
+        the Strawberry Schema with telemetry extensions, and dynamically mounting
+        the GraphQL router into the FastAPI application if present.
+    """
+
+    name: str = "graphql"
+    order: int = 35
+
+    def configure(self, context: BootstrapContext) -> None:
+        """Phase 2: Register visitor, compile Strawberry schema, and mount into FastAPI.
+
+        Args:
+            context: BootstrapContext containing DI container, config, and properties.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        cfg = context.get_config("graphql", HexastackGraphQLConfig)
+
+        registry = get_schema_registry()
+
+        # Register visitor for single-pass reflective scanning (Phase 3)
+        visitor = create_graphql_visitor(registry)
+        context.register_visitor(visitor)
+
+        # 1. Compile schema from registry with CorrelationExtension class
+        extensions = [CorrelationExtension]
+        schema = registry.build_schema(extensions=extensions)
+
+        # 2. Register Schema and Registry into DI container
+        context.container.add_instance(schema, declared_class=strawberry.Schema)
+        context.container.add_instance(registry)
+
+        # 3. Mount onto FastAPI app if available and configured
+        router = None
+        if cfg.auto_mount_fastapi and importlib.util.find_spec("fastapi") is not None:
+            fastapi_app = context.properties.get("app")
+            if fastapi_app is not None:
+                from hexastack_graphql.adapters.fastapi import (
+                    create_graphql_router,
+                )
+
+                router = create_graphql_router(
+                    schema=schema,
+                    container=context.container,
+                    graphiql=cfg.graphiql,
+                )
+                fastapi_app.include_router(router, prefix=cfg.path)
+
+        # 4. Store in context properties
+        result = GraphQLBootstrapResult(
+            config=cfg,
+            schema=schema,
+            router=router,
+        )
+        context.properties["graphql_result"] = result
+        context.properties["graphql_schema"] = schema
+        context.properties["graphql_router"] = router
+
+    def register_config(self, registry: ConfigRegistry) -> None:
+        """Phase 1: Register GraphQL configuration schema under 'graphql'.
+
+        Args:
+            registry: Target ConfigRegistry instance.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        register_graphql_config(registry)
+
+
+__all__ = [
+    "GraphQLBootstrapper",
+    "GraphQLBootstrapResult",
+]

hexastack_graphql/infra/config.py

@@ -0,0 +1,60 @@
+from pydantic import BaseModel, Field
+
+from hexastack_core.infra.decorators import config_section
+from hexastack_core.infra.registries.config import ConfigRegistry
+
+
+@config_section("graphql")
+class HexastackGraphQLConfig(BaseModel):
+    """Configuration schema for Hexastack Strawberry GraphQL adapter.
+
+    Notes/Architectural Intent:
+        Controls GraphQL routing, GraphiQL interactive playground, mutation enabling,
+        and automatic mounting into FastAPI applications.
+    """
+
+    path: str = Field(
+        default="/graphql",
+        description="HTTP path prefix for GraphQL queries and mutations.",
+    )
+    graphiql: bool = Field(
+        default=True,
+        description="Enable interactive GraphiQL web interface.",
+    )
+    allow_queries: bool = Field(
+        default=True,
+        description="Enable GraphQL query execution.",
+    )
+    allow_mutations: bool = Field(
+        default=True,
+        description="Enable GraphQL mutation execution.",
+    )
+    auto_mount_fastapi: bool = Field(
+        default=True,
+        description="Automatically mount GraphQLRouter into FastAPI application during bootstrap.",
+    )
+    title: str = Field(
+        default="Hexastack GraphQL API",
+        description="GraphQL schema / API title.",
+    )
+
+
+__all__ = [
+    "HexastackGraphQLConfig",
+    "register_graphql_config",
+]
+
+
+def register_graphql_config(registry: ConfigRegistry) -> None:
+    """Register GraphQL configuration schema under 'graphql'.
+
+    Args:
+        registry: Target ConfigRegistry instance.
+
+    Returns:
+        None.
+
+    Raises:
+        None.
+    """
+    registry.register_config_section("graphql", HexastackGraphQLConfig)

hexastack_graphql/infra/decorators.py

@@ -0,0 +1,212 @@
+from collections.abc import Callable
+from typing import Any, cast
+
+import strawberry
+
+from hexastack_core.ports.feature_flags import FeatureFlagPort
+from hexastack_graphql.infra.autodiscovery import (
+    _GRAPHQL_FIELD_ATTR,
+    _GRAPHQL_TYPE_ATTR,
+    GraphQLFieldMetadata,
+    GraphQLTypeMetadata,
+)
+from hexastack_graphql.infra.registries.schema import GraphQLSchemaRegistry
+
+_default_registry = GraphQLSchemaRegistry()
+
+
+__all__ = [
+    "feature_flag_field",
+    "get_schema_registry",
+    "graphql_mutation",
+    "graphql_mutation_type",
+    "graphql_query",
+    "graphql_query_type",
+]
+
+
+def _resolve_flags(args: tuple[Any, ...], kwargs: dict[str, Any]) -> FeatureFlagPort:
+    """Helper to extract FeatureFlagPort from arguments context or fallback to ConfigFeatureFlagAdapter."""
+    from hexastack_core.adapters.feature_flags.config import ConfigFeatureFlagAdapter
+    from hexastack_core.ports.feature_flags import FeatureFlagPort
+
+    for item in (*args, *kwargs.values()):
+        if hasattr(item, "context") and getattr(item.context, "container", None):
+            container = item.context.container
+            if FeatureFlagPort in container:
+                return container.resolve(FeatureFlagPort)
+            break
+    return ConfigFeatureFlagAdapter()
+
+
+def feature_flag_field(
+    flag_key: str,
+    *,
+    default: bool = False,
+    fallback: Any = None,
+    raise_error: bool = True,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Wrap a Strawberry GraphQL field resolver with dynamic feature flag evaluation.
+
+    Notes/Architectural Intent:
+        Evaluates the specified feature flag against ambient UserContext / GraphQLContext.
+        If disabled:
+        - If raise_error is True, raises a GraphQLError with a descriptive message.
+        - If raise_error is False, returns fallback value (e.g. None).
+
+    Args:
+        flag_key: Unique identifier of the feature flag to check.
+        default: Fallback boolean value if flag is not explicitly configured.
+        fallback: Value to return if flag is disabled and raise_error is False (defaults to None).
+        raise_error: Whether to raise a GraphQLError when disabled (defaults to True).
+
+    Returns:
+        Decorator wrapping the GraphQL resolver function.
+    """
+    import inspect
+    from functools import wraps
+
+    from hexastack_core.domain.feature_flags import EvaluationContext
+    from hexastack_graphql.domain.exceptions import GraphQLError
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        if inspect.iscoroutinefunction(fn):
+
+            @wraps(fn)
+            async def async_wrapped(*args: Any, **kwargs: Any) -> Any:
+                flags = _resolve_flags(args, kwargs)
+                eval_ctx = EvaluationContext.from_current_context()
+                if not flags.is_enabled(flag_key, default=default, context=eval_ctx):
+                    if raise_error:
+                        raise GraphQLError(
+                            f"GraphQL field is disabled by feature flag '{flag_key}'."
+                        )
+                    return fallback
+                return await fn(*args, **kwargs)
+
+            return async_wrapped
+
+        @wraps(fn)
+        def sync_wrapped(*args: Any, **kwargs: Any) -> Any:
+            flags = _resolve_flags(args, kwargs)
+            eval_ctx = EvaluationContext.from_current_context()
+            if not flags.is_enabled(flag_key, default=default, context=eval_ctx):
+                if raise_error:
+                    raise GraphQLError(
+                        f"GraphQL field is disabled by feature flag '{flag_key}'."
+                    )
+                return fallback
+            return fn(*args, **kwargs)
+
+        return sync_wrapped
+
+    return decorator
+
+
+def get_schema_registry() -> GraphQLSchemaRegistry:
+    """Return the global default GraphQLSchemaRegistry instance.
+
+    Returns:
+        GraphQLSchemaRegistry instance.
+    """
+    return _default_registry
+
+
+def graphql_mutation(
+    name: str | None = None,
+    *,
+    description: str | None = None,
+) -> Callable[[Callable[..., Any]], Any]:
+    """Decorator registering a standalone function as a root GraphQL mutation field.
+
+    Args:
+        name: Optional custom field name.
+        description: Optional GraphQL documentation description.
+
+    Returns:
+        Decorator function.
+    """
+
+    def decorator(fn: Callable[..., Any]) -> Any:
+        field_name = name or getattr(fn, "__name__", "field")
+        s_field = strawberry.mutation(fn, name=field_name, description=description)
+        setattr(
+            s_field,
+            _GRAPHQL_FIELD_ATTR,
+            GraphQLFieldMetadata(kind="mutation", name=field_name),
+        )
+        _default_registry.register_mutation_field(field_name, s_field)
+        return s_field
+
+    return decorator
+
+
+def graphql_mutation_type[T: type[Any]](cls: T) -> T:
+    """Decorator registering a class as a root Mutation type.
+
+    Notes/Architectural Intent:
+        Automatically applies @strawberry.type if not already applied,
+        attaches discovery metadata, and registers in the default schema registry.
+
+    Args:
+        cls: Target class containing mutation fields.
+
+    Returns:
+        Decorated Strawberry type class.
+    """
+    wrapped: Any = cls
+    if not hasattr(cls, "__strawberry_definition__"):
+        wrapped = strawberry.type(cls)
+    setattr(wrapped, _GRAPHQL_TYPE_ATTR, GraphQLTypeMetadata(kind="mutation"))
+    _default_registry.register_mutation_type(cast("type[Any]", wrapped))
+    return cast("T", wrapped)
+
+
+def graphql_query(
+    name: str | None = None,
+    *,
+    description: str | None = None,
+) -> Callable[[Callable[..., Any]], Any]:
+    """Decorator registering a standalone function as a root GraphQL query field.
+
+    Args:
+        name: Optional custom field name.
+        description: Optional GraphQL documentation description.
+
+    Returns:
+        Decorator function.
+    """
+
+    def decorator(fn: Callable[..., Any]) -> Any:
+        field_name = name or getattr(fn, "__name__", "field")
+        s_field = strawberry.field(fn, name=field_name, description=description)
+        setattr(
+            s_field,
+            _GRAPHQL_FIELD_ATTR,
+            GraphQLFieldMetadata(kind="query", name=field_name),
+        )
+        _default_registry.register_query_field(field_name, s_field)
+        return s_field
+
+    return decorator
+
+
+def graphql_query_type[T: type[Any]](cls: T) -> T:
+    """Decorator registering a class as a root Query type.
+
+    Notes/Architectural Intent:
+        Automatically applies @strawberry.type if not already applied,
+        attaches discovery metadata, and registers in the default schema registry.
+
+    Args:
+        cls: Target class containing query fields.
+
+    Returns:
+        Decorated Strawberry type class.
+    """
+    wrapped: Any = cls
+    if not hasattr(cls, "__strawberry_definition__"):
+        wrapped = strawberry.type(cls)
+    setattr(wrapped, _GRAPHQL_TYPE_ATTR, GraphQLTypeMetadata(kind="query"))
+    _default_registry.register_query_type(cast("type[Any]", wrapped))
+    return cast("T", wrapped)

hexastack_graphql/infra/extensions.py

@@ -0,0 +1,26 @@
+from typing import Any
+
+from strawberry.extensions import SchemaExtension
+
+from hexastack_core.utils.context import get_correlation_id
+
+
+class CorrelationExtension(SchemaExtension):
+    """Strawberry Schema Extension injecting correlation ID into GraphQL execution result.
+
+    Notes/Architectural Intent:
+        Aligns GraphQL execution with REST and CQRS telemetry by attaching
+        the active async context's correlation_id into the GraphQL 'extensions' payload.
+    """
+
+    def get_results(self) -> dict[str, Any]:
+        """Return extension dictionary to be merged into GraphQL ExecutionResult."""
+        cid = get_correlation_id()
+        if cid:
+            return {"correlation_id": cid}
+        return {}
+
+
+__all__ = [
+    "CorrelationExtension",
+]

hexastack_graphql/infra/registries/schema.py

@@ -0,0 +1,151 @@
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import strawberry
+from strawberry.extensions import SchemaExtension
+from strawberry.types import Info
+
+from hexastack_graphql.domain.context import GraphQLContext
+from hexastack_graphql.domain.exceptions import SchemaBuildingError
+
+
+class GraphQLSchemaRegistry:
+    """Registry maintaining registered GraphQL query types, mutation types, and fields.
+
+    Notes/Architectural Intent:
+        Aggregates modular GraphQL query and mutation fields registered across
+        distributed application modules, compiling them into a unified strawberry.Schema.
+    """
+
+    def __init__(self) -> None:
+        """Initialize empty schema registry."""
+        self._query_types: list[type[Any]] = []
+        self._mutation_types: list[type[Any]] = []
+        self._query_fields: dict[str, Any] = {}
+        self._mutation_fields: dict[str, Any] = {}
+        self._custom_schema: strawberry.Schema | None = None
+
+    def _build_mutation_root(self) -> type[Any] | None:
+        """Assemble composite GraphQL Mutation root type if any mutations registered."""
+        if self._mutation_types:
+            if len(self._mutation_types) == 1 and not self._mutation_fields:
+                return self._mutation_types[0]
+            bases = tuple(self._mutation_types)
+            MutationType = type("Mutation", bases, dict(self._mutation_fields))
+            return strawberry.type(MutationType)
+
+        if self._mutation_fields:
+            MutationType = type("Mutation", (), dict(self._mutation_fields))
+            return strawberry.type(MutationType)
+
+        return None
+
+    def _build_query_root(self) -> type[Any]:
+        """Assemble composite or fallback GraphQL Query root type."""
+        if self._query_types:
+            if len(self._query_types) == 1 and not self._query_fields:
+                return self._query_types[0]
+            bases = tuple(self._query_types)
+            fields = dict(self._query_fields)
+            QueryType = type("Query", bases, fields)
+            return strawberry.type(QueryType)
+
+        if self._query_fields:
+            QueryType = type("Query", (), dict(self._query_fields))
+            return strawberry.type(QueryType)
+
+        @strawberry.type
+        class DefaultQuery:
+            @strawberry.field
+            def ping(self, info: Info[GraphQLContext, Any]) -> str:
+                return "pong"
+
+        return DefaultQuery
+
+    def build_schema(
+        self,
+        extensions: Sequence[type[SchemaExtension] | Callable[[], SchemaExtension]]
+        | None = None,
+    ) -> strawberry.Schema:
+        """Assemble all registered types and fields into a strawberry.Schema.
+
+        Args:
+            extensions: Optional list of strawberry SchemaExtension classes or instances.
+
+        Returns:
+            The compiled strawberry.Schema instance.
+
+        Raises:
+            SchemaBuildingError: If schema assembly or validation fails.
+        """
+        if self._custom_schema is not None:
+            return self._custom_schema
+
+        query_cls = self._build_query_root()
+        mutation_cls = self._build_mutation_root()
+
+        try:
+            return strawberry.Schema(
+                query=query_cls,
+                mutation=mutation_cls,
+                extensions=extensions or (),
+            )
+        except Exception as e:
+            raise SchemaBuildingError(f"Failed to build GraphQL schema: {e}") from e
+
+    def clear(self) -> None:
+        """Clear all registered schema components (used for test isolation)."""
+        self._query_types.clear()
+        self._mutation_types.clear()
+        self._query_fields.clear()
+        self._mutation_fields.clear()
+        self._custom_schema = None
+
+    def register_mutation_field(self, name: str, field_def: Any) -> None:
+        """Register an individual mutation field or resolver function.
+
+        Args:
+            name: Field name.
+            field_def: Strawberry field or resolver function.
+        """
+        self._mutation_fields[name] = field_def
+
+    def register_mutation_type(self, cls: type[Any]) -> None:
+        """Register a Strawberry type class containing mutation fields.
+
+        Args:
+            cls: A class decorated with @strawberry.type.
+        """
+        if cls not in self._mutation_types:
+            self._mutation_types.append(cls)
+
+    def register_query_field(self, name: str, field_def: Any) -> None:
+        """Register an individual query field or resolver function.
+
+        Args:
+            name: Field name.
+            field_def: Strawberry field or resolver function.
+        """
+        self._query_fields[name] = field_def
+
+    def register_query_type(self, cls: type[Any]) -> None:
+        """Register a Strawberry type class containing query fields.
+
+        Args:
+            cls: A class decorated with @strawberry.type.
+        """
+        if cls not in self._query_types:
+            self._query_types.append(cls)
+
+    def set_custom_schema(self, schema: strawberry.Schema) -> None:
+        """Explicitly override with a pre-constructed Strawberry Schema.
+
+        Args:
+            schema: Pre-configured strawberry.Schema instance.
+        """
+        self._custom_schema = schema
+
+
+__all__ = [
+    "GraphQLSchemaRegistry",
+]

hexastack_graphql/infra/resolvers.py

@@ -0,0 +1,69 @@
+from strawberry.types import Info
+
+from hexastack_core.domain.command import Command
+from hexastack_core.domain.query import Query
+from hexastack_graphql.domain.context import GraphQLContext
+from hexastack_graphql.domain.exceptions import GraphQLError
+
+__all__ = [
+    "dispatch_command",
+    "dispatch_query",
+]
+
+
+def dispatch_command[T](
+    info: Info[GraphQLContext, None],
+    command: Command,
+) -> T:
+    """Dispatch a CQRS command from inside a Strawberry field resolver.
+
+    Notes/Architectural Intent:
+        Resolves CommandBusPort from info.context and dispatches the command,
+        returning the handler's result with type inference.
+
+    Args:
+        info: Strawberry execution Info object containing GraphQLContext.
+        command: Concrete Command instance to dispatch.
+
+    Returns:
+        The command execution result.
+
+    Raises:
+        GraphQLError: If CommandBusPort is not configured in context.
+    """
+    bus = info.context.command_bus
+    if bus is None:
+        raise GraphQLError(
+            "CommandBusPort is not available in GraphQLContext. "
+            "Ensure hexastack-cqrs is configured."
+        )
+    return bus.dispatch(command)  # type: ignore[no-any-return]
+
+
+def dispatch_query[T](
+    info: Info[GraphQLContext, None],
+    query: Query,
+) -> T:
+    """Dispatch a CQRS query from inside a Strawberry field resolver.
+
+    Notes/Architectural Intent:
+        Resolves QueryBusPort from info.context and dispatches the query,
+        returning the handler's result with type inference.
+
+    Args:
+        info: Strawberry execution Info object containing GraphQLContext.
+        query: Concrete Query instance to dispatch.
+
+    Returns:
+        The query execution result.
+
+    Raises:
+        GraphQLError: If QueryBusPort is not configured in context.
+    """
+    bus = info.context.query_bus
+    if bus is None:
+        raise GraphQLError(
+            "QueryBusPort is not available in GraphQLContext. "
+            "Ensure hexastack-cqrs is configured."
+        )
+    return bus.dispatch(query)  # type: ignore[no-any-return]

hexastack_graphql-0.0.0.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.3
+Name: hexastack-graphql
+Version: 0.0.0
+Summary: Strawberry GraphQL presentation adapter and CQRS integration for Hexastack
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: strawberry-graphql>=0.260.0
+Requires-Dist: fastapi>=0.141.1 ; extra == 'fastapi'
+Requires-Dist: hexastack-fastapi ; extra == 'fastapi'
+Requires-Python: >=3.13
+Provides-Extra: fastapi
+Description-Content-Type: text/markdown
+
+# hexastack-graphql
+
+> Strawberry GraphQL presentation adapter and CQRS integration for Hexastack.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-graphql` brings the power and type-safety of [Strawberry GraphQL](https://strawberry.rocks/) into the Hexastack architecture:
+
+- **Type-Safe GraphQL Schemas**: Native Python dataclass-based GraphQL schema definition via Strawberry.
+- **CQRS Integration via Context**: Injects the `rodi.Container`, `CommandBusPort`, and `QueryBusPort` directly into Strawberry's `Info.context` (`GraphQLContext`).
+- **Declarative Query & Mutation Registries**:
+  - `@graphql_query_type` and `@graphql_mutation_type`: Register whole type classes to be merged into root Query and Mutation types.
+  - `@graphql_query` and `@graphql_mutation`: Register standalone resolver functions as top-level fields.
+- **Dynamic Field Resolver Feature Flagging**:
+  - `@feature_flag_field("flag_key", raise_error=True, fallback=...)`: Evaluates feature flags dynamically before executing field resolvers, raising a `GraphQLError` or returning a safe fallback value.
+- **FastAPI Mount & GraphiQL Playground**: Seamless mounting as a `GraphQLRouter` into FastAPI applications with interactive GraphiQL playground enabled.
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_graphql/
+├── domain/          # GraphQLContext, GraphQLError, SchemaBuildingError
+├── ports/           # GraphQLContextFactoryPort
+├── adapters/        # create_graphql_router, mount_graphql_router (FastAPI integration)
+└── infra/
+    ├── bootstrap.py # GraphQLBootstrapper (order=35)
+    ├── config.py    # HexastackGraphQLConfig
+    ├── decorators.py# @graphql_query, @graphql_mutation, @graphql_query_type, @graphql_mutation_type, @feature_flag_field
+    └── registries/  # schema.py (GraphQLSchemaRegistry)
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Bootstrap** | `GraphQLBootstrapper` (order=35), `HexastackGraphQLConfig` |
+| **Context & Domain** | `GraphQLContext`, `GraphQLError`, `SchemaBuildingError` |
+| **Decorators** | `@graphql_query`, `@graphql_mutation`, `@graphql_query_type`, `@graphql_mutation_type`, `@feature_flag_field` |
+| **FastAPI Adapters** | `create_graphql_router`, `mount_graphql_router` |
+| **Registries** | `GraphQLSchemaRegistry`, `get_schema_registry` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph ClientRequests ["GraphQL Client Requests"]
+        CLIENT["Web / Mobile GraphQL Clients"]
+    end
+
+    subgraph GraphQLAdapter ["hexastack-graphql"]
+        SCHEMA["strawberry.Schema"]
+        CTX["GraphQLContext (Container + Buses)"]
+        ROUTER["GraphQLRouter (FastAPI integration)"]
+    end
+
+    subgraph ApplicationLayer ["hexastack-cqrs"]
+        CBUS["CommandBusPort"]
+        QBUS["QueryBusPort"]
+    end
+
+    subgraph WebServer ["hexastack-fastapi"]
+        FASTAPI_APP["FastAPI Application"]
+    end
+
+    CLIENT --> ROUTER
+    FASTAPI_APP --> ROUTER
+    ROUTER --> SCHEMA
+    SCHEMA --> CTX
+    CTX -->|dispatches commands/queries to| CBUS
+    CTX -->|dispatches commands/queries to| QBUS
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: DI container, configuration registry, base exceptions.
+- `hexastack-cqrs`: `CommandBusPort` and `QueryBusPort` for message dispatching.
+- `strawberry-graphql>=0.260.0`: Core GraphQL engine and schema generator.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **FastAPI Auto-Mounting**: `GraphQLBootstrapper` (order=35) discovers the `FastAPI` instance created by `FastApiBootstrapper` (order=30) and attaches the `GraphQLRouter` automatically if `auto_mount_fastapi=true`.
+- **CQRS Dispatching**: Field resolvers receive `info.context.query_bus` and `info.context.command_bus` to delegate execution into the CQRS pipeline.
+
+### Optional Integrations (Extras)
+- `[fastapi]`: Installs `hexastack-fastapi` and `fastapi>=0.141.1` for HTTP routing and GraphiQL playground.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone install
+pip install hexastack-graphql
+
+# With FastAPI integration
+pip install "hexastack-graphql[fastapi]"
+
+# Via umbrella package
+pip install "hexastack[graphql]"
+```
+
+---
+
+## 5. Configuration Reference
+
+```toml
+[hexastack.graphql]
+path = "/graphql" # Route prefix for GraphQL endpoint
+graphiql = true # Enable interactive GraphiQL web UI
+allow_queries = true
+allow_mutations = true
+auto_mount_fastapi = true # Auto mount onto FastAPI application on bootstrap
+title = "Hexastack GraphQL API"
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from dataclasses import dataclass
+import strawberry
+from strawberry.types import Info
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_cqrs.domain.query import Query
+from hexastack_cqrs.infra.decorators import query_handler
+from hexastack_graphql.domain.context import GraphQLContext
+from hexastack_graphql.infra.decorators import graphql_query_type
+
+
+# 1. Define CQRS Query & Handler
+@dataclass(frozen=True)
+class GetItemQuery(Query):
+    item_id: str
+
+
+@query_handler(GetItemQuery)
+class GetItemHandler:
+    def __call__(self, qry: GetItemQuery) -> dict:
+        return {"id": qry.item_id, "name": f"Item {qry.item_id}"}
+
+
+# 2. Define Strawberry GraphQL Type
+@strawberry.type
+class ItemType:
+    id: str
+    name: str
+
+
+@graphql_query_type
+class Query:
+    @strawberry.field
+    def item(self, info: Info[GraphQLContext, None], item_id: str) -> ItemType:
+        res = info.context.query_bus.dispatch(GetItemQuery(item_id=item_id))
+        return ItemType(id=res["id"], name=res["name"])
+
+
+# 3. Bootstrap Runtime with GraphQL
+runtime = bootstrap(packages_to_scan=[__name__])
+schema = runtime.get("graphql_schema")
+
+result = schema.execute_sync(
+    '{ item(itemId: "123") { id name } }',
+    context_value=GraphQLContext(
+        container=runtime.container, query_bus=runtime.get("query_bus")
+    ),
+)
+print(result.data)  # {'item': {'id': '123', 'name': 'Item 123'}}
+```

hexastack_graphql-0.0.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+hexastack_graphql/__init__.py,sha256=xCfNCPXPMLP3z745T4Efk3YIJrulBlDhIG0ylRrntMg,112
+hexastack_graphql/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hexastack_graphql/adapters/fastapi.py,sha256=QRzLTULYTvfn5UoTnkm-Nd5JlJewNYr164nc9Zg9BEg,3568
+hexastack_graphql/domain/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hexastack_graphql/domain/context.py,sha256=0wWrvnVmWKF3KjJeWA64uhDvqCbNeEcd8CtU-YA2DCA,758
+hexastack_graphql/domain/exceptions.py,sha256=Ub-znwr6qlQhKvzyM6sDU5ajsUHsEkFtv1NsAAhnOvk,673
+hexastack_graphql/infra/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hexastack_graphql/infra/autodiscovery.py,sha256=xfyzgek_cr2WKJ6m1OM094_msklAieCMqw2x1T_RcG0,3297
+hexastack_graphql/infra/bootstrap.py,sha256=XhiJNoLJJLi8qHR2Q8qgHHQHsud6ReFPeXHKmwsHbog,3734
+hexastack_graphql/infra/config.py,sha256=a0xH-Bf0f7bsTaP65V2KVstbB3OYK1YjTdzZhXOEqX4,1669
+hexastack_graphql/infra/decorators.py,sha256=JmCr8iyJtkFfNnRTun61W23VY6GMTEknmYyCXLnL0Nw,7106
+hexastack_graphql/infra/extensions.py,sha256=H1T_rWaN7I-QbYotwHDrg-EJ1tivOu8EwAIVJugSH-k,765
+hexastack_graphql/infra/registries/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hexastack_graphql/infra/registries/schema.py,sha256=MAtfbNsy4qNysQouiEi8G_hB88kDzzgXoP769U4rpEw,5275
+hexastack_graphql/infra/resolvers.py,sha256=4tw7E1YnBNiiWgJ1ZBL5xD6Y0Jkjf_8YGbC_54Zh6a4,2079
+hexastack_graphql-0.0.0.dist-info/WHEEL,sha256=EmLkUISDECbcUx3FMCYOqokNOJqNp2r0d4mJzjErvvs,80
+hexastack_graphql-0.0.0.dist-info/entry_points.txt,sha256=QIRZICASiqhHa1vQ2BZ8xPZgKu_n78U0HM-XpwZV2X4,91
+hexastack_graphql-0.0.0.dist-info/METADATA,sha256=6m585j1WU5bWeOVCSWs88wwcxaEoF7NNbWQTGqyyY7k,6566
+hexastack_graphql-0.0.0.dist-info/RECORD,,

hexastack_graphql-0.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.3
+Root-Is-Purelib: true
+Tag: py3-none-any

hexastack_graphql-0.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[hexastack.bootstrappers]
+graphql = hexastack_graphql.infra.bootstrap:GraphQLBootstrapper
+