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

module blink.mojom;

import "skia/public/interfaces/bitmap.mojom";
import "third_party/blink/public/mojom/cache_storage/cache_storage.mojom";
import "third_party/blink/public/mojom/fetch/fetch_api_request.mojom";
import "third_party/blink/public/mojom/fetch/fetch_api_response.mojom";
import "third_party/blink/public/mojom/manifest/manifest.mojom";
import "ui/gfx/geometry/mojo/geometry.mojom";

enum BackgroundFetchError {
  NONE,
  DUPLICATED_DEVELOPER_ID,
  INVALID_ARGUMENT,
  INVALID_ID,
  STORAGE_ERROR,
  SERVICE_WORKER_UNAVAILABLE,
  QUOTA_EXCEEDED,
  PERMISSION_DENIED,
  REGISTRATION_LIMIT_EXCEEDED
};

// Struct representing completed Background Fetch requests, along with their
// responses.
struct BackgroundFetchSettledFetch {
  FetchAPIRequest request;
  FetchAPIResponse? response;
};

enum BackgroundFetchResult {
  UNSET,
  FAILURE,
  SUCCESS
};

// https://wicg.github.io/background-fetch/#enumdef-backgroundfetchfailurereason
enum BackgroundFetchFailureReason {
  // "":
  NONE = 0,

  // "aborted":
  CANCELLED_FROM_UI = 1,
  CANCELLED_BY_DEVELOPER = 2,

  // "bad-status":
  BAD_STATUS = 3,

  // "fetch-error":
  FETCH_ERROR = 4,
  SERVICE_WORKER_UNAVAILABLE = 5,

  // "quota-exceeded":
  QUOTA_EXCEEDED = 6,

  // "download-total-exceeded":
  DOWNLOAD_TOTAL_EXCEEDED = 7,
};

// Represents the optional options a developer can provide when starting a new
// Background Fetch fetch. Analogous to the following structure in the spec:
// https://wicg.github.io/background-fetch/#background-fetch-manager
struct BackgroundFetchOptions {
  array<ManifestImageResource> icons;
  uint64 download_total;
  string title;
};

// Represents the information associated with a Background Fetch registration.
// Analogous to the following structure in the spec:
// https://wicg.github.io/background-fetch/#background-fetch-registration
struct BackgroundFetchRegistration {
  // Corresponds to IDL 'id' attribute. Not unique - an active registration can
  // have the same |developer_id| as one or more inactive registrations.
  string developer_id;
  // Globally unique ID for the registration, generated in content/. Used to
  // distinguish registrations in case a developer re-uses |developer_id|s. Not
  // exposed to JavaScript.
  string unique_id;

  uint64 upload_total;
  uint64 uploaded;
  uint64 download_total;
  uint64 downloaded;
  BackgroundFetchResult result = BackgroundFetchResult.UNSET;
  BackgroundFetchFailureReason failure_reason =
      BackgroundFetchFailureReason.NONE;
};

// This contains the data we need to record UKM metrics, that isn't needed for
// the background fetch itself.
struct BackgroundFetchUkmData {
  // Ratio of the icon size we display and that of the most suitable icon
  // provided by the developer, times 100. -1 means that either the display
  // size is empty, or no suitable icons have been provided.
  int64 ideal_to_chosen_icon_size = -1;
};

interface BackgroundFetchRegistrationObserver {
  // Notifies the BackgroundFetchRegistration about progress in the fetches that
  // are part of it. The JavaScript `progress` event will be fired.
  OnProgress(uint64 upload_total,
             uint64 uploaded,
             uint64 download_total,
             uint64 downloaded,
             BackgroundFetchResult result,
             BackgroundFetchFailureReason failure_reason);

  // Notifies the BackgroundFetchRegistration that the data for the associated
  // fetch is no longer available. The mojo connection will be closed after
  // this call.
  OnRecordsUnavailable();
};

// Interface for Background Fetch tasks. Lives in the browser process.
// Implements Background Fetch over Mojo IPC RFC.
interface BackgroundFetchService {
  // Creates a new Background Fetch registration identified to the developer by
  // |developer_id|, with the given |options| for the sequence of |requests|.
  // Also passed along the |icon| to display.
  Fetch(int64 service_worker_registration_id,
        string developer_id,
        array<FetchAPIRequest> requests,
        BackgroundFetchOptions options,
        skia.mojom.Bitmap? icon,
        BackgroundFetchUkmData ukm_data)
      => (BackgroundFetchError error,
          BackgroundFetchRegistration? registration);

  // Updates the user interface for the Background Fetch registration identified
  // by |service_worker_registration_id|, |developer_id|, and |unique_id|.
  UpdateUI(int64 service_worker_registration_id,
           string developer_id,
           string unique_id,
           string? title,
           skia.mojom.Bitmap? icon)
      => (BackgroundFetchError error);

  // Aborts the Background Fetch registration identified by |unique_id| and
  // the developer's |developer_id|. Fails if the registration had already
  // completed/failed/aborted.
  Abort(int64 service_worker_registration_id,
        string developer_id,
        string unique_id)
      => (BackgroundFetchError error);

  // Gets the active Background Fetch registration identified by |developer_id|.
  GetRegistration(int64 service_worker_registration_id,
                  string developer_id)
      => (BackgroundFetchError error,
          BackgroundFetchRegistration? registration);

  // Gets the sequence of |developer_id|s for active Background Fetch
  // registrations given the |service_worker_registration_id|.
  GetDeveloperIds(int64 service_worker_registration_id)
      => (BackgroundFetchError error,
          array<string> developer_ids);

  // Gets size of the icon to display with the Background Fetch UI.
  GetIconDisplaySize()
      => (gfx.mojom.Size icon_size_pixels);

  // Gets matching {request, response} pairs for the completed fetches associated
  // with |service_worker_registration_id|, |developer_id|, and |unique_id|.
  // TODO(crbug.com/866874): Create a mojo interface for
  // BackgroundFetchRegistrationId, so we can avoid having to pass the first
  // three arguments in multiple methods.
  MatchRequests(int64 service_worker_registration_id,
                string developer_id,
                string unique_id,
                FetchAPIRequest? request_to_match,
                QueryParams? cache_query_params,
                bool match_all) => (array<BackgroundFetchSettledFetch> fetches);

  // Registers the |observer| to receive events for the given registration
  // that is identified by the |unique_id|.
  AddRegistrationObserver(string unique_id,
                          BackgroundFetchRegistrationObserver observer);
};