hobots 1.0.0__py3-none-any.whl

hobots/__about__.py

@@ -0,0 +1,3 @@
+"""Única fonte da versão do pacote — lida pelo hatchling e por `_utils.SDK_VERSION`."""
+
+__version__ = "1.0.0"

hobots/__init__.py

@@ -0,0 +1,159 @@
+"""SDK Python da Hobots — telemetria e execução remota de tarefas (tasks).
+
+Duas capabilities, um único `init()`:
+
+- **Telemetria** — erros, transactions de performance e heartbeat. Sempre ativa.
+  Alimenta os módulos **Issues** e **Agentes** do app.
+- **Tasks** — execução sob demanda (polling, logs, cancelamento, anexos). Liga com
+  `tasks=True`. Alimenta o módulo **Solicitações**.
+
+    import hobots
+
+    hobots.init(client_secret="hb_<64 hex>", instance_id="vm-01", tasks=True)
+
+    @hobots.task("processar-nfe")
+    def processar(params, ctx):
+        ctx.log.info(f"processando lote {params['lote']}…")
+
+    hobots.run_forever()
+
+Todas as durações da API são em **milissegundos** (`ctx.sleep(2000)` são 2 segundos),
+igual ao SDK Node. Documentação completa em `docs/`.
+"""
+
+from __future__ import annotations
+
+from .__about__ import __version__
+from ._client import Client
+from ._config import DEFAULT_BASE_URL, ResolvedConfig
+from ._core import (
+    add_breadcrumb,
+    capture_exception,
+    capture_message,
+    close,
+    flush,
+    get_client,
+    init,
+    register,
+    run_forever,
+    set_context,
+    set_extra,
+    set_tag,
+    set_tags,
+    set_user,
+    start,
+    start_transaction,
+    stop,
+    task,
+    with_scope,
+)
+from ._errors import HobotsError, RunCanceled, TasksApiError, TaskTimeout, TransportError
+from ._scope import Scope
+from ._scrub import scrub_secrets
+from ._transaction import Step, Transaction
+from ._types import (
+    BeforeSend,
+    BreadcrumbInput,
+    CaptureHint,
+    HeartbeatOptions,
+    InitOptions,
+    TasksOptions,
+)
+from .protocol import (
+    Breadcrumb,
+    Envelope,
+    EnvelopeItem,
+    EventPayload,
+    EventUser,
+    ExceptionData,
+    HeartbeatPayload,
+    Severity,
+    StackFrame,
+    StepData,
+    StepStatus,
+    TransactionPayload,
+)
+from .tasks._attachments import AttachResult
+from .tasks._context import RunContext, RunLogger
+from .tasks._types import TaskHandler
+from .tasks.protocol import (
+    AgentInfo,
+    PollRequest,
+    PollResponse,
+    RunAttachmentContentType,
+    RunDescriptor,
+    RunError,
+    RunLogEntry,
+    RunLogLevel,
+    RunStatus,
+    RunUpdateRequest,
+    RunUpdateStatus,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "AgentInfo",
+    "AttachResult",
+    "BeforeSend",
+    "Breadcrumb",
+    "BreadcrumbInput",
+    "CaptureHint",
+    "Client",
+    "Envelope",
+    "EnvelopeItem",
+    "EventPayload",
+    "EventUser",
+    "ExceptionData",
+    "HeartbeatOptions",
+    "HeartbeatPayload",
+    "HobotsError",
+    "InitOptions",
+    "PollRequest",
+    "PollResponse",
+    "ResolvedConfig",
+    "RunAttachmentContentType",
+    "RunCanceled",
+    "RunContext",
+    "RunDescriptor",
+    "RunError",
+    "RunLogEntry",
+    "RunLogLevel",
+    "RunLogger",
+    "RunStatus",
+    "RunUpdateRequest",
+    "RunUpdateStatus",
+    "Scope",
+    "Severity",
+    "StackFrame",
+    "Step",
+    "StepData",
+    "StepStatus",
+    "TaskHandler",
+    "TaskTimeout",
+    "TasksApiError",
+    "TasksOptions",
+    "Transaction",
+    "TransactionPayload",
+    "TransportError",
+    "__version__",
+    "add_breadcrumb",
+    "capture_exception",
+    "capture_message",
+    "close",
+    "flush",
+    "get_client",
+    "init",
+    "register",
+    "run_forever",
+    "scrub_secrets",
+    "set_context",
+    "set_extra",
+    "set_tag",
+    "set_tags",
+    "set_user",
+    "start",
+    "start_transaction",
+    "stop",
+    "task",
+    "with_scope",
+]

