water_http

http framework meant to be the fastest and easiest http framework by using the power of rust macros and it`s provide stable workload over os systems and all the important features for servers

Features

• very slight and easy to use
• blazingly fast with very advanced concepts and services to provide, you can see Benchmarks repository
• very simple and familiar constructor
• support both protocols http2 and http1 with all existed features and more
• support all http encoding algorithms with custom encoding for low levels like
  • brotli
  • zstd
  • gzip
  • deflate
  • lz4
  • snappy
  • bzip2
  • custom encoding algorithms for low level of programming
• provide simple routing structure with many patterns of write
• very fast http parsing algorithms which archived http 1 parsing with 1 micro second
• can handle millions of requests in given seconds
• support videos streaming for web pages videos
• provide easy approaches for saving and downloading files from and to the server
• support tls or ssl implementation for secure connections without any confusing
• naming routes and redirecting to these routes by their names using one single method
• multi pattern ways to generate your code and very easy approaches
• support controlling low actions like block custom ip addresses from connecting your server or strict your service to custom ip addresses
• thresholding actions like the threshold the maximum size of using compressing algorithms when sending response back considering clients encoding support

Nice Information

• we need to understand that http request is based on another protocols like tcp (http1 and htt2) or udp (http3) and what framework is basically do is to read incoming bytes into certain bytes buffer which located on ram memory so when the framework uses the same bytes which read by the OS as much as possible that would make the framework better because at this logic we had zero additional memory allocations and that`s what water_http framework is meant to be
• when we need to serve requests in better pattern we need to understand one thing ( less memory allocations leads to better performance ) so water http used another way of serving post request in http 1 protocol and it`s allocating one buffer for each connection and reusing the same allocated buffer for each http request instead of using new buffer for each http request
• we are using IncomingRequest struct for parsing Http requests which it self-developed struct for using the same buffer bytes to handling request and also single bytes iteration with zero allocations
• we used the power of rust macros to makes code very easy to build and use /

Installation

for start building your own web server app you need to follow the steps

• install water_http by
  • using shell

    cargo add water_http
    

  • using cargo.toml file

    water_http = "[last_version]"
    

• install tokio by
  • using shell

    cargo add tokio --features=full
    

  • using cargo.toml file

    tokio = {version = "[last_version]",features = ["full"] }     
    

  Notes : you may encounter errors while building your Application because there are some packages depends on clang compiler specially tls crates , so you need to install clang llvm compiler and so on

Concepts

• water http built with concepts of controllers tree let`s say we have

  -MainController __ child 1 Controller | child 2 controller

  child 1 and child2 controller are both depends on MainController prefix if he has one and also could depend on MainController middleware if apply_parents_middlewares was set to true

• the context has shared public object of type generic ,so we could parse anything to children controllers also we need to specify what is the maxy headers count ( which means how many headers we would read from incoming request ) and the max query count ( which means how many queries we could request using path ) for example : http://example.com/post?id=1&name=2 in this example we have two queries in the path (id,name)

so to init these for controllers we could use InitControllerRoot macro

use std::collections::HashMap;
use water_http::InitControllersRoot;

type MainHolderType = HashMap<String,String>;
InitControllersRoot! {
    /// the name of root
    name:MAIN_ROOT,
    /// holder type
    holder_type:MainHolderType,
    /// (optional) default (16)
    headers_length:16,
    /// (optional) default(16)
    queries_length:16
}

so after initializing our controllers root we could build our controllers

Note : we are specifying headers length and queries length for two purpose

1- for providing security and refuse all malicious big load requests

2- to allocate memory on the stack which need known sized bytes so that we could make the app significantly faster

Some Tips

• if you need to trace debugging hints you could use feature debugging by running shell

  cargo run --features debugging
  

• if you need to count speed of parsing bytes to http 1 protocol as request you could use feature "count_connection_parsing_speed"

 cargo run --features count_connection_parsing_speed

• if you need to run one of the examples files

 cargo run example public_files_serving

• to set the framework to auto handle content encoding when sending back response

