axum-apcore

Expose Axum routes as AI-perceivable modules.

Axum integration for the apcore AI-Perceivable Core ecosystem.

axum-apcore automatically scans your Axum routes and exposes them as apcore modules — with full execution, context mapping, MCP serving, and OpenAI tool export. Define your routes once, and both code and AI can discover, understand, and invoke them through enforced schemas and behavioral annotations.

Features

• Route scanning — Discover Axum routes via the native metadata registry or OpenAPI (utoipa) specs
• ap_handler! macro — Register route metadata at compile time with zero boilerplate
• ApContext extractor — Extract apcore Context (identity, trace context) from Axum requests via FromRequestParts
• Module execution — Call any registered module programmatically with call(), stream(), or cancellable_call()
• Async task management — Submit background tasks with status tracking, cancellation, and cleanup
• MCP server — Serve registered modules as MCP tools (stdio, streamable-http, SSE transports)
• OpenAI export — Export modules as OpenAI-compatible tool definitions
• Access control — Enforce caller authorization via an apcore ACL file (APCORE_ACL_PATH)
• YAML bindings — Auto-discover modules from YAML binding files
• CLI — Scan, serve, export, manage tasks, list/describe modules, shell completions, man pages, and module scaffolding
• HTTP proxy CLI — Generate a full CLI where each command forwards requests to the running API via HTTP (create_cli())
• Configuration — APCORE_* environment variables for all settings
• Observability — Tracing middleware, metrics collection, and structured logging via tracing

API Overview

Core

Scanning

Engine

Requirements

• Rust >= 1.75
• Tokio async runtime
• Axum 0.8+

Installation

Add to your Cargo.toml:

[dependencies]
axum-apcore = "0.1"
axum = { version = "0.8", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
tracing-subscriber = "0.3"

Feature flags

axum-apcore = { version = "0.1", features = ["all"] }

Quick Start

Register routes and call modules

use axum::{routing::get, Router, Json};
use axum_apcore::{ap_handler, AxumApcore, ApContext};
use serde_json::{json, Value};
use std::sync::Arc;

// Define a handler
async fn get_user(
    ApContext(ctx): ApContext,
    axum::extract::Path(id): axum::extract::Path<String>,
) -> Json<Value> {
    Json(json!({"id": id, "name": "Alice", "trace_id": ctx.trace_id}))
}

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();

    // Register route metadata
    ap_handler! {
        method: "GET",
        path: "/api/users/:id",
        handler: get_user,
        description: "Get a user by ID",
        tags: ["users"],
        input_schema: json!({"type": "object", "properties": {"id": {"type": "string"}}}),
        output_schema: json!({"type": "object", "properties": {"name": {"type": "string"}}}),
    }

    // Initialize
    let apcore = Arc::new(AxumApcore::new());
    let router = Router::new()
        .route("/api/users/{id}", get(get_user))
        .with_state(apcore.clone());

    apcore.init_app(&router).await.unwrap();

    // List discovered modules
    println!("{:?}", apcore.list_modules());
    // => ["users.get_user.get"]

    // Start the server
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, router).await.unwrap();
}

Register executable handlers

use axum_apcore::{AxumApcore, Context, ModuleError};
use serde_json::{json, Value};
use std::sync::Arc;

async fn get_user_handler(input: Value, _ctx: &Context<Value>) -> Result<Value, ModuleError> {
    let id = input["id"].as_str().unwrap_or("unknown");
    Ok(json!({"id": id, "name": "Alice"}))
}

#[tokio::main]
async fn main() {
    let apcore = AxumApcore::new();

    // Register a callable handler
    apcore.register_handler(
        "axum::get_user",
        Arc::new(|input, ctx| Box::pin(get_user_handler(input, ctx))),
    );

    // After init_app(), call modules programmatically
    let result = apcore
        .call_anonymous("users.get_user.get", json!({"id": "1"}))
        .await
        .unwrap();

    println!("{result}"); // {"id":"1","name":"Alice"}
}

OpenAPI scanning

use axum_apcore::OpenAPIScanner;
use serde_json::json;

let scanner = OpenAPIScanner::new();
let spec = json!({
    "openapi": "3.1.0",
    "info": {"title": "My API", "version": "1.0.0"},
    "paths": {
        "/users/{id}": {
            "get": {
                "operationId": "get_user_get",
                "summary": "Get user",
                "tags": ["users"],
                "responses": {"200": {"description": "OK"}}
            }
        }
    }
});

