web_app

Minimal HTTP web application kit for modern C++.

web_app provides a lightweight web-oriented runtime built on top of the vix/app lifecycle foundation.

Header-only. Depends only on vix/app.

Download

https://vixcpp.com/registry/pkg/vix/web_app

Why web_app?

Every C++ web backend eventually needs:

• Route registration
• Request dispatching
• Response handling
• A structured application lifecycle
• Graceful shutdown
• Clean separation between runtime and business logic

Most projects either:

• Mix routing logic into main()
• Rebuild routing primitives repeatedly
• Tie themselves to a specific HTTP server too early
• Lack clear lifecycle control

web_app provides:

• A minimal router (exact match)
• Explicit Request / Response types
• Deterministic dispatch model
• Lifecycle integration via vix/app
• Clean extension points for real HTTP backends

No middleware stack. No JSON dependency. No async runtime requirement.

Just a structured web foundation.

Dependency

web_app depends on:

• vix/app

When installed via Vix Registry, vix/app is automatically installed.

This means:

• Lifecycle management is handled by vix::app::Application
• web_app focuses only on web semantics
• Clear separation of concerns

Installation

Using Vix Registry

vix add vix/web_app
vix deps

This will automatically install:

• vix/app

Manual

git clone https://github.com/vixcpp/web_app.git

Add the include/ directory to your project and ensure vix/app is available.

Quick example

#include <web_app/web_app.hpp>
#include <iostream>

class MyWebApp : public vix::web_app::WebApplication
{
protected:
    void serve_once() override
    {
        vix::web_app::Request req;
        req.method = vix::web_app::HttpMethod::Get;
        req.path = "/";

        auto res = dispatch(req);

        std::cout << res.status << " -> " << res.body << "\n";
        stop();
    }
};

int main()
{
    MyWebApp app;

    app.router().get("/", [](const vix::web_app::Request&) {
        vix::web_app::Response r;
        r.body = "Hello web_app";
        return r;
    });

    app.run();
}

Routing example

using vix::web_app::Request;
using vix::web_app::Response;

app.router().get("/users", [](const Request&) {
    Response r;
    r.body = "User list";
    return r;
});

app.router().post("/users", [](const Request& req) {
    Response r;
    r.body = "Created user with body: " + req.body;
    return r;
});

If no route matches, dispatch() returns:

• status 404
• body "Not Found"

API overview

Types:

• vix::web_app::WebApplication
• vix::web_app::Router
• vix::web_app::Request
• vix::web_app::Response
• vix::web_app::HttpMethod

Methods:

• WebApplication::router()
• WebApplication::dispatch()
• Router::get()
• Router::post()

Extension points:

• WebApplication::serve_once()
• WebApplication::run_loop()

Architecture model

Layered design:

vix/app
  ↑
vix/web_app

• vix/app handles lifecycle and shutdown.
• web_app handles routing and request dispatch.
• Higher-level kits (api_app, gateway_app, microservice_app) can extend web_app.

This ensures:

• Clear module boundaries
• Stable foundation
• No circular dependencies
• Composable runtime layers

Complexity

All routing operations are average O(1) due to hash-based lookup.

Operation	Time complexity
Route register	O(1) average
Route match	O(1) average
Dispatch	O(1) average

Lifecycle behavior depends on the underlying Application loop.

Design philosophy

web_app focuses on:

• Deterministic behavior
• Minimal abstraction
• Explicit request/response types
• No hidden threads
• No forced HTTP backend
• Clean runtime layering

It provides primitives only.

If you need:

• JSON APIs
• Middleware pipelines
• Authentication layers
• Reverse proxy behavior
• Service mesh integration

Build them on top of this layer.

Tests

Run:

vix build
vix test

Tests verify:

• Route registration
• Dispatch correctness
• 404 fallback behavior
• Lifecycle integration

License

MIT License
Copyright (c) Gaspard Kirira