use water_http::server::{EncodingConfigurations, EncodingLogic, ServerConfigurations};

 fn enable_encoding(config:&mut ServerConfigurations){

     let mut  encoding = EncodingConfigurations::default();
     encoding.set_logic(EncodingLogic::All);
     config.set_response_encoding_configuration(
         encoding
     );
 }

• to enable using tls

use water_http::server:: ServerConfigurations;

fn enabling_tls(config:&mut ServerConfigurations){
    // you could set multiple tls ports
    config.tls_ports = vec![8084,443];
    // specify the location of certificate.crt file and private.key
    config.set_tls_certificate(
        "./ssl/local_ssl/certificate.crt",
        "./ssl/local_ssl/private.key",
        None
    );
}

Note: you could choose your needed file from examples folder

🚀 Benchmarking

Water_http is now officially included in TechEmpower Framework Benchmarks, the most trusted and widely recognized benchmarking organization for web frameworks.

Benchmarking results for water_http will appear in the next official round, but you can already view and test it manually through the TechEmpower repository.

Current status:

✔️ water_http has been approved and merged into the TechEmpower project

✔️ Source and benchmark implementation are publicly available

⏳ Official numbers will be published in the upcoming round

🔍 You can manually inspect or run the benchmark now: https://github.com/TechEmpower/FrameworkBenchmarks

This marks a major milestone for water_http, showcasing its speed, stability, and production-grade performance.

Starting

• firstly you need to define Controllers Root as we explain in Concepts

• create controller using water_http::WaterController macro

 use water_http::WaterController;
/// we use crate key word because this macro will 
/// encapsulate everything inside new mod
/// and holder is the type that we defined in the previous step

WaterController! {
    holder -> crate::MainHolderType,
    name -> RootController,
    functions -> {
        GET => / => any_thing(context) async {
            _=context.send_str("hello world").await;
        }
    }
  }

• now inside main fn in rust we will create configurations and run the server app

 #[tokio::main]
 async fn main(){
    let  configs = ServerConfigurations::bind("127.0.0.1",8084);
    water_http::RunServer!(
        configs,
        MAIN_ROOT,
        RootController
    );
}

Basic Example

use std::collections::HashMap;
use water_http::server:: ServerConfigurations;
use water_http::{InitControllersRoot, WaterController};

type MainHolderType = HashMap<String,String>;
InitControllersRoot!{
   name:MAIN_ROOT,
   holder_type:MainHolderType,
}


#[tokio::main]
async fn main() {

   let  configs = ServerConfigurations::bind("127.0.0.1",8084);

   water_http::RunServer!(
       configs,
       MAIN_ROOT,
       MainController
   );
}
WaterController! {
   holder -> crate::MainHolderType,
   name -> MainController,
   functions -> {
       GET => / => any_thing(context) async {
           _=context.send_str("hello world").await;
       }
   }

}

Notes :

• water_http use tokio runtime for multithreading tasks
• using WaterController macro need to have (name,holder,function) in order arrangement but the following properties no needs for that
• you may need to install cmake and clang compiler for compiling
• in linux make sure to have build-essential and cmake and you sometime gcc to do install any of them

sudo apt-get install build-essential cmake 

• if you want to create fn which take context as parameter

you would need to parse parameters as following

use water_http::server::HttpContext;
type MainHolderType = crate::MainHolderType;
async fn handle_context<'context>(
    context:&mut HttpContext<'context,MainHolderType,16,16>){
    // Main Holder type it`s what you defined when InitControllersRoot
    // 16 and 16 is the headers and query length ,and they are the default values
    // if you need to change them then you need to chane the MainRoot defined lengths or
}

or you could use also

use water_http::server::HttpContext;
type MainHolderType = crate::MainHolderType;
async fn handle_context<'context,
 const HL:usize,
 const QL:usize   
>(
    context:&mut HttpContext<'context,
        MainHolderType,HL,QL>){
}

Writing Responses

• using sender

 water_http::functions_builder!{
     
     
     pub async fn send_response(context){
         let mut sender = context.sender();
         if sender.send_str("hello this is api response").await.is_ok() {
            println!("response sent successfully");
       }
     } 
     
     
}

