Skip to content
calternal docs

calternal_api::actions

Contract action metadata and request mapping (#484, #760, #818, #821, DESIGN §41). Adapters share this mapping; server routes retain all data validation and authorization. Registry-marked Home paths and Tag names keep their encoded separators in a fixed route slot; item IDs remain single segments. No caller can choose a method, endpoint or authority header. Input failures identify the action and schema field without copying caller values.

Source: crates/calternal-api/src/actions.rs

Structs

Section titled “Structs”

Action

Section titled “Action”
pub struct Action

Generated route metadata. Scope labels describe the route, never grant it.

Fields

  • pub events: Vec<crate::events::EventDefinition>
  • pub id: String
  • pub name: String
  • pub aliases: Vec<String>: Old discovery names that dispatch to this same action and route (#821).
  • pub help: String
  • pub tier: Option<McpTier>: Reviewed MCP tier when the registry declares one. Missing tiers keep legacy action behavior until the registry migration reviews them (#999).
  • pub method: String
  • pub path: String
  • pub scopes: Vec<String>
  • pub authority: String: Declarative route authority, never an access grant (#833, DESIGN §41).
  • pub fresh_assertion: bool: Whether the route requires a recent account assertion (#833).
  • pub replay: String: safe_read permits bounded safe-method retries; other values deny replay (#835).
  • pub responses: Value: Published response shapes retain continuation and revision fields (#833, #835).
  • pub continuation: Value: Route-specific continuation inputs, outputs and recovery, without invented paging (#835).
  • pub fresh_auth: bool: Recent assertion required for permanent removal or public grant changes (#739, #743).
  • pub enforce_scopes: bool: Apply reviewed requirements at the server route boundary (#774); legacy guards stay in place.
  • pub read_only: bool
  • pub destructive: bool
  • pub surfaces: Vec<String>
  • pub input_schema: Value
  • pub request_encoding: String
  • pub request_content_type: Option<String>
  • pub response_encoding: String

Implements: Debug, Deserialize

Action::encode_body

Section titled “Action::encode_body”
pub fn encode_body(&self, body: Option<&Value>) -> Result<Vec<u8>, String>

Encode the declared body transport within its fixed byte limit and name safe repair hints (#484, #818).

Action::prepare

Section titled “Action::prepare”
pub fn prepare(&self, input: &Value) -> Result<ActionRequest, String>

Map declared input groups to one fixed route and report schema paths (#484, #818). The API validates body semantics; adapters reject undeclared parameters.

Source: crates/calternal-api/src/actions.rs:16

ActionRequest

Section titled “ActionRequest”
pub struct ActionRequest

A mapped API request. Raw bodies are decoded once before dispatch. Authorization is supplied by the transport only (#484, DESIGN §41).

Fields

  • pub uri: String
  • pub headers: Vec<(String, String)>
  • pub body: Option<Value>
  • pub poll_ms: u64

Source: crates/calternal-api/src/actions.rs:76

Enums

Section titled “Enums”

McpTier

Section titled “McpTier”
pub enum McpTier

How the MCP client discovers one generated action (#975, DESIGN §62).

Variants

  • Core: Always present in the small default tool list.
  • Discoverable: Returned on demand by find_tools.
  • Hidden: Never listed or invoked from MCP.

Implements: Clone, Copy, Debug, Deserialize, PartialEq, Eq

Source: crates/calternal-api/src/actions.rs:65

Functions

Section titled “Functions”

decode_response

Section titled “decode_response”
pub fn decode_response(
    encoding: &str,
    bytes: &[u8],
    headers: &[(String, String)],
    complete: bool,
) -> Result<Value, String>

Convert non-JSON responses into a lossless tool envelope. Only declared transfer metadata is returned; cookies and credentials never become output. SSE polls expose complete frames only, so a durable cursor can be resumed.

Source: crates/calternal-api/src/actions.rs:242

registry

Section titled “registry”
pub fn registry() -> &'static [Action]

Parse once per process; the generator and CI validate these embedded bytes.

Source: crates/calternal-api/src/actions.rs:84

Constants

Section titled “Constants”

MAX_BASE64_TOOL_BYTES

Section titled “MAX_BASE64_TOOL_BYTES”
pub const MAX_BASE64_TOOL_BYTES: usize

Bound raw bytes so their base64 envelope and metadata stay below 1 MiB (#760).

Source: crates/calternal-api/src/actions.rs:237

MAX_TOOL_BYTES

Section titled “MAX_TOOL_BYTES”
pub const MAX_TOOL_BYTES: usize

Fixed response and upload chunk budget across generated surfaces (#484).

Source: crates/calternal-api/src/actions.rs:235