extensions/common/api/declarative_net_request.idl - chromium/src.git - Git at Google

 // Copyright 2017 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.

 // The <code>chrome.declarativeNetRequest</code> API is used to block or modify
 // network requests by specifying declarative rules.
 [generate_error_messages]
 namespace declarativeNetRequest {
   // This describes the resource type of the network request.
   enum ResourceType {
     main_frame,
     sub_frame,
     stylesheet,
     script,
     image,
     font,
     object,
     xmlhttprequest,
     ping,
     csp_report,
     media,
     websocket,
     other
   };

   // This describes whether the request is first or third party to the frame in
   // which it originated. A request is said to be first party if it has the same
   // domain (eTLD+1) as the frame in which the request originated.
   enum DomainType {
     // The network request is first party to the frame in which it originated.
     firstParty,
     // The network request is third party to the frame in which it originated.
     thirdParty
   };

   // This describes the headers which can be removed from the network request.
   enum RemoveHeaderType {
     cookie,
     referer,
     setCookie
   };

   // Describes the kind of action to take if a given RuleCondition matches.
   enum RuleActionType {
     // Block the network request.
     block,
     // Redirect the network request.
     redirect,
     // Allow the network request. The request won't be intercepted if there is
     // an allow rule which matches it.
     allow,
     // Upgrade the network request url's scheme to https if the request is http
     // or ftp.
     upgradeScheme,
     // Remove request/response headers from the network request.
     removeHeaders
   };

   // Represents a query key-value pair.
   dictionary QueryKeyValue {
     DOMString key;
     DOMString value;
   };

   // Describes modification to the url query.
   dictionary QueryTransform {
      // The list of query keys to be removed.
      DOMString[]? removeParams;
      // The list of query key-value pairs to be added or replaced.
      QueryKeyValue[]? addOrReplaceParams;
   };

   // Describes modification to various url components.
   dictionary URLTransform {
      // The new scheme for the request. Allowed values are "http", "https",
      // "ftp" and "chrome-extension".
      DOMString? scheme;

      // The new host for the request.
      DOMString? host;

      // The new port for the request. If empty, the existing port is cleared.
      DOMString? port;

      // The new path for the request. If empty, the existing path is cleared.
      DOMString? path;

      // The new query for the request. Should be either empty, in which case the
      // existing query is cleared; or should begin with '?'.
      DOMString? query;

      // Add, remove or replace query key-value pairs.
      QueryTransform? queryTransform;

      // The new fragment for the request. Should be either empty, in which case
      // the existing fragment is cleared; or should begin with '#'.
      DOMString? fragment;

      // The new username for the request.
      DOMString? username;

      // The new password for the request.
      DOMString? password;
   };

   dictionary Redirect {
      // Path relative to the extension directory. Should start with '/'.
      DOMString? extensionPath;
      // Url transformations to perform.
      URLTransform? transform;
      // The redirect url. Redirects to JavaScript urls are not allowed.
      DOMString? url;
   };

   dictionary RuleCondition {

     // The pattern which is matched against the network request url.
     // Supported constructs:
     //
     // <b>'*'</b>  : Wildcard: Matches any number of characters.
     //
     // <b>'|'</b>  : Left/right anchor: If used at either end of the pattern,
     //               specifies the beginning/end of the url respectively.
     //
     // <b>'||'</b> : Domain name anchor: If used at the beginning of the pattern,
     //               specifies the start of a (sub-)domain of the URL.
     //
     // <b>'^'</b>  : Separator character: This matches anything except a letter, a
     //               digit or one of the following: _ - . %. This can also match
     //               the end of the URL.
     //
     // Therefore <code>urlFilter</code> is composed of the following parts:
     // (optional Left/Domain name anchor) + pattern + (optional Right anchor).
     //
     // If omitted, all urls are matched. An empty string is not allowed.
     //
     // Note: The <code>urlFilter</code> must be composed of only ASCII
     // characters. This is matched against a url where the host is encoded in
     // the punycode format (in case of internationalized domains) and any other
     // non-ascii characters are url encoded in utf-8.
     // For example, when the request url is http://abc.рф?q=ф, the
     // <code>urlFilter</code> will be matched against the url
     // http://abc.xn--p1ai/?q=%D1%84.
     DOMString? urlFilter;

     // Whether the <code>urlFilter</code> is case sensitive. Default is true.
     boolean? isUrlFilterCaseSensitive;

     // The rule will only match network requests originating from the list of
     // <code>domains</code>. If the list is omitted, the rule is applied to
     // requests from all domains. An empty list is not allowed.
     //
     // Note: sub-domains like "a.example.com" are also allowed.
     // The entries must consist of only ascii characters. Use punycode encoding
     // for internationalized domains.
     DOMString[]? domains;

     // The rule will not match network requests originating from the list of
     // <code> excludedDomains</code>. If the list is empty or omitted, no domains
     // are excluded. This takes precedence over <code> domains</code>.
     //
     // Note: sub-domains like "a.example.com" are also allowed.
     // The entries must consist of only ascii characters. Use punycode encoding
     // for internationalized domains.
     DOMString[]? excludedDomains;

     // List of resource types which the rule can match. An empty list is not
     // allowed.
     ResourceType[]? resourceTypes;

     // List of resource types which the rule won't match. Only one of
     // <code>resourceTypes</code> and <code>excludedResourceTypes</code> should
     // be specified. If neither of them is specified, all resource types except
     // "main_frame" are blocked.
     ResourceType[]? excludedResourceTypes;

     // Specifies whether the network request is first-party or third-party to
     // the domain from which it originated. If omitted, all requests are
     // accepted.
     DomainType? domainType;
   };

   dictionary RuleAction {
     // The type of action to perform.
     RuleActionType type;

     // Describes how the redirect should be performed. Only valid for redirect
     // rules.
     Redirect? redirect;

     // The headers to remove from the request. Only valid if RuleActionType is
     // "removeHeaders".
     RemoveHeaderType[]? removeHeadersList;
   };

   dictionary Rule {
     // An id which uniquely identifies a rule. Mandatory and should be >= 1.
     long id;

     // Rule priority. Mandatory for redirect and upgradeScheme rules and should
     // be >= 1. This is used to break ties between multiple matching redirect
     // rules.
     long? priority;

     // The condition under which this rule is triggered.
     RuleCondition condition;

     // The action to take if this rule is matched.
     RuleAction action;
   };

   [nodoc]
   enum SourceType {
     // The rule is specified in a JSON file within the extension's package.
     manifest,
     // The rule is a dynamic rule added by the extension using
     // $(ref:declarativeNetRequest.addDynamicRules).
     dynamic
   };

   [nodoc]
   dictionary MatchedRule {
     // A matching rule's ID.
     long ruleId;

     // The source of the rule.
     SourceType sourceType;
   };

   [nodoc]
   dictionary MatchedRuleInfo {
     MatchedRule rule;

     // The time the rule was matched. Timestamps will correspond to the
     // Javascript convention for times, i.e. number of milliseconds since the
     // epoch.
     double timeStamp;

     // The tabId of the tab from which the request originated if the tab is
     // still active. Else -1.
     long tabId;
   };

   [nodoc]
   dictionary MatchedRulesFilter {
     // If specified, only matches rules for the given tab.
     long? tabId;

     // If specified, only matches rules after the given timestamp.
     long? minTimeStamp;
   };

   [nodoc]
   dictionary RulesMatchedDetails {
      // Rules matching the given filter.
      MatchedRuleInfo[] rulesMatchedInfo;
   };

   callback EmptyCallback = void();
   callback GetAllowedPagesCallback = void(DOMString[] result);
   callback GetRulesCallback = void(Rule[] rules);
   callback GetMatchedRulesCallback = void(RulesMatchedDetails details);

   interface Functions {

     // Adds <code>rules</code> to the current set of dynamic rules for the
     // extension. These rules are persisted across browser sessions.
     // Note: <a href="#property-MAX_NUMBER_OF_DYNAMIC_RULES">
     // MAX_NUMBER_OF_DYNAMIC_RULES</a> is the maximum number of dynamic rules an
     // extension can add.
     // |rules|: The rules to add.
     // |callback|: Called once the given <code>rules</code> are added. In case
     // of an error, $(ref:runtime.lastError) will be set to denote the error
     // message and no rules will be added. This can happen for multiple reasons,
     // such as invalid rule format, duplicate rule ID, rule count limit
     // exceeded, internal errors, and others.
     static void addDynamicRules(Rule[] rules, optional EmptyCallback callback);

     // Removes rules corresponding to <code>rule_ids</code> from the current set
     // of dynamic rules for the extension. Any <code>rule_ids</code> not already
     // present are ignored. Note that static rules specified as part of the
     // extension package can not be removed using this function.
     // |rule_ids|: The IDs of dynamic rules to remove.
     // |callback|: Called once the rules are removed. In case of an error,
     // $(ref:runtime.lastError) will be set to denote the error message and no
     // rules will be removed. This may happen due to internal errors.
     static void removeDynamicRules(long[] rule_ids,
         optional EmptyCallback callback);

     // Returns the current set of dynamic rules for the extension.
     // |callback|: Called with the set of dynamic rules. An error might be
     // raised in case of transient internal errors.
     static void getDynamicRules(GetRulesCallback callback);

     // Adds <code>page_patterns</code> to the set of allowed pages. Requests
     // from these pages are not intercepted by the extension. These are
     // persisted across browser sessions.
     // Note: <a href="#property-MAX_NUMBER_OF_ALLOWED_PAGES">
     // MAX_NUMBER_OF_ALLOWED_PAGES</a> is the maximum number of
     // allowed page an extension can add. Also, adding page patterns is
     // atomic. In case of an error, no page pattern is added.
     // |page_patterns| : Array of
     // <a href="/extensions/match_patterns">match patterns</a> which are to be
     // allowed.
     // |callback|: Called after the <code>page_patterns</code> have been added.
     // $(ref:runtime.lastError) will be set in case of an error, for example if
     // an invalid page pattern is specified or the extension exceeded the
     // maximum page patterns limit.
     static void addAllowedPages(DOMString[] page_patterns,
         optional EmptyCallback callback);

     // Removes <code>page_patterns</code> from the set of allowed pages.
     // Note: Removing page patterns is atomic. In case of an error, no page
     // pattern is removed.
     // |page_patterns| : Array of
     // <a href="/extensions/match_patterns">match patterns</a> which are to be
     // removed.
     // |callback|: Called after the <code>page_patterns</code> have been
     // removed. $(ref:runtime.lastError) will be set in case of an error.
     static void removeAllowedPages(DOMString[] page_patterns,
         optional EmptyCallback callback);

     // Returns the current set of allowed pages.
     // |callback|: Called with the set of currently allowed pages.
     static void getAllowedPages(GetAllowedPagesCallback callback);

     // TODO(crbug.com/967942): Add documentation once implementation is
     // complete.
     [nodoc]
     static void getMatchedRules(optional MatchedRulesFilter filter,
         GetMatchedRulesCallback callback);

     // Sets whether to automatically badge extension's icon to the matched
     // action count for a tab. This preference is persisted across sessions and
     // is false by default.
     // TODO(crbug.com/973211): Add documentation once implementation is
     // complete.
     [nodoc]
     static void setActionCountAsBadgeText(boolean enable);
   };

   interface Properties {
     // The maximum number of allowed pages that an extension can add.
     [value=100] static long MAX_NUMBER_OF_ALLOWED_PAGES();

     // The maximum number of rules that an extension can specify in the rule
     // resources file. Any excess rules will be ignored and an install warning
     // will be raised.
     [value=30000] static long MAX_NUMBER_OF_RULES();

     // The maximum number of dynamic rules that an extension can add.
     [value=5000] static long MAX_NUMBER_OF_DYNAMIC_RULES();
   };
 };
	// Copyright 2017 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.

	// The <code>chrome.declarativeNetRequest</code> API is used to block or modify
	// network requests by specifying declarative rules.
	[generate_error_messages]
	namespace declarativeNetRequest {
	// This describes the resource type of the network request.
	enum ResourceType {
	main_frame,
	sub_frame,
	stylesheet,
	script,
	image,
	font,
	object,
	xmlhttprequest,
	ping,
	csp_report,
	media,
	websocket,
	other
	};

	// This describes whether the request is first or third party to the frame in
	// which it originated. A request is said to be first party if it has the same
	// domain (eTLD+1) as the frame in which the request originated.
	enum DomainType {
	// The network request is first party to the frame in which it originated.
	firstParty,
	// The network request is third party to the frame in which it originated.
	thirdParty
	};

	// This describes the headers which can be removed from the network request.
	enum RemoveHeaderType {
	cookie,
	referer,
	setCookie
	};

	// Describes the kind of action to take if a given RuleCondition matches.
	enum RuleActionType {
	// Block the network request.
	block,
	// Redirect the network request.
	redirect,
	// Allow the network request. The request won't be intercepted if there is
	// an allow rule which matches it.
	allow,
	// Upgrade the network request url's scheme to https if the request is http
	// or ftp.
	upgradeScheme,
	// Remove request/response headers from the network request.
	removeHeaders
	};

	// Represents a query key-value pair.
	dictionary QueryKeyValue {
	DOMString key;
	DOMString value;
	};

	// Describes modification to the url query.
	dictionary QueryTransform {
	// The list of query keys to be removed.
	DOMString[]? removeParams;
	// The list of query key-value pairs to be added or replaced.
	QueryKeyValue[]? addOrReplaceParams;
	};

	// Describes modification to various url components.
	dictionary URLTransform {
	// The new scheme for the request. Allowed values are "http", "https",
	// "ftp" and "chrome-extension".
	DOMString? scheme;

	// The new host for the request.
	DOMString? host;

	// The new port for the request. If empty, the existing port is cleared.
	DOMString? port;

	// The new path for the request. If empty, the existing path is cleared.
	DOMString? path;

	// The new query for the request. Should be either empty, in which case the
	// existing query is cleared; or should begin with '?'.
	DOMString? query;

	// Add, remove or replace query key-value pairs.
	QueryTransform? queryTransform;

	// The new fragment for the request. Should be either empty, in which case
	// the existing fragment is cleared; or should begin with '#'.
	DOMString? fragment;

	// The new username for the request.
	DOMString? username;

	// The new password for the request.
	DOMString? password;
	};

	dictionary Redirect {
	// Path relative to the extension directory. Should start with '/'.
	DOMString? extensionPath;
	// Url transformations to perform.
	URLTransform? transform;
	// The redirect url. Redirects to JavaScript urls are not allowed.
	DOMString? url;
	};

	dictionary RuleCondition {

	// The pattern which is matched against the network request url.
	// Supported constructs:
	//
	// <b>'*'</b> : Wildcard: Matches any number of characters.
	//
	// <b>'\|'</b> : Left/right anchor: If used at either end of the pattern,
	// specifies the beginning/end of the url respectively.
	//
	// <b>'\|\|'</b> : Domain name anchor: If used at the beginning of the pattern,
	// specifies the start of a (sub-)domain of the URL.
	//
	// <b>'^'</b> : Separator character: This matches anything except a letter, a
	// digit or one of the following: _ - . %. This can also match
	// the end of the URL.
	//
	// Therefore <code>urlFilter</code> is composed of the following parts:
	// (optional Left/Domain name anchor) + pattern + (optional Right anchor).
	//
	// If omitted, all urls are matched. An empty string is not allowed.
	//
	// Note: The <code>urlFilter</code> must be composed of only ASCII
	// characters. This is matched against a url where the host is encoded in
	// the punycode format (in case of internationalized domains) and any other
	// non-ascii characters are url encoded in utf-8.
	// For example, when the request url is http://abc.рф?q=ф, the
	// <code>urlFilter</code> will be matched against the url
	// http://abc.xn--p1ai/?q=%D1%84.
	DOMString? urlFilter;

	// Whether the <code>urlFilter</code> is case sensitive. Default is true.
	boolean? isUrlFilterCaseSensitive;

	// The rule will only match network requests originating from the list of
	// <code>domains</code>. If the list is omitted, the rule is applied to
	// requests from all domains. An empty list is not allowed.
	//
	// Note: sub-domains like "a.example.com" are also allowed.
	// The entries must consist of only ascii characters. Use punycode encoding
	// for internationalized domains.
	DOMString[]? domains;

	// The rule will not match network requests originating from the list of
	// <code> excludedDomains</code>. If the list is empty or omitted, no domains
	// are excluded. This takes precedence over <code> domains</code>.
	//
	// Note: sub-domains like "a.example.com" are also allowed.
	// The entries must consist of only ascii characters. Use punycode encoding
	// for internationalized domains.
	DOMString[]? excludedDomains;

	// List of resource types which the rule can match. An empty list is not
	// allowed.
	ResourceType[]? resourceTypes;

	// List of resource types which the rule won't match. Only one of
	// <code>resourceTypes</code> and <code>excludedResourceTypes</code> should
	// be specified. If neither of them is specified, all resource types except
	// "main_frame" are blocked.
	ResourceType[]? excludedResourceTypes;

	// Specifies whether the network request is first-party or third-party to
	// the domain from which it originated. If omitted, all requests are
	// accepted.
	DomainType? domainType;
	};

	dictionary RuleAction {
	// The type of action to perform.
	RuleActionType type;

	// Describes how the redirect should be performed. Only valid for redirect
	// rules.
	Redirect? redirect;

	// The headers to remove from the request. Only valid if RuleActionType is
	// "removeHeaders".
	RemoveHeaderType[]? removeHeadersList;
	};

	dictionary Rule {
	// An id which uniquely identifies a rule. Mandatory and should be >= 1.
	long id;

	// Rule priority. Mandatory for redirect and upgradeScheme rules and should
	// be >= 1. This is used to break ties between multiple matching redirect
	// rules.
	long? priority;

	// The condition under which this rule is triggered.
	RuleCondition condition;

	// The action to take if this rule is matched.
	RuleAction action;
	};

	[nodoc]
	enum SourceType {
	// The rule is specified in a JSON file within the extension's package.
	manifest,
	// The rule is a dynamic rule added by the extension using
	// $(ref:declarativeNetRequest.addDynamicRules).
	dynamic
	};

	[nodoc]
	dictionary MatchedRule {
	// A matching rule's ID.
	long ruleId;

	// The source of the rule.
	SourceType sourceType;
	};

	[nodoc]
	dictionary MatchedRuleInfo {
	MatchedRule rule;

	// The time the rule was matched. Timestamps will correspond to the
	// Javascript convention for times, i.e. number of milliseconds since the
	// epoch.
	double timeStamp;

	// The tabId of the tab from which the request originated if the tab is
	// still active. Else -1.
	long tabId;
	};

	[nodoc]
	dictionary MatchedRulesFilter {
	// If specified, only matches rules for the given tab.
	long? tabId;

	// If specified, only matches rules after the given timestamp.
	long? minTimeStamp;
	};

	[nodoc]
	dictionary RulesMatchedDetails {
	// Rules matching the given filter.
	MatchedRuleInfo[] rulesMatchedInfo;
	};

	callback EmptyCallback = void();
	callback GetAllowedPagesCallback = void(DOMString[] result);
	callback GetRulesCallback = void(Rule[] rules);
	callback GetMatchedRulesCallback = void(RulesMatchedDetails details);

	interface Functions {

	// Adds <code>rules</code> to the current set of dynamic rules for the
	// extension. These rules are persisted across browser sessions.
	// Note: <a href="#property-MAX_NUMBER_OF_DYNAMIC_RULES">
	// MAX_NUMBER_OF_DYNAMIC_RULES</a> is the maximum number of dynamic rules an
	// extension can add.
	// \|rules\|: The rules to add.
	// \|callback\|: Called once the given <code>rules</code> are added. In case
	// of an error, $(ref:runtime.lastError) will be set to denote the error
	// message and no rules will be added. This can happen for multiple reasons,
	// such as invalid rule format, duplicate rule ID, rule count limit
	// exceeded, internal errors, and others.
	static void addDynamicRules(Rule[] rules, optional EmptyCallback callback);

	// Removes rules corresponding to <code>rule_ids</code> from the current set
	// of dynamic rules for the extension. Any <code>rule_ids</code> not already
	// present are ignored. Note that static rules specified as part of the
	// extension package can not be removed using this function.
	// \|rule_ids\|: The IDs of dynamic rules to remove.
	// \|callback\|: Called once the rules are removed. In case of an error,
	// $(ref:runtime.lastError) will be set to denote the error message and no
	// rules will be removed. This may happen due to internal errors.
	static void removeDynamicRules(long[] rule_ids,
	optional EmptyCallback callback);

	// Returns the current set of dynamic rules for the extension.
	// \|callback\|: Called with the set of dynamic rules. An error might be
	// raised in case of transient internal errors.
	static void getDynamicRules(GetRulesCallback callback);

	// Adds <code>page_patterns</code> to the set of allowed pages. Requests
	// from these pages are not intercepted by the extension. These are
	// persisted across browser sessions.
	// Note: <a href="#property-MAX_NUMBER_OF_ALLOWED_PAGES">
	// MAX_NUMBER_OF_ALLOWED_PAGES</a> is the maximum number of
	// allowed page an extension can add. Also, adding page patterns is
	// atomic. In case of an error, no page pattern is added.
	// \|page_patterns\| : Array of
	// <a href="/extensions/match_patterns">match patterns</a> which are to be
	// allowed.
	// \|callback\|: Called after the <code>page_patterns</code> have been added.
	// $(ref:runtime.lastError) will be set in case of an error, for example if
	// an invalid page pattern is specified or the extension exceeded the
	// maximum page patterns limit.
	static void addAllowedPages(DOMString[] page_patterns,
	optional EmptyCallback callback);

	// Removes <code>page_patterns</code> from the set of allowed pages.
	// Note: Removing page patterns is atomic. In case of an error, no page
	// pattern is removed.
	// \|page_patterns\| : Array of
	// <a href="/extensions/match_patterns">match patterns</a> which are to be
	// removed.
	// \|callback\|: Called after the <code>page_patterns</code> have been
	// removed. $(ref:runtime.lastError) will be set in case of an error.
	static void removeAllowedPages(DOMString[] page_patterns,
	optional EmptyCallback callback);

	// Returns the current set of allowed pages.
	// \|callback\|: Called with the set of currently allowed pages.
	static void getAllowedPages(GetAllowedPagesCallback callback);

	// TODO(crbug.com/967942): Add documentation once implementation is
	// complete.
	[nodoc]
	static void getMatchedRules(optional MatchedRulesFilter filter,
	GetMatchedRulesCallback callback);

	// Sets whether to automatically badge extension's icon to the matched
	// action count for a tab. This preference is persisted across sessions and
	// is false by default.
	// TODO(crbug.com/973211): Add documentation once implementation is
	// complete.
	[nodoc]
	static void setActionCountAsBadgeText(boolean enable);
	};

	interface Properties {
	// The maximum number of allowed pages that an extension can add.
	[value=100] static long MAX_NUMBER_OF_ALLOWED_PAGES();

	// The maximum number of rules that an extension can specify in the rule
	// resources file. Any excess rules will be ignored and an install warning
	// will be raised.
	[value=30000] static long MAX_NUMBER_OF_RULES();

	// The maximum number of dynamic rules that an extension can add.
	[value=5000] static long MAX_NUMBER_OF_DYNAMIC_RULES();
	};
	};