content/browser/attribution_reporting/attribution_internals.mojom

// Copyright 2020 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module attribution_internals.mojom;

import "components/attribution_reporting/registration.mojom";
import "components/attribution_reporting/source_registration_error.mojom";
import "components/attribution_reporting/source_type.mojom";
import "content/browser/attribution_reporting/store_source_result.mojom";
import "content/browser/attribution_reporting/attribution_reporting.mojom";
import "services/network/public/mojom/attribution.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";

// Represents `AttributionReport::Id`.
// Will be used to issue commands for individual reports.
struct ReportID {
  int64 value;
};

// Contains event-level data to be displayed.
struct WebUIReportEventLevelData {
  int64 priority;
  bool attributed_truthfully;
};

// Represents `AggregatableHistogramContribution`.
struct AggregatableHistogramContribution {
  // Hex-encoded unsigned 128-bit integer.
  string key;
  uint32 value;
};

// Contains aggregatable attribution data to be displayed.
struct WebUIReportAggregatableAttributionData {
  array<AggregatableHistogramContribution> contributions;
  string? verification_token;
  string aggregation_coordinator;
  bool is_null_report;
};

union WebUIReportData {
  WebUIReportEventLevelData event_level_data;
  WebUIReportAggregatableAttributionData
      aggregatable_attribution_data;
};

struct Empty {};

union ReportStatus {
  Empty pending;
  // Contains the external report ID of the replacement report.
  string replaced_by_higher_priority_report;
  Empty prohibited_by_browser_policy;
  // Contains the HTTP response code.
  int32 sent;
  string network_error;
  Empty failed_to_assemble;
};

// Struct containing stored data that will be sent in a future attribution
// report.
struct WebUIReport {
  // Allows the WebUI to issue commands for individual reports.
  // Not intended to be displayed.
  ReportID id;
  url.mojom.Url report_url;
  double trigger_time;
  double report_time;
  string report_body;
  ReportStatus status;
  WebUIReportData data;
};

union DebugReportStatus {
  int32 http_response_code;
  string network_error;
};

struct WebUIDebugReport {
  url.mojom.Url url;
  double time;
  string body;
  DebugReportStatus status;
};

// Struct representing a stored attribution source that will be displayed by WebUI.
struct WebUISource {
  uint64 source_event_id;
  url.mojom.Origin source_origin;
  attribution_reporting.mojom.DestinationSet destinations;
  url.mojom.Origin reporting_origin;
  double source_time;
  double expiry_time;
  double event_report_window_time;
  double aggregatable_report_window_time;
  attribution_reporting.mojom.SourceType source_type;
  int64 priority;
  attribution_reporting.mojom.DebugKey? debug_key;
  array<uint64> dedup_keys;
  map<string, array<string>> filter_data;
  // The value is a hex-encoded unsigned 128-bit integer.
  map<string, string> aggregation_keys;
  uint64 aggregatable_budget_consumed;
  array<uint64> aggregatable_dedup_keys;

  enum Attributability {
    kAttributable,
    // The source was dropped due to `CommonSourceInfo::AttributionLogic::kNever`.
    kNoisedNever,
    // The source was dropped due to `CommonSourceInfo::AttributionLogic::kFalsely`.
    kNoisedFalsely,
    kReachedEventLevelAttributionLimit,
  };
  Attributability attributability;
};

struct WebUIRegistration {
  double time;
  url.mojom.Origin context_origin;
  url.mojom.Origin reporting_origin;
  // String instead of mojo_base.mojom.DictionaryValue because the value is
  // simply displayed in the UI, never inspected.
  string registration_json;
  attribution_reporting.mojom.DebugKey? cleared_debug_key;
};

struct WebUITrigger {
  WebUIRegistration registration;
  network.mojom.TriggerVerification? verification;

  enum Status {
    // Shared statuses:
    kSuccess,
    kInternalError,
    kNoMatchingSources,
    kNoMatchingSourceFilterData,
    kNoReportCapacityForDestinationSite,
    kExcessiveAttributions,
    kExcessiveReportingOrigins,
    kProhibitedByBrowserPolicy,
    kDeduplicated,
    kReportWindowPassed,
    kNotRegistered,

    // Event-level statuses:
    kLowPriority,
    kNoised,
    kNoMatchingConfigurations,
    kExcessiveEventLevelReports,

    // Aggregatable statuses:
    kNoHistograms,
    kInsufficientBudget,
  };

  Status event_level_status;
  Status aggregatable_status;
};

union SourceStatus {
  attribution_reporting.mojom.StoreSourceResult store_source_result;
  attribution_reporting.mojom.SourceRegistrationError json_error;
};

struct WebUISourceRegistration {
  WebUIRegistration registration;
  attribution_reporting.mojom.SourceType type;
  SourceStatus status;
};

// Struct containing info of successfully passed OS registrations to be
// displayed as a log by WebUI.
struct WebUIOsRegistration {
  // Contains msec since the Unix epoch, as returned by
  // base::Time::ToJsTimeIgnoringNull().
  double time;
  url.mojom.Url registration_url;
  url.mojom.Origin top_level_origin;
  bool is_debug_key_allowed;
  attribution_reporting.mojom.OsRegistrationType type;
  attribution_reporting.mojom.OsRegistrationResult result;
};

// Observer for events relevant to the attribution internals WebUI.
interface Observer {
  // Called when the sources in storage changed, indicating that the observer
  // should call `Handler::GetActiveSources()`.
  OnSourcesChanged();

  // Called when the reports in storage changed, indicating that the observer
  // should call `Handler::GetReports()`.
  OnReportsChanged();

  // Called when a source is registered, regardless of success or failure.
  OnSourceHandled(WebUISourceRegistration source);

  // Called when a report is sent, regardless of success.
  OnReportSent(WebUIReport report);

  // Called when a verbose debug report is sent, regardless of success.
  OnDebugReportSent(WebUIDebugReport report);

  // Called when a report is dropped from storage or prevented from being
  // created in the first place.
  OnReportDropped(WebUIReport report);

  // Called when a trigger is registered, regardless of success or failure.
  OnTriggerHandled(WebUITrigger trigger);

  // Called when an OS source or trigger is registered, regardless of success
  // or failure.
  OnOsRegistration(WebUIOsRegistration registration);
};

// Mojo interface for the attribution internals WebUI to communicate with the
// storage layer.
interface Handler {
  // Returns the state of the Attribution Reporting API in the WebUI's browsing context.
  // `attribution_support` is the `Attribution-Reporting-Support` request header value.
  IsAttributionReportingEnabled() => (bool enabled, bool debug_mode,
                                      string attribution_support);

  // Returns all active sources that are persisted in storage. This does
  // not include expired sources, or sources that can no longer be attributed
  // due to reaching policy limits.
  GetActiveSources() => (array<WebUISource> sources);

  // Returns all reports contained in storage, including those that are actively
  // being sent.
  GetReports() => (array<WebUIReport> reports);

  // Sends the given reports, ignoring delay, returning when the operation has
  // been completed and the reports have been cleared from storage.
  SendReports(array<ReportID> ids) => ();

  // Deletes all persisted data for the attribution reporting API, returning when the
  // operation has been completed.
  ClearStorage() => ();
};

// Factory for Observer and Handler.
interface Factory {
  // Binds the observer and handler.
  Create(pending_remote<Observer> observer,
         pending_receiver<Handler> handler);
};