Anatomy of a minimal app: two files make a service

Overview

4.1 Intro

Most frameworks' "hello world" crosses five layers of abstraction: entry registration → route matching → middleware chain → context object → response serialization. XServer's philosophy is the opposite: hand you the protocol's minimal facts first — the parsed request head, transport pointers, the framing state machine — then step aside. So the minimal app is genuinely minimal:

Now the line-by-line dissection of these two facts. They are taken from demo-single's real files, with the business parts trimmed away.

4.2 xs.json line by line

{
    "services": [
        {
            "enabled": true,          /* service switch */
            "class": "http",          /* protocol class: http/ws/tcp/udp/custom */
            "name": "demo",           /* globally unique name, the key for xsServerFind */
            "ip": "127.0.0.1",
            "port": 9080,
            "host_default": {         /* default host: fallback when no vhost matches */
                "enabled": true,
                "name": "app",
                "path": "wwwroot",    /* static asset root */
                "devlang": "c",       /* c = TCC script; static = pure static */
                "devfile": "main.c"   /* script entry (relative to the config directory) */
            }
        }
    ]
}

What just happened: this config declares a chain of facts — listen for HTTP on 127.0.0.1:9080; requests matching no other vhost go to the default host app; app's static root is wwwroot; the business logic is main.c. Any wrong field (a typo in class, an out-of-range port) fails startup before config loaded, naming the exact field — the full field table is in the guide · configuration, and volume 2 covers it field by field.

4.3 main.c line by line

#include <xsbase.h>   /* contract header: pulls in xrt_decl.h and libtcc.h (all in the VFS) */

/* called once after this generation loads (assembly / reload control thread) */
static void ServiceInit(XS_HostInfo* pHost)
{
    printf("[%s] service init\n", pHost->Name);
}

/* once per request (engine worker threads, may run concurrently) */
static XS_RequestResult RequestProc(XS_HttpReq* pReq)
{
    /* unhandled requests → fall back to the static layer (wwwroot), else 404 */
    return XS_FALLBACK;
}

/* called when this generation retires (GC thread, at most once per lifetime) */
static void ServiceUnit(XS_HostInfo* pHost)
{
    printf("[%s] service unit\n", pHost->Name);
}

What just happened:

• #include <xsbase.h> needs no installation — the header, together with the full xrt declarations, lives in the exe's VFS and TCC reads it directly;
• the host looks up ServiceInit / RequestProc / ServiceUnit by symbol name (static doesn't hide them — symbols are visible in TCC's memory mode); all are optional;
• the three functions map exactly onto the generation's three moments from chapter 3: birth / service / retirement.

Run it (output from a real machine):

$ ./xs
[xs] config loaded: .../xs.json (1 servers)
[xs] script loaded: .../main.c (0.4 KB gen 1)
[app] service init
[xs] server 'demo' http bound on 127.0.0.1:9080
[xs] running, press Ctrl+C to stop

$ curl -s http://127.0.0.1:9080/
<!DOCTYPE html> ...          /* wwwroot/index.html — the static layer took over / */

4.4 The three-way return

RequestProc's return value is not "success / failure" but who owns the rest of this request's life:

4.5 Static-layer fallback

After XS_FALLBACK the host's static layer takes over: it looks for files under the host's path (wwwroot here) — GET returns content, HEAD headers only — with percent-decoding, directory indexes (index.html by default) and dot-files denied by default. That is how / got index.html above. The static layer's four knobs (custom headers, error pages, directory indexes, deny_dotfiles) open up in volume 2, chapter 10.

This "script first, static fallback" combination means you write no code for static assets — and no rewrite rules for dynamic routes either.

4.6 Contract

• Symbols: contract symbols are looked up by name, all optional — a host that exports no RequestProc is simply a pure static site.
• Ownership: XS_HttpReq and its inner pointers are valid only within the callback stack; a bare return is risk-free here, but once you start using views, chapter 3's rules apply.
• Response: returning XS_OK means "the complete response has been written" — head + body (except HEAD) are your responsibility.

Common mistakes

static XS_RequestResult
RequestProc(XS_HttpReq* pReq)
{
    if ( path is mine ) ...;
    /* missing return: leftover randomly hits a state */
}

static XS_RequestResult
RequestProc(XS_HttpReq* pReq)
{
    if ( path is mine ) return XS_OK;
    return XS_FALLBACK;   /* explicit fallthrough */
}

xrtNetStreamSend(pReq->tcp,
    "HTTP/1.1 200 OK\n\nhello", 22);
return XS_OK;   /* incomplete message, no length */

/* build the head with xrtHttp1ResponseWrite
 * (chapter 15 wraps it fully) */

ConnSend(pReq, head, n);
if ( !hasBody ) return XS_FALLBACK;

/* decide before writing:
 * either a complete response + XS_OK,
 * or write nothing + FALLBACK */

Exercises