and there is alot of functions that facilitate sending responses like sending json or file from public directory

  water_http::functions_builder!{
    
    
  pub async fn send_response(context){
          let mut sender = context.sender();
          let file = FileRSender::new("./public/text/test1.jpg");  
           if sender.send_file(file).await.is_success() {
            println!("file sent successfully");
        }
      } 
    
    
 }

• using context sending methods

 water_http::functions_builder! {
    
    
       pub async fn send_response(context){
        if context.send_str("hi this is api response").await.is_ok() {
            println!("response sent successfully");
        }
      }  
    
      pub async fn send_file(context){
          
        if context.send_file(FileRSender::new("./public/text/test1.txt")).await.is_success() {
            println!("response sent successfully");
        }
      }   
    
    
}

• using water_http macros

water_http::functions_builder! {
    
    
     pub async fn send_response(context){
         
       response!(context -> "hi this is api response") ;
     }  
   
     pub async fn send_file(context){
        response!(context file -> "./public/text/test1.txt");
     }   
    
    
}

also you could use response!(context json -> jsonValue ); to send json response

Writing Controllers Functions styles

use water_http::WaterController;
// you can use one style to make it your default and favorite one
// my personal favorite one is
// method -> path -> function_name(context) async {
//   function body
// }
WaterController! {
    holder -> crate::MainHolderType,
    name -> MainController,
    functions -> {

        // in this case path is "/" while method is GET
        "/" hello_world(context){
            _=context.send_str("hello world").await;
        }

        // in this case hi is the path and method is  GET
        hi(context) [crate::get_response]

        // in this case hi_post would be the path
        POST => hi_post(context) [crate::get_response]

        // in this case POST is the name of path and the method is GET
        "POST" => post(context) [crate::get_response]

        // in this case method is POST and path is ['test/post1']
        POST test/post1 g(context) async {
            super::get_response(context).await
        }

        // in this case method is get and path is hello
        hello(context) [super::get_response]

        // in this case method is post and get is path
        POST => get(context) async {
            super::get_response(context).await;
        }

        // in this case GET is the method and 'api/v1/users/' the path
        // and this type could inject string parameter like
        // 'api/v1/users/t22' so t22 is now represented by id variable
        GET -> api/v1/users/{id} -> get_user(context) async{
            println!("user id is {id}");
            super::get_response(context).await;
        }

        // in this case POST is Method and api/auth/login is path
        POST => api/auth/login => login_handler(context) async {
            response!(context -> "hello from login api endpoint");
        }

        GET info(context)[super::get_response]

        // in this case GET is the method and api/v2 is path ,
        #[POST,api/v2/{id}]
        get_profiles(context)  {
         println!("v2 id is {id}");
         super::get_response(context).await;
        }

        // in this example GET is the method and api/v23 is path
        #[GET,api/v23]
        get_profiles_v2(context) async {
          super::get_response(context).await;
        }

         // in this example GET is the method and api/v3 is path
        #[GET,api/v3]
        get_profiles_v3(context) async [super::get_response]

         // in this example GET is the method and api/v4 is path
        #[GET,api/v4]
        get_profiles_v4(context)  [super::get_response]
        
         // in this example GET is the method and api/v5 is path
        #[GET,api/v5]
        async get_profiles_v5(context)  [super::get_response]

        #[GET,api/6]
        async get_profiles_6(context)  {
            super::get_response(context).await;
        }

        getFile(context) [super::send_files]

    }
    extra_code->(..{



    })
}
// notice that writing methods like POST,post,Post,posT,POst
// it would give the same result cause the framework has auto under table requests handler

Full Code example

use std::collections::HashMap;
use water_http::server::{ServerConfigurations};
use water_http::{InitControllersRoot, response, WaterController};
use water_http::http::HttpSenderTrait;


InitControllersRoot! {
    name:MAIN_ROOT,
    holder_type:MainHolderType,
}
type MainHolderType = CHolder;

#[derive(Debug)]
pub struct CHolder {
    pub user:Option<HashMap<String,String>>,

}

