A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
types.h
Go to the documentation of this file.
1/*
2 * Copyright 2026 The A11 Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
36#ifndef A11_DATA_TYPES_H_
37#define A11_DATA_TYPES_H_
38
39#include <optional>
40#include <string>
41#include <string_view>
42#include <variant>
43#include <vector>
44
45#include <absl/base/nullability.h>
46#include <absl/container/flat_hash_map.h>
47#include <absl/status/status.h>
48#include <absl/status/statusor.h>
49#include <absl/time/time.h>
50
51namespace a11::data {
52
53class MsgpackWriter;
54
56using Bytes = std::string;
58using ByteMap = absl::flat_hash_map<std::string, Bytes>;
59
65absl::Status ValidateName(std::string_view name);
66
75 std::string mimetype = {};
76 std::optional<absl::Time> timestamp{};
78
80 [[nodiscard]] size_t ApproxBytes() const;
82 [[nodiscard]] std::string DebugString() const;
84 absl::Status Validate() const;
86 absl::StatusOr<std::string> GetAttribute(std::string_view key) const;
88 absl::Status SetAttribute(std::string key, std::string value);
89
91 absl::StatusOr<Bytes> ToMsgpack() const;
99 absl::Status ToMsgpackInto(MsgpackWriter* absl_nonnull writer) const;
101 static absl::StatusOr<ChunkMetadata> FromMsgpack(std::string_view bytes);
102
103 friend bool operator==(const ChunkMetadata&, const ChunkMetadata&) = default;
104
105 template <typename Sink>
106 friend void AbslStringify(Sink& sink, const ChunkMetadata& value) {
107 sink.Append(value.DebugString());
108 }
109};
110
141 public:
142 virtual ~ChunkObject() = default;
143
145 [[nodiscard]] virtual std::string_view tag() const = 0;
147 [[nodiscard]] virtual std::string_view mimetype() const = 0;
149 [[nodiscard]] virtual absl::StatusOr<Bytes> Encode() const = 0;
151 [[nodiscard]] virtual size_t ApproxBytes() const = 0;
152
154 [[nodiscard]] virtual const void* absl_nonnull address() const = 0;
155};
156
173struct Chunk {
174 std::optional<ChunkMetadata> metadata{};
175 std::string ref{};
184 std::shared_ptr<const ChunkObject> object{};
185
187 [[nodiscard]] size_t ApproxBytes() const;
189 [[nodiscard]] std::string DebugString() const;
191 [[nodiscard]] std::string GetMimetype() const;
193 [[nodiscard]] bool IsEmpty() const;
195 [[nodiscard]] bool IsNull() const;
197 absl::Status Validate() const;
198
200 [[nodiscard]] bool HasObject() const { return object != nullptr; }
201
212 absl::Status Materialize();
213
215 absl::StatusOr<Bytes> ToMsgpack() const;
229 absl::Status ToMsgpackInto(MsgpackWriter* absl_nonnull writer) const;
231 static absl::StatusOr<Chunk> FromMsgpack(std::string_view bytes);
232
233 friend bool operator==(const Chunk&, const Chunk&) = default;
234
235 template <typename Sink>
236 friend void AbslStringify(Sink& sink, const Chunk& value) {
237 sink.Append(value.DebugString());
238 }
239};
240
242inline constexpr std::string_view kStatusMimetype = "application/x-a11-status";
251inline constexpr std::string_view kCloseAttribute = "a11-close";
252
259absl::StatusOr<Chunk> MakeStatusChunk(const absl::Status& status,
260 bool closing = false);
262bool IsStatusChunk(const Chunk& chunk);
264bool IsCloseStatusChunk(const Chunk& chunk);
266absl::StatusOr<absl::Status> StatusFromStatusChunk(const Chunk& chunk);
267
270 std::string scheme{};
271 absl::flat_hash_map<std::string, std::string> fields{};
273 absl::Status Validate() const;
274 friend bool operator==(const StorageCredentials&,
275 const StorageCredentials&) = default;
276};
277
280 std::string role{};
281 std::string endpoint{};
282 std::optional<StorageCredentials> credentials{};
284 absl::Status Validate() const;
285 friend bool operator==(const StorageService&,
286 const StorageService&) = default;
287};
288
291 std::string id{};
292 std::optional<StorageCredentials> credentials{};
293 std::vector<StorageService>
296 absl::Status Validate() const;
298 [[nodiscard]] size_t ApproxBytes() const;
300 [[nodiscard]] std::string DebugString() const;
301 friend bool operator==(const StorageIdentity&,
302 const StorageIdentity&) = default;
303};
304
311struct NodeRef {
312 std::string id;
313 std::uint32_t offset = 0;
314 // 2^32 is a valid length for a full logical node and therefore requires a
315 // wider representation than offset and sequence numbers.
316 std::optional<std::uint64_t> length;
317 std::optional<StorageIdentity>
319
321 [[nodiscard]] size_t ApproxBytes() const;
323 [[nodiscard]] std::string DebugString() const;
325 absl::Status Validate() const;
327 absl::StatusOr<NodeRef> WithCredentials(
329 std::optional<std::string_view> service = std::nullopt) const;
330
332 absl::StatusOr<Bytes> ToMsgpack() const;
346 absl::Status ToMsgpackInto(MsgpackWriter* absl_nonnull writer) const;
348 static absl::StatusOr<NodeRef> FromMsgpack(std::string_view bytes);
349
350 friend bool operator==(const NodeRef&, const NodeRef&) = default;
351
352 template <typename Sink>
353 friend void AbslStringify(Sink& sink, const NodeRef& value) {
354 sink.Append(value.DebugString());
355 }
356};
357
367 std::string id = {};
368 std::variant<Chunk, NodeRef> data = Chunk{};
369 std::optional<std::uint32_t> seq = {};
370 bool continued = false;
371
373 [[nodiscard]] size_t ApproxBytes() const;
375 [[nodiscard]] std::string DebugString() const;
377 absl::Status Validate() const;
379 absl::StatusOr<Chunk* absl_nonnull> GetChunk();
381 absl::StatusOr<const Chunk* absl_nonnull> GetChunk() const;
383 absl::StatusOr<NodeRef* absl_nonnull> GetNodeRef();
385 absl::StatusOr<const NodeRef* absl_nonnull> GetNodeRef() const;
386
388 absl::StatusOr<Bytes> ToMsgpack() const;
402 absl::Status ToMsgpackInto(MsgpackWriter* absl_nonnull writer) const;
404 static absl::StatusOr<NodeFragment> FromMsgpack(std::string_view bytes);
405
406 friend bool operator==(const NodeFragment&, const NodeFragment&) = default;
407
408 template <typename Sink>
409 friend void AbslStringify(Sink& sink, const NodeFragment& value) {
410 sink.Append(value.DebugString());
411 }
412};
413
420struct Port {
421 std::string name;
422 std::string id;
423
425 [[nodiscard]] size_t ApproxBytes() const;
427 [[nodiscard]] std::string DebugString() const;
429 absl::Status Validate() const;
430
432 absl::StatusOr<Bytes> ToMsgpack() const;
446 absl::Status ToMsgpackInto(MsgpackWriter* absl_nonnull writer) const;
448 static absl::StatusOr<Port> FromMsgpack(std::string_view bytes);
449
450 friend bool operator==(const Port&, const Port&) = default;
451
452 template <typename Sink>
453 friend void AbslStringify(Sink& sink, const Port& value) {
454 sink.Append(value.DebugString());
455 }
456};
457
467 std::string id;
468 std::string name;
469 std::vector<Port> inputs{};
470 std::vector<Port> outputs{};
472
474 [[nodiscard]] size_t ApproxBytes() const;
476 [[nodiscard]] std::string DebugString() const;
478 absl::Status Validate() const;
479
481 absl::StatusOr<Bytes> ToMsgpack() const;
495 absl::Status ToMsgpackInto(MsgpackWriter* absl_nonnull writer) const;
497 static absl::StatusOr<ActionMessage> FromMsgpack(std::string_view bytes);
498
499 friend bool operator==(const ActionMessage&, const ActionMessage&) = default;
500
501 template <typename Sink>
502 friend void AbslStringify(Sink& sink, const ActionMessage& value) {
503 sink.Append(value.DebugString());
504 }
505};
506
517 static constexpr std::uint32_t kVersion = 1;
518
519 std::vector<NodeFragment> node_fragments{};
520 std::vector<ActionMessage> actions{};
522
524 [[nodiscard]] size_t ApproxBytes() const;
526 [[nodiscard]] std::string DebugString() const;
528 absl::Status Validate() const;
529
531 absl::StatusOr<Bytes> ToMsgpack() const;
545 absl::Status ToMsgpackInto(MsgpackWriter* absl_nonnull writer) const;
547 static absl::StatusOr<WireMessage> FromMsgpack(std::string_view bytes);
548
549 friend bool operator==(const WireMessage&, const WireMessage&) = default;
550
551 template <typename Sink>
552 friend void AbslStringify(Sink& sink, const WireMessage& value) {
553 sink.Append(value.DebugString());
554 }
555};
556
558bool IsHalfCloseMessage(const WireMessage& message);
560WireMessage MakeHalfCloseMessage(ByteMap trailers = {});
561
568size_t EmptyWireMessageSize();
569
570} // namespace a11::data
571
572#endif // A11_DATA_TYPES_H_
An in-process value a chunk may carry instead of its encoded bytes.
Definition types.h:140
virtual std::string_view mimetype() const =0
The mimetype the value would be encoded as.
virtual const void *absl_nonnull address() const =0
An opaque address supplied by the object implementation.
virtual absl::StatusOr< Bytes > Encode() const =0
Encodes the value, for whoever needs bytes after all.
virtual size_t ApproxBytes() const =0
A size estimate that does not encode anything.
virtual std::string_view tag() const =0
The serialisation tag of the held type.
virtual ~ChunkObject()=default
Incrementally encode the fields of one A11 wire record.
Definition msgpack.h:44
std::string value
Definition discover.cc:100
std::string key
Definition discover.cc:764
std::string name
The declaration name and its colon.
Definition format.cc:50
Definition json.cc:35
std::string Bytes
Raw byte payload; an alias of std::string.
Definition types.h:56
constexpr std::string_view kCloseAttribute
Metadata attribute marking a status chunk as a closure marker.
Definition types.h:251
absl::StatusOr< Chunk > MakeStatusChunk(const absl::Status &status, bool closing)
Encodes status as a chunk of mimetype kStatusMimetype.
Definition types.cc:419
size_t EmptyWireMessageSize()
The encoded size of an empty WireMessage.
Definition types.cc:1100
bool IsHalfCloseMessage(const WireMessage &message)
Whether message is a transport half-close signal.
Definition types.cc:1092
absl::Status ValidateName(std::string_view name)
Validates an A11 identifier (node/port/action name).
Definition types.cc:190
bool IsStatusChunk(const Chunk &chunk)
Whether chunk carries a packed status.
Definition types.cc:430
constexpr std::string_view kStatusMimetype
Mimetype marking a chunk whose payload is a packed status.
Definition types.h:242
WireMessage MakeHalfCloseMessage(ByteMap trailers)
Builds a half-close WireMessage carrying optional trailers.
Definition types.cc:1096
absl::StatusOr< absl::Status > StatusFromStatusChunk(const Chunk &chunk)
Decodes a status previously encoded by MakeStatusChunk.
Definition types.cc:439
bool IsCloseStatusChunk(const Chunk &chunk)
Whether chunk is a status chunk marking write-half closure.
Definition types.cc:434
absl::flat_hash_map< std::string, Bytes > ByteMap
String-keyed map of byte values (headers, attributes, etc.).
Definition types.h:58
std::optional< data::StorageCredentials > credentials
Definition runtime_streams.cc:38
The wire description of an action invocation.
Definition types.h:466
std::string DebugString() const
Return a concise representation suitable for logs and diagnostics.
Definition types.cc:817
std::vector< Port > outputs
Output port -> node bindings.
Definition types.h:470
static absl::StatusOr< ActionMessage > FromMsgpack(std::string_view bytes)
Decodes MessagePack bytes into an ActionMessage.
Definition types.cc:870
absl::StatusOr< Bytes > ToMsgpack() const
Encodes this message as MessagePack bytes.
Definition types.cc:845
std::string id
Unique id of this action instance.
Definition types.h:467
friend bool operator==(const ActionMessage &, const ActionMessage &)=default
std::vector< Port > inputs
Input port -> node bindings.
Definition types.h:469
absl::Status Validate() const
Validate the invocation id, action name, ports, and headers.
Definition types.cc:825
std::string name
Registered action name.
Definition types.h:468
ByteMap headers
Per-call headers.
Definition types.h:471
absl::Status ToMsgpackInto(MsgpackWriter *absl_nonnull writer) const
Append this record's fields to an already-open writer.
Definition types.cc:855
size_t ApproxBytes() const
Estimate memory/wire weight for session and transport limits.
Definition types.cc:803
friend void AbslStringify(Sink &sink, const ActionMessage &value)
Definition types.h:502
Descriptive metadata attached to a a11::data::Chunk.
Definition types.h:74
absl::StatusOr< Bytes > ToMsgpack() const
Encodes this metadata as MessagePack bytes.
Definition types.cc:256
std::string mimetype
Media type of the chunk payload.
Definition types.h:75
std::optional< absl::Time > timestamp
Optional creation timestamp.
Definition types.h:76
absl::Status SetAttribute(std::string key, std::string value)
Sets attribute key to value.
Definition types.cc:250
absl::Status ToMsgpackInto(MsgpackWriter *absl_nonnull writer) const
Append this record's fields to an already-open writer.
Definition types.cc:266
friend void AbslStringify(Sink &sink, const ChunkMetadata &value)
Definition types.h:106
absl::StatusOr< std::string > GetAttribute(std::string_view key) const
Returns attribute key, or a NotFound error when absent.
Definition types.cc:241
std::string DebugString() const
Return a concise representation suitable for logs and diagnostics.
Definition types.cc:226
size_t ApproxBytes() const
Estimate memory/wire weight for bounded-buffer accounting.
Definition types.cc:218
absl::Status Validate() const
Validate metadata before it crosses a store or transport boundary.
Definition types.cc:233
ByteMap attributes
Free-form key/value attributes.
Definition types.h:77
static absl::StatusOr< ChunkMetadata > FromMsgpack(std::string_view bytes)
Decodes MessagePack bytes into a ChunkMetadata.
Definition types.cc:278
friend bool operator==(const ChunkMetadata &, const ChunkMetadata &)=default
A unit of data: bytes plus optional descriptive metadata.
Definition types.h:173
absl::StatusOr< Bytes > ToMsgpack() const
Encodes this chunk as MessagePack bytes.
Definition types.cc:367
std::optional< ChunkMetadata > metadata
Optional payload metadata.
Definition types.h:174
bool IsEmpty() const
Whether the chunk carries no data, reference or object.
Definition types.cc:325
friend bool operator==(const Chunk &, const Chunk &)=default
bool HasObject() const
Whether this chunk is carrying a value rather than bytes.
Definition types.h:200
absl::Status Validate() const
Validate that payload, reference, and metadata fields are consistent.
Definition types.cc:336
absl::Status ToMsgpackInto(MsgpackWriter *absl_nonnull writer) const
Append this record's fields to an already-open writer.
Definition types.cc:377
std::string DebugString() const
Return a concise representation suitable for logs and diagnostics.
Definition types.cc:317
Bytes data
Inline byte payload.
Definition types.h:176
size_t ApproxBytes() const
Estimate memory/wire weight for bounded-buffer accounting.
Definition types.cc:308
friend void AbslStringify(Sink &sink, const Chunk &value)
Definition types.h:236
static absl::StatusOr< Chunk > FromMsgpack(std::string_view bytes)
Decodes MessagePack bytes into a Chunk.
Definition types.cc:392
std::string GetMimetype() const
Returns the metadata mimetype, or empty when unset.
Definition types.cc:321
bool IsNull() const
Whether the chunk represents an explicit null value.
Definition types.cc:332
absl::Status Materialize()
Produces data from object, if it has not been produced yet.
Definition types.cc:347
std::string ref
Node id this chunk references, if not inline.
Definition types.h:175
One piece of a node's stream: an inline chunk or a node reference.
Definition types.h:366
absl::StatusOr< Bytes > ToMsgpack() const
Encodes this fragment as MessagePack bytes.
Definition types.cc:676
std::string DebugString() const
Return a concise representation suitable for logs and diagnostics.
Definition types.cc:631
size_t ApproxBytes() const
Estimate memory/wire weight for session and transport limits.
Definition types.cc:625
absl::StatusOr< Chunk *absl_nonnull > GetChunk()
Returns the held Chunk, or an error when it holds a NodeRef.
Definition types.cc:648
friend bool operator==(const NodeFragment &, const NodeFragment &)=default
absl::StatusOr< NodeRef *absl_nonnull > GetNodeRef()
Returns the held NodeRef, or an error when it holds a Chunk.
Definition types.cc:662
friend void AbslStringify(Sink &sink, const NodeFragment &value)
Definition types.h:409
std::variant< Chunk, NodeRef > data
Inline chunk or reference.
Definition types.h:368
absl::Status ToMsgpackInto(MsgpackWriter *absl_nonnull writer) const
Append this record's fields to an already-open writer.
Definition types.cc:686
absl::Status Validate() const
Validate the node id, payload, sequence, and continuation marker.
Definition types.cc:641
bool continued
Whether further fragments follow this one.
Definition types.h:370
std::optional< std::uint32_t > seq
Ordering sequence number.
Definition types.h:369
static absl::StatusOr< NodeFragment > FromMsgpack(std::string_view bytes)
Decodes MessagePack bytes into a NodeFragment.
Definition types.cc:705
A reference to a (slice of a) logical node, in lieu of inline data.
Definition types.h:311
absl::Status Validate() const
Validate the referenced node id and requested slice.
Definition types.cc:551
std::optional< std::uint64_t > length
Optional fragment count.
Definition types.h:316
std::string DebugString() const
Return a concise representation suitable for logs and diagnostics.
Definition types.cc:540
friend bool operator==(const NodeRef &, const NodeRef &)=default
absl::Status ToMsgpackInto(MsgpackWriter *absl_nonnull writer) const
Append this record's fields to an already-open writer.
Definition types.cc:573
std::optional< StorageIdentity > storage
Host-resolved storage identity.
Definition types.h:318
absl::StatusOr< NodeRef > WithCredentials(StorageCredentials credentials, std::optional< std::string_view > service=std::nullopt) const
Return a qualified copy with the selected access fields.
Definition types.cc:500
absl::StatusOr< Bytes > ToMsgpack() const
Encodes this reference as MessagePack bytes.
Definition types.cc:563
friend void AbslStringify(Sink &sink, const NodeRef &value)
Definition types.h:353
static absl::StatusOr< NodeRef > FromMsgpack(std::string_view bytes)
Decodes MessagePack bytes into a NodeRef.
Definition types.cc:590
std::uint32_t offset
First referenced fragment sequence.
Definition types.h:313
size_t ApproxBytes() const
Estimate memory/wire weight for bounded-buffer accounting.
Definition types.cc:535
std::string id
Id of the referenced node.
Definition types.h:312
Binds an action's port name to the concrete node id serving it.
Definition types.h:420
absl::StatusOr< Bytes > ToMsgpack() const
Encodes this port as MessagePack bytes.
Definition types.cc:774
size_t ApproxBytes() const
Estimate memory/wire weight for session and transport limits.
Definition types.cc:757
std::string name
Schema-defined port name.
Definition types.h:421
absl::Status ToMsgpackInto(MsgpackWriter *absl_nonnull writer) const
Append this record's fields to an already-open writer.
Definition types.cc:784
static absl::StatusOr< Port > FromMsgpack(std::string_view bytes)
Decodes MessagePack bytes into a Port.
Definition types.cc:790
friend void AbslStringify(Sink &sink, const Port &value)
Definition types.h:453
friend bool operator==(const Port &, const Port &)=default
absl::Status Validate() const
Validate the port name and node id used to bind an action.
Definition types.cc:767
std::string DebugString() const
Return a concise representation suitable for logs and diagnostics.
Definition types.cc:761
std::string id
Id of the node backing this port.
Definition types.h:422
Scheme-labelled credential fields supplied to a host storage resolver.
Definition types.h:269
friend bool operator==(const StorageCredentials &, const StorageCredentials &)=default
std::string scheme
Authentication scheme interpreted by the host.
Definition types.h:270
absl::Status Validate() const
Validate the scheme and field names.
Definition types.cc:453
absl::flat_hash_map< std::string, std::string > fields
Scheme fields.
Definition types.h:271
Logical namespace with optional host-interpreted backend access information.
Definition types.h:290
std::string DebugString() const
Describe the namespace without printing credentials.
Definition types.cc:529
absl::Status Validate() const
Validate the namespace and its service metadata.
Definition types.cc:469
size_t ApproxBytes() const
Estimate wire weight, including credential fields.
Definition types.cc:480
std::vector< StorageService > services
Optional backend access metadata.
Definition types.h:294
friend bool operator==(const StorageIdentity &, const StorageIdentity &)=default
std::optional< StorageCredentials > credentials
Namespace access.
Definition types.h:292
One named service participating in a storage backend.
Definition types.h:279
std::optional< StorageCredentials > credentials
Optional access fields.
Definition types.h:282
absl::Status Validate() const
Validate service identity and authentication metadata.
Definition types.cc:461
friend bool operator==(const StorageService &, const StorageService &)=default
std::string endpoint
Host-interpreted endpoint.
Definition types.h:281
std::string role
Service role within the backend.
Definition types.h:280
The top-level frame exchanged between two A11 endpoints.
Definition types.h:516
friend void AbslStringify(Sink &sink, const WireMessage &value)
Definition types.h:552
std::string DebugString() const
Return a concise representation suitable for logs and diagnostics.
Definition types.cc:928
absl::Status Validate() const
Validate every contained fragment, action, and header.
Definition types.cc:995
ByteMap headers
Message-level headers.
Definition types.h:521
size_t ApproxBytes() const
Estimate memory/wire weight before admitting this message to a buffer.
Definition types.cc:914
absl::Status ToMsgpackInto(MsgpackWriter *absl_nonnull writer) const
Append this record's fields to an already-open writer.
Definition types.cc:1019
std::vector< ActionMessage > actions
Action invocations.
Definition types.h:520
static absl::StatusOr< WireMessage > FromMsgpack(std::string_view bytes)
Decodes MessagePack bytes into a WireMessage.
Definition types.cc:1038
static constexpr std::uint32_t kVersion
Wire format version.
Definition types.h:517
friend bool operator==(const WireMessage &, const WireMessage &)=default
std::vector< NodeFragment > node_fragments
Streamed data fragments.
Definition types.h:519
absl::StatusOr< Bytes > ToMsgpack() const
Encodes this message as MessagePack bytes.
Definition types.cc:1009