DEV Community: mohamed anas charkaoui

The "Invisible" Server Bug: What Building a Bare-Metal Java Server Taught Me About I/O

mohamed anas charkaoui — Sun, 12 Jul 2026 01:00:27 +0000

This is the first article in a series where I document building an HTTP server in Java from raw sockets — no frameworks, no Tomcat, no Spring. Just java.net and whatever mistakes I make along the way.

Where I Started

Week one looked like this — everything crammed into a single main() method:

public class App {
    public static void main(String[] args) {
        try (ServerSocket sc = new ServerSocket()) {
            sc.bind(new InetSocketAddress("127.0.0.1", 8080));
            System.out.println("the server is ready");

            while (true) {
                Socket client = sc.accept();
                System.out.println("Server accepted a new client. Processing...");

                PrintWriter pw = new PrintWriter(
                    new BufferedWriter(
                        new OutputStreamWriter(client.getOutputStream())
                    )
                );
                pw.println("HTTP/1.1 200 OK");
                pw.println("Content-Type: text/html");
                pw.println("Content-Length: 53");
                pw.println();
                pw.println("<html><body><h1>Bare-Metal is UP!</h1></body></html>");
                pw.flush();
                pw.close();
                client.close();
            }
        } catch (Exception e) {
            System.out.println("error in the main method with :" + e);
        }
    }
}

Ugly, but it worked. One accepted connection, one hand-built response, flush() and close() both there, done.

Then I started splitting this apart — pulling connection handling into its own ClientWorker class, and request parsing into a Dispatcher, to get ready for a thread pool and actual routing. That refactor is where I hit a bug that took me a genuinely embarrassing amount of time to find.

The Bug

The new ClientWorker looked, at a glance, like a clean translation of the same logic:

BufferedReader br = new BufferedReader(
    new InputStreamReader(client.getInputStream())
);
String line;
if ((line = br.readLine()) != null) {
    String res = Dispatcher.Rout(line);
    PrintWriter pw = new PrintWriter(
        new BufferedWriter(
            new OutputStreamWriter(client.getOutputStream())
        )
    );
    pw.println(res);
}
client.close();

The code compiled. It ran. It accepted connections without a single exception. And the browser just spun on a blank screen, waiting forever for a response that never came.

The bug: I wrote the response with pw.println(res), then closed the raw client socket directly — never touching pw again. In the Week 1 version, flush() and close() were both sitting right there, two lines below the write. Somewhere in pulling the logic apart into a separate class, they quietly didn't make the trip.

To explain why forgetting two lines could freeze an entire response, I need to explain why this three-layer nested constructor exists in the first place:

PrintWriter pw = new PrintWriter(
    new BufferedWriter(
        new OutputStreamWriter(socket.getOutputStream())
    )
);

The "Over-Engineered" Syntax That's Actually Genius

The first time you see this in Java, it looks like a joke. Three constructors nested inside each other just to write text to a socket? Why isn't there one simple NetworkWriter class that does all of this?

It turns out this isn't over-engineering — it's the direct, deliberate answer to a problem that would otherwise collapse a codebase under its own weight. To see why, you have to understand what I/O actually costs, and what happens if you try to avoid that cost the naive way.

What I/O Actually Means

I/O stands for Input/Output. In code, an I/O operation is any action that forces your program to step outside the memory the operating system assigned to it.

When your program touches a local variable, it's operating inside fast, safe RAM that belongs to it. But the moment you want to read a file off disk or send a packet over the network, your program has to hand off to the OS kernel and talk to actual hardware. That handoff — crossing from your process into the kernel and back — is slow. Not "slightly slower," but orders of magnitude slower than working in RAM. This is where Java's design problem starts.

The Nightmare of Class Explosion

Say you want a utility that writes data to a file. You build FileByteWriter. It works.

A week later, someone wants to write text Strings instead of raw bytes. Now you need FileStringWriter too.

A few days after that, the app needs to write to a network socket instead of a file. Now you need SocketByteWriter and SocketStringWriter. You're at four classes for two features.

Now imagine product wants encryption (SSL). And compression (GZIP). And buffering for performance. If you keep building one dedicated class per combination, your class count grows exponentially — roughly 2ⁿ for n independent features. You'd eventually need hundreds of classes like EncryptedBufferedSocketStringWriter, and half your day would go to remembering which one you actually need.

This is called class explosion, and it's exactly what Java's I/O designers built around using the Decorator Pattern.

Java's Actual Blueprint: Three Layers You Stack

Instead of one class per combination, Java splits I/O into small, single-purpose pieces you compose like building blocks:

