// Copyright 2017 The Chromium Authors
// 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
   /// base::EscapeQueryParamValue.
   remove_query_params : [string];

   /// Query params to be added/replaced. These are already escaped using
   /// base::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];

  // The list of top-level frame domains to be included/excluded from the
  // filter's affected set. Each should either be null or have at least a single
  // element. The domains should be in lower-case and kept sorted as defined by
  // url_pattern_index::CompareDomains. The entries must consist of only ASCII
  // characters. Use punycode encoding for internationalized domains.
  top_domains_included : [string];
  top_domains_excluded : [string];

  /// Headers to include/exclude. Note that `excluded_response_headers` will
  /// only match on header names.
  /// TODO(crbug.com/41482616): Consider relocating these header conditions as
  /// they apply to requests and what "embeds" the requests (such as the
  /// browser). One potentially suitable place would be a new table in the
  /// UrlPatternIndex for more complex conditions from requests and responses,
  /// especially if future components may reuse these conditions.
  response_headers: [HeaderCondition];
  excluded_response_headers: [HeaderCondition];
}

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

/// Options for regex filters and substitutions for headers. Corresponds to
/// extensions::api::declarative_net_request::HeaderRegexOptions.
table RegexFilterOptions {
  /// Whether the regex should match all groups for the value. This is only
  /// relevant if a regex substitution is present and would thus need to be
  /// applied onto all matching groups. Equivalent to the "g" flag.
  /// Defaults to false.
  match_all: bool = false;
}

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

  /// A regular expression to match against the header value. This follows the
  /// RE2 syntax for consistency with the rest of the API.
  regex_filter: string;

  /// Substitution pattern for the response header. `regexFilter` must be
  /// specified for this to be valid. Takes precedence over `value` and
  /// `operation` if specified and valid.
  regex_substitution: string;

  /// Options for the regex filter. If not specified, all options will be
  /// default.
  regex_options: RegexFilterOptions;
}

/// Describes the matching condition for a header, Corresponds to
/// extensions::api::declarative_net_request::HeaderInfo.
table HeaderCondition {
  /// The name of the header to be matched on.
  header: string;
  /// Header values to include or exclude for matching, if non-empty. This is
  /// converted into lowercase.
  values: [string];
  excluded_values: [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.
  /// This index list is for rules that can be matched before a request is
  /// initiated.
  before_request_index_list : [url_pattern_index.flat.UrlPatternIndex];

  /// An index list of `IndexType_count` indices for rules that are matched
  /// after response headers have been received from a request.
  headers_received_index_list : [url_pattern_index.flat.UrlPatternIndex];

  /// Regex rules are not matched by UrlPatternIndex and so we don't build an
  /// index for them. This list is for rules that can be matched before a
  /// request is initiated.
  before_request_regex_rules: [RegexRule];

  /// List of regex rules that are matched after response headers have been
  /// received from a request.
  headers_received_regex_rules: [RegexRule];

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

root_type ExtensionIndexedRuleset;

file_identifier "EXTR";