Basking in the Warmth of Assembly: Building a Web Server from Scratch in ARM64

In an era dominated by high-level frameworks, cloud-native abstractions, and the rising tide of AI-generated code, there is something profoundly rebellious about writing a web server in assembly. It is a task that is, by any modern commercial standard, "meaningless"—yet it is precisely this lack of utility that makes it a masterclass in craftsmanship and a journey into the heart of the machine.

Enter ymawky (pronounced yuh maw kee), a static-file web server written entirely in ARM64 assembly for macOS. Developed by imtomt, ymawky is a syscall-only, no-libc, fork-per-connection server. It doesn't rely on the comforts of a standard library; instead, it communicates directly with the kernel, handling everything from socket management to file I/O by hand.

The Architecture of ymawky

At its core, ymawky is designed to be a functional, albeit minimalist, static server. While it avoids the complexity of server-side scripting, it implements a surprising array of HTTP features that one wouldn't expect from a hand-written assembly project.

Core Capabilities

• HTTP Method Support: It handles GET, PUT, DELETE, OPTIONS, and HEAD requests.
• Advanced File Handling: The server supports % hex encoding for filenames and includes smart path traversal detection to prevent ../ attacks while allowing multiple periods in filenames (e.g., ohwell...txt).
• Range Requests: It supports Range: bytes= headers, enabling full, suffix, and open-ended ranges—making it fully capable of supporting video scrubbing.
• Atomic Uploads: PUT requests are handled atomically by writing to a temporary file (www/.ymawky_tmp_<pid>) and renaming it only upon successful completion, preventing corrupted files from overwriting existing data.
• MIME Type Detection: It includes a comprehensive mapping of file extensions to MIME types, covering everything from .wasm and .webp to .epub and .flac.

Safety and Security

Writing in assembly is often synonymous with memory vulnerabilities, but the author implemented several guardrails to harden the server:

• Path Constraints: Rejects paths exceeding PATH_MAX (4096 bytes) or those that don't contain a path within the first 16 bytes.
• Symlink Protection: Uses O_NOFOLLOW_ANY to reject paths containing symlinks.
• DoS Mitigation: To prevent Slowloris-style attacks, the server enforces a 10-second timeout for receiving data and a total 10-second limit for the full header.
• Process Limiting: A MAX_PROCS limit (default 256) prevents the server from exhausting the system's PID space.

The Challenge of Portability

One of the most common questions raised by the community was why a project written in assembly—the "universal language" of the CPU—is limited to macOS. The answer lies in the gap between the Instruction Set Architecture (ISA) and the Application Binary Interface (ABI).

While the ARM64 instructions are the same, the way the software interacts with the operating system differs wildly between macOS and Linux. As the author notes in the implementation details:

• Syscall Mechanics: macOS uses x16 for the syscall number and svc #0x80, while Linux uses x8 and svc #0.
• Error Handling: macOS sets the carry flag on error and puts errno in x0; Linux returns a negative value in x0.
• Process Management: The fork() system call returns different values in the child process across the two platforms.
• Relocation: Mach-O (macOS) and ELF (Linux) use different relocation operators for addressing memory.

This highlights a critical lesson in systems programming: the CPU is only half the story; the kernel is the other.

The "Hacker" Spirit in the Age of AI

The release of ymawky sparked a nostalgic and philosophical discussion among the Hacker News community. Many viewed the project as a return to the "hacker" ethos—building things not for profit or efficiency, but for the sheer joy of mastery.

"I mourn the death of a human artform. Ten years ago, I would have kowtowed to someone elite enough to build something like this. Today, I just think, 'how long would LLMs have taken to write this?'"

Conversely, others argued that such projects are more valuable than ever as a counterweight to the "vibe-coded" world of AI. One commenter likened it to a Minecraft map: while AI can build a city in seconds, the value of a hand-crafted art project is incomparable.

Technical Takeaways

For those looking to use ymawky as a learning tool, it serves as a practical example of how to build abstractions without a high-level language. By utilizing macros and procedures, the author created a "meta-language" on top of assembly to manage the verbosity of the ARM64 ISA.

It also serves as a reminder of the fragility of syscalls. As one community member pointed out, syscalls on macOS are not guaranteed to be stable, which is why languages like Go eventually shifted to calling libSystem.dylib instead of invoking the kernel directly.

Ultimately, ymawky is a testament to the fact that the most rewarding projects are often the ones that serve no purpose other than to prove that it can be done.