From a74c6fd99023b27264f0c9f2a4f75eef5c78bea1 Mon Sep 17 00:00:00 2001 From: Deploymentcenter Bot Date: Fri, 7 Aug 2026 16:27:02 +0200 Subject: [PATCH] fix(clients, docs): Lizenz-Antwortformat wiederherstellen, Packager absichern MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Regression aus dem vorigen Commit - /api/license/v1/validate lieferte die Antwort im neuen status/error-Umschlag. Der Vertrag dieses Endpunkts ist aber bereits ausgerollt: das Feld "status" auf oberster Ebene trägt den Lizenzzustand (valid, revoked, expired ...). LicenseClient las dadurch "success" statt "valid" — jeder ausgelieferte Client hätte seine Lizenz für ungültig gehalten. Die Lizenz-Endpunkte antworten jetzt wieder ohne Umschlag (Http::raw). Gefunden durch Ausführen der projekteigenen Test-Suite gegen den Server. Packager - FTP-Zugangsdaten standen als Standardwerte im Quelltext und zusätzlich in packager.config.json und in der Integrationsanleitung. Alle drei Fundstellen bereinigt; die Konfigurationsdatei ist nicht mehr versioniert. Zugangsdaten kommen aus Datei, Umgebungsvariablen oder CLI-Argument, sonst bricht das Programm mit einer klaren Meldung ab. - Das Veröffentlichen sendet jetzt ein Token (updateservice:publish) und nutzt den Endpunkt /api/updateservice/v1/publish. - Fehler wurden von einem leeren catch verschluckt, und ohne Erfolgsfall wurde gar nichts ausgegeben. Das Werkzeug meldete am Ende immer Erfolg und lieferte Rückgabewert 0, selbst wenn FTP-Upload und API-Aufruf fehlgeschlagen waren. Jetzt ehrliche Meldungen und Rückgabewerte 0/1/2. - packager.config.json wurde vom csproj nie ins Ausgabeverzeichnis kopiert, weshalb sie dort nie gefunden wurde und stets die hartkodierten Werte griffen. UpdateClient - IsVersionNewer entfernte die Vorabkennung, aber kein führendes "v". Damit scheiterte Version.TryParse bei "v1.4.2" und es wurde auf einen alphabetischen Vergleich zurückgefallen, in dem "v1.9.0" als neuer gilt als "v1.10.0" — derselbe Fehler wie zuvor serverseitig im SQL. Ersetzt durch einen vollständigen semantischen Vergleich, verifiziert mit 16 Testfällen. - Der Rückfall auf die API lag in einem catch-Block, aber GetAsync wirft bei einem 404 keine Exception. Fehlte die statische latest.json, brach die Prüfung ab, statt die API zu befragen. Dokumentation - BUGTRACKER_INTEGRATION_GUIDE.md beschrieb denselben Workflow ein zweites Mal und war bereits auseinandergelaufen: Aufrufe ohne Token, alte Pfade, weder Claim/Lease noch Idempotenz. Ersetzt durch einen Verweis auf das gepflegte Agenten-Handbuch samt Übersicht der Änderungen. - UPDATESERVICE_INTEGRATION_GUIDE.md um Token, Umgebungsvariablen und Rückgabewerte ergänzt. Co-Authored-By: Claude Opus 5 --- .gitignore | 1 + .../Deploymentcenter.Client/UpdateClient.cs | 128 +++++++- .../Deploymentcenter.Packager.csproj | 15 + .../Deploymentcenter.Packager/Program.cs | 240 ++++++++++++-- .../packager.config.example.json | 24 ++ .../packager.config.json | 18 -- docs/BUGTRACKER_INTEGRATION_GUIDE.md | 298 +++--------------- docs/UPDATESERVICE_INTEGRATION_GUIDE.md | 46 ++- public/api/license/v1/index.php | 13 +- src/Core/Http.php | 25 ++ 10 files changed, 481 insertions(+), 327 deletions(-) create mode 100644 client-dotnet/Deploymentcenter.Packager/packager.config.example.json delete mode 100644 client-dotnet/Deploymentcenter.Packager/packager.config.json diff --git a/.gitignore b/.gitignore index 200960d..edc16d3 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,4 @@ scripts/deploy_config.json Serverdaten.txt *.local.php .env +client-dotnet/Deploymentcenter.Packager/packager.config.json diff --git a/client-dotnet/Deploymentcenter.Client/UpdateClient.cs b/client-dotnet/Deploymentcenter.Client/UpdateClient.cs index 5d54fd8..a224d51 100644 --- a/client-dotnet/Deploymentcenter.Client/UpdateClient.cs +++ b/client-dotnet/Deploymentcenter.Client/UpdateClient.cs @@ -59,22 +59,39 @@ namespace Deploymentcenter.Client // Path pattern: https://domain/releases/{ProjectId}/{channel}/latest.json string staticUrl = $"{cleanBaseUrl}/releases/{projectId}/{channel}/latest.json"; - HttpResponseMessage response; + // Zuerst die statische latest.json, danach die API. + // + // Der Rueckfall auf die API war zuvor unerreichbar: er lag in + // einem catch, aber GetAsync wirft bei einem 404 keine Exception, + // sondern liefert eine Antwort mit Statuscode. Fehlte die + // latest.json, brach die Pruefung mit "HTTP Error NotFound" ab, + // statt die API zu befragen. + HttpResponseMessage? response = null; + try { response = await _httpClient.GetAsync(staticUrl, cancellationToken).ConfigureAwait(false); } catch { - // Fallback check: Deploymentcenter API endpoint - // Path pattern: https://domain/api/updateservice/v1/check?product={projectId}&version={currentVersion} - string apiUrl = $"{cleanBaseUrl}/api/updateservice/v1/check?product={Uri.EscapeDataString(projectId)}&version={Uri.EscapeDataString(currentVersion)}"; + response = null; + } + + if (response == null || !response.IsSuccessStatusCode) + { + response?.Dispose(); + + string apiUrl = $"{cleanBaseUrl}/api/updateservice/v1/check" + + $"?product={Uri.EscapeDataString(projectId)}" + + $"&version={Uri.EscapeDataString(currentVersion)}" + + $"&channel={Uri.EscapeDataString(channel)}"; + response = await _httpClient.GetAsync(apiUrl, cancellationToken).ConfigureAwait(false); } if (!response.IsSuccessStatusCode) { - result.Message = $"HTTP Error {response.StatusCode} during update check"; + result.Message = $"Update-Pruefung fehlgeschlagen: HTTP {(int)response.StatusCode}"; return result; } @@ -214,24 +231,107 @@ namespace Deploymentcenter.Client return BitConverter.ToString(hash).Replace("-", "").ToLowerInvariant(); } + /// + /// Prueft, ob neuer ist als . + /// + /// Die vorherige Fassung entfernte zwar die Vorabkennung, nicht aber ein + /// fuehrendes "v". Damit scheiterte Version.TryParse bei Angaben wie + /// "v1.4.2" und es wurde auf einen alphabetischen Vergleich + /// zurueckgefallen - dort gilt "v1.9.0" faelschlich als neuer als + /// "v1.10.0". Das entspricht dem Fehler, der serverseitig in der + /// SQL-Abfrage steckte. + /// public static bool IsVersionNewer(string currentVer, string remoteVer) { - if (string.IsNullOrEmpty(remoteVer)) return false; - if (string.IsNullOrEmpty(currentVer)) return true; + if (string.IsNullOrWhiteSpace(remoteVer)) return false; + if (string.IsNullOrWhiteSpace(currentVer)) return true; - string CleanVer(string v) + return CompareVersions(remoteVer, currentVer) > 0; + } + + /// + /// Vergleicht zwei Versionsangaben nach semantischer Ordnung. + /// Rueckgabe: negativ wenn a < b, 0 bei Gleichstand, positiv wenn a > b. + /// + public static int CompareVersions(string a, string b) + { + var (coreA, preA) = ParseVersion(a); + var (coreB, preB) = ParseVersion(b); + + int length = Math.Max(coreA.Count, coreB.Count); + for (int i = 0; i < length; i++) { - int dash = v.IndexOf('-'); - return dash > 0 ? v.Substring(0, dash) : v; + int partA = i < coreA.Count ? coreA[i] : 0; + int partB = i < coreB.Count ? coreB[i] : 0; + if (partA != partB) + { + return partA.CompareTo(partB); + } } - if (Version.TryParse(CleanVer(currentVer), out var cVer) && - Version.TryParse(CleanVer(remoteVer), out var rVer)) + // Eine Version ohne Vorabkennung rangiert ueber derselben mit: + // 1.0.0 ist neuer als 1.0.0-rc.1 + bool emptyA = preA.Count == 0; + bool emptyB = preB.Count == 0; + if (emptyA && emptyB) return 0; + if (emptyA) return 1; + if (emptyB) return -1; + + int preLength = Math.Max(preA.Count, preB.Count); + for (int i = 0; i < preLength; i++) { - return rVer > cVer; + if (i >= preA.Count) return -1; + if (i >= preB.Count) return 1; + + bool numericA = int.TryParse(preA[i], out int numA); + bool numericB = int.TryParse(preB[i], out int numB); + + if (numericA && numericB) + { + if (numA != numB) return numA.CompareTo(numB); + continue; + } + + // Rein numerische Bestandteile rangieren unter alphanumerischen. + if (numericA != numericB) return numericA ? -1 : 1; + + int cmp = string.CompareOrdinal(preA[i], preB[i]); + if (cmp != 0) return cmp > 0 ? 1 : -1; } - return string.Compare(remoteVer, currentVer, StringComparison.OrdinalIgnoreCase) > 0; + return 0; + } + + private static (List Core, List Prerelease) ParseVersion(string version) + { + string value = (version ?? string.Empty).Trim().TrimStart('v', 'V'); + + // Build-Metadaten sind fuer die Rangfolge ohne Bedeutung. + int plus = value.IndexOf('+'); + if (plus >= 0) value = value.Substring(0, plus); + + var prerelease = new List(); + int dash = value.IndexOf('-'); + if (dash >= 0) + { + string preString = value.Substring(dash + 1); + value = value.Substring(0, dash); + if (preString.Length > 0) + { + prerelease.AddRange(preString.Split('.')); + } + } + + var core = new List(); + foreach (string part in value.Split('.')) + { + string digits = new string(part.Where(char.IsDigit).ToArray()); + core.Add(digits.Length > 0 ? int.Parse(digits) : 0); + } + + if (core.Count == 0) core.Add(0); + + return (core, prerelease); } } } diff --git a/client-dotnet/Deploymentcenter.Packager/Deploymentcenter.Packager.csproj b/client-dotnet/Deploymentcenter.Packager/Deploymentcenter.Packager.csproj index 1fb5fbf..7a6e193 100644 --- a/client-dotnet/Deploymentcenter.Packager/Deploymentcenter.Packager.csproj +++ b/client-dotnet/Deploymentcenter.Packager/Deploymentcenter.Packager.csproj @@ -18,4 +18,19 @@ + + + + PreserveNewest + + + PreserveNewest + + + diff --git a/client-dotnet/Deploymentcenter.Packager/Program.cs b/client-dotnet/Deploymentcenter.Packager/Program.cs index 5b9c20f..3af3a51 100644 --- a/client-dotnet/Deploymentcenter.Packager/Program.cs +++ b/client-dotnet/Deploymentcenter.Packager/Program.cs @@ -15,18 +15,56 @@ using FluentFTP; namespace Deploymentcenter.Packager { + /// + /// Konfiguration des Packagers. + /// + /// Die Zugangsdaten standen zuvor als Standardwerte direkt im Quelltext und + /// lagen damit im Repository. Sie kommen jetzt ausschliesslich aus + /// packager.config.json (nicht versioniert) oder aus Umgebungsvariablen. + /// Fehlen sie, bricht das Programm mit einer klaren Meldung ab, statt sich + /// mit veralteten Werten zu verbinden. + /// public class PackagerConfig { - public string FtpHost { get; set; } = "www531.your-server.de"; + public string FtpHost { get; set; } = ""; public int FtpPort { get; set; } = 21; - public string FtpUser { get; set; } = "bergisnu_4"; - public string FtpPass { get; set; } = "o2#M*NN^5EsT"; + public string FtpUser { get; set; } = ""; + public string FtpPass { get; set; } = ""; public string FtpRemoteBaseDir { get; set; } = "/public_html/releases"; public string ApiBaseUrl { get; set; } = "https://dc.mhdf.de"; + + /// + /// Token mit dem Recht updateservice:publish. Das Veroeffentlichen eines + /// Releases ist nicht mehr unauthentifiziert moeglich. + /// + public string ApiToken { get; set; } = ""; + public List ExcludePatterns { get; set; } = new List { "*.pdb", "*.xml", "appsettings.Development.json", "appsettings.Staging.json", "*.log", "logs/*" }; + + /// Umgebungsvariablen haben Vorrang vor der Konfigurationsdatei. + public void ApplyEnvironmentOverrides() + { + FtpHost = Env("DC_FTP_HOST", FtpHost); + FtpUser = Env("DC_FTP_USER", FtpUser); + FtpPass = Env("DC_FTP_PASS", FtpPass); + ApiBaseUrl = Env("DC_API_URL", ApiBaseUrl); + ApiToken = Env("DC_TOKEN", ApiToken); + + string port = Env("DC_FTP_PORT", ""); + if (int.TryParse(port, out int parsedPort) && parsedPort > 0) + { + FtpPort = parsedPort; + } + } + + private static string Env(string name, string fallback) + { + string? value = Environment.GetEnvironmentVariable(name); + return string.IsNullOrWhiteSpace(value) ? fallback : value; + } } class Program @@ -46,12 +84,43 @@ namespace Deploymentcenter.Packager string configFile = GetArg(args, "--config") ?? Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "packager.config.json"); PackagerConfig config = LoadConfig(configFile); + config.ApplyEnvironmentOverrides(); - // Override config with explicit CLI args if provided + // Reihenfolge: CLI-Argument, dann Umgebungsvariable, dann Datei. string ftpHost = GetArg(args, "--ftp-host") ?? config.FtpHost; string ftpUser = GetArg(args, "--ftp-user") ?? config.FtpUser; string ftpPass = GetArg(args, "--ftp-pass") ?? config.FtpPass; string remoteBase = GetArg(args, "--remote-dir") ?? config.FtpRemoteBaseDir; + string apiToken = GetArg(args, "--token") ?? config.ApiToken; + + var missing = new List(); + if (string.IsNullOrWhiteSpace(ftpHost)) missing.Add("FTP-Host (--ftp-host / DC_FTP_HOST / ftpHost)"); + if (string.IsNullOrWhiteSpace(ftpUser)) missing.Add("FTP-Benutzer (--ftp-user / DC_FTP_USER / ftpUser)"); + if (string.IsNullOrWhiteSpace(ftpPass)) missing.Add("FTP-Passwort (--ftp-pass / DC_FTP_PASS / ftpPass)"); + + if (missing.Count > 0) + { + Console.ForegroundColor = ConsoleColor.Red; + Console.WriteLine("[FEHLER] Konfiguration unvollstaendig:"); + foreach (var item in missing) + { + Console.WriteLine($" - {item}"); + } + Console.ResetColor(); + Console.WriteLine(); + Console.WriteLine($"Vorlage kopieren: {Path.GetFileName(configFile)}.example -> {Path.GetFileName(configFile)}"); + return 1; + } + + if (string.IsNullOrWhiteSpace(apiToken)) + { + Console.ForegroundColor = ConsoleColor.Yellow; + Console.WriteLine("[WARNUNG] Kein API-Token gesetzt (--token / DC_TOKEN / apiToken)."); + Console.WriteLine(" Das Paket wird gebaut und hochgeladen, aber das Deploymentcenter"); + Console.WriteLine(" erfaehrt nichts davon - Veroeffentlichen erfordert seit Version 2.0"); + Console.WriteLine(" ein Token mit dem Recht updateservice:publish."); + Console.ResetColor(); + } publishDir = Path.GetFullPath(publishDir); if (!Directory.Exists(publishDir)) @@ -162,6 +231,8 @@ namespace Deploymentcenter.Packager Console.WriteLine($"[INFO] Uploading via FTP to {ftpHost}:{config.FtpPort} ({remoteVersionPath})..."); + bool ftpSucceeded = false; + try { using var ftp = new AsyncFtpClient(ftpHost, ftpUser, ftpPass, config.FtpPort); @@ -241,50 +312,153 @@ namespace Deploymentcenter.Packager Console.WriteLine("[SUCCESS] Updated latest.json on FTP server!"); await ftp.Disconnect(); + ftpSucceeded = true; } catch (Exception ex) { - Console.ForegroundColor = ConsoleColor.Yellow; - Console.WriteLine($"[WARNING] FTP upload encountered error: {ex.Message}"); + Console.ForegroundColor = ConsoleColor.Red; + Console.WriteLine($"[FEHLER] FTP-Upload fehlgeschlagen: {ex.Message}"); + Console.WriteLine(" Das Paket wurde NICHT ausgeliefert."); Console.ResetColor(); } - // 6. Notify Deploymentcenter Web API - try - { - using var http = new HttpClient(); - string apiPublishUrl = $"{config.ApiBaseUrl.TrimEnd('/')}/api/updateservice/v1/index.php"; - var payload = new - { - action = "publish_release", - product_slug = project, - version = version, - channel = channel, - release_notes = changelog, - download_url = $"{config.ApiBaseUrl.TrimEnd('/')}/releases/{project}/{channel}/{version}/package.tar.gz", - sha256_hash = packageSha256, - git_commit = gitCommitShort, - size_bytes = packageSizeBytes, - is_critical = isCritical ? 1 : 0 - }; + // 6. Deploymentcenter benachrichtigen + // + // Zuvor stand hier ein leeres catch, und ohne Erfolgsfall wurde gar + // nichts ausgegeben. Ein fehlgeschlagener Aufruf blieb damit + // unsichtbar, waehrend das Programm am Ende Erfolg meldete. + bool apiNotified = false; + string apiMessage = "uebersprungen (kein Token gesetzt)"; - string jsonContent = JsonSerializer.Serialize(payload); - var content = new StringContent(jsonContent, Encoding.UTF8, "application/json"); - var response = await http.PostAsync(apiPublishUrl, content); - if (response.IsSuccessStatusCode) + if (!string.IsNullOrWhiteSpace(apiToken)) + { + try { - Console.WriteLine("[SUCCESS] Notified Deploymentcenter Web API of new release."); + using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) }; + string apiPublishUrl = $"{config.ApiBaseUrl.TrimEnd('/')}/api/updateservice/v1/publish"; + + var payload = new + { + product_slug = project, + version = version, + channel = channel, + release_notes = changelog, + download_url = $"{config.ApiBaseUrl.TrimEnd('/')}/releases/{project}/{channel}/{version}/package.tar.gz", + sha256_hash = packageSha256, + git_commit = gitCommitShort, + size_bytes = packageSizeBytes, + is_critical = isCritical + }; + + var request = new HttpRequestMessage(HttpMethod.Post, apiPublishUrl) + { + Content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json") + }; + request.Headers.Add("Authorization", $"Bearer {apiToken}"); + + var response = await http.SendAsync(request); + string body = await response.Content.ReadAsStringAsync(); + + if (response.IsSuccessStatusCode) + { + apiNotified = true; + apiMessage = ExtractJsonString(body, "message") ?? "Release im Deploymentcenter eingetragen."; + + string? autoResolved = ExtractJsonString(body, "auto_resolved"); + if (!string.IsNullOrEmpty(autoResolved) && autoResolved != "0") + { + apiMessage += $" ({autoResolved} Bugtracker-Item(s) automatisch geschlossen)"; + } + } + else + { + apiMessage = $"HTTP {(int)response.StatusCode}: " + + (ExtractJsonString(body, "message") ?? body.Trim()); + } + } + catch (Exception ex) + { + apiMessage = $"Aufruf fehlgeschlagen: {ex.Message}"; } } - catch { } + + if (apiNotified) + { + Console.ForegroundColor = ConsoleColor.Green; + Console.WriteLine($"[SUCCESS] {apiMessage}"); + } + else + { + Console.ForegroundColor = ConsoleColor.Yellow; + Console.WriteLine($"[WARNUNG] Deploymentcenter nicht benachrichtigt - {apiMessage}"); + } + Console.ResetColor(); // Cleanup temp try { Directory.Delete(outputTempDir, true); } catch { } - Console.ForegroundColor = ConsoleColor.Green; - Console.WriteLine($"\n[FINISHED] Release v{version} for {project} ({channel}) successfully published!"); + // Der Rueckgabewert bildet jetzt ab, was tatsaechlich passiert ist. + // Zuvor wurde immer 0 und "successfully published" gemeldet, selbst + // wenn FTP-Upload und API-Aufruf beide fehlgeschlagen waren. + bool fullySucceeded = ftpSucceeded && apiNotified; + + Console.WriteLine(); + Console.ForegroundColor = fullySucceeded ? ConsoleColor.Green : ConsoleColor.Yellow; + Console.WriteLine(fullySucceeded + ? $"[FERTIG] Release {version} fuer {project} ({channel}) vollstaendig veroeffentlicht." + : $"[UNVOLLSTAENDIG] Release {version} fuer {project} ({channel}): " + + $"Upload {(ftpSucceeded ? "ok" : "FEHLGESCHLAGEN")}, " + + $"Registrierung {(apiNotified ? "ok" : "FEHLGESCHLAGEN")}."); Console.ResetColor(); - return 0; + + return fullySucceeded ? 0 : 2; + } + + /// + /// Liest einen einzelnen Wert aus einer JSON-Antwort, ohne ein + /// vollstaendiges Modell dafuer zu benoetigen. + /// + static string? ExtractJsonString(string json, string propertyName) + { + try + { + using var doc = JsonDocument.Parse(json); + return FindProperty(doc.RootElement, propertyName); + } + catch + { + return null; + } + } + + static string? FindProperty(JsonElement element, string propertyName) + { + if (element.ValueKind != JsonValueKind.Object) + { + return null; + } + + if (element.TryGetProperty(propertyName, out var direct)) + { + return direct.ValueKind == JsonValueKind.String + ? direct.GetString() + : direct.ToString(); + } + + // Fehlerantworten verpacken die Nachricht in einem "error"-Objekt. + foreach (var child in element.EnumerateObject()) + { + if (child.Value.ValueKind == JsonValueKind.Object) + { + string? nested = FindProperty(child.Value, propertyName); + if (nested != null) + { + return nested; + } + } + } + + return null; } static PackagerConfig LoadConfig(string path) diff --git a/client-dotnet/Deploymentcenter.Packager/packager.config.example.json b/client-dotnet/Deploymentcenter.Packager/packager.config.example.json new file mode 100644 index 0000000..3245a8d --- /dev/null +++ b/client-dotnet/Deploymentcenter.Packager/packager.config.example.json @@ -0,0 +1,24 @@ +{ + "_comment": "Kopie als packager.config.json anlegen und ausfuellen. packager.config.json ist per .gitignore ausgeschlossen. Alternativ ueber Umgebungsvariablen: DC_FTP_HOST, DC_FTP_PORT, DC_FTP_USER, DC_FTP_PASS, DC_API_URL, DC_TOKEN.", + + "ftpHost": "ftp.example.com", + "ftpPort": 21, + "ftpUser": "ftp-user", + "ftpPass": "ftp-password", + "ftpRemoteBaseDir": "/public_html/releases", + + "apiBaseUrl": "https://dc.example.com", + "_apiToken_comment": "Token mit dem Recht updateservice:publish. Im WebUI unter Token-Verwaltung erzeugen.", + "apiToken": "", + + "excludePatterns": [ + "*.pdb", + "*.xml", + "appsettings.Development.json", + "appsettings.Staging.json", + "*.log", + "logs/**", + "scratch/**", + "*.tmp" + ] +} diff --git a/client-dotnet/Deploymentcenter.Packager/packager.config.json b/client-dotnet/Deploymentcenter.Packager/packager.config.json deleted file mode 100644 index ef89c76..0000000 --- a/client-dotnet/Deploymentcenter.Packager/packager.config.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "ftpHost": "www531.your-server.de", - "ftpPort": 21, - "ftpUser": "bergisnu_4", - "ftpPass": "o2#M*NN^5EsT", - "ftpRemoteBaseDir": "/public_html/releases", - "apiBaseUrl": "https://dc.mhdf.de", - "excludePatterns": [ - "*.pdb", - "*.xml", - "appsettings.Development.json", - "appsettings.Staging.json", - "*.log", - "logs/**", - "scratch/**", - "*.tmp" - ] -} diff --git a/docs/BUGTRACKER_INTEGRATION_GUIDE.md b/docs/BUGTRACKER_INTEGRATION_GUIDE.md index df55f64..e565a56 100644 --- a/docs/BUGTRACKER_INTEGRATION_GUIDE.md +++ b/docs/BUGTRACKER_INTEGRATION_GUIDE.md @@ -1,266 +1,56 @@ -# 🤖 AI Agent Integration Guide: Deployment Center Bugtracker & Provisioning API +# Bugtracker-Integration -> **⚠️ Geändert in Version 2.0** — `POST /api/bugtracker/v1/report` und -> `GET /api/bugtracker/v1/projects` verlangen jetzt zwingend ein Token mit dem -> passenden Scope; Aufrufe ohne Token liefern `401 unauthorized`. Das -> Antwortformat wurde vereinheitlicht. Die aktuelle, vollständige Beschreibung -> steht im **[Agenten-Handbuch](../public/docs/bugtracker.md)** und unter -> `/api/openapi.json`. Umstellungsschritte: **[UPGRADE.md](./UPGRADE.md)**. - - -This guide defines the standardized protocol and API specifications for autonomous AI Developer Agents interacting with the **Deployment Center Bugtracker & Token Provisioning System**. +> **Dieser Leitfaden wurde zusammengeführt.** +> +> Die vollständige, gepflegte Beschreibung steht im +> **[Agenten-Handbuch](../public/docs/bugtracker.md)** — öffentlich erreichbar +> unter `https://dc.mhdf.de/docs/` und maschinenlesbar unter +> `https://dc.mhdf.de/api/openapi.json`. +> +> Zuvor existierten zwei Beschreibungen desselben Workflows nebeneinander. Sie +> waren bereits auseinandergelaufen: die hier stehenden Beispiele riefen die +> Endpunkte ohne Token auf, benutzten `report.php` und `manage/index.php` als +> Pfade und kannten weder Claim/Lease noch Idempotenz. Ein Agent, der diesem +> Dokument folgte, wäre seit Version 2.0 an `401 unauthorized` gescheitert. --- -## 📌 Executive Overview for AI Agents +## Was sich gegenüber der alten Fassung geändert hat -As an autonomous AI agent working on software repositories, you MUST actively track all runtime errors, stack traces, planned features, and backlog items in the central Deployment Center. +| Alt | Neu | +|---|---| +| `POST /api/bugtracker/v1/report.php` ohne Token | `POST /api/bugtracker/v1/report` **mit** Token (`bugtracker:report`) | +| `GET /api/bugtracker/v1/projects.php` ohne Token | `GET /api/bugtracker/v1/projects` **mit** Token (`bugtracker:read`) | +| `GET .../manage/index.php?project_slug=…` | `GET .../manage?action=list&project_slug=…` | +| `created_by` frei wählbar | Wird aus dem Token abgeleitet | +| Keine Reservierung — zwei Agenten konnten dasselbe Item bearbeiten | `?action=next` holt und reserviert exklusiv (Claim/Lease) | +| Wiederholte Sendung erzeugte Duplikate | `client_ref` bzw. Header `Idempotency-Key` | +| Fehler nur als Freitext | Stabiler `error.code` zum Auswerten | -### Core Capabilities: -1. **Sub-Token Auto-Provisioning**: Generate restricted sub-tokens for scoped agent tasks. -2. **Automated Error Ingestion**: Report unhandled exceptions with stack traces & automatic SHA-256 deduplication. -3. **Feature & Idea Backlog**: Submit roadmap ideas (`severity: "idea"`) or backlog items (`severity: "wishlist"`). -4. **Active Workflow Management**: Fetch active bugs assigned to your agent ID, update status (`in_progress`, `resolved`), and append diagnostic comments. +## Kürzestmögliche Fassung ---- - -## 🔑 1. Token Provisioning API - -Agents authenticate using a **Master Token** or auto-provisioned **Sub-Token**. - -### Endpoint: `POST /api/tokens/v1/provision` - -Header: `Authorization: Bearer ` - -#### Request Payload: -```json -{ - "parent_token": "dc_master_myapp_dev_agent_001", - "name": "Codebase Refactoring Agent Token", - "environment": "development", - "scopes": ["bugtracker:report", "bugtracker:manage"], - "expires_in_hours": 24 -} -``` - -#### Response: -```json -{ - "status": "success", - "token_id": "tok_s_8912ab", - "raw_token": "dc_sub_myapp_refactor_agent_991", - "scopes": ["bugtracker:report", "bugtracker:manage"], - "environment": "development", - "expires_at": "2026-08-07 21:00:00" -} -``` - ---- - -## 📂 1.5. Discovering Monitored Projects API - -Before reporting a bug or feature request, an agent can dynamically query all registered projects monitored by the Deployment Center. - -### Endpoint: `GET /api/bugtracker/v1/projects.php` - -#### Response: -```json -{ - "status": "success", - "count": 4, - "projects": [ - { - "id": 1, - "slug": "myapp", - "name": "My Application Deluxe", - "notes": "Hauptanwendung für Desktop und Server" - }, - { - "id": 2, - "slug": "polytrader", - "name": "PolyTrader Suite Pro", - "notes": "Trading- und Handelssystem Client" - }, - { - "id": 3, - "slug": "predictalytics", - "name": "Predictalytics Engine", - "notes": "Datenanalyse und Vorhersage Dienst" - }, - { - "id": 4, - "slug": "deploymentcenter", - "name": "Deployment Center", - "notes": "Zentrale Verwaltungs- & Update-Plattform" - } - ] -} -``` - -If an agent discovers an issue or refactoring opportunity in any monitored system (including `deploymentcenter` itself or external dependencies), it can fetch this project list and map the issue to the appropriate `project_slug`. - ---- - -## 🐛 2. Reporting Bugs, Features & Ideas - -### Endpoint: `POST /api/bugtracker/v1/report.php` - -Header: `Authorization: Bearer ` - -### A. Reporting an Unhandled Exception / Bug -```json -{ - "project_slug": "myapp", - "type": "bug", - "title": "NullReferenceException in UserAuthService.cs line 42", - "description": "Triggered when user logs in without an active session object.", - "error_message": "NullReferenceException: Object reference not set to an instance of an object.", - "stack_trace": "at MyApp.Core.UserAuthService.ValidateToken(String token) in UserAuthService.cs:line 42\nat MyApp.Controllers.AuthController.Login() in AuthController.cs:line 18", - "build_version": "v1.4.2-dev", - "environment": "development", - "severity": "high", - "push_id": "push_wf_8912", - "target_agent": "agent:code-fixer-01", - "tags": "auth, security, csharp", - "created_by": "agent:watchdog-monitor" -} -``` - -### B. Submitting a Feature Request or Quick Reminder Idea (`severity: "idea"`) -```json -{ - "project_slug": "myapp", - "type": "feature_request", - "title": "Automatische Datenbank-Backups vor FTP Deployments", - "description": "Gedanke für später: Vor jedem FTP-Deployment automatisch mysqldump ausführen und im Server-Archiv ablegen.", - "build_version": "v1.6.0-roadmap", - "environment": "development", - "severity": "idea", - "push_id": "push_wf_9910", - "target_agent": "agent:db-optimizer", - "tags": "database, automation, backup", - "created_by": "agent:planner" -} -``` - -#### Response: -```json -{ - "status": "success", - "item_id": 4, - "is_new": true, - "occurrence_count": 1, - "error_hash": "e2c918a514d89a42f", - "type": "bug", - "environment": "development", - "push_id": "push_wf_8912", - "message": "New bug reported successfully." -} -``` - ---- - -## 📌 3. Managing Items (Fetching, Updating & Commenting) - -### Base Endpoint: `/api/bugtracker/v1/manage/index.php` - -Header: `Authorization: Bearer ` - -### A. Fetching Open Items Assigned to an Agent -```http -GET /api/bugtracker/v1/manage/index.php?project_slug=myapp&status=open&agent=agent:code-fixer-01 -``` - -### B. Updating Status & Details (`POST ?action=update`) -```json -{ - "id": 4, - "status": "in_progress", - "severity": "high", - "push_id": "push_wf_8912", - "target_agent": "agent:code-fixer-01", - "tags": "auth, fixed_pending_test", - "author": "agent:code-fixer-01" -} -``` - -### C. Appending Diagnostic Timeline Comments (`POST ?action=comment`) -```json -{ - "id": 4, - "comment": "Ursache identifiziert: $_SESSION['user'] war Null in line 42. Null-Check und Safe Navigation Operator wurden hinzugefügt.", - "action_taken": "code_patched", - "author": "agent:code-fixer-01" -} -``` - -### D. Marking as Resolved (`POST ?action=resolve`) -```json -{ - "id": 4, - "resolved_in_build": "v1.4.3-dev", - "resolution_notes": "Unit tests hinzugefügt und Null-Check in ValidateToken() integriert.", - "author": "agent:code-fixer-01" -} -``` - ---- - -## 💻 4. Code Implementation Examples for Agents - -### Python Example: Automatic Error Reporter Decorator -```python -import requests -import traceback -import sys - -DC_API_URL = "https://dc.mhdf.de/api/bugtracker/v1/report.php" -AGENT_TOKEN = "dc_sub_myapp_agent_live_001" - -def report_exception_to_dc(project_slug: str, exc: Exception, env: str = "production", push_id: str = None): - payload = { - "project_slug": project_slug, - "type": "bug", - "title": f"{type(exc).__name__}: {str(exc)}", - "error_message": str(exc), - "stack_trace": traceback.format_exc(), - "build_version": "v1.4.2", - "environment": env, - "severity": "high", - "push_id": push_id, - "created_by": "agent:python-runner" - } - headers = { - "Content-Type": "application/json", - "Authorization": f"Bearer {AGENT_TOKEN}" - } - try: - r = requests.post(DC_API_URL, json=payload, headers=headers, timeout=5) - return r.json() - except Exception as e: - print(f"Failed to report to Deployment Center: {e}", file=sys.stderr) -``` - -### cURL Example: Submit Feature Request / Idea ```bash -curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/report.php" \ - -H "Authorization: Bearer dc_sub_myapp_agent_live_001" \ +# 1. Arbeit holen und übernehmen +curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=next" \ + -H "Authorization: Bearer $DC_TOKEN" \ -H "Content-Type: application/json" \ - -d '{ - "project_slug": "myapp", - "type": "feature_request", - "title": "Erweiterte Filterung im WebUI Dashboard", - "severity": "idea", - "push_id": "push_task_1029", - "tags": "ui, dashboard", - "created_by": "agent:dev-assistant" - }' + -d '{"project_slug": "myapp", "limit": 1}' + +# 2. Zwischenstand festhalten +curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=comment&id=42" \ + -H "Authorization: Bearer $DC_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"comment": "Ursache gefunden.", "action_taken": "investigated"}' + +# 3. Abschließen +curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=resolve&id=42" \ + -H "Authorization: Bearer $DC_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"resolved_in_build": "v1.4.3", "resolution_notes": "Fix in AuthController."}' ``` ---- +## Weiterführend -## 🎯 Best Practices for Developer Agents - -1. **Always set `push_id`**: When executing automated pipelines, pass a `push_id` so all updates can be traced back to the specific execution run. -2. **Use `severity: "idea"` for thoughts**: When noticing potential refactorings or future improvements during coding, log them immediately as ideas. -3. **Comment before resolving**: Before calling `action=resolve`, write a diagnostic comment explaining **why** and **how** the fix was performed. +- **[Agenten-Handbuch](../public/docs/bugtracker.md)** — vollständige Referenz mit allen Feldern, Filtern, Fehlercodes und einem Python-Beispiel +- **[Agent-Prompt-Vorlage](./AGENT_PROMPT_TEMPLATE.md)** — Textbaustein für `CLAUDE.md` / `AGENTS.md` +- **[UPGRADE.md](./UPGRADE.md)** — Umstellungsschritte für bestehende Integrationen diff --git a/docs/UPDATESERVICE_INTEGRATION_GUIDE.md b/docs/UPDATESERVICE_INTEGRATION_GUIDE.md index 5c9b27a..bedf1c8 100644 --- a/docs/UPDATESERVICE_INTEGRATION_GUIDE.md +++ b/docs/UPDATESERVICE_INTEGRATION_GUIDE.md @@ -76,26 +76,62 @@ Das Packaging-Tool verpackt den `dotnet publish`-Output, berechnet Hashes, erzeu pack-and-deploy --project myapp --version 1.4.0 --channel prod --publish-dir ./bin/Release/net8.0/publish --changelog "Fehlerbehebungen und Performance-Optimierung" ``` -### Konfiguration (`packager.config.json`): +### Konfiguration (`packager.config.json`) + +> Diese Datei enthält Zugangsdaten und ist per `.gitignore` von der +> Versionskontrolle ausgeschlossen. Vorlage: `packager.config.example.json`. +> In der vorherigen Fassung standen die echten FTP-Zugangsdaten sowohl hier in +> der Anleitung als auch als Standardwerte im Quelltext von `Program.cs`. ```json { - "ftpHost": "www531.your-server.de", + "ftpHost": "ftp.example.com", "ftpPort": 21, - "ftpUser": "bergisnu_4", - "ftpPass": "o2#M*NN^5EsT", + "ftpUser": "ftp-user", + "ftpPass": "ftp-password", "ftpRemoteBaseDir": "/public_html/releases", "apiBaseUrl": "https://dc.mhdf.de", + "apiToken": "dc_sub_...", "excludePatterns": [ "*.pdb", "*.xml", "appsettings.Development.json", "*.log", - "logs/*" + "logs/**" ] } ``` +`apiToken` braucht das Recht `updateservice:publish`. Ohne Token baut und lädt +der Packager das Paket zwar hoch, meldet es aber nicht beim Deploymentcenter an +und beendet sich mit Rückgabewert 2. + +### Alternative: Umgebungsvariablen + +Für CI-Läufe, in denen keine Datei abgelegt werden soll — sie haben Vorrang vor +der Konfigurationsdatei: + +```bash +export DC_FTP_HOST=ftp.example.com +export DC_FTP_USER=ftp-user +export DC_FTP_PASS='...' +export DC_TOKEN='dc_sub_...' + +pack-and-deploy --project myapp --version 1.4.0 --channel prod \ + --publish-dir ./bin/Release/net8.0/publish +``` + +### Rückgabewerte + +| Wert | Bedeutung | +|---|---| +| `0` | Paket gebaut, hochgeladen und im Deploymentcenter registriert | +| `1` | Konfiguration unvollständig oder Publish-Verzeichnis fehlt — nichts wurde ausgeführt | +| `2` | Teilweise fehlgeschlagen: FTP-Upload oder Registrierung ging schief | + +Zuvor lieferte das Werkzeug in allen Fällen `0` und meldete „successfully +published", selbst wenn FTP-Upload und API-Aufruf beide fehlgeschlagen waren. + --- ## 4. Standalone UpdateAgent (`update-agent`) diff --git a/public/api/license/v1/index.php b/public/api/license/v1/index.php index 2051b3c..87c2efd 100644 --- a/public/api/license/v1/index.php +++ b/public/api/license/v1/index.php @@ -33,23 +33,30 @@ $action = resolveLicenseAction(); switch ($action) { + // WICHTIG: Die Lizenz-Endpunkte antworten bewusst OHNE den + // status/error-Umschlag der uebrigen API. Ihr Format ist ein bereits + // ausgerollter Vertrag: das Feld "status" auf oberster Ebene traegt den + // Lizenzzustand (valid, revoked, expired, not_found, activation_limit). + // Ein Umschlag mit status=success wuerde von jedem bestehenden Client als + // "nicht valid" interpretiert - saemtliche Lizenzen gaelten als ungueltig. + case 'validate': if (Http::method() !== 'POST') { Http::fail(405, 'method_not_allowed', 'Diese Aktion erwartet POST.'); } // Bewusst oeffentlich: Client-Anwendungen pruefen hier ihre Lizenz. // Die Antwort verraet nichts ueber fremde Lizenzen. - Http::ok(['result' => $service->validate(Http::body(), $ip)]); + Http::raw($service->validate(Http::body(), $ip)); case 'deactivate': if (Http::method() !== 'POST') { Http::fail(405, 'method_not_allowed', 'Diese Aktion erwartet POST.'); } ApiAuth::requireScope($db, 'license:deactivate'); - Http::ok(['result' => $service->deactivate(Http::body(), $ip)]); + Http::raw($service->deactivate(Http::body(), $ip)); case 'status': - Http::ok(['module' => 'license', 'version' => '2.0']); + Http::raw(['status' => 'ok', 'module' => 'license', 'version' => '2.0']); default: Http::fail(404, 'unknown_action', 'Endpunkt nicht gefunden.', null, [ diff --git a/src/Core/Http.php b/src/Core/Http.php index 3716bb3..22c238b 100644 --- a/src/Core/Http.php +++ b/src/Core/Http.php @@ -101,6 +101,31 @@ final class Http self::send(['status' => 'error', 'error' => $error], $status); } + /** + * Sendet eine Antwort ohne den status/error-Umschlag. + * + * Fuer Schnittstellen mit bereits ausgerollten Konsumenten, deren Format + * feststeht. Konkret die Lizenzpruefung: dort liegt das Feld "status" auf + * oberster Ebene und traegt den Lizenzzustand (valid, revoked, expired ...). + * Ein Umschlag mit status=success wuerde von jedem bestehenden Client als + * "nicht valid" gelesen - die Lizenz gaelte damit ueberall als ungueltig. + */ + public static function raw(array $payload, int $status = 200): void + { + if (!headers_sent()) { + http_response_code($status); + header('Content-Type: application/json; charset=utf-8'); + } + + $json = json_encode( + $payload, + JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT | JSON_INVALID_UTF8_SUBSTITUTE + ); + + echo $json === false ? '{"status":"error","message":"Antwort nicht kodierbar."}' : $json; + exit; + } + private static function send(array $payload, int $status): void { if (!headers_sent()) {