HellcatAPI

A fast serve Raw HTTP server framework for backend developments, strongly typed & build with java.

Project Structure

HellcatAPI/
├── pom.xml
├── server.properties          ← server configuration (host, port, debug, dirs)
├── templates/
├── static/
└── src/main/java/hellcat/
    ├── TestApi.java            ← main entry point
    └── core/
        ├── app/
        │   └── HellcatApp.java
        ├── server/
        │   ├── HellcatServer.java
        │   ├── HellcatConnectionHandler.java
        │   └── HellcatServerLogger.java
        ├── router/
        │   ├── HellcatRouter.java
        │   └── HellcatRoute.java
        ├── request/
        │   ├── HellcatRequest.java
        │   ├── HellcatRequestParser.java
        │   └── HellcatUploadedFile.java
        ├── response/
        │   ├── HellcatResponse.java
        │   └── HellcatStreamResponse.java
        ├── middleware/
        │   ├── HellcatMiddleware.java
        │   └── HellcatMiddlewares.java
        ├── template/
        │   └── HellcatTemplateEngine.java
        ├── context/
        │   └── HellcatContext.java
        ├── db/
        │   ├── HellcatDB.java
        │   ├── HellcatQueryBuilder.java
        │   └── HellcatTransactionContext.java
        └── lib/
            ├── Logger.java
            └── ServerConfig.java

Configuration — server.properties

Edit server.properties in the project root before running:

server.host=0.0.0.0
server.port=9926
server.debug=false
server.template.dir=templates
server.static.dir=static
server.static.url=/static

Key	Default	Description
server.host	0.0.0.0	Bind address
server.port	9926	Listen port
server.debug	false	Enable debug mode (true / false)
server.template.dir	templates	HTML template directory
server.static.dir	static	Static files directory
server.static.url	/static	URL prefix for static files

Build & Run

Requirements: Java 17+, Maven 3.6+

mvn clean package -q
java -jar HellcatAPI.jar

Defining Routes

HellcatApp App = new HellcatApp("your-secret-key");

App.Get("/hello", Req ->
    App.Json(Map.of("Message", "Hello World"))
);

App.Post("/echo", Req -> {
    Map<String, Object> Body = Req.GetJson();
    return App.Json(Body);
});

App.Get("/users/<int:Id>", Req -> {
    int Id = Integer.parseInt(Req.PathParams.get("Id"));
    return App.Json(Map.of("Id", Id));
});

App.Route("/multi", List.of("GET", "POST"), Req ->
    App.Json(Map.of("Method", Req.Method))
);

App.Run();

Middleware

// Built-in middleware
App.UseCors(List.of("*"), false);
App.UseRateLimit(100, 60);
App.UseSecurityHeaders();
App.UseGzip(1024);
App.UseBodySizeLimit(10 * 1024 * 1024);

// Custom middleware (lambda)
App.UseMiddleware((Req, Next) -> {
    long Start  = System.currentTimeMillis();
    Object Resp = Next.apply(Req);
    System.out.println("Duration: " + (System.currentTimeMillis() - Start) + "ms");
    return Resp;
});

// Route-level middleware
App.Post("/secure", Handler, List.of(RequireAuthMiddleware));

Templates

Uses a lightweight Jinja2-like engine. Templates go in the templates/ folder.

App.Get("/", Req ->
    App.Render("index.html", Map.of(
        "Title",   "HellcatAPI",
        "Message", "Server is running!"
    ))
);

Supported syntax:

{{ variable }} {{ object.field }} {{ value | raw }} {% if condition %}...{%
endif %} {% for item in items %}{{ item }}{% endfor %} {% extends "base.html"
%}{% block content %}...{% endblock %} {% include "partial.html" %} {# comment
#}

Database

SQLite out of the box (PostgreSQL / MySQL via JDBC driver swap).

HellcatDB DB = new HellcatDB("app.db", 10, migrations);

// Query builder
DB.Table("users").WhereEq("role", "admin").OrderBy("id").All();
DB.Table("users").WhereEq("id", 1).First();
DB.Table("users").Count();
DB.Table("users").WhereLike("name", "%Tom%").Paginate(1, 20);

// Write
DB.InsertRow("users", Map.of("name", "Tom", "email", "tom@example.com"));
DB.Table("users").WhereEq("id", 1).Update(Map.of("name", "Bob"));
DB.Table("users").WhereEq("id", 1).Delete();

// Transaction
try (HellcatTransactionContext Tx = DB.Transaction()) {
    Tx.Execute("UPDATE products SET stock = stock - ? WHERE id = ?", 1, 5);
    long OrderId = Tx.Insert("INSERT INTO orders (...) VALUES (...)", ...);
    Tx.Commit();
}

// Auto migrations (run once on startup)
Map<String, String> Migrations = new LinkedHashMap<>();
Migrations.put("001_create_users", "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
HellcatDB DB = new HellcatDB("app.db", 10, Migrations);

Request Object

Req.Method           // "GET", "POST", etc.
Req.Path             // "/users/42"
Req.PathParams       // {"Id": "42"}
Req.QueryParams      // {"page": "1"}
Req.Headers          // all headers (lowercase keys)
Req.Cookies          // parsed cookies
Req.Body             // raw byte[]
Req.GetJson()        // parsed JSON body as Map
Req.GetQuery("page", "1")   // query param with default
Req.GetHeader("Authorization")
Req.GetRemoteIp()
Req.IsJson()
Req.IsForm()
Req.IsMultipart()

Response Helpers

App.Json(data)
App.Json(data, 201)
App.Html("<h1>Hello</h1>")
App.Text("plain text", 200)
App.Redirect("/login")
App.Redirect("/login", 301)
App.Error("Not found", 404)
App.Error("Validation failed", 422, Map.of("field", "email"))
App.File("report.pdf", "download.pdf")
App.Stream(() -> chunks, "text/event-stream")
App.Render("template.html", context)

JWT & Sessions

// Create JWT
String Token = App.CreateJwt(Map.of("UserId", 1, "Role", "admin"), 3600);

// Decode JWT
Map<String, Object> Payload = App.DecodeJwt(token);

// Session
Map<String, Object> Session = App.GetSession(Req);
App.SaveSession(Response, Map.of("UserId", 1), null);

Sub-Routers

HellcatRouter Api = new HellcatRouter("/api/v1");

Api.Get("/health", Req -> App.Json(Map.of("Status", "ok")));
Api.Get("/users",  Req -> App.Json(DB.Table("users").All()));

App.Include(Api);

Error Handlers

App.ErrorHandler(404, (Req, Err) ->
    App.Json(Map.of("Error", true, "Message", "Route not found", "Path", Req.Path), 404)
);

App.ErrorHandler(500, (Req, Err) ->
    App.Json(Map.of("Error", true, "Message", "Internal server error"), 500)
);

Dependencies

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.17.0</version>
</dependency>
<dependency>
    <groupId>org.xerial</groupId>
    <artifactId>sqlite-jdbc</artifactId>
    <version>3.45.3.0</version>
</dependency>

---

Documentation

• Open: Sites

Credit

• Author: @MatrixTM26
• License: AGPL-V3

Support Me

---

Copyright ©2023-2026 MatrixTM26 · All Rights Reserved