public/mojom/url_loader.mojom

// Copyright 2016 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module network.mojom;

import "mojo/public/mojom/base/big_buffer.mojom";
import "mojo/public/mojom/base/file.mojom";
import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "services/network/public/mojom/cors.mojom";
import "services/network/public/mojom/chunked_data_pipe_getter.mojom";
import "services/network/public/mojom/data_pipe_getter.mojom";
import "services/network/public/mojom/fetch_api.mojom";
import "services/network/public/mojom/http_request_headers.mojom";
import "services/network/public/mojom/network_isolation_key.mojom";
import "services/network/public/mojom/network_param.mojom";
import "services/network/public/mojom/site_for_cookies.mojom";
import "services/network/public/mojom/trust_tokens.mojom";
import "services/network/public/mojom/url_response_head.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";

[Native]
struct URLRequestRedirectInfo;

[Native]
struct CorsErrorStatus;

[Native]
struct URLLoaderCompletionStatus;

// This enum corresponds to net::RequestPriority. See its comments for details.
enum RequestPriority {
  kThrottled = 0,
  kIdle,
  kLowest,
  kLow,
  kMedium,
  kHighest
};

// This enum corresponds to net::URLRequest::ReferrerPolicy. See its comments.
enum URLRequestReferrerPolicy {
  kClearReferrerOnTransitionFromSecureToInsecure,
  kReduceReferrerGranularityOnTransitionCrossOrigin,
  kOriginOnlyOnTransitionCrossOrigin,
  kNeverClearReferrer,
  kOrigin,
  kClearReferrerOnTransitionCrossOrigin,
  kOriginClearOnTransitionFromSecureToInsecure,
  kNoReferrer
};

// Used for represents the type of the internal contents of
// network::DataElement.
enum DataElementType {
  kUnknown = -1,

  // Only used for Upload with Network Service as of now:
  kDataPipe,
  kChunkedDataPipe,
  kRawFile,

  // Used for Upload when Network Service is disabled:
  kBlob,
  kFile,

  // Commonly used in every case:
  kBytes,
};

// Used to determine if URLRequest::trusted_network_isolation_key should be
// updated on redirect.
enum UpdateNetworkIsolationKeyOnRedirect {
  kDoNotUpdate,

  // The updated network isolation key will take the redirected url's origin as
  // the top frame origin and frame origin.
  kUpdateTopFrameAndFrameOrigin,

  // The updated network isolation key will take the existing
  // NetworkIsolationKey's top frame origin and redirected url's origin as the
  // frame origin.
  kUpdateFrameOrigin
};

// Options that may only be set on URLRequests passed to a URLLoaderFactory
// created with |is_trusted| set to true.
struct TrustedUrlRequestParams {
  // This resource request will be keyed using |network_isolation_key| for
  // accessing shared network resources like the http cache.
  NetworkIsolationKey? network_isolation_key;

  // Whether or not the network isolation key needs to be recomputed on
  // redirects. Typically this is only done for navigations.
  UpdateNetworkIsolationKeyOnRedirect update_network_isolation_key_on_redirect;

  // Whether secure DNS should be disabled for the request.
  bool disable_secure_dns;

  // Whether a navigation is triggered with a user gesture.
  // Always true for navigations except the one triggered from a document
  // without user gesture. Used to determine the `Sec-Fetch-User` header.
  bool has_user_activation;
};

// Typemapped to network::ResourceRequest.
struct URLRequest {
  // The request method: GET, POST, etc.
  string method;

  // The absolute requested URL encoded in ASCII per the rules of RFC-2396.
  url.mojom.Url url;

  // Represents the first-party for the request, which may be checked by
  // the third-party cookie blocking policy or by some cookies. Leaving it empty
  // may lead to undesired cookie blocking. Third-party cookie blocking can be
  // bypassed by setting site_for_cookies = SiteForCookies::FromUrl(url), but
  // this should only be done if the fetch can be reasonably said to be done by
  // the same principal as what |url| represents.
  SiteForCookies site_for_cookies;

  // Boolean indicating whether SameSite cookies are allowed to be attached
  // to the request. It should be used as additional input to network side
  // checks.
  bool attach_same_site_cookies;

