admin/mcp-nextcloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(webhooks): bound queue waits, route URLs through dynaconf

Browse Source 
Addresses round-3 review feedback on PR #747:

- webhook_receiver: wrap send_stream.send() in anyio.fail_after(1.0)
  and return 503 with reason="queue full" if the queue is saturated.
  Avoids pinning the handler until NC's outbound timeout fires; the
  503 retry contract is the same as the existing "sync not running"
  branch.
- webhook_receiver: revise the compare_digest comment to match what
  the function actually guarantees — it avoids the per-character
  short-circuit of `==` but is not fully constant-time across length
  differences.
- _get_webhook_uri: read WEBHOOK_INTERNAL_URL and
  NEXTCLOUD_MCP_SERVER_URL via dynaconf so operators using
  settings.toml (rather than env vars) aren't silently routed into
  the docker/localhost fallback. Adds webhook_internal_url to
  Settings/_DEFAULTS/_field_map; nextcloud_mcp_server_url already
  existed. Docker-detection markers stay on os.getenv since they're
  container-runtime signals, not user-facing config.
- webhook_routes: sweep remaining f-string logger calls to lazy %s
  formatting per CLAUDE.md.
- client/webhooks: modernise full file's type hints to
  dict / list / | None per CLAUDE.md.

Tests:
- New test_returns_503_when_queue_is_full exercises the timeout
  branch with a saturated buffer and a shortened deadline.
- test_webhook_uri tests now patch get_settings (matching the
  auth-pair tests in the same file) instead of monkeypatching env
  vars directly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
