blob: d9ef64d42c45e8af977fcd3e5ad1115d27c8fa0a [file] [log] [blame]
// 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_path.mojom";
import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "services/network/public/mojom/client_security_state.mojom";
import "services/network/public/mojom/cors.mojom";
import "services/network/public/mojom/cookie_access_observer.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/isolation_info.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 "services/network/public/mojom/web_bundle_handle.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::ReferrerPolicy. See its comments.
enum URLRequestReferrerPolicy {
kClearReferrerOnTransitionFromSecureToInsecure,
kReduceReferrerGranularityOnTransitionCrossOrigin,
kOriginOnlyOnTransitionCrossOrigin,
kNeverClearReferrer,
kOrigin,
kClearReferrerOnTransitionCrossOrigin,
kOriginClearOnTransitionFromSecureToInsecure,
kNoReferrer
};
// Options that may only be set on URLRequests passed to a URLLoaderFactory
// created with |is_trusted| set to true.
struct TrustedUrlRequestParams {
// If non-empty, this value will be used to set the SiteForCookies and
// NetworkIsolationKey used by the network request.
IsolationInfo isolation_info;
// 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;
// Observer which should be notified when this URLRequest reads or writes
// a cookie. If this is set to non-null, the observer passed to
// URLLoaderFactory will be ignored.
pending_remote<CookieAccessObserver>? cookie_observer;
// Specifies the security state of the client, for cases when the
// URLLoaderFactory is shared among multiple clients.
//
// This field is only used if no ClientSecurityState was specified in the
// URLLoaderFactoryParams passed to the factory. Otherwise, the value from
// the factory params is used unconditionally.
ClientSecurityState? client_security_state;
};
// Options that may only be set on URLRequests which are related to WebBundle.
struct WebBundleTokenParams {
// Unique token to identify a WebBundle.
mojo_base.mojom.UnguessableToken token;
// Handle for the WebBundle-related communication between the network process
// and the renderer. This is also used as a 'keep-alive' handle. We clean up
// the WebBundle data in the network process when the renderer-side endpoint
// is deleted.
pending_remote<WebBundleHandle>? web_bundle_handle;
};
// 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.
//
// Currently if a renderer is compromised an attacker could alter the
// SiteForCookies. This would allow the renderer to send cookies to a
// third-party context when it otherwise wouldn't be able to.
// https://crbug.com/1060631 will move the SFC computation into the browser
// process to prevent this.
// TODO(https://crbug.com/1060631): Remove this message after the fix is
// landed.
SiteForCookies site_for_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.
//
// For all requests initiated via web (both subresource requests and
// navigations), |request_initiator| should always be set to the origin of
// the frame (or worker) 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| should be omitted (i.e. set to base::nullopt) for
// browser-initiated requests (e.g. navigations initiated via omnibox or
// bookmarks, internal subresource requests like fetching the SafeBrowsing
// data, etc.). Various security features may treat browser-initiated
// requests in a special way - for example in such requests 1) the special
// `Sec-Fetch-Site: none` request header is sent, 2) http responses are not
// blocked based on their Cross-Origin-Resource-Policy header, etc.
//
// SECURITY NOTE: Factories with |process_id| set to |kBrowserProcessId| do
// not enforce |request_initiator_origin_lock| and instead rely on the
// factory user to ensure that a valid, non-nullopt |request_initiator| is
// provided. Failure to provide a correct, verified |request_initiator| may
// lead to bypasses of CORS, CORB, SameSite cookies and other HTTP security
// features. An untrustworthy process (e.g. a renderer or a utility process)
// should not be able to trigger or influence requests with a base::nullopt
// |request_initiator|).
//
// See also:
// - |isolated_world_origin|
// - URLLoaderFactoryParams::request_initiator_origin_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. If this request is sent to the network service, the header
// names stored in this member should be declared in
// NetworkContextParams::cors_exempt_header_list for the NetworkContext.
// Otherwise, the request will fail.
//
// *Warning*: Adding new headers to this list is strongly discouraged and
// should only be done for non-standard headers used for legacy reasons. 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, and 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;
// 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;
// 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
// ServiceWorkerContainerHost::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;
// A V8 stack id string describing where the request was initiated. DevTools
// can use this to display the initiator call stack when debugging a process
// that later intercepts the request, e.g., in a service worker fetch event
// handler.
string? devtools_stack_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;
// True for XHR, Fetch, and EventSource.
bool is_fetch_like_api;
// 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;
// Set for WebBundle related requests. See the comment of WebBundleTokenParams
// for details.
WebBundleTokenParams? web_bundle_token_params;
};
// URLRequestBody represents body (i.e. upload data) of a HTTP request.
// Typemapped to network::ResourceRequestBody
struct URLRequestBody {
// The body contents. DataElementChunkedDataPipe can be used in `elements`
// only if `elements` consists of one element.
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;
// Indicates whether fetch upload streaming is allowed/rejected over H/1.
// Even if this is false but there is a QUIC/H2 stream, the upload is allowed.
bool allow_http1_for_streaming_upload;
};
// Represents part of an upload body consisting of bytes.
struct DataElementBytes {
mojo_base.mojom.BigBuffer data;
};
// Represents part of an upload body consisting of (part of) a file.
struct DataElementFile {
mojo_base.mojom.FilePath path;
uint64 offset;
uint64 length;
mojo_base.mojom.Time expected_modification_time;
};
// Represents part of an upload body consisting of a data pipe with a known
// size.
struct DataElementDataPipe {
pending_remote<network.mojom.DataPipeGetter> data_pipe_getter;
};
// Represents part of an upload body consisting of a data pipe without a known
// size.
struct DataElementChunkedDataPipe {
pending_remote<network.mojom.ChunkedDataPipeGetter> data_pipe_getter;
// When true, a data pipe can be gotten from `chunked_data_pipe_getter` only
// once.
bool read_only_once;
};
// Represents part of an upload body.
union DataElement {
DataElementBytes bytes;
DataElementFile file;
DataElementDataPipe data_pipe;
DataElementChunkedDataPipe chunked_data_pipe;
};
// URLLoader is an interface for performing a single request to a URL.
//
// Destroying a URLLoader will cancel the associated request.
//
// A URLLoader is normally created and started using
// URLLoaderFactory::CreateLoaderAndStart(). The result of the load is
// communicated to the URLLoaderClient provided to that function.
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.
// |modified_cors_exempt_headers| can be used to modify |cors_exempt_headers|
// in the URLRequest. See NetworkContextParams::cors_exempt_header_list
// and URLRequest::cors_exempt_headers for details.
// 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,
network.mojom.HttpRequestHeaders modified_cors_exempt_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();
};
// Receives messages from a single URLLoader.
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;
};