1. The Connection Layer — the actual physical endpoint, like File or Socket. It only knows how to move raw bytes in or out.

2. The Transport Layer — converts between representations. A raw socket only understands bytes; wrapping it in OutputStreamWriter gives you a translator that turns your characters into the bytes the network actually needs.

3. The Performance/Feature Layer — the decorators you stack on top. This is where BufferedWriter comes in.

Sending data one byte at a time over a network is like sending a semi-truck to deliver a single kitchen sponge — technically it works, but you're paying for a full trip every single time. A buffer is a small warehouse: it holds your data in RAM until there's a full truckload (commonly 8KB), then ships it all in one trip.

Then PrintWriter goes on top of all of that, giving you convenient methods like println() so you can write clean text without thinking about any of the layers underneath.

Where My Bug Actually Came From

Here's the part that isn't in most tutorials: the buffer doesn't know your response is "done." It only knows two things — "am I full?" and "was I told to flush?" That's it.

My response was small — a few hundred bytes, nowhere close to the 8KB buffer threshold — so the buffer just sat there, holding my data, waiting for either more bytes to arrive or an explicit signal that would never come. Then I closed the raw socket directly, out from under the writer. The connection went away with the data still sitting in the buffer. From the browser's side, nothing had errored — it just never received a response, so it kept waiting.

The fix was two lines:

pw.flush();
pw.close();

flush() tells the buffer "stop waiting for a full truckload, ship what you have right now." close() does something similar internally — a PrintWriter's close() flushes automatically before it shuts down — which is why in real code you'll often see people rely on close() alone, or better, a try-with-resources block, since either one guarantees the flush happens even if an exception is thrown partway through. What actually broke my server was closing the socket directly and never touching the writer at all, so neither of those safety nets ever ran.

Why the "Ugly" Syntax Is Actually a Feature

The nested-constructor syntax isn't hiding this complexity from you — it's making every layer, and every decision, visible and swappable. Want to drop buffering because you need every byte to go out immediately (like a live streaming protocol)? Delete one line. Want to add compression? Wrap one more layer around the existing ones, and nothing else in your code has to change.

That's the Open-Closed Principle in practice: the system is open for extension, but closed for modification. You don't touch Java's stream, buffering, or formatting logic — you just compose new pieces on top of what's already there.

What looks like over-engineering on first read is actually one of the more resilient, composable designs in the standard library — and understanding why it's built that way is what turned an invisible, silent bug into two obvious lines of code.

*This is Part 1 of a series on building an HTTP server in Java from scratch. Part 2 covers what happened when I hit this same server with concurrent requests — and why "just add more RAM" doesn't fix what actually breaks. Code for this series is on GitHub at https://github.com/AnasMAC/java-baremetal-server/releases/tag/v1-blocking-server.

Scaling Architecture, Not Hardware: Building a Multi-Threaded NIO Web Server from Scratch in Java

mohamed anas charkaoui — Sun, 12 Jul 2026 00:40:29 +0000

Why doesn't throwing more CPU and RAM at your server solve your latency issues under heavy load?

In this article, we will see why buying a more powerful server will not increase the performance of your blocking I/O app. Instead of just throwing hardware at the problem, we are going to get our hands dirty with systems architecture and build a custom, multi-threaded Non-Blocking I/O (NIO) HTTP server in Java from scratch. And yes, we will talk about the painful concurrency bugs you run into when you try to build the parts a framework normally hides from you.

This is Part 2 of a series where I document building an HTTP server in Java from raw sockets. Part 1 covers a buffering bug in blocking I/O — this one covers what happened under concurrent load and the NIO rewrite that followed.

Chapter 1: The Trap of Blocking I/O (BIO)

Imagine you are at a restaurant where one waiter is assigned to one table. When the waiter takes your order, they walk to the kitchen and stand there staring at the wall while the chef cooks your meal. While that waiter is waiting, no other customer in the restaurant can be served. If the restaurant gets busy, the owner's only solution is to hire more waiters. Eventually, the kitchen gets overcrowded, salaries skyrocket, and the restaurant runs out of physical space.

This is exactly how Blocking I/O (BIO) works.

In a classic blocking Java server (using ServerSocket), every incoming TCP connection gets its own dedicated OS thread. When a thread tries to read from a socket, it blocks:

// The thread is now frozen here until the client decides to send something
int bytesRead = inputStream.read(buffer);

If the client has slow internet, or if your database query takes a few seconds, that thread is just sitting there wasting resources.

If you think, "I'll just buy a bigger server with more RAM and spin up more threads," here is the catch:

