a11::actions::Action Class Reference

A11's unit of work: a schema-described, asynchronously run operation. More...

#include <cpp/a11/actions/action.h>

Inheritance diagram for a11::actions::Action:

Public Member Functions
std::string	GetId () const
	Returns this action's instance id.
absl::Status	SetId (std::string action_id)
	Sets this action's instance id.
ActionSchema	GetSchema () const
	Returns this action's schema.
absl::Status	SetSchema (ActionSchema schema)
	Replaces this action's schema (validated).
absl::Status	BindHandler (ActionHandler handler)
	Binds the handler invoked when the action runs.
ActionHandler	GetHandler () const
	Returns the currently bound handler.
bool	HasHandler () const
	Whether a handler is bound.
ActionSettings	GetSettings () const
	Returns the action's current settings.
absl::Status	SetSettings (ActionSettings settings)
	Replaces the action's settings.
absl::Status	BindStreamsOnInputsByDefault (bool bind)
	Sets whether input port streams are bound by default.
absl::Status	BindStreamsOnOutputsByDefault (bool bind)
	Sets whether output port streams are bound by default.
absl::Status	ClearInputsAfterRun (bool clear=true)
	Sets whether inputs are released after each run.
absl::Status	ClearOutputsAfterRun (bool clear=true)
	Sets whether outputs are released after each run.
absl::Status	BindNodeMap (std::shared_ptr< nodes::NodeMap > node_map)
	Binds the node map that backs this action's ports.
std::shared_ptr< nodes::NodeMap >	GetNodeMap () const
	Returns the bound node map.
absl::Status	BindStream (std::shared_ptr< net::WireStream > stream)
	Binds the wire stream used to dispatch the action remotely.
std::shared_ptr< net::WireStream >	GetStream () const
	Returns the bound wire stream.
absl::Status	BindRegistry (std::shared_ptr< ActionRegistry > registry)
	Binds the registry used to resolve nested actions by name.
std::shared_ptr< ActionRegistry >	GetRegistry () const
	Returns the bound registry.
absl::Status	BindSession (const std::shared_ptr< service::Session > &session)
	Binds the owning session.
std::shared_ptr< service::Session >	GetSession () const
	Returns the owning session, if any.
absl::Status	BindVerifiedAuthorization (std::shared_ptr< const VerifiedAuthorization > authorization)
	Binds identity and authority already verified for this action.
std::shared_ptr< const VerifiedAuthorization >	GetVerifiedAuthorization () const
	Returns the verified authorization bound to this action.
absl::StatusOr< std::shared_ptr< nodes::AsyncNode > >	GetNode (std::string node_id)
	Returns the port node with raw id node_id.
absl::StatusOr< std::shared_ptr< nodes::AsyncNode > >	GetInput (const std::string &name, std::optional< bool > bind_stream=std::nullopt)
	Returns the input port node named name.
absl::StatusOr< std::shared_ptr< nodes::AsyncNode > >	GetOutput (const std::string &name, std::optional< bool > bind_stream=std::nullopt)
	Returns the output port node named name.
absl::StatusOr< std::shared_ptr< nodes::AsyncNode > >	GetPort (const std::string &name)
	Returns the input or output port node named name.
bool	ContainsPort (std::string_view name) const
	Whether the schema declares a port named name.
template<typename T >
absl::Status	Log (const T &value, const LogOptions &options={})
	Logs value on the reserved kActionLogOutput port.
absl::Status	Log (data::Chunk chunk, const LogOptions &options={})
	Logs an already-built chunk, keeping its mimetype and data.
template<typename... Args>
absl::Status	Logf (const absl::FormatSpec< Args... > &format, const Args &... args)
	Logs a formatted string, as ::absl::StrFormat would format it.
template<typename... Args>
absl::Status	LogfWith (const LogOptions &options, const absl::FormatSpec< Args... > &format, const Args &... args)
	Logs a formatted string with explicit options.
