Quick Start

Minimal Configuration

Create a gateway.hcl file with an entrypoint, a router, and a service:

entrypoints "web" {
  address = "0.0.0.0:80"
}

routers "my-api" {
  rule        = "PathPrefix(`/api`)"
  service     = "api-backend"
  entrypoints = ["web"]
}

services "api-backend" {
  load_balancer {
    strategy = "round-robin"
    servers  = [{ url = "http://127.0.0.1:8001" }]
  }
}

Start the Gateway

# Start with HCL config
a3s-gateway --config gateway.hcl

# Start with debug logging
a3s-gateway --config gateway.hcl --log-level debug

# Validate configuration without starting
a3s-gateway validate --config gateway.hcl

Add HTTPS

entrypoints "web" {
  address = "0.0.0.0:80"
}

entrypoints "websecure" {
  address = "0.0.0.0:443"

  tls {
    cert_file = "/etc/certs/cert.pem"
    key_file  = "/etc/certs/key.pem"
  }
}

routers "my-api" {
  rule        = "Host(`api.example.com`) && PathPrefix(`/v1`)"
  service     = "api-backend"
  entrypoints = ["websecure"]
}

services "api-backend" {
  load_balancer {
    strategy = "round-robin"
    servers  = [{ url = "http://127.0.0.1:8001" }]
  }
}

Add Middleware

entrypoints "websecure" {
  address = "0.0.0.0:443"

  tls {
    cert_file = "/etc/certs/cert.pem"
    key_file  = "/etc/certs/key.pem"
  }
}

routers "my-api" {
  rule        = "Host(`api.example.com`)"
  service     = "api-backend"
  entrypoints = ["websecure"]
  middlewares  = ["auth", "rate-limit"]
}

middlewares "auth" {
  type  = "jwt"
  value = "my-jwt-secret"
}

middlewares "rate-limit" {
  type  = "rate-limit"
  rate  = 100
  burst = 50
}

services "api-backend" {
  load_balancer {
    strategy = "round-robin"
    servers = [
      { url = "http://127.0.0.1:8001" },
      { url = "http://127.0.0.1:8002" },
    ]
  }
}

Health Check

services "api-backend" {
  load_balancer {
    strategy = "least-connections"

    servers = [
      { url = "http://127.0.0.1:8001" },
      { url = "http://127.0.0.1:8002" },
    ]

    health_check {
      path                = "/health"
      interval            = "10s"
      timeout             = "5s"
      unhealthy_threshold = 3
      healthy_threshold   = 1
    }
  }
}

Dashboard API

The gateway exposes a built-in dashboard API for health, metrics, and live configuration:

# Health status
curl http://localhost:80/api/gateway/health

# Prometheus metrics
curl http://localhost:80/api/gateway/metrics

# Current configuration
curl http://localhost:80/api/gateway/config

# Active routes
curl http://localhost:80/api/gateway/routes

# Registered services
curl http://localhost:80/api/gateway/services

Programmatic Usage

use a3s_gateway::{Gateway, config::GatewayConfig};

#[tokio::main]
async fn main() -> a3s_gateway::Result<()> {
    let config = GatewayConfig::from_file("gateway.hcl").await?;
    let gateway = Gateway::new(config)?;

    gateway.start().await?;

    // Check health
    let health = gateway.health();
    println!("State: {:?}, Uptime: {}s", health.state, health.uptime_secs);

    // Wait for shutdown signal
    gateway.wait_for_shutdown().await;
    Ok(())
}

Quick Start

On this page