  // First-party URL redirect policy: During server redirects, the first-party
  // URL for cookies normally doesn't change. However, if this is true, the
  // the first-party URL should be updated to the URL on every redirect.
  bool update_first_party_url_on_redirect;

  // |request_initiator| indicates the origin initiating the resource request.
  //
  // |request_initiator| is null for browser-initiated requests (e.g.
  // navigations initiated via omnibox or bookmarks, internal subresource
  // requests like fetching the SafeBrowsing data, etc.).
  //
  // For all requests initiated via web (both subresource requests and
  // navigations), |request_initiator| is always set to the origin of the frame
  // that has initiated the request.  This is true even if the request might
  // have been initiated by an isolated world (e.g. from a content script of an
  // extension, with its own, separate origin).  This needs to be true even if
  // the request might be "proxied" in the browser process on behalf of a web
  // origin (e.g. as is the case for PaymentRequest API).
  //
  // |request_initiator| is consulted in a variety of security features,
  // including: calculating Sec-Fetch-Site request header, determining if the
  // request should be subject to CORS, determining if CORB and/or CORP should
  // block the response, determining if SameSite=strict cookies should be sent,
  // etc.
  //
  // See also:
  // - |isolated_world_origin|
  // - URLLoaderFactoryParams::request_initiator_site_lock
  url.mojom.Origin? request_initiator;

  // If this is a subresource request initiated from an isolated world (e.g.
  // from a content script of a Chrome Extension), then
  // |isolated_world_origin| indicates the origin of the isolated world.
  // Otherwise, |isolated_world_origin| is null.
  //
  // Example #1: XHR initiated from a content script of chrome-extension://foo
  // that was injected into a https://example.com web frame:
  // - |request_initiator| is "https://example.com"
  // - |isolated_world_origin| is "chrome-extension://foo"
  //
  // Example #2: XHR initiated from a Chrome Extension frame (e.g. from an
  // extension background page):
  // - |request_initiator| is "chrome-extension://foo"
  // - |isolated_world_origin| is null (this request is not associated with an
  //   isolated world)
  //
  // |isolated_world_origin| is consulted by OOR-CORS, to determine if this
  // request might need to be exempt from CORS, based on OriginAccessList.
  //
  // TODO(lukasza): https://crbug.com/936310: Attempt to remove
  // |isolated_world_origin| after removing the global/per-NetworkContext
  // OriginAccessList and replacing it with per-URLLoaderFactory
  // OriginAccessList.
  url.mojom.Origin? isolated_world_origin;

  // The referrer to use (may be empty).
  url.mojom.Url referrer;

  // The referrer policy to use.
  URLRequestReferrerPolicy referrer_policy;

  // Additional HTTP request headers.
  HttpRequestHeaders headers;

  // HTTP request headers that has been internally added. Some consumers want to
  // set additional HTTP headers, but such internal headers must be ignored by
  // CORS check (which run inside Network Service), so the values are stored
  // here (rather than in |headers|) and later merged into the |headers| after
  // CORS check.
  //
  // *Warning*: Adding new headers to this list is strongly discouraged. What
  // usually you need is to update the fetch spec, and add your custom headers
  // to the CORS-safelisted header so to pass proper CORS checks. 'Proxy-' or
  // 'Sec-' prefixes are also available. See cors::IsCORSSafelistedHeader and
  // cors::IsForbiddenHeader for details.
  //
  // You should ask Loading and CORS OWNERS when you need to add your own
  // headers to the list.
  HttpRequestHeaders cors_exempt_headers;  // See Note above before using.

  // net::URLRequest load flags.
  int32 load_flags;

  // What this resource load is for (main frame, sub-frame, sub-resource,
  // object).
  // Note: this is an enum of type blink::mojom::ResourceType.
  // TODO(jam): remove this from the struct since network service shouldn't know
  // about this.
  int32 resource_type;

  // The priority of this request determined by Blink.
  RequestPriority priority;

  // True if corresponding AppCache group should be reset.
  bool should_reset_appcache;

  // https://wicg.github.io/cors-rfc1918/#external-request
  // TODO(toyoshim): The browser should know better than renderers do.
  // This is used to plumb Blink decided information for legacy code path, but
  // eventually we should remove this.
  bool is_external_request;

