minum

Project Url: byronka/minum
Introduction: An obsessively minimal Java web framework built from scratch
More: Author   ReportBugs   
Tags:

When you need the fewest moving parts

The simplest Minum program (see more code samples below):

public class Main {
    public static void main(String[] args) {
        var minum = FullSystem.initialize();
        var wf = minum.getWebFramework();
        wf.registerPath(GET, "",
                r -> Response.htmlOk("<p>Hi there world!</p>"));
        minum.block();
    }
}

What is this?

This web framework, "Minum", provides an all-in-one minimalist foundation for a highly-maintainable single-binary web application. For TDD, by TDD.

  • Has its own web server, endpoint routing, logging, templating engine, html parser, assertions framework, and database
  • Around 100% test coverage that runs in 30 seconds without any special setup (make test_coverage)
  • Nearly 100% mutation test strength using the PiTest tool. (make mutation_test)
  • Relies on no dependencies other than the Java 21 SDK - i.e. no Netty, Jetty, Tomcat, Log4j, Hibernate, MySql, etc.
  • Well-documented
  • Uses no reflection
  • Requires no annotations
  • No magic
  • Has examples of framework use:
    • a tiny project, as the basis to get started
    • a small project, showing some minimal use cases
    • a full application demonstrating realistic usage

Minum is five thousand lines of code - the "minimalist" competitors range from 400,000 to 700,000 lines when accounting for their dependencies. I have not found a similar project.

Applying a minimalist approach enables easier debugging, maintainability, and lower overall cost. Most frameworks trade faster start-up for a higher overall cost. If you need sustainable quality, the software must be well-tested and documented from the onset. As an example, this project's ability to attain such high test coverage was greatly enabled by the minimalism paradigm.

Getting Started

There is a 🚀 Quick start, or if you have a bit more time, consider trying the tutorial

Maven

<dependency>
    <groupId>com.renomad</groupId>
    <artifactId>minum</artifactId>
    <version>3.1.1</version>
</dependency>

Features:

Size Comparison:

Compiled size: 150 kilobytes.

Lines of production code (including required dependencies)

Minum Javalin Spring Boot
4,398 141,048 1,085,405

See details

Performance:

  • 19,000 http responses per second by web server. detail
  • 2,000,000 updates per second to database. detail
  • 27,000 templates per second rendered. detail

See framework performance comparison

Documentation:

Example projects demonstrating usage:

See the following links for sample projects that use this framework.

Smallest-possible

This project is valuable to see the minimal-possible application that can be made. This might be a good starting point for use of Minum on a new project.


Example

This is a good example to see a basic project with various functionality. It shows many of the typical use cases of the Minum framework.


Memoria project

This is a family-tree project. It demonstrates the kind of approach this framework is meant to foster.

Code samples

Instantiating a new database:

var db = new Db<>(foosDirectory, context, new Foo());

Adding a new object to a database:

var foo = new Foo(0L, 42, "blue");
db.write(foo);

Updating an object in a database:

foo.setColor("orange");
db.write(foo);

Deleting from a database:

db.delete(foo);

Writing a log statement:

logger.logDebug(() -> "hello");

Parsing an HTML document:

List<HtmlParseNode> results = new HtmlParser().parse("<p></p>");

Searching for an element in the parsed graph:

HtmlParseNode node;
List<HtmlParseNode> results = node.search(TagName.P, Map.of());

Creating a new web handler (a function that handles an HTTP request and returns a response):

public Response myHandler(Request r) {
  return Response.htmlOk("<p>Hi world!</p>");
}

Registering that endpoint:

webFramework.registerPath(GET, "formentry", sd::formEntry);

Building and rendering a template:

TemplateProcessor foo = TemplateProcessor.buildProcessor("hello {{ name }}");
String rendered = foo.renderTemplate(Map.of("name", "world"));

Getting a query parameter from a request:

String id = r.requestLine().queryString().get("id");

Getting a body parameter from a request, as a string:

String personId = request.body().asString("person_id");

Getting a body parameter from a request, as a byte array:

byte[] photoBytes = body.asBytes("image_uploads");
Apps
About Me
GitHub: Trinea
Facebook: Dev Tools