Minum Web Framework

This codebase provides the facilities necessary to build a web application, with a design that prioritizes server-side-rendering. Basic capabilities that any web application would need, like persistent storage or templating, are provided. See Features further down in this document.

You might find this project well-suited to your needs if your priority is maintainability and quality, and if you are aiming to build programs that last years with minimal upkeep.

There are several examples of projects built with this framework in the example projects below.

Here is a small 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();
    }
}

The high level characteristics

| Capability | Rating | |----------------|--------------| | Small | [#######-] | | Tested | [#######-] | | Documented | [######--] | | Performant | [######--] | | Maintainable | [#######-] | | Understandable | [#######-] | | Simple | [######--] | | Capable | [######--] |

• Embraces the concept of kaizen: small beneficial changes over time leading to impressive capabilities
• Has its own web server, endpoint routing, logging, templating engine, html parser, assertions framework, and database
• Designed with TDD (Test-Driven Development)
• It has 100% test coverage (branch and statement) that runs in 30 seconds without any special setup (make test_coverage)
• Has close to 100% mutation test strength using the PiTest mutation testing tool (make mutation_test)
• Relies on no dependencies other than the Java 21 (and up) SDK - i.e. no Netty, Jetty, Tomcat, Log4j, Hibernate, MySql, etc.
• Is thoroughly documented throughout, anticipating to benefit developers' comprehension
• No reflection - The framework's method calls are all scope-respecting, and navigation of the code base is plain
• No annotations - unlike certain other frameworks, the design principle is to solely use ordinary Java method calls for all behavior, and configuration is minimal and relegated to a properties file
• No magic - nothing unusual behind the scenes, no byte-code runtime surprises. Just ordinary Java
• Has examples of framework use - see Example Projects below

Minum has zero dependencies, and is built of ordinary and well-tested code: hashmaps, sockets, and so on. The "minimalist" competitors range from 400,000 to 700,000 lines when accounting for their dependencies.

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. The plentiful tests and comments help to make intent and implementation clearer.

Minum follows semantic versioning.

The design process

1. Make it work.
2. Make it right.
3. Make it fast.

This project represents thousands of hours of an experienced practitioner experimenting with maintainability, performance, and pragmatic simplicity.

Getting Started

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

Maven

Maven central repository

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

Features:

<details><summary>Secure TLS 1.3 HTTP/1.1 web server</summary> <p> A web server is the program that enables sending your data over the internet. </p> </details> <details><summary>In-memory database with disk persistence</summary> <p> A database is necessary to store data for later use, such as user accounts. Our database stores all its data in memory, but writes it to the disk as well. The only time data is read from disk is at database startup. There are benefits and risks to this approach. </p> </details> <details><summary>Server-side templating</summary> <p> A template is just a string with areas you can replace, and the template processor renders these quickly. For example, here is a template: "Hello {{ name }}". If we provide the template processor with that template and say that "name" should be replaced with "world", it will do so. </p> </details> <details><summary>Logging</summary> <p> Logs are text that the program outputs while running. There can be thousands of lines output while the program runs. </p> </details> <details><summary>Testing utilities</summary> <p> The test utilities are mostly ways to confirm expectations, and throw an error if unmet. </p> </details> <details><summary>HTML parsing</summary> <p> Parsing means to interpret the syntax and convert it to meaningful data for later analysis. Because web applications often have to deal with HTML, it is a valuable feature in a minimalist framework like this one. </p> </details> <details><summary>Background queue processor</summary> <p> Across the majority of the codebase, the only time code runs is when a request comes in. The background queue processor, however, can continue running programs in parallel. </p> </details>

Size Comparison:

Compiled size: 209 kilobytes.

Lines of production code (including required dependencies)

| Minum | Javalin | Spring Boot | |-------|---------|-------------| | 6,486 | 141,048 | 1,085,405 |

See a size comparison in finer detail

Performance:

Performance is a feature. On your own applications, collect performance metrics at milestones, so that trends and missteps are made apparent.

One of the benefits of minimalism combined with test-driven development is that finding the bottlenecks and making changes is easier, faster, and safer.

• Web request handling: Plenty fast, depending on network and server configuration. details here
• Database updates/reads: 2,000,000 per second. See "test_Performance" in DbTests.java. O(1) reads (does not increase in time as database size increases) by use of indexing feature.
• Template processing:
  • 100,000 per second for large complex templates.

See a Minum versus Spring performance comparison

Documentation:

• Development handbook
• Javadocs
• Code coverage
• Mutation test report
• Test run report
• Project site report

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.

<hr>

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.

<hr>

Memoria project

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

<hr>

Restaurants

Restaurants is a prototype project to provide a customizable ranked list of restaurants.

<hr>

Alternate database

This is a project which uses a SQL database called H2, and which shows how a user might go about including a different database than the one built-in.

Code samples

The following code samples help provide an introduction to the features.

• Database
• Logging
• HTML Parser
• Endpoints
• Templates
• User Input
• Testing
• Output
• Helpful utilities

Database

Instantiating a new database:

There are two database options - the older simpler database, or the new DbEngine2 database. They have nearly identical interfaces and external behaviors, but the DbEngine2 database reads and writes to disk magnitudes faster than its sibling Db. It is the recommended database to use going forward.

Here is how you instantiate the faster database:

AbstractDb<Foo> db = new DbEngine2<>(foosDirectory, context, new Foo());

Here is the simpler database:

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

The Minum database keeps its data and processing primarily in memory but persists to the disk. Data is only read from disk at startup.

There are pros and cons to this design choice: on the upside, it's very fast and the data stays strongly typed. On the downside, it does not make the same guarantees as ACID-compliant databases. Also, an ill-considered application design could end up using too much memory.

On the Memoria project, the risks and benefits were carefully considered, and so far it has worked well.

Users are free to pick any other database they desire (See "Al