  // A policy to decide if CORS-preflight fetch should be performed.
  CorsPreflightPolicy cors_preflight_policy;

  // True if the request originated from a Service Worker, e.g. due to a
  // fetch() in the Service Worker script.
  bool originated_from_service_worker;

  // The service worker mode that indicates which service workers should get
  // events for this request.
  // TODO(jam): remove this from the struct since network service shouldn't know
  // about this.
  bool skip_service_worker;

  // If true then the request continues even if it's blocked by CORB.
  bool corb_detachable = false;

  // TODO(lukasza): https://crbug.com/846339: Remove the field below and instead
  // make plugins use a separate URLoaderFactory. Note requests of this type are
  // only excluded if mode is kNoCors.
  bool corb_excluded = false;

  // https://fetch.spec.whatwg.org/#concept-request-mode
  // Used mainly by CORS handling (out-of-blink CORS), CORB, Service Worker.
  // CORS handling needs a proper origin (including a unique opaque origin).
  // Hence a request with kSameOrigin, kCors, or kCorsWithForcedPreflight should
  // have a non-null request_initiator.
  RequestMode mode;

  // https://fetch.spec.whatwg.org/#concept-request-credentials-mode
  // Controls whether credentials are attached to this request.
  // |kSameOrigin| credentials mode requires a non-null |request_initiator|.
  // When |mode| is |kNavigate|, this needs to be |kInclude|.
  CredentialsMode credentials_mode;

  // https://fetch.spec.whatwg.org/#concept-request-redirect-mode
  // Used mainly by CORS handling (out-of-blink CORS), Service Worker.
  // This member must be kFollow as long as |mode| is kNoCors.
  RedirectMode redirect_mode;

  // The integrity used in Fetch API.
  string fetch_integrity;

  // The request context passed to the ServiceWorker.
  // Note: this is an enum of type content::RequestContextType.
  // TODO(jam): remove this from the struct since network service shouldn't know
  // about this.
  int32 fetch_request_context_type;

  // https://fetch.spec.whatwg.org/#concept-request-destiantion
  RequestDestination destination;

  // Optional resource request body.
  URLRequestBody? request_body;

  // True if the request can work after the fetch group is terminated.
  // https://fetch.spec.whatwg.org/#request-keepalive-flag
  bool keepalive;

  // True if the request was user initiated.
  bool has_user_gesture;

  // TODO(mmenke): Investigate if enable_load_timing is safe to remove.
  //
  // True if load timing data should be collected for request.
  bool enable_load_timing;

  // True if upload progress should be available for request.
  bool enable_upload_progress;

  // True if login prompts for this request should be suppressed. Cached
  // credentials or default credentials may still be used for authentication.
  bool do_not_prompt_for_login;

  // The id of the RenderFrame. This may be:
  // - The render frame id for a) subresource requests from a document, b) the
  //   main resource request for a dedicated/shared worker if that worker was
  //   created by a frame.
  // - MSG_ROUTING_NONE for nested dedicated workers.
  // - MSG_ROUTING_NONE for subresource requests from a dedicated/shared worker.
  // - service_worker_route_id from EmbeddedWorkerStartParams for service worker
  //   main script requests and subresource requests.
  // - The frame tree node ID for navigation requests only. Please do not use
  //   frame tree node ID for other requests.
  int32 render_frame_id;

  // True if |frame_id| is the main frame of a RenderView.
  bool is_main_frame;

  // Note: this is an enum of type ui::PageTransition.
  // TODO(jam): remove this from the struct since network service shouldn't know
  // about this.
  int32 transition_type;

  // Whether to intercept headers to pass back to the renderer.
  // This also enables reporting of SSLInfo in URLLoaderClient's
  // OnResponseReceived and OnComplete, as well as invocation of
  // OnTransferSizeUpdated().
  bool report_raw_headers;

  // Whether or not to request a Preview version of the resource or let the
  // browser decide.
  // Note: this is an enum of type PreviewsState.
  // TODO(jam): remove this from the struct since network service shouldn't know
  // about this.
  int32 previews_state;

