A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
plan.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
17#ifndef A11_FLOW_PLAN_H_
18#define A11_FLOW_PLAN_H_
19
20#include <cstddef>
21#include <memory>
22#include <optional>
23#include <string>
24#include <string_view>
25#include <vector>
26
27#include <absl/base/nullability.h>
28#include <absl/time/time.h>
29
30#include "a11/flow/syntax.h"
31
32namespace a11::flow {
33
34struct DtoPlan;
35
37struct PortPlan {
38 std::string name;
41 std::string declared;
42 std::optional<syntax::TypeExpression> syntax_type;
46 std::string type;
47 bool unary = true;
48 bool required = false;
49 std::string description;
50 std::vector<std::string> constraints;
51 std::shared_ptr<const DtoPlan> analysis_shape;
53};
54
62struct FieldPlan {
63 std::string name;
64 std::string declared;
65 std::optional<syntax::TypeExpression> syntax_type;
66 std::string type;
69 std::string element;
71 std::string dto_name;
72 std::string element_dto_name;
73 bool required = false;
74 bool unique = false;
76 std::string pattern;
77 bool has_pattern = false;
78 std::vector<syntax::Constant> enumeration;
79 bool has_enumeration = false;
81 bool has_default = false;
82 std::string description;
84};
85
87struct DtoPlan {
88 std::string name;
89 bool exported = false;
90 std::string description;
91 std::vector<FieldPlan> fields;
99 bool binary = false;
101
103 [[nodiscard]] const FieldPlan* absl_nullable Field(
104 std::string_view field_name) const;
105
107 [[nodiscard]] std::vector<std::string> FieldNames() const;
108};
109
119
121struct StepPlan {
122 bool scope_barrier = false;
123 std::string optional_binding;
124 std::vector<std::string> serial_sources;
125 std::vector<std::string> destinations;
130 std::string kind;
133 std::string label;
135 std::vector<std::string> after;
137 std::string action;
138 std::string mode;
139 std::string node_map;
140 std::string pipeline_input;
141 std::string pipeline_output;
142 std::optional<absl::Duration> timeout;
143 bool has_deadline = false;
144 bool tolerant = false;
145 bool tee = false;
148 std::string source;
149 std::string destination;
152 std::vector<std::vector<StepPlan>> bodies;
154};
155
157struct FlowPlan {
159 std::string name;
168 bool entry = false;
169 bool interface_only = false;
170 bool ambiguous = false;
171 bool imported = false;
172 bool registerable = true;
173 std::string module;
174 bool exported = false;
175 std::string binding_name;
176 std::string description;
177 std::vector<PortPlan> ports;
178 std::vector<HeaderPlan> headers;
180 std::vector<std::string> node_maps;
181 std::vector<StepPlan> steps;
183
185 [[nodiscard]] const PortPlan* absl_nullable Port(
186 std::string_view port_name, syntax::PortDirection direction) const;
187
189 [[nodiscard]] bool HasPort(std::string_view port_name,
191 return Port(port_name, direction) != nullptr;
192 }
193
195 [[nodiscard]] std::vector<std::string> PortNames(
197};
198
200struct Program {
201 std::string source_name;
202 std::vector<FlowPlan> flows;
209 std::vector<DtoPlan> dtos;
211 std::vector<FlowPlan> context_flows;
212 std::vector<DtoPlan> context_dtos;
213
216 [[nodiscard]] const FlowPlan* absl_nullable Flow(std::string_view name) const;
217
219 [[nodiscard]] const FlowPlan* absl_nullable Entry() const;
220
222 [[nodiscard]] const DtoPlan* absl_nullable Dto(std::string_view name) const;
223};
224
226inline constexpr std::string_view kPlanFormat = "flow.plan/v1";
227
228} // namespace a11::flow
229
230#endif // A11_FLOW_PLAN_H_
std::string name
The declaration name and its colon.
Definition format.cc:50
std::string direction
in, out or header as written; empty for a shape field.
Definition format.cc:48
PortDirection
Which side of the descriptor a port lands on, spelled as the plan spells it.
Definition syntax.h:624
Definition catalogue.cc:29
constexpr std::string_view kPlanFormat
The format field of the plan envelope.
Definition plan.h:226
One compiled struct: a shape a port may be typed with.
Definition plan.h:87
std::string description
Definition plan.h:90
const FieldPlan *absl_nullable Field(std::string_view field_name) const
The field of this name, or nullptr.
Definition resolve.cc:6611
bool exported
Definition plan.h:89
std::vector< std::string > FieldNames() const
Every field name, in declaration order, for a message that lists them.
Definition resolve.cc:6621
std::string name
Definition plan.h:88
syntax::Location location
Definition plan.h:100
bool binary
Whether the shape holds bytes anywhere in it, directly or through another shape it names.
Definition plan.h:99
std::vector< FieldPlan > fields
Definition plan.h:91
One field of a struct, resolved.
Definition plan.h:62
syntax::FieldRange range
Definition plan.h:75
std::string pattern
Definition plan.h:76
std::string element
The element type of a list[T], resolved, or empty where it is not a list.
Definition plan.h:69
bool has_default
Definition plan.h:81
std::string name
Definition plan.h:63
std::string element_dto_name
Definition plan.h:72
syntax::Constant default_value
Definition plan.h:80
std::string dto_name
Whether the field, or a list's element, names a declared shape.
Definition plan.h:71
std::vector< syntax::Constant > enumeration
Definition plan.h:78
std::optional< syntax::TypeExpression > syntax_type
Definition plan.h:65
bool unique
Definition plan.h:74
bool has_pattern
Definition plan.h:77
syntax::Location location
Definition plan.h:83
std::string declared
Definition plan.h:64
bool required
Definition plan.h:73
std::string description
Definition plan.h:82
std::string type
Definition plan.h:66
bool has_enumeration
Definition plan.h:79
One compiled flow: what a caller sees, and what the runtime will do.
Definition plan.h:157
bool imported
Definition plan.h:171
std::vector< HeaderPlan > headers
Definition plan.h:178
bool HasPort(std::string_view port_name, syntax::PortDirection direction) const
Whether a port of this name is declared in that direction.
Definition plan.h:189
syntax::Location location
Definition plan.h:182
std::vector< StepPlan > steps
Definition plan.h:181
std::string description
Definition plan.h:176
bool entry
Whether this is the file's entry point, declared flow { ... }.
Definition plan.h:168
std::vector< PortPlan > ports
Definition plan.h:177
std::vector< std::string > PortNames(syntax::PortDirection direction) const
Every port name in one direction, sorted, for a message that lists them.
Definition resolve.cc:6551
std::string bool exported
Definition plan.h:174
bool registerable
Definition plan.h:172
bool ambiguous
Definition plan.h:170
bool interface_only
Definition plan.h:169
std::string binding_name
Definition plan.h:175
std::vector< std::string > node_maps
The node maps the flow declares, in declaration order.
Definition plan.h:180
std::string name
Empty for the entry flow, which is the one flow that has no name.
Definition plan.h:159
const PortPlan *absl_nullable Port(std::string_view port_name, syntax::PortDirection direction) const
The port with this name and direction, or nullptr.
Definition resolve.cc:6541
One declared header.
Definition plan.h:111
std::string alias
Definition plan.h:113
std::string description
Definition plan.h:116
bool has_default
Definition plan.h:115
std::string name
Definition plan.h:112
syntax::Location location
Definition plan.h:117
syntax::Constant default_value
Definition plan.h:114
One declared port of a flow, resolved.
Definition plan.h:37
bool unary
Definition plan.h:47
std::string description
Definition plan.h:49
syntax::Location location
Definition plan.h:52
std::optional< syntax::TypeExpression > syntax_type
Definition plan.h:42
syntax::PortDirection direction
Definition plan.h:39
std::string type
What the type is, for the schema a caller sees: a built-in's mimetype or Python type name,...
Definition plan.h:46
bool required
Definition plan.h:48
std::vector< std::string > constraints
Definition plan.h:50
std::shared_ptr< const DtoPlan > analysis_shape
Definition plan.h:51
std::string name
Definition plan.h:38
std::string declared
The type as the flow wrote it, parameters and all: list[string].
Definition plan.h:41
Every flow and shape one source file declares.
Definition plan.h:200
std::vector< FlowPlan > context_flows
Host metadata used during analysis, separate from source declarations.
Definition plan.h:211
std::string source_name
Definition plan.h:201
const FlowPlan *absl_nullable Flow(std::string_view name) const
The flow of this name, or nullptr.
Definition resolve.cc:6563
const DtoPlan *absl_nullable Dto(std::string_view name) const
The shape of this name, or nullptr.
Definition resolve.cc:6597
std::vector< DtoPlan > context_dtos
Definition plan.h:212
std::vector< DtoPlan > dtos
The shapes, in declaration order.
Definition plan.h:209
const FlowPlan *absl_nullable Entry() const
The file's entry point, or nullptr when it declares none.
Definition resolve.cc:6588
std::vector< FlowPlan > flows
Definition plan.h:202
One resolved statement in the a11 flow describe plan.
Definition plan.h:121
bool tee
Definition plan.h:145
bool scope_barrier
Definition plan.h:122
std::string continuation_parent
Definition plan.h:126
std::string node_map
Definition plan.h:139
std::vector< std::vector< StepPlan > > bodies
Bodies nested in this step, in the order the language reads them: a for or repeat has one,...
Definition plan.h:152
syntax::Location location
Definition plan.h:153
std::string action
For a call: the action, the verb, and where it goes.
Definition plan.h:137
std::string optional_binding
Definition plan.h:123
std::vector< std::string > serial_sources
Definition plan.h:124
std::string pipeline_input
Definition plan.h:140
std::string label
The name this step is known by: a bound name, or action, for, if with a #2 after it where one label i...
Definition plan.h:133
std::optional< absl::Duration > timeout
Definition plan.h:142
std::string mode
Definition plan.h:138
bool has_deadline
Definition plan.h:143
std::vector< std::string > after
What it waits for, by label.
Definition plan.h:135
std::vector< std::string > destinations
Definition plan.h:125
std::string destination
Definition plan.h:149
std::string pipeline_output
Definition plan.h:141
std::string source
For a pipe/skip/wait/close: what it reads and what it writes, as a reader would say them – search....
Definition plan.h:148
std::string kind
The kind of statement, as a11.flow.plan's Step.kind spells it: call, pipe, skip, wait,...
Definition plan.h:130
bool tolerant
Definition plan.h:144
A literal or folded literal expression, including nested lists and objects.
Definition syntax.h:62
A field bound such as 1..200, 1.., or ..200.
Definition syntax.h:719
The start token's byte span, line, and code-point column.
Definition syntax.h:39