blob: 6c5411e808ca5e4cc61e16e54bf755d2536da9ac [file] [log] [blame]
// 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.
#ifndef NET_REPORTING_REPORTING_CACHE_H_
#define NET_REPORTING_REPORTING_CACHE_H_
#include <memory>
#include <set>
#include <string>
#include <vector>
#include "base/callback.h"
#include "base/macros.h"
#include "base/time/time.h"
#include "base/values.h"
#include "net/base/net_export.h"
#include "net/reporting/reporting_endpoint.h"
#include "net/reporting/reporting_header_parser.h"
#include "net/reporting/reporting_report.h"
#include "url/gurl.h"
#include "url/origin.h"
namespace net {
class ReportingContext;
// The cache holds undelivered reports and clients (per-origin endpoint
// configurations) in memory. (It is not responsible for persisting them.)
//
// Each Reporting "endpoint" represents a report collector at some specified
// URL. Endpoints are organized into named "endpoint groups", each of which
// additionally specifes some properties such as expiration time.
// A "client" represents the entire endpoint configuration set by an origin via
// a Report-To header, which consists of multiple endpoint groups, each of which
// consists of multiple endpoints. An endpoint group is keyed by its name. An
// endpoint is unkeyed except by the client and group structure tree above it.
//
// The cache implementation corresponds roughly to the "Reporting cache"
// described in the spec, except that endpoints and clients are stored in a more
// structurally-convenient way, and endpoint failures/retry-after are tracked in
// ReportingEndpointManager.
//
// The cache implementation has the notion of "pending" reports. These are
// reports that are part of an active delivery attempt, so they won't be
// actually deallocated. Any attempt to remove a pending report wil mark it
// "doomed", which will cause it to be deallocated once it is no longer pending.
class NET_EXPORT ReportingCache {
public:
class PersistentReportingStore;
static std::unique_ptr<ReportingCache> Create(ReportingContext* context);
virtual ~ReportingCache();
// Adds a report to the cache.
//
// All parameters correspond to the desired values for the relevant fields in
// ReportingReport.
virtual void AddReport(const NetworkIsolationKey& network_isolation_key,
const GURL& url,
const std::string& user_agent,
const std::string& group_name,
const std::string& type,
std::unique_ptr<const base::Value> body,
int depth,
base::TimeTicks queued,
int attempts) = 0;
// Gets all reports in the cache. The returned pointers are valid as long as
// either no calls to |RemoveReports| have happened or the reports' |pending|
// flag has been set to true using |SetReportsPending|. Does not return
// doomed reports (pending reports for which removal has been requested).
//
// (Clears any existing data in |*reports_out|.)
virtual void GetReports(
std::vector<const ReportingReport*>* reports_out) const = 0;
// Gets all reports in the cache, including pending and doomed reports, as a
// base::Value.
virtual base::Value GetReportsAsValue() const = 0;
// Gets all reports in the cache that aren't pending or doomed (i.e. that are
// eligible for delivery), and marks returned reports as pending in
// preparation for a delivery attempt. The returned pointers are valid as long
// as the reports are still pending.
virtual std::vector<const ReportingReport*> GetReportsToDeliver() = 0;
// Unmarks a set of reports as pending. |reports| must be previously marked as
// pending.
virtual void ClearReportsPending(
const std::vector<const ReportingReport*>& reports) = 0;
// Increments |attempts| on a set of reports.
virtual void IncrementReportsAttempts(
const std::vector<const ReportingReport*>& reports) = 0;
// Records that we attempted (and possibly succeeded at) delivering
// |reports_delivered| reports to the specified endpoint.
virtual void IncrementEndpointDeliveries(
const ReportingEndpointGroupKey& group_key,
const GURL& url,
int reports_delivered,
bool successful) = 0;
// Removes a set of reports. Any reports that are pending will not be removed
// immediately, but rather marked doomed and removed once they are no longer
// pending.
virtual void RemoveReports(
const std::vector<const ReportingReport*>& reports) = 0;
// Removes all reports. Like |RemoveReports()|, pending reports are doomed
// until no longer pending.
virtual void RemoveAllReports() = 0;
// Gets the count of reports in the cache, *including* doomed reports.
//
// Needed to ensure that doomed reports are eventually deleted, since no
// method provides a view of *every* report in the cache, just non-doomed
// ones.
virtual size_t GetFullReportCountForTesting() const = 0;
virtual bool IsReportPendingForTesting(
const ReportingReport* report) const = 0;
virtual bool IsReportDoomedForTesting(
const ReportingReport* report) const = 0;
// Adds a new client to the cache for |origin|, or updates the existing one
// to match the new header. All values are assumed to be valid as they have
// passed through the ReportingHeaderParser.
virtual void OnParsedHeader(
const NetworkIsolationKey& network_isolation_key,
const url::Origin& origin,
std::vector<ReportingEndpointGroup> parsed_header) = 0;
// Gets all the origins of clients in the cache.
virtual std::set<url::Origin> GetAllOrigins() const = 0;
// Remove client for the given (NIK, origin) pair, if it exists in the cache.
// All endpoint groups and endpoints for that client are also removed.
virtual void RemoveClient(const NetworkIsolationKey& network_isolation_key,
const url::Origin& origin) = 0;
// Remove all clients for the given |origin|, if any exists in the cache.
// All endpoint groups and endpoints for |origin| are also removed.
virtual void RemoveClientsForOrigin(const url::Origin& origin) = 0;
// Remove all clients, groups, and endpoints from the cache.
virtual void RemoveAllClients() = 0;
// Remove the endpoint group matching |group_key|, and remove
// all endpoints for that group. May cause the client it was associated with
// to be deleted if it becomes empty.
virtual void RemoveEndpointGroup(
const ReportingEndpointGroupKey& group_key) = 0;
// Remove all endpoints for with |url|, regardless of origin or group. Used
// when a delivery returns 410 Gone. May cause deletion of groups/clients if
// they become empty.
virtual void RemoveEndpointsForUrl(const GURL& url) = 0;
// Insert endpoints and endpoint groups that have been loaded from the store.
//
// You must only call this method if context.store() was non-null when you
// constructed the cache and persist_clients_across_restarts in your
// ReportingPolicy is true.
virtual void AddClientsLoadedFromStore(
std::vector<ReportingEndpoint> loaded_endpoints,
std::vector<CachedReportingEndpointGroup> loaded_endpoint_groups) = 0;
// Gets endpoints that apply to a delivery for |origin| and |group|.
//
// First checks for |group| in a client exactly matching |origin|.
// If none exists, then checks for |group| in clients for superdomains
// of |origin| which have include_subdomains enabled, returning only the
// endpoints for the most specific applicable parent origin of |origin|. If
// there are multiple origins with that group within the most specific
// applicable superdomain, gets endpoints for that group from only one of
// them. The group must not be expired.
//
// For example, given the origin https://foo.bar.baz.com/, the cache
// would prioritize returning each potential match below over the ones below
// it, for groups with name |group| with include_subdomains enabled:
// 1. https://foo.bar.baz.com/ (exact origin match)
// 2. https://foo.bar.baz.com:444/ (technically, a superdomain)
// 3. https://bar.baz.com/, https://bar.baz.com:444/, etc. (superdomain)
// 4. https://baz.com/, https://baz.com:444/, etc. (superdomain)
// If both https://bar.baz.com/ and https://bar.baz.com:444/ had a group with
// name |group| with include_subdomains enabled, this method would return
// endpoints from that group from the earliest-inserted origin.
virtual std::vector<ReportingEndpoint> GetCandidateEndpointsForDelivery(
const ReportingEndpointGroupKey& group_key) = 0;
// Gets the status of all clients in the cache, including expired ones, as a
// base::Value.
virtual base::Value GetClientsAsValue() const = 0;
// Gets the total number of endpoints in the cache across all origins.
virtual size_t GetEndpointCount() const = 0;
// Flush the contents of the cache to disk, if applicable.
virtual void Flush() = 0;
// Finds an endpoint for the given |group_key| and |url|, otherwise returns an
// invalid ReportingEndpoint.
virtual ReportingEndpoint GetEndpointForTesting(
const ReportingEndpointGroupKey& group_key,
const GURL& url) const = 0;
// Returns whether an endpoint group with exactly the given properties exists
// in the cache. If |expires| is base::Time(), it will not be checked.
virtual bool EndpointGroupExistsForTesting(
const ReportingEndpointGroupKey& group_key,
OriginSubdomains include_subdomains,
base::Time expires) const = 0;
// Returns whether a client for the given (NIK, Origin) exists.
virtual bool ClientExistsForTesting(
const NetworkIsolationKey& network_isolation_key,
const url::Origin& origin) const = 0;
// Returns number of endpoint groups.
virtual size_t GetEndpointGroupCountForTesting() const = 0;
// Returns number of endpoint groups.
virtual size_t GetClientCountForTesting() const = 0;
// Sets an endpoint with the given properties in a group with the given
// properties, bypassing header parsing. Note that the endpoint is not
// guaranteed to exist in the cache after calling this function, if endpoint
// eviction is triggered. Unlike the AddOrUpdate*() methods used in header
// parsing, this method inserts or updates a single endpoint while leaving the
// exiting configuration for that origin intact.
virtual void SetEndpointForTesting(const ReportingEndpointGroupKey& group_key,
const GURL& url,
OriginSubdomains include_subdomains,
base::Time expires,
int priority,
int weight) = 0;
};
// Persistent storage for Reporting reports and clients.
class NET_EXPORT ReportingCache::PersistentReportingStore {
public:
using ReportingClientsLoadedCallback =
base::OnceCallback<void(std::vector<ReportingEndpoint>,
std::vector<CachedReportingEndpointGroup>)>;
PersistentReportingStore() = default;
virtual ~PersistentReportingStore() = default;
// Initializes the store and retrieves stored endpoints and endpoint groups.
// Called only once at startup.
virtual void LoadReportingClients(
ReportingClientsLoadedCallback loaded_callback) = 0;
// Adds an endpoint to the store.
virtual void AddReportingEndpoint(const ReportingEndpoint& endpoint) = 0;
// Adds an endpoint group to the store.
virtual void AddReportingEndpointGroup(
const CachedReportingEndpointGroup& group) = 0;
// Updates the access time of an endpoint group in the store.
virtual void UpdateReportingEndpointGroupAccessTime(
const CachedReportingEndpointGroup& group) = 0;
// Updates the details of an endpoint in the store.
virtual void UpdateReportingEndpointDetails(
const ReportingEndpoint& endpoint) = 0;
// Updates the details of an endpoint group in the store.
virtual void UpdateReportingEndpointGroupDetails(
const CachedReportingEndpointGroup& group) = 0;
// Deletes an endpoint from the store.
virtual void DeleteReportingEndpoint(const ReportingEndpoint& endpoint) = 0;
// Deletes an endpoint group from the store.
virtual void DeleteReportingEndpointGroup(
const CachedReportingEndpointGroup& group) = 0;
// TODO(chlily): methods to load, add, and delete reports will be added.
// Flushes the store.
virtual void Flush() = 0;
private:
DISALLOW_COPY_AND_ASSIGN(PersistentReportingStore);
};
} // namespace net
#endif // NET_REPORTING_REPORTING_CACHE_H_