absl::StatusOr< std::shared_ptr< nodes::AsyncNode > >	GetLogNode ()
	Returns the log port's node, claiming it for this consumer.
data::ActionMessage	GetActionMessage () const
	Returns the wire a11::data::ActionMessage describing this action.
absl::Status	MapPortsFromMessage (const data::ActionMessage &message)
	Binds this action's ports to the nodes named in message.
data::ByteMap	Headers () const
	Returns a copy of all headers.
absl::StatusOr< std::optional< data::Bytes > >	GetHeader (std::string_view name) const
	Returns header name, or nullopt when absent.
bool	HasHeader (std::string_view name) const
	Whether header name is set.
absl::Status	SetHeader (const std::string &name, data::Bytes value)
	Sets header name to value.
absl::Status	RemoveHeader (std::string_view name)
	Removes header name.
absl::Status	ForwardHeader (const std::shared_ptr< Action > &target, std::string_view name) const
	Copies header name from this action onto target.
absl::Status	ForwardHeadersWithPrefix (const std::shared_ptr< Action > &target, std::string_view prefix=kActionHeaderPrefix) const
	Copies all headers starting with prefix onto target.
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.
absl::StatusOr< std::shared_ptr< Action > >	MakeNested (std::string_view action_name, bool propagate_io=true, bool forward_headers=true)
	Creates a nested action by name from the bound registry.
absl::StatusOr< std::shared_ptr< Action > >	Run ()
	Runs the action's handler locally.
a11::Future< std::shared_ptr< Action > >	Call (data::ByteMap wire_headers={})
	Dispatches the action to a peer over the bound wire stream.
a11::Future< absl::Status >	WaitForDispatch (absl::Duration timeout=absl::InfiniteDuration())
	Awaits acceptance of a remote dispatch.
a11::Future< std::shared_ptr< Action > >	Wait (absl::Duration timeout=absl::InfiniteDuration())
	Awaits completion of the action.
absl::Status	Cancel ()
	Requests cancellation of the action (local or remote).
absl::Status	SetOnCancelled (OnActionCancelled callback)
	Registers a callback invoked when the action is cancelled.
std::string	TraceId () const
	This action's trace id as lowercase hex.
std::string	SpanId () const
	This action's span id as lowercase hex, or empty when untraced.
void	SetSpanAttribute (std::string_view key, std::string_view value)
	Sets a string attribute on this action's span.
void	SetSpanAttribute (std::string_view key, std::int64_t value)
	Sets an integer attribute on this action's span.
void	SetSpanAttribute (std::string_view key, bool value)
	Sets a boolean attribute on this action's span.
void	SetSpanAttribute (std::string_view key, double value)
	Sets a floating-point attribute on this action's span.
void	SetSpanName (std::string_view name)
	Overrides the display name of this action's span.
void	SetSpanStatus (obs::SpanStatus status, std::string_view description={})
	Sets the span status explicitly.
bool	IsDone () const
	Whether the action has finished (successfully or not).
bool	HasBeenRun () const
	Whether the action has been started with Run.
bool	HasBeenCalled () const
	Whether the action has been dispatched with Call.
bool	Cancelled () const
	Whether cancellation has been requested/applied.
absl::Status	GetStatus () const
	The action's completion status (OK while still running).
std::optional< absl::Status >	GetDispatchStatus () const
	The remote dispatch status, or nullopt when not (yet) dispatched.

Static Public Member Functions
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.
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.

Friends
class	ActionRegistry
class	service::Session

Detailed Description

A11's unit of work: a schema-described, asynchronously run operation.

An action pairs an a11::actions::ActionSchema with a handler and a set of typed input/output ports (each an a11::nodes::AsyncNode). Running the action invokes its handler, which reads from the inputs and streams into the outputs. The same action can either run locally (Run) or be dispatched to a peer over a bound a11::net::WireStream (Call). Actions are always held by std::shared_ptr and compose recursively via MakeNested.

