|
A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
|
Namespaces | |
| namespace | internal |
Classes | |
| class | Action |
| A11's unit of work: a schema-described, asynchronously run operation. More... | |
| struct | ActionHeaderSchema |
| Schema for a single header an action accepts. More... | |
| class | ActionLimiter |
| Cancellation-aware counting semaphore for nested-action concurrency. More... | |
| struct | ActionPortSchema |
| Schema for a single input or output port of an action. More... | |
| class | ActionRegistry |
| A thread-safe catalogue mapping action names to schema and handler. More... | |
| struct | ActionSchema |
| The full typed interface of an action. More... | |
| struct | ActionSettings |
| Per-action runtime settings for stream binding and cleanup. More... | |
| struct | AuthorizationContext |
| Result of installing a verified connection context. More... | |
| class | AuthorizationContextStore |
| Bounded verified contexts scoped to the receiving Session and stream. More... | |
| struct | AuthorizationEnvelope |
| A versioned ordered sequence of compact signed delegation statements. More... | |
| struct | BuiltinAction |
| A schema and handler pair the registry resolves without holding. More... | |
| struct | LogOptions |
| Everything about a log other than the object being logged. More... | |
| struct | LogRecord |
| One log as a sink sees it. More... | |
| struct | SchemaQuery |
| Which schemas to write, and how much of each. More... | |
| struct | VerifiedAuthorization |
| Identity and effective authority returned by an application verifier. More... | |
Typedefs | |
| using | ActionHandler = std::function< a11::Task(std::shared_ptr< Action >)> |
| Asynchronous action handler: runs the action, returns an awaitable. | |
| using | SyncActionHandler = std::function< absl::Status(std::shared_ptr< Action >)> |
| Synchronous action handler returning a completion status. | |
| using | OnActionCancelled = std::function< absl::Status(std::shared_ptr< Action >)> |
| Callback invoked when an action is cancelled. | |
| using | AuthorizationVerifier = std::function< absl::StatusOr< VerifiedAuthorization >(std::string_view)> |
| using | ActionLogSink = std::function< void(const LogRecord &)> |
| What the process does with a log it consumes itself. | |
Enumerations | |
| enum class | PortView { kCallable , kAll } |
| Which ports a written schema includes. More... | |
| enum class | LogLevel { kDebug , kInfo , kWarning , kError , kCritical } |
| Severity of a log chunk. More... | |
Functions | |
| ActionHandler | MakeAsyncActionHandler (SyncActionHandler handler) |
| Adapts a synchronous handler into an asynchronous ActionHandler. | |
| absl::StatusOr< std::string > | EncodeAuthorization (const AuthorizationEnvelope &envelope) |
| Validate and canonically encode an authorization envelope as MessagePack. | |
| absl::StatusOr< AuthorizationEnvelope > | DecodeAuthorization (std::string_view value) |
| Decode a canonical, bounded native authorization value. | |
| absl::StatusOr< std::string > | AuthorizationToText (const AuthorizationEnvelope &envelope) |
| Convert a native value to an ASCII physical HTTP header. | |
| absl::StatusOr< std::string > | AuthorizationFingerprint (const AuthorizationEnvelope &envelope) |
| Return an unpadded base64url SHA-256 identifier for the exact envelope. | |
| absl::StatusOr< AuthorizationEnvelope > | AuthorizationFromText (std::string_view value) |
| Convert an ASCII physical HTTP header to the native envelope. | |
| absl::StatusOr< std::optional< AuthorizationEnvelope > > | GetAuthorization (const Action &action) |
| Decode the complete authorization on an action, when present. | |
| absl::Status | SetAuthorization (const std::shared_ptr< Action > &action, const std::optional< AuthorizationEnvelope > &envelope) |
| Set or remove a complete authorization and clear any context reference. | |
| absl::StatusOr< std::optional< std::string > > | GetAuthorizationReference (const Action &action) |
| Read the receiver-issued raw 128-bit context reference, when present. | |
| absl::Status | SetAuthorizationReference (const std::shared_ptr< Action > &action, const std::optional< std::string > &context_id) |
| Set or remove a raw 128-bit context reference and clear any full proof. | |
| ActionSchema | AuthorizationActionSchema () |
| Schema of the transport-independent connection authorizing action. | |
| absl::StatusOr< std::shared_ptr< AuthorizationContextStore > > | InstallAuthorizer (const std::shared_ptr< ActionRegistry > ®istry, AuthorizationVerifier verifier, std::shared_ptr< AuthorizationContextStore > contexts=nullptr) |
Register __authorize__ for a native verifier and context store. | |
| bool | IsBuiltinAction (std::string_view name) |
Whether name is a builtin every registry answers for. | |
| const BuiltinAction *absl_nullable | GetBuiltinAction (std::string_view name) |
The builtin named name, or null. | |
| const std::vector< std::string > & | BuiltinActionNames () |
| Every builtin's name, sorted. | |
| bool | SchemaQueryAccepts (const SchemaQuery &query, std::string_view name) |
Whether name matches query's name filters. | |
| absl::StatusOr< SchemaQuery > | ParseSchemaQuery (std::string_view encoded) |
Parses a SchemaQuery from the request port's JSON. | |
| absl::StatusOr< SchemaQuery > | ParseSchemaQueryString (std::string_view query) |
Parses a SchemaQuery from a URL query string. | |
| nlohmann::json | SchemaToJson (const ActionSchema &schema, bool runnable, PortView ports=PortView::kCallable) |
One schema as an actions entry. | |
| nlohmann::json | RegistryToJson (const ActionRegistry ®istry, const SchemaQuery &query) |
A whole document: every schema in registry that query accepts. | |
| absl::StatusOr< std::string > | RegistryToJsonText (const ActionRegistry ®istry, const SchemaQuery &query) |
| RegistryToJson as text, or why it could not be encoded. | |
| absl::StatusOr< std::string > | SchemaToJsonText (const ActionSchema &schema, bool runnable, PortView ports=PortView::kCallable) |
| One schema as a whole document, for a route that answers with one. | |
| absl::StatusOr< ActionSchema > | SchemaFromJson (const nlohmann::json &entry) |
The schema an actions entry was written from. | |
| absl::StatusOr< ActionSchema > | SchemaFromJsonText (std::string_view encoded) |
SchemaFromJson, parsing encoded first. | |
| absl::StatusOr< std::vector< nlohmann::json > > | SchemasInDocument (const nlohmann::json &document) |
The actions entries of document, or why there are none to read. | |
| std::string_view | LogLevelName (LogLevel level) |
Canonical lowercase name of level, as written to a chunk. | |
| absl::StatusOr< LogLevel > | ParseLogLevel (std::string_view name) |
| Parses a level name. | |
| absl::LogSeverity | LogLevelToSeverity (LogLevel level) |
The Abseil severity level is reported at. | |
| void | SetActionLogSink (ActionLogSink sink) |
Installs sink as the process's action log sink. | |
| ActionLogSink | GetActionLogSink () |
| Returns the installed sink; never null. | |
| void | ReportLog (const LogRecord &record) |
Reports record to the installed sink. | |
| bool | IsTextualLogMimetype (std::string_view mimetype) |
Whether a log payload of mimetype reads as text. | |
| std::string | LogText (const LogRecord &record) |
record as one line: its payload where that is text, a description of it where it is not. | |
| LogRecord | LogRecordFromChunk (const data::Chunk &chunk, std::string_view action_name={}, std::string_view action_id={}) |
| Reads a LogRecord back out of a log chunk. | |
| absl::StatusOr< data::Chunk > | StatusToChunk (const absl::Status &status) |
| Encodes a status as a chunk (mimetype kActionStatusMimetype). | |
| absl::StatusOr< absl::Status > | StatusFromChunk (const data::Chunk &chunk) |
| Decodes a status previously encoded by StatusToChunk. | |
Variables | |
| constexpr size_t | kDefaultMaxConcurrentNestedActions = 64 |
| Default cap on concurrently running nested actions. | |
| constexpr std::string_view | kAuthorizationHeader = "x-a11-auth" |
| constexpr std::string_view | kAuthorizationReferenceHeader |
| constexpr std::string_view | kAuthorizationDefaultHeader |
| constexpr std::string_view | kAuthorizationReplaceHeader |
| constexpr std::string_view | kAuthorizeAction = "__authorize__" |
| constexpr int | kAuthorizationVersion = 1 |
| constexpr size_t | kMaxAuthorizationBytes = 16 * 1024 |
| constexpr size_t | kMaxAuthorizationHops = 8 |
| constexpr std::string_view | kListActionsName = "__list_actions__" |
| Lists the actions a peer serves, with their schemas. | |
| constexpr std::string_view | kGetSchemaName = "__get_schema__" |
| Returns one action's schema, or NotFound. | |
| constexpr std::string_view | kPingName = "__ping" |
| Echoes a value, so a caller can tell A11 from anything holding a port. | |
| constexpr std::string_view | kSchemaDocumentFormat = "a11.actions/v1" |
The format field of the schema document. | |
| constexpr LogLevel | kDefaultLogLevel = LogLevel::kInfo |
| The default level of a log written without one. | |
| constexpr std::string_view | kLogLevelAttribute = "level" |
| Metadata attribute naming the log's level. | |
| constexpr std::string_view | kLogInternalAttribute = "internal" |
| Metadata attribute marking a log not meant for an end user. | |
| constexpr std::string_view | kLogChannelAttribute = "channel" |
| Metadata attribute naming the log's logical channel. | |
| constexpr std::string_view | kLogFileAttribute = "file" |
| Metadata attribute naming the source file the log came from. | |
| constexpr std::string_view | kLogLinenoAttribute = "lineno" |
| Metadata attribute naming the source line the log came from. | |
| constexpr std::string_view | kLogChildActionAttribute = "a11-child-action" |
| Metadata attribute naming the nested action that wrote a log. | |
| constexpr std::string_view | kLogChildCallIdAttribute |
| Metadata attribute naming the nested action call that wrote a log. | |
| constexpr std::string_view | kLogInternalTrue = "true" |
| The value kLogInternalAttribute takes when the log is internal. | |
| constexpr std::string_view | kLogInternalFalse = "false" |
| The value kLogInternalAttribute takes when it is not. | |
| constexpr std::string_view | kActionStatusMimetype = data::kStatusMimetype |
| Mimetype marking a chunk that carries an action status. | |
| constexpr std::string_view | kActionStatusOutput = "__status__" |
| Reserved output port name carrying the action's completion status. | |
| constexpr std::string_view | kActionDispatchStatusOutput |
| Reserved output port name carrying the remote dispatch status. | |
| constexpr std::string_view | kActionLogOutput = "__log__" |
| Reserved output port name carrying the action's log. | |
| constexpr std::string_view | kCancelActionName = "__cancel__" |
| Reserved action name used to signal cancellation to a peer. | |
| constexpr std::string_view | kCancelActionHeader = "__action" |
| Header naming the action targeted by a cancel request. | |
| constexpr std::string_view | kActionHeaderPrefix = "x-a11-" |
| Prefix reserved for A11's framework headers. | |
| using a11::actions::ActionHandler = typedef std::function<a11::Task(std::shared_ptr<Action>)> |
Asynchronous action handler: runs the action, returns an awaitable.
| using a11::actions::ActionLogSink = typedef std::function<void(const LogRecord&)> |
What the process does with a log it consumes itself.
One sink is installed per process. It runs on the thread that called Action::Log and must not block or fail.
| using a11::actions::AuthorizationVerifier = typedef std::function<absl::StatusOr<VerifiedAuthorization>(std::string_view)> |
| using a11::actions::OnActionCancelled = typedef std::function<absl::Status(std::shared_ptr<Action>)> |
Callback invoked when an action is cancelled.
| using a11::actions::SyncActionHandler = typedef std::function<absl::Status(std::shared_ptr<Action>)> |
Synchronous action handler returning a completion status.
|
strong |
|
strong |
Which ports a written schema includes.
kCallable omits inputs the receiver autofills, because a caller cannot write them: an autofilled input must be empty when the default is applied, so offering it to a model or a flow only invites a call that fails. kAll keeps them, flagged, for a reader that is inspecting rather than calling.
| Enumerator | |
|---|---|
| kCallable | What a caller may write. The default. |
| kAll | Everything the schema declares, autofills flagged. |
| ActionSchema a11::actions::AuthorizationActionSchema | ( | ) |
Schema of the transport-independent connection authorizing action.
| absl::StatusOr< std::string > a11::actions::AuthorizationFingerprint | ( | const AuthorizationEnvelope & | envelope | ) |
Return an unpadded base64url SHA-256 identifier for the exact envelope.
| absl::StatusOr< AuthorizationEnvelope > a11::actions::AuthorizationFromText | ( | std::string_view | value | ) |
Convert an ASCII physical HTTP header to the native envelope.
| absl::StatusOr< std::string > a11::actions::AuthorizationToText | ( | const AuthorizationEnvelope & | envelope | ) |
Convert a native value to an ASCII physical HTTP header.
| const std::vector< std::string > & a11::actions::BuiltinActionNames | ( | ) |
Every builtin's name, sorted.
| absl::StatusOr< AuthorizationEnvelope > a11::actions::DecodeAuthorization | ( | std::string_view | value | ) |
Decode a canonical, bounded native authorization value.
| absl::StatusOr< std::string > a11::actions::EncodeAuthorization | ( | const AuthorizationEnvelope & | envelope | ) |
Validate and canonically encode an authorization envelope as MessagePack.
| ActionLogSink a11::actions::GetActionLogSink | ( | ) |
Returns the installed sink; never null.
| absl::StatusOr< std::optional< AuthorizationEnvelope > > a11::actions::GetAuthorization | ( | const Action & | action | ) |
Decode the complete authorization on an action, when present.
| absl::StatusOr< std::optional< std::string > > a11::actions::GetAuthorizationReference | ( | const Action & | action | ) |
Read the receiver-issued raw 128-bit context reference, when present.
| const BuiltinAction *absl_nullable a11::actions::GetBuiltinAction | ( | std::string_view | name | ) |
The builtin named name, or null.
| absl::StatusOr< std::shared_ptr< AuthorizationContextStore > > a11::actions::InstallAuthorizer | ( | const std::shared_ptr< ActionRegistry > & | registry, |
| AuthorizationVerifier | verifier, | ||
| std::shared_ptr< AuthorizationContextStore > | contexts | ||
| ) |
Register __authorize__ for a native verifier and context store.
| bool a11::actions::IsBuiltinAction | ( | std::string_view | name | ) |
Whether name is a builtin every registry answers for.
| bool a11::actions::IsTextualLogMimetype | ( | std::string_view | mimetype | ) |
Whether a log payload of mimetype reads as text.
Text and JSON payloads are textual. LogText describes other payloads instead of rendering their bytes.
| std::string_view a11::actions::LogLevelName | ( | LogLevel | level | ) |
Canonical lowercase name of level, as written to a chunk.
| absl::LogSeverity a11::actions::LogLevelToSeverity | ( | LogLevel | level | ) |
The Abseil severity level is reported at.
Never FATAL.
| LogRecord a11::actions::LogRecordFromChunk | ( | const data::Chunk & | chunk, |
| std::string_view | action_name = {}, |
||
| std::string_view | action_id = {} |
||
| ) |
Reads a LogRecord back out of a log chunk.
Unknown attributes are ignored. A missing level uses kDefaultLogLevel.
| std::string a11::actions::LogText | ( | const LogRecord & | record | ) |
record as one line: its payload where that is text, a description of it where it is not.
| ActionHandler a11::actions::MakeAsyncActionHandler | ( | SyncActionHandler | handler | ) |
Adapts a synchronous handler into an asynchronous ActionHandler.
| absl::StatusOr< LogLevel > a11::actions::ParseLogLevel | ( | std::string_view | name | ) |
Parses a level name.
Case-insensitive, and accepts warn for kWarning and fatal for kCritical – the two spellings host languages differ on. An empty name is kDefaultLogLevel.
| absl::StatusOr< SchemaQuery > a11::actions::ParseSchemaQuery | ( | std::string_view | encoded | ) |
Parses a SchemaQuery from the request port's JSON.
An empty or null document is the default request, not an error: asking "what do you serve" with no qualification is the common case.
| absl::StatusOr< SchemaQuery > a11::actions::ParseSchemaQueryString | ( | std::string_view | query | ) |
Parses a SchemaQuery from a URL query string.
| query | The part after ?, without it. May be empty. |
| nlohmann::json a11::actions::RegistryToJson | ( | const ActionRegistry & | registry, |
| const SchemaQuery & | request | ||
| ) |
A whole document: every schema in registry that query accepts.
| absl::StatusOr< std::string > a11::actions::RegistryToJsonText | ( | const ActionRegistry & | registry, |
| const SchemaQuery & | request | ||
| ) |
RegistryToJson as text, or why it could not be encoded.
| void a11::actions::ReportLog | ( | const LogRecord & | record | ) |
Reports record to the installed sink.
Never fails.
| absl::StatusOr< ActionSchema > a11::actions::SchemaFromJson | ( | const nlohmann::json & | entry | ) |
The schema an actions entry was written from.
The exact inverse of SchemaToJson, for a side that has to call what it was told about: a tool bridge registering a reverse-dispatch proxy, or a flow run against a peer registering the peer's actions for their schemas alone. What cannot survive the trip comes back empty: typeinfo is a local handle, and receiver-owned autofill defaults remain local.
| entry | One entry from a document's actions array. |
| absl::StatusOr< ActionSchema > a11::actions::SchemaFromJsonText | ( | std::string_view | encoded | ) |
SchemaFromJson, parsing encoded first.
| bool a11::actions::SchemaQueryAccepts | ( | const SchemaQuery & | request, |
| std::string_view | name | ||
| ) |
Whether name matches query's name filters.
| absl::StatusOr< std::vector< nlohmann::json > > a11::actions::SchemasInDocument | ( | const nlohmann::json & | document | ) |
The actions entries of document, or why there are none to read.
Accepts a bare array too, so a caller need not care whether it was handed a whole document or just its entries.
| nlohmann::json a11::actions::SchemaToJson | ( | const ActionSchema & | schema, |
| bool | runnable, | ||
| PortView | ports = PortView::kCallable |
||
| ) |
One schema as an actions entry.
| schema | The action's interface. |
| runnable | Whether this side holds a handler for it. The registry's annotation on the schema, not part of the schema itself. |
| ports | Which ports to include. |
| absl::StatusOr< std::string > a11::actions::SchemaToJsonText | ( | const ActionSchema & | schema, |
| bool | runnable, | ||
| PortView | ports | ||
| ) |
One schema as a whole document, for a route that answers with one.
| void a11::actions::SetActionLogSink | ( | ActionLogSink | sink | ) |
Installs sink as the process's action log sink.
A null sink restores the default, which reports the log through Abseil at the record's severity and source location.
| absl::Status a11::actions::SetAuthorization | ( | const std::shared_ptr< Action > & | action, |
| const std::optional< AuthorizationEnvelope > & | envelope | ||
| ) |
Set or remove a complete authorization and clear any context reference.
| absl::Status a11::actions::SetAuthorizationReference | ( | const std::shared_ptr< Action > & | action, |
| const std::optional< std::string > & | context_id | ||
| ) |
Set or remove a raw 128-bit context reference and clear any full proof.
| absl::StatusOr< absl::Status > a11::actions::StatusFromChunk | ( | const data::Chunk & | chunk | ) |
Decodes a status previously encoded by StatusToChunk.
| absl::StatusOr< data::Chunk > a11::actions::StatusToChunk | ( | const absl::Status & | status | ) |
Encodes a status as a chunk (mimetype kActionStatusMimetype).
|
inlineconstexpr |
Reserved output port name carrying the remote dispatch status.
|
inlineconstexpr |
Prefix reserved for A11's framework headers.
|
inlineconstexpr |
Reserved output port name carrying the action's log.
Every action has one, declared by nobody: it is not in the schema, so it does not appear in an a11::data::ActionMessage, in a tool definition, or in the flow catalogue, and a handler that never logs never materialises it. Written through Action::Log, closed with the action's other outputs. See a11/actions/log.h.
|
inlineconstexpr |
Mimetype marking a chunk that carries an action status.
|
inlineconstexpr |
Reserved output port name carrying the action's completion status.
|
inlineconstexpr |
|
inlineconstexpr |
|
inlineconstexpr |
|
inlineconstexpr |
|
inlineconstexpr |
|
inlineconstexpr |
|
inlineconstexpr |
Header naming the action targeted by a cancel request.
|
inlineconstexpr |
Reserved action name used to signal cancellation to a peer.
|
inlineconstexpr |
The default level of a log written without one.
|
inlineconstexpr |
Default cap on concurrently running nested actions.
|
inlineconstexpr |
Returns one action's schema, or NotFound.
|
inlineconstexpr |
Lists the actions a peer serves, with their schemas.
|
inlineconstexpr |
Metadata attribute naming the log's logical channel.
A free-form label consumers can use to filter related messages.
|
inlineconstexpr |
Metadata attribute naming the nested action that wrote a log.
|
inlineconstexpr |
Metadata attribute naming the nested action call that wrote a log.
|
inlineconstexpr |
Metadata attribute naming the source file the log came from.
|
inlineconstexpr |
Metadata attribute marking a log not meant for an end user.
Written as "true" or "false"; absent means false. Consumers can use it to filter framework bookkeeping.
|
inlineconstexpr |
The value kLogInternalAttribute takes when it is not.
|
inlineconstexpr |
The value kLogInternalAttribute takes when the log is internal.
|
inlineconstexpr |
Metadata attribute naming the log's level.
Attributes intrinsic to the log record use unprefixed names on the reserved log port. Nested-action provenance uses the framework-prefixed attributes below.
|
inlineconstexpr |
Metadata attribute naming the source line the log came from.
|
inlineconstexpr |
|
inlineconstexpr |
|
inlineconstexpr |
Echoes a value, so a caller can tell A11 from anything holding a port.
The name and shape a gateway has always used are preserved because clients in four languages probe with it. The probe works against every A11 service because registration is automatic.
|
inlineconstexpr |
The format field of the schema document.