Thread Overhead: In Java, each thread takes up about 1MB of memory for its stack. If you have 5,000 active connections, that is roughly 5GB of RAM gone just to keep idle threads sleeping.
Context Switching: The CPU spends more time swapping between thousands of threads than actually running your code.
Bottlenecks: Your database connection pool or OS files will max out long before your fancy CPU even hits 50%.

The Non-Blocking (NIO) Solution

Instead of one waiter per table, imagine a single waiter with a pager system. The waiter takes orders from multiple tables, sends them to the kitchen, and moves on to serve other people. When a dish is ready, the kitchen buzzes the pager. The waiter only works when there is an actual event to handle.

Chapter 2: Migrating from BIO to Java NIO

When we migrate from Blocking I/O to Non-Blocking I/O in Java, we swap out our core networking objects:

ServerSocket becomes ServerSocketChannel: We can configure it to be non-blocking by calling ssc.configureBlocking(false). This lets us listen for connection events without freezing the thread.
Socket becomes SocketChannel: Reads and writes become non-blocking. Calling read() returns immediately with whatever data is currently ready.

To understand how this works, we need to talk about Channels, Buffers, and Selectors.

1. Channels (SocketChannel)

Think of a channel as a two-way pipe. Unlike standard blocking streams, you can tell it to be non-blocking. If you ask it to read, it returns immediately: it gives you the bytes if they are there, a 0 if the network is still loading, or -1 if the client closed the connection.

2. Buffers (ByteBuffer)

You cannot read directly from a channel. You must read from the channel into a buffer, and write from a buffer into the channel.

A ByteBuffer is not like a normal array or list. It has three pointers that you have to manage manually:

capacity: The size of the buffer.
position: Where you are currently reading or writing.
limit: The boundary of how far you can go.

Because there is only one pointer (position) for both reading and writing, you have to tell the buffer when you are switching roles by calling flip() and clear().

To show you what is actually happening under the hood, here is a simple conceptual class:

public class MockByteBuffer {
    private byte[] array;
    private int position = 0;
    private int limit;
    private int capacity;

    public MockByteBuffer(int capacity) {
        this.capacity = capacity;
        this.limit = capacity;
        this.array = new byte[capacity];
    }

    // 1. Write mode: putting data into the buffer
    public void put(byte b) {
        if (position < limit) {
            array[position++] = b;
        }
    }

    // 2. Flip: Switch from WRITE mode to READ mode
    public void flip() {
        limit = position; // Limit becomes the end of written data
        position = 0;     // Reset pointer to start reading from the beginning
    }

    // 3. Clear: Switch from READ mode back to WRITE mode
    public void clear() {
        position = 0;     // Reset pointer to the start for writing
        limit = capacity; // Restore limit to full capacity
    }
}

When you write bytes into the buffer (like receiving data from a socket), the position moves forward.
Before you read those bytes, you call flip(). This resets the position to 0 and sets the limit to where you stopped writing, so you don't read empty space.
Once you are done reading, you call clear() to reset the pointer so you can write into it again.

3. Selectors

The Selector is the brain of NIO. It is the multiplexer that monitors multiple channels.

You register your channel to a selector and tell it what you are interested in (like SelectionKey.OP_READ for incoming data or SelectionKey.OP_ACCEPT for new connections).
You call selector.select(), which blocks your thread only until one of those events happens.
Then you get the selectedKeys() and process them one by one.

Chapter 3: Architecting the Event Loop (Boss & Workers)

For our server, we are going to implement a simple Boss-Worker model:

The Boss Thread (NioServer.java): Its only job is to run a selector that listens for new client connections (OP_ACCEPT). When a client connects, it accepts the channel, sets it to non-blocking, and hands it over to the worker pool.
The Worker Pool (SelectorsPool.java): A pool of threads, each running its own selector. They handle the reading (OP_READ) and processing for the clients assigned to them.

Here is how the Boss Thread sets up the ServerSocketChannel and binds it:

public void start() {
    try (ServerSocketChannel ssc = ServerSocketChannel.open()) {
        ssc.bind(new InetSocketAddress(host, port));
        ssc.configureBlocking(false); // Make it non-blocking

        Selector selector = Selector.open();
        ssc.register(selector, SelectionKey.OP_ACCEPT); // Listen only for accepts

        while (true) {
            selector.select(); // Block until a client connects
            Set<SelectionKey> keys = selector.selectedKeys();
            Iterator<SelectionKey> iter = keys.iterator();

            while (iter.hasNext()) {
                SelectionKey key = iter.next();
                if (key.isAcceptable()) {
                    SocketChannel sc = ssc.accept();
                    sc.configureBlocking(false);
                    // Pass the channel to our worker pool!
                    pool.execute(sc); 
                }
                iter.remove();
            }
        }
    } catch (Exception e) {
        System.out.println("Error in the nio server: " + e);
    }
}

