blob: df21fdef619ea0c41d1dac061f6a750d52508d17 [file] [log] [blame]
Alex Deymoc705cc82014-02-19 11:15:00 -08001// Copyright (c) 2014 The Chromium OS 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
Gilad Arnold48415f12014-06-27 07:10:58 -07005#ifndef UPDATE_ENGINE_UPDATE_MANAGER_POLICY_H_
6#define UPDATE_ENGINE_UPDATE_MANAGER_POLICY_H_
Alex Deymoc705cc82014-02-19 11:15:00 -08007
Alex Deymo0d11c602014-04-23 20:12:20 -07008#include <string>
Gilad Arnoldb3b05442014-05-30 14:25:05 -07009#include <vector>
Alex Deymo0d11c602014-04-23 20:12:20 -070010
Gilad Arnoldb3b05442014-05-30 14:25:05 -070011#include "update_engine/error_code.h"
Alex Deymo63784a52014-05-28 10:46:14 -070012#include "update_engine/update_manager/evaluation_context.h"
13#include "update_engine/update_manager/state.h"
Alex Deymoc705cc82014-02-19 11:15:00 -080014
Alex Deymo63784a52014-05-28 10:46:14 -070015namespace chromeos_update_manager {
Alex Deymoc705cc82014-02-19 11:15:00 -080016
17// The three different results of a policy request.
Alex Deymoe636c3c2014-03-11 19:02:08 -070018enum class EvalStatus {
19 kFailed,
20 kSucceeded,
21 kAskMeAgainLater,
Alex Deymoc705cc82014-02-19 11:15:00 -080022};
23
Alex Deymo0d11c602014-04-23 20:12:20 -070024std::string ToString(EvalStatus status);
25
26// Parameters of an update check. These parameters are determined by the
27// UpdateCheckAllowed policy.
28struct UpdateCheckParams {
29 bool updates_enabled; // Whether the auto-updates are enabled on this build.
Gilad Arnold42f253b2014-06-25 12:39:17 -070030
31 // Attributes pertaining to the case where update checks are allowed.
32 //
33 // A target channel, if so imposed by policy; otherwise, an empty string.
34 std::string target_channel;
Alex Deymo0d11c602014-04-23 20:12:20 -070035};
36
Gilad Arnoldf62a4b82014-05-01 07:41:07 -070037// Input arguments to UpdateCanStart.
38//
39// A snapshot of the state of the current update process.
40struct UpdateState {
Gilad Arnoldb3b05442014-05-30 14:25:05 -070041 // Information pertaining to the Omaha update response.
42 //
Gilad Arnoldf62a4b82014-05-01 07:41:07 -070043 // Time when update was first offered by Omaha.
44 base::Time first_seen;
45 // Number of update checks returning the current update.
46 int num_checks;
Gilad Arnoldb3b05442014-05-30 14:25:05 -070047
48 // Information pertaining to the update download URL.
49 //
50 // An array of download URLs provided by Omaha.
51 std::vector<std::string> download_urls;
52 // Max number of failures allowed per download URL.
53 int download_failures_max;
54 // The index of the URL to use, as previously determined by the policy. This
55 // number is significant iff |num_checks| is greater than 1.
56 int download_url_idx;
57 // The number of failures already associated with this URL.
58 int download_url_num_failures;
59 // An array of failure error codes that occurred since the latest reported
60 // ones (included in the number above).
61 std::vector<chromeos_update_engine::ErrorCode> download_url_error_codes;
62
63 // Information pertaining to update scattering.
64 //
Gilad Arnoldf62a4b82014-05-01 07:41:07 -070065 // Scattering wallclock-based wait period, as returned by the policy.
66 base::TimeDelta scatter_wait_period;
67 // Maximum wait period allowed for this update, as determined by Omaha.
68 base::TimeDelta scatter_wait_period_max;
69 // Scattering update check threshold, as returned by the policy.
70 int scatter_check_threshold;
71 // Minimum/maximum check threshold values.
72 // TODO(garnold) These appear to not be related to the current update and so
Gilad Arnoldddd3fe32014-05-22 12:57:09 -070073 // should probably be obtained as variables via UpdaterProvider.
Gilad Arnoldf62a4b82014-05-01 07:41:07 -070074 int scatter_check_threshold_min;
75 int scatter_check_threshold_max;
76};
77
78// Results regarding the downloading and applying of an update, as determined by
79// UpdateCanStart.
80//
81// An enumerator for the reasons of not allowing an update to start.
82enum class UpdateCannotStartReason {
83 kUndefined,
84 kCheckDue,
Gilad Arnoldf62a4b82014-05-01 07:41:07 -070085 kScattering,
Gilad Arnoldb3b05442014-05-30 14:25:05 -070086 kCannotDownload,
Gilad Arnoldf62a4b82014-05-01 07:41:07 -070087};
88
Gilad Arnold42f253b2014-06-25 12:39:17 -070089struct UpdateDownloadParams {
Gilad Arnoldf62a4b82014-05-01 07:41:07 -070090 // Whether the update attempt is allowed to proceed.
91 bool update_can_start;
Gilad Arnoldb3b05442014-05-30 14:25:05 -070092
Gilad Arnoldf62a4b82014-05-01 07:41:07 -070093 // Attributes pertaining to the case where update is allowed. The update
94 // engine uses them to choose the means for downloading and applying an
95 // update.
Gilad Arnoldf62a4b82014-05-01 07:41:07 -070096 bool p2p_allowed;
Gilad Arnoldb3b05442014-05-30 14:25:05 -070097 // The index of the download URL to use, and the number of failures associated
98 // with this URL. An index value of -1 indicates that no suitable URL is
99 // available, but there may be other means for download (like P2P).
100 int download_url_idx;
101 int download_url_num_failures;
102
Gilad Arnoldf62a4b82014-05-01 07:41:07 -0700103 // Attributes pertaining to the case where update is not allowed. Some are
104 // needed for storing values to persistent storage, others for
105 // logging/metrics.
106 UpdateCannotStartReason cannot_start_reason;
107 base::TimeDelta scatter_wait_period; // Needs to be persisted.
108 int scatter_check_threshold; // Needs to be persisted.
109};
Alex Deymo0d11c602014-04-23 20:12:20 -0700110
Alex Deymoc705cc82014-02-19 11:15:00 -0800111// The Policy class is an interface to the ensemble of policy requests that the
112// client can make. A derived class includes the policy implementations of
113// these.
114//
115// When compile-time selection of the policy is required due to missing or extra
116// parts in a given platform, a different Policy subclass can be used.
117class Policy {
118 public:
119 virtual ~Policy() {}
120
Gilad Arnoldb3b05442014-05-30 14:25:05 -0700121 // Returns the name of a public policy request.
122 // IMPORTANT: Be sure to add a conditional for each new public policy that is
123 // being added to this class in the future.
124 template<typename R, typename... Args>
125 std::string PolicyRequestName(
126 EvalStatus (Policy::*policy_method)(EvaluationContext*, State*,
127 std::string*, R*,
128 Args...) const) const {
129 std::string class_name = PolicyName() + "::";
130
131 if (reinterpret_cast<typeof(&Policy::UpdateCheckAllowed)>(
132 policy_method) == &Policy::UpdateCheckAllowed)
133 return class_name + "UpdateCheckAllowed";
134 if (reinterpret_cast<typeof(&Policy::UpdateCanStart)>(
135 policy_method) == &Policy::UpdateCanStart)
136 return class_name + "UpdateCanStart";
Gilad Arnold684219d2014-07-07 14:54:57 -0700137 if (reinterpret_cast<typeof(&Policy::UpdateDownloadAllowed)>(
138 policy_method) == &Policy::UpdateDownloadAllowed)
139 return class_name + "UpdateDownloadAllowed";
Gilad Arnoldb3b05442014-05-30 14:25:05 -0700140
141 NOTREACHED();
142 return class_name + "(unknown)";
143 }
144
145
Alex Deymoc705cc82014-02-19 11:15:00 -0800146 // List of policy requests. A policy request takes an EvaluationContext as the
Alex Deymo2de23f52014-02-26 14:30:13 -0800147 // first argument, a State instance, a returned error message, a returned
148 // value and optionally followed by one or more arbitrary constant arguments.
Alex Deymoc705cc82014-02-19 11:15:00 -0800149 //
Alex Deymoe636c3c2014-03-11 19:02:08 -0700150 // When the implementation fails, the method returns EvalStatus::kFailed and
151 // sets the |error| string.
Alex Deymoc705cc82014-02-19 11:15:00 -0800152
153 // UpdateCheckAllowed returns whether it is allowed to request an update check
154 // to Omaha.
Alex Deymo0d11c602014-04-23 20:12:20 -0700155 virtual EvalStatus UpdateCheckAllowed(
156 EvaluationContext* ec, State* state, std::string* error,
157 UpdateCheckParams* result) const = 0;
Alex Deymoc705cc82014-02-19 11:15:00 -0800158
Gilad Arnoldf62a4b82014-05-01 07:41:07 -0700159 // Returns EvalStatus::kSucceeded if either an update can start being
160 // processed, or the attempt needs to be aborted. In cases where the update
161 // needs to wait for some condition to be satisfied, but none of the values
162 // that need to be persisted has changed, returns
163 // EvalStatus::kAskMeAgainLater. Arguments include an |interactive| flag that
164 // tells whether the update is user initiated, and an |update_state| that
Alex Vakulenko072359c2014-07-18 11:41:07 -0700165 // encapsulates data pertaining to the current ongoing update process.
Gilad Arnoldf62a4b82014-05-01 07:41:07 -0700166 virtual EvalStatus UpdateCanStart(
167 EvaluationContext* ec,
168 State* state,
169 std::string* error,
Gilad Arnold42f253b2014-06-25 12:39:17 -0700170 UpdateDownloadParams* result,
Gilad Arnoldf62a4b82014-05-01 07:41:07 -0700171 const bool interactive,
172 const UpdateState& update_state) const = 0;
Gilad Arnoldaf2f6ae2014-04-28 14:14:52 -0700173
Gilad Arnold684219d2014-07-07 14:54:57 -0700174 // Checks whether downloading of an update is allowed; currently, this checks
175 // whether the network connection type is suitable for updating over. May
176 // consult the shill provider as well as the device policy (if available).
Gilad Arnold0adbc942014-05-12 10:35:43 -0700177 // Returns |EvalStatus::kSucceeded|, setting |result| according to whether or
178 // not the current connection can be used; on failure, returns
179 // |EvalStatus::kFailed| and sets |error| accordingly.
Gilad Arnold684219d2014-07-07 14:54:57 -0700180 virtual EvalStatus UpdateDownloadAllowed(
Gilad Arnold0adbc942014-05-12 10:35:43 -0700181 EvaluationContext* ec,
182 State* state,
183 std::string* error,
184 bool* result) const = 0;
185
Alex Deymoc705cc82014-02-19 11:15:00 -0800186 protected:
187 Policy() {}
188
Gilad Arnoldb3b05442014-05-30 14:25:05 -0700189 // Returns the name of the actual policy class.
190 virtual std::string PolicyName() const = 0;
191
Alex Deymoc705cc82014-02-19 11:15:00 -0800192 private:
193 DISALLOW_COPY_AND_ASSIGN(Policy);
194};
195
Alex Deymo63784a52014-05-28 10:46:14 -0700196} // namespace chromeos_update_manager
Alex Deymoc705cc82014-02-19 11:15:00 -0800197
Gilad Arnold48415f12014-06-27 07:10:58 -0700198#endif // UPDATE_ENGINE_UPDATE_MANAGER_POLICY_H_