Crate blazingly_executor

Expand description

§blazingly-executor

Runtime-neutral operation executor for the Blazingly framework: extraction, validation, dependency resolution, and typed response projection.

This crate makes the operation model of blazingly-core executable. ExecutableOperation pairs an OperationDescriptor with a handler; Plugin scopes group operations with providers (from blazingly-di), lifecycle hooks, and security schemes; ExecutableApp::from_plugin validates and compiles the whole graph once, and invoke runs the full pipeline — hooks, typed extraction, validation (behind the validation feature), the handler, and projection into an ExecutionOutcome — for one operation. The same pipeline serves HTTP requests (routed by blazingly-http) and MCP tool calls. Extract<T> disambiguates a custom extractor from a compiled dependency request, Extract<RequestParts> snapshots the HTTP request line, and Plugin::mount / Plugin::with_id_namespace serve one module at two prefixes under distinct operation identities.

The crate also owns the bounded blocking pool (run_blocking, install_global_blocking_pool), which blazingly-database uses. It is opt-in, not automatic: a synchronous handler runs inline on the calling thread and is never moved to the pool, so work that genuinely blocks has to reach for run_blocking itself.

Standalone use is real: there is no HTTP transport, no macro, and no async runtime here. invoke returns an ordinary future you can drive with any executor, which is how applications are tested in memory. The blazingly facade adds the attribute macros that generate ExecutableOperations from function signatures; without them, the typed, json, and empty constructors build operations by hand, as below.

§Direct use

The example depends on blazingly-core and blazingly-json for the descriptor and invocation value types, and uses futures-lite as the executor; any executor works.

use blazingly_core::{HttpMethod, Json, OperationDescriptor, OperationId, ResponseDescriptor};
use blazingly_executor::{ExecutableApp, ExecutableOperation, ExecutionOutcome, Plugin};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let descriptor = OperationDescriptor::new(
        HttpMethod::Get,
        "/health",
        "health.read",
        "Liveness probe",
        None,
        vec![ResponseDescriptor::success(200, None)],
    )?;

    let app = ExecutableApp::from_plugin(
        Plugin::new("app")
            .operation(ExecutableOperation::empty(descriptor, || async { Json("ok") })),
    )?;

    let id = OperationId::new("health.read")?;
    let outcome = futures_lite::future::block_on(app.invoke(&id, blazingly_json::Value::Null));
    assert!(matches!(outcome, ExecutionOutcome::Success { status: 200, .. }));
    Ok(())
}

§Links

Macros§

routes: Collects annotated handlers into the operation list an application is built from.

Structs§

BlockingFuture: Future resolved by a bounded blocking worker.
BlockingPool: A bounded process-wide pool used only by explicitly synchronous handlers.
BlockingPoolConfig: Capacity and worker count for synchronous blocking handlers.
CancellationToken: Runtime-neutral cooperative cancellation shared by adapters and operation execution.
Cancelled: Future completed when a CancellationToken is cancelled.
ExecutableApp: A validated executable operation graph.
ExecutableOperation: A handler plus the operation descriptor shared by HTTP and MCP.
Extension: Typed request-local value installed by transport middleware.
Extract: Explicitly asks the operation macro to extract T from the invocation.
HookContext: Runtime-neutral metadata passed to compiled plugin hooks.
HookOutcome: A body-free result summary passed to on_response hooks.
InputRejection: A stable client-visible failure produced while extracting an argument.
InvocationControl: Adapter-supplied cancellation and timeout signals for one invocation.
Plugin: A lexical provider scope containing operations and nested plugins.
RequestParts: An owned snapshot of the raw request parts, taken before the handler runs.
RequestProvider: A provider together with the request inputs it declared.
ResolvedDependencies: Slot-based dependency values visible to one operation handler.
TestOverrides: Typed provider replacements applied only while compiling a test app.
UploadBody: Pull-based request body with adapter-enforced transport limits.

Enums§

BlockingError: Failure to schedule or execute a synchronous blocking handler.
DependencyError: A stable request rejection or an internal dependency failure.
ExecutableBuildError: An application-definition or dependency-compilation failure.
ExecutionOutcome: The protocol-neutral result of executing one operation.
HookOutcomeKind: Stable result classes visible to plugin response hooks.
InvocationAbort: Reason a controlled invocation stopped before completion.
InvocationInput: Transport-neutral values supplied to typed operation extractors.

Traits§

FilePayload: Types accepted by the typed File extractor.
FromInvocation: Decodes one typed handler argument from an invocation.
HttpRequestParts: Borrowed HTTP request values used by the compiled executor.
OperationOutput: A typed handler result that can become a shared operation outcome.

Functions§

blocking_error_outcome
install_global_blocking_pool: Installs the process-wide blocking pool before the first sync invocation.
on_blocking_worker: Reports whether the calling thread is a blocking-pool worker.
run_blocking: Schedules owned synchronous work without blocking an async worker.

Type Aliases§

OperationFuture