Struct Refractium 

pub struct Refractium { /* private fields */ }

The main engine for the Refractium proxy.

Refractium manages the lifecycle of TCP and UDP servers, protocol identification, and backend health monitoring. It is designed to be highly concurrent and supports atomic routing table updates via reload_routes.

Examples

use refractium::{Refractium, Http, types::{ProtocolRoute, ForwardTarget}};
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let routes = vec![ProtocolRoute {
        protocol: Arc::new(Http),
        sni: None,
        forward_to: ForwardTarget::Single("127.0.0.1:8080".to_string()),
    }];

    let refractium = Refractium::builder()
        .routes(routes, Vec::new())
        .build()?;

    refractium.run_tcp("0.0.0.0:80".parse()?).await?;
    Ok(())
}

Implementations

impl Refractium

pub const fn builder() -> RefractiumBuilder

Returns a new RefractiumBuilder with default settings.

pub async fn reload_routes( &self, tcp: Vec<ProtocolRoute>, udp: Vec<ProtocolRoute>, )

Atomically reloads the routing table for all active servers.

This method updates the internal load balancers and starts monitoring any new backend addresses. Active connections are not dropped during the reload.

pub fn cancel_token(&self) -> CancellationToken

Returns the CancellationToken used by the engine.

This can be used to trigger a graceful shutdown from external logic.

pub async fn run_tcp(&self, addr: SocketAddr) -> Result<()>

Starts the TCP server on the provided address.

This method will block until the server is shut down or an unrecoverable error occurs.

Errors

Returns a crate::errors::RefractiumError::BindError if the address is already in use or other IO errors occur during startup.

pub async fn run_udp(&self, addr: SocketAddr) -> Result<()>

Starts the UDP server on the provided address.

Errors

Returns a crate::errors::RefractiumError::BindError if the address is already in use.

pub async fn run_both(&self, addr: SocketAddr) -> Result<()>

Starts both TCP and UDP servers concurrently.

Errors

Returns an error if either the TCP or UDP server fails to bind.

pub async fn report_health(&self)

Prints a visual health report of all configured backends to stdout.

This is mainly used for debugging or CLI reporting.