The Battle for Wesnoth  1.17.23+dev
client.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2008 - 2023
3  by Iris Morelle <shadowm2006@gmail.com>
4  Copyright (C) 2003 - 2008 by David White <dave@whitevine.net>
5  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
6 
7  This program is free software; you can redistribute it and/or modify
8  it under the terms of the GNU General Public License as published by
9  the Free Software Foundation; either version 2 of the License, or
10  (at your option) any later version.
11  This program is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY.
13 
14  See the COPYING file for more details.
15 */
16 
17 /**
18  * @file
19  * Networked add-ons (campaignd) client interface.
20  *
21  * This API revolves around the campaignd client functionality. It depends on
22  * the add-ons management and Asio network APIs.
23  */
24 
25 #pragma once
26 
27 #include "addon/info.hpp"
29 #include "network_asio.hpp"
30 
31 #include <set>
32 
33 /**
34  * Add-ons (campaignd) client class.
35  *
36  * This class encapsulates much of the logic behind the campaignd
37  * add-ons server interaction for the client-side. Most networking
38  * operations with it are implemented here.
39  */
41 {
42 public:
43  struct invalid_server_address : public std::exception {};
44  struct not_connected_to_server : public std::exception {};
45  struct user_exit : public std::exception {};
46  struct user_disconnect : public std::exception {};
47 
48  addons_client(const addons_client&) = delete;
50 
51  /**
52  * Constructor.
53  *
54  * @param address Server address (e.g. "localhost:15999").
55  */
56  explicit addons_client(const std::string& address);
57 
58  /**
59  * Tries to establish a connection to the add-ons server.
60  */
61  void connect();
62 
63  /**
64  * Disconnects from the add-on server.
65  */
66  void disconnect()
67  {
68  conn_.reset();
71  }
72 
73  /** Returns the current hostname:port used for this connection. */
74  const std::string& addr() const { return addr_; }
75 
76  /** Returns the last error message sent by the server, or an empty string. */
77  const std::string& get_last_server_error() const { return last_error_; }
78 
79  /** Returns the last error message extra data sent by the server, or an empty string. */
80  const std::string& get_last_server_error_data() const { return last_error_data_; }
81 
82  /** Returns true if the client is connected to the server. */
83  bool is_connected() { return conn_ != nullptr; }
84 
85  /**
86  * Request the add-ons list from the server.
87  *
88  * @return @a true on success, @a false on failure. Retrieve the error message with @a get_last_server_error.
89  *
90  * @param cfg A config object whose contents are replaced with
91  * the server's list if available, cleared otherwise.
92  */
93  bool request_addons_list(config& cfg);
94 
95  /**
96  * Retrieves the add-ons server web URL if available.
97  */
98  const std::string& server_url() const
99  {
100  return server_url_;
101  }
102 
103  /**
104  * Request the add-ons server distribution terms message.
105  */
106  bool request_distribution_terms(std::string& terms);
107 
108  /**
109  * Installation outcome values.
110  */
111  enum class install_outcome
112  {
113  /** The add-on was correctly installed. */
114  success,
115  /** The add-on could not be downloaded from the server. */
116  failure,
117  /** User aborted the operation because of an issue with dependencies or chose not to overwrite the add-on. */
118  abort,
119  };
120 
121  /**
122  * Contains the outcome of an add-on install operation.
123  */
125  {
126  /**
127  * Overall outcome of the operation.
128  */
130 
131  /**
132  * Specifies if WML on disk was altered and needs to be reloaded.
133  *
134  * @note Failure to install an add-on properly may not necessarily mean
135  * that WML on disk was left unchanged (e.g. if any dependencies were
136  * succesfully installed first.)
137  */
139  };
140 
141  /**
142  * Performs an add-on download and install cycle.
143  *
144  * This checks and prompts the user through the UI before overwriting an
145  * existing add-on with a .pbl file or version control system files (.git/,
146  * .svn/, etc.). It also resolves add-on dependencies and downloads them
147  * using the same system before downloading the original target add-on.
148  *
149  * @param addons Add-ons list used for resolving dependencies.
150  * @param addon Identity of the singular add-on that will be
151  * downloaded.
152  *
153  * @return An install_result with the outcome of the operation.
154  */
155  install_result install_addon_with_checks(const addons_list& addons, const addon_info& addon);
156 
157  /**
158  * Uploads an add-on to the server.
159  *
160  * This method reads the add-on upload passphrase and other data
161  * from the associated .pbl file. If the .pbl file doesn't have a
162  * passphrase, a new, random one will be automatically generated
163  * and written to the file for the user.
164  *
165  * @todo Notify the user about the automatic passphrase.
166  *
167  * @return @a true on success, @a false on failure. Retrieve the error message with @a get_last_server_error.
168  *
169  * @param id Id. of the add-on to upload.
170  * @param response_message The server response message on success, such as "add-on accepted".
171  * @param cfg The pbl config of the add-on with the specified id.
172  * @param local_only Whether the addon is not present on the server.
173  */
174  bool upload_addon(const std::string& id, std::string& response_message, config& cfg, bool local_only);
175 
176  /**
177  * Requests the specified add-on to be removed from the server.
178  *
179  * This method reads the add-on upload passphrase from the associated
180  * .pbl file.
181  *
182  * @return @a true on success, @a false on failure. Retrieve the error message with @a get_last_server_error.
183  *
184  * @param id Id. of the add-on to take down.
185  * @param response_message The server response message on success, such as "add-on accepted".
186  */
187  bool delete_remote_addon(const std::string& id, std::string& response_message);
188 
189  /**
190  * Returns whether the server supports the given named capability.
191  */
192  bool server_supports(const std::string& cap_id) const
193  {
194  return server_capabilities_.find(cap_id) != server_capabilities_.end();
195  }
196 
197  /**
198  * Returns whether the server supports incremental (delta) downloads and uploads.
199  */
201  {
202  return server_supports("delta");
203  }
204 
205  /**
206  * Returns whether the server supports passphrase authentication on an add-on basis.
207  */
209  {
210  return server_supports("auth:legacy");
211  }
212 
213  /**
214  * Returns whether the current connection uses TLS.
215  */
216  bool using_tls() const
217  {
218  return conn_ && conn_->using_tls();
219  }
220 
221 private:
223 
224  std::string addr_;
225  std::string host_;
226  std::string port_;
227  std::unique_ptr<network_asio::connection> conn_;
228  std::string last_error_;
229  std::string last_error_data_;
230 
231  std::string server_id_;
232  std::string server_version_;
233  std::set<std::string> server_capabilities_;
234  std::string server_url_;
235  std::string license_notice_;
236 
237  /**
238  * Downloads the specified add-on from the server.
239  *
240  * @return @a true on success, @a false on failure. Retrieve the error message with @a get_last_server_error.
241  *
242  * @param archive_cfg Config object to hold the downloaded add-on archive data.
243  * @param id Add-on id.
244  * @param title Add-on title, used for status display.
245  * @param version Specifies an add-on version to download.
246  * @param increase_downloads Whether to request the server to increase the add-on's
247  * download count or not (e.g. when upgrading).
248  */
249  bool download_addon(config& archive_cfg, const std::string& id, const std::string& title, const version_info& version, bool increase_downloads = true);
250 
251  /**
252  * Installs the specified add-on using an archive received from the server.
253  *
254  * An _info.cfg file will be added to the local directory for the add-on
255  * to keep track of version and dependency information.
256  */
257  bool install_addon(config& archive_cfg, const addon_info& info);
258 
259  // Asks the client to download and install an addon, reporting errors in a gui dialog. Returns true if new content was installed, false otherwise.
260  bool try_fetch_addon(const addon_info& addon);
261 
262  /**
263  * Warns the user about unresolved dependencies and installs them if they choose to do so.
264  * Returns: outcome: abort in case the user chose to abort because of an issue
265  * success otherwise
266  * wml_change: indicates if new wml content was installed
267  */
269 
270  /** Checks whether the given add-on has local .pbl or VCS information and asks before overwriting it. */
272 
273  /** Makes sure the add-ons server connection is working. */
274  void check_connected() const;
275 
276  /**
277  * Sends a request to the add-ons server.
278  *
279  * @note This is an asynchronous operation. @a display_status_window
280  * should be called afterwards to wait for it to finish.
281  *
282  * @param request The client request WML.
283  * @param response A config object whose contents are replaced
284  * with the server response WML.
285  */
286  void send_request(const config& request, config& response);
287 
288  /**
289  * Sends a simple request message to the add-ons server.
290  *
291  * The real request sent consists of a WML object with an empty
292  * child node whose name corresponds to @a request_string
293  *
294  * @note This is an asynchronous operation. @a display_status_window
295  * should be called afterwards to wait for it to finish.
296  *
297  * @param request_string The client request string.
298  * @param response A config object whose contents are replaced
299  * with the server response WML.
300  */
301  void send_simple_request(const std::string& request_string, config& response);
302 
303  /**
304  * Waits for a network transfer, displaying a status window.
305  *
306  * The window is displayed with the specified contents. This
307  * method doesn't return until the network transfer is complete. It
308  * will throw a @a user_exit exception if the user cancels the
309  * transfer by canceling the status window.
310  */
311  void wait_for_transfer_done(const std::string& status_message, transfer_mode mode = transfer_mode::download);
312 
313  bool update_last_error(config& response_cfg);
314 
315  void clear_last_error();
316 
317  void clear_server_info();
318 };
Add-ons (campaignd) client class.
Definition: client.hpp:41
bool update_last_error(config &response_cfg)
Definition: client.cpp:600
std::string addr_
Definition: client.hpp:224
void disconnect()
Disconnects from the add-on server.
Definition: client.hpp:66
install_result install_addon_with_checks(const addons_list &addons, const addon_info &addon)
Performs an add-on download and install cycle.
Definition: client.cpp:574
bool is_connected()
Returns true if the client is connected to the server.
Definition: client.hpp:83
bool delete_remote_addon(const std::string &id, std::string &response_message)
Requests the specified add-on to be removed from the server.
Definition: client.cpp:273
bool do_check_before_overwriting_addon(const addon_info &addon)
Checks whether the given add-on has local .pbl or VCS information and asks before overwriting it.
Definition: client.cpp:541
void wait_for_transfer_done(const std::string &status_message, transfer_mode mode=transfer_mode::download)
Waits for a network transfer, displaying a status window.
Definition: client.cpp:693
const std::string & get_last_server_error_data() const
Returns the last error message extra data sent by the server, or an empty string.
Definition: client.hpp:80
std::unique_ptr< network_asio::connection > conn_
Definition: client.hpp:227
install_outcome
Installation outcome values.
Definition: client.hpp:112
@ success
The add-on was correctly installed.
@ failure
The add-on could not be downloaded from the server.
@ abort
User aborted the operation because of an issue with dependencies or chose not to overwrite the add-on...
std::string port_
Definition: client.hpp:226
bool download_addon(config &archive_cfg, const std::string &id, const std::string &title, const version_info &version, bool increase_downloads=true)
Downloads the specified add-on from the server.
Definition: client.cpp:320
void send_request(const config &request, config &response)
Sends a request to the add-ons server.
Definition: client.cpp:643
bool request_addons_list(config &cfg)
Request the add-ons list from the server.
Definition: client.cpp:118
bool try_fetch_addon(const addon_info &addon)
Definition: client.cpp:415
std::string server_url_
Definition: client.hpp:234
const std::string & server_url() const
Retrieves the add-ons server web URL if available.
Definition: client.hpp:98
std::string host_
Definition: client.hpp:225
void check_connected() const
Makes sure the add-ons server connection is working.
Definition: client.cpp:634
std::set< std::string > server_capabilities_
Definition: client.hpp:233
std::string server_id_
Definition: client.hpp:231
bool install_addon(config &archive_cfg, const addon_info &info)
Installs the specified add-on using an archive received from the server.
Definition: client.cpp:343
std::string license_notice_
Definition: client.hpp:235
bool using_tls() const
Returns whether the current connection uses TLS.
Definition: client.hpp:216
void clear_last_error()
Definition: client.cpp:619
std::string last_error_
Definition: client.hpp:228
bool server_supports_delta() const
Returns whether the server supports incremental (delta) downloads and uploads.
Definition: client.hpp:200
addons_client(const addons_client &)=delete
bool server_supports_legacy_auth() const
Returns whether the server supports passphrase authentication on an add-on basis.
Definition: client.hpp:208
std::string last_error_data_
Definition: client.hpp:229
std::string server_version_
Definition: client.hpp:232
void connect()
Tries to establish a connection to the add-ons server.
Definition: client.cpp:72
void send_simple_request(const std::string &request_string, config &response)
Sends a simple request message to the add-ons server.
Definition: client.cpp:651
bool request_distribution_terms(std::string &terms)
Request the add-ons server distribution terms message.
Definition: client.cpp:135
install_result do_resolve_addon_dependencies(const addons_list &addons, const addon_info &addon)
Warns the user about unresolved dependencies and installs them if they choose to do so.
Definition: client.cpp:434
const std::string & get_last_server_error() const
Returns the last error message sent by the server, or an empty string.
Definition: client.hpp:77
void clear_server_info()
Definition: client.cpp:625
const std::string & addr() const
Returns the current hostname:port used for this connection.
Definition: client.hpp:74
bool upload_addon(const std::string &id, std::string &response_message, config &cfg, bool local_only)
Uploads an add-on to the server.
Definition: client.cpp:158
addons_client & operator=(const addons_client &)=delete
bool server_supports(const std::string &cap_id) const
Returns whether the server supports the given named capability.
Definition: client.hpp:192
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:161
Represents version numbers.
std::map< std::string, addon_info > addons_list
Definition: info.hpp:28
logger & info()
Definition: log.cpp:238
Contains the outcome of an add-on install operation.
Definition: client.hpp:125
install_outcome outcome
Overall outcome of the operation.
Definition: client.hpp:129
bool wml_changed
Specifies if WML on disk was altered and needs to be reloaded.
Definition: client.hpp:138