rabbitkit 0.9.0__py3-none-any.whl

rabbitkit/asyncapi/__init__.py

@@ -0,0 +1,5 @@
+"""AsyncAPI documentation generation for rabbitkit."""
+
+from rabbitkit.asyncapi.generator import AsyncAPIGeneratorConfig, generate_asyncapi_doc, generate_asyncapi_json
+
+__all__ = ["AsyncAPIGeneratorConfig", "generate_asyncapi_doc", "generate_asyncapi_json"]

rabbitkit/asyncapi/generator.py

@@ -0,0 +1,219 @@
+"""AsyncAPI 2.6.0 document generator from rabbitkit routes.
+
+Generates an **AsyncAPI** specification from a broker's route definitions.
+The spec describes your messaging API contract — queues, exchanges, message
+schemas, and operations — in a machine-readable format compatible with the
+AsyncAPI toolchain (Studio, code generators, documentation renderers).
+
+What is generated
+-----------------
+For every ``RouteDefinition`` in ``broker.routes``:
+
+* A **channel** named after the queue.
+* A **subscribe operation** with the handler's body type as the message
+  payload schema (JSON Schema).  Pydantic models use ``model_json_schema()``;
+  stdlib dataclasses use field introspection; primitives map to JSON primitives.
+* **AMQP bindings** — exchange type/name, queue durable/exclusive flags,
+  routing key.
+* **Tags** from ``route.tags`` and **description** from ``route.description``.
+* A **publish operation** when ``route.result_publisher`` is configured
+  (documents the reply channel).
+
+Quick start
+-----------
+    from rabbitkit.asyncapi.generator import (
+        generate_asyncapi_doc,
+        generate_asyncapi_json,
+        AsyncAPIGeneratorConfig,
+    )
+
+    # broker.routes populated after registering @broker.subscriber decorators
+    doc = generate_asyncapi_doc(
+        broker.routes,
+        config=AsyncAPIGeneratorConfig(
+            title="Order Service",
+            version="2.1.0",
+            description="Processes incoming orders and emits confirmations.",
+            server_url="rabbitmq.prod.internal:5672",
+        ),
+    )
+
+    # Pretty-print JSON spec
+    json_str = generate_asyncapi_json(broker.routes, indent=2)
+    print(json_str)
+
+CLI integration
+---------------
+    rabbitkit docs generate myapp.main:broker > asyncapi.json
+    rabbitkit docs serve   myapp.main:broker   # opens browser preview
+
+Saving to file::
+
+    import json
+    with open("asyncapi.json", "w") as f:
+        json.dump(generate_asyncapi_doc(broker.routes), f, indent=2)
+
+Example output (condensed)::
+
+    {
+      "asyncapi": "2.6.0",
+      "info": { "title": "Order Service", "version": "2.1.0" },
+      "servers": {
+        "rabbitmq": { "url": "localhost:5672", "protocol": "amqp" }
+      },
+      "channels": {
+        "orders": {
+          "subscribe": {
+            "operationId": "handle_order",
+            "message": {
+              "name": "handle_order",
+              "payload": {
+                "type": "object",
+                "properties": {
+                  "id":   { "type": "integer" },
+                  "item": { "type": "string"  }
+                }
+              }
+            }
+          },
+          "bindings": {
+            "amqp": {
+              "is": "queue",
+              "queue": { "name": "orders", "durable": true }
+            }
+          }
+        }
+      }
+    }
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from rabbitkit.asyncapi.schema import extract_json_schema, get_handler_body_type
+from rabbitkit.core.route import RouteDefinition
+
+
+@dataclass
+class AsyncAPIGeneratorConfig:
+    """Configuration for AsyncAPI document generation."""
+
+    title: str = "rabbitkit Service"
+    version: str = "1.0.0"
+    description: str = ""
+    server_url: str = "localhost:5672"
+    server_description: str = "RabbitMQ"
+
+
+def generate_asyncapi_doc(
+    routes: list[RouteDefinition],
+    config: AsyncAPIGeneratorConfig | None = None,
+) -> dict[str, Any]:
+    """Generate an AsyncAPI 2.6.0 document from route definitions.
+
+    Args:
+        routes: List of RouteDefinition from broker.routes.
+        config: Generator configuration.
+
+    Returns:
+        AsyncAPI 2.6.0 spec as a JSON-serializable dict.
+    """
+    if config is None:
+        config = AsyncAPIGeneratorConfig()
+
+    doc: dict[str, Any] = {
+        "asyncapi": "2.6.0",
+        "info": {
+            "title": config.title,
+            "version": config.version,
+        },
+        "servers": {
+            "rabbitmq": {
+                "url": config.server_url,
+                "protocol": "amqp",
+                "description": config.server_description,
+            },
+        },
+        "channels": {},
+    }
+
+    if config.description:
+        doc["info"]["description"] = config.description
+
+    for route in routes:
+        channel_name = route.queue.name
+        channel: dict[str, Any] = {}
+
+        if route.description:
+            channel["description"] = route.description
+
+        # Subscribe operation (consumer)
+        operation: dict[str, Any] = {
+            "operationId": route.name,
+        }
+
+        # Message schema from handler type hints
+        body_type = get_handler_body_type(route.handler)
+        payload = extract_json_schema(body_type)
+        message: dict[str, Any] = {
+            "name": route.name,
+        }
+        if payload:
+            message["payload"] = payload
+        operation["message"] = message
+
+        # Tags
+        if route.tags:
+            operation["tags"] = [{"name": t} for t in sorted(route.tags)]
+
+        channel["subscribe"] = operation
+
+        # AMQP bindings
+        bindings: dict[str, Any] = {"amqp": {"is": "queue"}}
+        queue_binding: dict[str, Any] = {
+            "name": route.queue.name,
+            "durable": route.queue.durable,
+        }
+        if hasattr(route.queue, "exclusive"):
+            queue_binding["exclusive"] = route.queue.exclusive
+        bindings["amqp"]["queue"] = queue_binding
+
+        if route.exchange is not None:
+            exchange_binding: dict[str, Any] = {
+                "name": route.exchange.name,
+                "type": (
+                    route.exchange.type.value
+                    if hasattr(route.exchange.type, "value")
+                    else str(route.exchange.type)
+                ),
+            }
+            if hasattr(route.exchange, "durable"):
+                exchange_binding["durable"] = route.exchange.durable
+            bindings["amqp"]["exchange"] = exchange_binding
+
+        channel["bindings"] = bindings
+
+        # Publish operation (if result_publisher is set)
+        if route.result_publisher is not None:
+            publish_op: dict[str, Any] = {
+                "operationId": f"{route.name}.reply",
+                "message": {"name": f"{route.name}.response"},
+            }
+            channel["publish"] = publish_op
+
+        doc["channels"][channel_name] = channel
+
+    return doc
+
+
+def generate_asyncapi_json(
+    routes: list[RouteDefinition],
+    config: AsyncAPIGeneratorConfig | None = None,
+    indent: int | None = 2,
+) -> str:
+    """Generate AsyncAPI spec as a JSON string."""
+    doc = generate_asyncapi_doc(routes, config)
+    return json.dumps(doc, indent=indent)

rabbitkit/asyncapi/schema.py

@@ -0,0 +1,98 @@
+"""JSON Schema extraction from Python type annotations."""
+
+from __future__ import annotations
+
+import dataclasses
+import inspect
+from typing import Any, get_type_hints
+
+from rabbitkit.core.message import is_rabbit_message_annotation
+
+
+def get_handler_body_type(handler: Any) -> type | None:
+    """Extract the body parameter type from a handler signature.
+
+    Returns the first non-RabbitMessage, non-Annotated parameter type.
+    Returns None if no suitable parameter found or type is bytes.
+    """
+    try:
+        sig = inspect.signature(handler)
+    except (ValueError, TypeError):
+        return None
+
+    # Resolve string annotations (from __future__ import annotations)
+    try:
+        hints = get_type_hints(handler)
+    except Exception:
+        hints = {}
+
+    for name, param in sig.parameters.items():
+        # Prefer resolved type hints over raw annotations
+        ann = hints.get(name, param.annotation)
+        if ann is inspect.Parameter.empty:
+            continue
+        if is_rabbit_message_annotation(ann):
+            continue
+        # Skip Annotated types (DI markers)
+        if getattr(ann, "__metadata__", None) is not None:
+            continue
+        if ann is bytes:
+            return None
+        return ann  # type: ignore[no-any-return]
+    return None
+
+
+def extract_json_schema(type_hint: type | None) -> dict[str, Any]:
+    """Extract JSON Schema from a Python type hint.
+
+    Supports:
+    - None -> empty schema
+    - Pydantic V2 models -> model_json_schema()
+    - dataclasses -> field inspection
+    - Primitives (str, int, float, bool) -> {"type": "..."}
+    - bytes -> {"type": "string", "contentEncoding": "base64"}
+    """
+    if type_hint is None:
+        return {}
+
+    # Pydantic V2 model
+    if hasattr(type_hint, "model_json_schema"):
+        return type_hint.model_json_schema()  # type: ignore[no-any-return]
+
+    # dataclass
+    if dataclasses.is_dataclass(type_hint) and isinstance(type_hint, type):
+        properties: dict[str, Any] = {}
+        required: list[str] = []
+        for f in dataclasses.fields(type_hint):
+            properties[f.name] = _python_type_to_schema(f.type)
+            if f.default is dataclasses.MISSING and f.default_factory is dataclasses.MISSING:
+                required.append(f.name)
+        schema: dict[str, Any] = {"type": "object", "properties": properties}
+        if required:
+            schema["required"] = required
+        return schema
+
+    # Primitive types
+    return _python_type_to_schema(type_hint)
+
+
+def _python_type_to_schema(python_type: Any) -> dict[str, Any]:
+    """Convert a Python type to a JSON Schema type."""
+    type_map: dict[type, dict[str, str]] = {
+        str: {"type": "string"},
+        int: {"type": "integer"},
+        float: {"type": "number"},
+        bool: {"type": "boolean"},
+        bytes: {"type": "string", "contentEncoding": "base64"},
+        dict: {"type": "object"},
+        list: {"type": "array"},
+    }
+    if isinstance(python_type, type) and python_type in type_map:
+        return type_map[python_type]
+    if isinstance(python_type, str):
+        # String annotation — best effort
+        lower = python_type.lower()
+        for t, schema in type_map.items():
+            if t.__name__.lower() == lower:
+                return schema
+    return {"type": "object"}

rabbitkit/cli/__init__.py

@@ -0,0 +1,77 @@
+"""rabbitkit CLI — production-grade RabbitMQ toolkit.
+
+Provides the ``rabbitkit`` command-line interface for running, inspecting,
+and interacting with rabbitkit brokers.
+
+Requires: ``pip install rabbitkit[cli]``
+
+Available commands
+------------------
+rabbitkit run <app_path>            Start a broker
+rabbitkit run <app_path> --reload   Start with hot-reload (requires rabbitkit[reload])
+rabbitkit run <app_path> -w 4       Start 4 worker processes
+
+rabbitkit health check <app_path>   Print broker health as JSON
+
+rabbitkit topology list <app_path>  List all registered routes
+
+rabbitkit routes list <app_path>    List all consumer routes with retry info
+rabbitkit routes describe <app_path> <name>  Show full route details
+
+rabbitkit dlq inspect <queue>       Peek at messages in a dead-letter queue
+rabbitkit dlq replay <queue> <target>  Republish DLQ messages to a target exchange
+
+rabbitkit shell <app_path>          Open interactive Python shell with broker pre-loaded
+
+App path format
+---------------
+``<module.path>:<attribute_name>``
+
+Examples::
+
+    rabbitkit run myapp.main:broker
+    rabbitkit health check myapp.main:broker
+    rabbitkit topology list myapp.main:broker --format json
+    rabbitkit routes list myapp.main:broker
+    rabbitkit routes describe myapp.main:broker handle_order
+    rabbitkit dlq inspect orders.created.dlq --limit 50
+    rabbitkit dlq replay orders.created.dlq orders --dry-run
+    rabbitkit shell myapp.main:broker
+
+The module must be importable from the current working directory (add it to
+``PYTHONPATH`` if needed, or run from the project root).
+
+Installation check::
+
+    pip install "rabbitkit[cli]"
+    rabbitkit --help
+"""
+
+from __future__ import annotations
+
+try:
+    import typer
+except ImportError as _err:  # pragma: no cover
+    raise ImportError(
+        "rabbitkit CLI requires typer. Install with: pip install rabbitkit[cli]"
+    ) from _err
+
+from rabbitkit.cli.commands.dlq import dlq_app
+from rabbitkit.cli.commands.health import health_app
+from rabbitkit.cli.commands.routes import routes_app
+from rabbitkit.cli.commands.run import run_command
+from rabbitkit.cli.commands.shell import shell_command
+from rabbitkit.cli.commands.topology import topology_app
+
+app = typer.Typer(
+    name="rabbitkit",
+    help="Production-grade RabbitMQ toolkit CLI.",
+    no_args_is_help=True,
+)
+
+app.command("run")(run_command)
+app.command("shell")(shell_command)
+app.add_typer(health_app, name="health")
+app.add_typer(topology_app, name="topology")
+app.add_typer(routes_app, name="routes")
+app.add_typer(dlq_app, name="dlq")

rabbitkit/cli/_utils.py

@@ -0,0 +1,38 @@
+"""CLI utilities — broker loading and path parsing."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+
+def parse_app_path(app_path: str) -> tuple[str, str]:
+    """Split 'module.path:attr' into (module_path, attr_name).
+
+    Raises ValueError if format is invalid.
+    """
+    if ":" not in app_path:
+        raise ValueError(
+            f"Invalid app path '{app_path}'. Expected format: 'module.path:broker_attr'"
+        )
+    module_path, attr = app_path.rsplit(":", 1)
+    return module_path, attr
+
+
+def load_broker(app_path: str) -> Any:
+    """Import module and return the broker attribute.
+
+    Args:
+        app_path: String like 'myapp.main:broker'
+
+    Returns:
+        The broker instance.
+
+    Raises:
+        ValueError: Invalid path format.
+        ImportError: Module not found.
+        AttributeError: Attribute not found in module.
+    """
+    module_path, attr = parse_app_path(app_path)
+    module = importlib.import_module(module_path)
+    return getattr(module, attr)

