background_fetch.mojom | Explore in Territory

// Copyright 2017 The Chromium Authors
// 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/mojom/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/mojom/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 BackgroundFetchRegistrationData {
  // 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;

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

// The registration data and interface to make per registration calls.
struct BackgroundFetchRegistration {
  BackgroundFetchRegistrationData registration_data;
  pending_remote<BackgroundFetchRegistrationService> registration_interface;
};

// 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();

  // Notifies the BackgroundFetchRegistration that the |request| has completed.
  // |response| points to the completed response, if any.
  OnRequestCompleted(FetchAPIRequest request,
                     FetchAPIResponse? response);
};

// 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.BitmapN32? icon,
        BackgroundFetchUkmData ukm_data)
      => (BackgroundFetchError error,
          BackgroundFetchRegistration? registration);

  // 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);
};

// Interface for tasks that are linked to a registration.
interface BackgroundFetchRegistrationService {
  // Updates the user interface for the Background Fetch registration.
  UpdateUI(string? title,
           skia.mojom.BitmapN32? icon)
      => (BackgroundFetchError error);

  // Aborts the Background Fetch registration.
  // Fails if the registration had already completed/failed/aborted.
  Abort() => (BackgroundFetchError error);

  // Gets matching {request, response} pairs for the completed fetches.
  MatchRequests(FetchAPIRequest? request_to_match,
                CacheQueryOptions? cache_query_options,
                bool match_all) => (array<BackgroundFetchSettledFetch> fetches);

  // Registers the |observer| to receive events for the given registration.
  AddRegistrationObserver(pending_remote<BackgroundFetchRegistrationObserver> observer);
};
chromium/third_party/blink/public/mojom/background_fetch/background_fetch.mojom
