request.intercept

Inspect inbound HTTP requests before handlers run.

When

On every matching request, outermost request hook layer.

Input

Method code, path, headers JSON (lowercase keys), body bytes.

Output

REQUEST_CONTINUE or short-circuit via write_request_response.

Route matching

Prefix match: `/api/*`, `/plugins/hello`, `*` for all routes.

First hook layer on inbound requests. Use for auth gates, rate limits, and early JSON error responses. authorization header value is redacted in headers JSON.

Pipeline

Runs before middleware.inject and before Axum handlers.

Use cases

API key or custom header validation
Block requests before they hit core handlers
Audit log method + path for matching routes

Example

Registration and handler

Register

hook_request!(host, RequestHookPhase::Intercept, "/api/*", on_intercept);

Handler

extern "C" fn on_intercept(ctx: *const RequestHookContext) -> i32 {
    let ctx = unsafe { &*ctx };
    let headers = unsafe { std::slice::from_raw_parts(ctx.headers_json_ptr, ctx.headers_json_len) };
    let Ok(value) = serde_json::from_slice::<serde_json::Value>(headers) else {
        return REQUEST_CONTINUE;
    };
    if value.get("x-api-key").is_some() {
        return REQUEST_CONTINUE;
    }
    write_request_response(ctx, 401, br#"{"error":"unauthorized"}"#)
}

← Back to index