  // Whether or not this request (including redirects) should be upgraded to
  // HTTPS due to an Upgrade-Insecure-Requests requirement.
  bool upgrade_if_insecure;

  // True when the request is revalidating.
  // Some users, notably blink, has its own cache. This flag is set to exempt
  // some CORS logic for a revalidating request.
  bool is_revalidating;

  // The profile ID of network conditions to throttle the network request.
  mojo_base.mojom.UnguessableToken? throttling_profile_id;

  // See https://fetch.spec.whatwg.org/#concept-request-window
  //
  // This is an opaque id of the original requestor of the resource, which might
  // be different to the current requestor which is |render_frame_id|. For
  // example, if a navigation for window "abc" is intercepted by a service
  // worker, which re-issues the request via fetch, the re-issued request has
  // |render_frame_id| of MSG_ROUTING_NONE (the service worker) and |window_id|
  // of "abc". This is used for, e.g., client certificate selection. It's
  // important that this id be unguessable so renderers cannot impersonate
  // other renderers.
  //
  // This may be empty when the original requestor is the current requestor or
  // is not a window. When it's empty, use |render_frame_id| instead. In
  // practical terms, it's empty for requests that didn't go through a service
  // worker, or if the original requestor is not a window. When the request
  // goes through a service worker, the id is
  // ServiceWorkerProviderHost::fetch_request_window_id.
  mojo_base.mojom.UnguessableToken? fetch_window_id;

  // The ID that DevTools uses to track network requests. It is generated in the
  // renderer process and is only present when DevTools is enabled in the
  // renderer.
  string? devtools_request_id;

  // True for prefetch requests when SignedExchangePrefetchCacheForNavigations
  // feature is enabled by flags or SignedExchangeSubresourcePrefetch feature is
  // enabled by flags, or OriginTrial. TODO(horo): Remove this when these
  // features are enabled by default.
  bool is_signed_exchange_prefetch_cache_enabled;

  // If set, the network service will attempt to retrieve the appropriate origin
  // policy, if necessary, and attach it to the ResourceResponseHead.
  // Spec: https://wicg.github.io/origin-policy/
  bool obey_origin_policy;

  // Setting these from an untrusted URLLoader will cause the request to fail.
  TrustedUrlRequestParams? trusted_params;

  // Set for recursive prefetch requests originating from cross-origin
  // prefetches. These requests take the form of `Link: rel=preload` HTTP
  // response headers. For more information on these requests see
  // https://github.com/w3c/resource-hints/issues/77.
  mojo_base.mojom.UnguessableToken? recursive_prefetch_token;

  // Set when Trust Tokens (https://github.com/wicg/trust-token-api) is enabled
  // and the request has set the trustToken Fetch parameter, denoting that it
  // wishes to execute a Trust Tokens protocol operation.
  TrustTokenParams? trust_token_params;
};

// URLRequestBody represents body (i.e. upload data) of a HTTP request.
// Typemapped to network::ResourceRequestBody
struct URLRequestBody {
  // Store upload bodies
  array<DataElement> elements;

  // Identifies a particular upload instance, which is used by the cache to
  // formulate a cache key.
  uint64 identifier;

  // Indicates whether the post data contains sensitive information like
  // passwords.
  bool contains_sensitive_info;
};

// Represents part of an upload body. This could be either one of bytes, file or
// a data pipe.
// Typemapped to network::DataElement
struct DataElement {
  DataElementType type;

  // For kBytes.
  array<uint8> buf;
  // For kFile and kRawFile
  mojo_base.mojom.FilePath path;
  // For kRawFile
  mojo_base.mojom.File? file;
  // For kBlob
  // TODO(richard.li): Deprecate this once NetworkService is fully shipped.
  string? blob_uuid;
  // For kDataPipe
  pending_remote<network.mojom.DataPipeGetter>? data_pipe_getter;
  // For kChunkedDataPipe
  pending_remote<network.mojom.ChunkedDataPipeGetter>? chunked_data_pipe_getter;

  uint64 offset;
  uint64 length;
  mojo_base.mojom.Time expected_modification_time;
};