rabbitkit/cli/commands/dlq.py

@@ -0,0 +1,190 @@
+"""rabbitkit dlq — dead-letter queue inspection and replay commands."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+dlq_app = typer.Typer(help="Dead-letter queue commands.")
+
+
+@dlq_app.command("inspect")
+def dlq_inspect(
+    queue: str = typer.Argument(..., help="DLQ name to inspect, e.g. 'orders.created.dlq'"),
+    amqp_url: str = typer.Option(
+        "amqp://guest:guest@localhost/",
+        "--url",
+        "-u",
+        envvar="RABBITMQ_URL",
+        help="AMQP connection URL",
+    ),
+    limit: int = typer.Option(20, "--limit", "-n", help="Maximum messages to fetch"),
+    output_format: str = typer.Option("table", "--format", "-f", help="Output format: table or json"),
+) -> None:
+    """Inspect messages in a dead-letter queue without removing them.
+
+    Connects directly to RabbitMQ and peeks at the DLQ contents using
+    basic_get in passive mode.
+
+    Example::
+
+        rabbitkit dlq inspect orders.created.dlq
+        rabbitkit dlq inspect orders.created.dlq --limit 100 --format json
+    """
+    try:
+        import pika
+    except ImportError:
+        typer.echo("pika is required: pip install pika", err=True)
+        raise typer.Exit(1) from None
+
+    params = pika.URLParameters(amqp_url)
+    connection = pika.BlockingConnection(params)
+    channel = connection.channel()
+
+    messages = []
+    for _ in range(limit):
+        method, properties, body = channel.basic_get(queue=queue, auto_ack=False)
+        if method is None:
+            break
+        channel.basic_nack(delivery_tag=method.delivery_tag, requeue=True)
+        entry = {
+            "routing_key": method.routing_key,
+            "exchange": method.exchange,
+            "redelivered": method.redelivered,
+            "message_id": properties.message_id,
+            "correlation_id": properties.correlation_id,
+            "headers": dict(properties.headers or {}),
+            "body_preview": body[:200].decode(errors="replace"),
+        }
+        messages.append(entry)
+
+    connection.close()
+
+    if output_format == "json":
+        typer.echo(json.dumps(messages, indent=2, default=str))
+        return
+
+    if not messages:
+        typer.echo(f"No messages in {queue!r}.")
+        return
+
+    typer.echo(f"Messages in {queue!r} ({len(messages)} shown):")
+    typer.echo("-" * 60)
+    for i, msg in enumerate(messages, 1):
+        typer.echo(f"[{i}] routing_key={msg['routing_key']}  message_id={msg['message_id']}")
+        if msg["headers"]:
+            typer.echo(f"     headers={msg['headers']}")
+        typer.echo(f"     body: {msg['body_preview']}")
+        typer.echo()
+
+
+@dlq_app.command("replay")
+def dlq_replay(
+    queue: str = typer.Argument(..., help="DLQ name to replay from, e.g. 'orders.created.dlq'"),
+    target: str = typer.Argument(..., help="Target exchange or queue to republish to"),
+    amqp_url: str = typer.Option(
+        "amqp://guest:guest@localhost/",
+        "--url",
+        "-u",
+        envvar="RABBITMQ_URL",
+        help="AMQP connection URL",
+    ),
+    limit: int = typer.Option(10, "--limit", "-n", help="Maximum messages to replay"),
+    routing_key: str | None = typer.Option(None, "--routing-key", "-k", help="Override routing key"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be replayed without publishing"),
+    reset_retry_count: bool = typer.Option(
+        False,
+        "--reset-retry-count",
+        help=(
+            "Strip the retry-count header before replaying, so the message gets a fresh "
+            "retry ladder instead of resuming at its old count (default: preserve headers "
+            "verbatim -- a previously max-retried message is terminal after one more failed "
+            "attempt and returns straight to the DLQ)."
+        ),
+    ),
+    retry_count_header: str = typer.Option(
+        "x-rabbitkit-retry-count",
+        "--retry-count-header",
+        help="Header name --reset-retry-count strips. Match RetryConfig.retry_header if customized.",
+    ),
+) -> None:
+    """Replay messages from a dead-letter queue to a target exchange/queue.
+
+    Messages are consumed from the DLQ and published to the target with
+    publisher confirms and ``mandatory=True``. The DLQ message is acked
+    (removed) only after the broker confirms the republish; a failed or
+    unroutable publish is nack-requeued so the message stays on the DLQ.
+
+    Example::
+
+        # Replay up to 10 messages to the original exchange
+        rabbitkit dlq replay orders.created.dlq orders
+
+        # Dry-run to preview without publishing
+        rabbitkit dlq replay orders.created.dlq orders --dry-run
+
+        # Replay with a specific routing key
+        rabbitkit dlq replay orders.created.dlq orders -k orders.created
+
+        # Give a previously max-retried message a fresh retry ladder
+        rabbitkit dlq replay orders.created.dlq orders --reset-retry-count
+    """
+    try:
+        import pika
+        from pika import exceptions as pika_exceptions
+    except ImportError:
+        typer.echo("pika is required: pip install pika", err=True)
+        raise typer.Exit(1) from None
+
+    params = pika.URLParameters(amqp_url)
+    connection = pika.BlockingConnection(params)
+    channel = connection.channel()
+    # Confirms make basic_publish raise on nack/unroutable instead of
+    # fire-and-forget — without this, ack-after-publish can lose the message.
+    channel.confirm_delivery()
+
+    replayed = 0
+    failed = 0
+    for _ in range(limit):
+        method, properties, body = channel.basic_get(queue=queue, auto_ack=False)
+        if method is None:
+            break
+
+        rk = routing_key or method.routing_key
+        if reset_retry_count and properties.headers and retry_count_header in properties.headers:
+            properties.headers.pop(retry_count_header, None)
+
+        if dry_run:
+            typer.echo(f"[dry-run] Would publish to exchange={target!r} routing_key={rk!r}  body={body[:100]!r}")
+            channel.basic_nack(delivery_tag=method.delivery_tag, requeue=True)
+            continue
+
+        try:
+            channel.basic_publish(
+                exchange=target,
+                routing_key=rk,
+                body=body,
+                properties=properties,
+                mandatory=True,
+            )
+        except (pika_exceptions.UnroutableError, pika_exceptions.NackError) as exc:
+            channel.basic_nack(delivery_tag=method.delivery_tag, requeue=True)
+            typer.echo(
+                f"FAILED (stays on DLQ): routing_key={rk!r}  message_id={properties.message_id}  ({exc})",
+                err=True,
+            )
+            failed += 1
+            continue
+
+        channel.basic_ack(delivery_tag=method.delivery_tag)
+        typer.echo(f"Replayed: routing_key={rk!r}  message_id={properties.message_id}")
+        replayed += 1
+
+    connection.close()
+
+    if not dry_run:
+        typer.echo(f"\nReplayed {replayed} message(s) from {queue!r} → {target!r}.")
+        if failed:
+            typer.echo(f"{failed} message(s) failed to publish and remain on {queue!r}.", err=True)
+            raise typer.Exit(1)

rabbitkit/cli/commands/health.py

@@ -0,0 +1,34 @@
+"""rabbitkit health — broker health check."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from rabbitkit.cli._utils import load_broker
+
+health_app = typer.Typer(help="Health check commands.")
+
+
+@health_app.command("check")
+def health_check(
+    app_path: str = typer.Argument(..., help="Broker path, e.g. 'myapp.main:broker'"),
+) -> None:
+    """Check broker health and exit with code 1 if unhealthy."""
+    from rabbitkit.health import HealthStatus, broker_health_check
+
+    broker = load_broker(app_path)
+    result = broker_health_check(broker)
+
+    output = {
+        "status": result.status.value,
+        "started": result.started,
+        "connected": result.connected,
+        "consumer_count": result.consumer_count,
+        "route_count": result.route_count,
+    }
+    typer.echo(json.dumps(output, indent=2))
+
+    if result.status != HealthStatus.HEALTHY:
+        raise typer.Exit(code=1)