Introduction: what XServer is and how to read this book

Overview

One-sentence definition first:

XServer is a single-file C application server: one executable (compiler and runtime embedded) plus one plain C source directory is a complete, hot-reloadable server-side deployment.

Three keywords in that sentence map to the three story lines of this book: single file (runtime and toolchain fully embedded — volume 2 covers build and delivery), C source directory (the application is the source itself, not a prebuilt artifact — volumes 1 and 3 cover how to write it), and hot reload (edit code with zero downtime — volume 4 dives deep).

1.1 What XServer is

Traditional C server development goes "write code → compile → link → deploy the binary → restart", and every business change walks the whole pipeline. XServer folds that pipeline into the runtime: what you place on the target machine is a source directory as the deployment artifact; xs.exe compiles your C code into native machine code with the embedded TCC compiler at startup and on every hot reload, and runs it in-process.

/* Traditional C server */
myapp/  →  build pipeline  →  myapp.exe + dependency list  →  install deps on target  →  restart

/* xs */
myapp/  =  xs.exe (the only binary; compiler/runtime/SDK embedded)
        + main.c + modules/ + wwwroot/ + db/ (source is the deployment)
        →  copy to deploy, edit source to hot reload

This is not a toy "C as scripting" scheme but a deliberate engineering trade: scripts are trusted native code, in-process with the host, calling the host's 3,030 xrt APIs by address — no interpreter overhead, no FFI boundary; a function call is just a function call. The price is no sandbox: XServer targets operator-controlled trusted deployments and does not accept untrusted third-party scripts (this boundary is explored in chapter 44, volume 5).

Underneath sits xrt — a 310k-line in-house runtime (TLS 1.2/1.3, HTTP/1.1, WebSocket, a five-backend event loop, coroutines, memory debugging). This book does not re-teach xrt: where xrt fundamentals matter, the "further reading" box at the chapter end links to the matching chapters of the xrt book.

1.2 Compared with alternatives

The difference in one sentence: other stacks manage "the runtime" and "your code" as two separate things; XServer packs them into the same file, the same process, and the same lifecycle.

1.3 Roadmap of the book

• Volume 1 (ch. 01–06): mental model and toolchain. The three essential chapters are 03 (mental model), 04 (minimal app) and 06 (debugging).
• Volume 2 (ch. 07–13): xs.json is the single assembly surface — every field, constraint and error semantic.
• Volume 3 (ch. 14–25): development patterns for the four protocol classes; pick yours.
• Volume 4 (ch. 26–31): hot reload from "can trigger it" to "understand the semantics" — rollback, handover, zero leaks.
• Volume 5 (ch. 32–43): the extension system, deployment and ops, security boundaries, and three end-to-end projects.

1.4 The chapter template contract

All 51 chapters follow the same eight-part structure. Chapter 1 turns the template into a contract — any later chapter that violates it counts as a chapter defect, not a style choice:

Every chapter ends with two fixed boxes: APIs covered in this chapter (linking to this book's reference pages with entry counts) and xrt further reading (linking to the xrt book). Every code block tagged "verified on a real machine" shows genuinely captured output — including unforgeable details like dynamic ports and real timestamps.

1.5 Reader paths

Common mistakes

curl http://127.0.0.1:9080/__xs/status
/* expecting a built-in admin endpoint → 404 */

/* Write admin routes in your own script:
 * inspection / reload endpoints are ordinary business routes */

Exercises