Member Function Documentation

BindHandler()

absl::Status a11::actions::Action::BindHandler

(

ActionHandler

handler

)

Binds the handler invoked when the action runs.

BindNodeMap()

absl::Status a11::actions::Action::BindNodeMap

(

std::shared_ptr< nodes::NodeMap >

node_map

)

Binds the node map that backs this action's ports.

BindRegistry()

absl::Status a11::actions::Action::BindRegistry

(

std::shared_ptr< ActionRegistry >

registry

)

Binds the registry used to resolve nested actions by name.

BindSession()

absl::Status a11::actions::Action::BindSession

(

const std::shared_ptr< service::Session > &

session

)

Binds the owning session.

BindStream()

absl::Status a11::actions::Action::BindStream

(

std::shared_ptr< net::WireStream >

stream

)

Binds the wire stream used to dispatch the action remotely.

BindStreamsOnInputsByDefault()

absl::Status a11::actions::Action::BindStreamsOnInputsByDefault

(

bool

bind

)

Sets whether input port streams are bound by default.

BindStreamsOnOutputsByDefault()

absl::Status a11::actions::Action::BindStreamsOnOutputsByDefault

(

bool

bind

)

Sets whether output port streams are bound by default.

BindVerifiedAuthorization()

absl::Status a11::actions::Action::BindVerifiedAuthorization

(

std::shared_ptr< const VerifiedAuthorization >

authorization

)

Binds identity and authority already verified for this action.

Call()

a11::Future< std::shared_ptr< Action > > a11::actions::Action::Call

(

data::ByteMap

wire_headers = {}

)

Dispatches the action to a peer over the bound wire stream.

Parameters

wire_headers

Extra headers to send with the dispatch.

Returns

An awaitable resolving to this action once dispatch is accepted.

Cancel()

absl::Status a11::actions::Action::Cancel

(

)

Requests cancellation of the action (local or remote).

Cancelled()

bool a11::actions::Action::Cancelled

(

)

const

Whether cancellation has been requested/applied.

ClearInputsAfterRun()

absl::Status a11::actions::Action::ClearInputsAfterRun

(

bool

clear = true

)

Sets whether inputs are released after each run.

ClearOutputsAfterRun()

absl::Status a11::actions::Action::ClearOutputsAfterRun

(

bool

clear = true

)

Sets whether outputs are released after each run.

ContainsPort()

bool a11::actions::Action::ContainsPort

(

std::string_view

name

)

const

Whether the schema declares a port named name.

Create()

absl::StatusOr< std::shared_ptr< Action > > a11::actions::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  )

static

Creates an action.

Parameters

schema	Schema describing ports, headers and outputs.
action_id	Instance id; generated when empty.
handler	Handler run by Run/Call; may be bound later.
node_map	Node map backing the action's ports.
stream	Optional wire stream enabling remote Call.
session	Optional owning session.
registry	Optional registry used to resolve nested actions.
max_concurrent_nested_actions	Cap on concurrent nested actions.

Returns

The new action, or an error when the schema is invalid.

ForwardHeader()

absl::Status a11::actions::Action::ForwardHeader	(	const std::shared_ptr< Action > &	target,
		std::string_view	name
	)		const

Copies header name from this action onto target.

ForwardHeadersWithPrefix()

absl::Status a11::actions::Action::ForwardHeadersWithPrefix	(	const std::shared_ptr< Action > &	target,
		std::string_view	prefix = kActionHeaderPrefix
	)		const

Copies all headers starting with prefix onto target.

GetActionMessage()

data::ActionMessage a11::actions::Action::GetActionMessage

(

)

const

Returns the wire a11::data::ActionMessage describing this action.

GetDispatchStatus()

std::optional< absl::Status > a11::actions::Action::GetDispatchStatus

(

)

const

The remote dispatch status, or nullopt when not (yet) dispatched.

GetHandler()

ActionHandler a11::actions::Action::GetHandler

(

)

