1 // Copyright 2012 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.
5 #ifndef CHROME_BROWSER_COMPONENT_UPDATER_COMPONENT_UPDATER_SERVICE_H_
6 #define CHROME_BROWSER_COMPONENT_UPDATER_COMPONENT_UPDATER_SERVICE_H_
11 #include "base/gtest_prod_util.h"
12 #include "base/version.h"
18 class DictionaryValue;
23 class URLRequestContextGetter;
28 class ResourceThrottle;
31 namespace component_updater {
33 class OnDemandUpdater;
35 // Component specific installers must derive from this class and implement
36 // OnUpdateError() and Install(). A valid instance of this class must be
37 // given to ComponentUpdateService::RegisterComponent().
38 class ComponentInstaller {
40 // Called by the component updater on the UI thread when there was a
41 // problem unpacking or verifying the component. |error| is a non-zero
42 // value which is only meaningful to the component updater.
43 virtual void OnUpdateError(int error) = 0;
45 // Called by the component updater when a component has been unpacked
46 // and is ready to be installed. |manifest| contains the CRX manifest
47 // json dictionary and |unpack_path| contains the temporary directory
48 // with all the unpacked CRX files.
49 virtual bool Install(const base::DictionaryValue& manifest,
50 const base::FilePath& unpack_path) = 0;
52 // Set |installed_file| to the full path to the installed |file|. |file| is
53 // the filename of the file in this component's CRX. Returns false if this is
54 // not possible (the file has been removed or modified, or its current
55 // location is unknown). Otherwise, returns true.
56 virtual bool GetInstalledFile(const std::string& file,
57 base::FilePath* installed_file) = 0;
59 virtual ~ComponentInstaller() {}
62 // Describes a particular component that can be installed or updated. This
63 // structure is required to register a component with the component updater.
64 // |pk_hash| is the SHA256 hash of the component's public key. If the component
65 // is to be installed then version should be "0" or "0.0", else it should be
66 // the current version. |fingerprint|, and |name| are optional.
67 // |allow_background_download| specifies that the component can be background
68 // downloaded in some cases. The default for this value is |true| and the value
69 // can be overriden at the registration time. This is a temporary change until
70 // the issue 340448 is resolved.
72 std::vector<uint8> pk_hash;
73 ComponentInstaller* installer;
75 std::string fingerprint;
77 bool allow_background_download;
84 // The component update service is in charge of installing or upgrading
85 // select parts of chrome. Each part is called a component and managed by
86 // instances of CrxComponent registered using RegisterComponent(). On the
87 // server, each component is packaged as a CRX which is the same format used
88 // to package extensions. To the update service each component is identified
89 // by its public key hash (CrxComponent::pk_hash). If there is an update
90 // available and its version is bigger than (CrxComponent::version), it will
91 // be downloaded, verified and unpacked. Then component-specific installer
92 // ComponentInstaller::Install (of CrxComponent::installer) will be called.
94 // During the normal operation of the component updater some specific
95 // notifications are fired, like COMPONENT_UPDATER_STARTED and
96 // COMPONENT_UPDATE_FOUND. See notification_type.h for more details.
98 // All methods are safe to call ONLY from chrome's UI thread.
99 class ComponentUpdateService {
101 enum Status { kOk, kReplaced, kInProgress, kError };
102 // Controls the component updater behavior.
105 virtual ~Configurator() {}
106 // Delay in seconds from calling Start() to the first update check.
107 virtual int InitialDelay() = 0;
108 // Delay in seconds to every subsequent update check. 0 means don't check.
109 virtual int NextCheckDelay() = 0;
110 // Delay in seconds from each task step. Used to smooth out CPU/IO usage.
111 virtual int StepDelay() = 0;
112 // Delay in seconds between applying updates for different components, if
113 // several updates are available at a given time.
114 virtual int StepDelayMedium() = 0;
115 // Minimum delta time in seconds before checking again the same component.
116 virtual int MinimumReCheckWait() = 0;
117 // Minimum delta time in seconds before an on-demand check is allowed
118 // for the same component.
119 virtual int OnDemandDelay() = 0;
120 // The url that is going to be used update checks over Omaha protocol.
121 virtual GURL UpdateUrl() = 0;
122 // The url where the completion pings are sent. Invalid if and only if
123 // pings are disabled.
124 virtual GURL PingUrl() = 0;
125 // Parameters added to each url request. It can be null if none are needed.
126 virtual std::string ExtraRequestParams() = 0;
127 // How big each update request can be. Don't go above 2000.
128 virtual size_t UrlSizeLimit() = 0;
129 // The source of contexts for all the url requests.
130 virtual net::URLRequestContextGetter* RequestContext() = 0;
131 // True means that all ops are performed in this process.
132 virtual bool InProcess() = 0;
133 // True means that this client can handle delta updates.
134 virtual bool DeltasEnabled() const = 0;
135 // True means that the background downloader can be used for downloading
136 // non on-demand components.
137 virtual bool UseBackgroundDownloader() const = 0;
140 // Defines an interface to observe ComponentUpdateService. It provides
141 // notifications when state changes occur for the service or for the
142 // registered components.
146 // Sent when the component updater starts doing update checks.
147 COMPONENT_UPDATER_STARTED,
149 // Sent when the component updater is going to take a long nap.
150 COMPONENT_UPDATER_SLEEPING,
152 // Sent when there is a new version of a registered component. After
153 // the notification is sent the component will be downloaded.
154 COMPONENT_UPDATE_FOUND,
156 // Sent when the new component has been downloaded and an installation
157 // or upgrade is about to be attempted.
158 COMPONENT_UPDATE_READY,
160 // Sent when a component has been successfully updated.
163 // Sent when a component has not been updated following an update check:
164 // either there was no update available, or an update failed.
165 COMPONENT_NOT_UPDATED,
167 // Sent when component bytes are being downloaded.
168 COMPONENT_UPDATE_DOWNLOADING,
171 virtual ~Observer() {}
173 // The component updater service will call this function when an interesting
174 // state change happens. If the |id| is specified, then the event is fired
175 // on behalf of a specific component. The implementors of this interface are
176 // expected to filter the relevant events based on the component id.
177 virtual void OnEvent(Events event, const std::string& id) = 0;
180 // Adds an observer for this class. An observer should not be added more
181 // than once. The caller retains the ownership of the observer object.
182 virtual void AddObserver(Observer* observer) = 0;
184 // Removes an observer. It is safe for an observer to be removed while
185 // the observers are being notified.
186 virtual void RemoveObserver(Observer* observer) = 0;
188 // Start doing update checks and installing new versions of registered
189 // components after Configurator::InitialDelay() seconds.
190 virtual Status Start() = 0;
192 // Stop doing update checks. In-flight requests and pending installations
193 // will not be canceled.
194 virtual Status Stop() = 0;
196 // Add component to be checked for updates. You can call this method
197 // before calling Start().
198 virtual Status RegisterComponent(const CrxComponent& component) = 0;
200 // Returns a list of registered components.
201 virtual std::vector<std::string> GetComponentIDs() const = 0;
203 // Returns an interface for on-demand updates. On-demand updates are
204 // proactively triggered outside the normal component update service schedule.
205 virtual OnDemandUpdater& GetOnDemandUpdater() = 0;
207 virtual ~ComponentUpdateService() {}
210 // Returns details about registered component in the |item| parameter. The
211 // function returns true in case of success and false in case of errors.
212 virtual bool GetComponentDetails(const std::string& component_id,
213 CrxUpdateItem* item) const = 0;
215 friend class ::ComponentsUI;
216 FRIEND_TEST_ALL_PREFIXES(ComponentUpdaterTest, ResourceThrottleLiveNoUpdate);
219 typedef ComponentUpdateService::Observer ServiceObserver;
221 class OnDemandUpdater {
223 virtual ~OnDemandUpdater() {}
225 // Returns a network resource throttle. It means that a component will be
226 // downloaded and installed before the resource is unthrottled. This function
227 // can be called from the IO thread. The function implements a cooldown
228 // interval of 30 minutes. That means it will ineffective to call the
229 // function before the cooldown interval has passed. This behavior is intended
230 // to be defensive against programming bugs, usually triggered by web fetches,
231 // where the on-demand functionality is invoked too often.
232 virtual content::ResourceThrottle* GetOnDemandResourceThrottle(
233 net::URLRequest* request,
234 const std::string& crx_id) = 0;
237 friend class OnDemandTester;
238 friend class ::ComponentsUI;
240 // Triggers an update check for a component. |component_id| is a value
241 // returned by GetCrxComponentID(). If an update for this component is already
242 // in progress, the function returns |kInProgress|. If an update is available,
243 // the update will be applied. The caller can subscribe to component update
244 // service notifications to get an indication about the outcome of the
245 // on-demand update. The function does not implement any cooldown interval.
246 virtual ComponentUpdateService::Status OnDemandUpdate(
247 const std::string& component_id) = 0;
250 // Creates the component updater. You must pass a valid |config| allocated on
251 // the heap which the component updater will own.
252 ComponentUpdateService* ComponentUpdateServiceFactory(
253 ComponentUpdateService::Configurator* config);
254 } // namespace component_updater
256 #endif // CHROME_BROWSER_COMPONENT_UPDATER_COMPONENT_UPDATER_SERVICE_H_