Cadente

Cadente ist eine experimentelle verwaltete HTTP/1.1-Listener-Implementierung für Sisk. Sie dient als Ersatz für den Standard-System.Net.HttpListener und bietet mehr Kontrolle und Flexibilität, insbesondere auf Nicht‑Windows‑Plattformen.

Überblick #

Standardmäßig verwendet Sisk HttpListener (aus System.Net) als zugrunde liegende HTTP‑Server‑Engine. Während HttpListener unter Windows stabil und performant ist (wo es den Kernel‑Modus‑Treiber HTTP.sys nutzt), ist seine Implementierung unter Linux und macOS verwaltet und hatte historisch gesehen Einschränkungen, wie fehlende native SSL‑Unterstützung (die einen Reverse‑Proxy wie Nginx erfordert) und unterschiedliche Leistungsmerkmale.

Cadente zielt darauf ab, diese Probleme zu lösen, indem es einen vollständig verwalteten HTTP/1.1‑Server in C# bereitstellt. Seine Hauptziele sind:

• Native SSL Support: Funktioniert auf allen Plattformen, ohne externe Proxies oder komplexe Konfiguration zu benötigen.
• Cross-Platform Consistency: Identisches Verhalten unter Windows, Linux und macOS.
• Performance: Entwickelt, um eine Hochleistungs‑Alternative zum verwalteten HttpListener zu sein.
• Independence: Entkoppelt von System.Net.HttpListener, wodurch Sisk vor möglichen zukünftigen Deprecations oder fehlender Wartung dieser Komponente in .NET geschützt wird.

Installation #

Cadente ist als separates Paket verfügbar. Um es mit Sisk zu verwenden, benötigen Sie das Paket Sisk.Cadente.CoreEngine.

dotnet add package Sisk.Cadente.CoreEngine

Sisk.Cadente und Sisk.Cadente.CoreEngine zielen auf .NET 9 und .NET 10 ab. Sie können nicht in Projekten verwendet werden, die .NET 8 anvisieren, obwohl Sisk.HttpServer dies unterstützt.

Verwendung mit Sisk #

Um Cadente als HTTP‑Engine für Ihre Sisk‑Anwendung zu verwenden, müssen Sie den HttpServer so konfigurieren, dass er CadenteHttpServerEngine anstelle der Standard‑Engine nutzt.

CadenteHttpServerEngine adaptiert den Cadente-HttpHost an die von Sisk benötigte HttpServerEngine‑Abstraktion.

using Sisk.Core.Http;
using Sisk.Cadente.CoreEngine;

using var host = HttpServer.CreateBuilder()
    .UseEngine<CadenteHttpServerEngine>()
    .UseSsl(certificate: CertificateHelper.CreateTrustedDevelopmentCertificate("localhost"))
    .Build();

await host.StartAsync();

Wenn ein lauschernder Host mit SSL konfiguriert ist, gibt HttpServer.ListeningPrefixes seine Adressen mit dem https‑Schema aus. Sendet ein Client plain HTTP an einen mit SSL konfigurierten Port, antwortet Cadente mit einer 301 Moved Permanently‑Weiterleitung zur https‑Adresse desselben Hosts und Pfads.

Erweiterte Konfiguration #

Sie können die zugrunde liegende HttpHost‑Instanz anpassen, indem Sie dem Konstruktor von CadenteHttpServerEngine eine Setup‑Aktion übergeben. Dies ist nützlich, um Timeouts oder andere Low‑Level‑Einstellungen zu konfigurieren.

using var engine = new CadenteHttpServerEngine(host =>
{
    // Konfiguriere Lese-/Schreib-Timeouts des Clients
    host.TimeoutManager.ClientReadTimeout = TimeSpan.FromSeconds(30);
    host.TimeoutManager.ClientWriteTimeout = TimeSpan.FromSeconds(30);
});

Eigenständige Nutzung #

Obwohl Cadente hauptsächlich für Sisk konzipiert ist, kann es als eigenständiger HTTP‑Server verwendet werden (ähnlich wie HttpListener).

using Sisk.Cadente;

var host = new HttpHost(15000)
{
    Handler = new MyHostHandler()
};

host.Start();
Thread.Sleep(-1);

class MyHostHandler : HttpHostHandler
{
    public override async Task OnContextCreatedAsync(HttpHost host, HttpHostContext context)
    {
        context.Response.StatusCode = 200;

        using var stream = await context.Response.GetResponseStreamAsync(chunked: true);
        using var writer = new StreamWriter(stream);
        await writer.WriteLineAsync("Hello, world!");
    }
}

Wenn der Antwortkörper klein und bereits im Speicher ist, schreiben WriteInlineContent und WriteInlineContentAsync die Header und den Körper in einem einzigen Vorgang. Die Antwort muss einen Content-Length‑Header besitzen:

byte[] body = "Hello, world!"u8.ToArray();

context.Response.StatusCode = 200;
context.Response.Headers.Set(new HttpHeader("Content-Length", body.Length.ToString()));
await context.Response.WriteInlineContentAsync(body);

Anforderungsvalidierung #

Cadente prüft das Request‑Framing, bevor es den Handler erreicht. Seit Version 1.7 tut es Folgendes:

• unterstützt pipelined Anfragen bei Keep‑Alive‑Verbindungen;
• verwirft Anfragemethoden, die keine gültigen HTTP‑Tokens sind, und Anforderungsziele, die Bytes außerhalb des sichtbaren ASCII‑Bereichs (%x21-7E) enthalten;
• verwirft Anfragen, deren Transfer-Encoding etwas anderes als einen einzelnen chunked‑Wert ist, sowie Anfragen mit widersprüchlichen Content-Length‑Headern;
• antwortet mit 431 Request Header Fields Too Large und schließt die Verbindung, wenn die Request‑Zeile und Header 8 KB überschreiten.

Ungültige Anfragen werden mit einem Fehler beantwortet und die Verbindung wird geschlossen, ohne den Handler aufzurufen.