#[tokio::main]
async fn main() {

    // when debugging feature enabled
    #[cfg(feature = "debugging")]
    {
        let subscriber  = tracing_subscriber::FmtSubscriber::builder()
            .with_max_level(tracing::Level::DEBUG)
            .finish();
        tracing::subscriber::set_global_default(subscriber)
            .expect("no thing");
    }


    let  config = ServerConfigurations::bind("127.0.0.1",8084);
    water_http::RunServer!(
        config,
        MAIN_ROOT,
        MainController
    );
}

// you can use one style to make it your default and favorite one
// my personal favorite one is
// method -> path -> function_name(context) async {
//   function body
// }
WaterController! {
    holder -> crate::MainHolderType,
    name -> MainController,
    functions -> {
         // in this case POST is Method and api/auth/login is path
        POST => api/auth/login => login_handler(context) async {
            response!(context -> "hello from login api endpoint");
        }


        GET => "categories/byId/{id}" => get_cat(context) [super::get_cat_by_id]

        // in this case GET is the method and 'api/v1/users/' the path
        // and this type could inject string parameter like
        // 'api/v1/users/t22' so t22 is now represented by id variable
        GET -> api/v1/users/{id} -> get_user(context) async{
            println!("user id is {id}");
            super::get_response(context).await;
        }


        // in this case path is "/" while method is GET
        "/" hello_world(context){
            _=context.send_str("hello world").await;
        }

        // in this case hi is the path and method is  GET
        hi(context) [crate::get_response]

        // in this case hi_post would be the path
        POST => hi_post(context) [crate::get_response]

        // in this case POST is the name of path and the method is GET
        "POST" => post(context) [crate::get_response]

        // in this case method is POST and path is ['test/post1']
        POST test/post1 g(context) async {
            super::get_response(context).await
        }

        // in this case method is get and path is hello
        hello(context) [super::get_response]

        // in this case method is post and get is path
        POST => get(context) async {
            super::get_response(context).await;
        }



        GET info(context)[super::get_response]

        // in this case GET is the method and api/v2 is path ,
        #[POST,api/v2/{id}]
        get_profiles(context)  {
         println!("v2 id is {id}");
         super::get_response(context).await;
        }

        // in this example GET is the method and api/v23 is path
        #[GET,api/v23]
        get_profiles_v2(context) async {
          super::get_response(context).await;
        }

         // in this example GET is the method and api/v3 is path
        #[GET,api/v3]
        get_profiles_v3(context) async [super::get_response]

         // in this example GET is the method and api/v4 is path
        #[GET,api/v4]
        get_profiles_v4(context)  [super::get_response]
         // in this example GET is the method and api/v4 is path

        #[GET,api/v5]
        async get_profiles_v5(context)  [super::get_response]

        #[GET,api/6]
        async get_profiles_6(context)  {
            super::get_response(context).await;
        }

        getFile(context) [super::send_files]

    }
    extra_code->(..{

    }),
    middleware-> (context {
        println!("middleware function invoked");

        if let Some(ref holder) = context.holder {
            if holder.user.is_some() {
                println!("user is authenticated");
            }
        }

        if 1 == 1  { return server::MiddlewareResult::Pass }

        response!(context -> "invalid middleware passing");
        server::MiddlewareResult::Stop
    })
}

// notice that writing methods like POST,post,Post,posT,POst
// it would give the same result cause the framework has auto under table requests handler

water_http::functions_builder!{

    pub async fn get_response(context)  {
        let method = context.method();
        let path = context.path();

        // sending response
        response!(context string -> "method is {method} while path is {path}");
    }

    pub async fn get_cat_by_id(context) (id){
        let method = context.method();
        let path = context.path();
      response!(context string -> "method is {method} , id is {id} while path is {path}");
    }

    pub async fn send_files(context)  {

           response!(context file -> "./public/text/test1.txt");

        // response!(context file -> "./public/text/test1.txt",|c|{
        //     // if we need to modify or encrypt every chunk sent to the user
        //     for i in &mut *c {
        //         *i = b'a';
        //     }
        // });

    }

      pub async fn send_response(context){

        response!(context -> "hi this is api response") ;
      }

      pub async fn send_file(context){
         response!(context file -> "./public/text/test1.txt");
      }
}

// to generate normal function without helper
// pub async fn fn_name<'context, MainHolderType: Send + 'static, const header_length: usize, const query_length: usize>
//   (context: &mut water_http::server::HttpContext<'context, MainHolderType, header_length, query_length>) {
// }

