extensions/browser/api/declarative_net_request/flat/extension_ruleset.fbs

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

include "components/url_pattern_index/flat/url_pattern_index.fbs";

// NOTE: Increment kIndexedRulesetFormatVersion at
// extensions/browser/api/declarative_net_request/utils.cc whenever
// making a breaking change to this schema.

namespace extensions.declarative_net_request.flat;

/// The type of an action. Corresponds to
/// extensions::api::declarative_net_request::RuleActionType.
enum ActionType : ubyte {
  block,
  allow,
  redirect,
  upgrade_scheme,
  modify_headers,
  allow_all_requests,
  /// Number of actions. Must be the last entry.
  count
}

table QueryKeyValue {
  key : string (required);
  value : string (required);
  replace_only: bool = false;
}

table UrlTransform {
   scheme : string;
   host : string;

   clear_port : bool = false;
   port : string;

   clear_path : bool = false;
   path : string;

   clear_query : bool = false;

   /// If valid, doesn't include the '?' separator.
   query : string;

   /// Query params to be removed. These are already sorted and escaped using
   /// net::EscapeQueryParamValue.
   remove_query_params : [string];

   /// Query params to be added/replaced. These are already escaped using
   /// net::EscapeQueryParamValue.
   add_or_replace_query_params : [QueryKeyValue];

   clear_fragment : bool = false;

   /// If valid, doesn't include the '#' separator.
   fragment : string;

   username : string;
   password : string;
}

/// Additional extension related metadata for a url_pattern_index UrlRule.
table UrlRuleMetadata {
  /// ID of the UrlRule for which this metadata is stored.
  id : uint (key);

  /// Action type for this rule.
  action : ActionType;

  /// Redirect url for this rule. Should represent a valid GURL. At most one of
  /// |redirect_url| and |transform| should be specified for redirect rules.
  redirect_url : string;

  /// UrlTransform for this rule.
  transform : UrlTransform;

  /// A list of ModifyHeaderInfo, for both request and response headers. Valid
  /// for "modifyHeaders" rules.
  request_headers: [ModifyHeaderInfo];
  response_headers: [ModifyHeaderInfo];
}

// Extension embedder conditions for a flat::UrlRule. This is stored as a nested
// flatbuffer in `flat::UrlRule::embedder_conditions`. The constructed
// flatbuffer must use `kEmbedderConditionsBufferIdentifier` as the file
// identifier.
table EmbedderConditions {
  // Sorted list of tab IDs to include/exclude.
  tab_ids_included : [int];
  tab_ids_excluded : [int];
}

/// This provides a mapping from an index type to its index within
/// the |index_list| vector.
enum IndexType : ubyte {
  /// Index for rules that are evaluated during the onBeforeRequest stage of a
  /// request, excluding allowAllRequests rules.
  before_request_except_allow_all_requests = 0,

  /// Index for allowAllRequests rule. We have a separate index for these rules
  /// since they need to be evaluated separately when a navigation commits.
  allow_all_requests,

  modify_headers,

  /// Number of indices. Must be the last entry.
  count
}

/// The type of header operation for modifyHeaders rules. Corresponds to
/// extensions::api::declarative_net_request::HeaderOperation.
enum HeaderOperation : ubyte {
  append,
  set,
  remove
}

/// Describes the header to be modified and operation to be performed on it.
/// Corresponds to extensions::api::declarative_net_request::ModifyHeaderInfo.
table ModifyHeaderInfo {
  operation: HeaderOperation;
  /// The name the header to be modified. Since header names are
  /// case-insensitive, the header name is normalized by converting it to
  /// lowercase.
  header: string;
  /// The value of the header to be set/appended. Should be specified only if
  /// |operation| is append or set.
  value: string;
}

/// Completely represents a rule with a regex filter.
table RegexRule {
  /// The underlying UrlRule.
  url_rule: url_pattern_index.flat.UrlRule;

  /// The action to take.
  // TODO(tbodt): this is duplicated in the UrlRuleMetadata. We should either
  // use the action type in the metadata or not use UrlRuleMetadata at all for
  // regex rules.
  action_type: ActionType;

  /// The regex substitution pattern for this rule if specified.
  regex_substitution: string;
}

/// The top-level data structure used to store extensions URL rules for the
/// Declarative Net Request API.
table ExtensionIndexedRuleset {
  /// Vector of UrlPatternIndex. This will consist of IndexType_count
  /// indices.
  index_list : [url_pattern_index.flat.UrlPatternIndex];

  // Regex rules are not matched by UrlPatternIndex and so we don't build an
  // index for them.
  regex_rules: [RegexRule];

  /// Extension related metadata. Sorted by id, to support fast lookup.
  extension_metadata : [UrlRuleMetadata];
}

root_type ExtensionIndexedRuleset;

file_identifier "EXTR";