The Battle for Wesnoth  1.19.0-dev
client.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2008 - 2024
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  const std::string& server_id() const
222  {
223  return server_id_;
224  }
225 
226  const std::string& server_version() const
227  {
228  return server_version_;
229  }
230 
231 private:
233 
234  std::string addr_;
235  std::string host_;
236  std::string port_;
237  std::unique_ptr<network_asio::connection> conn_;
238  std::string last_error_;
239  std::string last_error_data_;
240 
241  std::string server_id_;
242  std::string server_version_;
243  std::set<std::string> server_capabilities_;
244  std::string server_url_;
245  std::string license_notice_;
246 
247  /**
248  * Downloads the specified add-on from the server.
249  *
250  * @return @a true on success, @a false on failure. Retrieve the error message with @a get_last_server_error.
251  *
252  * @param archive_cfg Config object to hold the downloaded add-on archive data.
253  * @param id Add-on id.
254  * @param title Add-on title, used for status display.
255  * @param version Specifies an add-on version to download.
256  * @param increase_downloads Whether to request the server to increase the add-on's
257  * download count or not (e.g. when upgrading).
258  */
259  bool download_addon(config& archive_cfg, const std::string& id, const std::string& title, const version_info& version, bool increase_downloads = true);
260 
261  /**
262  * Installs the specified add-on using an archive received from the server.
263  *
264  * An _info.cfg file will be added to the local directory for the add-on
265  * to keep track of version and dependency information.
266  */
267  bool install_addon(config& archive_cfg, const addon_info& info);
268 
269  // Asks the client to download and install an addon, reporting errors in a gui dialog. Returns true if new content was installed, false otherwise.
270  bool try_fetch_addon(const addon_info& addon);
271 
272  /**
273  * Warns the user about unresolved dependencies and installs them if they choose to do so.
274  * Returns: outcome: abort in case the user chose to abort because of an issue
275  * success otherwise
276  * wml_change: indicates if new wml content was installed
277  */
279 
280  /** Checks whether the given add-on has local .pbl or VCS information and asks before overwriting it. */
282 
283  /** Makes sure the add-ons server connection is working. */
284  void check_connected() const;
285 
286  /**
287  * Sends a request to the add-ons server.
288  *
289  * @note This is an asynchronous operation. @a display_status_window
290  * should be called afterwards to wait for it to finish.
291  *
292  * @param request The client request WML.
293  * @param response A config object whose contents are replaced
294  * with the server response WML.
295  */
296  void send_request(const config& request, config& response);
297 
298  /**
299  * Sends a simple request message to the add-ons server.
300  *
301  * The real request sent consists of a WML object with an empty
302  * child node whose name corresponds to @a request_string
303  *
304  * @note This is an asynchronous operation. @a display_status_window
305  * should be called afterwards to wait for it to finish.
306  *
307  * @param request_string The client request string.
308  * @param response A config object whose contents are replaced
309  * with the server response WML.
310  */
311  void send_simple_request(const std::string& request_string, config& response);
312 
313  /**
314  * Waits for a network transfer, displaying a status window.
315  *
316  * The window is displayed with the specified contents. This
317  * method doesn't return until the network transfer is complete. It
318  * will throw a @a user_exit exception if the user cancels the
319  * transfer by canceling the status window.
320  */
321  void wait_for_transfer_done(const std::string& status_message, transfer_mode mode = transfer_mode::download);
322 
323  bool update_last_error(config& response_cfg);
324 
325  void clear_last_error();
326 
327  void clear_server_info();
328 };
Add-ons (campaignd) client class.
Definition: client.hpp:41
bool update_last_error(config &response_cfg)
Definition: client.cpp:598
std::string addr_
Definition: client.hpp:234
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:572
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:271
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:539
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:691
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:237
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...
const std::string & server_id() const
Definition: client.hpp:221
std::string port_
Definition: client.hpp:236
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:318
void send_request(const config &request, config &response)
Sends a request to the add-ons server.
Definition: client.cpp:641
bool request_addons_list(config &cfg)
Request the add-ons list from the server.
Definition: client.cpp:116
bool try_fetch_addon(const addon_info &addon)
Definition: client.cpp:413
std::string server_url_
Definition: client.hpp:244
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:235
void check_connected() const
Makes sure the add-ons server connection is working.
Definition: client.cpp:632
std::set< std::string > server_capabilities_
Definition: client.hpp:243
std::string server_id_
Definition: client.hpp:241
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:341
std::string license_notice_
Definition: client.hpp:245
bool using_tls() const
Returns whether the current connection uses TLS.
Definition: client.hpp:216
void clear_last_error()
Definition: client.cpp:617
std::string last_error_
Definition: client.hpp:238
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:239
std::string server_version_
Definition: client.hpp:242
void connect()
Tries to establish a connection to the add-ons server.
Definition: client.cpp:70
void send_simple_request(const std::string &request_string, config &response)
Sends a simple request message to the add-ons server.
Definition: client.cpp:649
bool request_distribution_terms(std::string &terms)
Request the add-ons server distribution terms message.
Definition: client.cpp:133
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:432
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:623
const std::string & addr() const
Returns the current hostname:port used for this connection.
Definition: client.hpp:74
const std::string & server_version() const
Definition: client.hpp:226
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:156
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:159
Represents version numbers.
std::map< std::string, addon_info > addons_list
Definition: info.hpp:27
logger & info()
Definition: log.cpp:314
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