ginkgo-slack 0.4.0__tar.gz

ginkgo_slack-0.4.0/.gitignore

@@ -0,0 +1,58 @@
+# Local environment and tool caches
+.pixi/*
+!.pixi/config.toml
+.pytest_cache/
+.ruff_cache/
+ui/node_modules/
+ui/.vite/
+__pycache__/
+*.py[cod]
+
+*__pycache__*
+# Ginkgo runtime state
+.ginkgo/
+examples/**/logs/
+examples/**/results/
+benchmarks/results/
+
+# Agent / local-instructions files
+AGENTS.md
+# ...but not the one `ginkgo init` scaffolds into new projects.
+!src/ginkgo/templates/init/agents/AGENTS.md
+CLAUDE.md
+.claude/
+.agents/
+
+# uncoded symbol index (regenerated locally via `uncoded sync`)
+.uncoded/
+
+# Local planning / design / worklog docs
+plan.md
+*plan.local.md
+worklog.md
+*worklog*.md
+ginkgo-design-doc.md
+example-workflow.py
+docs/_build/
+docs/site/node_modules/
+docs/site/dist/
+docs/site/.astro/
+
+# OS/editor noise
+.DS_Store
+
+*.lock
+# Env lockfiles that are part of a fixture or example are inputs, not build
+# output: an example whose lock is missing re-solves on first use, which
+# changes its env identity between runs and silently breaks cache reuse.
+!tests/**/pixi.lock
+!plugins/**/pixi.lock
+!examples/**/pixi.lock
+
+# Maintainer working documents (CLAUDE.md: plans are not committed)
+docs/*-plan.md
+docs/user-testing-*.md
+docs/oke-validation.md
+docs/*.pptx
+scratchpad/
+.vscode/

ginkgo_slack-0.4.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.5
+Name: ginkgo-slack
+Version: 0.4.0
+Summary: Slack run notifications for ginkgo
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: ginkgo-workflow==0.4.0
+Description-Content-Type: text/markdown
+
+# ginkgo-slack
+
+Slack run notifications for ginkgo.
+
+A plugin for [Ginkgo](https://sanjaynagi.github.io/ginkgo/). Install it with `pip install "ginkgo-workflow[slack]"`, and see the [plugins guide](https://sanjaynagi.github.io/ginkgo/getting-started/installation/#plugins).

ginkgo_slack-0.4.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "ginkgo-slack"
+version = "0.4.0"
+description = "Slack run notifications for ginkgo"
+requires-python = ">= 3.11"
+readme = { text = "# ginkgo-slack\n\nSlack run notifications for ginkgo.\n\nA plugin for [Ginkgo](https://sanjaynagi.github.io/ginkgo/). Install it with `pip install \"ginkgo-workflow[slack]\"`, and see the [plugins guide](https://sanjaynagi.github.io/ginkgo/getting-started/installation/#plugins).", content-type = "text/markdown" }
+license = "Apache-2.0"
+dependencies = [
+    "ginkgo-workflow==0.4.0",
+]
+
+[project.entry-points."ginkgo.plugins"]
+slack = "ginkgo_slack:PLUGIN"
+
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ginkgo_slack"]

ginkgo_slack-0.4.0/src/ginkgo_slack/__init__.py

@@ -0,0 +1,15 @@
+"""ginkgo-slack: posts run notifications to a Slack incoming webhook."""
+
+from __future__ import annotations
+
+from ginkgo.plugins.api import EventSubscriberType, Plugin
+from ginkgo_slack.subscriber import build_slack_subscriber, check_slack_config
+
+__all__ = ["PLUGIN"]
+
+PLUGIN = Plugin(
+    name="ginkgo-slack",
+    contributions=(
+        EventSubscriberType(name="slack", build=build_slack_subscriber, check=check_slack_config),
+    ),
+)

ginkgo_slack-0.4.0/src/ginkgo_slack/subscriber.py

@@ -0,0 +1,434 @@
+"""Slack run notifications: configuration and the delivery subscriber."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ginkgo.core.secret import SecretRef
+from ginkgo.plugins.api import (
+    EventSubscriberCheckContext,
+    EventSubscriberConfigProblem,
+    EventSubscriberContext,
+)
+from ginkgo.plugins.registry import PluginNotFoundError
+from ginkgo.runtime.events import GinkgoEvent, RunCompleted, RunStarted, TaskFailed
+from ginkgo_slack.webhook import (
+    SlackDeliveryError,
+    SlackTaskFailure,
+    SlackUnreachableError,
+    build_retry_exhausted_payload,
+    build_run_failed_payload,
+    build_run_started_payload,
+    build_run_succeeded_payload,
+    post_slack_message,
+)
+from ginkgo.runtime.rundir import combined_log_tail
+from ginkgo.runtime.environment.secrets import SecretResolutionError, SecretResolver
+from ginkgo.runtime.run_summary import RunSummary, TaskSummary
+from ginkgo.store.protocol import ProvenanceStore
+
+
+VALID_NOTIFICATION_EVENTS = frozenset(
+    {"run_started", "run_succeeded", "run_failed", "retry_exhausted"}
+)
+EVENT_ALIASES = {"run_completed": "run_succeeded"}
+
+#: The settings ``[notifications.slack]`` accepts, with each integer's bounds.
+_INT_SETTINGS = {"log_tail_lines": (1, 25), "max_failed_tasks": (1, 10)}
+_SETTINGS = frozenset({"enabled", "webhook", "events", *_INT_SETTINGS})
+_TABLE = "[notifications.slack]"
+_WEBHOOK_EXAMPLE = 'webhook = { env = "GINKGO_SLACK_WEBHOOK" }'
+
+
+@dataclass(frozen=True, kw_only=True)
+class SlackNotificationConfig:
+    """Resolved Slack notification settings.
+
+    ``ignored_events`` holds one message per ``events`` entry that names no
+    event. A misspelt entry beside valid ones is ignored rather than turning
+    every notification off, so the run still sends the events it can.
+    """
+
+    enabled: bool = False
+    webhook: SecretRef | None = None
+    events: frozenset[str] = frozenset({"run_failed"})
+    log_tail_lines: int = 10
+    max_failed_tasks: int = 3
+    ignored_events: tuple[str, ...] = ()
+
+
+@dataclass(kw_only=True)
+class SlackSubscriber:
+    """Subscribe to runtime events and deliver Slack notifications."""
+
+    config: SlackNotificationConfig
+    webhook_url: str
+    store: ProvenanceStore
+    run_id: str
+    run_dir: Path
+    workflow_path: Path
+    logger: Callable[[str], None]
+    _executor: ThreadPoolExecutor = field(
+        default_factory=lambda: ThreadPoolExecutor(
+            max_workers=1, thread_name_prefix="ginkgo-slack"
+        ),
+        init=False,
+        repr=False,
+    )
+    _futures: list[tuple[str, Future[None]]] = field(default_factory=list, init=False, repr=False)
+    _unreachable: SlackUnreachableError | None = field(default=None, init=False, repr=False)
+
+    def handle(self, event: GinkgoEvent) -> None:
+        """Handle one runtime event."""
+        if isinstance(event, RunStarted):
+            self._handle_run_started(event=event)
+            return
+        if isinstance(event, TaskFailed):
+            self._handle_task_failed(event=event)
+            return
+        if isinstance(event, RunCompleted):
+            self._handle_run_completed(event=event)
+
+    def close(self) -> None:
+        """Wait for outstanding deliveries and emit warnings for failures."""
+        self._executor.shutdown(wait=True)
+        for event_name, future in self._futures:
+            try:
+                future.result()
+            except Exception as exc:
+                self.logger(f"Slack notification for {event_name} failed: {exc}")
+
+    def _handle_run_started(self, *, event: RunStarted) -> None:
+        if "run_started" not in self.config.events:
+            return
+        payload = build_run_started_payload(
+            workflow_label=self._workflow_label,
+            run_id=event.run_id,
+            ts=event.ts,
+        )
+        self._submit(event_name="run_started", payload=payload)
+
+    def _handle_task_failed(self, *, event: TaskFailed) -> None:
+        if "retry_exhausted" not in self.config.events:
+            return
+
+        task_failure = self._retry_exhausted_failure(task_id=event.task_id)
+        if task_failure is None:
+            return
+
+        payload = build_retry_exhausted_payload(
+            workflow_label=self._workflow_label,
+            run_id=event.run_id,
+            ts=event.ts,
+            failed_task=task_failure,
+        )
+        self._submit(event_name=f"retry_exhausted ({task_failure.task_name})", payload=payload)
+
+    def _handle_run_completed(self, *, event: RunCompleted) -> None:
+        # A run someone interrupted needs no announcement: the person who
+        # stopped it is watching the terminal it stopped in, and posting it as
+        # a failure would report a deliberate act as an incident.
+        if event.status == "cancelled":
+            return
+
+        if event.status == "success":
+            if "run_succeeded" not in self.config.events:
+                return
+            payload = build_run_succeeded_payload(
+                workflow_label=self._workflow_label,
+                run_id=event.run_id,
+                ts=event.ts,
+                task_counts=event.task_counts,
+            )
+            self._submit(event_name="run_succeeded", payload=payload)
+            return
+
+        if "run_failed" not in self.config.events:
+            return
+
+        payload = build_run_failed_payload(
+            workflow_label=self._workflow_label,
+            run_id=event.run_id,
+            ts=event.ts,
+            task_counts=event.task_counts,
+            failed_tasks=self._failed_tasks(),
+            error=event.error,
+        )
+        self._submit(event_name="run_failed", payload=payload)
+
+    def _submit(self, *, event_name: str, payload: dict[str, Any]) -> None:
+        """Post *payload* in the background; *event_name* names it if delivery fails."""
+        self._futures.append((event_name, self._executor.submit(self._deliver, payload=payload)))
+
+    def _deliver(self, *, payload: dict[str, Any]) -> None:
+        """Post one payload, unless an earlier one found Slack unreachable.
+
+        Deliveries run one at a time on a single thread, so once the host has
+        failed to answer, each later notification would wait out the same
+        timeout and the run's end would wait for all of them. They are given up
+        instead, so an unreachable Slack costs a run one timeout.
+        """
+        if self._unreachable is not None:
+            raise SlackDeliveryError(f"not sent, as an earlier one failed: {self._unreachable}")
+        try:
+            post_slack_message(webhook_url=self.webhook_url, payload=payload)
+        except SlackUnreachableError as exc:
+            self._unreachable = exc
+            raise
+
+    def _summary(self) -> RunSummary:
+        """Reload the run from the ledger, which the recorder has committed."""
+        return RunSummary.load(self.store, self.run_id, runs_root=self.run_dir.parent)
+
+    def _failed_tasks(self) -> list[SlackTaskFailure]:
+        failed = self._summary().failed_tasks
+        return [self._failure(task=task) for task in failed[: self.config.max_failed_tasks]]
+
+    def _retry_exhausted_failure(self, *, task_id: str) -> SlackTaskFailure | None:
+        task = next(
+            (item for item in self._summary().tasks if item.task_key == task_id),
+            None,
+        )
+        if task is None or task.max_attempts is None or task.max_attempts < 2:
+            return None
+        if task.attempts < task.max_attempts:
+            return None
+        return self._failure(task=task)
+
+    def _failure(self, *, task: TaskSummary) -> SlackTaskFailure:
+        return SlackTaskFailure(
+            task_name=task.label,
+            exit_code=task.exit_code,
+            attempt=task.attempts,
+            max_attempts=task.max_attempts,
+            log_tail=tuple(
+                combined_log_tail(
+                    run_dir=self.run_dir,
+                    stdout_log=task.stdout_log,
+                    stderr_log=task.stderr_log,
+                    lines=self.config.log_tail_lines,
+                )
+            ),
+        )
+
+    @property
+    def _workflow_label(self) -> str:
+        try:
+            return str(self.workflow_path.relative_to(Path.cwd()))
+        except ValueError:
+            return str(self.workflow_path)
+
+
+def build_slack_subscriber(context: EventSubscriberContext) -> SlackSubscriber | None:
+    """Return a ready-to-use notification service when Slack is configured.
+
+    Parameters
+    ----------
+    context : EventSubscriberContext
+        The run being observed.
+
+    Returns
+    -------
+    SlackSubscriber | None
+        ``None`` when ``[notifications.slack]`` is disabled or has problems;
+        each problem is reported through ``context.warn``.
+    """
+    config, problems = parse_notification_config(config=context.config)
+    if not config.enabled:
+        return None
+    webhook_url = None
+    if not problems:
+        webhook_url, problem = _resolve_webhook(
+            ref=config.webhook, resolver=context.secret_resolver
+        )
+        problems = [] if problem is None else [problem]
+    if webhook_url is None:
+        for problem in problems:
+            context.warn(f"Slack notifications are off: {problem}")
+        return None
+    for message in config.ignored_events:
+        context.warn(message)
+
+    return SlackSubscriber(
+        config=config,
+        webhook_url=webhook_url,
+        store=context.store,
+        run_id=context.run_id,
+        run_dir=context.run_dir,
+        workflow_path=context.workflow_path,
+        logger=context.warn,
+    )
+
+
+def check_slack_config(context: EventSubscriberCheckContext) -> list[EventSubscriberConfigProblem]:
+    """Return every problem with ``[notifications.slack]``, for ``ginkgo doctor``.
+
+    Parameters
+    ----------
+    context : EventSubscriberCheckContext
+        The runtime config and the secret resolver a run would use.
+
+    Returns
+    -------
+    list[EventSubscriberConfigProblem]
+        One per problem; empty when a run would send notifications as
+        configured, or when they are disabled and otherwise valid. An unknown
+        event beside valid ones is not blocking: the run ignores it and still
+        sends the others.
+    """
+    config, problems = parse_notification_config(config=context.config)
+    if config.enabled and not problems:
+        _, problem = _resolve_webhook(ref=config.webhook, resolver=context.secret_resolver)
+        if problem is not None:
+            problems.append(problem)
+    return [
+        *(EventSubscriberConfigProblem(message=message) for message in problems),
+        *(
+            EventSubscriberConfigProblem(message=message, blocking=False)
+            for message in config.ignored_events
+        ),
+    ]
+
+
+def parse_notification_config(
+    *, config: Mapping[str, Any] | None
+) -> tuple[SlackNotificationConfig, list[str]]:
+    """Parse ``[notifications.slack]`` from the loaded config mapping.
+
+    Parameters
+    ----------
+    config : Mapping[str, Any] | None
+        The merged runtime config.
+
+    Returns
+    -------
+    tuple[SlackNotificationConfig, list[str]]
+        The settings, and one message per invalid or unknown setting. A setting
+        with a problem keeps its default, so the settings are only to be used
+        when there are no problems.
+    """
+    notifications = config.get("notifications", {}) if isinstance(config, Mapping) else {}
+    raw = notifications.get("slack", {}) if isinstance(notifications, Mapping) else {}
+    if not isinstance(raw, Mapping):
+        return SlackNotificationConfig(), [f"{_TABLE} must be a table."]
+
+    problems = [
+        f"{_TABLE} has no setting {key!r}; the settings are {', '.join(sorted(_SETTINGS))}."
+        for key in sorted(set(raw) - _SETTINGS, key=str)
+    ]
+    settings: dict[str, Any] = {}
+
+    enabled = raw.get("enabled", False)
+    if isinstance(enabled, bool):
+        settings["enabled"] = enabled
+    else:
+        problems.append(f"{_TABLE} enabled must be true or false, not {enabled!r}.")
+
+    if "events" in raw:
+        events, ignored, event_problems = _parse_events(raw["events"])
+        settings["events"] = events
+        settings["ignored_events"] = ignored
+        problems.extend(event_problems)
+
+    for key, (minimum, maximum) in _INT_SETTINGS.items():
+        if key not in raw:
+            continue
+        value = raw[key]
+        if isinstance(value, int) and not isinstance(value, bool) and minimum <= value <= maximum:
+            settings[key] = value
+        else:
+            problems.append(
+                f"{_TABLE} {key} must be a whole number from {minimum} to {maximum}, "
+                f"not {value!r}."
+            )
+
+    # A disabled table may leave the webhook out; one it gives must still be valid.
+    if "webhook" in raw or enabled is True:
+        webhook, problem = _parse_webhook(raw.get("webhook"))
+        settings["webhook"] = webhook
+        if problem is not None:
+            problems.append(problem)
+
+    return SlackNotificationConfig(**settings), problems
+
+
+def _parse_events(value: Any) -> tuple[frozenset[str], tuple[str, ...], list[str]]:
+    """Parse the ``events`` list.
+
+    Returns the events, one message per entry that names no event (ignored
+    while another entry is valid), and the problems that leave nothing to send.
+    """
+    if not isinstance(value, list):
+        return (
+            frozenset(),
+            (),
+            [f"{_TABLE} events must be a list of event names, not {value!r}."],
+        )
+    if not value:
+        return frozenset(), (), [f"{_TABLE} events is empty, so nothing would be sent."]
+    known = ", ".join(sorted({*VALID_NOTIFICATION_EVENTS, *EVENT_ALIASES}))
+    parsed: set[str] = set()
+    unknown: list[Any] = []
+    for item in value:
+        name = EVENT_ALIASES.get(item, item) if isinstance(item, str) else item
+        if name in VALID_NOTIFICATION_EVENTS:
+            parsed.add(name)
+        else:
+            unknown.append(item)
+    if not parsed:
+        return (
+            frozenset(),
+            (),
+            [
+                f"{_TABLE} events has no event {item!r}; the events are {known}."
+                for item in unknown
+            ],
+        )
+    ignored = tuple(
+        f"{_TABLE} events has no event {item!r}, so it is ignored and the other events "
+        f"are still sent; the events are {known}."
+        for item in unknown
+    )
+    return frozenset(parsed), ignored, []
+
+
+def _parse_webhook(value: Any) -> tuple[SecretRef | None, str | None]:
+    """Parse the webhook's secret reference, explaining the shape when it is wrong."""
+    if value is None:
+        return None, f"{_TABLE} webhook is missing; add {_WEBHOOK_EXAMPLE}."
+    if isinstance(value, str):
+        return None, (
+            f"{_TABLE} webhook must be a secret reference such as {_WEBHOOK_EXAMPLE}, "
+            "naming where the URL is kept rather than the URL itself: a webhook URL "
+            "is a credential and does not belong in config."
+        )
+    if isinstance(value, Mapping) and len(value) == 1:
+        backend, name = next(iter(value.items()))
+        if isinstance(backend, str) and isinstance(name, str) and backend.strip() and name.strip():
+            return SecretRef(name=name.strip(), backend=backend.strip()), None
+    return None, f"{_TABLE} webhook must name one secret, such as {_WEBHOOK_EXAMPLE}."
+
+
+def _resolve_webhook(
+    *, ref: SecretRef | None, resolver: SecretResolver | None
+) -> tuple[str | None, str | None]:
+    """Resolve the webhook URL, or say which secret is unset."""
+    assert ref is not None
+    if resolver is None:
+        return None, f"{_TABLE} webhook cannot be read: no secret resolver is available."
+    where = (
+        f"the environment variable {ref.name}"
+        if ref.backend == "env"
+        else f"the {ref.backend} secret {ref.name!r}"
+    )
+    try:
+        url = resolver.resolve(ref=ref)
+    except (SecretResolutionError, PluginNotFoundError):
+        url = ""
+    if not url.strip():
+        return None, f"{_TABLE} webhook reads {where}, which is unset or empty."
+    return url, None

ginkgo_slack-0.4.0/src/ginkgo_slack/webhook.py

@@ -0,0 +1,253 @@
+"""Slack notification transport and payload helpers."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from ginkgo.errors import GinkgoError
+
+
+#: Seconds one delivery may wait on Slack. Delivery runs beside the workflow,
+#: but the run waits for what is outstanding as it ends, so an unreachable
+#: host costs at most this, once (see ``SlackSubscriber``).
+DELIVERY_TIMEOUT_SECONDS = 3.0
+
+
+class SlackDeliveryError(GinkgoError, RuntimeError):
+    """Raised when a Slack webhook request cannot be delivered."""
+
+
+class SlackUnreachableError(SlackDeliveryError):
+    """Raised when the Slack webhook's host could not be reached at all."""
+
+
+class _RefuseRedirects(HTTPRedirectHandler):
+    """Surface a redirect as an ``HTTPError``: a followed one was never delivered."""
+
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+
+@dataclass(frozen=True, kw_only=True)
+class SlackTaskFailure:
+    """Compact failed-task summary for Slack payloads."""
+
+    task_name: str
+    exit_code: int | None
+    attempt: int | None = None
+    max_attempts: int | None = None
+    log_tail: tuple[str, ...] = ()
+
+
+def post_slack_message(
+    *,
+    webhook_url: str,
+    payload: dict[str, Any],
+    timeout_seconds: float = DELIVERY_TIMEOUT_SECONDS,
+) -> None:
+    """Send one JSON payload to a Slack incoming webhook."""
+    body = json.dumps(payload).encode("utf-8")
+    request = Request(
+        webhook_url,
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with build_opener(_RefuseRedirects).open(request, timeout=timeout_seconds) as response:
+            status_code = getattr(response, "status", response.getcode())
+    except HTTPError as exc:
+        raise SlackDeliveryError(
+            f"Slack webhook rejected the request with HTTP {exc.code}."
+        ) from exc
+    except URLError as exc:
+        reason = getattr(exc, "reason", None)
+        detail = str(reason) if reason else exc.__class__.__name__
+        raise SlackUnreachableError(f"Slack webhook request failed: {detail}.") from exc
+    except Exception as exc:  # pragma: no cover - defensive wrapper
+        raise SlackDeliveryError("Slack webhook request failed.") from exc
+
+    if not 200 <= status_code < 300:
+        raise SlackDeliveryError(f"Slack webhook rejected the request with HTTP {status_code}.")
+
+
+def build_run_started_payload(
+    *,
+    workflow_label: str,
+    run_id: str,
+    ts: str,
+) -> dict[str, Any]:
+    """Build a Slack payload for run start notifications."""
+    summary_lines = [
+        f"*Workflow*: `{workflow_label}`",
+        f"*Run*: `{run_id}`",
+        f"*Started*: `{ts}`",
+    ]
+
+    return _build_payload(
+        fallback=f"Ginkgo run started: {workflow_label} ({run_id})",
+        title="Ginkgo Run Started",
+        body_lines=summary_lines,
+    )
+
+
+def build_run_succeeded_payload(
+    *,
+    workflow_label: str,
+    run_id: str,
+    ts: str,
+    task_counts: dict[str, int],
+) -> dict[str, Any]:
+    """Build a Slack payload for successful run completion."""
+    summary_lines = [
+        f"*Workflow*: `{workflow_label}`",
+        f"*Run*: `{run_id}`",
+        f"*Completed*: `{ts}`",
+        f"*Task counts*: {_format_task_counts(task_counts)}",
+    ]
+
+    return _build_payload(
+        fallback=f"Ginkgo run succeeded: {workflow_label} ({run_id})",
+        title="Ginkgo Run Succeeded",
+        body_lines=summary_lines,
+    )
+
+
+def build_run_failed_payload(
+    *,
+    workflow_label: str,
+    run_id: str,
+    ts: str,
+    task_counts: dict[str, int],
+    failed_tasks: list[SlackTaskFailure],
+    error: str | None,
+) -> dict[str, Any]:
+    """Build a Slack payload for failed run completion.
+
+    The counts are as much use here as on a success, and more so under a
+    non-fatal failure policy: a card naming three failures without saying
+    that five thousand tasks went unrun describes a different run.
+    """
+    summary_lines = [
+        f"*Workflow*: `{workflow_label}`",
+        f"*Run*: `{run_id}`",
+        f"*Failed*: `{ts}`",
+        f"*Task counts*: {_format_task_counts(task_counts)}",
+    ]
+    if error:
+        summary_lines.append(f"*Error*: `{_truncate(error, limit=180)}`")
+
+    return _build_payload(
+        fallback=f"Ginkgo run failed: {workflow_label} ({run_id})",
+        title="Ginkgo Run Failed",
+        body_lines=summary_lines,
+        failure_lines=_format_failure_lines(failed_tasks),
+    )
+
+
+def build_retry_exhausted_payload(
+    *,
+    workflow_label: str,
+    run_id: str,
+    ts: str,
+    failed_task: SlackTaskFailure,
+) -> dict[str, Any]:
+    """Build a Slack payload for retry exhaustion notifications."""
+    summary_lines = [
+        f"*Workflow*: `{workflow_label}`",
+        f"*Run*: `{run_id}`",
+        f"*Task*: `{failed_task.task_name}`",
+        f"*Failed*: `{ts}`",
+    ]
+    attempt_line = _format_attempts(failed_task)
+    if attempt_line is not None:
+        summary_lines.append(f"*Attempts*: `{attempt_line}`")
+    if failed_task.exit_code is not None:
+        summary_lines.append(f"*Exit code*: `{failed_task.exit_code}`")
+
+    return _build_payload(
+        fallback=f"Ginkgo task exhausted retries: {failed_task.task_name} ({run_id})",
+        title="Ginkgo Retries Exhausted",
+        body_lines=summary_lines,
+        failure_lines=_format_failure_lines([failed_task]),
+    )
+
+
+def _build_payload(
+    *,
+    fallback: str,
+    title: str,
+    body_lines: list[str],
+    failure_lines: list[str] | None = None,
+) -> dict[str, Any]:
+    blocks: list[dict[str, Any]] = [
+        {
+            "type": "header",
+            "text": {"type": "plain_text", "text": title},
+        },
+        {
+            "type": "section",
+            "text": {"type": "mrkdwn", "text": "\n".join(body_lines)},
+        },
+    ]
+    if failure_lines:
+        blocks.append(
+            {
+                "type": "section",
+                "text": {"type": "mrkdwn", "text": "\n".join(failure_lines)},
+            }
+        )
+
+    return {"text": fallback, "blocks": blocks}
+
+
+def _format_task_counts(task_counts: dict[str, int]) -> str:
+    ordered = [
+        (name, count)
+        for name, count in (
+            ("succeeded", task_counts.get("succeeded", 0)),
+            ("cached", task_counts.get("cached", 0)),
+            ("failed", task_counts.get("failed", 0)),
+            ("skipped", task_counts.get("skipped", 0)),
+            ("running", task_counts.get("running", 0)),
+            ("pending", task_counts.get("pending", 0)),
+        )
+        if count
+    ]
+    if not ordered:
+        return "none"
+    return ", ".join(f"{name}={count}" for name, count in ordered)
+
+
+def _format_failure_lines(failed_tasks: list[SlackTaskFailure]) -> list[str]:
+    lines: list[str] = []
+    for item in failed_tasks:
+        detail_parts = [f"*Task*: `{item.task_name}`"]
+        if item.exit_code is not None:
+            detail_parts.append(f"*Exit*: `{item.exit_code}`")
+        attempt_line = _format_attempts(item)
+        if attempt_line is not None:
+            detail_parts.append(f"*Attempts*: `{attempt_line}`")
+        lines.append(" | ".join(detail_parts))
+        if item.log_tail:
+            excerpt = "\n".join(_truncate(line, limit=140) for line in item.log_tail)
+            lines.append(f"```{_truncate(excerpt, limit=900)}```")
+    return lines
+
+
+def _format_attempts(item: SlackTaskFailure) -> str | None:
+    if item.attempt is None:
+        return None
+    if item.max_attempts is None:
+        return str(item.attempt)
+    return f"{item.attempt}/{item.max_attempts}"
+
+
+def _truncate(value: str, *, limit: int) -> str:
+    if len(value) <= limit:
+        return value
+    return value[: limit - 3] + "..."

ginkgo_slack-0.4.0/tests/test_slack_subscriber.py

@@ -0,0 +1,310 @@
+"""Slack notification tests."""
+
+from __future__ import annotations
+
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+import pytest
+
+from ginkgo.core.secret import SecretRef
+from ginkgo.plugins.api import EventSubscriberCheckContext, EventSubscriberConfigProblem
+from ginkgo.runtime.environment.secrets import build_secret_resolver
+from ginkgo_slack.subscriber import (
+    SlackNotificationConfig,
+    SlackSubscriber,
+    check_slack_config,
+    parse_notification_config,
+)
+from ginkgo_slack.webhook import (
+    SlackDeliveryError,
+    SlackUnreachableError,
+    build_run_failed_payload,
+    post_slack_message,
+)
+from tests.conftest import run_cli
+
+_WORKFLOW = """
+from ginkgo import flow, task
+
+@task(retries=1)
+def fail() -> str:
+    raise RuntimeError("boom from task")
+
+@task()
+def succeed() -> str:
+    return "ok"
+
+@flow
+def main():
+    return {body}
+"""
+
+
+class _WebhookHandler(BaseHTTPRequestHandler):
+    def do_POST(self) -> None:  # noqa: N802
+        length = int(self.headers.get("Content-Length", "0"))
+        body = self.rfile.read(length).decode("utf-8")
+        self.server.requests.append(json.loads(body))  # type: ignore[attr-defined]
+        self.send_response(200)
+        self.end_headers()
+        self.wfile.write(b"ok")
+
+    def log_message(self, format: str, *args) -> None:
+        return
+
+
+class _RedirectingHandler(_WebhookHandler):
+    def do_POST(self) -> None:  # noqa: N802
+        self.send_response(302)
+        self.send_header("Location", "/elsewhere")
+        self.end_headers()
+
+    def do_GET(self) -> None:  # noqa: N802
+        self.send_response(200)
+        self.end_headers()
+
+
+class _WebhookServer:
+    def __init__(self, handler: type[BaseHTTPRequestHandler] = _WebhookHandler) -> None:
+        self._server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
+        self._server.requests = []  # type: ignore[attr-defined]
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+
+    @property
+    def url(self) -> str:
+        host, port = self._server.server_address
+        return f"http://{host}:{port}/hook"
+
+    @property
+    def requests(self) -> list[dict[str, object]]:
+        return list(self._server.requests)  # type: ignore[attr-defined]
+
+    def __enter__(self) -> _WebhookServer:
+        self._thread.start()
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self._server.shutdown()
+        self._server.server_close()
+        self._thread.join(timeout=5)
+
+
+def _payload_text(payload: dict[str, object]) -> str:
+    blocks = payload.get("blocks", [])
+    if not isinstance(blocks, list):
+        return str(payload.get("text", ""))
+    return "\n".join(
+        block["text"]["text"]
+        for block in blocks
+        if isinstance(block, dict) and isinstance(block.get("text"), dict)
+    )
+
+
+def _slack(**settings: object) -> dict[str, object]:
+    return {"notifications": {"slack": {"enabled": True, **settings}}}
+
+
+def _check(
+    config: dict[str, object], *, environ: dict[str, str]
+) -> list[EventSubscriberConfigProblem]:
+    resolver = build_secret_resolver(project_root=Path.cwd(), config=config, environ=environ)
+    return check_slack_config(EventSubscriberCheckContext(config=config, secret_resolver=resolver))
+
+
+_WEBHOOK = {"env": "GINKGO_SLACK_WEBHOOK"}
+
+
+class TestNotificationConfig:
+    def test_parse_notification_config_supports_aliases_and_secret_refs(self) -> None:
+        config, problems = parse_notification_config(
+            config=_slack(
+                webhook=_WEBHOOK,
+                events=["run_started", "run_completed", "retry_exhausted"],
+                log_tail_lines=25,
+                max_failed_tasks=10,
+            )
+        )
+
+        assert problems == []
+        assert config.webhook == SecretRef(name="GINKGO_SLACK_WEBHOOK", backend="env")
+        # "run_completed" is an alias for "run_succeeded"; the parser normalises it.
+        assert config.events == frozenset({"run_started", "run_succeeded", "retry_exhausted"})
+        assert (config.log_tail_lines, config.max_failed_tasks) == (25, 10)
+
+    def test_every_invalid_setting_is_named(self) -> None:
+        _, problems = parse_notification_config(
+            config=_slack(
+                webhook=_WEBHOOK, events=["run_finished"], channel="#alerts", log_tail_lines=-3
+            )
+        )
+
+        assert len(problems) == 3
+        assert "'channel'" in problems[0]
+        assert "'run_finished'" in problems[1]
+        assert "log_tail_lines" in problems[2]
+
+    def test_a_misspelt_event_beside_valid_ones_is_ignored_not_fatal(self) -> None:
+        """RP4-4: one typo must not turn off the alerts that were spelt right."""
+        settings = _slack(webhook=_WEBHOOK, events=["run_faild", "run_failed"])
+        config, problems = parse_notification_config(config=settings)
+
+        assert problems == []
+        assert config.events == frozenset({"run_failed"})
+        [ignored] = config.ignored_events
+        assert "'run_faild', so it is ignored" in ignored
+        # doctor still names it, as a warning: the run still sends.
+        environ = {"GINKGO_SLACK_WEBHOOK": "http://127.0.0.1:1/"}
+        assert _check(settings, environ=environ) == [
+            EventSubscriberConfigProblem(message=ignored, blocking=False)
+        ]
+
+    def test_a_literal_webhook_url_is_explained(self) -> None:
+        _, problems = parse_notification_config(
+            config=_slack(webhook="https://hooks.slack.com/services/x")
+        )
+
+        assert len(problems) == 1
+        assert 'webhook = { env = "GINKGO_SLACK_WEBHOOK" }' in problems[0]
+
+    def test_the_check_names_an_unset_environment_variable(self) -> None:
+        config = _slack(webhook=_WEBHOOK)
+
+        [problem] = _check(config, environ={"GINKGO_SLACK_WEBHOOK": ""})
+        assert "GINKGO_SLACK_WEBHOOK, which is unset or empty" in problem.message
+        assert _check(config, environ={"GINKGO_SLACK_WEBHOOK": "http://127.0.0.1:1/"}) == []
+
+
+def test_once_slack_is_unreachable_later_notifications_are_not_attempted(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    attempts: list[dict[str, object]] = []
+
+    def unreachable(*, webhook_url: str, payload: dict[str, object]) -> None:
+        attempts.append(payload)
+        raise SlackUnreachableError("Slack webhook request failed: timed out.")
+
+    monkeypatch.setattr("ginkgo_slack.subscriber.post_slack_message", unreachable)
+    warnings: list[str] = []
+    subscriber = SlackSubscriber(
+        config=SlackNotificationConfig(enabled=True),
+        webhook_url="http://127.0.0.1:1/hook",
+        store=None,  # type: ignore[arg-type]
+        run_id="run-1",
+        run_dir=tmp_path,
+        workflow_path=tmp_path / "workflow.py",
+        logger=warnings.append,
+    )
+
+    subscriber._submit(event_name="run_started", payload={"text": "a"})
+    subscriber._submit(event_name="run_failed", payload={"text": "b"})
+    subscriber.close()
+
+    assert attempts == [{"text": "a"}]
+    assert len(warnings) == 2
+    assert "run_failed" in warnings[1] and "not sent" in warnings[1]
+
+
+def test_a_redirected_webhook_is_not_delivered() -> None:
+    with _WebhookServer(_RedirectingHandler) as server:
+        with pytest.raises(SlackDeliveryError, match="HTTP 302"):
+            post_slack_message(webhook_url=server.url, payload={"text": "hi"})
+
+
+def test_the_failed_run_card_counts_the_tasks_a_failure_left_unrun() -> None:
+    """Three failures beside five thousand skips is a different run."""
+    payload = build_run_failed_payload(
+        workflow_label="flow.py",
+        run_id="run_1",
+        ts="2026-09-02T09:00:00+00:00",
+        task_counts={"succeeded": 4997, "failed": 3, "skipped": 4997},
+        failed_tasks=[],
+        error="3 tasks failed; the run continued under its failure policy.",
+    )
+
+    text = _payload_text(payload)
+    assert "failed=3" in text
+    assert "skipped=4997" in text
+
+
+class TestSlackNotifications:
+    @pytest.fixture(autouse=True)
+    def _run_in_tmp_path(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        # Each test writes a workflow and config into the working directory.
+        monkeypatch.chdir(tmp_path)
+
+    def _project(self, *, events: list[str], body: str = "succeed()") -> None:
+        Path("ginkgo.toml").write_text(
+            "[notifications.slack]\nenabled = true\n"
+            'webhook = { env = "GINKGO_SLACK_WEBHOOK" }\n'
+            f"events = {json.dumps(events)}\nlog_tail_lines = 5\n",
+            encoding="utf-8",
+        )
+        Path("workflow.py").write_text(_WORKFLOW.format(body=body), encoding="utf-8")
+
+    @pytest.mark.parametrize(
+        ("events", "body", "code", "expected"),
+        [
+            (
+                ["run_started", "run_completed"],
+                "succeed()",
+                0,
+                [("Ginkgo Run Started", "workflow.py"), ("Ginkgo Run Succeeded", "succeeded=1")],
+            ),
+            (
+                ["retry_exhausted", "run_failed"],
+                "fail()",
+                1,
+                [("Ginkgo Retries Exhausted", "boom from task"), ("Ginkgo Run Failed", "fail")],
+            ),
+        ],
+    )
+    def test_cli_run_sends_the_configured_notifications(
+        self, monkeypatch, events, body, code, expected
+    ) -> None:
+        with _WebhookServer() as server:
+            monkeypatch.setenv("GINKGO_SLACK_WEBHOOK", server.url)
+            self._project(events=events, body=body)
+
+            result = run_cli("run", "workflow.py")
+            assert result.returncode == code, result.stderr
+            texts = [_payload_text(request) for request in server.requests]
+
+        assert len(texts) == len(expected)
+        for text, fragments in zip(texts, expected):
+            assert all(fragment in text for fragment in fragments)
+
+    def test_doctor_blocks_an_invalid_slack_table(self, monkeypatch) -> None:
+        monkeypatch.delenv("GINKGO_SLACK_WEBHOOK", raising=False)
+        self._project(events=["run_finished"])
+
+        result = run_cli("doctor", "workflow.py")
+
+        assert result.returncode == 1
+        assert "notification_config" in result.stderr
+        assert "'run_finished'" in result.stderr
+
+    def test_doctor_warns_but_passes_on_an_unknown_event_beside_valid_ones(
+        self, monkeypatch
+    ) -> None:
+        monkeypatch.setenv("GINKGO_SLACK_WEBHOOK", "http://127.0.0.1:1/hook")
+        self._project(events=["run_faild", "run_failed"])
+
+        result = run_cli("doctor", "workflow.py")
+
+        assert result.returncode == 0, result.stdout + result.stderr
+        assert "'run_faild'" in result.stdout + result.stderr
+
+    def test_cli_run_warns_when_slack_webhook_is_unreachable(self, monkeypatch) -> None:
+        monkeypatch.setenv("GINKGO_SLACK_WEBHOOK", "http://127.0.0.1:1/hook")
+        self._project(events=["run_completed"])
+
+        result = run_cli("run", "workflow.py")
+        assert result.returncode == 0, result.stderr
+        assert "Slack notification for run_succeeded failed:" in result.stderr
+
+        # The failure is kept with the run, not only printed while it ran.
+        shown = run_cli("runs", "show")
+        assert "Notice: Slack notification for run_succeeded failed:" in shown.stdout