// so we created water_http::functions_builder macro to help you create functions in fast and easy way

🚀 The fast_build! Macro (Easy & Rapid Prototyping)

When you need to spin up a structured server with full routing support instantly, water_http offers the fast_build! macro. It eliminates boilerplate entirely, automatically managing controller root initializations, server configurations, and setup hooks behind the scenes for an incredibly fast and straightforward development cycle.

Feature Variants & Syntax Flexibility

The fast_build! macro adapts to your architecture natively. Whether you need a minimal single-file endpoint or a complex tree of controllers with shared multi-threaded state, fast_build! handles it effortlessly.

1. The Ultra-Fast Bare Minimum

Great for simple microservices. Bypasses structure configuration overhead and assumes default bindings automatically.

use water_http::fast_build;
fn main() {
  start_fast_server();
}

fast_build!{
    port -> 8081,
    functions -> {

        GET => / => hello(context)async{
            _= context.send_str("hello from fast server").await;
        }
    }
}

⏳ The LazyResponse Architecture (Deferred Payload Pipeline)

In standard server configurations, writing a response immediately pushes byte chunks down into the active socket stream. While fast for simple handlers, immediate execution strips away the ability to modify or abort responses during deep controller routing traversals or middleware execution phases.

water_http solves this with LazyResponse. A lazy response defers payload assembly and socket writes until the final microsecond of the connection cycle. It holds the payload in a non-allocating, deferred structure until the entire controller tree validation finishes, ensuring all headers, state changes, and interceptors have had their absolute final say before committing to a network transmit.

Key Advantages

• Perfect Middleware Compatibility: Parent interceptors can safely override, augment, or drop down-tree handlers because no bytes have physically touched the socket yet.
• Dynamic Header Mutation: Append or alter headers anywhere along the pipeline route without triggering pre-mature chunk transmission errors.
• Early-Exit Guarantees: Instantly stop expensive nested database/serialization logic if an upper-tier interceptor completely overrides the response context.

Code Example: Cascade Interception & Lazy Deferral

The example below demonstrates how multiple nested controllers handle LazyResponse contexts, and how parent interceptors seamlessly intercept and rewrite down-tree executions when apply_parents_interceptors -> (true) is configured.

use water_http::server::ServerConfigurations;
use water_http::{InitControllersRoot, WaterController};

type MainHolderType = u8;
InitControllersRoot!{
    name: MAIN_ROOT,
    holder_type: MainHolderType,
}

fn main() {
    let config = ServerConfigurations::bind("127.0.0.1", 8084);
    water_http::RunServer!(
        config,
        MAIN_ROOT,
        MainController
    );
}

// =============================================================================
// ROOT CONTROLLER
// =============================================================================
WaterController! {
    holder -> crate::MainHolderType,
    name -> MainController,
    functions -> {
        GET => / => main(context) async {
            let mut response = http::LazyResponse::new();
            response.set_text_response("hello world from lazy response");
            context.set_lazy_response(response);
        }
    }
    children -> ([
        SecondController
    ]),
    interceptor -> (context {
        let mut response = http::LazyResponse::new();
        response.set_text_response("response intercepted by root interceptor");
        context.set_lazy_response(response);
    })
}

// =============================================================================
// SECONDARY NESTED CONTROLLER
// =============================================================================
WaterController! {
    holder -> crate::MainHolderType,
    name -> SecondController,
    functions -> {
        GET => secondController => main(context) async {
            let mut response = http::LazyResponse::new();
            response.set_text_response("hello world from lazy response");
            context.set_lazy_response(response);
        }
    }
    interceptor -> (context {
        let mut response = http::LazyResponse::new();
        response.set_text_response("response intercepted by SecondController");
        context.set_lazy_response(response);
    }),
    children -> ([
        ThirdController
    ])
}