const

Returns the currently bound handler.

GetHeader()

absl::StatusOr< std::optional< data::Bytes > > a11::actions::Action::GetHeader

(

std::string_view

name

)

const

Returns header name, or nullopt when absent.

GetId()

std::string a11::actions::Action::GetId

(

)

const

Returns this action's instance id.

GetInput()

absl::StatusOr< std::shared_ptr< nodes::AsyncNode > > a11::actions::Action::GetInput	(	const std::string &	name,
		std::optional< bool >	bind_stream = std::nullopt
	)

Returns the input port node named name.

Parameters

name	Input port name from the schema.
bind_stream	Override for whether the node's stream is bound.

Returns

The port's node, or an error when name is not an input.

GetLogNode()

absl::StatusOr< std::shared_ptr< nodes::AsyncNode > > a11::actions::Action::GetLogNode

(

)

Returns the log port's node, claiming it for this consumer.

Claiming suppresses default forwarding and the process sink for this action, so a consumer that presents the logs itself does not also have them reported twice. Claim before the action runs: logs written earlier have already followed the default route.

The node's stream is not bound: on the calling side, binding an output would echo received fragments back to the peer.

GetNode()

absl::StatusOr< std::shared_ptr< nodes::AsyncNode > > a11::actions::Action::GetNode

(

std::string

node_id

)

Returns the port node with raw id node_id.

GetNodeMap()

std::shared_ptr< nodes::NodeMap > a11::actions::Action::GetNodeMap

(

)

const

Returns the bound node map.

GetOutput()

absl::StatusOr< std::shared_ptr< nodes::AsyncNode > > a11::actions::Action::GetOutput	(	const std::string &	name,
		std::optional< bool >	bind_stream = std::nullopt
	)

Returns the output port node named name.

Parameters

name	Output port name from the schema.
bind_stream	Override for whether the node's stream is bound.

Returns

The port's node, or an error when name is not an output.

GetPort()

absl::StatusOr< std::shared_ptr< nodes::AsyncNode > > a11::actions::Action::GetPort

(

const std::string &

name

)

Returns the input or output port node named name.

GetRegistry()

std::shared_ptr< ActionRegistry > a11::actions::Action::GetRegistry

(

)

const

Returns the bound registry.

GetSchema()

ActionSchema a11::actions::Action::GetSchema

(

)

const

Returns this action's schema.

GetSession()

std::shared_ptr< service::Session > a11::actions::Action::GetSession

(

)

const

Returns the owning session, if any.

GetSettings()

ActionSettings a11::actions::Action::GetSettings

(

)

const

Returns the action's current settings.

GetStatus()

absl::Status a11::actions::Action::GetStatus

(

)

const

The action's completion status (OK while still running).

GetStream()

std::shared_ptr< net::WireStream > a11::actions::Action::GetStream

(

)

const

Returns the bound wire stream.

GetVerifiedAuthorization()

std::shared_ptr< const VerifiedAuthorization > a11::actions::Action::GetVerifiedAuthorization

(

)

const

Returns the verified authorization bound to this action.

HasBeenCalled()

bool a11::actions::Action::HasBeenCalled

(

)

const

Whether the action has been dispatched with Call.

HasBeenRun()

bool a11::actions::Action::HasBeenRun

(

)

const

Whether the action has been started with Run.

HasHandler()

bool a11::actions::Action::HasHandler

(

)

const

Whether a handler is bound.

HasHeader()

bool a11::actions::Action::HasHeader

(

std::string_view

name

)

const

Whether header name is set.

Headers()

data::ByteMap a11::actions::Action::Headers

(

)

const

Returns a copy of all headers.

IsDone()

bool a11::actions::Action::IsDone

(

)

const

Whether the action has finished (successfully or not).

Log() [1/2]

template<typename T >

absl::Status a11::actions::Action::Log	(	const T &	value,
		const LogOptions &	options = {}
	)

Logs value on the reserved kActionLogOutput port.

