Struct RequestContext 

pub struct RequestContext { /* private fields */ }

Request context that wraps asupersync’s capability context.

RequestContext provides access to:

• Request-scoped identity (request ID, trace context)
• Cancellation checkpoints for cancel-safe handlers
• Budget/deadline awareness for timeout enforcement
• Region-scoped spawning for background work
• Body size limit configuration for DoS prevention

Example

async fn handler(ctx: &RequestContext) -> impl IntoResponse {
    // Check for client disconnect
    ctx.checkpoint()?;

    // Get remaining time budget
    let remaining = ctx.remaining_budget();

    // Check body size limit
    let max_body = ctx.body_limit().max_size();

    // Do work...
    "Hello, World!"
}

Implementations

impl RequestContext

pub fn new(cx: Cx, request_id: u64) -> Self

Creates a new request context from an asupersync Cx.

This is typically called by the server when accepting a new request, creating a new region for the request lifecycle. Uses the default body size limit (1MB).

pub fn with_body_limit(cx: Cx, request_id: u64, max_body_size: usize) -> Self

Creates a new request context with a custom body size limit.

Use this when the application has configured a specific max_body_size in AppConfig, or when a route has an override.

pub fn with_overrides( cx: Cx, request_id: u64, overrides: Arc<DependencyOverrides>, ) -> Self

Creates a new request context with shared dependency overrides.

pub fn with_overrides_and_body_limit( cx: Cx, request_id: u64, overrides: Arc<DependencyOverrides>, max_body_size: usize, ) -> Self

Creates a new request context with overrides and a custom body size limit.

pub fn request_id(&self) -> u64

Returns the unique request identifier.

Useful for logging and tracing across the request lifecycle.

pub fn dependency_cache(&self) -> &DependencyCache

Returns the dependency cache for this request.

pub fn dependency_overrides(&self) -> &DependencyOverrides

Returns the dependency overrides registry.

pub fn resolution_stack(&self) -> &ResolutionStack

Returns the resolution stack for cycle detection.

pub fn cleanup_stack(&self) -> &CleanupStack

Returns the cleanup stack for registering cleanup functions.

Cleanup functions run after the handler completes in LIFO order.

pub fn body_limit(&self) -> &BodyLimitConfig

Returns the body limit configuration for this request.

This can be used by body extractors (e.g., Json<T>) to enforce size limits and prevent DoS attacks.

pub fn max_body_size(&self) -> usize

Returns the maximum body size in bytes for this request.

This is a convenience method equivalent to ctx.body_limit().max_size().

pub fn region_id(&self) -> RegionId

Returns the underlying region ID from asupersync.

The region represents the request’s lifecycle scope - all spawned tasks belong to this region and will be cleaned up when the request completes or is cancelled.

pub fn task_id(&self) -> TaskId

Returns the current task ID.

pub fn budget(&self) -> Budget

Returns the current budget.

The budget represents the remaining computational resources (time, polls) available for this request. When exhausted, the request should be cancelled gracefully.

pub fn is_cancelled(&self) -> bool

Checks if cancellation has been requested.

This includes client disconnection, timeout, or explicit cancellation. Handlers should check this periodically and exit early if true.

pub fn checkpoint(&self) -> Result<(), CancelledError>

Cooperative cancellation checkpoint.

Call this at natural suspension points in your handler to allow graceful cancellation. Returns Err if cancellation is pending.

Errors

Returns an error if the request has been cancelled and cancellation is not currently masked.

Example

async fn process_items(ctx: &RequestContext, items: Vec<Item>) -> Result<(), HttpError> {
    for item in items {
        ctx.checkpoint()?;  // Allow cancellation between items
        process_item(item).await?;
    }
    Ok(())
}

pub fn masked<F, R>(&self, f: F) -> R

where F: FnOnce() -> R,

Executes a closure with cancellation masked.

While masked, checkpoint() will not return an error even if cancellation is pending. Use this for critical sections that must complete atomically.

Example

// Commit transaction - must not be interrupted
ctx.masked(|| {
    db.commit().await?;
    Ok(())
})

pub fn trace(&self, message: &str)

Records a trace event for this request.

Events are associated with the request’s trace context and can be used for debugging and observability.

pub fn cx(&self) -> &Cx

Returns a reference to the underlying asupersync Cx.

Use this when you need direct access to asupersync primitives, such as spawning tasks or using combinators.

Trait Implementations

impl Clone for RequestContext

fn clone(&self) -> RequestContext

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RequestContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromRequest for RequestContext

type Error = Infallible

Error type when extraction fails.

async fn from_request( ctx: &RequestContext, _req: &mut Request, ) -> Result<Self, Self::Error>

Extract a value from the request.