PushPromise Method

Pushes an associated resource to the client (PUSH_PROMISE plus a server-initiated push stream).

Syntax

function PushPromise(const aConnection: TsgcQUICServerConnection; const aPromisedPath: string; const aPushResponse: TsgcHTTP3Response): Boolean; virtual;

Parameters

Name	Type	Description
`aConnection`	`const TsgcQUICServerConnection`	QUIC connection the push is sent on. Pass the aConnection parameter received in OnH3Request.
`aPromisedPath`	`const string`	Path of the resource being promised, for example `/style.css`. The server synthesizes the promised request for you as a GET on this path.
`aPushResponse`	`const TsgcHTTP3Response`	Response delivered on the push stream. Set StatusCode, ContentType, optional Headers and the Data body before calling.

Return Value

True when the push was written to the connection. False when the client granted no push budget, that is, it never sent a MAX_PUSH_ID frame or the granted budget is already exhausted, and also when the connection is unknown or the push stream could not be opened. (Boolean)

Remarks

PushPromise implements HTTP/3 server push as described in RFC 9114 sections 4.6, 7.2.5 and 7.2.7. It performs two steps. First it writes a PUSH_PROMISE frame on the request stream that is currently being dispatched, carrying a synthesized GET header section for aPromisedPath (:method=GET, :scheme=https, :authority copied from the request being processed, and :path=aPromisedPath). Then it opens a server-initiated unidirectional QUIC stream of type 0x01, prefixes it with the assigned Push ID and delivers aPushResponse there as a HEADERS frame followed by a DATA frame when the response has a body.

PushPromise must be called from inside the OnH3Request handler. The PUSH_PROMISE frame has to travel on the request stream that triggered the push, and the server only tracks that stream while the event is being dispatched. Calling PushPromise outside OnH3Request has no correct stream to write the promise to.

Push IDs are assigned automatically and incremented on each successful call, so the application never manages them. A client controls how many resources may be pushed by sending MAX_PUSH_ID on its control stream. Until it does, the server has no budget and PushPromise returns False without sending anything, which is the correct behavior rather than an error. Always check the result instead of assuming the push was delivered.

Note that HTTP/3 server push is not implemented by current mainstream browsers, so this method is useful mainly with clients you control, such as TsgcHTTP3Client, which surfaces pushes through its OnPushPromise event.

This member is currently available in the Delphi/C++Builder implementation only.

Example


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;

Back to Methods