2026-04-30 04:17:00 +02:00
co-authored by Claude Opus 4.7
parent 42675e7c20
commit c1368b9a7f
6 changed files with 122 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nextcloud_mcp_server/auth/webhook_routes.py
+25 -19
View File
@@ -72,7 +72,7 @@ async def _get_installed_apps(http_client: httpx.AsyncClient) -> list[str]:
app_keys = set(capabilities.keys()) - core_keys
return sorted(app_keys)
except Exception as e:
logger.warning(f"Failed to get installed apps from capabilities: {e}")
logger.warning("Failed to get installed apps from capabilities: %s", e)
return []
@@ -81,10 +81,10 @@ def _get_webhook_uri() -> str:
Priority (highest first):
1. ``WEBHOOK_INTERNAL_URL`` — explicit override, e.g. for split
internal/external URLs.
2. ``NEXTCLOUD_MCP_SERVER_URL`` — the configured public URL. This is
set on cloud deployments (ECS, k8s) and is the URL Nextcloud must
POST to.
internal/external URLs (read via dynaconf, so env vars and
settings.toml both work).
2. ``NEXTCLOUD_MCP_SERVER_URL`` — the configured public URL set on
cloud deployments (ECS, k8s); the URL NC must POST to.
3. ``/.dockerenv`` (or podman / ``DOCKER_CONTAINER=true``) → internal
docker-compose service name. Only relevant when no public URL is
configured — i.e. local dev where MCP and NC share a Docker
@@ -96,14 +96,16 @@ def _get_webhook_uri() -> str:
docker-compose hostname (e.g. ``http://mcp:8000``) that NC cannot
resolve, dropping every webhook delivery.
"""
webhook_url = os.getenv("WEBHOOK_INTERNAL_URL")
if webhook_url:
return f"{webhook_url}/webhooks/nextcloud"
settings = get_settings()
if settings.webhook_internal_url:
return f"{settings.webhook_internal_url}/webhooks/nextcloud"
server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL")
if server_url:
return f"{server_url}/webhooks/nextcloud"
if settings.nextcloud_mcp_server_url:
return f"{settings.nextcloud_mcp_server_url}/webhooks/nextcloud"
# Docker-environment markers stay on os.getenv: they're container-runtime
# signals (filesystem markers, optional service-name override) rather
# than user-facing config that would belong in settings.toml.
is_docker = (
os.path.exists("/.dockerenv")
or os.path.exists("/run/.containerenv")
@@ -284,7 +286,7 @@ async def _get_enabled_presets(
return enabled_presets
except Exception as e:
logger.error(f"Failed to list webhooks: {e}")
logger.error("Failed to list webhooks: %s", e)
return {}
@@ -329,7 +331,7 @@ async def webhook_management_pane(request: Request) -> HTMLResponse:
# Get installed apps to filter presets
installed_apps = await _get_installed_apps(http_client)
logger.debug(f"Installed apps: {installed_apps}")
logger.debug("Installed apps: %s", installed_apps)
# Get currently enabled presets (from database or API)
enabled_presets = await _get_enabled_presets(webhooks_client, storage)
@@ -404,7 +406,7 @@ async def webhook_management_pane(request: Request) -> HTMLResponse:
return HTMLResponse(content=html_content)
except Exception as e:
logger.error(f"Error loading webhook management pane: {e}", exc_info=True)
logger.error("Error loading webhook management pane: %s", e, exc_info=True)
return HTMLResponse(
content=f"""
<div class="warning">
@@ -462,7 +464,9 @@ async def enable_webhook_preset(request: Request) -> HTMLResponse:
for webhook_id in registered_ids:
await storage.store_webhook(webhook_id, preset_id)
logger.info(
f"Persisted {len(registered_ids)} webhook(s) for preset '{preset_id}' to database"
"Persisted %d webhook(s) for preset '%s' to database",
len(registered_ids),
preset_id,
)
# Return updated card
@@ -494,7 +498,7 @@ async def enable_webhook_preset(request: Request) -> HTMLResponse:
)
except Exception as e:
logger.error(f"Failed to enable preset {preset_id}: {e}", exc_info=True)
logger.error("Failed to enable preset %s: %s", preset_id, e, exc_info=True)
return HTMLResponse(
content=f'<div class="warning">Failed to enable preset: {str(e)}</div>',
status_code=500,
@@ -548,13 +552,15 @@ async def disable_webhook_preset(request: Request) -> HTMLResponse:
for webhook_id in webhook_ids:
await webhooks_client.delete_webhook(webhook_id)
logger.info(f"Deleted webhook {webhook_id} from preset {preset_id}")
logger.info("Deleted webhook %s from preset %s", webhook_id, preset_id)
# Remove from database
if storage:
deleted_count = await storage.clear_preset_webhooks(preset_id)
logger.info(
f"Removed {deleted_count} webhook(s) for preset '{preset_id}' from database"
"Removed %d webhook(s) for preset '%s' from database",
deleted_count,
preset_id,
)
# Return updated card
@@ -584,7 +590,7 @@ async def disable_webhook_preset(request: Request) -> HTMLResponse:
)
except Exception as e:
logger.error(f"Failed to disable preset {preset_id}: {e}", exc_info=True)
logger.error("Failed to disable preset %s: %s", preset_id, e, exc_info=True)
return HTMLResponse(
content=f'<div class="warning">Failed to disable preset: {str(e)}</div>',
status_code=500,
nextcloud_mcp_server/client/webhooks.py
+9 -9
View File
@@ -1,6 +1,6 @@
"""Client for Nextcloud Webhook Listeners API operations."""
from typing import Any, Dict, List, Optional
from typing import Any
from nextcloud_mcp_server.client.base import BaseNextcloudClient
@@ -11,15 +11,15 @@ class WebhooksClient(BaseNextcloudClient):
app_name = "webhooks"
def _get_webhook_headers(
self, additional_headers: Optional[Dict[str, str]] = None
) -> Dict[str, str]:
self, additional_headers: dict[str, str] | None = None
) -> dict[str, str]:
"""Get standard headers required for Webhook Listeners API calls."""
headers = {"OCS-APIRequest": "true", "Accept": "application/json"}
if additional_headers:
headers.update(additional_headers)
return headers
async def list_webhooks(self) -> List[Dict[str, Any]]:
async def list_webhooks(self) -> list[dict[str, Any]]:
"""List all registered webhooks for the current user.
Returns:
@@ -40,10 +40,10 @@ class WebhooksClient(BaseNextcloudClient):
uri: str,
http_method: str = "POST",
auth_method: str = "none",
headers: Optional[Dict[str, str]] = None,
headers: dict[str, str] | None = None,
auth_data: dict[str, str] | None = None,
event_filter: Optional[Dict[str, Any]] = None,
) -> Dict[str, Any]:
event_filter: dict[str, Any] | None = None,
) -> dict[str, Any]:
"""Register a new webhook for the specified event.
Args:
@@ -63,7 +63,7 @@ class WebhooksClient(BaseNextcloudClient):
Returns:
Webhook registration details including webhook ID
"""
data: Dict[str, Any] = {
data: dict[str, Any] = {
"httpMethod": http_method,
"uri": uri,
"event": event,
@@ -101,7 +101,7 @@ class WebhooksClient(BaseNextcloudClient):
headers=headers,
)
async def get_webhook(self, webhook_id: int) -> Dict[str, Any]:
async def get_webhook(self, webhook_id: int) -> dict[str, Any]:
"""Get details of a specific webhook registration.
Args:
nextcloud_mcp_server/config.py
+8
View File
@@ -57,6 +57,9 @@ _DEFAULTS: dict[str, Any] = {
# tell NC to add `Authorization: Bearer <secret>` to webhook deliveries
# and the receiver rejects unauthenticated requests.
"webhook_secret": None,
# Internal URL override for webhook registration; wins over
# NEXTCLOUD_MCP_SERVER_URL when set (e.g. split internal/external URLs).
"webhook_internal_url": None,
# Vector sync
"vector_sync_scan_interval": 300,
"vector_sync_processor_workers": 3,
@@ -440,6 +443,10 @@ class Settings:
# delivery. When unset, registration uses authMethod="none" and the
# receiver accepts unauthenticated POSTs (backward-compatible).
webhook_secret: str | None = None
# Internal URL override for webhook registration. Highest-priority
# source for the URL we register with NC (above
# nextcloud_mcp_server_url and the docker-detection fallback).
webhook_internal_url: str | None = None
# Vector sync settings (ADR-007)
vector_sync_enabled: bool = False
@@ -780,6 +787,7 @@ def get_settings() -> Settings:
"token_storage_db": "TOKEN_STORAGE_DB",
# Webhook auth (ADR-010)
"webhook_secret": "WEBHOOK_SECRET",
"webhook_internal_url": "WEBHOOK_INTERNAL_URL",
# Vector sync settings (ADR-007)
"vector_sync_scan_interval": "VECTOR_SYNC_SCAN_INTERVAL",
"vector_sync_processor_workers": "VECTOR_SYNC_PROCESSOR_WORKERS",
nextcloud_mcp_server/vector/webhook_receiver.py
+20 -4
View File
@@ -8,6 +8,7 @@ in :mod:`nextcloud_mcp_server.app`.
import hmac
import logging
import anyio
from starlette.requests import Request
from starlette.responses import JSONResponse
@@ -53,9 +54,10 @@ async def handle_nextcloud_webhook(request: Request) -> JSONResponse:
if secret:
provided = request.headers.get("authorization", "")
expected = f"Bearer {secret}"
# Always run compare_digest so the constant-time path is taken even
# when the header is missing — `compare_digest("", expected)` returns
# False without leaking length information.
# Use compare_digest to avoid the character-by-character short-circuit
# of `==`. compare_digest still returns False for differing lengths
# but isn't fully constant-time across them; that's fine here — a
# secret length leak is not a sensitive signal.
if not hmac.compare_digest(provided, expected):
logger.warning("Webhook rejected: missing or invalid Authorization header")
return JSONResponse(
@@ -94,7 +96,21 @@ async def handle_nextcloud_webhook(request: Request) -> JSONResponse:
)
try:
await send_stream.send(task)
with anyio.fail_after(1.0):
await send_stream.send(task)
except TimeoutError:
# Queue is saturated (default 10 000 tasks). Returning 503 lets NC
# retry rather than pinning this handler until its outbound timeout
# fires; the queue-pressure signal also surfaces in metrics.
logger.warning(
"Webhook task drop: queue full for %s_%s",
task.doc_type,
task.doc_id,
)
return JSONResponse(
{"status": "unavailable", "reason": "queue full"},
status_code=503,
)
except Exception as e:
logger.error(
"Failed to queue webhook task for %s_%s: %s",