components/url_pattern_index/proto/rules.proto

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

syntax = "proto2";
option optimize_for = LITE_RUNTIME;

package url_pattern_index.proto;
option java_package = "org.chromium.components.url_pattern_index.proto";

// The type of a subresource filtering rule.
enum RuleType {
  RULE_TYPE_UNSPECIFIED = 0;

  RULE_TYPE_COMMENT = 1;  // Comment rule.
  RULE_TYPE_URL = 2;      // Network level filtering rule based on URL pattern.
  RULE_TYPE_CSS = 3;      // Element hiding rule based on a CSS selector.
};

// The format of a URL pattern.
enum UrlPatternType {
  URL_PATTERN_TYPE_UNSPECIFIED = 0;

  // A pattern without special characters, e.g. "example.com".
  URL_PATTERN_TYPE_SUBSTRING = 1;

  // The pattern contains one or more wildcards, namely '*' and/or '^'
  // characters. The '*' matches any sequence of characters, while the '^'
  // matches a separator, i.e. anything but a letter, a digit, or one of [-._%].
  URL_PATTERN_TYPE_WILDCARDED = 2;

  // The pattern is a regular expression.
  URL_PATTERN_TYPE_REGEXP = 3;
};

// Types of anchors that can be used to constrain where a URL pattern must
// begin/end in the URL in order to be considered a match.
enum AnchorType {
  ANCHOR_TYPE_UNSPECIFIED = 0;

  // Acts like a '*' wildcard at the respective end of a pattern.
  ANCHOR_TYPE_NONE = 1;
  // The pattern must match from the start/until the end of the URL.
  ANCHOR_TYPE_BOUNDARY = 2;
  // The pattern must match starting with the TLD+n of the URL's domain, but the
  // scheme and subdomains (if any) can be arbitrary.
  ANCHOR_TYPE_SUBDOMAIN = 3;
};

// The types of subresource requests that a URL rule should be applied to.
// Note: Values are used as flags in a bitmask.
enum ElementType {
  option allow_alias = true;
  ELEMENT_TYPE_UNSPECIFIED = 0;

  ELEMENT_TYPE_OTHER = 1;
  ELEMENT_TYPE_SCRIPT = 2;
  ELEMENT_TYPE_IMAGE = 4;
  ELEMENT_TYPE_STYLESHEET = 8;
  ELEMENT_TYPE_OBJECT = 16;
  ELEMENT_TYPE_XMLHTTPREQUEST = 32;
  ELEMENT_TYPE_OBJECT_SUBREQUEST = 64;
  ELEMENT_TYPE_SUBDOCUMENT = 128;
  ELEMENT_TYPE_PING = 256;
  ELEMENT_TYPE_MEDIA = 512;
  ELEMENT_TYPE_FONT = 1024;
  ELEMENT_TYPE_POPUP = 2048;
  ELEMENT_TYPE_WEBSOCKET = 4096;

  // NOTE: Keep these two values consistent with the values above.
  ELEMENT_TYPE_MAX = 4096;
  ELEMENT_TYPE_ALL = 8191;
};

// The options controlling whether or not to activate filtering for subresources
// of documents that match the URL pattern of the rule.
// Note: Values are used as flags in a bitmask.
enum ActivationType {
  option allow_alias = true;
  ACTIVATION_TYPE_UNSPECIFIED = 0;

  ACTIVATION_TYPE_DOCUMENT = 1;      // Disable all rules on the page.
  ACTIVATION_TYPE_ELEMHIDE = 2;      // Disable CSS rules on the page.
  ACTIVATION_TYPE_GENERICHIDE = 4;   // Disable generic CSS rules on the page.
  ACTIVATION_TYPE_GENERICBLOCK = 8;  // Disable generic URL rules on the page.

  // NOTE: Keep these two values consistent with the values above.
  ACTIVATION_TYPE_MAX = 8;
  ACTIVATION_TYPE_ALL = 15;
};

// The semantics of a rule. Defines how the rule relates to other rules and how
// it influences the filtering decision.
enum RuleSemantics {
  RULE_SEMANTICS_UNSPECIFIED = 0;

  // Matching subresource requests should be aborted, matching elements should
  // be hidden.
  RULE_SEMANTICS_BLACKLIST = 1;
  // If the rule matches, it suppresses any matching RULE_SEMANTICS_BLACKLIST
  // rule.
  RULE_SEMANTICS_WHITELIST = 2;
}

// The type of relation between the source of the requested subresource and that
// of the document.
enum SourceType {
  SOURCE_TYPE_UNSPECIFIED = 0;

  SOURCE_TYPE_ANY = 1;          // Doesn't matter.
  SOURCE_TYPE_THIRD_PARTY = 2;  // Requesting a trird-party resource.
  SOURCE_TYPE_FIRST_PARTY = 3;  // Requesting a first-party resource.
}

// An item of the domain list.
message DomainListItem {
  // The UTF-8 representation of the domain, e.g. "subdomain.example.com".
  optional string domain = 1;

  // Defines whether the domain is excluded from the set of domains.
  optional bool exclude = 2;
}

// A network level filtering rule based on a URL pattern. Corresponds to
// RULE_TYPE_URL.
message UrlRule {
  // The semantics of the rule.
  optional RuleSemantics semantics = 1;

  // Restricts application of the rule to first-party/third-party requests.
  optional SourceType source_type = 2;

  // Stores the ElementTypes that the rule applies to as a bitwise OR of the
  // corresponding ElementType values.
  optional int32 element_types = 3;

  // Stores the ActivationTypes associated with the rule as a bitwise OR of the
  // corresponding ActivationType values.
  optional int32 activation_types = 4;

  // The rule applies only to subresources of documents loaded from included
  // domains (or subdomains thereof). If the list is empty, the rule is applied
  // on documents from all domains.
  // If |domains| is empty or has exceptions only, the rule is called generic.
  // Otherwise is it called domain specific, i.e. applies to a limited number of
  // domains.
  repeated DomainListItem domains = 5;

  // The format of |url_pattern|.
  optional UrlPatternType url_pattern_type = 6;

  // Defines where the URL pattern must start in the URL in order to be
  // considered a match. Never used with REGEXP patterns.
  optional AnchorType anchor_left = 7;

  // Defines where the URL pattern must end in the URL in order to be
  // considered a match. Never used with REGEXP patterns. Never equals to
  // ANCHOR_TYPE_SUBDOMAIN.
  optional AnchorType anchor_right = 8;

  // When set, the rule applies only to URLs that match |url_pattern| in a
  // case-sensitive way.
  // Not currently implemented.
  optional bool match_case = 9 [deprecated = true];

  // The URL pattern of the format prescribed by |url_pattern_type|.
  optional string url_pattern = 10;
}

// Element hiding rule based on a CSS selector. Corresponds to RULE_TYPE_CSS.
message CssRule {
  // The semantics of the rule.
  optional RuleSemantics semantics = 1;

  // The list of domains, same as UrlRule::domains.
  repeated DomainListItem domains = 2;

  // A CSS selector as specified in http://www.w3.org/TR/css3-selectors.
  optional string css_selector = 3;
}

// A comment line.
message Comment {
  // Comment text.
  optional string text = 1;

  // For special key-value comments, if any.
  optional string key = 2;
  optional string value = 3;
}

// A container for lists of non-comment rules collated by RuleType.
message FilteringRules {
  repeated UrlRule url_rules = 1;
  repeated CssRule css_rules = 2;
}