VLink  2.3.0
A high-performance communication middleware
convert_plugin_interface.h
浏览该文件的文档.
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 convert_plugin_interface.h
26  * @brief Plugin contract for converting VLink payloads to visualisation backend formats.
27  *
28  * @details
29  * @c ConvertPluginInterface lets users supply custom encoders that translate raw VLink
30  * messages -- in any serialisation -- into the payload format expected by a particular
31  * webviz frontend. The plugin is loaded as a shared library via the VLink @c Plugin
32  * framework and has no third-party dependencies of its own: it consumes @c Bytes and
33  * emits @c Bytes, so consumers may implement it without linking Protobuf, FlatBuffers,
34  * the Rerun SDK or any JSON library.
35  *
36  * Conversion pipeline:
37  *
38  * @verbatim
39  * can_convert(ser, target)?
40  * VLink Bytes -----> +-----------------------+
41  * | ConvertPluginInterface | --get_schema(ser, target, info)--> channel registration
42  * +-----------------------+
43  * |
44  * v convert(ser, raw, target, payload)
45  * backend Bytes ---> Foxglove / Rerun frontend
46  * @endverbatim
47  *
48  * Supported source/target combinations and the meaning of each output field:
49  *
50  * | @c Target | Wire payload | @c SchemaInfo::type_name meaning |
51  * | ------------------ | ----------------------------------- | ------------------------------------- |
52  * | @c kFoxglove | FlatBuffer / Protobuf binary bytes | Foxglove schema name |
53  * | @c kRerun | UTF-8 JSON describing components | Rerun archetype name |
54  *
55  * @par Rerun JSON payload format
56  * Plugins targeting Rerun emit a UTF-8 JSON object whose fields match the Rerun
57  * archetype in the linked SDK. Byte arrays accept a JSON array or a @c {"base64":"..."} object.
58  *
59  * @code{.json}
60  * // Points3D
61  * { "positions": [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
62  * "colors": [[255, 0, 0, 255], [0, 255, 0, 255]],
63  * "radii": [0.1, 0.2] }
64  *
65  * // EncodedImage (binary payload base64-encoded)
66  * { "media_type": "image/jpeg",
67  * "blob": {"base64": "<base64 image bytes>"} }
68  *
69  * // GeoPoints
70  * { "positions": [[37.7749, -122.4194], [37.7750, -122.4195]] }
71  *
72  * // TextLog
73  * { "text": "Hello world", "level": "INFO" }
74  *
75  * // Scalars
76  * { "scalars": [3.14] }
77  *
78  * // Transform3D
79  * { "translation": [1.0, 2.0, 3.0],
80  * "quaternion": [0.0, 0.0, 0.0, 1.0] }
81  *
82  * // Boxes3D
83  * { "half_sizes": [[1.0, 2.0, 3.0]],
84  * "centers": [[0.0, 0.0, 0.0]],
85  * "quaternions": [[0.0, 0.0, 0.0, 1.0]],
86  * "colors": [[255, 0, 0, 255]],
87  * "labels": ["box1"] }
88  *
89  * // Pinhole
90  * { "image_from_camera": [fx, 0, 0, 0, fy, 0, cx, cy, 1],
91  * "resolution": [1920, 1080] }
92  * @endcode
93  *
94  * Fields and component layouts come from the linked SDK: vectors are arrays,
95  * matrices are flat column-major arrays, structs are objects, and tagged unions
96  * are single-key objects such as @c {"F32":[1.0,2.0]}. Enum strings use SDK names.
97  * Image components use @c format and @c buffer; Tensor uses
98  * @c {"data":{"shape":[2],"buffer":{"F32":[1.0,2.0]}}}.
99  * Binary numeric lists use little-endian values of the declared component type.
100  * Integer components reject fractions and overflow; floating components retain
101  * NaN and infinity when the source representation supports them.
102  * Missing components are omitted. Empty component batches clear their values;
103  * an empty Blob array is one empty Blob. @c RecordingInfo is logged statically
104  * at the SDK recording-properties path. Field mappings use this same writer.
105  *
106  * Plugin lifecycle:
107  * 1. @c init() runs once after dynamic load, with an opaque configuration string.
108  * 2. @c can_convert() is queried per discovered VLink serialisation type, per target.
109  * 3. @c get_schema() registers the channel and refreshes dynamic output schemas.
110  * 4. @c convert() runs for every incoming payload on accepted types.
111  * 5. Optional reverse hooks (@c can_publish(), @c get_publish(),
112  * @c convert_publish()) handle inbound frontend command/control flows.
113  * 6. The destructor runs when the host unloads the plugin.
114  *
115  * @par Example
116  * @code
117  * #include <vlink/extension/convert_plugin_interface.h>
118  *
119  * class MyConvertPlugin : public vlink::ConvertPluginInterface {
120  * VLINK_PLUGIN_REGISTER(ConvertPluginInterface)
121  *
122  * public:
123  * bool init(const std::string& config) override {
124  * (void)config;
125  * return true;
126  * }
127  *
128  * bool can_convert(const std::string& ser_type, Target target) override {
129  * return ser_type == "my_pkg.MyMessage";
130  * }
131  *
132  * bool get_schema(const std::string& ser_type, Target target,
133  * SchemaInfo& schema_info) override {
134  * if (target == Target::kFoxglove) {
135  * schema_info.type_name = "foxglove.LocationFix";
136  * schema_info.encoding = "flatbuffers";
137  * schema_info.schema_encoding = "flatbuffers";
138  * // schema_info.schema_data = compiled BFBS bytes
139  * } else {
140  * schema_info.type_name = "GeoPoints";
141  * schema_info.encoding = "json";
142  * }
143  * return true;
144  * }
145  *
146  * bool convert(const std::string& ser_type, const vlink::Bytes& raw,
147  * Target target, vlink::Bytes& payload) override {
148  * if (target == Target::kRerun) {
149  * std::string json = R"({"positions":[[37.77,-122.41]]})";
150  * payload = vlink::Bytes::deep_copy(json.data(), json.size());
151  * }
152  * return true;
153  * }
154  * };
155  * VLINK_PLUGIN_DECLARE(MyConvertPlugin, 4, 0)
156  * @endcode
157  */
158 
159 #pragma once
160 
161 #include <cstdint>
162 #include <string>
163 
164 #include "../base/bytes.h"
165 #include "../base/plugin.h"
166 #include "../impl/types.h"
167 
168 namespace vlink {
169 
170 /**
171  * @class ConvertPluginInterface
172  * @brief Abstract plugin base translating between VLink payloads and visualisation backends.
173  *
174  * @details
175  * Loaded via @c Plugin::load<ConvertPluginInterface>(). The plugin must be thread-safe:
176  * @c convert() and the inbound @c convert_publish() hooks may run concurrently from
177  * multiple ProxyAPI worker threads. A plugin that only supports one backend should
178  * return @c false from @c can_convert() / @c can_publish() for the others.
179  */
182 
183  protected:
185 
186  virtual ~ConvertPluginInterface() = default;
187 
188  public:
189  /**
190  * @enum Target
191  * @brief Visualisation backend identifier carried by every conversion hook.
192  *
193  * @details
194  * Allows a single plugin to support multiple backends from one binary -- the plugin
195  * branches on this value to produce the appropriate payload format.
196  */
197  enum class Target : uint8_t {
198  kFoxglove = 0, ///< Foxglove Studio (WebSocket transport, FlatBuffers/Protobuf payloads).
199  kRerun = 1, ///< Rerun Viewer (gRPC + Arrow IPC; plugin payload is UTF-8 JSON).
200  };
201 
202  /**
203  * @struct SchemaInfo
204  * @brief Backend channel schema metadata returned by @c get_schema().
205  */
206  struct SchemaInfo final {
207  std::string type_name; ///< Backend schema or archetype name.
208  std::string encoding; ///< Wire encoding label (e.g. @c "flatbuffers", @c "json").
209  std::string schema_encoding; ///< Encoding of @c schema_data when provided.
210  std::string schema_data; ///< Binary schema bytes or schema text, depending on @c target.
211  };
212 
213  /**
214  * @struct FrontendChannel
215  * @brief Frontend-advertised channel description used by inbound conversion hooks.
216  *
217  * @details
218  * Allows plugins to route Foxglove @c clientPublish-style messages onto the right VLink
219  * topic by inspecting the channel's topic, encoding and schema metadata.
220  */
221  struct FrontendChannel final {
222  std::string topic; ///< Channel topic advertised by the frontend client.
223  std::string encoding; ///< Frontend payload encoding (json/protobuf/flatbuffers/...).
224  std::string schema_name; ///< Frontend-side schema or type name.
225  std::string schema_encoding; ///< Encoding of @c schema when provided.
226  std::string schema; ///< Raw schema string or binary payload (transport-specific).
227  };
228 
229  /**
230  * @struct PublishInfo
231  * @brief VLink publish destination resolved from an inbound frontend channel.
232  */
233  struct PublishInfo final {
234  std::string url; ///< Destination VLink URL (e.g. @c "dds://vehicle/cmd").
235  std::string ser_type; ///< Destination VLink serialisation type.
236  SchemaType schema_type{SchemaType::kUnknown}; ///< Coarse schema family for the published payload.
237  };
238 
239  /**
240  * @brief Initialises the plugin with an opaque configuration string.
241  *
242  * @details
243  * Called once after the plugin is loaded; the @p config string may be a file path,
244  * JSON document or anything the plugin defines. Returning @c false causes the host
245  * to unload the plugin.
246  *
247  * @param config Configuration payload; may be empty.
248  * @return @c true on success.
249  */
250  virtual bool init(const std::string& config) = 0;
251 
252  /**
253  * @brief Reports whether this plugin handles a (serialisation, target) pair.
254  *
255  * @details
256  * Polled during channel discovery for each new VLink type. A @c true answer commits
257  * the plugin to subsequent @c get_schema() and @c convert() calls for that pair.
258  *
259  * @param ser_type VLink serialisation type name (e.g. @c "proto.VehiclePose").
260  * @param target Visualisation backend asking about the conversion.
261  * @return @c true when the plugin can produce a payload for @p target.
262  */
263  [[nodiscard]] virtual bool can_convert(const std::string& ser_type, Target target) = 0;
264 
265  /**
266  * @brief Provides schema metadata for an accepted (serialisation, target) pair.
267  *
268  * @details
269  * Called when registering a channel and when refreshing a plugin's output schema. Outputs
270  * differ per target:
271  * - @c kFoxglove: fill @p schema_info with type, encoding and schema bytes
272  * (typically the bytes of a compiled BFBS file).
273  * - @c kRerun: fill @p schema_info.type_name with the archetype name and
274  * @p schema_info.encoding with @c "json"; schema payload fields are unused.
275  *
276  * @param[in] ser_type VLink serialisation type name.
277  * @param[in] target Visualisation backend.
278  * @param[out] schema_info Backend channel schema metadata.
279  * @return @c true on success.
280  */
281  [[nodiscard]] virtual bool get_schema(const std::string& ser_type, Target target, SchemaInfo& schema_info) = 0;
282 
283  /**
284  * @brief Converts a single raw VLink payload to the backend-specific representation.
285  *
286  * @details
287  * Invoked once per incoming message on accepted types. Must be thread-safe.
288  *
289  * @param[in] ser_type VLink serialisation type name.
290  * @param[in] raw Raw serialised VLink payload.
291  * @param[in] target Visualisation backend.
292  * @param[out] payload Output buffer that receives the backend payload.
293  * @return @c true on success.
294  */
295  [[nodiscard]] virtual bool convert(const std::string& ser_type, const Bytes& raw, Target target, Bytes& payload) = 0;
296 
297  /**
298  * @brief Optionally extracts a per-message timestamp from the raw payload.
299  *
300  * @details
301  * Called after @c convert() so the frontend can prefer a sensor or content timestamp
302  * over the proxy transport timestamp. The default implementation returns @c -1,
303  * causing the host to fall back to the transport-level timestamp.
304  *
305  * @param[in] ser_type VLink serialisation type name.
306  * @param[in] raw Raw serialised VLink payload.
307  * @param[in] target Visualisation backend.
308  * @return Timestamp in nanoseconds since epoch, or @c -1 when unavailable.
309  */
310  [[nodiscard]] virtual int64_t get_timestamp(const std::string& ser_type, const Bytes& raw, Target target) {
311  (void)ser_type;
312  (void)raw;
313  (void)target;
314  return -1;
315  }
316 
317  /**
318  * @brief Inbound counterpart of @c can_convert() for frontend-published channels.
319  *
320  * @details
321  * Default implementation returns @c false; override to opt in to clientPublish-style
322  * command flows.
323  */
324  [[nodiscard]] virtual bool can_publish(const FrontendChannel& channel, Target target) {
325  (void)channel;
326  (void)target;
327  return false;
328  }
329 
330  /**
331  * @brief Resolves the VLink publish destination for an inbound frontend channel.
332  *
333  * @details
334  * Returning @c true allows the host to provision the required VLink publishers ahead
335  * of time. Default implementation returns @c false.
336  */
337  [[nodiscard]] virtual bool get_publish(const FrontendChannel& channel, Target target, PublishInfo& publish_info) {
338  (void)channel;
339  (void)target;
340  (void)publish_info;
341  return false;
342  }
343 
344  /**
345  * @brief Converts a frontend-published payload into a raw VLink payload.
346  *
347  * @details
348  * Invoked once per inbound message after @c get_publish() routed the channel.
349  * Default implementation returns @c false.
350  */
351  [[nodiscard]] virtual bool convert_publish(const FrontendChannel& channel, const Bytes& raw, Target target,
352  Bytes& payload) {
353  (void)channel;
354  (void)raw;
355  (void)target;
356  (void)payload;
357  return false;
358  }
359 
360  private:
362 };
363 
364 } // 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_PLUGIN_REGISTER(InterfaceType)
Declares a plugin's identity from the demangled name of its abstract interface.
Definition: plugin.h:359