| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374 |
- """hermes webhook — manage dynamic webhook subscriptions from the CLI."""
- import hashlib
- import hmac
- import json
- import re
- import secrets
- import threading
- import time
- import urllib.request
- from contextlib import contextmanager
- from pathlib import Path
- from typing import Any, Callable, Dict
- from hermes_constants import display_hermes_home
- from utils import atomic_json_write
- from hermes_cli.config import cfg_get
- _SUBSCRIPTIONS_FILENAME = "webhook_subscriptions.json"
- _SUBSCRIPTIONS_FILE_MODE = 0o600
- _SUBSCRIPTIONS_LOCK_FILENAME = ".webhook_subscriptions.lock"
- _SUBSCRIPTIONS_THREAD_LOCK = threading.Lock()
- _MISSING_SUBSCRIPTION = object()
- class SubscriptionMutationConflict(RuntimeError):
- """The route changed after a caller took the snapshot it intended to replace."""
- def _subscriptions_path() -> Path:
- from hermes_constants import get_hermes_home
- return get_hermes_home() / _SUBSCRIPTIONS_FILENAME
- def _subscriptions_lock_path() -> Path:
- return _subscriptions_path().with_name(_SUBSCRIPTIONS_LOCK_FILENAME)
- @contextmanager
- def _subscriptions_lock():
- """Serialize subscription snapshots and mutations across threads and processes."""
- from hermes_cli.active_sessions import _FileLock
- with _SUBSCRIPTIONS_THREAD_LOCK:
- with _FileLock(_subscriptions_lock_path()):
- yield
- def _load_subscriptions_unlocked() -> dict[str, dict]:
- """Read one complete store snapshot; unreadable or malformed files read as empty."""
- try:
- raw = _subscriptions_path().read_bytes()
- except OSError:
- return {}
- try:
- data = json.loads(raw.decode("utf-8-sig"))
- except ValueError:
- return {}
- return data if isinstance(data, dict) else {}
- def _load_subscriptions() -> dict[str, dict]:
- """Lock-free read: writers publish by atomic rename, so a reader always sees one whole
- snapshot, and read-only homes (no lock file can be created) keep working."""
- return _load_subscriptions_unlocked()
- def _save_subscriptions_unlocked(subs: dict[str, dict]) -> None:
- # The file holds per-route HMAC secrets: atomic_json_write fchmods the temp file 0o600 BEFORE the
- # rename (no umask window) and re-asserts the mode on the destination afterwards.
- atomic_json_write(_subscriptions_path(), subs, mode=_SUBSCRIPTIONS_FILE_MODE)
- def _mutate_subscriptions(mutate: Callable[[dict[str, dict]], Any]) -> Any:
- """Lock, re-read, mutate and atomically publish one complete store snapshot."""
- with _subscriptions_lock():
- subscriptions = _load_subscriptions_unlocked()
- result = mutate(subscriptions)
- _save_subscriptions_unlocked(subscriptions)
- return result
- def _replace_subscription(name: str, route: dict, expected: object) -> dict:
- """CAS one route so a stale update cannot recreate a removed or disabled record.
- A general update is not an enable operation: an explicit ``enabled: False`` on the
- replaced record survives (only the dashboard's dedicated enabled endpoint lifts it).
- Returns the route as published.
- """
- def replace(subscriptions: dict[str, dict]) -> dict:
- current = subscriptions.get(name, _MISSING_SUBSCRIPTION)
- expected_missing = expected is _MISSING_SUBSCRIPTION
- if (current is _MISSING_SUBSCRIPTION) != expected_missing or (
- not expected_missing and current != expected
- ):
- raise SubscriptionMutationConflict(
- f"Webhook subscription '{name}' changed concurrently; retry the operation."
- )
- published = route
- if isinstance(current, dict) and current.get("enabled") is False:
- published = {**route, "enabled": False}
- subscriptions[name] = published
- return published
- return _mutate_subscriptions(replace)
- def _get_webhook_config() -> dict:
- """Load webhook platform config. Returns {} if not configured."""
- try:
- from hermes_cli.config import load_config
- cfg = load_config()
- return cfg_get(cfg, "platforms", "webhook", default={})
- except Exception:
- return {}
- def _is_webhook_enabled() -> bool:
- return bool(_get_webhook_config().get("enabled"))
- def _get_webhook_base_url() -> str:
- wh = _get_webhook_config().get("extra", {})
- host = wh.get("host")
- display_host = "localhost" if not host or host in {"0.0.0.0", "::"} else host
- if ":" in display_host and not display_host.startswith("["):
- display_host = f"[{display_host}]"
- return f"http://{display_host}:{wh.get('port', 8644)}"
- def _route_url(name: str, route: dict) -> str:
- profile = route.get("profile", "default")
- prefix = f"/p/{profile}" if profile != "default" else ""
- return f"{_get_webhook_base_url()}{prefix}/webhooks/{name}"
- def _setup_hint() -> str:
- _dhh = display_hermes_home()
- return f"""
- Webhook platform is not enabled. To set it up:
- 1. Run the gateway setup wizard:
- hermes gateway setup
- 2. Or manually add to {_dhh}/config.yaml:
- platforms:
- webhook:
- enabled: true
- extra:
- port: 8644
- secret: "your-global-hmac-secret"
- 3. Or set environment variables in {_dhh}/.env:
- WEBHOOK_ENABLED=true
- WEBHOOK_PORT=8644
- WEBHOOK_SECRET=your-global-secret
- Then start the gateway: hermes gateway run
- """
- def webhook_command(args):
- """Entry point for 'hermes webhook' subcommand."""
- sub = getattr(args, "webhook_action", None)
- if not sub:
- print("Usage: hermes webhook {subscribe|list|remove|test}")
- print("Run 'hermes webhook --help' for details.")
- return
- if not _is_webhook_enabled():
- print(_setup_hint())
- return 1
- handler = _ACTIONS.get(sub)
- if handler is not None:
- # A refusal returns 1 so scripts can tell no route was written (#139332).
- return handler(args)
- def _cmd_subscribe(args):
- name = args.name.strip().lower().replace(" ", "-")
- if not re.match(r'^[a-z0-9][a-z0-9_-]*$', name):
- print(f"Error: Invalid name '{name}'. Use lowercase alphanumeric with hyphens/underscores.")
- return 1
- subs = _load_subscriptions()
- expected = subs.get(name, _MISSING_SUBSCRIPTION)
- is_update = expected is not _MISSING_SUBSCRIPTION
- existing = expected if isinstance(expected, dict) else {}
- profile_arg = getattr(args, "route_profile", None)
- if profile_arg is None:
- profile = existing.get("profile", "default")
- else:
- from hermes_cli.profiles import normalize_profile_name, profile_exists, validate_profile_name
- try:
- profile = normalize_profile_name(profile_arg)
- validate_profile_name(profile)
- except ValueError as exc:
- print(f"Error: {exc}")
- return 1
- if not profile_exists(profile):
- print(f"Error: Profile '{profile}' does not exist.")
- return 1
- existing_profile = existing.get("profile", "default")
- profile_changed = is_update and profile != existing_profile
- if profile_changed and args.secret and args.secret == existing.get("secret"):
- print(
- "Error: Rebinding a webhook route requires a new HMAC secret. "
- "Omit --secret to generate one automatically, or provide a different secret."
- )
- return 1
- secret = args.secret or (None if profile_changed else existing.get("secret")) or secrets.token_urlsafe(32)
- events = [e.strip() for e in args.events.split(",")] if args.events else []
- route = {
- "description": args.description or f"Agent-created subscription: {name}",
- "events": events,
- "secret": secret,
- "prompt": args.prompt or "",
- "skills": [s.strip() for s in args.skills.split(",")] if args.skills else [],
- "deliver": args.deliver or "log",
- "profile": profile,
- "created_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())}
- if getattr(args, "deliver_only", False):
- if getattr(args, "cron_job", ""):
- print(
- "Error: --deliver-only and --cron-job are mutually exclusive. "
- "--deliver-only pushes the rendered template as a message; "
- "--cron-job fires an existing cron job (which handles its own "
- "delivery)."
- )
- return 1
- if route["deliver"] == "log":
- print(
- "Error: --deliver-only requires --deliver to be a real target "
- "(telegram, discord, slack, github_comment, etc.) — not 'log'.")
- return 1
- route["deliver_only"] = True
- if getattr(args, "mirror_to_session", False):
- route["mirror_to_session"] = True
- cron_job = (getattr(args, "cron_job", "") or "").strip()
- if cron_job:
- # Validate the reference up-front so a typo surfaces here, not on the first inbound event.
- from cron.jobs import AmbiguousJobReference
- try:
- job = _resolve_route_cron_job(profile, cron_job)
- except AmbiguousJobReference as e:
- print(f"Error: {e}")
- return 1
- if job is None:
- print(f"Error: no cron job matches '{cron_job}'. List jobs with: hermes cron list")
- return 1
- route["cron_job"] = job["id"]
- script = (getattr(args, "script", "") or "").strip()
- if script:
- route["script"] = script
- if args.deliver_chat_id:
- route["deliver_extra"] = {"chat_id": args.deliver_chat_id}
- try:
- route = _replace_subscription(name, route, expected)
- except SubscriptionMutationConflict as exc:
- print(f"Error: {exc}")
- return 1
- print(f"\n {'Updated' if is_update else 'Created'} webhook subscription: {name}")
- print(f" URL: {_route_url(name, route)}")
- print(f" Profile: {profile}")
- print(f" Secret: {secret}")
- print(f" Events: {', '.join(events) or '(all)'}")
- print(f" Deliver: {route['deliver']}")
- if route.get("deliver_only"):
- print(" Mode: direct delivery (no agent, zero LLM cost)")
- if route.get("mirror_to_session"):
- print(" Replies: each delivery is mirrored into the target chat's session")
- if route.get("cron_job"):
- print(f" Mode: cron-job trigger — fires job '{route['cron_job']}' on each event")
- if route.get("prompt"):
- prompt_preview = route["prompt"][:80] + ("..." if len(route["prompt"]) > 80 else "")
- print(f" {'Message' if route.get('deliver_only') else 'Prompt'}: {prompt_preview}")
- if route.get("script"):
- print(f" Script: {route['script']}")
- print("\n Configure your service to POST to the URL above.")
- print(" Use the secret for HMAC-SHA256 signature validation.")
- print(" The gateway must be running to receive events (hermes gateway run).\n")
- def _resolve_route_cron_job(profile: str, reference: str):
- """Match runtime routing without changing the caller's subscription/config home."""
- from cron.jobs import resolve_job_ref, use_cron_store
- from hermes_cli.profiles import get_profile_dir
- # Bare/default routes execute in the ambient home, including standalone installs.
- if profile == "default":
- return resolve_job_ref(reference)
- with use_cron_store(get_profile_dir(profile)):
- return resolve_job_ref(reference)
- def _cmd_list(args):
- subs = _load_subscriptions()
- if not subs:
- print(" No dynamic webhook subscriptions.")
- print(" Create one with: hermes webhook subscribe <name>")
- return
- print(f"\n {len(subs)} webhook subscription(s):\n")
- for name, route in subs.items():
- events = ", ".join(route.get("events", [])) or "(all)"
- deliver = route.get("deliver", "log")
- if route.get("deliver_only"):
- deliver = f"{deliver} (direct — no agent)"
- if route.get("cron_job"):
- deliver = f"cron job '{route['cron_job']}'"
- desc = route.get("description", "")
- print(f" ◆ {name}")
- if desc:
- print(f" {desc}")
- profile = route.get("profile", "default")
- print(f" URL: {_route_url(name, route)}")
- print(f" Profile: {profile}")
- print(f" Events: {events}")
- print(f" Deliver: {deliver}")
- if route.get("script"):
- print(f" Script: {route['script']}")
- print()
- def _cmd_remove(args):
- name = args.name.strip().lower()
- def remove(subscriptions: dict[str, dict]) -> None:
- if name not in subscriptions:
- raise KeyError(name)
- del subscriptions[name]
- try:
- _mutate_subscriptions(remove)
- except KeyError:
- print(f" No subscription named '{name}'.")
- print(" Note: Static routes from config.yaml cannot be removed here.")
- return
- print(f" Removed webhook subscription: {name}")
- def _cmd_test(args):
- """Send a test POST to a webhook route."""
- name = args.name.strip().lower()
- subs = _load_subscriptions()
- if name not in subs:
- print(f" No subscription named '{name}'.")
- return
- secret = subs[name].get("secret", "")
- url = _route_url(name, subs[name])
- payload = args.payload or '{"test": true, "event_type": "test", "message": "Hello from hermes webhook test"}'
- sig = "sha256=" + hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
- print(f" Sending test POST to {url}")
- try:
- req = urllib.request.Request(
- url,
- data=payload.encode(),
- headers={"Content-Type": "application/json", "X-Hub-Signature-256": sig, "X-GitHub-Event": "test"},
- method="POST")
- with urllib.request.urlopen(req, timeout=10) as resp:
- body = resp.read().decode()
- print(f" Response ({resp.status}): {body}")
- except Exception as e:
- print(f" Error: {e}")
- print(" Is the gateway running? (hermes gateway run)")
- _ACTIONS = {
- "subscribe": _cmd_subscribe, "add": _cmd_subscribe,
- "list": _cmd_list, "ls": _cmd_list,
- "remove": _cmd_remove, "rm": _cmd_remove,
- "test": _cmd_test}
|