clean up repo

2025-12-18 18:52:28 -05:00
parent 54978770be
commit 7eae7db1f6
13 changed files with 329 additions and 46 deletions
--- a/.idea/.gitignore
+++ b/.idea/.gitignore
@@ -1,8 +0,0 @@
-# Default ignored files
-/shelf/
-/workspace.xml
-# Editor-based HTTP Client requests
-/httpRequests/
-# Datasource local storage ignored files
-/dataSources/
-/dataSources.local.xml
--- a/.idea/enginewhy.iml
+++ b/.idea/enginewhy.iml
@@ -2,6 +2,7 @@
 <module type="EMPTY_MODULE" version="4">
  <component name="NewModuleRootManager">
    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/examples" isTestSource="false" />
      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
      <excludeFolder url="file://$MODULE_DIR$/target" />
    </content>
--- a/.idea/misc.xml
+++ b/.idea/misc.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="DiscordProjectSettings">
+    <option name="show" value="ASK" />
+    <option name="description" value="" />
+  </component>
+</project>
--- a/.idea/modules.xml
+++ b/.idea/modules.xml
@@ -2,7 +2,7 @@
 <project version="4">
  <component name="ProjectModuleManager">
    <modules>
-      <module fileurl="file://$PROJECT_DIR$/.idea/l4lb.iml" filepath="$PROJECT_DIR$/.idea/l4lb.iml" />
+      <module fileurl="file://$PROJECT_DIR$/.idea/enginewhy.iml" filepath="$PROJECT_DIR$/.idea/enginewhy.iml" />
    </modules>
  </component>
 </project>