The object is converted into a a11::data::Chunk similar to a11::nodes::AsyncNode::Put, mapping string types (std::string, std::string_view, string literals, and const char*) to a11::data::kTextMimetype. options carries the level, the media type, the channel, the source location and any extra metadata; see a11::actions::LogOptions. The chunk's timestamp is always set.

Only a running handler may log. Logging before Run, from the calling side of a Call, or after a cancellation that beat the start returns FailedPrecondition – the log would have nowhere to go and no reader to close it. Nothing else about logging can fail the action: once the chunk is built, a transport or lifecycle failure is reported through the sink rather than returned, so an action never fails because it narrated itself.

Where the log goes: an unclaimed nested action forwards it through its parent's log, while an unclaimed root action reports it to the process's a11::actions::ActionLogSink and also to an attached peer. A local consumer that claimed the port with GetLogNode receives it there instead. Nobody has to close the port; the action closes it with its other outputs.

Parameters

value	Object to log.
options	Level, media type, channel, location and extra metadata.

Returns

OK once the log has been reported, or an error when the action is not running or value cannot be serialized.

Log() [2/2]

absl::Status a11::actions::Action::Log	(	data::Chunk	chunk,
		const LogOptions &	options = {}
	)

Logs an already-built chunk, keeping its mimetype and data.

LogOptions::mimetype must be empty here: the chunk already says what it is, and two answers to that question is a bug rather than a precedence rule.

Logf()

template<typename... Args>

absl::Status a11::actions::Action::Logf	(	const absl::FormatSpec< Args... > &	format,
		const Args &...	args
	)

Logs a formatted string, as ::absl::StrFormat would format it.

action->Logf("read %d of %d pages", done, total);
action->LogfWith({.level = "warning", .channel = "fetch"},
                 "retrying %s", url);

The format is checked at compile time, so it must be a literal or an ::absl::ParsedFormat; to log a string computed at runtime, use Log.

LogfWith()

template<typename... Args>

absl::Status a11::actions::Action::LogfWith	(	const LogOptions &	options,
		const absl::FormatSpec< Args... > &	format,
		const Args &...	args
	)

Logs a formatted string with explicit options.

A second name rather than a leading-LogOptions overload of Logf, because ::absl::FormatSpec has a catch-all constructor to diagnose a non-constexpr format: it makes Logf(options, ...) match both overloads, one better in its first argument and the other in its second, which is ambiguous. Keeping the format spec a direct parameter is what keeps the format checked at compile time, so the name gives way rather than the checking.

MakeNested() [1/2]

absl::StatusOr< std::shared_ptr< Action > > a11::actions::Action::MakeNested	(	const ActionSchema &	schema,
		bool	propagate_io = true,
		bool	forward_headers = true
	)

Creates a nested action from a schema, parented to this action.

The child always receives a new action id and therefore new derived port ids. With propagate_io it shares this action's NodeMap, stream, and Session; it does not copy this action's port mappings. Registry and nested concurrency context are inherited in either mode. Unclaimed child logs forward through this action by default.

Parameters

schema	Schema for the nested action.
propagate_io	Share this action's NodeMap, stream, and Session.
forward_headers	Copy this action's framework headers to the child.

Returns

The nested action.

MakeNested() [2/2]

absl::StatusOr< std::shared_ptr< Action > > a11::actions::Action::MakeNested	(	std::string_view	action_name,
		bool	propagate_io = true,
		bool	forward_headers = true
	)

Creates a nested action by name from the bound registry.

The child has its own id and port ids. With propagate_io it shares this action's NodeMap, stream, and Session, but not its port mappings.

Parameters

action_name	Registered action to instantiate.
propagate_io	Share this action's NodeMap, stream, and Session.
forward_headers	Copy this action's framework headers to the child.

Returns

The nested action, or NotFound when action_name is unknown.

MakeNodeId()

