1// Copyright 2017 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5module blink.mojom;
6
7import "skia/public/mojom/bitmap.mojom";
8import "third_party/blink/public/mojom/cache_storage/cache_storage.mojom";
9import "third_party/blink/public/mojom/fetch/fetch_api_request.mojom";
10import "third_party/blink/public/mojom/fetch/fetch_api_response.mojom";
11import "third_party/blink/public/mojom/manifest/manifest.mojom";
12import "ui/gfx/geometry/mojom/geometry.mojom";
13
14enum BackgroundFetchError {
15  NONE,
16  DUPLICATED_DEVELOPER_ID,
17  INVALID_ARGUMENT,
18  INVALID_ID,
19  STORAGE_ERROR,
20  SERVICE_WORKER_UNAVAILABLE,
21  QUOTA_EXCEEDED,
22  PERMISSION_DENIED,
23  REGISTRATION_LIMIT_EXCEEDED
24};
25
26// Struct representing completed Background Fetch requests, along with their
27// responses.
28struct BackgroundFetchSettledFetch {
29  FetchAPIRequest request;
30  FetchAPIResponse? response;
31};
32
33enum BackgroundFetchResult {
34  UNSET,
35  FAILURE,
36  SUCCESS
37};
38
39// https://wicg.github.io/background-fetch/#enumdef-backgroundfetchfailurereason
40enum BackgroundFetchFailureReason {
41  // "":
42  NONE = 0,
43
44  // "aborted":
45  CANCELLED_FROM_UI = 1,
46  CANCELLED_BY_DEVELOPER = 2,
47
48  // "bad-status":
49  BAD_STATUS = 3,
50
51  // "fetch-error":
52  FETCH_ERROR = 4,
53  SERVICE_WORKER_UNAVAILABLE = 5,
54
55  // "quota-exceeded":
56  QUOTA_EXCEEDED = 6,
57
58  // "download-total-exceeded":
59  DOWNLOAD_TOTAL_EXCEEDED = 7,
60};
61
62// Represents the optional options a developer can provide when starting a new
63// Background Fetch fetch. Analogous to the following structure in the spec:
64// https://wicg.github.io/background-fetch/#background-fetch-manager
65struct BackgroundFetchOptions {
66  array<ManifestImageResource> icons;
67  uint64 download_total;
68  string title;
69};
70
71// Represents the information associated with a Background Fetch registration.
72// Analogous to the following structure in the spec:
73// https://wicg.github.io/background-fetch/#background-fetch-registration
74struct BackgroundFetchRegistrationData {
75  // Corresponds to IDL 'id' attribute. Not unique - an active registration can
76  // have the same |developer_id| as one or more inactive registrations.
77  string developer_id;
78
79  uint64 upload_total;
80  uint64 uploaded;
81  uint64 download_total;
82  uint64 downloaded;
83  BackgroundFetchResult result = BackgroundFetchResult.UNSET;
84  BackgroundFetchFailureReason failure_reason =
85      BackgroundFetchFailureReason.NONE;
86};
87
88// The registration data and interface to make per registration calls.
89struct BackgroundFetchRegistration {
90  BackgroundFetchRegistrationData registration_data;
91  pending_remote<BackgroundFetchRegistrationService> registration_interface;
92};
93
94// This contains the data we need to record UKM metrics, that isn't needed for
95// the background fetch itself.
96struct BackgroundFetchUkmData {
97  // Ratio of the icon size we display and that of the most suitable icon
98  // provided by the developer, times 100. -1 means that either the display
99  // size is empty, or no suitable icons have been provided.
100  int64 ideal_to_chosen_icon_size = -1;
101};
102
103interface BackgroundFetchRegistrationObserver {
104  // Notifies the BackgroundFetchRegistration about progress in the fetches that
105  // are part of it. The JavaScript `progress` event will be fired.
106  OnProgress(uint64 upload_total,
107             uint64 uploaded,
108             uint64 download_total,
109             uint64 downloaded,
110             BackgroundFetchResult result,
111             BackgroundFetchFailureReason failure_reason);
112
113  // Notifies the BackgroundFetchRegistration that the data for the associated
114  // fetch is no longer available. The mojo connection will be closed after
115  // this call.
116  OnRecordsUnavailable();
117
118  // Notifies the BackgroundFetchRegistration that the |request| has completed.
119  // |response| points to the completed response, if any.
120  OnRequestCompleted(FetchAPIRequest request,
121                     FetchAPIResponse? response);
122};
123
124// Interface for Background Fetch tasks. Lives in the browser process.
125// Implements Background Fetch over Mojo IPC RFC.
126interface BackgroundFetchService {
127  // Creates a new Background Fetch registration identified to the developer by
128  // |developer_id|, with the given |options| for the sequence of |requests|.
129  // Also passed along the |icon| to display.
130  Fetch(int64 service_worker_registration_id,
131        string developer_id,
132        array<FetchAPIRequest> requests,
133        BackgroundFetchOptions options,
134        skia.mojom.Bitmap? icon,
135        BackgroundFetchUkmData ukm_data)
136      => (BackgroundFetchError error,
137          BackgroundFetchRegistration? registration);
138
139  // Gets the active Background Fetch registration identified by |developer_id|.
140  GetRegistration(int64 service_worker_registration_id,
141                  string developer_id)
142      => (BackgroundFetchError error,
143          BackgroundFetchRegistration? registration);
144
145  // Gets the sequence of |developer_id|s for active Background Fetch
146  // registrations given the |service_worker_registration_id|.
147  GetDeveloperIds(int64 service_worker_registration_id)
148      => (BackgroundFetchError error,
149          array<string> developer_ids);
150
151  // Gets size of the icon to display with the Background Fetch UI.
152  GetIconDisplaySize()
153      => (gfx.mojom.Size icon_size_pixels);
154};
155
156// Interface for tasks that are linked to a registration.
157interface BackgroundFetchRegistrationService {
158  // Updates the user interface for the Background Fetch registration.
159  UpdateUI(string? title,
160           skia.mojom.Bitmap? icon)
161      => (BackgroundFetchError error);
162
163  // Aborts the Background Fetch registration.
164  // Fails if the registration had already completed/failed/aborted.
165  Abort() => (BackgroundFetchError error);
166
167  // Gets matching {request, response} pairs for the completed fetches.
168  MatchRequests(FetchAPIRequest? request_to_match,
169                CacheQueryOptions? cache_query_options,
170                bool match_all) => (array<BackgroundFetchSettledFetch> fetches);
171
172  // Registers the |observer| to receive events for the given registration.
173  AddRegistrationObserver(pending_remote<BackgroundFetchRegistrationObserver> observer);
174};
175