--- a/.idea/workspace.xml
+++ b/.idea/workspace.xml
@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="ALL" />
+  </component>
+  <component name="CargoProjects">
+    <cargoProject FILE="$PROJECT_DIR$/Cargo.toml">
+      <package file="$PROJECT_DIR$">
+        <feature name="default" enabled="true" />
+      </package>
+    </cargoProject>
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="5bc80de0-5ea4-4d85-9c70-3d4dd48ecd6e" name="Changes" comment="">
+      <change beforePath="$PROJECT_DIR$/.idea/.gitignore" beforeDir="false" />
+      <change beforePath="$PROJECT_DIR$/.idea/l4lb.iml" beforeDir="false" />
+      <change beforePath="$PROJECT_DIR$/.idea/modules.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/modules.xml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/config.yaml" beforeDir="false" afterPath="$PROJECT_DIR$/config.yaml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/report.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/backend/health.rs" beforeDir="false" afterPath="$PROJECT_DIR$/src/backend/health.rs" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/balancer/adaptive_weight.rs" beforeDir="false" afterPath="$PROJECT_DIR$/src/balancer/adaptive_weight.rs" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/balancer/round_robin.rs" beforeDir="false" afterPath="$PROJECT_DIR$/src/balancer/round_robin.rs" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/config/loader.rs" beforeDir="false" afterPath="$PROJECT_DIR$/src/config/loader.rs" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/main.rs" beforeDir="false" afterPath="$PROJECT_DIR$/src/main.rs" afterDir="false" />
+    </list>
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="ExecutionTargetManager" SELECTED_TARGET="RsBuildProfile:dev" />
+  <component name="Git.Settings">
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+  </component>
+  <component name="MacroExpansionManager">
+    <option name="directoryName" value="mBGI6hzN" />
+  </component>
+  <component name="ProjectColorInfo"><![CDATA[{
+  "customColor": "",
+  "associatedIndex": 2
+}]]></component>
+  <component name="ProjectId" id="372Va98jrjZ8PHjIMvsLlQC60VZ" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "Cargo.clippy.executor": "Run",
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.git.unshallow": "true",
+    "RunOnceActivity.rust.reset.selective.auto.import": "true",
+    "com.intellij.ml.llm.matterhorn.ej.ui.settings.DefaultModelSelectionForGA.v1": "true",
+    "git-widget-placeholder": "main",
+    "junie.onboarding.icon.badge.shown": "true",
+    "node.js.detected.package.eslint": "true",
+    "node.js.detected.package.tslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "node.js.selected.package.tslint": "(autodetect)",
+    "nodejs_package_manager_path": "npm",
+    "org.rust.cargo.project.model.PROJECT_DISCOVERY": "true",
+    "org.rust.first.attach.projects": "true",
+    "settings.editor.selected.configurable": "language.rust.build.tool.cargo",
+    "to.speed.mode.migration.done": "true",
+    "vue.rearranger.settings.migration": "true"
+  }
+}]]></component>
+  <component name="RunAnythingCache">
+    <option name="myCommands">
+      <command value="cargo clippy" />
+    </option>
+  </component>
+  <component name="RunManager" selected="Cargo.clippy">
+    <configuration name="Run l4lb" type="CargoCommandRunConfiguration" factoryName="Cargo Command">
+      <option name="buildProfileId" value="dev" />
+      <option name="command" value="run --package l4lb --bin l4lb" />
+      <option name="workingDirectory" value="file://$PROJECT_DIR$" />
+      <envs />
+      <option name="emulateTerminal" value="true" />
+      <option name="channel" value="DEFAULT" />
+      <option name="requiredFeatures" value="true" />
+      <option name="allFeatures" value="false" />
+      <option name="withSudo" value="false" />
+      <option name="buildTarget" value="REMOTE" />
+      <option name="backtrace" value="SHORT" />
+      <option name="isRedirectInput" value="false" />
+      <option name="redirectInputPath" value="" />
+      <method v="2">
+        <option name="CARGO.BUILD_TASK_PROVIDER" enabled="true" />
+      </method>
+    </configuration>
+    <configuration name="Test l4lb" type="CargoCommandRunConfiguration" factoryName="Cargo Command">
+      <option name="command" value="test --workspace" />
+      <option name="workingDirectory" value="file://$PROJECT_DIR$" />
+      <envs />
+      <option name="emulateTerminal" value="true" />
+      <option name="channel" value="DEFAULT" />
+      <option name="requiredFeatures" value="true" />
+      <option name="allFeatures" value="false" />
+      <option name="withSudo" value="false" />
+      <option name="buildTarget" value="REMOTE" />
+      <option name="backtrace" value="SHORT" />
+      <option name="isRedirectInput" value="false" />
+      <option name="redirectInputPath" value="" />
+      <method v="2">
+        <option name="CARGO.BUILD_TASK_PROVIDER" enabled="true" />
+      </method>
+    </configuration>
+    <configuration name="clippy" type="CargoCommandRunConfiguration" factoryName="Cargo Command" temporary="true">
+      <option name="command" value="clippy" />
+      <option name="workingDirectory" value="file://$PROJECT_DIR$" />
+      <envs />
+      <option name="emulateTerminal" value="true" />
+      <option name="channel" value="DEFAULT" />
+      <option name="requiredFeatures" value="true" />
+      <option name="allFeatures" value="false" />
+      <option name="withSudo" value="false" />
+      <option name="buildTarget" value="REMOTE" />
+      <option name="backtrace" value="SHORT" />
+      <option name="isRedirectInput" value="false" />
+      <option name="redirectInputPath" value="" />
+      <method v="2">
+        <option name="CARGO.BUILD_TASK_PROVIDER" enabled="true" />
+      </method>
+    </configuration>
+    <recent_temporary>
+      <list>
+        <item itemvalue="Cargo.clippy" />
+        <item itemvalue="Cargo.clippy" />
+      </list>
+    </recent_temporary>
+  </component>
+  <component name="RustProjectSettings">
+    <option name="toolchainHomeDirectory" value="$USER_HOME$/.cargo/bin" />
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="5bc80de0-5ea4-4d85-9c70-3d4dd48ecd6e" name="Changes" comment="" />
+      <created>1766101214189</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1766101214189</updated>
+      <workItem from="1766101215227" duration="703000" />
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>
--- a/README.md
+++ b/README.md
@@ -0,0 +1,122 @@
+# nginy
+
+EngineWhy, also known as nginy, is a simple but flexible TCP load balancer.
+
+## Contents
+- [Features](#features)
+- [Getting started](#getting-started)
+  - [Running as a standalone binary](#running-as-a-standalone-binary)
+  - [Running as a dockerized application](#running-as-a-dockerized-application)
+- [Configuration](#configuration)
+- [Examples](#examples)
+
+## Features
+
+- Multiple different load balancing algorithms
+  - Round Robin
+  - IP Hashing
+  - Adaptive algorithm (based on [this paper](https://www.wcse.org/WCSE_2018/W110.pdf))
+- Cluster based backend grouping, and CIDR based client matching for fine-grained control.
+- YAML based config for readability and simplicity.
+- Automatic hot-reload of configuration without interruptions to service.
+
+## Getting started
+
+### Running as a standalone binary
+You must have the latest stable Rust release (1.91 at the time of writing), and a valid configuration file (see [Configuration](#configuration) for details).
+
+1. Clone the repository:
+```sh
+git clone https://github.com/psun256/enginewhy.git
+cd enginewhy
+```
+2. Build the application:
+```sh
+cargo build --release
+```
+3. Run the application:
+```sh
+./target/release/l4lb -c path/to/config.yaml
+```
+
+### Running as a dockerized application
+You may also consider running the load balancer as a dockerized application.
+
+1. Clone the repository:
+```sh
+git clone https://github.com/psun256/enginewhy.git
+cd enginewhy
+```
+2. Build the application:
+```sh
+docker build -t enginewhy .
+```
+3. Run the application:
+```sh
+docker run -v "path/to/config.yaml:/enginewhy/config.yaml" enginewhy
+```
+
+## Configuration
+Configuration file is written in YAML.
+By default, the program will look for a file named `config.yaml` in the working directory.
+You can change this by specifying the path with `-c` or `--config` when running the program.
+
+The file consists of:
+- Defining the health response and iperf port (IP + port).
+- A set of backends (IP + Port for each).
+- A set of clusters, which act as group aliases for a set of backends.
+- A list of rules, which consist of:
+  - Clients: One or more CIDR + port number, used to match incoming client connection
+  - Targets: One or more clusters / backend names.
+  - Strategy: A load balancing algorithm to use.
+    - Some algorithms have additional configuration, like the Adaptive algorithm.
+
+Sample configuration:
+```yml
+healthcheck_addr: "10.0.1.10:9000"
+
+iperf_addr: "10.0.1.10:5201"
+
+backends:
+  - id: "srv-1"
+    ip: "10.0.1.11:8081"
+  - id: "srv-2"
+    ip: "10.0.1.12:8082"
+  - id: "srv-3"
+    ip: "10.0.1.13:8083"
+  - id: "srv-4"
+    ip: "10.0.1.14:8084"
+
+clusters:
+  main-api:
+    - "srv-1"
+    - "srv-2"
+  priority-api:
+    - "srv-3"
+    - "srv-4"
+
+rules:
+  - clients:
+      - "0.0.0.0/0:8080"
+    targets:
+      - "main-api"
+    strategy:
+      type: "RoundRobin"
+
+  - clients:
+      - "10.0.0.0/24:8080"
+      - "10.0.0.0/24:25565"
+    targets:
+      - "main-api"
+      - "priority-api"
+    strategy:
+      type: "RoundRobin"
+```
+
+An incoming client will be matched with whatever rule has the longest matching prefix on the correct port.
+
+## Examples
+
+You can find some examples in the `examples` directory of the project.
+
+To run these, just run `docker compose up`.
--- a/config.yaml
+++ b/config.yaml
@@ -1,27 +1,38 @@
-healthcheck_addr: "0.0.0.0:8080"
+healthcheck_addr: "10.0.1.10:9000"

-iperf_addr: "0.0.0.0:5001"
+iperf_addr: "10.0.1.10:5201"

 backends:
  - id: "srv-1"
-    ip: "192.67.67.2:8080"
+    ip: "10.0.1.11:8081"
  - id: "srv-2"
-    ip: "192.67.67.3:8080"
+    ip: "10.0.1.12:8082"
+  - id: "srv-3"
+    ip: "10.0.1.13:8083"
+  - id: "srv-4"
+    ip: "10.0.1.14:8084"

 clusters:
  main-api:
    - "srv-1"
    - "srv-2"
  priority-api:
-    - "srv-1"
+    - "srv-3"
+    - "srv-4"

 rules:
  - clients:
-      - "172.67.67.2/24:80"
+      - "0.0.0.0/0:8080"
+    targets:
+      - "main-api"
+    strategy:
+      type: "RoundRobin"
+
+  - clients:
+      - "10.0.0.0/24:8080"
+      - "10.0.0.0/24:25565"
    targets:
      - "main-api"
      - "priority-api"
    strategy:
-      type: "Adaptive"
-      coefficients: [ 1.5, 1.0, 0.5, 0.1 ]
-      alpha: 0.75
+      type: "RoundRobin"
--- a/report.md
+++ b/report.md
--- a/src/backend/health.rs
+++ b/src/backend/health.rs
@@ -1,10 +1,10 @@
+use rperf3::{Config, Server};
+use serde_json::Value;
 use std::collections::HashMap;
 use std::net::{IpAddr, SocketAddr};
 use std::sync::{Arc, RwLock};
-use serde_json::Value;
-use rperf3::{Config, Server};
-use tokio::net::{TcpListener, TcpSocket, TcpStream};
 use tokio::io::AsyncBufReadExt;
+use tokio::net::{TcpSocket, TcpStream};

 // Physical server health statistics, used for certain load balancing algorithms
 #[derive(Debug, Default)]
@@ -47,14 +47,14 @@ pub async fn start_healthcheck_listener(

    let listener = listener.ok_or_else(|| {
        eprintln!("health listener could not bind to port");
-        std::io::Error::new(std::io::ErrorKind::Other, "health listener failed")
+        std::io::Error::other("health listener failed")
    })?;

    println!("healthcheck server listening on {}", addr);
    loop {
-        let (stream, remote_addr) = match listener.accept().await {
+        let (stream, _remote_addr) = match listener.accept().await {
            Ok(v) => v,
-            Err(e) => {
+            Err(_e) => {
                continue;
            }
        };
--- a/src/balancer/adaptive_weight.rs
+++ b/src/balancer/adaptive_weight.rs
@@ -1,11 +1,10 @@
-use crate::backend::{Backend, BackendPool};
 use crate::backend::health::ServerMetrics;
+use crate::backend::{Backend, BackendPool};
 use crate::balancer::{Balancer, ConnectionInfo};
 use rand::prelude::*;
 use rand::rngs::SmallRng;
 use std::fmt::Debug;
-use std::fs::Metadata;
-use std::sync::{Arc, RwLock};
+use std::sync::Arc;

 #[derive(Debug)]
 struct AdaptiveNode {
@@ -49,7 +48,7 @@ impl AdaptiveWeightBalancer {
 }

 impl Balancer for AdaptiveWeightBalancer {
-    fn choose_backend(&mut self, ctx: ConnectionInfo) -> Option<Arc<Backend>> {
+    fn choose_backend(&mut self, _ctx: ConnectionInfo) -> Option<Arc<Backend>> {
        if self.pool.is_empty() {
            return None;
        }
@@ -148,6 +147,7 @@ mod tests {
    use super::*;
    use crate::backend::Backend;
    use std::net::SocketAddr;
+    use std::sync::RwLock;

    fn backend_factory(id: &str, ip: &str, port: u16) -> Arc<Backend> {
        Arc::new(Backend::new(
--- a/src/balancer/round_robin.rs
+++ b/src/balancer/round_robin.rs
@@ -19,7 +19,7 @@ impl RoundRobinBalancer {
 }

 impl Balancer for RoundRobinBalancer {
-    fn choose_backend(&mut self, ctx: ConnectionInfo) -> Option<Arc<Backend>> {
+    fn choose_backend(&mut self, _ctx: ConnectionInfo) -> Option<Arc<Backend>> {
        let backends = self.pool.backends.clone();
        if backends.is_empty() {
            return None;
--- a/src/config/loader.rs
+++ b/src/config/loader.rs
@@ -7,8 +7,8 @@ use crate::backend::health::*;
 use crate::backend::*;
 use crate::balancer::Balancer;
 use crate::balancer::adaptive_weight::AdaptiveWeightBalancer;
-use crate::balancer::round_robin::RoundRobinBalancer;
 use crate::balancer::ip_hashing::SourceIPHash;
+use crate::balancer::round_robin::RoundRobinBalancer;
 use crate::config::*;

 pub struct RoutingTable {
@@ -37,7 +37,9 @@ pub fn build_lb(
    let mut backends: HashMap<String, Arc<Backend>> = HashMap::new();

    for backend_cfg in &config.backends {
-        let addr: SocketAddr = backend_cfg.ip.parse()
+        let addr: SocketAddr = backend_cfg
+            .ip
+            .parse()
            .map_err(|_| format!("bad ip: {}", backend_cfg.ip))?;
        let ip = addr.ip();

@@ -87,7 +89,7 @@ pub fn build_lb(
        let mut port_groups: HashMap<u16, Vec<IpCidr>> = HashMap::new();

        for client_def in &rule.clients {
-            let (cidr, port) = parse_client(&client_def)?;
+            let (cidr, port) = parse_client(client_def)?;
            port_groups.entry(port).or_default().push(cidr);
        }

--- a/src/main.rs
+++ b/src/main.rs
@@ -3,25 +3,22 @@ mod balancer;
 mod config;
 mod proxy;

-use crate::backend::health::{start_healthcheck_listener, start_iperf_server, ServerMetrics};
+use crate::backend::health::{ServerMetrics, start_healthcheck_listener, start_iperf_server};
 use crate::balancer::ConnectionInfo;
-use crate::config::loader::{build_lb, RoutingTable};
+use crate::config::loader::{RoutingTable, build_lb};
 use crate::proxy::tcp::proxy_tcp_connection;
 use anywho::Error;
+use clap::Parser;
+use notify::{Event, RecursiveMode, Watcher};
 use std::collections::HashMap;
 use std::fs::File;
-use std::hash::Hash;
-use std::net::{IpAddr, SocketAddr};
+use std::net::IpAddr;
 use std::path::PathBuf;
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::{Arc, Mutex, RwLock};
 use std::time::Duration;
-use tokio::io::AsyncBufReadExt;
 use tokio::net::TcpListener;
 use tokio::sync::mpsc;
-use clap::Parser;
-use notify::{Event, RecursiveMode, Watcher};
-use std::cmp;

 static NEXT_CONN_ID: AtomicU64 = AtomicU64::new(1);

@@ -72,11 +69,11 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
        let (tx, mut rx) = mpsc::channel(1);

        let mut watcher = notify::recommended_watcher(move |res: Result<Event, notify::Error>| {
-            if let Ok(event) = res {
-                if event.kind.is_modify() {
+            if let Ok(event) = res
+                && event.kind.is_modify()
+            {
                let _ = tx.blocking_send(());
            }
-            }
        })
        .unwrap();