A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
action.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
32#ifndef A11_ACTIONS_ACTION_H_
33#define A11_ACTIONS_ACTION_H_
34
35#include <cstddef>
36#include <functional>
37#include <memory>
38#include <optional>
39#include <string>
40#include <string_view>
41#include <type_traits>
42#include <utility>
43#include <vector>
44
45#include <absl/base/thread_annotations.h>
46#include <absl/container/flat_hash_map.h>
47#include <absl/container/flat_hash_set.h>
48#include <absl/status/status.h>
49#include <absl/status/statusor.h>
50#include <absl/strings/str_format.h>
51#include <absl/time/time.h>
52
53#include "a11/actions/log.h"
54#include "a11/actions/schema.h"
58#include "a11/data/types.h"
59#include "a11/obs/span.h"
61
62namespace thread {
63class PermanentEvent;
64} // namespace thread
65
66namespace a11::net {
67class WireStream;
68} // namespace a11::net
69
70namespace a11::nodes {
71class AsyncNode;
72class NodeMap;
73} // namespace a11::nodes
74
75namespace a11::service {
76class Session;
77} // namespace a11::service
78
79namespace a11::actions {
80
81class Action;
82class ActionRegistry;
83class ReferenceMirrorRegistry;
84struct VerifiedAuthorization;
85
87inline constexpr size_t kDefaultMaxConcurrentNestedActions = 64;
88
92using ActionHandler = std::function<a11::Task(std::shared_ptr<Action>)>;
94using SyncActionHandler = std::function<absl::Status(std::shared_ptr<Action>)>;
96using OnActionCancelled = std::function<absl::Status(std::shared_ptr<Action>)>;
97
100
109 public:
111 static absl::StatusOr<std::shared_ptr<ActionLimiter>> Create(size_t maximum);
113 bool TryAcquire();
115 absl::Status Acquire();
117 void Release();
118
119 private:
120 explicit ActionLimiter(size_t maximum);
121
122 thread::Mutex mu_;
123 const size_t maximum_;
124 size_t active_ ABSL_GUARDED_BY(mu_) = 0;
125 std::shared_ptr<thread::PermanentEvent> changed_ ABSL_GUARDED_BY(mu_);
126};
127
138class Action : public std::enable_shared_from_this<Action> {
139 public:
152 static absl::StatusOr<std::shared_ptr<Action>> Create(
153 ActionSchema schema, std::string action_id = {},
154 ActionHandler handler = {},
155 std::shared_ptr<nodes::NodeMap> node_map = nullptr,
156 std::shared_ptr<net::WireStream> stream = nullptr,
157 std::shared_ptr<service::Session> session = nullptr,
158 std::shared_ptr<ActionRegistry> registry = nullptr,
159 size_t max_concurrent_nested_actions =
161
165 static absl::StatusOr<std::string> MakeNodeId(std::string_view action_id,
166 std::string_view node_name);
167
169 [[nodiscard]] std::string GetId() const;
171 absl::Status SetId(std::string action_id);
173 [[nodiscard]] ActionSchema GetSchema() const;
175 absl::Status SetSchema(ActionSchema schema);
177 absl::Status BindHandler(ActionHandler handler);
179 [[nodiscard]] ActionHandler GetHandler() const;
181 [[nodiscard]] bool HasHandler() const;
182
184 [[nodiscard]] ActionSettings GetSettings() const;
186 absl::Status SetSettings(ActionSettings settings);
188 absl::Status BindStreamsOnInputsByDefault(bool bind);
190 absl::Status BindStreamsOnOutputsByDefault(bool bind);
192 absl::Status ClearInputsAfterRun(bool clear = true);
194 absl::Status ClearOutputsAfterRun(bool clear = true);
195
197 absl::Status BindNodeMap(std::shared_ptr<nodes::NodeMap> node_map);
199 [[nodiscard]] std::shared_ptr<nodes::NodeMap> GetNodeMap() const;
201 absl::Status BindStream(std::shared_ptr<net::WireStream> stream);
203 [[nodiscard]] std::shared_ptr<net::WireStream> GetStream() const;
205 absl::Status BindRegistry(std::shared_ptr<ActionRegistry> registry);
207 [[nodiscard]] std::shared_ptr<ActionRegistry> GetRegistry() const;
209 absl::Status BindSession(const std::shared_ptr<service::Session>& session);
211 [[nodiscard]] std::shared_ptr<service::Session> GetSession() const;
213 absl::Status BindVerifiedAuthorization(
214 std::shared_ptr<const VerifiedAuthorization> authorization);
216 [[nodiscard]] std::shared_ptr<const VerifiedAuthorization>
218
220 absl::StatusOr<std::shared_ptr<nodes::AsyncNode>> GetNode(
221 std::string node_id);
228 absl::StatusOr<std::shared_ptr<nodes::AsyncNode>> GetInput(
229 std::string_view name, std::optional<bool> bind_stream = std::nullopt);
236 absl::StatusOr<std::shared_ptr<nodes::AsyncNode>> GetOutput(
237 std::string_view name, std::optional<bool> bind_stream = std::nullopt);
239 absl::StatusOr<std::shared_ptr<nodes::AsyncNode>> GetPort(
240 std::string_view name);
242 [[nodiscard]] bool ContainsPort(std::string_view name) const;
243
273 template <typename T>
274 absl::Status Log(const T& value, const LogOptions& options = {});
281 absl::Status Log(data::Chunk chunk, const LogOptions& options = {});
294 template <typename... Args>
295 absl::Status Logf(const absl::FormatSpec<Args...>& format,
296 const Args&... args);
307 template <typename... Args>
308 absl::Status LogfWith(const LogOptions& options,
309 const absl::FormatSpec<Args...>& format,
310 const Args&... args);
322 absl::StatusOr<std::shared_ptr<nodes::AsyncNode>> GetLogNode();
323
325 absl::StatusOr<std::shared_ptr<nodes::AsyncNode>> GetStreamSourcesNode(
326 bool request_payload = true);
327
329 absl::Status ExposeStreamSources(std::string port, std::string purpose);
330
334 absl::StatusOr<StreamReference> RegisterStream(
335 std::string purpose, data::Chunk source, std::string producer_id = {},
336 std::string parent_producer_id = {});
337
341 [[nodiscard]] data::ActionMessage GetActionMessage() const;
343 absl::Status MapPortsFromMessage(const data::ActionMessage& message);
344
346 [[nodiscard]] data::ByteMap Headers() const;
348 absl::StatusOr<std::optional<data::Bytes>> GetHeader(
349 std::string_view name) const;
351 [[nodiscard]] bool HasHeader(std::string_view name) const;
353 absl::Status SetHeader(std::string_view name, data::Bytes value);
355 absl::Status RemoveHeader(std::string_view name);
357 absl::Status ForwardHeader(const std::shared_ptr<Action>& target,
358 std::string_view name) const;
360 absl::Status ForwardHeadersWithPrefix(
361 const std::shared_ptr<Action>& target,
362 std::string_view prefix = kActionHeaderPrefix) const;
363
378 absl::StatusOr<std::shared_ptr<Action>> MakeNested(
379 const ActionSchema& schema, bool propagate_io = true,
380 bool forward_headers = true);
392 absl::StatusOr<std::shared_ptr<Action>> MakeNested(
393 std::string_view action_name, bool propagate_io = true,
394 bool forward_headers = true);
395
405 absl::StatusOr<std::shared_ptr<Action>> Run();
418 absl::Duration timeout = absl::InfiniteDuration());
426 absl::Duration timeout = absl::InfiniteDuration());
428 absl::Status Cancel();
430 absl::Status SetOnCancelled(OnActionCancelled callback);
431
438 [[nodiscard]] std::string TraceId() const;
440 [[nodiscard]] std::string SpanId() const;
441
449 void SetSpanAttribute(std::string_view key, std::string_view value);
451 void SetSpanAttribute(std::string_view key, std::int64_t value);
453 void SetSpanAttribute(std::string_view key, bool value);
455 void SetSpanAttribute(std::string_view key, double value);
457 void SetSpanName(std::string_view name);
464 void SetSpanStatus(obs::SpanStatus status, std::string_view description = {});
465
467 [[nodiscard]] bool IsDone() const;
469 [[nodiscard]] bool HasBeenRun() const;
471 [[nodiscard]] bool HasBeenCalled() const;
473 [[nodiscard]] bool Cancelled() const;
475 [[nodiscard]] absl::Status GetStatus() const;
479 [[nodiscard]] std::optional<absl::Status> GetDispatchStatus() const;
480
481 private:
482 enum class Mode { kNone, kRun, kCall, kCancelled };
483
484 struct PortOverrides {
485 absl::flat_hash_map<std::string, std::string> inputs;
486 absl::flat_hash_map<std::string, std::string> outputs;
487 };
488
489 struct StreamState {
490 bool reader_requested = false;
491 absl::flat_hash_set<std::string> direct_ids;
492 absl::flat_hash_map<std::string, std::string> source_ports;
493 absl::flat_hash_map<std::string, std::shared_ptr<const StreamReference>>
494 references;
495 absl::flat_hash_set<std::string> owned_ids;
496 };
497
498 struct DispatchState {
499 DispatchState()
500 : promise(std::make_shared<a11::Promise<a11::Unit>>()),
501 future(promise->future()) {}
502
503 std::optional<absl::Status> status;
504 std::shared_ptr<a11::Promise<a11::Unit>> promise;
505 a11::Task future;
506 };
507
508 absl::Status ReceiveStreamReference(const StreamReference& reference);
509 absl::Status PublishStreamReference(const StreamReference& reference);
510 absl::Status WaitForStreamChildren();
511
512 Action(ActionSchema schema, std::string id, ActionHandler handler,
513 std::shared_ptr<nodes::NodeMap> node_map,
514 std::shared_ptr<net::WireStream> stream,
515 const std::shared_ptr<service::Session>& session,
516 std::shared_ptr<ActionRegistry> registry,
517 size_t max_concurrent_nested_actions);
518
519 absl::Status Begin(Mode mode);
520 absl::Status RemapDefaultPorts() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
521 [[nodiscard]] bool IsOutputPortLocked(std::string_view name) const
522 ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
523 [[nodiscard]] std::string InputIdLocked(std::string_view name) const
524 ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
525 [[nodiscard]] std::string OutputIdLocked(std::string_view name) const
526 ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
527 PortOverrides& EnsurePortOverridesLocked() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
528 StreamState& EnsureStreamStateLocked() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
529 absl::Status AttachStreamIfRequested(
530 const std::shared_ptr<nodes::AsyncNode>& node, bool bind);
531 std::shared_ptr<ReferenceMirrorRegistry> MirrorRegistry();
532 absl::Status ValidateMessagePorts(
533 const std::vector<data::Port>& ports,
534 const absl::flat_hash_map<std::string, ActionPortSchema>& schema_ports,
535 std::string_view kind) const;
536 void RunHandler(const std::shared_ptr<ActionLimiter>& limiter);
537 absl::Status ApplyInputAutofills();
538 [[nodiscard]] std::vector<data::NodeFragment> CollectAutofillFragments()
539 const;
540 void StartFinish(absl::Status status);
541 absl::Status FinishRun(absl::Status status);
542 // Whether any input port declares autofills, which are written before the
543 // handler runs and so must not happen on the caller's thread.
544 [[nodiscard]] bool HasInputAutofills() const;
545 // Starts the handler on the calling thread and continues from its task
546 // without a fiber. Only valid when nothing before the handler can block.
547 absl::StatusOr<std::shared_ptr<Action>> RunHandlerWithoutFiber(
548 const std::shared_ptr<Action>& self,
549 std::shared_ptr<ActionLimiter> acquired_limiter = nullptr);
550 void ReleaseAcquiredLimiter();
551 absl::Status FinishOutputNodes(const absl::Status& status);
552 // Applies an already-finished Action's terminal state to an output node that
553 // is only being materialised now, so a late reader sees the end of the
554 // stream.
555 static absl::Status CloseUnwrittenOutput(
556 const std::shared_ptr<nodes::AsyncNode>& node,
557 const absl::Status& status);
558 // Applies `options` to `chunk`, reports it to the process sink, and writes it
559 // to the log port when anything could read it. The one place the log policy
560 // lives; the Log/Logf templates only build the chunk.
561 absl::Status WriteLog(data::Chunk chunk, const LogOptions& options);
562 absl::Status CommunicateStatus(const absl::Status& status);
563 absl::Status AbortInputs(const absl::Status& status);
564 absl::Status SendNodeAbortStatuses(
565 const absl::flat_hash_set<std::string>& node_ids,
566 const absl::Status& status);
567 absl::Status ReleaseNodesAfterRun();
568 absl::Status DetachBoundStreamNodes();
569 absl::Status SendRemoteCancel();
570 void CompleteCall(const absl::Status& status, bool remove_from_session);
571 void AbortLocalCallOutputs(const absl::Status& status);
572 absl::Status TrackInSession(const std::shared_ptr<service::Session>& session);
573 void UntrackFromSession();
574 void SetDispatchStatus(absl::Status status);
575 void SetCompletionStatus(const absl::Status& status);
576
577 // Tracing hooks (a11::obs).
578 absl::Status StartActionSpan(Mode mode);
579 void EndActionSpan(const absl::Status& status);
580 obs::Span MakeChildSpan(std::string_view name, obs::SpanKind kind);
581 void RecordActionCallEvent(std::string_view name, std::string_view id);
582
583 mutable thread::Mutex mu_;
584 ActionSchema schema_ ABSL_GUARDED_BY(mu_);
585 ActionHandler handler_ ABSL_GUARDED_BY(mu_);
586 std::string id_ ABSL_GUARDED_BY(mu_);
587 data::ByteMap headers_ ABSL_GUARDED_BY(mu_);
588 ActionSettings settings_ ABSL_GUARDED_BY(mu_);
589 std::shared_ptr<nodes::NodeMap> node_map_ ABSL_GUARDED_BY(mu_);
590 std::shared_ptr<net::WireStream> stream_ ABSL_GUARDED_BY(mu_);
591 std::weak_ptr<service::Session> session_ ABSL_GUARDED_BY(mu_);
592 std::weak_ptr<service::Session> tracked_session_ ABSL_GUARDED_BY(mu_);
593 std::shared_ptr<ActionRegistry> registry_ ABSL_GUARDED_BY(mu_);
594 std::shared_ptr<const VerifiedAuthorization> verified_authorization_
595 ABSL_GUARDED_BY(mu_);
596 std::unique_ptr<PortOverrides> port_overrides_ ABSL_GUARDED_BY(mu_);
597 absl::flat_hash_set<std::shared_ptr<nodes::AsyncNode>> input_nodes_
598 ABSL_GUARDED_BY(mu_);
599 absl::flat_hash_set<std::shared_ptr<nodes::AsyncNode>> output_nodes_
600 ABSL_GUARDED_BY(mu_);
601 absl::flat_hash_set<std::shared_ptr<nodes::AsyncNode>> stream_bound_nodes_
602 ABSL_GUARDED_BY(mu_);
603 std::shared_ptr<ReferenceMirrorRegistry> reference_mirrors_
604 ABSL_GUARDED_BY(mu_);
605 Mode mode_ ABSL_GUARDED_BY(mu_) = Mode::kNone;
606 bool input_autofills_applied_ ABSL_GUARDED_BY(mu_) = false;
607 a11::Task task_ ABSL_GUARDED_BY(mu_);
608 std::shared_ptr<ActionLimiter> acquired_limiter_ ABSL_GUARDED_BY(mu_);
609 obs::Span span_ ABSL_GUARDED_BY(mu_);
610 bool span_status_set_by_user_ ABSL_GUARDED_BY(mu_) = false;
611 bool cancel_requested_ ABSL_GUARDED_BY(mu_) = false;
612 bool finishing_ ABSL_GUARDED_BY(mu_) = false;
613 std::optional<absl::Status> completion_status_ ABSL_GUARDED_BY(mu_);
614 // Set once the Action has closed its output ports, with the status it closed
615 // them under. Read by GetOutput() so a port materialised after that point
616 // carries the same terminal state as one closed in place.
617 bool outputs_finished_ ABSL_GUARDED_BY(mu_) = false;
618 absl::Status outputs_final_status_ ABSL_GUARDED_BY(mu_);
619 // Set once a consumer has taken the log port through GetLogNode(). It then
620 // owns presentation, so WriteLog stops reporting to the process sink.
621 bool log_claimed_ ABSL_GUARDED_BY(mu_) = false;
622 bool streams_enabled_ ABSL_GUARDED_BY(mu_) = false;
623 std::unique_ptr<StreamState> stream_state_ ABSL_GUARDED_BY(mu_);
624 std::shared_ptr<a11::Promise<a11::Unit>> done_promise_ ABSL_GUARDED_BY(mu_);
625 a11::Task done_future_ ABSL_GUARDED_BY(mu_);
626 std::unique_ptr<DispatchState> dispatch_ ABSL_GUARDED_BY(mu_);
627 std::vector<OnActionCancelled> cancel_callbacks_ ABSL_GUARDED_BY(mu_);
628 std::weak_ptr<Action> parent_ ABSL_GUARDED_BY(mu_);
629 absl::flat_hash_set<std::shared_ptr<Action>> children_ ABSL_GUARDED_BY(mu_);
630 std::shared_ptr<ActionLimiter> nested_limiter_ ABSL_GUARDED_BY(mu_);
631 const size_t max_concurrent_nested_actions_;
632
633 friend class ActionRegistry;
634 friend class service::Session;
635};
636
637namespace internal {
638
649template <typename T>
650inline constexpr bool kLogsAsText =
651 std::is_convertible_v<const T&, std::string_view>;
652
653} // namespace internal
654
655template <typename T>
656absl::Status Action::Log(const T& value, const LogOptions& options) {
657 const data::SerializationRegistry& registry =
659 absl::StatusOr<data::Chunk> chunk;
660 if constexpr (internal::kLogsAsText<T>) {
661 // Normalised to std::string first: the registry has a codec for that, not
662 // for a pointer or an array of char.
663 const std::string text{std::string_view(value)};
664 chunk = registry.ToChunk<std::string>(text, options.mimetype.empty()
666 : options.mimetype);
667 } else {
668 chunk = registry.ToChunk<T>(value, options.mimetype);
669 }
670 if (!chunk.ok()) {
671 return chunk.status();
672 }
673 return WriteLog(*std::move(chunk), options);
674}
675
676template <typename... Args>
677absl::Status Action::Logf(const absl::FormatSpec<Args...>& format,
678 const Args&... args) {
679 return Log(absl::StrFormat(format, args...), LogOptions{});
680}
681
682template <typename... Args>
684 const absl::FormatSpec<Args...>& format,
685 const Args&... args) {
686 return Log(absl::StrFormat(format, args...), options);
687}
688
689} // namespace a11::actions
690
691#endif // A11_ACTIONS_ACTION_H_
Schemas describing an action's typed interface and its settings.
std::shared_ptr< service::Session > session
Definition authorization.cc:216
Shared handle to one asynchronous result.
Definition future.h:125
Move-only producer for a Future result.
Definition future.h:295
Cancellation-aware counting semaphore for nested-action concurrency.
Definition action.h:108
absl::Status Acquire()
Acquires a slot, blocking until one is free or cancelled.
Definition action.cc:164
bool TryAcquire()
Acquires a slot if one is immediately available.
Definition action.cc:155
void Release()
Releases a previously acquired slot.
Definition action.cc:184
static absl::StatusOr< std::shared_ptr< ActionLimiter > > Create(size_t maximum)
Creates a limiter admitting at most maximum holders.
Definition action.cc:141
A thread-safe catalogue mapping action names to schema and handler.
Definition registry.h:59
A11's unit of work: a schema-described, asynchronously run operation.
Definition action.h:138
std::shared_ptr< const VerifiedAuthorization > GetVerifiedAuthorization() const
Returns the verified authorization bound to this action.
Definition action.cc:517
absl::StatusOr< std::shared_ptr< nodes::AsyncNode > > GetStreamSourcesNode(bool request_payload=true)
Return references to auxiliary streams produced by this action subtree.
Definition streams.cc:36
absl::Status ClearInputsAfterRun(bool clear=true)
Sets whether inputs are released after each run.
Definition action.cc:363
void SetSpanStatus(obs::SpanStatus status, std::string_view description={})
Sets the span status explicitly.
Definition action.cc:1450
absl::Status BindStream(std::shared_ptr< net::WireStream > stream)
Binds the wire stream used to dispatch the action remotely.
Definition action.cc:386
absl::Status BindSession(const std::shared_ptr< service::Session > &session)
Binds the owning session.
Definition action.cc:478
std::optional< absl::Status > GetDispatchStatus() const
The remote dispatch status, or nullopt when not (yet) dispatched.
Definition action.cc:1312
bool HasBeenRun() const
Whether the action has been started with Run.
Definition action.cc:1290
absl::Status SetId(std::string action_id)
Sets this action's instance id.
Definition action.cc:282
absl::StatusOr< std::shared_ptr< nodes::AsyncNode > > GetPort(std::string_view name)
Returns the input or output port node named name.
Definition action.cc:612
absl::StatusOr< std::optional< data::Bytes > > GetHeader(std::string_view name) const
Returns header name, or nullopt when absent.
Definition action.cc:828
data::ByteMap Headers() const
Returns a copy of all headers.
Definition action.cc:823
absl::Status SetOnCancelled(OnActionCancelled callback)
Registers a callback invoked when the action is cancelled.
Definition action.cc:1276
std::string GetId() const
Returns this action's instance id.
Definition action.cc:277
absl::Status RemoveHeader(std::string_view name)
Removes header name.
Definition action.cc:855
std::string TraceId() const
This action's trace id as lowercase hex.
Definition action.cc:1415
bool HasBeenCalled() const
Whether the action has been dispatched with Call.
Definition action.cc:1295
absl::Status ExposeStreamSources(std::string port, std::string purpose)
Publish references of purpose on a declared output port.
Definition streams.cc:67
ActionSchema GetSchema() const
Returns this action's schema.
Definition action.cc:301
absl::StatusOr< std::shared_ptr< nodes::AsyncNode > > GetInput(std::string_view name, std::optional< bool > bind_stream=std::nullopt)
Returns the input port node named name.
Definition action.cc:536
std::shared_ptr< nodes::NodeMap > GetNodeMap() const
Returns the bound node map.
Definition action.cc:381
std::shared_ptr< service::Session > GetSession() const
Returns the owning session, if any.
Definition action.cc:502
ActionSettings GetSettings() const
Returns the action's current settings.
Definition action.cc:340
absl::Status BindVerifiedAuthorization(std::shared_ptr< const VerifiedAuthorization > authorization)
Binds identity and authority already verified for this action.
Definition action.cc:507
absl::Status LogfWith(const LogOptions &options, const absl::FormatSpec< Args... > &format, const Args &... args)
Logs a formatted string with explicit options.
Definition action.h:683
void SetSpanName(std::string_view name)
Overrides the display name of this action's span.
Definition action.cc:1445
absl::Status SetSchema(ActionSchema schema)
Replaces this action's schema (validated).
Definition action.cc:306
bool ContainsPort(std::string_view name) const
Whether the schema declares a port named name.
Definition action.cc:634
absl::Status ForwardHeadersWithPrefix(const std::shared_ptr< Action > &target, std::string_view prefix=kActionHeaderPrefix) const
Copies all headers starting with prefix onto target.
Definition action.cc:872
absl::Status Log(const T &value, const LogOptions &options={})
Logs value on the reserved kActionLogOutput port.
Definition action.h:656
absl::Status ClearOutputsAfterRun(bool clear=true)
Sets whether outputs are released after each run.
Definition action.cc:369
absl::Status BindRegistry(std::shared_ptr< ActionRegistry > registry)
Binds the registry used to resolve nested actions by name.
Definition action.cc:467
static absl::StatusOr< std::shared_ptr< Action > > Create(ActionSchema schema, std::string action_id={}, ActionHandler handler={}, std::shared_ptr< nodes::NodeMap > node_map=nullptr, std::shared_ptr< net::WireStream > stream=nullptr, std::shared_ptr< service::Session > session=nullptr, std::shared_ptr< ActionRegistry > registry=nullptr, size_t max_concurrent_nested_actions=kDefaultMaxConcurrentNestedActions)
Creates an action.
Definition action.cc:198
absl::Status MapPortsFromMessage(const data::ActionMessage &message)
Binds this action's ports to the nodes named in message.
Definition action.cc:791
absl::Status BindStreamsOnInputsByDefault(bool bind)
Sets whether input port streams are bound by default.
Definition action.cc:351
bool Cancelled() const
Whether cancellation has been requested/applied.
Definition action.cc:1300
a11::Future< std::shared_ptr< Action > > Wait(absl::Duration timeout=absl::InfiniteDuration())
Awaits completion of the action.
Definition action.cc:1189
a11::Future< std::shared_ptr< Action > > Call(data::ByteMap wire_headers={})
Dispatches the action to a peer over the bound wire stream.
Definition action.cc:1080
absl::Status GetStatus() const
The action's completion status (OK while still running).
Definition action.cc:1307
absl::Status Logf(const absl::FormatSpec< Args... > &format, const Args &... args)
Logs a formatted string, as ::absl::StrFormat would format it.
Definition action.h:677
absl::Status SetHeader(std::string_view name, data::Bytes value)
Sets header name to value.
Definition action.cc:848
absl::Status BindNodeMap(std::shared_ptr< nodes::NodeMap > node_map)
Binds the node map that backs this action's ports.
Definition action.cc:375
absl::Status BindHandler(ActionHandler handler)
Binds the handler invoked when the action runs.
Definition action.cc:317
data::ActionMessage GetActionMessage() const
Returns the wire a11::data::ActionMessage describing this action.
Definition action.cc:774
std::string SpanId() const
This action's span id as lowercase hex, or empty when untraced.
Definition action.cc:1420
absl::Status Cancel()
Requests cancellation of the action (local or remote).
Definition action.cc:1215
bool HasHandler() const
Whether a handler is bound.
Definition action.cc:335
bool IsDone() const
Whether the action has finished (successfully or not).
Definition action.cc:1285
std::shared_ptr< ActionRegistry > GetRegistry() const
Returns the bound registry.
Definition action.cc:473
absl::StatusOr< std::shared_ptr< nodes::AsyncNode > > GetLogNode()
Returns the log port's node, claiming it for this consumer.
Definition action.cc:648
bool HasHeader(std::string_view name) const
Whether header name is set.
Definition action.cc:840
void SetSpanAttribute(std::string_view key, std::string_view value)
Sets a string attribute on this action's span.
Definition action.cc:1425
a11::Future< absl::Status > WaitForDispatch(absl::Duration timeout=absl::InfiniteDuration())
Awaits acceptance of a remote dispatch.
Definition action.cc:1145
static absl::StatusOr< std::string > MakeNodeId(std::string_view action_id, std::string_view node_name)
Derives the node id for port node_name of action action_id.
Definition action.cc:268
absl::Status BindStreamsOnOutputsByDefault(bool bind)
Sets whether output port streams are bound by default.
Definition action.cc:357
absl::StatusOr< std::shared_ptr< Action > > Run()
Runs the action's handler locally.
Definition action.cc:955
std::shared_ptr< net::WireStream > GetStream() const
Returns the bound wire stream.
Definition action.cc:462
absl::StatusOr< std::shared_ptr< nodes::AsyncNode > > GetNode(std::string node_id)
Returns the port node with raw id node_id.
Definition action.cc:523
absl::Status ForwardHeader(const std::shared_ptr< Action > &target, std::string_view name) const
Copies header name from this action onto target.
Definition action.cc:862
absl::Status SetSettings(ActionSettings settings)
Replaces the action's settings.
Definition action.cc:345
absl::StatusOr< std::shared_ptr< nodes::AsyncNode > > GetOutput(std::string_view name, std::optional< bool > bind_stream=std::nullopt)
Returns the output port node named name.
Definition action.cc:562
ActionHandler GetHandler() const
Returns the currently bound handler.
Definition action.cc:330
absl::StatusOr< StreamReference > RegisterStream(std::string purpose, data::Chunk source, std::string producer_id={}, std::string parent_producer_id={})
Create an owned auxiliary stream and publish its JSON reference.
Definition streams.cc:87
absl::StatusOr< std::shared_ptr< Action > > MakeNested(const ActionSchema &schema, bool propagate_io=true, bool forward_headers=true)
Creates a nested action from a schema, parented to this action.
Definition action.cc:887
Definition serialization.h:153
absl::StatusOr< Chunk > ToChunk(const T &value, std::string_view mimetype={}) const
Serializes value into a Chunk.
Definition serialization.h:283
A bidirectional, message-oriented channel between two A11 endpoints.
Definition wire_stream.h:103
An asynchronous, ordered stream of chunks read from and written to A11.
Definition async_node.h:114
A thread-safe registry of AsyncNodes keyed by id.
Definition node_map.h:71
Move-only RAII handle to one action, session, or transport span.
Definition span.h:51
A connection-scoped runtime that multiplexes wire streams and runs actions.
Definition session.h:126
Definition boost_primitives.h:21
size_t inputs
Definition contract.cc:37
size_t outputs
Definition contract.cc:38
std::string value
Definition discover.cc:100
std::string key
Definition discover.cc:764
std::optional< std::string > text
The text, where the value is a string literal or a name bound to one.
Definition discover.cc:596
TokenKind kind
Definition format.cc:1372
std::optional< PortColumns > port
Definition format.cc:66
std::string name
The declaration name and its colon.
Definition format.cc:50
std::string description
The description, quoted exactly as it was written.
Definition format.cc:54
Completion values used by every asynchronous A11 operation.
std::optional< absl::Duration > timeout
Definition main.cc:146
Log levels, log-chunk metadata and the process-wide action log sink.
constexpr bool kLogsAsText
Whether Action::Log reads a T as text rather than as bytes.
Definition action.h:650
Definition action.cc:66
ActionHandler MakeAsyncActionHandler(SyncActionHandler handler)
Adapts a synchronous handler into an asynchronous ActionHandler.
Definition action.cc:131
std::function< absl::Status(std::shared_ptr< Action >)> SyncActionHandler
Synchronous action handler returning a completion status.
Definition action.h:94
constexpr std::string_view kActionHeaderPrefix
Prefix reserved for A11's framework headers.
Definition schema.h:76
constexpr size_t kDefaultMaxConcurrentNestedActions
Default cap on concurrently running nested actions.
Definition action.h:87
std::function< absl::Status(std::shared_ptr< Action >)> OnActionCancelled
Callback invoked when an action is cancelled.
Definition action.h:96
std::function< a11::Task(std::shared_ptr< Action >)> ActionHandler
Asynchronous action handler: runs the action, returns an awaitable.
Definition action.h:92
std::string Bytes
Raw byte payload; an alias of std::string.
Definition types.h:56
constexpr std::string_view kTextMimetype
Media type of UTF-8 text carried as itself.
Definition serialization.h:65
SerializationRegistry & GlobalSerializationRegistry()
Returns the process-wide registry (defaults pre-installed).
Definition serialization.cc:523
absl::flat_hash_map< std::string, Bytes > ByteMap
String-keyed map of byte values (headers, attributes, etc.).
Definition types.h:58
Definition action.h:66
Definition action.h:70
SpanStatus
OpenTelemetry outcome states, mirrored to keep OTel out of this API.
Definition span.h:38
SpanKind
OpenTelemetry span relationships, mirrored to keep OTel out of this API.
Definition span.h:35
Definition action.h:75
Future< Unit > Task
Asynchronous operation whose only successful result is completion itself.
Definition future.h:431
Definition action.h:62
graph::RefId node
Graph ref for this result, or [graph::kNone] without a resolved ref.
Definition resolve.cc:809
stores::ChunkStoreReaderOptions options
Definition runtime_streams.cc:31
Type-and-mimetype indexed serialization of values to/from Chunks.
The full typed interface of an action.
Definition schema.h:144
Per-action runtime settings for stream binding and cleanup.
Definition schema.h:178
Everything about a log other than the object being logged.
Definition log.h:115
Locate an auxiliary producer independently of its stream payload.
Definition stream_reference.h:33
The wire description of an action invocation.
Definition types.h:466
A unit of data: bytes plus optional descriptive metadata.
Definition types.h:173
Output format
Definition main.cc:65
std::string target
Which editor definition syntax is about; every one when empty, which is the default.
Definition main.cc:75
A11's core wire value types: chunks, node fragments and messages.