VLink  2.3.0
A high-performance communication middleware
proxy_api.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2026 by Thun Lu. All rights reserved.
3  * Author: Thun Lu <thun.lu@zohomail.cn>
4  * Repo: https://github.com/thun-res/vlink
5  * _ __ __ _ __
6  * | | / / / / (_) ____ / /__
7  * | | / / / / / / / __ \ / //_/
8  * | |/ / / /___ / / / / / / / ,<
9  * |___/ /_____/ /_/ /_/ /_/ /_/|_|
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 
24 /**
25  * @file proxy_api.h
26  * @brief Client-side C++ API for connecting to a @c ProxyServer daemon.
27  *
28  * @details
29  * @c ProxyAPI is the consumer-facing half of the VLink proxy subsystem. It connects
30  * to a running @c ProxyServer over a security-authenticated DDS channel set and
31  * exposes asynchronous callbacks for connection state, error transitions, server
32  * heartbeats, per-topic statistics, and (when active) raw payload bytes. The class
33  * inherits @c MessageLoop, so posted tasks, timers, handshake retries, and async
34  * control publishes execute inside the inherited loop once @c run() or
35  * @c async_run() has been started. Incoming DDS/SHM callbacks may still arrive on
36  * transport-managed receive threads.
37  *
38  * @par Roles
39  * Each instance is constructed with exactly one role.
40  *
41  * | Role | Description |
42  * | ---------------- | ----------------------------------------------------------------------- |
43  * | @c kController | Drives the server: may call @c send_control() and @c send_data(). |
44  * | @c kListener | Passive observer only; @c send_control() / @c send_data() return false. |
45  *
46  * @par Inheritance Pattern
47  * Both @c ProxyAPI and @c ProxyServer derive from @c MessageLoop. Application code
48  * may either embed a @c ProxyAPI directly or subclass it to centralise callback
49  * wiring.
50  * @code
51  * MessageLoop
52  * ^
53  * |
54  * ProxyAPI <-- this class (publicly inherits MessageLoop)
55  * ^
56  * |
57  * MyMonitor : public ProxyAPI
58  * - register_connect_callback()
59  * - register_info_callback()
60  * - register_data_callback()
61  * @endcode
62  *
63  * @par Operation Modes
64  * Selectable by a @c kController instance through @c Control::mode.
65  *
66  * | Mode | Value | Description |
67  * | ----------------------- | ----- | -------------------------------------------------------- |
68  * | @c kOffline | 0 | Disconnected; server releases all subscriptions. |
69  * | @c kObserveOne | 1 | Observe a single selected topic. |
70  * | @c kObserveAll | 2 | Observe every discovered topic. |
71  * | @c kRecord | 3 | Record every topic in the subscription URL list. |
72  * | @c kPlay | 4 | Playback / injection, usually fed by recorded data. |
73  * | @c kEdit | 5 | Forward data injected by the controller. |
74  * | @c kAuto | 6 | Observe selected topics and accept controller injection. |
75  * | @c kAutoAndObserveAll | 7 | Observe every topic and accept controller injection. |
76  *
77  * @par Error Codes
78  *
79  * | Error | Value | Description |
80  * | ----------------------- | ----- | --------------------------------------------------------------- |
81  * | @c kNoError | 0 | No error. |
82  * | @c kModeError | 1 | Reserved legacy code for unsupported modes. |
83  * | @c kControlError | 2 | Control ID mismatch with the server. |
84  * | @c kReliableCompError | 3 | @c reliable setting mismatch between client and server. |
85  * | @c kTcpCompError | 4 | @c enable_tcp setting mismatch. |
86  * | @c kDirectCompError | 5 | @c direct setting mismatch. |
87  * | @c kMultiProxyError | 7 | Multiple proxy servers or @c Time identity mismatch. |
88  * | @c kVersionCompError | 8 | VLink version mismatch between client and server. |
89  * | @c kTokenError | 9 | Handshake refused/empty token, or same-identity token mismatch. |
90  * | @c kUnknownError | 10 | Unknown or unclassified error. |
91  *
92  * @par Connectivity, Handshake, and Heartbeat
93  * Internally the API subscribes to the 1-second @c Time heartbeat published by
94  * @c ProxyServer. When @c VLINK_PROXY_ENABLE_HANDSHAKE is non-zero (default), it
95  * also runs an RPC handshake against the server's security-authenticated handshake
96  * service before any @c Control may be published; the server replies with a
97  * per-process @em token that the API caches under a dedicated mutex and stamps onto
98  * every outgoing @c Control. A refused or empty token raises @c kTokenError, while
99  * handshake setup/connect/invoke timeouts are treated as channel-not-ready and
100  * retried silently. Every incoming heartbeat must come from the same server
101  * identity and carry the same token: identity mismatch raises @c kMultiProxyError,
102  * an identity-matching token mismatch raises @c kTokenError; both paths clear the
103  * cached token and retry the handshake. After five consecutive seconds without a
104  * heartbeat the connection is declared lost and @c ConnectCallback fires with
105  * @c connected=false. A @c kController instance caches and posts an initial
106  * @c kAuto @c Control at construction and re-sends the last control automatically
107  * once the server reconnects; actual publication waits for the loop, handshake, and
108  * transport handles to be ready. When the macro is @c 0, the handshake is bypassed
109  * and controls flow without any token field.
110  *
111  * @par Channel Configuration
112  *
113  * | @c direct | Data path | Control / Info / Time / Handshake path |
114  * | --------- | ------------------------------------------ | -------------------------------------- |
115  * | false | Server-relayed DDS data channel | DDS (security-enabled) |
116  * | true | Local direct SHM publishers / subscribers | DDS (security-enabled) |
117  *
118  * @par Version Matching
119  * When @c Config::match_version is @c true (default) the client cross-checks the
120  * server's @c VLINK_VERSION string at connection time and reports
121  * @c kVersionCompError on mismatch.
122  *
123  * @par Example (Controller)
124  * @code
125  * vlink::ProxyAPI::Config cfg;
126  * cfg.role = vlink::ProxyAPI::kController;
127  * cfg.dds_impl = "dds";
128  * cfg.domain_id = 0;
129  * cfg.reliable = false;
130  * cfg.match_version = true;
131  *
132  * vlink::ProxyAPI api(cfg);
133  * api.register_connect_callback([](bool connected) {
134  * if (connected) {
135  * // server online
136  * }
137  * });
138  * api.register_info_callback([](const std::vector<vlink::ProxyAPI::Info>& list) {
139  * for (const auto& info : list) {
140  * // info.url, info.freq, info.status, ...
141  * }
142  * });
143  * api.async_run(); // start the loop so handshake/timers can run
144  *
145  * vlink::ProxyAPI::Control ctrl;
146  * ctrl.mode = vlink::ProxyAPI::kObserveOne;
147  * ctrl.url_meta_list.push_back(
148  * {"dds://my/topic", "demo.proto.PointCloud", vlink::SchemaType::kProtobuf, vlink::kSubscriber});
149  * api.send_control(ctrl);
150  * @endcode
151  *
152  * @note
153  * - Only one @c ProxyServer should exist on a given DDS domain at a time; reaching
154  * two will trigger @c kMultiProxyError.
155  * - @c send_control() and @c send_data() return @c false immediately for
156  * @c kListener instances.
157  */
158 
159 #pragma once
160 
161 #undef VLINK_PROXY_API_EXPORT
162 #ifdef VLINK_PROXY_API_LIBRARY_STATIC
163 #define VLINK_PROXY_API_EXPORT
164 #elif defined(_WIN32) || defined(__CYGWIN__)
165 #ifdef VLINK_PROXY_API_LIBRARY
166 #define VLINK_PROXY_API_EXPORT __declspec(dllexport)
167 #else
168 #define VLINK_PROXY_API_EXPORT __declspec(dllimport)
169 #endif
170 #else
171 #define VLINK_PROXY_API_EXPORT __attribute__((visibility("default")))
172 #endif
173 
174 #include <cstdint>
175 #include <memory>
176 #include <string>
177 #include <unordered_set>
178 #include <vector>
179 
180 #include "../base/bytes.h"
181 #include "../base/functional.h"
182 #include "../base/message_loop.h"
183 #include "../impl/types.h"
184 
185 namespace vlink {
186 
187 /**
188  * @class ProxyAPI
189  * @brief Client-side proxy monitoring and control surface backed by a @c MessageLoop.
190  *
191  * @details
192  * Connects to a @c ProxyServer over security-authenticated DDS control channels and
193  * exposes registration entry points for connection state, error transitions,
194  * heartbeat timestamps, per-topic statistics, and raw data payloads. In direct mode
195  * data payloads ride on locally-created SHM channels instead of the server-relayed
196  * data channel. Inherits @c MessageLoop; start the loop with @c run() or
197  * @c async_run() so the handshake retries, heartbeat timer, handle reset, and async
198  * control posts can execute.
199  */
201  public:
202  /**
203  * @enum Mode
204  * @brief Proxy operation modes published via @c send_control().
205  *
206  * @details
207  * The mode governs what the @c ProxyServer observes or what the controller may
208  * inject. Only a @c kController instance may switch the mode.
209  */
210  enum Mode : uint8_t {
211  kOffline = 0, ///< Disconnected; server releases every subscription.
212  kObserveOne = 1, ///< Observe a single topic taken from the URL list.
213  kObserveAll = 2, ///< Observe every discovered topic on the network.
214  kRecord = 3, ///< Record data from topics in the URL list.
215  kPlay = 4, ///< Injection/playback mode, usually fed by recorded data.
216  kEdit = 5, ///< Forward data injected by the controller.
217  kAuto = 6, ///< Observe specified URLs and accept controller injection.
218  kAutoAndObserveAll = 7, ///< Observe every topic and accept controller injection.
219  };
220 
221  /**
222  * @enum Error
223  * @brief Compatibility and protocol error codes reported through @c ErrorCallback.
224  *
225  * @details
226  * Errors are produced when the client parses an incoming @c Time heartbeat or a
227  * handshake response; the callback fires only when the error state changes.
228  */
229  enum Error : uint8_t {
230  kNoError = 0, ///< No error; the connection is healthy.
231  kModeError = 1, ///< Reserved legacy code; unsupported modes are ignored server-side.
232  kControlError = 2, ///< Server responded with a different @c control_id.
233  kReliableCompError = 3, ///< @c reliable setting differs between client and server.
234  kTcpCompError = 4, ///< @c enable_tcp setting differs between client and server.
235  kDirectCompError = 5, ///< @c direct setting differs between client and server.
236  kMultiProxyError = 7, ///< Multiple proxy servers, or Time identity differs from the handshake.
237  kVersionCompError = 8, ///< @c VLINK_VERSION string differs between client and server.
238  kTokenError = 9, ///< Handshake refused/empty token or identity-matching token mismatch.
239  kUnknownError = 10, ///< Unknown or unclassified error.
240  };
241 
242  /**
243  * @enum Status
244  * @brief Per-topic activity status reported inside @c Info records.
245  */
246  enum Status : uint8_t {
247  kActive = 0, ///< Topic is actively receiving data.
248  kInActive = 1, ///< Topic exists but has not produced data recently.
249  kPending = 2, ///< Topic was just discovered; statistics are still accumulating.
250  kInvalid = 3, ///< Topic type does not support observation (e.g. subscriber-only).
251  };
252 
253  /**
254  * @enum Role
255  * @brief Role this @c ProxyAPI instance plays towards the @c ProxyServer.
256  *
257  * @details
258  * @c kController may call @c send_control() and @c send_data(). @c kListener is
259  * a passive observer; send calls return @c false immediately. In direct mode,
260  * it follows the server's current subscription selection through periodic heartbeats,
261  * including when it joins after the controller has sent its selection.
262  */
263  enum Role : uint8_t { kController = 0, kListener };
264 
265  /**
266  * @struct Process
267  * @brief Description of a VLink node process attached to a topic endpoint.
268  */
269  struct Process final {
270  uint32_t type{0}; ///< Bitmask of @c ImplType kinds advertised by this process.
271  std::string host; ///< Hostname of the machine running the process.
272  uint32_t pid{0}; ///< Operating-system process ID.
273  std::string name; ///< Human-readable process name.
274  std::vector<std::string> ip_list; ///< Live discovery source IPv4 addresses, unique and sorted numerically.
275  };
276 
277  /**
278  * @struct Info
279  * @brief Statistics and metadata describing one discovered topic endpoint.
280  *
281  * @details
282  * Delivered in batches through @c InfoCallback once per second. @c freq, @c rate,
283  * @c loss, and @c latency are weighted moving averages over the last two
284  * one-second collection intervals.
285  */
286  struct Info final {
287  uint32_t type{0}; ///< Node-type bitmask for this endpoint.
288  std::string url; ///< Full topic URL, e.g. @c "dds://my/topic".
289  std::string ser; ///< Serialisation type, e.g. @c "demo.proto.PointCloud".
290  SchemaType schema{SchemaType::kUnknown}; ///< Coarse schema family of the payload.
291  Status status{kInvalid}; ///< Current activity status of the topic.
292  float freq{0}; ///< Observed message rate in messages/s.
293  uint64_t rate{0}; ///< Observed throughput in bytes/s.
294  float loss{0}; ///< Sample loss ratio in the range [0, 1].
295  float latency{0}; ///< Latency in ms; @c -1 = no sample, @c -2 = invalid.
296  std::vector<Process> process_list; ///< Connected publisher/subscriber processes.
297  };
298 
299  /**
300  * @struct UrlMeta
301  * @brief Pairs a topic URL with its serialisation type and node role.
302  *
303  * @details
304  * Carried in @c Control::url_meta_list to tell the server which topics to
305  * subscribe to or publish on. Use @c kSubscriber to observe a topic (field
306  * reception is inferred from discovery), @c kPublisher to inject events, or
307  * @c kSetter to inject field updates. Field injection requires both proxy
308  * peers to support @c kSetter routes.
309  */
310  struct UrlMeta final {
311  std::string url; ///< Full topic URL.
312  std::string ser; ///< Required serialisation type on this proxy route.
313  SchemaType schema{SchemaType::kUnknown}; ///< Required coarse schema family on this proxy route.
314  ImplType type{kSubscriber}; ///< Observer (@c kSubscriber), event writer or field writer.
315  };
316 
317  /**
318  * @struct Control
319  * @brief Control message sent from a @c kController instance to @c ProxyServer.
320  *
321  * @details
322  * Sets the server's operating mode and the list of topics to observe, record, or
323  * inject/play. @c filter_str is a space- or comma-separated set of substrings; entries
324  * must contain at least one substring to be included. When @c filter_by_process
325  * is @c true, the filter is matched against process names instead of URLs.
326  */
327  struct Control final {
328  Mode mode{kOffline}; ///< Target operation mode.
329  std::vector<UrlMeta> url_meta_list; ///< Topics to observe / record / inject (mode-dependent).
330  bool filter_by_process{false}; ///< When true, @c filter_str matches process names; otherwise URLs.
331  std::string filter_str; ///< Space- or comma-separated filter keywords (case-insensitive).
332  uint32_t filter_type{0}; ///< Type filter: 0=all, 1=pub+sub pair, 2=srv+cli pair, etc.
333  bool bridge{false}; /**< Mark bridge-injected event publishers in global discovery. */
334  };
335 
336  /**
337  * @struct Data
338  * @brief Raw message payload delivered via @c DataCallback or sent via @c send_data().
339  *
340  * @details
341  * In non-direct observe/record modes the server relays raw serialised bytes plus
342  * routing metadata. In direct mode the callback is fed by the local direct
343  * subscriber created by @c ProxyAPI. When sending data, @c timestamp and @c seq
344  * are caller-defined and forwarded verbatim.
345  */
346  struct Data final {
347  std::string url; ///< Topic URL the data was captured on.
348  std::string ser; ///< Serialisation type of the payload.
349  SchemaType schema{SchemaType::kUnknown}; ///< Coarse schema family of the payload.
350  Bytes raw; ///< Raw serialised message bytes.
351  int64_t timestamp{-1}; ///< Sender/session timestamp in microseconds; @c -1 if unset.
352  int64_t seq{0}; ///< Sender or relay sequence number for the URL.
353  };
354 
355  /**
356  * @struct Config
357  * @brief Construction-time configuration aggregate for @c ProxyAPI.
358  *
359  * @details
360  * Every field must be set consistently with the @c ProxyServer::Config the
361  * instance connects to. A mismatch on @c reliable, @c enable_tcp, or @c direct
362  * raises the corresponding @c Error code on the first heartbeat received.
363  */
364  struct Config final {
365  Role role{kController}; ///< Role of this client instance.
366  int domain_id{0}; ///< DDS domain ID; must match the server's @c domain_id.
367  std::string dds_impl{"dds"}; ///< DDS implementation: "dds", "ddsc", "ddsr", etc.
368  std::string security_key; ///< Optional security key; empty selects the default slot.
369  bool native{false}; ///< Bind all DDS endpoints to @c VLINK_DDS_NATIVE_IP (default @c 127.0.0.1).
370  bool reliable{false}; ///< Use reliable DDS QoS; must match the server.
371  bool direct{false}; ///< Use direct SHM channels for data; must match the server.
372  bool enable_tcp{false}; ///< Use TCP transport for data channels; must match the server.
373  bool match_version{true}; ///< Reject when the server's @c VLINK_VERSION differs from this client.
374  std::string allow_ip; ///< Bind DDS sockets to this IP (empty = any).
375  std::string peer_ip; ///< Unicast peer IP for DDS discovery (empty = multicast).
376  int buf_size{0}; ///< Socket send/receive buffer in bytes; 0 = default.
377  int mtu_size{0}; ///< DDS MTU size in bytes; 0 = default.
378  };
379 
380  /**
381  * @brief Callback fired when the connection state with @c ProxyServer changes.
382  *
383  * @details
384  * @c connected becomes @c true on the first valid heartbeat and @c false after
385  * five seconds of heartbeat silence or when the control channel reports
386  * disconnection.
387  */
388  using ConnectCallback = MoveFunction<void(bool connected)>;
389 
390  /**
391  * @brief Callback fired on each error-state transition.
392  *
393  * @details
394  * Only invoked when @c Error changes -- for instance from @c kNoError to
395  * @c kVersionCompError, or back to @c kNoError.
396  */
397  using ErrorCallback = MoveFunction<void(Error error)>;
398 
399  /**
400  * @brief Callback delivering the server's wall-clock and boot-time from each heartbeat.
401  *
402  * @param sys_time Server system time in microseconds since the Unix epoch.
403  * @param boot_time Server uptime in microseconds since boot.
404  */
405  using TimeCallback = MoveFunction<void(uint64_t sys_time, uint64_t boot_time)>;
406 
407  /**
408  * @brief Callback delivering the per-topic statistics list once per second.
409  *
410  * @param info_list Filtered discovery records relevant to the current mode,
411  * including their status fields.
412  */
413  using InfoCallback = MoveFunction<void(const std::vector<Info>& info_list)>;
414 
415  /**
416  * @brief Callback delivering raw message data from the active proxy data path.
417  *
418  * @details
419  * Fires for every message forwarded in observe, record, or auto modes. In
420  * non-direct mode the bytes are relayed by @c ProxyServer; in direct mode they
421  * come from local direct subscribers. @c Data::raw is shallow-borrowed -- copy
422  * it if you must retain it past the callback.
423  */
424  using DataCallback = MoveFunction<void(const Data& data)>;
425 
426  /**
427  * @brief Constructs a @c ProxyAPI using the supplied configuration.
428  *
429  * @details
430  * Stores @p config, starts the internal heartbeat timer, and derives a unique
431  * @c control_id from the CPU timestamp so the server can distinguish concurrent
432  * controllers. Transport handles are created by @c reset_handle(), which runs
433  * when the inherited @c MessageLoop starts and again whenever the reconnect logic
434  * resets the connection. A controller also caches and posts an initial @c kAuto
435  * @c Control, but it is only published once the loop, handshake, and transport
436  * handles are all ready.
437  *
438  * @param config Configuration for the proxy connection.
439  */
440  explicit ProxyAPI(const Config& config);
441 
442  /**
443  * @brief Destroys the @c ProxyAPI and releases every transport handle.
444  *
445  * @details
446  * Quits the inherited @c MessageLoop (if running), waits for it to stop, then
447  * releases DDS/SHM handles. For controller instances, normal @c MessageLoop
448  * shutdown publishes @c kOffline from @c on_end().
449  */
450  ~ProxyAPI() override;
451 
452  /**
453  * @brief Registers a callback for connection-state changes.
454  *
455  * @details
456  * If the API is already connected when the registration runs, the callback is
457  * invoked immediately with @c connected=true inside this call. Callbacks are
458  * replaced atomically; only one callback is active at a time.
459  *
460  * @param callback Callable with signature @c void(bool connected).
461  */
463 
464  /**
465  * @brief Registers a callback for error-state transitions.
466  *
467  * @details
468  * If a non-zero error is already active at registration time, the callback fires
469  * immediately with the current error inside this call.
470  *
471  * @param callback Callable with signature @c void(Error error).
472  */
474 
475  /**
476  * @brief Registers a callback for heartbeat timestamp delivery.
477  *
478  * @details
479  * If timestamps have already been received (timers active) the callback is
480  * invoked immediately with the latest extrapolated values inside this call.
481  *
482  * @param callback Callable with signature @c void(uint64_t sys_time, uint64_t boot_time).
483  */
485 
486  /**
487  * @brief Registers a callback for per-topic statistics updates.
488  *
489  * @details
490  * Invoked once per second with the full @c Info list from the server. There is
491  * no immediate invocation at registration; data arrives on the next server
492  * broadcast cycle.
493  *
494  * @param callback Callable with signature @c void(const std::vector<Info>& info_list).
495  */
497 
498  /**
499  * @brief Registers a callback for raw message data relayed by the server.
500  *
501  * @details
502  * There is no immediate invocation at registration time. Data arrives when the
503  * server is in a mode that forwards messages: @c kObserveOne, @c kObserveAll,
504  * @c kRecord, @c kAuto, or @c kAutoAndObserveAll.
505  *
506  * @param callback Callable with signature @c void(const Data& data).
507  */
509 
510  /**
511  * @brief Publishes a @c Control message to the @c ProxyServer.
512  *
513  * @details
514  * Valid only for the @c kController role; returns @c false immediately for
515  * @c kListener. The control is cached internally and automatically re-sent when
516  * the server reconnects after a dropout.
517  *
518  * When @p async is @c true (default) the DDS @c Control publish is posted to the
519  * @c MessageLoop thread and the return value reports only whether posting was
520  * accepted. When @p async is @c false the publish runs synchronously on the
521  * calling thread and the return value reports the publish result. In direct
522  * mode, direct-map synchronisation is still queued on the @c MessageLoop, so the
523  * return value also depends on whether that enqueue was accepted.
524  *
525  * Entries in @c control.url_meta_list are encoded using their supplied @c ser and
526  * @c schema verbatim. Proxy no longer back-fills missing routing metadata from
527  * discovery caches: entries with an empty @c ser or unknown @c schema are ignored
528  * by the direct-map sync path and cannot become usable server-side routes.
529  *
530  * In @c direct mode, matching local SHM publishers are created or destroyed to
531  * mirror the publisher entries. Direct subscribers are synchronised either from
532  * subscriber entries in @c url_meta_list or, for @c kObserveAll and
533  * @c kAutoAndObserveAll, from the latest @c Info list reported by the server.
534  * Setter endpoints are observed with getter semantics so field updates keep
535  * their last-value behaviour.
536  *
537  * @param control Control message to send.
538  * @param async @c true to post asynchronously (default); @c false to block.
539  * @return When @p async=false, @c true means the DDS publish succeeded and
540  * any direct-map sync was queued. When @p async=true, @c true
541  * means the publish task was accepted. @c false on listener role,
542  * shutdown, or enqueue/publish failure.
543  *
544  * @note Thread-safe. The control is also stored as the last-known control for
545  * automatic resend on reconnect.
546  */
547  bool send_control(const Control& control, bool async = true);
548 
549  /**
550  * @brief Injects raw message data into the proxy data path.
551  *
552  * @details
553  * Valid only for the @c kController role; returns @c false for @c kListener. In
554  * @c direct mode the data is published through the local SHM publisher matching
555  * @c data.url and @c ProxyServer is not on the data relay path. In non-direct
556  * mode the payload is wrapped in a @c ProxyData envelope and forwarded over the
557  * DDS data channel. Returns @c false if no subscribers are listening on the
558  * target channel.
559  *
560  * The caller must provide both @c data.ser and a known @c data.schema. Proxy no
561  * longer guesses the decode stack from cached discovery metadata.
562  *
563  * @param data Data to inject: URL, serialisation type, schema family, raw bytes,
564  * timestamp, and sequence number.
565  * @return In non-direct mode, @c true only if the underlying data publish
566  * succeeds. In direct mode, @c true means a matching local direct
567  * publisher and subscriber were found, metadata matched, and the
568  * publish attempt was made (backend result is not surfaced).
569  * @c false otherwise.
570  */
571  bool send_data(const Data& data);
572 
573  /**
574  * @brief Returns the configuration supplied at construction.
575  *
576  * @return Const reference to the internal @c Config aggregate.
577  */
578  [[nodiscard]] const Config& get_current_config() const;
579 
580  /**
581  * @brief Returns the most recently requested proxy operation mode.
582  *
583  * @details
584  * Reflects the mode most recently set through @c send_control(). Updated on the
585  * calling thread before any async DDS publish.
586  *
587  * @return Current @c Mode value.
588  */
589  [[nodiscard]] Mode get_current_mode() const;
590 
591  /**
592  * @brief Returns the current error state.
593  *
594  * @return Current @c Error value; @c kNoError when no error is active.
595  */
596  [[nodiscard]] Error get_current_error() const;
597 
598  /**
599  * @brief Returns the hostname of the connected @c ProxyServer.
600  *
601  * @details
602  * With handshake enabled, initialised from the successful handshake response and
603  * cross-checked against @c Time heartbeats. Without handshake, populated from
604  * the first valid heartbeat. Empty before any server identity is accepted and
605  * after disconnection.
606  *
607  * @return Server hostname, or empty when unavailable.
608  */
609  [[nodiscard]] std::string get_current_hostname() const;
610 
611  /**
612  * @brief Returns the machine ID of the connected @c ProxyServer.
613  *
614  * @details
615  * With handshake enabled, initialised from the successful handshake response and
616  * cross-checked against @c Time heartbeats. Without handshake, populated from
617  * the first valid heartbeat. Empty before any server identity is accepted and
618  * after disconnection.
619  *
620  * @return Server machine ID, or empty when unavailable.
621  */
622  [[nodiscard]] std::string get_current_machine_id() const;
623 
624  /**
625  * @brief Returns the best estimate of the server's current wall-clock time.
626  *
627  * @details
628  * Computed as the last received @c sys_time plus the elapsed microseconds since
629  * that heartbeat, extrapolated via an @c ElapsedTimer. Returns the raw
630  * @c sys_time field when the timer is not yet running.
631  *
632  * @return Estimated server system time in microseconds since the Unix epoch.
633  */
634  [[nodiscard]] uint64_t get_current_sys_time() const;
635 
636  /**
637  * @brief Returns the best estimate of the server's current boot time.
638  *
639  * @details
640  * Computed as the last received @c boot_time plus the elapsed microseconds since
641  * that heartbeat, extrapolated via an @c ElapsedTimer.
642  *
643  * @return Estimated server uptime in microseconds since boot.
644  */
645  [[nodiscard]] uint64_t get_current_boot_time() const;
646 
647  /**
648  * @brief Returns the server's most recently reported CPU utilisation.
649  *
650  * @return CPU usage percentage in the range [0, 100]; @c 0 when disconnected.
651  */
652  [[nodiscard]] double get_current_cpu_usage() const;
653 
654  /**
655  * @brief Returns the server's most recently reported memory utilisation.
656  *
657  * @return Memory usage percentage in the range [0, 100]; @c 0 when disconnected.
658  */
659  [[nodiscard]] double get_current_memory_usage() const;
660 
661  /**
662  * @brief Returns the latest backend-reported latency on the data channel.
663  *
664  * @details
665  * In direct (SHM) mode, or before the DDS data subscriber is initialised, this
666  * returns @c 0. Otherwise it delegates to the underlying data subscriber's
667  * latency tracker. Main backends report one-way/end-to-end data latency in
668  * nanoseconds.
669  *
670  * @return Latency in nanoseconds, or @c 0 when unavailable.
671  */
672  [[nodiscard]] int64_t get_latency() const;
673 
674  /**
675  * @brief Returns the sample-loss statistics on the data channel.
676  *
677  * @details
678  * In direct (SHM) mode, or before the DDS data subscriber is initialised, this
679  * returns a default-constructed (zero) @c SampleLostInfo. Otherwise it
680  * delegates to the underlying data subscriber.
681  *
682  * @return @c SampleLostInfo holding total and lost sample counters.
683  */
684  [[nodiscard]] SampleLostInfo get_lost() const;
685 
686  /**
687  * @brief Returns whether a valid connection to @c ProxyServer exists.
688  *
689  * @details
690  * @c true once the first valid heartbeat arrives; @c false after five seconds
691  * without a heartbeat or when the control channel reports disconnection.
692  *
693  * @return @c true if connected, @c false otherwise.
694  */
695  [[nodiscard]] bool is_connected() const;
696 
697  /**
698  * @brief Returns the @c VLINK_VERSION string reported by the server.
699  *
700  * @details
701  * With handshake enabled, initialised from the successful handshake response and
702  * subsequently refreshed from @c Time metadata after token/control checks.
703  * Without handshake, populated from the first valid heartbeat. Empty before any
704  * server version is accepted and after a handle reset.
705  *
706  * @return Server VLink version string, e.g. @c "2.0.0".
707  */
708  [[nodiscard]] std::string get_proxy_version() const;
709 
710  /**
711  * @brief Returns every server hostname observed during this session.
712  *
713  * @details
714  * Hostnames are accumulated for the lifetime of the connection. They are NOT
715  * cleared on disconnect, only when @c reset_handle() runs.
716  *
717  * @return Unordered set of observed hostnames.
718  */
719  [[nodiscard]] std::unordered_set<std::string> get_proxy_hostnames() const;
720 
721  /**
722  * @brief Returns every server machine ID observed during this session.
723  *
724  * @details
725  * Analogous to @c get_proxy_hostnames(); accumulated for the lifetime of the
726  * connection.
727  *
728  * @return Unordered set of observed machine IDs.
729  */
730  [[nodiscard]] std::unordered_set<std::string> get_proxy_machine_ids() const;
731 
732  /**
733  * @brief Returns @c true when the build includes SHM (Iceoryx) support.
734  *
735  * @details
736  * Decided at compile time by @c VLINK_SUPPORT_SHM. Useful to gate
737  * @c Config::direct.
738  *
739  * @return @c true when SHM support is compiled in.
740  */
741  [[nodiscard]] static bool is_support_shm();
742 
743  /**
744  * @brief Returns @c true when topic filtering support is compiled in.
745  *
746  * @details
747  * Decided at compile time by @c VLINK_PROXY_ENABLE_FILTER. When @c false the
748  * @c filter_str and @c filter_by_process fields in @c Control are ignored by the
749  * server.
750  *
751  * @return @c true when filtering is enabled.
752  */
753  [[nodiscard]] static bool is_enable_filter();
754 
755  /**
756  * @brief Formats a microsecond wall-clock timestamp as a human-readable string.
757  *
758  * @details
759  * Output format: @c "YYYY/MM/DD HH:MM:SS:mmm" where @c mmm is milliseconds.
760  * Uses @c localtime_r by default; @c gmtime_r when @p enable_utc is @c true.
761  *
762  * @param time Microseconds since the Unix epoch.
763  * @param enable_utc @c true for UTC; @c false for local time (default).
764  * @return Formatted timestamp string, or empty on conversion error.
765  */
766  [[nodiscard]] static std::string get_format_sys_time(uint64_t time, bool enable_utc = false);
767 
768  /**
769  * @brief Formats a microsecond boot-time duration as a human-readable string.
770  *
771  * @details
772  * Converts @p time (microseconds since boot) into a formatted elapsed string,
773  * e.g. @c "0d 01:23:45.678".
774  *
775  * @param time Microseconds since boot.
776  * @return Formatted elapsed-time string.
777  */
778  [[nodiscard]] static std::string get_format_boot_time(uint64_t time);
779 
780  protected:
781  size_t get_max_task_count() const override;
782 
783  uint32_t get_max_elapsed_time() const override;
784 
785  void on_begin() override;
786 
787  void on_end() override;
788 
789  private:
790  friend class ProxyServer;
791 
792  [[nodiscard]] bool is_same_machine(const std::string& hostname, const std::string& machine_id,
793  const std::vector<std::string>& ip_list) const;
794 
795  bool send_control_sync(const Control& control);
796 
797  void sync_direct_maps(const Control& control);
798 
799  bool do_handshake(Error& out_err);
800 
801  void reset_handle();
802 
803  void process_connected(bool connected);
804 
805  void process_time(uint64_t sys_time, uint64_t boot_time);
806 
807  void process_error(Error error);
808 
809  struct Impl;
810  std::unique_ptr<Impl> impl_;
811 
813 };
814 
815 } // namespace vlink
#define VLINK_DISALLOW_COPY_AND_ASSIGN(classname)
Deletes the copy constructor and copy-assignment operator of classname.
Definition: macros.h:174
#define VLINK_PROXY_API_EXPORT
Definition: proxy_api.h:171