solrctl 0.5.0__py3-none-any.whl

solrctl/cli.py

@@ -0,0 +1,231 @@
+"""solrctl CLI – Verwaltung von Solr-Cores und Aliases."""
+
+from __future__ import annotations
+
+import click
+from loguru import logger
+
+from solrctl.client import SolrClient, SolrClientError
+
+
+class SolrContext:
+    """Hält den SolrClient für die Laufzeit des CLI-Aufrufs."""
+
+    def __init__(self, solr_url: str, auth: tuple[str, str] | None) -> None:
+        self.client = SolrClient(solr_url, auth=auth)
+
+    def close(self) -> None:
+        self.client.close()
+
+
+pass_solr_ctx = click.make_pass_decorator(SolrContext)
+
+
+def _handle_error(exc: SolrClientError) -> None:
+    click.secho(f"Fehler: {exc}", fg="red", err=True)
+    raise SystemExit(1)
+
+
+@click.group()
+@click.option(
+    "--solr-url",
+    envvar="SOLR_URL",
+    default="http://localhost:8983",
+    show_default=True,
+    help="Basis-URL der Solr-Instanz.",
+)
+@click.option(
+    "--user", envvar="SOLR_USER", default=None, help="Basic-Auth Benutzername."
+)
+@click.option(
+    "--password", envvar="SOLR_PASSWORD", default=None, help="Basic-Auth Passwort."
+)
+@click.pass_context
+def cli(
+    ctx: click.Context, solr_url: str, user: str | None, password: str | None
+) -> None:
+    """solrctl – Verwaltung von Solr-Cores und Aliases."""
+    auth = (user, password) if user and password else None
+    ctx.obj = SolrContext(solr_url, auth)
+
+
+@cli.command()
+@pass_solr_ctx
+def ping(ctx: SolrContext) -> None:
+    """Prüft, ob Solr erreichbar ist."""
+    if ctx.client.ping():
+        click.echo("Solr erreichbar.")
+    else:
+        click.secho("Solr NICHT erreichbar.", fg="red", err=True)
+        raise SystemExit(1)
+
+
+# ── core ──────────────────────────────────────────────────────────
+
+
+@cli.group()
+def core() -> None:
+    """Standalone Core-Operationen."""
+
+
+@core.command("list")
+@pass_solr_ctx
+def core_list(ctx: SolrContext) -> None:
+    """Listet alle vorhandenen Cores auf."""
+    try:
+        cores = ctx.client.list_cores()
+    except SolrClientError as exc:
+        _handle_error(exc)
+        return
+
+    if not cores:
+        click.echo("Keine Cores gefunden.")
+        return
+    for name in cores:
+        click.echo(name)
+
+
+@core.command()
+@click.option("--source", required=True, help="Name des neuen Cores (frische Daten).")
+@click.option(
+    "--target", required=True, help="Name des aktiven Cores (wird getauscht)."
+)
+@pass_solr_ctx
+def swap(ctx: SolrContext, source: str, target: str) -> None:
+    """Tauscht zwei Solr-Cores (CoreAdmin SWAP-Action)."""
+    logger.info("Swap: '{}' <-> '{}'", target, source)
+    try:
+        ctx.client.swap_cores(target, source)
+        click.secho(f"Swap erfolgreich: '{target}' <-> '{source}'.", fg="green")
+    except SolrClientError as exc:
+        _handle_error(exc)
+
+
+@core.command()
+@click.argument("name")
+@click.option("--delete-index", is_flag=True, help="Index-Daten auf Disk löschen.")
+@pass_solr_ctx
+def delete(ctx: SolrContext, name: str, delete_index: bool) -> None:
+    """Löscht (unload) einen Solr-Core."""
+    try:
+        ctx.client.unload_core(name, delete_index=delete_index)
+        click.secho(f"Core '{name}' gelöscht.", fg="green")
+    except SolrClientError as exc:
+        _handle_error(exc)
+
+
+@core.command("info")
+@click.argument("name")
+@pass_solr_ctx
+def core_info(ctx: SolrContext, name: str) -> None:
+    """Zeigt detaillierte Informationen zu einem Core an."""
+    try:
+        info = ctx.client.get_core_info(name)
+    except SolrClientError as exc:
+        _handle_error(exc)
+        return
+
+    click.echo(f"Core:         {info.get('name', name)}")
+    click.echo(f"InstanceDir:  {info.get('instanceDir')}")
+    click.echo(f"DataDir:      {info.get('dataDir')}")
+    click.echo(f"Config:       {info.get('config')}")
+    click.echo(f"Schema:       {info.get('schema')}")
+    click.echo(f"StartTime:    {info.get('startTime')}")
+    uptime = info.get("uptime", 0)
+    click.echo(f"Uptime:       {uptime // 1000}s")
+
+    index = info.get("index", {})
+    if index:
+        click.echo()
+        click.secho("Index:", bold=True)
+        click.echo(f"  numDocs:      {index.get('numDocs')}")
+        click.echo(f"  maxDoc:       {index.get('maxDoc')}")
+        click.echo(f"  deletedDocs:  {index.get('deletedDocs')}")
+        click.echo(f"  segments:     {index.get('segmentCount')}")
+        click.echo(f"  size:         {index.get('size')}")
+        click.echo(f"  lastModified: {index.get('lastModified')}")
+
+
+@core.command("config")
+@click.argument("name")
+@pass_solr_ctx
+def core_config(ctx: SolrContext, name: str) -> None:
+    """Gibt die solrconfig.xml eines Cores als XML aus."""
+    try:
+        config_xml = ctx.client.get_core_config(name)
+    except SolrClientError as exc:
+        _handle_error(exc)
+        return
+    click.echo(config_xml)
+
+
+@core.command("schema")
+@click.argument("name")
+@pass_solr_ctx
+def core_schema(ctx: SolrContext, name: str) -> None:
+    """Gibt das Schema eines Cores als XML aus."""
+    try:
+        schema_xml = ctx.client.get_core_schema(name)
+    except SolrClientError as exc:
+        _handle_error(exc)
+        return
+    click.echo(schema_xml)
+
+
+# ── alias ─────────────────────────────────────────────────────────
+
+
+@cli.group()
+def alias() -> None:
+    """SolrCloud Alias-Operationen."""
+
+
+@alias.command("list")
+@pass_solr_ctx
+def alias_list(ctx: SolrContext) -> None:
+    """Listet alle Aliases auf."""
+    try:
+        aliases = ctx.client.list_aliases()
+    except SolrClientError as exc:
+        _handle_error(exc)
+        return
+
+    if not aliases:
+        click.echo("Keine Aliases gefunden.")
+        return
+    for alias_name, collection in aliases.items():
+        click.echo(f"{alias_name} -> {collection}")
+
+
+@alias.command()
+@click.option("--alias", required=True, help="Name des Alias.")
+@click.option("--collection", required=True, help="Ziel-Collection.")
+@pass_solr_ctx
+def swap(ctx: SolrContext, alias: str, collection: str) -> None:
+    """Setzt einen Alias auf eine neue Collection um."""
+    try:
+        ctx.client.create_or_update_alias(alias, collection)
+        click.secho(f"Alias '{alias}' -> '{collection}' gesetzt.", fg="green")
+    except SolrClientError as exc:
+        _handle_error(exc)
+
+
+@alias.command()
+@click.argument("name")
+@pass_solr_ctx
+def delete(ctx: SolrContext, name: str) -> None:
+    """Löscht einen Alias."""
+    try:
+        ctx.client.delete_alias(name)
+        click.secho(f"Alias '{name}' gelöscht.", fg="green")
+    except SolrClientError as exc:
+        _handle_error(exc)
+
+
+def main() -> None:
+    """Einstiegspunkt für die CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

solrctl/client.py

@@ -0,0 +1,473 @@
+"""Solr HTTP-Client auf Basis von httpx.
+
+Kapselt alle API-Aufrufe gegen Solr 9.x:
+- Collections API (SolrCloud): Alias-Verwaltung
+- CoreAdmin API (Standalone): Core-Verwaltung
+- Health-Check
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class SolrClientError(Exception):
+    """Wird bei Fehlern der Solr-API geworfen."""
+
+
+class SolrClient:
+    """HTTP-Client für Solr 9.x.
+
+    Args:
+        base_url: Basis-URL der Solr-Instanz (z. B. ``http://localhost:8983``).
+        timeout: HTTP-Timeout in Sekunden.
+        auth: Optionales ``(user, password)``-Tupel für Basic Auth.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float = 30.0,
+        auth: tuple[str, str] | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout,
+            auth=auth,
+        )
+
+    # ------------------------------------------------------------------
+    # Health
+    # ------------------------------------------------------------------
+
+    def ping(self) -> bool:
+        """Prüft, ob die Solr-Instanz erreichbar ist.
+
+        Returns:
+            ``True`` wenn Solr antwortet, sonst ``False``.
+        """
+        try:
+            response = self._client.get(
+                "/solr/admin/info/system", params={"wt": "json"}
+            )
+            response.raise_for_status()
+            logger.debug("Solr erreichbar: %s", self._base_url)
+            return True
+        except Exception as exc:
+            logger.warning("Solr nicht erreichbar: %s", exc)
+            return False
+
+    # ------------------------------------------------------------------
+    # Collections API – Aliases (SolrCloud)
+    # ------------------------------------------------------------------
+
+    def list_aliases(self) -> dict[str, str]:
+        """Gibt alle bekannten Aliases zurück.
+
+        Returns:
+            Dict ``{alias_name: collection_name}``.
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        response = self._request(
+            "GET",
+            "/solr/admin/collections",
+            params={"action": "LISTALIASES", "wt": "json"},
+        )
+        # Antwort: {"aliases": {"alias1": "col1", ...}, ...}
+        return response.get("aliases", {})
+
+    def create_or_update_alias(self, alias: str, collection: str) -> None:
+        """Erstellt einen neuen Alias oder setzt einen bestehenden um.
+
+        Args:
+            alias: Name des Alias.
+            collection: Ziel-Collection, auf die der Alias zeigen soll.
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        logger.info("Setze Alias '%s' auf Collection '%s'", alias, collection)
+        self._request(
+            "GET",
+            "/solr/admin/collections",
+            params={
+                "action": "CREATEALIAS",
+                "name": alias,
+                "collections": collection,
+                "wt": "json",
+            },
+        )
+
+    def delete_alias(self, alias: str) -> None:
+        """Löscht einen Alias.
+
+        Args:
+            alias: Name des zu löschenden Alias.
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        logger.info("Lösche Alias '%s'", alias)
+        self._request(
+            "GET",
+            "/solr/admin/collections",
+            params={"action": "DELETEALIAS", "name": alias, "wt": "json"},
+        )
+
+    def delete_collection(self, collection: str) -> None:
+        """Löscht eine SolrCloud Collection.
+
+        Args:
+            collection: Name der zu löschenden Collection.
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        logger.info("Lösche Collection '%s'", collection)
+        self._request(
+            "GET",
+            "/solr/admin/collections",
+            params={"action": "DELETE", "name": collection, "wt": "json"},
+        )
+
+    # ------------------------------------------------------------------
+    # CoreAdmin API – Cores (Standalone)
+    # ------------------------------------------------------------------
+
+    def list_cores(self) -> list[str]:
+        """Gibt die Namen aller vorhandenen Cores zurück。
+
+        Returns:
+            Liste der Core-Namen。
+
+        Raises:
+            SolrClientError: Bei API-Fehler。
+        """
+        response = self._request(
+            "GET",
+            "/solr/admin/cores",
+            params={"action": "STATUS", "wt": "json"},
+        )
+        return list(response.get("status", {}).keys())
+
+    def get_core_info(self, core: str) -> dict[str, Any]:
+        """Liefert detaillierte Informationen zu einem Core。
+
+        Enthält Name, Pfade, Startzeit, Uptime und Index-Statistiken
+        (Dokumentanzahl, Segmentanzahl, Größe usw.)。
+
+        Args:
+            core: Name des Core。
+
+        Returns:
+            Dict mit den Core-Informationen aus der STATUS-Antwort。
+
+        Raises:
+            SolrClientError: Bei API-Fehler oder wenn der Core nicht existiert。
+        """
+        response = self._request(
+            "GET",
+            "/solr/admin/cores",
+            params={"action": "STATUS", "core": core, "wt": "json"},
+        )
+        status = response.get("status", {})
+        if core not in status:
+            raise SolrClientError(f"Core '{core}' nicht gefunden")
+        return status[core]
+
+    def swap_cores(self, core1: str, core2: str) -> None:
+        """Tauscht zwei Cores via CoreAdmin SWAP-Action.
+
+        Nach dem Swap übernimmt ``core1`` alle Daten von ``core2`` und umgekehrt.
+
+        Args:
+            core1: Name des ersten Core (wird zum neuen aktiven Core).
+            core2: Name des zweiten Core.
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        logger.info("Swap Cores: '%s' <-> '%s'", core1, core2)
+        self._request(
+            "GET",
+            "/solr/admin/cores",
+            params={"action": "SWAP", "core": core1, "other": core2, "wt": "json"},
+        )
+
+    def unload_core(self, core: str, *, delete_index: bool = False) -> None:
+        """Entlädt (und löscht optional) einen Core.
+
+        Args:
+            core: Name des Core.
+            delete_index: Wenn ``True``, werden Index-Daten auf Disk gelöscht.
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        logger.info("Unload Core '%s' (delete_index=%s)", core, delete_index)
+        self._request(
+            "GET",
+            "/solr/admin/cores",
+            params={
+                "action": "UNLOAD",
+                "core": core,
+                "deleteIndex": str(delete_index).lower(),
+                "deleteDataDir": str(delete_index).lower(),
+                "deleteInstanceDir": str(delete_index).lower(),
+                "wt": "json",
+            },
+        )
+
+    def create_collection(
+        self,
+        collection: str,
+        num_shards: int = 1,
+        replication_factor: int = 1,
+        config_set: str = "_default",
+    ) -> None:
+        """Erstellt eine neue SolrCloud Collection.
+
+        Args:
+            collection: Name der Collection.
+            num_shards: Anzahl Shards (default: 1).
+            replication_factor: Replikationsfaktor (default: 1).
+            config_set: Zu verwendendes ConfigSet (default: "_default").
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        logger.info(
+            "Erstelle Collection '%s' (shards=%d, replicas=%d)",
+            collection,
+            num_shards,
+            replication_factor,
+        )
+        self._request(
+            "GET",
+            "/solr/admin/collections",
+            params={
+                "action": "CREATE",
+                "name": collection,
+                "numShards": num_shards,
+                "replicationFactor": replication_factor,
+                "collection.configName": config_set,
+                "wt": "json",
+            },
+        )
+
+    def create_core(self, core: str, config_set: str = "_default") -> None:
+        """Erstellt einen neuen Standalone Core.
+
+        Args:
+            core: Name des Core.
+            config_set: Zu verwendendes ConfigSet (default: "_default").
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        logger.info("Erstelle Core '%s'", core)
+        self._request(
+            "GET",
+            "/solr/admin/cores",
+            params={
+                "action": "CREATE",
+                "name": core,
+                "configSet": config_set,
+                "wt": "json",
+            },
+        )
+
+    def index_documents(
+        self,
+        core_or_collection: str,
+        documents: list[dict],
+        commit: bool = True,
+    ) -> None:
+        """Indexiert Dokumente in einen Core oder Collection.
+
+        Args:
+            core_or_collection: Name des Ziel-Core/Collection.
+            documents: Liste von Dokumenten (Dicts).
+            commit: Wenn True, wird sofort committed.
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        if not documents:
+            logger.debug("Keine Dokumente zu indexieren")
+            return
+
+        logger.info(
+            "Indexiere %d Dokumente in '%s'", len(documents), core_or_collection
+        )
+
+        # Solr Update API verwendet POST mit JSON-Body
+        url = f"/solr/{core_or_collection}/update"
+        params: dict[str, Any] = {"wt": "json"}
+        if commit:
+            params["commit"] = "true"
+
+        response = self._client.post(url, params=params, json=documents)
+        response.raise_for_status()
+
+        data: dict[str, Any] = response.json()
+        header = data.get("responseHeader", {})
+        if header.get("status", 0) != 0:
+            raise SolrClientError(f"Solr-Fehler beim Indexieren: {data}")
+
+        logger.debug("Indexierung erfolgreich: %s", data)
+
+    # ------------------------------------------------------------------
+    # Konfigurationsdateien
+    # ------------------------------------------------------------------
+
+    def get_core_config(self, core: str) -> str:
+        """Liefert die solrconfig.xml eines Cores als XML-String.
+
+        Args:
+            core: Name des Core.
+
+        Returns:
+            Inhalt der solrconfig.xml als String.
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        logger.info("Lese solrconfig.xml für Core '%s'", core)
+        return self._get_file(core, "solrconfig.xml")
+
+    def get_core_schema(self, core: str) -> str:
+        """Liefert das Schema eines Cores als XML-String.
+
+        Bei managed-schema Cores wird das Schema über die Schema-API
+        im schema.xml-Format abgerufen, da die Datei auf Disk
+        ``managed-schema.xml`` heißt und automatisch verwaltet wird.
+
+        Args:
+            core: Name des Core.
+
+        Returns:
+            Schema-Inhalt als XML-String.
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        logger.info("Lese Schema für Core '%s'", core)
+        info = self.get_core_info(core)
+        schema_name = info.get("schema", "managed-schema.xml")
+
+        if schema_name == "managed-schema.xml":
+            return self._get_schema_api(core)
+
+        return self._get_file(core, schema_name)
+
+    def _get_file(self, core: str, filename: str) -> str:
+        """Liest eine Konfigurationsdatei über die Admin-File-API.
+
+        Args:
+            core: Name des Core.
+            filename: Dateiname (z. B. ``solrconfig.xml``).
+
+        Returns:
+            Dateiinhalt als String.
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        try:
+            response = self._client.get(
+                f"/solr/{core}/admin/file",
+                params={"file": filename},
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise SolrClientError(
+                f"HTTP {exc.response.status_code} von Solr: {exc.response.text}"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise SolrClientError(f"Verbindungsfehler zu Solr: {exc}") from exc
+
+        return response.text
+
+    def _get_schema_api(self, core: str) -> str:
+        """Liest das Schema über die Schema-API im schema.xml-Format.
+
+        Args:
+            core: Name des Core.
+
+        Returns:
+            Schema als XML-String.
+
+        Raises:
+            SolrClientError: Bei API-Fehler.
+        """
+        try:
+            response = self._client.get(
+                f"/solr/{core}/schema",
+                params={"wt": "schema.xml"},
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise SolrClientError(
+                f"HTTP {exc.response.status_code} von Solr: {exc.response.text}"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise SolrClientError(f"Verbindungsfehler zu Solr: {exc}") from exc
+
+        return response.text
+
+    # ------------------------------------------------------------------
+    # Interner Hilfsmethoden
+    # ------------------------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Sendet eine HTTP-Anfrage und wertet die JSON-Antwort aus.
+
+        Args:
+            method: HTTP-Methode (z. B. ``"GET"``).
+            path: URL-Pfad relativ zur Basis-URL.
+            **kwargs: Werden direkt an ``httpx.Client.request`` weitergegeben.
+
+        Returns:
+            Geparste JSON-Antwort als Dict.
+
+        Raises:
+            SolrClientError: Bei HTTP-Fehler oder Solr-Fehler in der Antwort.
+        """
+        try:
+            response = self._client.request(method, path, **kwargs)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise SolrClientError(
+                f"HTTP {exc.response.status_code} von Solr: {exc.response.text}"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise SolrClientError(f"Verbindungsfehler zu Solr: {exc}") from exc
+
+        data: dict[str, Any] = response.json()
+
+        # Solr signalisiert Fehler manchmal im Body mit status != 0
+        header = data.get("responseHeader", {})
+        if header.get("status", 0) != 0:
+            raise SolrClientError(f"Solr-Fehler in Antwort: {data}")
+
+        logger.debug("Solr-Antwort: %s", data)
+        return data
+
+    def close(self) -> None:
+        """Schließt den HTTP-Client."""
+        self._client.close()
+
+    def __enter__(self) -> "SolrClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()