VLink  2.3.0
A high-performance communication middleware
message_parser.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 message_parser.h
26  * @brief Unified runtime parser for built-in VLink zero-copy wire messages.
27  *
28  * @details
29  * @c MessageParser centralises type detection, deserialization, indexed field
30  * access, collection bounds, and exact integer representation for all nine
31  * built-in VLink zero-copy wire types. Root paths use names such as
32  * @c header.time_meas and @c width. Indexed payloads use @c data[N].field;
33  * tensors additionally expose @c shape[N] and @c strides[N].
34  *
35  * Integer fields remain @c int64_t or @c uint64_t in @c MessageParser::Value.
36  * Conversion through @c numeric reports values outside the exact IEEE-754
37  * integer range. Deserialized containers borrow the input wire storage; the
38  * input must therefore outlive the parser and any returned @c Bytes view.
39  *
40  * @par Parsing and access flow
41  * @verbatim
42  * serialized type + wire Bytes
43  * |
44  * v
45  * MessageParser::detect_type
46  * |
47  * v
48  * MessageParser::parse ---- failure ----> invalid / empty state
49  * |
50  * +----> exact field: value(path)
51  * |
52  * +----> collection: value(name, index, field)
53  * @endverbatim
54  *
55  * @par Path and value mapping
56  * | Payload kind | Example path | @c Value alternative |
57  * | ------------------ | ---------------------------- | -------------------- |
58  * | Header / metadata | @c header.time_meas | @c uint64_t |
59  * | Point record | @c data[4].intensity | Schema-dependent |
60  * | Object record | @c objects[2].track_id | @c uint64_t |
61  * | Grid / tensor cell | @c data[7] | Dtype-dependent |
62  * | Tensor dimension | @c shape[1] / @c strides[1] | @c uint64_t |
63  * | Raw payload | @c data / @c raw | Borrowed @c Bytes |
64  *
65  * @par Collection mapping
66  * | Message type | Indexed collections | Element field form |
67  * | ------------------ | --------------------------------------- | ------------------------ |
68  * | @c RawData | None | — |
69  * | @c CameraFrame | None | — |
70  * | @c PointCloud | @c data / @c points | Dynamic point key |
71  * | @c ProxyData | None | — |
72  * | @c OccupancyGrid | @c data / @c cells | Empty or @c value |
73  * | @c Tensor | @c data / @c elements, shape, strides | Empty or @c value |
74  * | @c ObjectArray | @c data / @c objects | Object member or alias |
75  * | @c AudioFrame | @c data | Empty or @c value |
76  * | @c FastBuffer | None (metadata only) | None |
77  *
78  * @par Example -- parse and read an exact integer field
79  * @code
80  * vlink::zerocopy::MessageParser parser;
81  * if (!parser.parse("vlink::zerocopy::ObjectArray", wire)) {
82  * return;
83  * }
84  *
85  * vlink::zerocopy::MessageParser::Value value;
86  * if (parser.value("data[0].track_id", value)) {
87  * consume(std::get<uint64_t>(value));
88  * }
89  * @endcode
90  */
91 
92 #pragma once
93 
94 #include <array>
95 #include <cstddef>
96 #include <cstdint>
97 #include <string>
98 #include <string_view>
99 #include <variant>
100 #include <vector>
101 
102 #include "../base/bytes.h"
103 #include "../base/macros.h"
104 #include "./audio_frame.h"
105 #include "./camera_frame.h"
106 #include "./fast_buffer.h"
107 #include "./object_array.h"
108 #include "./occupancy_grid.h"
109 #include "./point_cloud.h"
110 #include "./proxy_data.h"
111 #include "./raw_data.h"
112 #include "./tensor.h"
113 
114 namespace vlink {
115 
116 namespace zerocopy {
117 
118 /**
119  * @class MessageParser
120  * @brief Unified parser and field reader for built-in zero-copy messages.
121  *
122  * @details
123  * A successful parse retains the decoded message and exposes schema-neutral
124  * scalar access through @c value(), @c numeric(), and @c text(). Indexed
125  * payloads use paths such as @c data[4].x, @c shape[1], and
126  * @c objects[2].track_id. Integer values remain exact in @c Value; callers
127  * converting them to double can request a precision loss report. Decoded
128  * containers and @c Bytes values borrow payload storage from the input. The
129  * input must outlive the parser and every returned byte view; scalar and
130  * string values are copied into @c Value.
131  */
133  public:
134  /**
135  * @enum Type
136  * @brief Built-in zero-copy wire type retained by the parser.
137  */
138  enum Type : uint8_t {
139  kUnknown = 0, ///< No message is parsed, or the serialized type is unsupported.
140  kRawData = 1, ///< Opaque bytes with a common zero-copy header.
141  kCameraFrame = 2, ///< Image or encoded video frame.
142  kPointCloud = 3, ///< Dynamically described packed point records.
143  kProxyData = 4, ///< Proxy routing envelope and nested raw payload.
144  kOccupancyGrid = 5, ///< Typed two-dimensional occupancy or cost cells.
145  kTensor = 6, ///< Typed multidimensional tensor payload.
146  kObjectArray = 7, ///< Detection or tracking object records.
147  kAudioFrame = 8, ///< PCM or encoded audio frame.
148  kFastBuffer = 9, ///< Plugin-backed buffer; parsed as metadata without importing device memory.
149  };
150 
151  /**
152  * @enum ValueType
153  * @brief Exact C++ alternative stored by @c Value for a field.
154  */
155  enum ValueType : uint8_t {
156  kValueUnknown = 0, ///< Field has no supported value representation.
157  kInt64 = 1, ///< Signed integral value retained as @c int64_t.
158  kUInt64 = 2, ///< Unsigned integral value retained as @c uint64_t.
159  kDouble = 3, ///< Floating-point value represented as @c double.
160  kString = 4, ///< UTF-8 or protocol text represented as @c std::string.
161  kBytes = 5, ///< Opaque payload returned as a borrowed @c Bytes view.
162  };
163 
164  /**
165  * @enum EnumKind
166  * @brief Built-in enumeration a scalar field maps to, for symbolic-name rendering.
167  *
168  * @details
169  * Structural reflection alone cannot recover an integer field's symbolic
170  * enumerator name. @c EnumKind names the concrete built-in enum a field
171  * encodes so a presentation layer can resolve its label without re-hardcoding
172  * per-type knowledge. @c kEnumNone marks a plain numeric field.
173  */
174  enum EnumKind : uint8_t {
175  kEnumNone = 0, ///< Plain numeric field with no symbolic enumeration.
176  kEnumCameraFormat = 1, ///< @c CameraFrame::Format image or codec format.
177  kEnumCameraStream = 2, ///< @c CameraFrame::Stream stream role.
178  kEnumGridCellType = 3, ///< @c OccupancyGrid::CellType cell storage type.
179  kEnumTensorDataType = 4, ///< @c Tensor::DataType element data type.
180  kEnumTensorDevice = 5, ///< @c Tensor::Device residency device.
181  kEnumAudioFormat = 6, ///< @c AudioFrame::Format sample format.
182  kEnumAudioLayout = 7, ///< @c AudioFrame::Layout channel layout.
183  kEnumFastBufferStorage = 8, ///< @c FastBuffer::Storage wire payload kind.
184  kEnumFastBufferMemory = 9, ///< @c zerocopy::FastBuffer::MemoryType allocation domain.
185  };
186 
187  /**
188  * @struct Field
189  * @brief Schema-neutral field descriptor returned by field enumeration.
190  */
191  struct Field final {
192  std::string name; ///< Canonical path or collection element field name.
193  ValueType type{ValueType::kValueUnknown}; ///< Exact @c Value alternative returned for the field.
194  uint16_t native_type{0}; ///< Message-specific schema type tag, or zero when not applicable.
195  uint16_t storage_size{0}; ///< Encoded field width in bytes, or zero for variable-width fields.
196  EnumKind enum_kind{EnumKind::kEnumNone}; ///< Built-in enumeration the field encodes, for symbolic rendering.
197  bool is_time{false}; ///< Field is a nanosecond timestamp eligible for date rendering.
198  bool is_bool{false}; ///< Field encodes a boolean and should render as @c true / @c false.
199  bool is_reserved{false}; ///< Field is a reserved slot a presentation layer may hide.
200  size_t byte_offset{0}; ///< Byte offset within an indexed packed record, when applicable.
201  size_t element_index{static_cast<size_t>(-1)}; ///< Declaration index within an indexed record, when applicable.
202  };
203 
204  /**
205  * @typedef Value
206  * @brief Exact schema-neutral field value without implicit integer-to-double conversion.
207  */
208  using Value = std::variant<int64_t, uint64_t, double, std::string, Bytes>;
209 
210  /**
211  * @brief Constructs an invalid parser with no retained message.
212  */
213  MessageParser() = default;
214 
215  /**
216  * @brief Releases the retained typed message.
217  */
218  ~MessageParser() = default;
219 
220  /**
221  * @brief Parsers are non-copyable because decoded containers may borrow wire storage.
222  *
223  * @param target Parser whose borrowed state would otherwise be copied.
224  */
225  MessageParser(const MessageParser&) = delete;
227 
228  /**
229  * @brief Move-constructs or move-assigns the retained parser state.
230  *
231  * @param target Parser whose retained state is transferred.
232  */
233  MessageParser(MessageParser&&) noexcept = default;
234  MessageParser& operator=(MessageParser&&) noexcept = default;
235 
236  /**
237  * @brief Detects @p serialized_type and parses @p bytes; failure clears the parser.
238  *
239  * @param serialized_type Exact type name or namespace-delimited built-in type suffix.
240  * @param bytes Zero-copy wire envelope to decode; its storage must outlive this parser.
241  * @return @c true on successful type detection and deserialization.
242  */
243  bool parse(std::string_view serialized_type, const Bytes& bytes);
244 
245  /**
246  * @brief Parses @p bytes as the explicitly selected type; failure clears the parser.
247  *
248  * @param type Built-in zero-copy type expected in @p bytes.
249  * @param bytes Zero-copy wire envelope to decode; its storage must outlive this parser.
250  * @return @c true when the envelope is valid for @p type.
251  */
252  bool parse(Type type, const Bytes& bytes);
253 
254  /**
255  * @brief Releases the current decoded message and returns to the invalid state.
256  */
257  void clear() noexcept;
258 
259  /**
260  * @brief Returns the retained built-in type, or @c kUnknown when invalid.
261  */
262  [[nodiscard]] Type type() const noexcept;
263 
264  /**
265  * @brief Returns whether the parser currently retains a successfully decoded message.
266  */
267  [[nodiscard]] bool valid() const noexcept;
268 
269  /**
270  * @brief Reads a root or indexed field without losing its integer representation.
271  *
272  * @param path Root path or indexed path such as @c data[3].x.
273  * @param out Exact field value written only when the path resolves.
274  * @return @c true when @p path exists and is readable.
275  */
276  bool value(std::string_view path, Value& out) const;
277 
278  /**
279  * @brief Reads @p field from element @p index of a named collection.
280  *
281  * @param collection Canonical collection or supported alias.
282  * @param index Zero-based element index.
283  * @param field Element field name, or @c value for scalar collections.
284  * @param out Exact field value written on success.
285  * @return @c false for an unknown collection, field, or out-of-range index.
286  */
287  bool value(std::string_view collection, size_t index, std::string_view field, Value& out) const;
288 
289  /**
290  * @brief Reads a collection element through a descriptor returned by @c element_fields().
291  *
292  * @details This overload avoids repeated name resolution in packed-record hot paths. The
293  * descriptor is validated against the parser's current schema, so a stale descriptor from
294  * an incompatible subsequent parse is rejected.
295  */
296  bool value(std::string_view collection, size_t index, const Field& field, Value& out) const;
297 
298  /**
299  * @brief Reads a numeric path and optionally reports integer-to-double precision loss.
300  *
301  * @param path Root or indexed numeric field path.
302  * @param out Numeric value converted to @c double.
303  * @param precision_loss Optional flag set when an integer exceeds the exact IEEE-754 range.
304  * @return @c true when @p path resolves to a numeric value.
305  */
306  bool numeric(std::string_view path, double& out, bool* precision_loss = nullptr) const;
307 
308  /**
309  * @brief Reads a numeric collection element and optionally reports precision loss.
310  *
311  * @param collection Canonical collection or supported alias.
312  * @param index Zero-based element index.
313  * @param field Element field name, or @c value for scalar collections.
314  * @param out Numeric value converted to @c double.
315  * @param precision_loss Optional flag set when integer conversion is inexact.
316  * @return @c true when the selected element resolves to a numeric value.
317  */
318  bool numeric(std::string_view collection, size_t index, std::string_view field, double& out,
319  bool* precision_loss = nullptr) const;
320 
321  /**
322  * @brief Reads a numeric collection element through a pre-resolved field descriptor.
323  */
324  bool numeric(std::string_view collection, size_t index, const Field& field, double& out,
325  bool* precision_loss = nullptr) const;
326 
327  /**
328  * @brief Reads a string-valued path.
329  *
330  * @param path Root or indexed string field path.
331  * @param out String copied from the decoded field on success.
332  * @return @c true when @p path resolves to a string value.
333  */
334  bool text(std::string_view path, std::string& out) const;
335 
336  /**
337  * @brief Reads a string-valued collection element.
338  *
339  * @param collection Canonical collection or supported alias.
340  * @param index Zero-based element index.
341  * @param field String field name.
342  * @param out String copied from the decoded field on success.
343  * @return @c true when the selected element resolves to a string value.
344  */
345  bool text(std::string_view collection, size_t index, std::string_view field, std::string& out) const;
346 
347  /**
348  * @brief Returns the validated accessible element count of @p collection.
349  *
350  * @param collection Canonical collection or supported alias.
351  * @return Number of elements safe to read from the decoded payload.
352  */
353  [[nodiscard]] size_t collection_size(std::string_view collection) const noexcept;
354 
355  /**
356  * @brief Enumerates root fields available for the parsed type.
357  *
358  * @return Stable declaration-order descriptors; empty when the parser is invalid.
359  */
360  [[nodiscard]] std::vector<Field> fields() const;
361 
362  /**
363  * @brief Enumerates fields of one element in @p collection.
364  *
365  * @param collection Canonical collection or supported alias.
366  * @return Stable element field descriptors, or an empty vector for an unknown collection.
367  */
368  [[nodiscard]] std::vector<Field> element_fields(std::string_view collection) const;
369 
370  /**
371  * @brief Deep-copies the retained message into a matching typed container.
372  *
373  * @tparam T A built-in zero-copy container, or @c FastBuffer::Metadata for FastBuffer messages.
374  * @param out Destination container replaced only when @p T matches the parsed type.
375  * @return @c true when a matching retained message was copied.
376  *
377  * @note This compatibility operation is intended for typed container APIs. Dynamic
378  * readers should use @c value(), @c fields(), and collection access instead.
379  * FastBuffer resource import is separate; this operation copies only its metadata.
380  */
381  template <typename T>
382  bool copy_to(T& out) const;
383 
384  /**
385  * @brief Detects a built-in type using an exact name or namespace-delimited suffix.
386  *
387  * @param serialized_type Serialized type name supplied by schema metadata.
388  * @return Detected built-in type, or @c kUnknown when no exact suffix matches.
389  */
390  static Type detect_type(std::string_view serialized_type) noexcept;
391 
392  /**
393  * @brief Returns the canonical unqualified serialized name for @p type.
394  *
395  * @param type Built-in parser type.
396  * @return Stable unqualified name, or an empty view for @c kUnknown.
397  */
398  static std::string_view type_name(Type type) noexcept;
399 
400  private:
401  using Message = std::variant<std::monostate, RawData, CameraFrame, PointCloud, ProxyData, OccupancyGrid, Tensor,
403 
404  template <typename T>
405  [[nodiscard]] const T* get() const noexcept;
406 
407  /**
408  * @brief Resolves a non-indexed field from the retained message.
409  */
410  bool root_value(std::string_view path, Value& out) const;
411 
412  /**
413  * @brief Resolves one field from a validated collection element.
414  */
415  bool element_value(std::string_view collection, size_t index, std::string_view field, Value& out) const;
416 
417  /**
418  * @brief Reads a PointCloud field whose schema descriptor has already been validated.
419  */
420  bool point_value(size_t index, const Field& field, Value& out) const;
421 
422  Type type_{Type::kUnknown};
423  Message message_;
424  std::array<uint64_t, 5> reserved_{};
425  std::vector<Field> point_fields_;
426  std::vector<size_t> point_field_buckets_;
427  std::vector<size_t> point_field_next_;
428 };
429 
430 ////////////////////////////////////////////////////////////////
431 /// Details
432 ////////////////////////////////////////////////////////////////
433 
434 inline MessageParser::Type MessageParser::type() const noexcept { return type_; }
435 
436 inline bool MessageParser::valid() const noexcept { return type_ != Type::kUnknown; }
437 
438 template <typename T>
439 inline bool MessageParser::copy_to(T& out) const {
440  const auto* message = get<T>();
441 
442  if VUNLIKELY (message == nullptr) {
443  return false;
444  }
445 
446  out = *message;
447  return true;
448 }
449 
450 template <typename T>
451 inline const T* MessageParser::get() const noexcept {
452  return std::get_if<T>(&message_);
453 }
454 
455 /**
456  * @struct MessageFormatOptions
457  * @brief Presentation toggles for @c format_message.
458  */
459 struct MessageFormatOptions final {
460  bool hex{false}; ///< Render integer fields as hexadecimal instead of decimal.
461  bool date{false}; ///< Render nanosecond timestamp fields as calendar dates.
462  bool enum_name{false}; ///< Render enumeration fields as symbolic names instead of numbers.
463  bool expand_arrays{true}; ///< Expand indexed collections (e.g. PointCloud points) element by element.
464  size_t max_elements{10000}; ///< Upper bound on expanded collection elements.
465 };
466 
467 /**
468  * @brief Renders a parsed zero-copy message as canonical human-readable text.
469  *
470  * @details
471  * Walks @p parser purely through its field reflection (@c fields, @c element_fields,
472  * @c collection_size, @c value) and renders the canonical text form shared by
473  * @c vlink-parse, @c vlink-efbs and @c vlink-eproto. Per-type presentation -- header
474  * grouping, hidden reserved slots, symbolic enumerator names, nanosecond timestamps,
475  * boolean rendering, the PointCloud protocol block and Tensor shape line -- is driven
476  * by the @c MessageParser::Field metadata rather than by per-message branches.
477  *
478  * @param parser Valid parser retained for the duration of this call.
479  * @param options Presentation toggles.
480  * @param truncated Optional flag set when collection expansion hit @c max_elements.
481  * @return Rendered text, or an empty string when @p parser is invalid.
482  */
483 VLINK_EXPORT std::string format_message(const MessageParser& parser, const MessageFormatOptions& options,
484  bool* truncated = nullptr);
485 
486 } // namespace zerocopy
487 
488 } // namespace vlink
Zero-copy audio frame container carrying one PCM or codec-encoded packet.
Zero-copy container for a single image / video frame plus pixel-format metadata.
Platform-independent buffer with a Header and a pointer-free wire envelope.
#define VUNLIKELY(...)
Short alias for VLINK_UNLIKELY.
Definition: macros.h:292
#define VLINK_EXPORT
Definition: macros.h:81
Zero-copy variable-length array of fixed-size 3-D detection / tracking records.
Zero-copy 2-D occupancy / cost-map grid container with typed cell storage.
Zero-copy, schema-aware 3-D point cloud container with per-field type protocol.
Routing envelope used by the VLink proxy / monitoring path.
Generic zero-copy byte-buffer container with a Header prefix.
128-byte POD container holding one audio packet with full sample-format metadata.
80-byte POD container holding one camera / video frame plus image-format metadata.
Holds a local memory address and an owned provider reference.
Definition: fast_buffer.h:138
112-byte POD container holding a packed array of 144-byte Object records.
152-byte POD container holding a typed 2-D occupancy / cost grid plus pose metadata.
256-byte POD container holding a schema-described array of N-field point records.
80-byte POD envelope packing payload, URL, serialisation type and host string.
64-byte POD container that wraps an opaque byte payload with a Header prefix.
248-byte POD container holding a dense N-D tensor plus shape / dtype / device metadata.
Zero-copy N-dimensional dense tensor container with shape, strides, and dtype metadata.