TsgcHTTP3Server › Methoden › PushPromise
Sendet eine zugehörige Ressource per Push an den Client (PUSH_PROMISE plus ein vom Server initiierter Push-Stream).
function PushPromise(const aConnection: TsgcQUICServerConnection; const aPromisedPath: string; const aPushResponse: TsgcHTTP3Response): Boolean; virtual;| Name | Typ | Beschreibung |
|---|---|---|
aConnection | const TsgcQUICServerConnection | QUIC-Verbindung, über die der Push gesendet wird. Übergeben Sie den Parameter aConnection, den Sie in OnH3Request erhalten haben. |
aPromisedPath | const string | Pfad der versprochenen Ressource, zum Beispiel /style.css. Der Server erzeugt die versprochene Anfrage für Sie als GET auf diesen Pfad. |
aPushResponse | const TsgcHTTP3Response | Antwort, die auf dem Push-Stream zugestellt wird. Setzen Sie StatusCode, ContentType, optionale Headers und den Data-Body vor dem Aufruf. |
True, wenn der Push in die Verbindung geschrieben wurde. False, wenn der Client kein Push-Budget gewährt hat, das heißt, er hat nie ein MAX_PUSH_ID-Frame gesendet oder das gewährte Budget ist bereits aufgebraucht, und auch, wenn die Verbindung unbekannt ist oder der Push-Stream nicht geöffnet werden konnte. (Boolean)
PushPromise implementiert HTTP/3 Server Push, wie in RFC 9114 Abschnitt 4.6, 7.2.5 und 7.2.7 beschrieben. Es führt zwei Schritte aus. Zuerst schreibt es einen PUSH_PROMISE-Frame auf den Anfrage-Stream, der gerade verarbeitet wird, und überträgt darin einen synthetisierten GET-Header-Abschnitt für aPromisedPath (:method=GET, :scheme=https, :authority aus der gerade verarbeiteten Anfrage kopiert, und :path=aPromisedPath). Anschließend öffnet es einen vom Server initiierten unidirektionalen QUIC-Stream vom Typ 0x01, stellt ihm die zugewiesene Push-ID voran und liefert dort aPushResponse als HEADERS-Frame, gefolgt von einem DATA-Frame, wenn die Antwort einen Body hat.
PushPromise muss innerhalb des OnH3Request-Handlers aufgerufen werden. Der PUSH_PROMISE-Frame muss über den Anfrage-Stream übertragen werden, der den Push ausgelöst hat, und der Server verfolgt diesen Stream nur, während das Ereignis ausgeliefert wird. Ein Aufruf von PushPromise außerhalb von OnH3Request hat keinen korrekten Stream, auf den das Promise geschrieben werden könnte.
Push-IDs werden automatisch vergeben und bei jedem erfolgreichen Aufruf hochgezählt, die Anwendung verwaltet sie also nie. Ein Client steuert, wie viele Ressourcen gepusht werden dürfen, indem er MAX_PUSH_ID auf seinem Control-Stream sendet. Solange er das nicht tut, hat der Server kein Budget und PushPromise gibt False zurück, ohne etwas zu senden, was das korrekte Verhalten und kein Fehler ist. Prüfen Sie stets das Ergebnis, anstatt anzunehmen, dass der Push zugestellt wurde.
Beachten Sie, dass HTTP/3-Server-Push von aktuellen gängigen Browsern nicht implementiert wird, sodass diese Methode hauptsächlich bei Clients nützlich ist, die Sie selbst kontrollieren, etwa TsgcHTTP3Client, der Pushes über sein OnPushPromise-Ereignis bereitstellt.
Dieses Mitglied ist derzeit nur in der Delphi/C++Builder-Implementierung verfügbar.
procedure OnH3RequestEvent(Sender: TObject; const aConnection:
TsgcQUICServerConnection; const aRequest: TsgcHTTP3Request;
const aResponse: TsgcHTTP3Response);
var
oPush: TsgcHTTP3Response;
begin
if aRequest.Path = '/index.html' then
begin
// push the stylesheet the page is going to ask for
oPush := TsgcHTTP3Response.Create;
try
oPush.StatusCode := 200;
oPush.ContentType := 'text/css';
oPush.Data := TEncoding.UTF8.GetBytes('body { margin: 0; }');
if not TsgcHTTP3Server(Sender).PushPromise(aConnection, '/style.css', oPush) then
Log('client granted no push budget, skipping push');
finally
oPush.Free;
end;
aResponse.StatusCode := 200;
aResponse.ContentType := 'text/html';
aResponse.Data := TEncoding.UTF8.GetBytes(
'<html><link rel="stylesheet" href="/style.css"></html>');
end
else
aResponse.StatusCode := 404;
end;