hobots/_client.py

@@ -0,0 +1,206 @@
+"""O `Client`: prepara eventos (merge de scope/hint) e é dono do transport."""
+
+from __future__ import annotations
+
+import platform
+import random
+import sys
+from typing import Any, Dict, List, Optional
+
+from ._config import ResolvedConfig, resolve_config
+from ._eventbuilder import event_from_exception, event_from_message
+from ._scope import Scope
+from ._transport import Transport
+from ._types import CaptureHint, InitOptions
+from ._utils import Logger, truncate
+from .protocol import EventPayload, HeartbeatPayload, Severity, TransactionPayload
+
+# Limites do servidor (zod). Um único campo acima do limite devolve 422 para o
+# envelope INTEIRO — que pode carregar até 50 itens. Vale truncar no cliente.
+MAX_TAG_VALUE_CHARS = 512
+MAX_BREADCRUMB_MESSAGE_CHARS = 4_096
+MAX_FINGERPRINT_ITEMS = 10
+MAX_FINGERPRINT_ITEM_CHARS = 255
+MAX_TRANSACTION_NAME_CHARS = 500
+MAX_STEPS = 200
+
+
+def _runtime_contexts() -> Dict[str, Dict[str, Any]]:
+    return {
+        "runtime": {
+            "name": "python",
+            "version": platform.python_version(),
+            "implementation": platform.python_implementation(),
+        },
+        "os": {"name": sys.platform, "arch": platform.machine()},
+    }
+
+
+def _clip_tags(tags: Dict[str, str]) -> Dict[str, str]:
+    return {str(k): truncate(str(v), MAX_TAG_VALUE_CHARS) for k, v in tags.items()}
+
+
+class Client:
+    """Cliente resolvido do SDK. Obtido com `hobots.get_client()`.
+
+    O Client Secret nunca aparece em `repr()`/serialização — só no acesso explícito
+    (`client.options.client_secret` / `client.config.key`).
+    """
+
+    def __init__(self, options: InitOptions, config: Optional[ResolvedConfig] = None) -> None:
+        self.__options = options
+        self.__config = config or resolve_config(options.client_secret)
+        self.logger = Logger(options.debug)
+        self._transport = Transport(
+            endpoint=self.__config.ingest_endpoint,
+            key=self.__config.key,
+            logger=self.logger,
+            flush_interval=options.flush_interval,
+            max_batch_size=options.max_batch_size,
+        )
+
+    @property
+    def options(self) -> InitOptions:
+        return self.__options
+
+    @property
+    def config(self) -> ResolvedConfig:
+        return self.__config
+
+    def __repr__(self) -> str:
+        return f"Client(base_url={self.__config.base_url!r})"
+
+    # ── Captura ───────────────────────────────────────────────────────────────
+
+    def capture_exception(self, error: Any, hint: Optional[CaptureHint], scope: Scope) -> str:
+        level: Severity = (hint or {}).get("level", "error")
+        return self.capture_event(event_from_exception(error, level), hint, scope)
+
+    def capture_message(self, message: str, level: Severity, hint: Optional[CaptureHint], scope: Scope) -> str:
+        return self.capture_event(event_from_message(message, level), hint, scope)
+
+    def capture_event(self, event: EventPayload, hint: Optional[CaptureHint], scope: Scope) -> str:
+        sample_rate = self.__options.sample_rate
+        if sample_rate < 1 and random.random() >= sample_rate:
+            self.logger.debug("evento descartado por sample_rate")
+            return event["event_id"]
+
+        prepared = self._prepare_event(event, hint, scope)
+
+        before_send = self.__options.before_send
+        if before_send is not None:
+            try:
+                final = before_send(prepared)
+            except Exception as error:  # noqa: BLE001
+                # capture_exception costuma ser chamado dentro de um `except` do
+                # usuário: um before_send que levanta não pode derrubar o programa
+                self.logger.error("before_send levantou uma exceção, evento descartado:", error)
+                return event["event_id"]
+            if final is None:
+                self.logger.debug("evento descartado por before_send")
+                return event["event_id"]
+        else:
+            final = prepared
+
+        self._transport.enqueue({"type": "event", "payload": final})
+        return final["event_id"]
+
+    def _prepare_event(self, event: EventPayload, hint: Optional[CaptureHint], scope: Scope) -> EventPayload:
+        hint = hint or {}
+        options = self.__options
+
+        tags: Dict[str, str] = {}
+        tags.update(options.tags or {})
+        tags.update(scope.tags)
+        tags.update(event.get("tags") or {})
+        tags.update(hint.get("tags") or {})
+
+        extra: Dict[str, Any] = {}
+        extra.update(scope.extra)
+        extra.update(event.get("extra") or {})
+        extra.update(hint.get("extra") or {})
+
+        contexts: Dict[str, Dict[str, Any]] = _runtime_contexts()
+        contexts.update(scope.contexts)
+        contexts.update(event.get("contexts") or {})
+
+        prepared: EventPayload = dict(event)  # type: ignore[assignment]
+        # `scope.level` não entra aqui de propósito: o eventbuilder já grava o level
+        # (error na exceção, o argumento na mensagem). Para sobrescrever, use o hint.
+        prepared["level"] = hint.get("level") or event["level"]
+        prepared["environment"] = event.get("environment") or options.environment or "production"
+        prepared["contexts"] = contexts
+
+        release = event.get("release") or options.release
+        if release:
+            prepared["release"] = release
+        if tags:
+            prepared["tags"] = _clip_tags(tags)
+        if extra:
+            prepared["extra"] = extra
+
+        user = event.get("user") or scope.user
+        if user:
+            prepared["user"] = user
+
+        breadcrumbs = list(scope.breadcrumbs) if scope.breadcrumbs else (event.get("breadcrumbs") or [])
+        if breadcrumbs:
+            prepared["breadcrumbs"] = [self._clip_breadcrumb(crumb) for crumb in breadcrumbs]
+
+        fingerprint = hint.get("fingerprint") or event.get("fingerprint") or scope.fingerprint
+        if fingerprint:
+            prepared["fingerprint"] = [
+                truncate(str(item), MAX_FINGERPRINT_ITEM_CHARS) for item in fingerprint[:MAX_FINGERPRINT_ITEMS]
+            ]
+
+        return prepared
+
+    @staticmethod
+    def _clip_breadcrumb(crumb: Any) -> Any:
+        message = crumb.get("message")
+        if isinstance(message, str) and len(message) > MAX_BREADCRUMB_MESSAGE_CHARS:
+            clipped = dict(crumb)
+            clipped["message"] = truncate(message, MAX_BREADCRUMB_MESSAGE_CHARS)
+            return clipped
+        return crumb
+
+    # ── Envio direto ──────────────────────────────────────────────────────────
+
+    def send_transaction(self, payload: TransactionPayload) -> None:
+        options = self.__options
+        final: TransactionPayload = dict(payload)  # type: ignore[assignment]
+        final["name"] = truncate(payload["name"] or "(sem nome)", MAX_TRANSACTION_NAME_CHARS)
+        final["environment"] = payload.get("environment") or options.environment or "production"
+        if len(final["steps"]) > MAX_STEPS:
+            self.logger.warn(f"transaction com {len(final['steps'])} steps — enviando as primeiras {MAX_STEPS}")
+            final["steps"] = final["steps"][:MAX_STEPS]
+
+        release = payload.get("release") or options.release
+        if release:
+            final["release"] = release
+
+        tags: Dict[str, str] = {}
+        tags.update(options.tags or {})
+        tags.update(payload.get("tags") or {})
+        if tags:
+            final["tags"] = _clip_tags(tags)
+
+        self._transport.enqueue({"type": "transaction", "payload": final})
+
+    def send_heartbeat(self, payload: HeartbeatPayload) -> None:
+        final: HeartbeatPayload = dict(payload)  # type: ignore[assignment]
+        release = payload.get("release") or self.__options.release
+        if release:
+            final["release"] = release
+        self._transport.enqueue({"type": "heartbeat", "payload": final})
+
+    # ── Ciclo de vida ─────────────────────────────────────────────────────────
+
+    def flush(self, timeout: int = 5_000) -> bool:
+        return self._transport.flush(timeout)
+
+    def close(self, timeout: int = 5_000) -> bool:
+        return self._transport.close(timeout)
+
+
+__all__: List[str] = ["Client"]

