content/browser/attribution_reporting/attribution_internals.mojom

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

module content.mojom;

import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";

// Represents StorableSource::SourceType.
enum SourceType {
  kNavigation,
  kEvent,
};

struct AttributionReportID {
  int64 value;
};

// Struct containing stored data that will be sent in a future attribution
// report.
struct WebUIAttributionReport {
  // Allows the WebUI to issue commands for individual reports.
  // Not intended to be displayed.
  AttributionReportID? id;
  string attribution_destination;
  url.mojom.Url report_url;
  double trigger_time;
  double report_time;
  int64 priority;
  string report_body;
  bool attributed_truthfully;

  enum Status {
    kPending,
    kDroppedDueToRateLimiting,
    kDroppedDueToLowPriority,
    kDroppedForNoise,
    kProhibitedByBrowserPolicy,
    kSent,
    kNetworkError,
  };

  Status status;

  // Only valid if `status == kSent`.
  int32 http_response_code;
};

// Struct representing a stored attribution source that will be displayed by WebUI.
struct WebUIAttributionSource {
  uint64 source_event_id;
  url.mojom.Origin impression_origin;
  // Replace SchemefulSite with string if this struct is ever reused elsewhere.
  string attribution_destination;
  url.mojom.Origin reporting_origin;
  double impression_time;
  double expiry_time;
  SourceType source_type;
  int64 priority;
  array<int64> dedup_keys;

  enum Attributability {
    kAttributable,
    // The source was dropped due to `StorableSource::AttributionLogic::kNever`.
    kNoised,
    kReplacedByNewerSource,
    kReachedAttributionLimit,
  };
  Attributability attributability;
};

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

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

  // Called when a source is deactivated.
  OnSourceDeactivated(WebUIAttributionSource source);

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

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

// Mojo interface for the attribution internals WebUI to communicate with the
// storage layer.
interface AttributionInternalsHandler {
  // Returns whether attribution reporting and the debug mode are enabled in
  // the browsing context the WebUI is in.
  IsAttributionReportingEnabled() => (bool enabled, bool debug_mode);

  // 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<WebUIAttributionSource> sources);

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

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

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

  // Registers an observer to be notified of attribution reporting events.
  AddObserver(pending_remote<AttributionInternalsObserver> observer) => (bool success);
};