Refractium

Extensible low-level reverse proxy for port multiplexing and protocol-based routing.

refractium is a high-performance multiplexer that identifies incoming traffic by protocol signature and routes it to the correct backend. It allows Web, SSH, and custom binary services to coexist on the same external port with near-native throughput.

Features

• Expose one single port for multiple services

  • You can run an HTTP server and an SSH daemon on port 80 simultaneously.
  • Automatically detects protocols by inspecting the initial bytes of the stream.

• Load Balancing & Health Checks

  • Distributes traffic across multiple backend instances (Round Robin).
  • Active monitoring: automatically skips dead backends to ensure zero-downtime routing.

• TCP & UDP Support

  • Handles both stream-based (TCP) and packet-based (UDP) traffic within the same engine.
  • Optimized for low-latency infrastructure and high-throughput applications.

• Extensible

  • You can define new protocols in the refractium.toml file. Or use Refractium as a library and define new built-in protocols.

• Hot Reload

  • Update your routing table without dropping active connections or restarting the server.

• Graceful Shutdown

  • Built-in support for cancellation tokens to ensure clean termination.

How it works

refractium operates at the edge of the transport layer. Unlike Layer 7 proxies (Nginx, HAProxy) that often parse the entire request, refractium:

1. Peeks: It briefly inspects the very first bytes of a connection without consuming them.
2. Identifies: Matches the signature against its protocol registry in nanoseconds.
3. Welds: Once the destination is known, it "welds" the incoming stream directly to the backend.

By using zero-copy techniques, data flows through the proxy with near-native throughput, as if the client were directly connected to the target service.

Why Refractium?

Because managing multiple open ports on a firewall is tedious and restricts your architectural flexibility.

refractium lets you:

• Bypass Firewall Restrictions: Expose services that would normally be blocked by using standard ports (80, 443).
• Consolidate IP Resources: Multiplex diverse protocols on a single public IP address.
• Scale Transparently: Your backends receive traffic as if they were directly connected; they don't need to be "Refractium-aware."

Installation

Direct Download

Grab the pre-built binary for your operating system from the Latest Releases.

From Source (Cargo)

cargo install refractium

Cargo Features:

• default/full (contains: cli, logging, protocols, watch features)
• protocols (contains: proto-http, proto-https, proto-ssh, proto-dns, proto-ftp features)
• cli: Includes the command line interface modules.
• logging: Includes tracing and tracing-subscriber libraries
• watch: Includes hot-reload functions.

Command Reference

Global Options:

• -b, --bind: Address to bind to (Default: 0.0.0.0).
• -p, --port: Port to listen on (Default: 8080).
• -c, --config: Path to configuration file (Default: refractium.toml).
• -f, --forward: Inline routing rules (e.g., ssh=127.0.0.1:22).
• --debug: Enable verbose logging.

Usage Examples

Zero-Config (CLI only)

You don't need a refractium.toml file to start using Refractium. Use the -f flag to define routes on the fly:

# Route HTTP and SSH on port 80
refractium -p 80 -f "http=127.0.0.1:8080" -f "ssh=127.0.0.1:22"

# Load balance HTTP across multiple backends
refractium -f "http=10.0.0.1:80" -f "http=10.0.0.2:80"

Using a Configuration File

Create a refractium.toml to define more complex routing, including custom byte patterns and transport settings.

1. Initialize the config:

refractium init

2. Edit refractium.toml:

[server]
bind = "0.0.0.0"
port = 8080

[[protocols]]
name = "http"
forward_to = "127.0.0.1:3000"

[[protocols]]
name = "ssh"
forward_to = "127.0.0.1:22"

[[protocols]]
name = "dns"
forward_to = "1.1.1.1:53"

# Custom protocol via magic bytes
[[protocols]]
name = "my_app"
patterns = ["\x01\x02\x03", "MY_PROTO_V1"]
forward_to = "127.0.0.1:9000"
transport = "udp"

3. Run with the config:

refractium
# Or if you want to define the route to the config file:
refractium --config refractium.toml

Built-in Protocols

Performance

Refractium is designed for extreme speed. Protocol identification happens in nanoseconds, adding negligible overhead to your connections.

Identification Benchmarks:

• HTTP: ~16 ns
• HTTPS (SNI): ~47 ns
• SSH: ~24 ns
• DNS (UDP): ~25 ns
• Mixed Traffic: ~56 ns

Environment: Intel Core i7-7700 @ 3.60GHz. Run cargo bench to verify on your own hardware.

Library Usage (Extensibility)

Refractium is also a modular engine. You can define complex identification logic in Rust by implementing the RefractiumProtocol trait or using the provided macro:

use refractium::{define_protocol, Refractium, Transport, ProtocolRegistry};
use std::sync::Arc;

// Define a new protocol outside the project
define_protocol!(
    name: MyProto,
    transport: Transport::Tcp,
    identify: |data| data.starts_with(b"MY_SECRET_MAGIC")
);

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut registry = ProtocolRegistry::new();
    registry.register(Box::new(MyProto));

    let refractium = Refractium::builder()
        .registries(Arc::new(registry), Arc::new(ProtocolRegistry::new()))
        .build();

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

Reliability

• Memory Safety: Built 100% in Rust with zero unsafe blocks.
• Panic-Free: Rigorous use of clippy denials to ensure the proxy never crashes in production.
• Resource Protection: Configurable peek buffers and timeouts to mitigate slow-loris style attacks.