extensions/common/api/declarative_net_request.idl - chromium/src - 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
   };

   // This describes the possible opeations for a "modifyHeaders" rule.
   // TODO(crbug.com/947591): Add documentation once implementation is complete.
   [nodoc]
   enum HeaderOperation {
     remove
   };

   // 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,
     // Modify request/response headers from the network request.
     // TODO(crbug.com/947591): Add documentation once implementation is
     // complete.
     [nodoc]
     modifyHeaders,
     // Allow all requests within a frame hierarchy, including the frame request
     // itself.
     allowAllRequests
   };

   // Describes a single static ruleset.
   dictionary Ruleset {
     // The path of the JSON ruleset relative to the extension directory.
     DOMString path;
   };

   // 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;

      // Substitution pattern for rules which specify a <code>regexFilter</code>.
      // The first match of <code>regexFilter</code> within the url will be
      // replaced with this pattern. Within <code>regexSubstitution</code>,
      // backslash-escaped digits (\1 to \9) can be used to insert the
      // corresponding capture groups. \0 refers to the entire matching text.
      DOMString? regexSubstitution;
   };

   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.
     //
     // A pattern beginning with <code>||*</code> is not allowed. Use
     // <code>*</code> instead.
     //
     // Note: Only one of <code>urlFilter</code> or <code>regexFilter</code> can
     // be specified.
     //
     // 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;

     // Regular expression to match against the network request url. This follows
     // the <a href = "https://github.com/google/re2/wiki/Syntax">RE2 syntax</a>.
     //
     // Note: Only one of <code>urlFilter</code> or <code>regexFilter</code> can
     // be specified.
     //
     // Note: The <code>regexFilter</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.
     DOMString? regexFilter;

     // Whether the <code>urlFilter</code> or <code>regexFilter</code>
     // (whichever is specified) 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.
     //
     // Note: this must be specified for <code>allowAllRequests</code> rules and
     // may only include the <code>sub_frame</code> and <code>main_frame</code>
     // resource types.
     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;
   };

   // TODO(crbug.com/947591): Add documentation once implementation is complete.
   [nodoc]
   dictionary ModifyHeaderInfo {
     DOMString header;
     HeaderOperation operation;
   };

   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;

     // The request headers to modify for the request. Only valid if
     // RuleActionType is "modifyHeaders".
     // TODO(crbug.com/947591): Add documentation once implementation is
     // complete.
     [nodoc]
     ModifyHeaderInfo[]? requestHeaders;

     // The response headers to modify for the request. Only valid if
     // RuleActionType is "modifyHeaders".
     // TODO(crbug.com/947591): Add documentation once implementation is
     // complete.
     [nodoc]
     ModifyHeaderInfo[]? responseHeaders;
   };

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

     // Rule priority. Mandatory for all rules other than removeHeaders, and
     // should be >= 1. This is used to break ties between multiple matching
     // rules.
     long? priority;

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

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

   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.updateDynamicRules).
     dynamic
   };

   // Uniquely describes a declarative rule specified by the extension.
   dictionary MatchedRule {
     // A matching rule's ID.
     long ruleId;

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

   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;
   };

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

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

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

   dictionary RequestDetails {
     // The ID of the request. Request IDs are unique within a browser session.
     DOMString requestId;

     // The URL of the request.
     DOMString url;

     // The origin where the request was initiated. This does not change through
     // redirects. If this is an opaque origin, the string 'null' will be used.
     DOMString? initiator;

     // Standard HTTP method.
     DOMString method;

     // The value 0 indicates that the request happens in the main frame; a
     // positive value indicates the ID of a subframe in which the request
     // happens. If the document of a (sub-)frame is loaded (<code>type</code> is
     // <code>main_frame</code> or <code>sub_frame</code>), <code>frameId</code>
     // indicates the ID of this frame, not the ID of the outer frame. Frame IDs
     // are unique within a tab.
     long frameId;

     // ID of frame that wraps the frame which sent the request. Set to -1 if no
     // parent frame exists.
     long parentFrameId;

     // The ID of the tab in which the request takes place. Set to -1 if the
     // request isn't related to a tab.
     long tabId;

     // The resource type of the request.
     ResourceType type;
   };

   dictionary MatchedRuleInfoDebug {
     MatchedRule rule;

     // Details about the request for which the rule was matched.
     RequestDetails request;
   };

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

   interface Functions {

     // Modify the current set of dynamic rules for the extension. The rules
     // with IDs listed in <code>rule_ids_to_remove</code> are first removed,
     // and then the rules given in <code>rules_to_add</code> are added. This
     // update happens as a single atomic operation: either all specified rules
     // are added and removed, or an error is returned.
     // These rules are persisted across browser sessions.
     // Any ids in <code>rule_ids_to_remove</code> that are not present will be
     // ignored.
     // Note that static rules specified as part of the extension package can
     // not be removed using this function.
     // 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.
     // |rule_ids_to_remove|: The IDs of rules to remove.
     // |rules_to_add|: The rules to add.
     // |callback|: Called once the update is complete or has failed. In case of
     // an error, $(ref:runtime.lastError) will be set to denote the error
     // message and no change will be made to the rule set. This can happen for
     // multiple reasons, such as invalid rule format, duplicate rule ID, rule
     // count limit exceeded, internal errors, and others.
     static void updateDynamicRules(long[] rule_ids_to_remove, Rule[] rules_to_add,
         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);

     // Returns all rules matched for the extension. Callers can optionally
     // filter the list of matched rules by specifying a |filter|. This method is
     // only available to extensions with the
     // <code>declarativeNetRequestFeedback</code> permission or having the
     // <code>activeTab</code> permission granted for the <code>tabId</code>
     // specified in <code>filter</code>.
     // Note: Rules not associated with an active document that were matched more
     // than five minutes ago will not be returned.
     // |filter|: An object to filter the list of matched rules.
     // |callback|: Called once the list of matched rules has been fetched. In
     // case of an error, $(ref:runtime.lastError) will be set to denote the
     // error and no rules will be returned. This can happen for multiple
     // reasons, such as insufficient permissions, or exceeding the quota.
     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.
     static void setActionCountAsBadgeText(boolean enable);
   };

   interface Properties {
     // 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();

     // Time interval within which <code>MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
     // getMatchedRules</code> calls can be made, specified in minutes.
     // Additional calls will fail immediately and set $(ref:runtime.lastError).
     // Note: <code>getMatchedRules</code> calls associated with a user gesture
     // are exempt from the quota.
     [value=10] static long GETMATCHEDRULES_QUOTA_INTERVAL();

     // The number of times <code>getMatchedRules</code> can be called within a
     // period of <code>GETMATCHEDRULES_QUOTA_INTERVAL</code>.
     [value=20] static long MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL();

     // The maximum number of regular expression rules that an extension can
     // add. This limit is evaluated separately for the set of dynamic rules and
     // those specified in the rule resources file.
     [value=1000] static long MAX_NUMBER_OF_REGEX_RULES();
   };

   interface Events {
     // Fired when a rule is matched with a request. Only available for unpacked
     // extensions with the <code>declarativeNetRequestFeedback</code> permission
     // as this is intended to be used for debugging purposes only.
     // |matched_rule_info|: The rule that has been matched along with
     // information about the associated request.
     static void onRuleMatchedDebug(MatchedRuleInfoDebug matched_rule_info);
   };
 };
	// 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
	};

	// This describes the possible opeations for a "modifyHeaders" rule.
	// TODO(crbug.com/947591): Add documentation once implementation is complete.
	[nodoc]
	enum HeaderOperation {
	remove
	};

	// 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,
	// Modify request/response headers from the network request.
	// TODO(crbug.com/947591): Add documentation once implementation is
	// complete.
	[nodoc]
	modifyHeaders,
	// Allow all requests within a frame hierarchy, including the frame request
	// itself.
	allowAllRequests
	};

	// Describes a single static ruleset.
	dictionary Ruleset {
	// The path of the JSON ruleset relative to the extension directory.
	DOMString path;
	};

	// 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;

	// Substitution pattern for rules which specify a <code>regexFilter</code>.
	// The first match of <code>regexFilter</code> within the url will be
	// replaced with this pattern. Within <code>regexSubstitution</code>,
	// backslash-escaped digits (\1 to \9) can be used to insert the
	// corresponding capture groups. \0 refers to the entire matching text.
	DOMString? regexSubstitution;
	};

	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.
	//
	// A pattern beginning with <code>\|\|*</code> is not allowed. Use
	// <code>*</code> instead.
	//
	// Note: Only one of <code>urlFilter</code> or <code>regexFilter</code> can
	// be specified.
	//
	// 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;

	// Regular expression to match against the network request url. This follows
	// the <a href = "https://github.com/google/re2/wiki/Syntax">RE2 syntax</a>.
	//
	// Note: Only one of <code>urlFilter</code> or <code>regexFilter</code> can
	// be specified.
	//
	// Note: The <code>regexFilter</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.
	DOMString? regexFilter;

	// Whether the <code>urlFilter</code> or <code>regexFilter</code>
	// (whichever is specified) 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.
	//
	// Note: this must be specified for <code>allowAllRequests</code> rules and
	// may only include the <code>sub_frame</code> and <code>main_frame</code>
	// resource types.
	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;
	};

	// TODO(crbug.com/947591): Add documentation once implementation is complete.
	[nodoc]
	dictionary ModifyHeaderInfo {
	DOMString header;
	HeaderOperation operation;
	};

	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;

	// The request headers to modify for the request. Only valid if
	// RuleActionType is "modifyHeaders".
	// TODO(crbug.com/947591): Add documentation once implementation is
	// complete.
	[nodoc]
	ModifyHeaderInfo[]? requestHeaders;

	// The response headers to modify for the request. Only valid if
	// RuleActionType is "modifyHeaders".
	// TODO(crbug.com/947591): Add documentation once implementation is
	// complete.
	[nodoc]
	ModifyHeaderInfo[]? responseHeaders;
	};

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

	// Rule priority. Mandatory for all rules other than removeHeaders, and
	// should be >= 1. This is used to break ties between multiple matching
	// rules.
	long? priority;

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

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

	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.updateDynamicRules).
	dynamic
	};

	// Uniquely describes a declarative rule specified by the extension.
	dictionary MatchedRule {
	// A matching rule's ID.
	long ruleId;

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

	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;
	};

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

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

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

	dictionary RequestDetails {
	// The ID of the request. Request IDs are unique within a browser session.
	DOMString requestId;

	// The URL of the request.
	DOMString url;

	// The origin where the request was initiated. This does not change through
	// redirects. If this is an opaque origin, the string 'null' will be used.
	DOMString? initiator;

	// Standard HTTP method.
	DOMString method;

	// The value 0 indicates that the request happens in the main frame; a
	// positive value indicates the ID of a subframe in which the request
	// happens. If the document of a (sub-)frame is loaded (<code>type</code> is
	// <code>main_frame</code> or <code>sub_frame</code>), <code>frameId</code>
	// indicates the ID of this frame, not the ID of the outer frame. Frame IDs
	// are unique within a tab.
	long frameId;

	// ID of frame that wraps the frame which sent the request. Set to -1 if no
	// parent frame exists.
	long parentFrameId;

	// The ID of the tab in which the request takes place. Set to -1 if the
	// request isn't related to a tab.
	long tabId;

	// The resource type of the request.
	ResourceType type;
	};

	dictionary MatchedRuleInfoDebug {
	MatchedRule rule;

	// Details about the request for which the rule was matched.
	RequestDetails request;
	};

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

	interface Functions {

	// Modify the current set of dynamic rules for the extension. The rules
	// with IDs listed in <code>rule_ids_to_remove</code> are first removed,
	// and then the rules given in <code>rules_to_add</code> are added. This
	// update happens as a single atomic operation: either all specified rules
	// are added and removed, or an error is returned.
	// These rules are persisted across browser sessions.
	// Any ids in <code>rule_ids_to_remove</code> that are not present will be
	// ignored.
	// Note that static rules specified as part of the extension package can
	// not be removed using this function.
	// 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.
	// \|rule_ids_to_remove\|: The IDs of rules to remove.
	// \|rules_to_add\|: The rules to add.
	// \|callback\|: Called once the update is complete or has failed. In case of
	// an error, $(ref:runtime.lastError) will be set to denote the error
	// message and no change will be made to the rule set. This can happen for
	// multiple reasons, such as invalid rule format, duplicate rule ID, rule
	// count limit exceeded, internal errors, and others.
	static void updateDynamicRules(long[] rule_ids_to_remove, Rule[] rules_to_add,
	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);

	// Returns all rules matched for the extension. Callers can optionally
	// filter the list of matched rules by specifying a \|filter\|. This method is
	// only available to extensions with the
	// <code>declarativeNetRequestFeedback</code> permission or having the
	// <code>activeTab</code> permission granted for the <code>tabId</code>
	// specified in <code>filter</code>.
	// Note: Rules not associated with an active document that were matched more
	// than five minutes ago will not be returned.
	// \|filter\|: An object to filter the list of matched rules.
	// \|callback\|: Called once the list of matched rules has been fetched. In
	// case of an error, $(ref:runtime.lastError) will be set to denote the
	// error and no rules will be returned. This can happen for multiple
	// reasons, such as insufficient permissions, or exceeding the quota.
	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.
	static void setActionCountAsBadgeText(boolean enable);
	};

	interface Properties {
	// 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();

	// Time interval within which <code>MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
	// getMatchedRules</code> calls can be made, specified in minutes.
	// Additional calls will fail immediately and set $(ref:runtime.lastError).
	// Note: <code>getMatchedRules</code> calls associated with a user gesture
	// are exempt from the quota.
	[value=10] static long GETMATCHEDRULES_QUOTA_INTERVAL();

	// The number of times <code>getMatchedRules</code> can be called within a
	// period of <code>GETMATCHEDRULES_QUOTA_INTERVAL</code>.
	[value=20] static long MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL();

	// The maximum number of regular expression rules that an extension can
	// add. This limit is evaluated separately for the set of dynamic rules and
	// those specified in the rule resources file.
	[value=1000] static long MAX_NUMBER_OF_REGEX_RULES();
	};

	interface Events {
	// Fired when a rule is matched with a request. Only available for unpacked
	// extensions with the <code>declarativeNetRequestFeedback</code> permission
	// as this is intended to be used for debugging purposes only.
	// \|matched_rule_info\|: The rule that has been matched along with
	// information about the associated request.
	static void onRuleMatchedDebug(MatchedRuleInfoDebug matched_rule_info);
	};
	};