let modules = scanner.scan_spec(&spec, None, None).unwrap();
println!("{}", modules[0].module_id); // "users.get_user.get"

Cancellable execution with timeout

use std::time::Duration;

let result = apcore
    .cancellable_call("users.get_user.get", json!({"id": "1"}), None, Duration::from_secs(5))
    .await;

Background tasks

// Submit a task
let task_id = apcore.submit_task("users.get_user.get", json!({"id": "1"})).unwrap();

// Check status
let info = apcore.get_task_status(&task_id);

// Get result when complete
let result = apcore.get_task_result(&task_id);

// Cancel a running task
apcore.cancel_task(&task_id);

HTTP proxy CLI

Generate a CLI where each command forwards requests to the running API via HTTP:

use axum_apcore::{AxumApcore, CreateCliConfig};

let apcore = AxumApcore::new();
let config = CreateCliConfig {
    prog_name: "myapp-cli".into(),
    base_url: "http://localhost:3000".into(),
    ..Default::default()
};

let cmd = apcore.create_cli(&router, config).await?;

CLI Reference

The CLI provides both framework-specific commands and apcore-cli commands (requires cli feature):

Framework Commands

scan

axum-apcore scan [OPTIONS]

serve

axum-apcore serve [OPTIONS]

export

axum-apcore export [OPTIONS]

apcore-cli Commands

These commands are delegated to the apcore-cli library:

Examples

# List all modules in table format
axum-apcore list

# List modules filtered by tag, output as JSON
axum-apcore list --tag users --format json

# Describe a specific module
axum-apcore describe users.get_user.get

# Generate bash completions
axum-apcore completion bash

# Generate man page for the program
axum-apcore man

# Scaffold a new module with binding style
axum-apcore init module users.create_user --style binding --description "Create a user"

Configuration

All settings are read from environment variables with the APCORE_ prefix:

Access control (ACL)

Set APCORE_ACL_PATH (or ApcoreSettings::acl_path) to an ACL YAML file to have apcore enforce caller authorization on every call() / stream(). The executor runs apcore's acl_check pipeline step; a denied call returns ErrorCode::ACLDenied, which maps to HTTP 403 Forbidden.

ACL rules match on the caller id, which is apcore's module-level identity — not the request's RequestIdentity/JWT subject:

• a top-level request (your HTTP route invoking a module) is checked as the @external caller;
• a module calling another module is checked under the calling module's id.

# acl/global_acl.yaml
default_effect: allow
rules:
  - callers: ["@external"]          # all top-level (HTTP-originated) calls
    targets: ["admin.delete_user.delete"]
    effect: deny
    description: "External callers cannot reach the admin delete module."

APCORE_ACL_PATH=acl/global_acl.yaml cargo run --example handler_registration

Use ACL for module-level / external-entry authorization. For per-user HTTP authz (roles, ownership), keep using the Axum middleware / JWT layer — that identity is available on ApContext but is independent of the ACL caller id. A malformed or missing ACL file is logged and treated as "no ACL" rather than crashing startup.

Examples

The examples/ directory contains runnable demos. Run any example with:

cargo run --example basic
cargo run --example handler_registration
cargo run --example async_tasks
cargo run --example openapi_scanner --features openapi
cargo run --example mcp_server --features mcp
cargo run --example cli_proxy --features cli

Tests

Run all tests (unit + integration):

cargo test --all-features

Run only unit tests:

cargo test --all-features --lib

Run only integration tests:

cargo test --all-features --test integration_test

Run a specific test by name:

cargo test test_e2e_register_scan_call

Run with output visible:

cargo test -- --nocapture

Development

Prerequisites

Install Rust via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Clone and build

git clone https://github.com/aiperceivable/axum-apcore.git
cd axum-apcore
cargo build --all-features

Quality gates

All of these must pass before committing:

cargo fmt --all -- --check          # Formatting
cargo clippy --all-targets --all-features -- -D warnings  # Lint
cargo build --all-features          # Full build
cargo test --all-features           # Tests (unit + integration)
cargo build --examples              # Example build

Lint and format

cargo fmt           # Auto-format code
cargo clippy        # Lint with suggestions

Build documentation

cargo doc --all-features --open

Architecture

axum-apcore follows the same module structure as fastapi-apcore:

License

Apache-2.0

Links

• Core SDK: aiperceivable/apcore-rust
• Toolkit: aiperceivable/apcore-toolkit-rust
• Reference: aiperceivable/fastapi-apcore
• Website: aiperceivable.com
• Issues: GitHub Issues