A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
schema.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
31#ifndef A11_ACTIONS_SCHEMA_H_
32#define A11_ACTIONS_SCHEMA_H_
33
34#include <memory>
35#include <optional>
36#include <string>
37#include <string_view>
38#include <vector>
39
40#include <absl/container/flat_hash_map.h>
41#include <absl/status/status.h>
42#include <absl/status/statusor.h>
43
44#include "a11/data/types.h"
45
46namespace a11::actions {
47
49inline constexpr std::string_view kActionStatusMimetype = data::kStatusMimetype;
51inline constexpr std::string_view kActionStatusOutput = "__status__";
53inline constexpr std::string_view kActionDispatchStatusOutput =
54 "__dispatch_status__";
64inline constexpr std::string_view kActionLogOutput = "__log__";
66inline constexpr std::string_view kActionStreamsOutput = "__streams__";
68inline constexpr std::string_view kStreamScopeHeader = "x-a11-stream-scope";
70inline constexpr std::string_view kStreamStorageHeader = "x-a11-stream-storage";
72inline constexpr std::string_view kCancelActionName = "__cancel__";
74inline constexpr std::string_view kCancelActionHeader = "__action";
76inline constexpr std::string_view kActionHeaderPrefix = "x-a11-";
77
88 std::string name;
89 std::string type;
90 std::string description = {};
91 bool required = false;
92 bool unary = false;
94 std::vector<std::optional<data::NodeFragment>> autofills{};
95
106 std::string json_schema = {};
107
110 std::shared_ptr<void> typeinfo{nullptr};
111
113 absl::Status Validate() const;
114 friend bool operator==(const ActionPortSchema&,
115 const ActionPortSchema&) = default;
116};
117
125 std::string name;
126 std::string description;
127 std::optional<data::Bytes> default_value{
128 std::nullopt};
129
131 absl::Status Validate() const;
132 friend bool operator==(const ActionHeaderSchema&,
133 const ActionHeaderSchema&) = default;
134};
135
145 static constexpr std::string_view kWholeJson = "$";
146
147 std::string name;
148 std::string description = {};
149 absl::flat_hash_map<std::string, ActionPortSchema> inputs =
150 {};
151 absl::flat_hash_map<std::string, ActionPortSchema> outputs =
152 {};
153 absl::flat_hash_map<std::string, ActionHeaderSchema> headers =
154 {};
156 absl::flat_hash_map<std::string, std::string> output_to_json_field = {};
157
159 absl::Status Validate() const;
165 absl::Status MapOutputToJson(std::string output_name,
166 std::string field_name = {});
167
168 friend bool operator==(const ActionSchema&, const ActionSchema&) = default;
169};
170
185
186 friend bool operator==(const ActionSettings&,
187 const ActionSettings&) = default;
188};
189
191absl::StatusOr<data::Chunk> StatusToChunk(const absl::Status& status);
193absl::StatusOr<absl::Status> StatusFromChunk(const data::Chunk& chunk);
210
211} // namespace a11::actions
212
213#endif // A11_ACTIONS_SCHEMA_H_
Definition action.cc:66
constexpr std::string_view kStreamScopeHeader
Header enabling auxiliary stream propagation across action calls.
Definition schema.h:68
constexpr std::string_view kStreamStorageHeader
Collector storage namespaces that require no payload mirroring.
Definition schema.h:70
constexpr std::string_view kActionStatusMimetype
Mimetype marking a chunk that carries an action status.
Definition schema.h:49
constexpr std::string_view kActionStreamsOutput
Reserved output discovering auxiliary streams in an action subtree.
Definition schema.h:66
constexpr std::string_view kActionDispatchStatusOutput
Reserved output port name carrying the remote dispatch status.
Definition schema.h:53
constexpr std::string_view kActionStatusOutput
Reserved output port name carrying the action's completion status.
Definition schema.h:51
constexpr std::string_view kActionHeaderPrefix
Prefix reserved for A11's framework headers.
Definition schema.h:76
absl::StatusOr< absl::Status > StatusFromChunk(const data::Chunk &chunk)
Decodes a status previously encoded by StatusToChunk.
Definition schema.cc:144
constexpr std::string_view kCancelActionHeader
Header naming the action targeted by a cancel request.
Definition schema.h:74
constexpr std::string_view kCancelActionName
Reserved action name used to signal cancellation to a peer.
Definition schema.h:72
constexpr std::string_view kActionLogOutput
Reserved output port name carrying the action's log.
Definition schema.h:64
absl::StatusOr< data::Chunk > StatusToChunk(const absl::Status &status)
Encodes a status as a chunk (mimetype kActionStatusMimetype).
Definition schema.cc:140
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
bool IsCloseStatusChunk(const Chunk &chunk)
Whether chunk is a status chunk marking write-half closure.
Definition types.cc:434
Schema for a single header an action accepts.
Definition schema.h:124
std::string description
Human-readable description.
Definition schema.h:126
friend bool operator==(const ActionHeaderSchema &, const ActionHeaderSchema &)=default
std::string name
Header name.
Definition schema.h:125
absl::Status Validate() const
Validates the header schema.
Definition schema.cc:47
std::optional< data::Bytes > default_value
Value used when omitted.
Definition schema.h:127
Schema for a single input or output port of an action.
Definition schema.h:87
bool unary
Whether the port carries a single value.
Definition schema.h:92
absl::Status Validate() const
Validates the port schema.
Definition schema.cc:33
std::string json_schema
JSON Schema for the port's payload, as text.
Definition schema.h:106
std::string type
Payload type name.
Definition schema.h:89
std::shared_ptr< void > typeinfo
Owning, opaque type handle installed by a language binding.
Definition schema.h:110
bool required
Whether the port must be supplied.
Definition schema.h:91
std::string description
Human-readable description.
Definition schema.h:90
std::string name
Port name (unique within its direction).
Definition schema.h:88
std::vector< std::optional< data::NodeFragment > > autofills
Input-default fragments; an autofilled input must otherwise be empty.
Definition schema.h:94
friend bool operator==(const ActionPortSchema &, const ActionPortSchema &)=default
The full typed interface of an action.
Definition schema.h:144
absl::Status MapOutputToJson(std::string output_name, std::string field_name={})
Maps an output port onto a JSON result field.
Definition schema.cc:115
static constexpr std::string_view kWholeJson
Whole-JSON target.
Definition schema.h:145
absl::flat_hash_map< std::string, ActionPortSchema > inputs
Input ports.
Definition schema.h:149
friend bool operator==(const ActionSchema &, const ActionSchema &)=default
absl::flat_hash_map< std::string, ActionHeaderSchema > headers
Headers.
Definition schema.h:153
absl::flat_hash_map< std::string, ActionPortSchema > outputs
Output ports.
Definition schema.h:151
std::string description
Human-readable description.
Definition schema.h:148
absl::flat_hash_map< std::string, std::string > output_to_json_field
Maps output port names to JSON result fields.
Definition schema.h:156
std::string name
Action name.
Definition schema.h:147
absl::Status Validate() const
Validates the schema and all of its ports and headers.
Definition schema.cc:51
Per-action runtime settings for stream binding and cleanup.
Definition schema.h:178
bool clear_inputs_after_run
Release inputs after each run.
Definition schema.h:183
friend bool operator==(const ActionSettings &, const ActionSettings &)=default
std::optional< bool > bind_streams_on_outputs_by_default
Bind output port streams by default when unset per-port.
Definition schema.h:182
std::optional< bool > bind_streams_on_inputs_by_default
Bind input port streams by default when unset per-port.
Definition schema.h:180
bool clear_outputs_after_run
Release outputs after each run.
Definition schema.h:184
A unit of data: bytes plus optional descriptive metadata.
Definition types.h:173
A11's core wire value types: chunks, node fragments and messages.