Deploymentcenter BotandClaude Opus 5
60e34b29f6
Fehler-Schnittstelle - Neuer schlanker Eingang POST /api/errors/v1/report für den globalen Exception-Handler einer Anwendung. Titel und Dringlichkeit leitet der Server ab; gespeichert wird in derselben Tabelle wie der Bugtracker. Ein zweiter Speicher wäre nur ein zweiter Ort, an dem man suchen müsste. - error_level (fatal/error/warning) trennt die technische Art des Ereignisses von der geschäftlichen Dringlichkeit. Ein Duplicate-Entry ist technisch ein error, geschäftlich belanglos — beides zu vermischen war der Grund, warum solche Meldungen als Bug im Dashboard landeten. Ignore-Regeln gegen bekanntes Rauschen - bugtracker_ignore_rules mit contains/regex/exception_class, Pflichtfeld für die Begründung und optionaler Alarmschwelle. - Ein Treffer bedeutet nicht "wegwerfen": Der Fehler wird weiterhin erfasst und hochgezählt, bleibt aber aus der Übersicht heraus und löst keine Benachrichtigung aus. Der Zähler ist der eigentliche Zweck — dass ein bekannter Fehler auftritt, ist normal; dass er plötzlich hundertmal so oft auftritt, ist ein Signal. Dafür das rollende Stundenfenster und error.rate_exceeded. - Neue Regeln lassen sich rückwirkend auf bestehende Einträge anwenden. Gruppierung überarbeitet - Der Schlüssel nahm bisher 300 Zeichen Stacktrace auf. Derselbe Fehler zersplitterte dadurch, sobald ein Aufrufer den Stack einmal mitschickte und einmal nicht. Jetzt zählt der Ursprungsort: bevorzugt die Dateiangabe, sonst der erste Rahmen des Stacktrace. - Die Normalisierung ersetzte nur Zahlen ab vier Stellen, wodurch 'AA-1' und 'BB-2' getrennt blieben. Werte in Anführungszeichen, die Ziffern enthalten, gelten jetzt als veränderlich — der Schlüsselname bleibt erhalten, sodass verschiedene Unique-Keys unterscheidbar sind. Mit 9 Testfällen belegt. Metrik-Verlauf - watchdog_metrics speichert numerische Heartbeat-Werte mit Zeitstempel. Zuvor wurde metrics_json bei jedem Heartbeat überschrieben; damit ließ sich "die Platte läuft seit drei Tagen voll" nicht erkennen, nur "sie ist voll". - GET /api/watchdog/v1/metrics liefert den verdichteten Verlauf und die Abweichung vom eigenen Sieben-Tage-Durchschnitt. Dieser relative Ansatz braucht keine projektspezifischen Schwellwerte. - Aufbewahrung 14 Tage, Bereinigung stündlich durch den Evaluator. Health-Checks per Push statt Abruf - Der Heartbeat nimmt ein checks-Objekt entgegen, das die Anwendung selbst ermittelt. Das Deploymentcenter interpretiert die Namen nicht, es liest nur ok und message — was "gesund" bedeutet, entscheidet jede Anwendung selbst. Schlägt eine Prüfung fehl, wird ein als ok gemeldeter Heartbeat auf warning herabgestuft. - Bewusst ausgehend: auf den Zielmaschinen müssen keine Ports geöffnet werden. Abhängigkeitsbewusste Alarmierung - Fällt ein Monitor aus, dessen Parent selbst unten ist, wird der Alarm unterdrückt. Der Zustand bleibt sichtbar. Vorher erzeugte ein ausgefallener Hypervisor mit zwölf VMs dreizehn Meldungen für ein Problem. - Mehrere Ebenen und fehlerhafte Hierarchien (Zyklen, gelöschte Parents) sind abgesichert; mit 10 Testfällen belegt. WebUI - Neue Ansicht "Fehler-Stream" mit Filtern nach Projekt, Fehlerklasse, Umgebung, Zeitraum und Sichtbarkeit sowie Volltextsuche und Pagination. Stummgeschaltete Einträge sind standardmäßig ausgeblendet. - Verwaltung der Ignore-Regeln inklusive Trefferzähler. - Die Detailansicht zeigt Fehlerklasse, Stummschaltungsgrund und die Häufung im laufenden Stundenfenster. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
365 lines
20 KiB
PHP
365 lines
20 KiB
PHP
<?php
|
|
|
|
/**
|
|
* GET /api/openapi.json
|
|
*
|
|
* Maschinenlesbare Beschreibung der Schnittstelle. Ersetzt den frueher fest
|
|
* im WebUI hinterlegten Textblock: ein Agent kann sich hier selbst orientieren,
|
|
* ohne dass eine Prompt-Vorlage gepflegt werden muss.
|
|
*/
|
|
|
|
declare(strict_types=1);
|
|
|
|
require_once __DIR__ . '/../../src/bootstrap.php';
|
|
|
|
use Deploymentcenter\Core\Config;
|
|
use Deploymentcenter\Core\Http;
|
|
use Deploymentcenter\Modules\Bugtracker\BugRepo;
|
|
use Deploymentcenter\Core\TokenManager;
|
|
|
|
Http::beginJson(['GET', 'OPTIONS'], true);
|
|
|
|
$baseUrl = Http::baseUrl();
|
|
|
|
$errorResponse = [
|
|
'description' => 'Fehler',
|
|
'content' => ['application/json' => ['schema' => ['$ref' => '#/components/schemas/Error']]],
|
|
];
|
|
|
|
$spec = [
|
|
'openapi' => '3.0.3',
|
|
'info' => [
|
|
'title' => 'Deploymentcenter API',
|
|
'version' => (string)Config::get('app.version', '2.0.0'),
|
|
'description' =>
|
|
"Zentrale Schnittstelle fuer Bugtracker, UpdateService, Watchdog und Token-Provisionierung.\n\n"
|
|
. "Authentifizierung ueber `Authorization: Bearer <token>` oder `X-Agent-Token`.\n"
|
|
. "Tokens werden im WebUI erzeugt (Master-Token) und koennen sich per\n"
|
|
. "`/api/tokens/v1/provision` selbst in Sub-Tokens aufteilen.\n\n"
|
|
. "Typischer Agenten-Ablauf:\n"
|
|
. "1. `POST /api/bugtracker/v1/manage?action=next` - naechstes Item holen und uebernehmen\n"
|
|
. "2. Arbeiten, Zwischenstand per `?action=comment` dokumentieren\n"
|
|
. "3. `?action=resolve` mit `resolved_in_build`\n"
|
|
. "4. Beim Release meldet `POST /api/updateservice/v1/publish` den Build; passende Items schliessen sich selbst.",
|
|
],
|
|
'servers' => [['url' => $baseUrl]],
|
|
'components' => [
|
|
'securitySchemes' => [
|
|
'bearerAuth' => ['type' => 'http', 'scheme' => 'bearer'],
|
|
'agentToken' => ['type' => 'apiKey', 'in' => 'header', 'name' => 'X-Agent-Token'],
|
|
],
|
|
'schemas' => [
|
|
'Error' => [
|
|
'type' => 'object',
|
|
'properties' => [
|
|
'status' => ['type' => 'string', 'enum' => ['error']],
|
|
'error' => [
|
|
'type' => 'object',
|
|
'properties' => [
|
|
'code' => ['type' => 'string', 'description' => 'Stabiler, maschinenlesbarer Fehlercode'],
|
|
'message' => ['type' => 'string'],
|
|
],
|
|
],
|
|
],
|
|
],
|
|
'BugtrackerItem' => [
|
|
'type' => 'object',
|
|
'properties' => [
|
|
'id' => ['type' => 'integer'],
|
|
'project_slug' => ['type' => 'string'],
|
|
'type' => ['type' => 'string', 'enum' => BugRepo::TYPES],
|
|
'title' => ['type' => 'string'],
|
|
'description' => ['type' => 'string', 'nullable' => true],
|
|
'error_message' => ['type' => 'string', 'nullable' => true],
|
|
'stack_trace' => ['type' => 'string', 'nullable' => true],
|
|
'environment' => ['type' => 'string', 'enum' => BugRepo::ENVIRONMENTS],
|
|
'severity' => ['type' => 'string', 'enum' => BugRepo::SEVERITIES],
|
|
'status' => ['type' => 'string', 'enum' => BugRepo::STATUSES],
|
|
'occurrence_count' => ['type' => 'integer'],
|
|
'claimed_by' => ['type' => 'string', 'nullable' => true],
|
|
'lease_until' => ['type' => 'string', 'format' => 'date-time', 'nullable' => true],
|
|
'repo_url' => ['type' => 'string', 'nullable' => true],
|
|
'git_branch' => ['type' => 'string', 'nullable' => true],
|
|
'commit_sha' => ['type' => 'string', 'nullable' => true],
|
|
'file_path' => ['type' => 'string', 'nullable' => true],
|
|
'line_no' => ['type' => 'integer', 'nullable' => true],
|
|
'resolved_in_build' => ['type' => 'string', 'nullable' => true],
|
|
'updated_at' => ['type' => 'string', 'format' => 'date-time'],
|
|
],
|
|
],
|
|
'ReportRequest' => [
|
|
'type' => 'object',
|
|
'required' => ['title'],
|
|
'properties' => [
|
|
'project_slug' => ['type' => 'string', 'example' => 'deploymentcenter'],
|
|
'type' => ['type' => 'string', 'enum' => BugRepo::TYPES, 'default' => 'bug'],
|
|
'title' => ['type' => 'string', 'maxLength' => 255],
|
|
'description' => ['type' => 'string'],
|
|
'error_message' => ['type' => 'string'],
|
|
'stack_trace' => ['type' => 'string'],
|
|
'severity' => ['type' => 'string', 'enum' => BugRepo::SEVERITIES],
|
|
'environment' => ['type' => 'string', 'enum' => BugRepo::ENVIRONMENTS],
|
|
'build_version' => ['type' => 'string'],
|
|
'push_id' => ['type' => 'string'],
|
|
'target_agent' => ['type' => 'string'],
|
|
'tags' => ['type' => 'string', 'description' => 'Kommagetrennt'],
|
|
'client_ref' => [
|
|
'type' => 'string',
|
|
'description' => 'Idempotenz-Schluessel. Ein erneuter Aufruf mit demselben Wert legt kein Duplikat an. Alternativ als Header Idempotency-Key.',
|
|
],
|
|
'repo_url' => ['type' => 'string'],
|
|
'git_branch' => ['type' => 'string'],
|
|
'commit_sha' => ['type' => 'string'],
|
|
'file_path' => ['type' => 'string'],
|
|
'line_no' => ['type' => 'integer'],
|
|
'context' => ['type' => 'object', 'description' => 'Beliebiger strukturierter Zusatzkontext'],
|
|
],
|
|
],
|
|
],
|
|
],
|
|
'security' => [['bearerAuth' => []], ['agentToken' => []]],
|
|
'paths' => [
|
|
|
|
'/api/health' => [
|
|
'get' => [
|
|
'tags' => ['System'],
|
|
'summary' => 'Verfuegbarkeit und Schema-Status',
|
|
'security' => [],
|
|
'responses' => ['200' => ['description' => 'Zustand'], '503' => ['description' => 'Nicht bereit']],
|
|
],
|
|
],
|
|
|
|
'/api/bugtracker/v1/report' => [
|
|
'post' => [
|
|
'tags' => ['Bugtracker'],
|
|
'summary' => 'Bug, Feature Request oder Idee melden',
|
|
'description' => 'Benoetigt den Scope bugtracker:report. Gleiche Fehler werden automatisch zusammengefasst und hochgezaehlt.',
|
|
'requestBody' => [
|
|
'required' => true,
|
|
'content' => ['application/json' => ['schema' => ['$ref' => '#/components/schemas/ReportRequest']]],
|
|
],
|
|
'responses' => [
|
|
'201' => ['description' => 'Neu angelegt'],
|
|
'200' => ['description' => 'Bestehendes Item aktualisiert (Duplikat oder Idempotenz-Treffer)'],
|
|
'401' => $errorResponse,
|
|
'429' => $errorResponse,
|
|
],
|
|
],
|
|
],
|
|
|
|
'/api/errors/v1/report' => [
|
|
'post' => [
|
|
'tags' => ['Fehler'],
|
|
'summary' => 'Laufzeitfehler melden',
|
|
'description' =>
|
|
"Schlanker Eingang fuer den globalen Exception-Handler. Titel und Dringlichkeit "
|
|
. "leitet der Server ab.\n\n"
|
|
. "Gleiche Fehler werden zu einer Gruppe zusammengefasst; veraenderliche Anteile "
|
|
. "(Werte in Anfuehrungszeichen mit Ziffern, Adressen, GUIDs, Zeitstempel) werden "
|
|
. "dabei ausgeblendet.\n\n"
|
|
. "Greift eine Ignore-Regel, kommt `\"ignored\": true` zurueck: der Fehler wird "
|
|
. "gezaehlt, aber nicht gemeldet. Ueberschreitet er die hinterlegte Alarmschwelle, "
|
|
. "meldet die Antwort `\"rate_alerted\": true`.",
|
|
'requestBody' => [
|
|
'required' => true,
|
|
'content' => ['application/json' => ['schema' => [
|
|
'type' => 'object',
|
|
'properties' => [
|
|
'project_slug' => ['type' => 'string'],
|
|
'exception' => ['type' => 'string', 'example' => 'PDOException'],
|
|
'message' => ['type' => 'string'],
|
|
'stack_trace' => ['type' => 'string'],
|
|
'level' => ['type' => 'string', 'enum' => BugRepo::ERROR_LEVELS, 'default' => 'error'],
|
|
'build' => ['type' => 'string'],
|
|
'environment' => ['type' => 'string', 'enum' => BugRepo::ENVIRONMENTS],
|
|
'file' => ['type' => 'string'],
|
|
'line' => ['type' => 'integer'],
|
|
'client_ref' => ['type' => 'string'],
|
|
'context' => ['type' => 'object'],
|
|
],
|
|
]]],
|
|
],
|
|
'responses' => [
|
|
'201' => ['description' => 'Neue Fehlergruppe angelegt'],
|
|
'200' => ['description' => 'Bestehende Gruppe hochgezaehlt'],
|
|
'401' => $errorResponse,
|
|
'429' => $errorResponse,
|
|
],
|
|
],
|
|
],
|
|
|
|
'/api/watchdog/v1/metrics' => [
|
|
'get' => [
|
|
'tags' => ['Watchdog'],
|
|
'summary' => 'Metrik-Verlauf abrufen',
|
|
'description' => 'Ohne "metric" die verfuegbaren Namen, mit "metric" den verdichteten Verlauf samt Abweichung vom eigenen Durchschnitt.',
|
|
'parameters' => [
|
|
['name' => 'source', 'in' => 'query', 'required' => true, 'schema' => ['type' => 'string']],
|
|
['name' => 'metric', 'in' => 'query', 'schema' => ['type' => 'string']],
|
|
['name' => 'hours', 'in' => 'query', 'schema' => ['type' => 'integer', 'default' => 24]],
|
|
['name' => 'bucket', 'in' => 'query', 'schema' => ['type' => 'integer', 'default' => 15], 'description' => 'Fenstergroesse in Minuten'],
|
|
],
|
|
'responses' => ['200' => ['description' => 'Verlauf'], '401' => $errorResponse],
|
|
],
|
|
],
|
|
|
|
'/api/bugtracker/v1/projects' => [
|
|
'get' => [
|
|
'tags' => ['Bugtracker'],
|
|
'summary' => 'Projekte auflisten (Discovery)',
|
|
'description' => 'Benoetigt den Scope bugtracker:read.',
|
|
'responses' => ['200' => ['description' => 'Projektliste'], '401' => $errorResponse],
|
|
],
|
|
],
|
|
|
|
'/api/bugtracker/v1/manage' => [
|
|
'get' => [
|
|
'tags' => ['Bugtracker'],
|
|
'summary' => 'Items lesen',
|
|
'description' => 'Scope bugtracker:read. action=list|get|stats|projects.',
|
|
'parameters' => [
|
|
['name' => 'action', 'in' => 'query', 'schema' => ['type' => 'string', 'enum' => ['list', 'get', 'stats', 'projects'], 'default' => 'list']],
|
|
['name' => 'id', 'in' => 'query', 'schema' => ['type' => 'integer'], 'description' => 'Pflicht bei action=get'],
|
|
['name' => 'project_slug', 'in' => 'query', 'schema' => ['type' => 'string']],
|
|
['name' => 'status', 'in' => 'query', 'schema' => ['type' => 'string'], 'description' => 'Mehrere kommagetrennt, z. B. open,in_progress'],
|
|
['name' => 'severity', 'in' => 'query', 'schema' => ['type' => 'string'], 'description' => 'Mehrere kommagetrennt'],
|
|
['name' => 'target_agent', 'in' => 'query', 'schema' => ['type' => 'string']],
|
|
['name' => 'unclaimed_only', 'in' => 'query', 'schema' => ['type' => 'boolean']],
|
|
['name' => 'updated_since', 'in' => 'query', 'schema' => ['type' => 'string', 'format' => 'date-time'], 'description' => 'Delta-Abfrage fuer Polling'],
|
|
['name' => 'order', 'in' => 'query', 'schema' => ['type' => 'string', 'enum' => ['newest', 'oldest', 'updated', 'severity', 'occurrences']]],
|
|
['name' => 'limit', 'in' => 'query', 'schema' => ['type' => 'integer', 'default' => 100, 'maximum' => 500]],
|
|
['name' => 'offset', 'in' => 'query', 'schema' => ['type' => 'integer', 'default' => 0]],
|
|
],
|
|
'responses' => ['200' => ['description' => 'Trefferliste mit total/has_more'], '401' => $errorResponse],
|
|
],
|
|
'post' => [
|
|
'tags' => ['Bugtracker'],
|
|
'summary' => 'Items veraendern',
|
|
'description' =>
|
|
"Scope bugtracker:manage.\n\n"
|
|
. "- `action=next` holt die naechsten offenen Items und uebernimmt sie exklusiv\n"
|
|
. "- `action=claim&id=` uebernimmt ein bestimmtes Item (409 wenn bereits vergeben)\n"
|
|
. "- `action=release&id=` gibt es wieder frei\n"
|
|
. "- `action=comment&id=` haengt einen Ermittlungsschritt an\n"
|
|
. "- `action=status&id=` setzt den Status\n"
|
|
. "- `action=update&id=` aendert mehrere Felder\n"
|
|
. "- `action=resolve&id=` schliesst mit resolved_in_build\n"
|
|
. "- `action=bulk_update` aendert mehrere Items (ids[] + updates{})",
|
|
'parameters' => [
|
|
['name' => 'action', 'in' => 'query', 'required' => true, 'schema' => ['type' => 'string', 'enum' => ['claim', 'next', 'release', 'comment', 'status', 'update', 'resolve', 'bulk_update']]],
|
|
['name' => 'id', 'in' => 'query', 'schema' => ['type' => 'integer']],
|
|
],
|
|
'responses' => [
|
|
'200' => ['description' => 'Erfolg'],
|
|
'409' => ['description' => 'Item bereits von einem anderen Agenten uebernommen'],
|
|
'401' => $errorResponse,
|
|
],
|
|
],
|
|
],
|
|
|
|
'/api/updateservice/v1/check' => [
|
|
'get' => [
|
|
'tags' => ['UpdateService'],
|
|
'summary' => 'Auf Update pruefen',
|
|
'security' => [],
|
|
'parameters' => [
|
|
['name' => 'product', 'in' => 'query', 'required' => true, 'schema' => ['type' => 'string']],
|
|
['name' => 'version', 'in' => 'query', 'required' => true, 'schema' => ['type' => 'string']],
|
|
['name' => 'channel', 'in' => 'query', 'schema' => ['type' => 'string', 'default' => 'prod']],
|
|
],
|
|
'responses' => ['200' => ['description' => 'Vergleich nach semantischer Versionsordnung']],
|
|
],
|
|
],
|
|
|
|
'/api/updateservice/v1/publish' => [
|
|
'post' => [
|
|
'tags' => ['UpdateService'],
|
|
'summary' => 'Release veroeffentlichen',
|
|
'description' => 'Scope updateservice:publish. Schliesst automatisch alle Bugtracker-Items, deren resolved_in_build dieser Version entspricht.',
|
|
'requestBody' => [
|
|
'required' => true,
|
|
'content' => ['application/json' => ['schema' => [
|
|
'type' => 'object',
|
|
'required' => ['product_slug', 'version', 'download_url'],
|
|
'properties' => [
|
|
'product_slug' => ['type' => 'string'],
|
|
'version' => ['type' => 'string', 'example' => '1.4.3'],
|
|
'channel' => ['type' => 'string', 'default' => 'prod'],
|
|
'download_url' => ['type' => 'string'],
|
|
'sha256_hash' => ['type' => 'string', 'pattern' => '^[0-9a-fA-F]{64}$'],
|
|
'git_commit' => ['type' => 'string'],
|
|
'size_bytes' => ['type' => 'integer'],
|
|
'release_notes' => ['type' => 'string'],
|
|
'is_critical' => ['type' => 'boolean'],
|
|
],
|
|
]]],
|
|
],
|
|
'responses' => ['201' => ['description' => 'Angelegt'], '200' => ['description' => 'Aktualisiert'], '401' => $errorResponse],
|
|
],
|
|
],
|
|
|
|
'/api/watchdog/v1/ping' => [
|
|
'post' => [
|
|
'tags' => ['Watchdog'],
|
|
'summary' => 'Heartbeat senden',
|
|
'description' => 'Scope watchdog:ping. Alternativ ein Agent-Token aus watchdog_agent_tokens.',
|
|
'requestBody' => [
|
|
'required' => true,
|
|
'content' => ['application/json' => ['schema' => [
|
|
'type' => 'object',
|
|
'required' => ['source'],
|
|
'properties' => [
|
|
'source' => ['type' => 'string'],
|
|
'instance' => ['type' => 'string', 'default' => 'default'],
|
|
'status' => ['type' => 'string', 'enum' => ['ok', 'warning', 'error']],
|
|
'interval' => ['type' => 'integer', 'description' => 'Erwarteter Abstand in Sekunden; danach gilt der Monitor als auffaellig'],
|
|
'message' => ['type' => 'string'],
|
|
'metrics' => ['type' => 'object'],
|
|
'os' => ['type' => 'string'],
|
|
],
|
|
]]],
|
|
],
|
|
'responses' => ['200' => ['description' => 'Empfangen'], '401' => $errorResponse],
|
|
],
|
|
],
|
|
|
|
'/api/watchdog/v1/evaluate' => [
|
|
'get' => [
|
|
'tags' => ['Watchdog'],
|
|
'summary' => 'Evaluationslauf ausloesen',
|
|
'description' => 'Nur mit Shared Key oder angemeldeter Sitzung. Per Cron minuetlich aufrufen, sonst bleiben ausgefallene Monitore gruen.',
|
|
'responses' => ['200' => ['description' => 'Ergebnis des Laufs'], '401' => $errorResponse],
|
|
],
|
|
],
|
|
|
|
'/api/tokens/v1/provision' => [
|
|
'post' => [
|
|
'tags' => ['Tokens'],
|
|
'summary' => 'Sub-Token aus Master-Token erzeugen',
|
|
'description' => 'Master-Token im Header X-Master-Token. Rechte koennen nur eingeschraenkt, nicht erweitert werden.',
|
|
'requestBody' => [
|
|
'content' => ['application/json' => ['schema' => [
|
|
'type' => 'object',
|
|
'properties' => [
|
|
'client_name' => ['type' => 'string'],
|
|
'instance_id' => ['type' => 'string'],
|
|
'scopes' => ['type' => 'array', 'items' => ['type' => 'string', 'enum' => TokenManager::KNOWN_SCOPES]],
|
|
'environment' => ['type' => 'string', 'enum' => TokenManager::ENVIRONMENTS],
|
|
],
|
|
]]],
|
|
],
|
|
'responses' => ['201' => ['description' => 'Sub-Token erstellt'], '403' => $errorResponse],
|
|
],
|
|
],
|
|
],
|
|
];
|
|
|
|
// Direkte Ausgabe statt Http::ok(), damit die Spezifikation nicht in einen
|
|
// status-Umschlag verpackt wird.
|
|
if (!headers_sent()) {
|
|
header('Content-Type: application/json; charset=utf-8');
|
|
header('Cache-Control: public, max-age=300');
|
|
}
|
|
|
|
echo json_encode($spec, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
|