Struct Runtime 

pub struct Runtime { /* private fields */ }

The ironflow runtime server builder.

Runtime uses a builder pattern: create one with Runtime::new, register webhook routes with Runtime::webhook and cron jobs with Runtime::cron, then call Runtime::serve to start both the HTTP server and the cron scheduler, or Runtime::run_crons to run only the cron scheduler without an HTTP listener.

Built-in endpoints

Method	Path	Description
GET	/health	Returns 200 OK with body "ok". Useful for load-balancer health checks.
POST	user-defined	Webhook endpoints registered via Runtime::webhook.

Examples

use ironflow_runtime::prelude::*;

#[tokio::main]
async fn main() -> Result<(), ironflow_runtime::error::RuntimeError> {
    Runtime::new()
        .webhook("/hooks/deploy", WebhookAuth::github("secret"), |payload| async move {
            println!("deploy triggered: {payload}");
        })
        .cron("0 0 * * * *", "hourly-sync", || async {
            println!("syncing...");
        })
        .serve("0.0.0.0:3000")
        .await?;

    Ok(())
}

Implementations

impl Runtime

pub fn new() -> Self

Creates a new, empty Runtime with no webhooks or cron jobs.

Examples

use ironflow_runtime::runtime::Runtime;

let runtime = Runtime::new();

pub fn max_body_size(self, bytes: usize) -> Self

Set the maximum allowed body size for webhook payloads.

Requests exceeding this limit are rejected by axum before reaching the handler. Defaults to 2 MiB.

Examples

use ironflow_runtime::runtime::Runtime;

let runtime = Runtime::new().max_body_size(512 * 1024); // 512 KiB

pub fn max_concurrent_handlers(self, limit: usize) -> Self

Set the maximum number of concurrently running webhook handlers.

When the limit is reached, new webhook requests still receive 202 Accepted but their handlers are queued until a slot is available. Defaults to 64.

Panics

Panics if limit is 0.

Examples

use ironflow_runtime::runtime::Runtime;

let runtime = Runtime::new().max_concurrent_handlers(16);

pub fn with_shutdown<F>(self, signal: F) -> Self

where F: Future<Output = ()> + Send + 'static,

Override the default shutdown signal (Ctrl+C / SIGTERM).

By default, Runtime::serve and Runtime::run_crons block until the process receives Ctrl+C or SIGTERM. Use this method to provide a custom future that resolves when the runtime should shut down.

This is useful in tests where you want to trigger a clean shutdown (including scheduler.shutdown()) without relying on OS signals.

Examples

use ironflow_runtime::runtime::Runtime;
use tokio::sync::oneshot;

let (tx, rx) = oneshot::channel::<()>();

let rt = Runtime::new()
    .with_shutdown(async { let _ = rx.await; })
    .cron("0 */5 * * * *", "check", || async {});

// In another task: tx.send(()) to trigger shutdown.
rt.run_crons().await?;

pub fn webhook<F, Fut>(self, path: &str, auth: WebhookAuth, handler: F) -> Self

where F: Fn(Value) -> Fut + Send + Sync + Clone + 'static, Fut: Future<Output = ()> + Send + 'static,

Registers a webhook route.

The handler receives the parsed JSON body as a serde_json::Value. When a request arrives, the server verifies authentication using auth, then spawns the handler in the background and immediately returns 202 Accepted to the caller.

Arguments

• path - The URL path to listen on (e.g. "/hooks/github").
• auth - The WebhookAuth strategy for this endpoint.
• handler - An async function receiving the JSON payload.

Examples

use ironflow_runtime::prelude::*;

let runtime = Runtime::new()
    .webhook("/hooks/github", WebhookAuth::github("secret"), |payload| async move {
        println!("payload: {payload}");
    });

pub fn cron<F, Fut>(self, schedule: &str, name: &str, handler: F) -> Self

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Registers a cron job.

The schedule uses a 6-field cron expression (seconds granularity): sec min hour day-of-month month day-of-week.

Arguments

• schedule - A 6-field cron expression, e.g. "0 */5 * * * *" for every 5 minutes.
• name - A human-readable name for logging.
• handler - An async function to execute on each tick.

Examples

use ironflow_runtime::prelude::*;

let runtime = Runtime::new()
    .cron("0 0 * * * *", "hourly-cleanup", || async {
        println!("cleaning up...");
    });

pub fn into_router(self) -> Router

Consumes the runtime and returns only the axum Router.

Cron jobs are not started. This is useful for testing the HTTP layer in isolation without side-effects (e.g. with tower::ServiceExt::oneshot).

Examples

use ironflow_runtime::prelude::*;

let router = Runtime::new()
    .webhook("/hooks/test", WebhookAuth::none(), |_payload| async {})
    .into_router();

pub async fn run_crons(self) -> Result<(), RuntimeError>

Starts only the cron scheduler, blocking until a shutdown signal is received (Ctrl+C / SIGTERM).

Unlike Runtime::serve, this does not start an HTTP server. Any registered webhooks are ignored (a warning is logged if webhooks were registered).

Errors

Returns an error if:

• The cron scheduler fails to initialise or a cron expression is invalid.
• The scheduler fails to shut down cleanly.

Examples

use ironflow_runtime::prelude::*;

#[tokio::main]
async fn main() -> Result<(), ironflow_runtime::error::RuntimeError> {
    Runtime::new()
        .cron("0 0 * * * *", "hourly-sync", || async {
            println!("syncing...");
        })
        .run_crons()
        .await?;
    Ok(())
}

pub async fn serve(self, addr: &str) -> Result<(), RuntimeError>

Starts the HTTP server and cron scheduler, blocking until shutdown.

This method:

1. Loads environment variables from .env via dotenvy.
2. Starts the tokio_cron_scheduler scheduler with all registered cron jobs.
3. Builds an Axum router with all registered webhook routes plus a GET /health endpoint.
4. Binds to addr and serves until a Ctrl+C signal is received.
5. Gracefully shuts down the scheduler before returning.

If you only need cron jobs without an HTTP server, use Runtime::run_crons instead.

Errors

Returns an error if:

• The cron scheduler fails to initialise or a cron expression is invalid.
• The TCP listener cannot bind to addr.
• The Axum server encounters a fatal I/O error.

Examples

use ironflow_runtime::prelude::*;

#[tokio::main]
async fn main() -> Result<(), ironflow_runtime::error::RuntimeError> {
    Runtime::new()
        .serve("127.0.0.1:3000")
        .await?;
    Ok(())
}

Trait Implementations

impl Default for Runtime

fn default() -> Self

Returns the “default value” for a type.