// Destroying a URLLoader will cancel the associated request.
interface URLLoader {
  // If a disconnection is initiated by the client side, it may send the
  // following disconnection reason, along with an application-defined string
  // description, to notify the service side.
  const uint32 kClientDisconnectReason = 1;

  // If the associated request has |auto_follow_redirects| set to false, then
  // upon receiving an URLResponse with a non-NULL |redirect_url| field,
  // |FollowRedirect| may be called to load the URL indicated by the redirect.
  // |removed_headers| can be used to remove existing headers for the redirect.
  // This parameter is before |modified_headers| since removing headers is
  // applied first in the URLLoader::FollowRedirect().  |modified_headers| can
  // be used to add or override existing headers for the redirect. If |new_url|
  // is specified, then the request will be made to it instead of the redirected
  // URL. Note: it has to be in the same origin as the redirected URL, and this
  // is only supported when the network service is enabled.
  FollowRedirect(array<string> removed_headers,
                 network.mojom.HttpRequestHeaders modified_headers,
                 url.mojom.Url? new_url);

  // Sets the request priority.
  // |intra_priority_value| is a lesser priority which is used to prioritize
  // requests within a given priority level. If -1 is passed, the existing
  // intra priority value is maintained.
  SetPriority(RequestPriority priority, int32 intra_priority_value);

  // If the resource is being fetched from the network,
  // PauseReadingBodyFromNet() pauses fetching the response body. It is okay to
  // call this method before fetching the body starts, too.
  // ResumeReadingBodyFromNet() resumes fetching the body if it has been paused.
  //
  // Note that PauseReadingBodyFromNet() is asynchronous and only gurantees to
  // pause if the response body is fetched from the network. This means:
  // - any data in flight before PauseReadingBodyFromNet() is processed will
  //   still be passed to the client data pipe.
  // - a response body not from the network, e.g. from blob, may not be paused
  //   at all.
  //
  // Redundant calls to these methods are ingored. It is not required to match
  // pause and resume calls. It is not an error to resume a non-paused request,
  // or pause a request multiple times.
  PauseReadingBodyFromNet();
  ResumeReadingBodyFromNet();
};

interface URLLoaderClient {
  // Called when the response head is received.
  OnReceiveResponse(URLResponseHead head);

  // Called when the request has been redirected. The receiver is expected to
  // call FollowRedirect or cancel the request.
  OnReceiveRedirect(URLRequestRedirectInfo redirect_info, URLResponseHead head);

  // Called when the service made some progress on the file upload. This is
  // called only when the request has an upload data.
  // The implementation should call the response closure when the client is
  // ready to receive the next upload progress.
  OnUploadProgress(int64 current_position, int64 total_size) => ();

  // Called when cached metadata from a resource request is ready.
  OnReceiveCachedMetadata(mojo_base.mojom.BigBuffer data);

  // Called when the transfer size is updated. This is only called if
  // |report_raw_headers| is set or the renderer has permission to read the
  // request. The transfer size is the length of the response (including both
  // headers and the body) over the network. |transfer_size_diff| is the
  // difference from the value previously reported one (including the one in
  // OnReceiveResponse and OnReceiveRedirect). It must be positive.
  // TODO(yhirano): Dispatch this notification even when |download_to_file| is
  // set.
  // TODO(yhirano): Consider using an unsigned type.
  // TODO(rajendrant): Consider reporting the transfer size directly to browser
  // process from net service, and not pass it via renderer process. This can be
  // done after the upcoming network servicification work.
  OnTransferSizeUpdated(int32 transfer_size_diff);

  // Called when the loader starts loading response body. This is called after
  // OnReceiveResponse is called.
  OnStartLoadingResponseBody(handle<data_pipe_consumer> body);

  // Called when the loading completes. No notification will be dispatched for
  // this client after this message arrives. |status| has its |ssl_info| field
  // set only when |kURLLoadOptionsSendSSLInfoForCertificateError| was set.
  OnComplete(URLLoaderCompletionStatus status);
};

// Convenient struct that groups the two communication endpoints most
// implementations of URLLoaderClient use to communicate with their URLLoader.
struct URLLoaderClientEndpoints {
  pending_remote<URLLoader> url_loader;
  pending_receiver<URLLoaderClient> url_loader_client;
};