macro_rules! bootstrap {
(@get_addr) => { ... };
($addr:expr, [$tool:ty $(, $next_tool:ty)* $(,)?]) => { ... };
([$($tool:ty),+ $(,)?]) => { ... };
($addr:expr, $tool:ty) => { ... };
($tool:ty) => { ... };
}Expand description
Macro to bootstrap the runtime for a set of tools. The macro generates the necessary routes for each tool and serves them on the provided address.
§Signed HTTP (Leader <-> Tool authentication)
The runtime can optionally require signed /invoke requests and sign the responses.
Configuration is file-based and loaded from crate::ENV_TOOLKIT_CONFIG_PATH. The file schema
is documented on crate::ToolkitRuntimeConfig.
When enabled (signed_http.mode = "required"), the runtime:
- Rejects unsigned or invalidly signed
/invokerequests (fail-closed). - Verifies the Leader signature against a local allowlist (
allowed_leaders/allowed_leaders_path). - Optionally requires each Tool’s directly observed TLS peer key to match the allowlisted Leader key.
- Caches completed responses by deterministic nonce and canonical input hash; in-flight nonce reuse is rejected.
- Returns exact ordered BCS Tool output bytes and signs the nonce-bound v3 Tool response message.
- Keeps nonce replay and cached-response handling entirely offchain.
Operational note: your gateway/proxy must forward the X-Nexus-Sig-* headers in both directions.
The request body, nonce, and unsigned identity headers require authenticated HTTPS transport.
Set both NEXUS_TOOL_TLS_CERT_PATH and NEXUS_TOOL_TLS_KEY_PATH to terminate TLS in the
Toolkit; setting only one, or invalid TLS credentials, prevents startup. Plain HTTP is served
only when neither is set, which is intended solely for hosts that terminate HTTPS in front of
the Toolkit (e.g. Cloud Run or a load balancer). The Leader only calls https:// Tool URLs,
so a Tool exposed directly over plain HTTP is never invoked.
If a Tool enables require_client_certificate, TLS must terminate in Toolkit or pass through
the gateway; forwarded certificate headers do not establish identity. With that option disabled,
a gateway may terminate the Leader’s TLS connection and use HTTPS to connect to the Toolkit.
§Example config
{
"signed_http": {
"mode": "required",
"allowed_leaders_path": "./allowed_leaders.json",
"tools": {
"xyz.dummy.tool@1": {
"response_signing_key": "0000000000000000000000000000000000000000000000000000000000000000",
"replay_cache_ttl_ms": 300000
}
}
}
}§--meta flag
When the binary is invoked with --meta, the macro prints a JSON array of
tool metadata (one entry per tool) to stdout and exits immediately — no HTTP
server is started. This is used by CI pipelines to extract registration data
from a Docker image without running the tool.
./my-tool --meta # prints JSON array and exits§Request body limits
/invoke enforces a Content-Length limit via warp::body::content_length_limit.
Requests without a Content-Length header are rejected.
§Invocation errors and timeouts
The runtime catches unwinding panics during input decoding, tool construction, authorization, invocation, and output serialization. It returns a generic HTTP 500 response without the panic payload or a tool result signature.
Recovery requires panic = "unwind" (Cargo’s default). The final application’s
workspace controls this setting; with panic = "abort", a panic terminates the process.
Invocation deadlines follow NexusTool::timeout().
§Examples
§One tool running on 127.0.0.1:8080
use nexus_toolkit::bootstrap;
#[tokio::main]
async fn main() {
bootstrap!(YourTool);
}§Multiple tools running on 127.0.0.1:8080
use nexus_toolkit::bootstrap;
#[tokio::main]
async fn main() {
bootstrap!([YourTool, AnotherTool]);
}§One tool running on the provided address
use nexus_toolkit::bootstrap;
#[tokio::main]
async fn main() {
bootstrap!(([127, 0, 0, 1], 8081), YourTool);
}§Multiple tools running on the provided address
use nexus_toolkit::bootstrap;
#[tokio::main]
async fn main() {
bootstrap!(([127, 0, 0, 1], 8081), [YourTool, AnotherTool]);
}