Chapter 4: Processing the Data (NioWorker.java)

Once the client is registered to a worker's selector, the worker thread reads the bytes and routes the request:

public class NioWorker implements Runnable {
    private SocketChannel sc;
    private Dispatcher dispatcher;

    public NioWorker(SocketChannel client, Dispatcher dispatcher) {
        this.sc = client;
        this.dispatcher = dispatcher;
    }

    @Override
    public void run() {
        ByteBuffer buffer = ByteBuffer.allocate(1024);
        StringBuilder sb = new StringBuilder();
        try {
            int r;
            // Read bytes from channel into buffer
            while ((r = sc.read(buffer)) > 0) {
                buffer.flip(); // Switch to read mode
                sb.append(new String(buffer.array(), 0, buffer.limit(), StandardCharsets.UTF_8));
                buffer.clear(); // Clear buffer for next write
            }

            String message = sb.toString();

            // Route the request and write the response back
            String res = dispatcher.rout(message.split("\n")[0]);
            ByteBuffer resBuffer = ByteBuffer.wrap(res.getBytes());
            sc.write(resBuffer);
            sc.close(); 
        } catch (Exception e) {
            System.out.println("Error in the worker: " + e);
        }
    }
}

Known simplification: this version reads once per worker invocation and assumes the full request arrived in that pass — it doesn't yet register back with a selector to wait for more OP_READ events if a client's request is split across multiple TCP packets. That's a real gap between this code and the "worker has its own selector" model described above, and it's on my list to fix in a later revision rather than something I'm claiming is solved here.

Chapter 5: The Hidden Trap of Custom NIO

Building your own web server is great for learning, but it exposes you to subtle bugs that modern frameworks hide. Let's look at one of the biggest headaches you will encounter:

The Selector Registration Deadlock

Look at how the Boss hands a socket to a worker's selector:

// Boss Thread:
sc.register(workerSelector, SelectionKey.OP_READ);

And look at how the Worker is waiting:

// Worker Thread:
workerSelector.select(); // Blocks here waiting for network activity

In Java, selector.select() locks the selector's key set. At the same time, calling socketChannel.register(selector, ...) from the Boss thread tries to get that exact same lock.

If the worker thread is blocked inside select(), the Boss thread will hang forever on .register(), and your entire server will freeze.

The Fix

You have to wake up the selector before registering the channel:

workerSelector.wakeup();
sc.register(workerSelector, SelectionKey.OP_READ);

Note: Because wakeup() and register() are not atomic, production frameworks like Netty use a concurrent queue to enqueue registration tasks and run them directly inside the worker thread loop, avoiding this lock contention entirely.

Benchmarks: Proving the Architecture

Same test every time — an artificial 5-second delay in the request handler to simulate a slow database call, hit with ab -n 10 -c 10 http://localhost:8080/:

Server	Total time (10 requests, concurrency 10)	Requests/sec
1 thread, blocking (no pool)	50.015s	0.20
1 NIO worker + boss	50.015s	0.20
10 NIO workers + boss	10.009s	1.00

The 1-worker NIO server and the 1-thread blocking server land on almost identical numbers — which makes sense, since one worker means every request still queues behind the last one, regardless of blocking or non-blocking I/O underneath. The moment you add nine more workers, ten requests that would've taken 50 seconds serially finish in about 10 — a 5x improvement from spreading load across workers, not from any change in hardware.

(I also ran this with a 10-thread blocking pool instead of one thread, which is the more common real-world setup — I don't have that exact run saved, so I'm leaving it out rather than guessing at a number. Worth noting though: since 10 threads can serve 10 concurrent requests at once, that version should land close to the single request's 5-second delay rather than 50 seconds — the same idea as the NIO version, just paying for it in threads instead of workers.)

Conclusion & Takeaways

Writing a bare-metal web server teaches you three main things:

Architecture > Hardware: Buying a bigger server is useless if your system is bottlenecked by blocking threads.
NIO is Hard: Managing buffers, selector states, and thread deadlocks manually is highly complex.
Appreciate the Ecosystem: This project makes you appreciate why frameworks like Netty, Tomcat, and Spring Boot exist. They handle the low-level heavy lifting so you can focus on writing actual business features.