Meziantou.FrameworkDocumentLoader Class
Loads the documents of the navigations of the browsing contexts (e.g. the src of an iframe, or location.href = url), the style sheets of the @import rules and, when a BrowsingContextOptions.ScriptEngine is set, the external scripts and the HTTP requests of fetch() and XMLHttpRequest (see DocumentRequest.Destination). The library never fetches anything by itself: the application provides a loader, for instance the HTTP loader returned by DocumentLoader.Create, which decides which resources are available.
public abstract class DocumentLoaderRemarks
The library uses the following headers of the responses (DocumentResource.Headers); the other headers are ignored:
Accept-CH,Critical-CHandClear-Site-Data: the client hints that the origin of a top-level document opts into (seeBrowsingContextOptions.AcceptCHCache).Content-Type: the MIME type and the encoding of the resource.Content-Disposition: a navigation to anattachmentdoes not create a document.Content-DPR: the density of an image, which divides its natural size (as in Chromium).Last-Modified:Document.LastModified.Content-Language: the default language of the elements (e.g.:lang()): its first language.Document-Policy:expect-no-linked-resourcesdisables the speculative parsing of the document (seeBrowsingContextOptions.SpeculativeParsing).Content-Security-PolicyandContent-Security-Policy-Report-Only: the fetch directives of the subresources, thesandboxdirective and the Trusted Types directives (seeDocument.TrustedTypesDirectives), whose violations are reported (thesecuritypolicyviolationevent and thereport-urireports).Referrer-Policy: the referrer policy of the document, which determinesDocumentRequest.ReferrerandDocument.Referrer.Refresh: the declarative refresh of the document (seeBrowsingContextOptions.DeclarativeRefreshEnabled).X-Content-Type-Options:nosniffblocks the scripts whose MIME type is not a JavaScript MIME type, and the style sheets whose MIME type is nottext/css.
Constructors
| Name | Description |
|---|---|
| DocumentLoader() |
DocumentLoader()
protected DocumentLoader()No documentation is available.
Methods
| Name | Description |
|---|---|
| ConnectWebSocketAsync(DocumentRequest, CancellationToken) | Opens the connection of a WebSocket (https://fetch.spec.whatwg.org/#concept-websocket-connection-obtain) and sends its opening handshake (https://websockets.spec.whatwg.org/#concept-websocket-establish): an HTTP/1.1 GET request to DocumentRequest.Url (an http: or https: URL, the URL of the WebSocket with the http or https scheme) whose DocumentRequest.Mode is RequestMode.WebSocket, with the headers of DocumentRequest.Headers (Upgrade, Connection, Sec-WebSocket-Key, Sec-WebSocket-Version, Origin...) and the headers of the connection (Host, Cookie...). Returns the response, or null when the connection cannot be established (a network error). The library validates the handshake: the response must have the 101 status, its headers, and the connection on which the frames are read and written (DocumentResource.Connection). The loader must not follow the redirects. The default implementation returns null: the WebSockets cannot connect. |
| Create(HttpClient?) | Returns a loader that gets the documents with HTTP GET requests (only http: and https: URLs; the other URLs are network errors). It sends and stores the cookies of DocumentRequest.CookieJar, and follows the redirects itself (up to 20) when the client does not. |
| LoadAsync(DocumentRequest, CancellationToken) | Sends a request of the fetch algorithm of the library (https://fetch.spec.whatwg.org/#http-network-fetch): the document of a navigation, a subresource of a document (e.g. an external script, a style sheet, an image, see DocumentRequest.Destination), or a request of fetch() or XMLHttpRequest. The library follows the redirects (DocumentRequest.FollowRedirects is false: the loader returns the redirect responses) and checks each response (CORS, mixed content, content security policies...). Returns null when the resource is not available: the navigation then results in an error document with an opaque origin, as a network error (the error event is fired at a script or style element). An exception (including a cancellation) is also a network error. |
ConnectWebSocketAsync(DocumentRequest, CancellationToken)
BrowsingContextOptions.csOpens the connection of a WebSocket (https://fetch.spec.whatwg.org/#concept-websocket-connection-obtain) and sends its opening handshake (https://websockets.spec.whatwg.org/#concept-websocket-establish): an HTTP/1.1 GET request to DocumentRequest.Url (an http: or https: URL, the URL of the WebSocket with the http or https scheme) whose DocumentRequest.Mode is RequestMode.WebSocket, with the headers of DocumentRequest.Headers (Upgrade, Connection, Sec-WebSocket-Key, Sec-WebSocket-Version, Origin...) and the headers of the connection (Host, Cookie...). Returns the response, or null when the connection cannot be established (a network error). The library validates the handshake: the response must have the 101 status, its headers, and the connection on which the frames are read and written (DocumentResource.Connection). The loader must not follow the redirects. The default implementation returns null: the WebSockets cannot connect.
public virtual ValueTask<DocumentResource?> ConnectWebSocketAsync(DocumentRequest request, CancellationToken cancellationToken)Parameters
requestDocumentRequestcancellationTokenCancellationToken
Returns
Remarks
The method is called from a task of the DomEventLoop of the global object of the WebSocket (a window or a worker). cancellationToken is canceled when the WebSocket is closed (or its document is unloaded) before the connection is established. The library disposes the connection.
Create(HttpClient?)
BrowsingContextOptions.csReturns a loader that gets the documents with HTTP GET requests (only http: and https: URLs; the other URLs are network errors). It sends and stores the cookies of DocumentRequest.CookieJar, and follows the redirects itself (up to 20) when the client does not.
public static DocumentLoader Create(HttpClient? httpClient = null)Parameters
httpClientHttpClient?- The client used to send the requests. Its handler should not use its own cookies (
UseCookies = false) whenBrowsingContextOptions.CookieJaris set. When null, a shared loader is returned, whose client does not follow the redirects, does not use cookies, and decompresses the responses.
Returns
Remarks
Any URL a document navigates to is requested (e.g. the src of its iframes). Do not use this loader with untrusted documents when the requests can reach private resources (server-side request forgery): use a client whose handler filters the destinations, or a custom DocumentLoader.
LoadAsync(DocumentRequest, CancellationToken)
Sends a request of the fetch algorithm of the library (https://fetch.spec.whatwg.org/#http-network-fetch): the document of a navigation, a subresource of a document (e.g. an external script, a style sheet, an image, see DocumentRequest.Destination), or a request of fetch() or XMLHttpRequest. The library follows the redirects (DocumentRequest.FollowRedirects is false: the loader returns the redirect responses) and checks each response (CORS, mixed content, content security policies...). Returns null when the resource is not available: the navigation then results in an error document with an opaque origin, as a network error (the error event is fired at a script or style element). An exception (including a cancellation) is also a network error.
public abstract ValueTask<DocumentResource?> LoadAsync(DocumentRequest request, CancellationToken cancellationToken)Parameters
requestDocumentRequestcancellationTokenCancellationToken
Returns
Remarks
The method is called from a task of the DomEventLoop. When it completes asynchronously, the document is created by a task queued on completion (from any thread): use DomEventLoop.RunUntilIdleAsync to wait for it. cancellationToken is canceled when the navigation is aborted (e.g. another navigation of the browsing context starts, or the iframe is removed); the result of an aborted navigation is ignored.