content/public/browser/origin_trials_controller_delegate.h

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

#ifndef CONTENT_PUBLIC_BROWSER_ORIGIN_TRIALS_CONTROLLER_DELEGATE_H_
#define CONTENT_PUBLIC_BROWSER_ORIGIN_TRIALS_CONTROLLER_DELEGATE_H_

#include <string>

#include "base/containers/flat_set.h"
#include "base/strings/string_piece.h"
#include "base/time/time.h"
#include "content/common/content_export.h"
#include "third_party/blink/public/common/origin_trials/origin_trial_feature.h"
#include "url/origin.h"

namespace content {

// The `OriginTrialsControllerDelegate` interface exposes the functionality
// of the origin_trials component to the browser process.
//
// Use this class to check if a given persistent origin trial has been enabled
// for the current profile.
//
// See `components/origin_trials/README.md` for more information.
// TODO(https://crbug.com/1410180): Switch `partition_origin` to use Cookie
// partitioning. This interface uses the last committed origin from the
// outermost frame or document as partitioning as an interim measure to get a
// stable partitioning key until cookie partitioning is fully rolled out.
class CONTENT_EXPORT OriginTrialsControllerDelegate {
 public:
  virtual ~OriginTrialsControllerDelegate() = default;

  // Persist all enabled and persistable tokens in the `header_tokens`.
  //
  // Token persistence is partitioned based on `partition_origin`, meaning that
  // the storage keeps track of which `partition_origin`s have been seen when
  // persisting tokens for a given trial and origin.
  //
  // Subsequent calls to this method will update the registration of a token
  // for an origin. Passing an empty `header_tokens` will effectively clear the
  // persistence of tokens for the `origin` and `partition_origin`.
  // TODO(https://crbug.com/1410180): Switch `partition_origin` to use Cookie
  // partitioning.
  virtual void PersistTrialsFromTokens(
      const url::Origin& origin,
      const url::Origin& partition_origin,
      const base::span<const std::string> header_tokens,
      const base::Time current_time) = 0;

  // Appends all enabled and persistable `tokens` to the set of already enabled
  // trials for `origin`. By passing `script_origins`, this method can be used
  // to append third-party origin trials as well. If a token in `tokens` is a
  // third-party origin trial token, and the corresponding origin is present in
  // `script_tokens`, then the trial will be enabled for the origin stored in
  // the token itself, rather than any origin found in `script_origins`. This
  // limitation means that subdomain matching does not work for third-party
  // origin trial tokens using this method.
  virtual void PersistAdditionalTrialsFromTokens(
      const url::Origin& origin,
      const url::Origin& partition_origin,
      base::span<const url::Origin> script_origins,
      const base::span<const std::string> tokens,
      const base::Time current_time) = 0;

  // Returns `true` if `feature` has been persistently enabled for `origin`,
  // partitioned by `partition_origin` and is still valid. This method should
  // be used by origin trial owners to check if the feature under trial should
  // be enabled.
  // TODO(https://crbug.com/1410180): Switch `partition_origin` to use Cookie
  // partitioning.
  virtual bool IsFeaturePersistedForOrigin(const url::Origin& origin,
                                           const url::Origin& partition_origin,
                                           blink::OriginTrialFeature feature,
                                           const base::Time current_time) = 0;

  // Return the list of persistent origin trials that have been saved for
  // `origin`, partitioned by `partition_origin`, and haven't expired given the
  // `current_time` parameter.
  // TODO(https://crbug.com/1410180): Switch `partition_origin` to use Cookie
  // partitioning.
  virtual base::flat_set<std::string> GetPersistedTrialsForOrigin(
      const url::Origin& origin,
      const url::Origin& partition_origin,
      base::Time current_time) = 0;

  // Remove all persisted tokens. Used to clear browsing data.
  virtual void ClearPersistedTokens() = 0;
};

}  // namespace content

#endif  // CONTENT_PUBLIC_BROWSER_ORIGIN_TRIALS_CONTROLLER_DELEGATE_H_