absl::StatusOr< std::string > a11::actions::Action::MakeNodeId ( std::string_view  action_id, std::string_view  node_name  )

static

Derives the node id for port node_name of action action_id.

MapPortsFromMessage()

absl::Status a11::actions::Action::MapPortsFromMessage

(

const data::ActionMessage &

message

)

Binds this action's ports to the nodes named in message.

RemoveHeader()

absl::Status a11::actions::Action::RemoveHeader

(

std::string_view

name

)

Removes header name.

Run()

absl::StatusOr< std::shared_ptr< Action > > a11::actions::Action::Run

(

)

Runs the action's handler locally.

Starts the handler and returns the action immediately; use Wait or the completion status to observe the outcome. (The Python binding also exposes this as run_in_background.)

Returns

This action, or an error when it cannot be started.

SetHeader()

absl::Status a11::actions::Action::SetHeader	(	const std::string &	name,
		data::Bytes	value
	)

Sets header name to value.

SetId()

absl::Status a11::actions::Action::SetId

(

std::string

action_id

)

Sets this action's instance id.

SetOnCancelled()

absl::Status a11::actions::Action::SetOnCancelled

(

OnActionCancelled

callback

)

Registers a callback invoked when the action is cancelled.

SetSchema()

absl::Status a11::actions::Action::SetSchema

(

ActionSchema

schema

)

Replaces this action's schema (validated).

SetSettings()

absl::Status a11::actions::Action::SetSettings

(

ActionSettings

settings

)

Replaces the action's settings.

SetSpanAttribute() [1/4]

void a11::actions::Action::SetSpanAttribute	(	std::string_view	key,
		bool	value
	)

Sets a boolean attribute on this action's span.

SetSpanAttribute() [2/4]

void a11::actions::Action::SetSpanAttribute	(	std::string_view	key,
		double	value
	)

Sets a floating-point attribute on this action's span.

SetSpanAttribute() [3/4]

void a11::actions::Action::SetSpanAttribute	(	std::string_view	key,
		std::int64_t	value
	)

Sets an integer attribute on this action's span.

SetSpanAttribute() [4/4]

void a11::actions::Action::SetSpanAttribute	(	std::string_view	key,
		std::string_view	value
	)

Sets a string attribute on this action's span.

No-op when the action is not traced. Intended to be called from the handler while the span is active (e.g. langfuse.observation.input / .output).

SetSpanName()

void a11::actions::Action::SetSpanName

(

std::string_view

name

)

Overrides the display name of this action's span.

SetSpanStatus()

void a11::actions::Action::SetSpanStatus	(	obs::SpanStatus	status,
		std::string_view	description = {}
	)

Sets the span status explicitly.

Suppresses the automatic status the framework would otherwise record from the action's completion status.

SpanId()

std::string a11::actions::Action::SpanId

(

)

const

This action's span id as lowercase hex, or empty when untraced.

TraceId()

std::string a11::actions::Action::TraceId

(

)

const

This action's trace id as lowercase hex.

Empty when the action is not traced (no OTel context / tracing not configured). Valid once the action has started and until it finishes.

Wait()

a11::Future< std::shared_ptr< Action > > a11::actions::Action::Wait

(

absl::Duration

timeout = absl::InfiniteDuration()

)

Awaits completion of the action.

Parameters

timeout

Maximum time to wait.

Returns

An awaitable resolving to this action when it finishes (or fails with the action's error status).

WaitForDispatch()

a11::Future< absl::Status > a11::actions::Action::WaitForDispatch

(

absl::Duration

timeout = absl::InfiniteDuration()

)

Awaits acceptance of a remote dispatch.

Parameters

timeout

Maximum time to wait.

Returns

An awaitable resolving to the dispatch status.

Friends And Related Symbol Documentation

ActionRegistry

friend class ActionRegistry

friend

service::Session

friend class service::Session

friend

---

The documentation for this class was generated from the following files:

• cpp/a11/actions/action.h
• cpp/a11/actions/action.cc