API Reference · Structs

ABI discipline

Structs are ABI

The layout is frozen: new fields may only be appended at the tail, never reordered or renamed (stated outright in the xsbase.h comments). Scripts access fields by name; binaries stay compatible across versions.

Views are not modified

XS_HostInfo / XS_ServerInfo / XS_HttpReq / XS_StreamConn are host-owned views — reading fields is safe, writing them is undefined.

Lifetimes

Host views are protected by their server lease; HttpReq / StreamConn views are valid within a callback. To keep one, Retain it (topology) or copy it (requests).

XS_HostInfo (host info, 15 fields)

Field	Type	Notes
`Enabled`	bool	whether enabled
`Name`	const char*	host name (unique within the server)
`Host`	const char*	domain bindings (semicolon-separated); the http/ws routing key
`Path`	const char*	asset / script root (absolute path)
`DevLang`	const char*	c / static / application-defined
`DevFile`	const char*	script entry path
`TlsCA / TlsCert / TlsKey`	const char*	host-level certificate paths → the SNI selector's data source
`State`	XS_RunState	run state (see the enums reference)
`Runtime`	void*	this generation's script runtime (opaque; do not dereference)
`Server`	XS_ServerInfo*	back pointer: from one host, reach the whole topology
`Custom`	xvalue*	everything this host holds beyond the preset fields
`DevInc / DevLib`	const char*	script include / library directories (tail-appended fields)
`RuntimeLock`	void*	the host-side generation-switch lock (opaque; tail-appended field)

XS_ServerInfo (server info, 20 fields)

Field	Type	Notes
`Enabled`	bool	whether enabled
`Class`	const char*	"http" \| "ws" \| "tcp" \| "udp" \| "custom" \| "app"
`Name`	const char*	globally unique name (the xsServerFind key)
`IP / Port`	const char* / uint16	plaintext listen endpoint
`TLS / PortTLS / IPTLS`	bool / uint16 / const char*	TLS endpoint; IPTLS reuses IP by default
`Backlog`	uint32	passed through to the xrt listen configuration
`RecvLimit`	size_t	stream read cap (passed through to xrt)
`DefaultHost`	XS_HostInfo*	always present; an unmatched vhost falls back here
`HostCount / Hosts`	uint32 / XS_HostInfo**	the vhost list (excluding DefaultHost)
`State`	XS_RunState	run state
`Runtime`	void*	server-level runtime (opaque)
`Engine`	struct xnetengine*	the process-level engine (the starting point for custom-class applications)
`Custom`	xvalue*	server-level non-preset fields
`Generation`	void*	owner of the server generation's lifecycle (tail-appended)
`ConfigOwner`	void*	owner of the dynamic configuration snapshot (tail-appended)
`PortBound`	uint16	the actually bound port (tail-appended): a fixed port = Port; the app class with `port:0` auto-assign = the OS-assigned value (Port is written back too, keeping endpoint identity consistent with the script view); 0 = not bound yet

XS_HttpReq (HTTP request view, 6 fields)

typedef struct { xnetstream* tcp; /* exactly one of tcp/tls is non-null */ xtlsstream* tls; /* the full xrt stream/send API is usable directly */ const xhttp1head* head; /* holds MethodCode; field view valid within the callback */ xhttp1body* body; /* framing state machine: fixed-length / chunked / close */ const XS_HostInfo* host; XS_ServerInfo* server; } XS_HttpReq;

head's raw method and field views are valid only within a callback (the ring buffer gets reused); body is consumed incrementally by xrtHttp1BodyRead. The fields of the native xrt structs (xhttp1head / xhttp1body) are covered in xrt · the http1 reference.

XS_StreamConn (TCP connection view, 2 fields)

typedef struct XS_StreamConn { xnetstream* tcp; /* plaintext TCP transport */ xtlsstream* tls; /* TLS transport (tcps) */ } XS_StreamConn;

Exactly one side is non-null: use the matching send API on the non-null side; under tcps, writing to tcp directly, bypassing tls, is forbidden. The connection's lifetime is held by the host driver (Accept takeover → registry → Close destruction) — the application never calls Destroy.

XS_ReloadResult (reload result, 5 fields)

Field	Type	Notes
`Id`	XS_ReloadId (uint64)	the intent ID (Submit's return value)
`State`	XS_ReloadState	one of the seven states (see the enums reference)
`Revision`	uint64	content fingerprint of the immutable input snapshot; includes the script fingerprint when there is no config input
`Target[160]`	char[]	target description (server / host name)
`Message[256]`	char[]	result message (the failure reason)

This is the only result struct whose storage the application owns (received as a stack out-parameter); for queries see xsReloadQuery.

Structs Reference