// =============================================================================
// THIRD NESTED CONTROLLER (INHERITING PARENT PIPELINES)
// =============================================================================
WaterController! {
    holder -> crate::MainHolderType,
    name -> ThirdController,
    functions -> {
        GET => thirdController => main(context) async {
            let mut response = http::LazyResponse::new();
            
            // This evaluation is completely bypassed at runtime!
            // Because 'apply_parents_interceptors' is true, SecondController's 
            // interceptor overwrites the deferred context first. The socket never
            // registers the string below.
            response.set_text_response("hello world from ThirdController");
            context.set_lazy_response(response);
        }
    }
    
    // Forces execution of upstream middleware trees before final pipeline generation
    apply_parents_interceptors -> (true)
}

⚡ The mini Engine (Zero-Overhead Hyper-Performance)

For deployment environments where every single CPU cycle, byte of memory, and nano-second matters, water_http provides a dedicated mini engine.

It is designed specifically to serve ultra-tiny services with absolute zero runtime overhead. By bypassing traditional macro routers, allocations, and controller hierarchies, mini gives you direct, raw, bare-metal access to the underlying socket ring-buffers using stack-allocated const-generics.

Key Highlights

• Strictly Zero Heap Allocation: Memory layout is completely determined at compile time.
• No Routing Overhead: Requests drop straight into a single, lightning-fast direct callback handler.
• Bare-Metal Context Control: Uses direct raw static pointer structures (CtxPtr) instead of heavy abstraction layers.

Code Example

use water_http::server::mini::{CtxPtr, HandlerFn, serve};
use water_http::server::ServerConfigurations;

fn main() {
    let no_init = || async {};
    let conf = ServerConfigurations::bind("0.0.0.0", 8084);
    serve::<16, 10, _,_,_>(conf, HandlerFn(|ctx: CtxPtr<16, 10>| handler(ctx)),Some(no_init));
}

async fn handler(mut ctx: CtxPtr<16,10>){
    let ctx = ctx.get();
    ctx.set_header("Content-Length", "11");
    ctx.write_body_bytes(b"Hello World");
}

⚠️ Current Architecture Limitations

While water_http is engineered for extreme raw performance, certain feature combinations are explicitly restricted due to fundamental architectural trade-offs.

1. io_uring is Restricted to Plaintext HTTP/1.x Only

The high-performance asynchronous io_uring completion-based engine is strictly scoped to plaintext HTTP/1.x. It is deliberately not supported alongside TLS or HTTP/2 for the following system-level reasons:

• TLS Devalues io_uring (System Call Optimization Defeat): The core purpose of utilizing io_uring is to eliminate runtime system calls (read/write) by sharing submission and completion queues directly with the kernel. When using TLS, encrypted data must constantly be brought back up to user-space cryptographic libraries (like rustls or openssl) for decryption and processing before the server can even understand the HTTP payload. This user-space memory thrashing and parsing overhead completely negates the syscall-limitation benefits that io_uring provides, making it functionally useless for encrypted streams.

• HTTP/2 Requires a Separate From-Scratch Architecture: HTTP/2 shifts the network paradigm to a highly multiplexed, single-connection stream framework. Mapping asynchronous, independent kernel completion events back to a heavily stateful, multiplexed frame system requires an entirely custom I/O architecture built from scratch specifically for that purpose.

🛠️ Fallback Behavior: When your server configurations enable TLS/SSL or require HTTP/2 features, water_http transparently shifts routing traffic to its highly optimized, stable epoll/Tokio-driven runtime network backend, ensuring 100% feature reliability.

2. Strict Path-Based Routing (No Method Multiplexing)

To achieve absolute maximum routing throughput and eliminate pointer-chasing overhead during requests, water_http utilizes an ultra-lean, highly optimized map to resolve route handlers. Consequently, the router matches strictly by the URI path string, introducing a strict design rule:

No Shared Paths Across HTTP Methods: You cannot bind multiple HTTP methods (such as a GET and a POST) to the exact same path string (e.g., /api/data). If paths overlap, one handler will overwrite the other in the map.

The Performance Payload: By removing multi-method conditional branching and nested lookups inside the hot path of the router, path lookup achieves near-constant time complexity, keeping route resolution lightning fast.

💡 Recommended Design Pattern: If you need to handle multiple actions on a single resource, use explicit, high-performance RESTful paths (e.g., GET /api/data_get and POST /api/data_post) or distinct action-based prefixes.