imbi-plugin-sentry 2.46.0__tar.gz

imbi_plugin_sentry-2.46.0/.gitignore

@@ -0,0 +1,30 @@
+__pycache__
+*.egg-info
+*.pyc
+*.env
+.env
+.env.test
+build/
+dist/
+docs/site/
+helm/imbi/charts/
+runtime/state/
+.venv/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+coverage.xml
+site/
+
+# moon
+.moon/cache
+.moon/docker
+
+# design-sync
+.design-sync/sb-reference/
+.design-sync/learnings/
+.design-sync/.cache/
+.design-sync/node_modules
+.ds-sync/
+ds-bundle/

imbi_plugin_sentry-2.46.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.5
+Name: imbi-plugin-sentry
+Version: 2.46.0
+Summary: Sentry integration plugin for Imbi
+Author-email: "Gavin M. Roy" <gavinr@aweber.com>
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.27
+Requires-Dist: imbi-common==2.46.0
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# imbi-plugin-sentry
+
+Sentry integration plugin for Imbi (Plugin Architecture v3). See
+[the plugin documentation](https://aweber-imbi.github.io/imbi/plugins/sentry/).

imbi_plugin_sentry-2.46.0/README.md

@@ -0,0 +1,4 @@
+# imbi-plugin-sentry
+
+Sentry integration plugin for Imbi (Plugin Architecture v3). See
+[the plugin documentation](https://aweber-imbi.github.io/imbi/plugins/sentry/).

imbi_plugin_sentry-2.46.0/moon.yml

@@ -0,0 +1,22 @@
+# yaml-language-server: $schema=https://moonrepo.dev/schemas/project.json
+layer: 'library'
+stack: 'backend'
+language: 'python'
+tags:
+  - 'python'
+
+project:
+  name: 'imbi-plugin-sentry'
+  description: 'Sentry plugin for Imbi'
+
+dependsOn:
+  - 'common'
+
+# Inherits lint / format / typecheck / test from .moon/tasks/python.yml. The
+# shared test task points --cov-config at this member's pyproject, where
+# [tool.coverage] scopes source + threshold to the member.
+tasks:
+  test:
+    args:
+      - '--cov'
+      - '--cov-report=term-missing'

imbi_plugin_sentry-2.46.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "imbi-plugin-sentry"
+version = "2.46.0"
+description = "Sentry integration plugin for Imbi"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "BSD-3-Clause"
+authors = [
+  { name = "Gavin M. Roy", email = "gavinr@aweber.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+  "httpx>=0.27",
+  "imbi-common==2.46.0",
+  "pydantic>=2",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# Coverage for the per-member `moon run sentry:test` run. Scoped to this
+# member so the report/threshold reflect only imbi.plugins.sentry; the aggregate
+# `root:coverage` run uses the root pyproject config instead.
+[tool.coverage.run]
+branch = true
+source_pkgs = ["imbi.plugins.sentry"]
+
+[tool.coverage.report]
+exclude_also = ["typing.TYPE_CHECKING"]
+fail_under = 85
+show_missing = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/imbi"]
+include = [
+  "src/imbi/plugins/sentry/py.typed",
+]

imbi_plugin_sentry-2.46.0/src/imbi/plugins/sentry/__init__.py

@@ -0,0 +1,9 @@
+from importlib import metadata
+
+from imbi.plugins.sentry.plugin import SentryPlugin
+
+#: Discovered by the imbi-common registry's convention scan.
+PLUGIN = SentryPlugin
+
+version = metadata.version('imbi-plugin-sentry')
+__all__ = ['PLUGIN', 'SentryPlugin', 'version']

imbi_plugin_sentry-2.46.0/src/imbi/plugins/sentry/actions.py

@@ -0,0 +1,90 @@
+"""Webhook action: sync the project's Sentry issue-count facts."""
+
+import logging
+import typing
+import urllib.parse
+
+import pydantic
+import pydantic_settings
+
+from imbi.common.api import client as api_client
+from imbi.common.plugins import base as plugin_base
+from imbi.plugins.sentry import client
+
+LOGGER = logging.getLogger(__name__)
+
+
+class _ImbiSettings(pydantic_settings.BaseSettings):
+    """Imbi API connection settings, the same environment variables the
+    gateway's own actions read (see the SonarQube plugin)."""
+
+    model_config = {'env_prefix': 'IMBI_GATEWAY_'}
+
+    imbi_url: pydantic.HttpUrl = pydantic.Field(
+        default=pydantic.HttpUrl('http://localhost:8000'),
+        validation_alias='IMBI_INTERNAL_API_URL',
+    )
+    # imbi-api mounts its routers under the path of its public URL.
+    api_public_url: str = pydantic.Field(
+        default='', validation_alias='IMBI_API_URL'
+    )
+    api_token: str
+
+    @property
+    def api_base_url(self) -> str:
+        prefix = urllib.parse.urlparse(self.api_public_url).path.rstrip('/')
+        return str(self.imbi_url).rstrip('/') + prefix
+
+
+class SyncIssueCountsConfig(pydantic.BaseModel):
+    """No settings: the facts and searches are Integration options."""
+
+
+async def sync_issue_counts(
+    *,
+    ctx: plugin_base.PluginContext,
+    credentials: dict[str, str],
+    external_identifier: str,
+    action_config: SyncIssueCountsConfig,
+    event: object,
+) -> None:
+    """Re-count the project's Sentry issues and patch the facts.
+
+    ``external_identifier`` is the Sentry project slug the gateway
+    matched against ``EXISTS_IN.identifier``. The count is read from
+    Sentry, not derived from the event, so a missed delivery cannot make
+    the fact drift.
+    """
+    del action_config, event
+    try:
+        s = client.settings(ctx, credentials)
+        project = await client.get_project(s, external_identifier)
+        if project is None:
+            LOGGER.warning(
+                'Sentry project %r not found; skipping', external_identifier
+            )
+            return
+        counts = await client.count_all(ctx, s, project)
+    except client.SentryClientError:
+        LOGGER.exception(
+            'Failed to count Sentry issues for %r', external_identifier
+        )
+        return
+    await _patch_imbi_project(
+        ctx.org_slug,
+        ctx.project_id,
+        [
+            {'op': 'add', 'path': f'/{fact}', 'value': count}
+            for fact, count in counts.items()
+        ],
+    )
+
+
+async def _patch_imbi_project(
+    org_slug: str, project_id: str, patch: list[dict[str, typing.Any]]
+) -> None:
+    settings = _ImbiSettings()  # type: ignore[call-arg]
+    async with api_client.Imbi(
+        base_url=settings.api_base_url, token=settings.api_token, timeout=30.0
+    ) as imbi:
+        await imbi.patch_project(org_slug, project_id, patch)

imbi_plugin_sentry-2.46.0/src/imbi/plugins/sentry/client.py

@@ -0,0 +1,298 @@
+"""Sentry REST API client, plus the settings every capability shares."""
+
+import asyncio
+import importlib.metadata
+import re
+import typing
+import urllib.parse
+
+import httpx
+
+from imbi.common.plugins.base import PluginContext, ServiceWriteback
+
+_VERSION = importlib.metadata.version('imbi-plugin-sentry')
+
+#: Project link key the issues URL is written under.
+LINK_KEY = 'sentry'
+
+#: Fact name -> Sentry issue search, when the operator sets none.
+DEFAULT_ISSUE_COUNT_FACTS = {'sentry_open_issues': 'is:unresolved'}
+
+#: Issue search window, when the operator sets none. Sentry's issue
+#: stream defaults to the same window, so the linked page shows the
+#: issues that were counted.
+DEFAULT_ISSUE_PERIOD = '14d'
+
+
+class SentryClientError(Exception):
+    """Raised on non-2xx responses or transport errors."""
+
+
+_SLUG_RE = re.compile(r'[A-Za-z0-9_-]+')
+
+
+class Settings(typing.NamedTuple):
+    """What every Sentry call needs, resolved from the Integration."""
+
+    base_url: str
+    organization: str
+    auth_token: str
+
+
+def settings(ctx: PluginContext, credentials: dict[str, str]) -> Settings:
+    """Resolve the Integration settings, or raise :class:`SentryClientError`.
+
+    The message is the one the operator sees, so it names what to set.
+    """
+    base_url = str(ctx.integration_options.get('service_url') or '').strip()
+    organization = str(
+        ctx.integration_options.get('organization') or ''
+    ).strip()
+    auth_token = credentials.get('auth_token', '')
+    if not organization:
+        raise SentryClientError('The Integration has no organization set.')
+    if not auth_token:
+        raise SentryClientError('No auth_token credential configured.')
+    return Settings(
+        (base_url or 'https://sentry.io').rstrip('/'), organization, auth_token
+    )
+
+
+def _mapping(ctx: PluginContext, name: str) -> dict[str, str]:
+    """Return the ``mapping`` option ``name`` as ``dict[str, str]``."""
+    raw: object = ctx.integration_options.get(name)
+    if not isinstance(raw, dict):
+        return {}
+    items = typing.cast('dict[object, object]', raw).items()
+    return {str(k): str(v) for k, v in items}
+
+
+def issue_count_facts(ctx: PluginContext) -> dict[str, str]:
+    """Return the configured ``fact name -> Sentry issue search`` map."""
+    return _mapping(ctx, 'issue_count_facts') or dict(
+        DEFAULT_ISSUE_COUNT_FACTS
+    )
+
+
+def issue_period(ctx: PluginContext) -> str:
+    raw = str(ctx.integration_options.get('issue_period') or '').strip()
+    return raw or DEFAULT_ISSUE_PERIOD
+
+
+def sentry_team(ctx: PluginContext) -> str | None:
+    """Return the Sentry team that owns the project's Sentry project.
+
+    The ``team_mapping`` option wins; an unmapped team uses its own slug.
+    """
+    if ctx.team_slug is None:
+        return None
+    return _mapping(ctx, 'team_mapping').get(ctx.team_slug) or ctx.team_slug
+
+
+def writeback(
+    ctx: PluginContext, s: Settings, project: dict[str, typing.Any]
+) -> ServiceWriteback:
+    """Build the ``EXISTS_IN`` edge + issues link for a Sentry project."""
+    slug = str(project['slug'])
+    query = urllib.parse.urlencode(
+        {'project': project['id'], 'statsPeriod': issue_period(ctx)}
+    )
+    return ServiceWriteback(
+        identifier=slug,
+        canonical_url=canonical_url(s, slug),
+        dashboard_links={
+            LINK_KEY: (
+                f'{s.base_url}/organizations/{s.organization}/issues/?{query}'
+            )
+        },
+    )
+
+
+def _q(segment: str) -> str:
+    """Return a Sentry slug for a URL path, or raise.
+
+    Sentry slugs hold only letters, digits, ``-`` and ``_``. Anything
+    else (``..``, ``/``, encoded forms of either) could point a call at a
+    different API path, because httpx normalizes the path.
+    """
+    if not _SLUG_RE.fullmatch(segment):
+        raise SentryClientError(f'{segment!r} is not a valid Sentry slug')
+    return segment
+
+
+def canonical_url(s: Settings, slug: str) -> str:
+    return f'{s.base_url}/api/0/projects/{_q(s.organization)}/{_q(slug)}/'
+
+
+async def _request(
+    s: Settings,
+    method: str,
+    path: str,
+    *,
+    params: dict[str, str] | None = None,
+    json: dict[str, typing.Any] | None = None,
+) -> httpx.Response:
+    headers = {
+        'Authorization': f'Bearer {s.auth_token}',
+        'Accept': 'application/json',
+        'User-Agent': f'imbi-plugin-sentry/{_VERSION}',
+    }
+    try:
+        # Within the host's default 10 second plugin deadline.
+        async with httpx.AsyncClient(timeout=10.0) as http_client:
+            return await http_client.request(
+                method,
+                f'{s.base_url}/api/0{path}',
+                params=params,
+                json=json,
+                headers=headers,
+            )
+    except httpx.RequestError as exc:
+        raise SentryClientError(f'Sentry request failed: {exc}') from exc
+
+
+def _raise_for_error(response: httpx.Response) -> None:
+    if response.is_error:
+        raise SentryClientError(
+            f'Sentry returned status {response.status_code}: '
+            f'{response.text[:200]}'
+        )
+
+
+def _json(response: httpx.Response) -> dict[str, typing.Any]:
+    _raise_for_error(response)
+    try:
+        payload: object = response.json()
+    except ValueError as exc:
+        raise SentryClientError('Sentry returned non-JSON response') from exc
+    if not isinstance(payload, dict):
+        raise SentryClientError('Sentry returned an unexpected payload')
+    return typing.cast('dict[str, typing.Any]', payload)
+
+
+async def get_project(s: Settings, slug: str) -> dict[str, typing.Any] | None:
+    """Return the Sentry project ``slug``, or ``None`` when it is absent."""
+    response = await _request(
+        s, 'GET', f'/projects/{_q(s.organization)}/{_q(slug)}/'
+    )
+    if response.status_code == 404:
+        return None
+    return _json(response)
+
+
+async def create_project(
+    s: Settings, team: str, slug: str, name: str
+) -> dict[str, typing.Any]:
+    """Create a Sentry project owned by ``team``.
+
+    Sentry answers ``404`` when the team does not exist.
+    """
+    response = await _request(
+        s,
+        'POST',
+        f'/teams/{_q(s.organization)}/{_q(team)}/projects/',
+        json={'name': name, 'slug': slug},
+    )
+    if response.status_code == 404:
+        raise SentryClientError(
+            f'Sentry team {team!r} does not exist; map the Imbi team to a '
+            'Sentry team in the team_mapping option.'
+        )
+    return _json(response)
+
+
+def team_slugs(project: dict[str, typing.Any]) -> list[str]:
+    """Return the slugs of the teams that own a Sentry project."""
+    teams: object = project.get('teams') or []
+    if not isinstance(teams, list):
+        return []
+    return [
+        str(typing.cast('dict[str, typing.Any]', t).get('slug'))
+        for t in typing.cast('list[object]', teams)
+        if isinstance(t, dict)
+    ]
+
+
+def may_link(project: dict[str, typing.Any], team: str | None) -> bool:
+    """Return whether Imbi may link an existing Sentry project.
+
+    Only when no team owns it, or ``team`` already does: linking a
+    project owned only by other teams would hand it to this project.
+    """
+    current = team_slugs(project)
+    return not current or team in current
+
+
+async def set_team(
+    s: Settings, project: dict[str, typing.Any], team: str
+) -> list[str]:
+    """Make ``team`` the only team that owns ``project``.
+
+    Removes other teams only when ``team`` already owns the project, so
+    someone with access in Sentry has granted it; a project with no team
+    gets ``team`` added. Otherwise raises, because replacing the owners
+    of a project that ``team`` has no claim to would take it from them.
+    Returns the removed team slugs.
+    """
+    slug = str(project['slug'])
+    path = f'/projects/{_q(s.organization)}/{_q(slug)}/teams'
+    current = team_slugs(project)
+    if current and team not in current:
+        raise SentryClientError(
+            f'Sentry team {team!r} does not own this project; add it to the '
+            'project in Sentry first.'
+        )
+    if not current:
+        response = await _request(s, 'POST', f'{path}/{_q(team)}/')
+        if response.status_code == 404:
+            raise SentryClientError(
+                f'Sentry team {team!r} does not exist; map the Imbi team to '
+                'a Sentry team in the team_mapping option.'
+            )
+        _raise_for_error(response)
+    removed = [t for t in current if t != team]
+    for other in removed:
+        _raise_for_error(await _request(s, 'DELETE', f'{path}/{_q(other)}/'))
+    return removed
+
+
+async def count_issues(
+    s: Settings, project_id: str, query: str, period: str
+) -> int:
+    """Count the project's issues that match ``query`` in ``period``.
+
+    Reads the ``X-Hits`` header of the organization issues endpoint.
+    """
+    # ponytail: X-Hits is approximate and caps at 1000; paginate the
+    # issue list if a fact needs an exact count past that.
+    response = await _request(
+        s,
+        'GET',
+        f'/organizations/{_q(s.organization)}/issues/',
+        params={
+            'project': project_id,
+            'query': query,
+            'statsPeriod': period,
+            'limit': '1',
+        },
+    )
+    _raise_for_error(response)
+    hits = response.headers.get('X-Hits')
+    if hits is None or not hits.isdigit():
+        raise SentryClientError('Sentry returned no X-Hits issue count')
+    return int(hits)
+
+
+async def count_all(
+    ctx: PluginContext, s: Settings, project: dict[str, typing.Any]
+) -> dict[str, int]:
+    """Return ``{fact name: issue count}`` for every configured fact."""
+    period = issue_period(ctx)
+    facts = issue_count_facts(ctx)
+    counts = await asyncio.gather(
+        *(
+            count_issues(s, str(project['id']), query, period)
+            for query in facts.values()
+        )
+    )
+    return dict(zip(facts, counts, strict=True))