hobots/_config.py

@@ -0,0 +1,126 @@
+"""Validação do Client Secret e resolução dos endpoints.
+
+Nenhuma mensagem de erro aqui pode ecoar o valor do secret ou a URL completa —
+a env pode conter credenciais embutidas por engano.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from dataclasses import dataclass
+from typing import Optional
+from urllib.parse import urlsplit
+
+#: API oficial da Hobots — o SDK sempre fala com ela em produção.
+DEFAULT_BASE_URL = "https://api2.hobots.app"
+
+#: hb_<64 hex>
+_SECRET_PATTERN = re.compile(r"^hb_[a-f0-9]{64}$", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class ResolvedConfig:
+    """Endpoints derivados do Client Secret, resolvidos uma vez por `init()`."""
+
+    #: Client Secret do agente (enviado como Authorization: Bearer, nunca na URL)
+    key: str
+    base_url: str
+    #: Ingestão de telemetria: <base_url>/v1/ingest
+    ingest_endpoint: str
+    #: API de tasks (execução sob demanda): <base_url>/v1/tasks
+    tasks_base_url: str
+
+    def __repr__(self) -> str:
+        # o secret nunca aparece na representação padrão da dataclass
+        return f"ResolvedConfig(base_url={self.base_url!r})"
+
+
+def _env_base_url() -> Optional[str]:
+    """Override de desenvolvimento via env HOBOTS_API_URL — a única forma de apontar
+    o SDK para outro host. Em produção a URL é sempre a API oficial."""
+    raw = os.environ.get("HOBOTS_API_URL")
+    if raw is None:
+        return None
+    return raw.strip() or None
+
+
+def _is_loopback_host(hostname: str) -> bool:
+    return (
+        hostname == "localhost"
+        or hostname.endswith(".localhost")
+        or hostname.startswith("127.")
+        or hostname in ("::1", "[::1]", "0.0.0.0")
+    )
+
+
+# warning de http remoto sai uma vez por processo
+_warned_insecure_base_url = False
+
+
+def _reset_insecure_warning_for_testing() -> None:
+    global _warned_insecure_base_url
+    _warned_insecure_base_url = False
+
+
+def _validate_base_url(raw: str, prefix: str) -> str:
+    """Valida a base_url sem nunca ecoar o valor completo em erro/log."""
+    global _warned_insecure_base_url
+
+    invalid = f"{prefix} HOBOTS_API_URL inválida — esperado URL http(s), ex.: http://localhost:3001"
+
+    try:
+        url = urlsplit(raw)
+    except ValueError:
+        raise ValueError(invalid) from None
+
+    if not url.scheme or not url.netloc:
+        raise ValueError(invalid)
+
+    if url.scheme not in ("http", "https"):
+        raise ValueError(f'{prefix} HOBOTS_API_URL com esquema "{url.scheme}:" não suportado — use http(s)')
+
+    try:
+        has_credentials = bool(url.username or url.password)
+        hostname = url.hostname or ""
+    except ValueError:
+        # netloc malformado (ex.: porta inválida) — não ecoar o valor
+        raise ValueError(invalid) from None
+
+    if has_credentials:
+        raise ValueError(
+            f"{prefix} HOBOTS_API_URL não pode conter credenciais na URL — a autenticação é só pelo Client Secret"
+        )
+
+    if url.scheme == "http" and not _is_loopback_host(hostname) and not _warned_insecure_base_url:
+        _warned_insecure_base_url = True
+        print(
+            f'{prefix} HOBOTS_API_URL usa http para o host remoto "{hostname}" — o Client Secret trafega sem TLS',
+            file=sys.stderr,
+            flush=True,
+        )
+
+    return raw.rstrip("/")
+
+
+def resolve_config(client_secret: Optional[str], prefix: str = "[hobots]") -> ResolvedConfig:
+    """Resolve o client_secret nos endpoints de telemetria e de tasks."""
+    key = (client_secret or "").strip()
+    if not key:
+        raise ValueError(f"{prefix} client_secret ausente — copie o Client Secret do agente em Configurações → Agentes")
+    if not _SECRET_PATTERN.match(key):
+        # nunca incluir o valor na mensagem — só o tamanho, como pista de diagnóstico
+        raise ValueError(
+            f"{prefix} client_secret com formato inválido ({len(key)} caracteres) — esperado "
+            f'"hb_" + 64 hex; copie o Client Secret do agente em Configurações → Agentes'
+        )
+
+    base_url = _validate_base_url(_env_base_url() or DEFAULT_BASE_URL, prefix)
+
+    return ResolvedConfig(
+        key=key,
+        base_url=base_url,
+        ingest_endpoint=f"{base_url}/v1/ingest",
+        tasks_base_url=f"{base_url}/v1/tasks",
+    )