Web Server API

The web server library is a fast, compact web server designed for management web applications and serving device data.

The web server does not attempt to offer ALL HTTP features and functions. Rather, it aims to implement only the required core of HTTP/1.1 and thus deliver a tiny, fast, secure embedded web server that is exceptionally good at serving single page web applications and device data.

The web server supports: HTTP/1.0, HTTP/1.1, TLS/SSL, Action routines, user authentication, sessions, cookie management, request logging, and security sandboxing. The web server uses 80K of code and will run in 200K RAM (without TLS).

The core web services include:

HTTP/1.1 protocol engine
TLS 1.3 support
Non-blocking socket communications
Multiple listen endpoints
Flexible configuration via a web.json5 file
Request routing with access control
Binding URLs to C functions for dynamic content rendering
Serve static files
Configurable redirections
Transfer encoding filter
Session and cookie management
Authentication and User management
File upload
JSON parser and query engine
Sandbox limits and timeouts
Paralelism via fiber coroutines

Extensions

Web	Embedded web server.
WebUpload	File upload structure.

Functions

void	webAddAccessControlHeader(Web *web)
	Add an Access-Control-Allow-Origin response header for the request host name.
void	webAddAction(WebHost host, cchar prefix, WebProc fn, cchar *role)
	Add an action callback for a URL prefix.
void	webAddHeader(Web web, cchar key, cchar *fmt, ...)
	Add a header to the request response.
WebHost *	webAllocHost(Json *config)
	Allocate a new host object.
bool	webAuthenticate(Web *web)
	Authenticate a user.
ssize	webBufferUntil(Web web, cchar until, ssize limit, bool discard)
	Read data and buffer until a given pattern or limit is reached.
bool	webCan(Web web, cchar role)
	Test if a user possesses the required role.
WebSession *	webCreateSession(Web *web)
	Create a login session.
char *	webDate(char *buf, time_t when)
	Convert a time to a date string.
char *	webDecode(char *str)
	Decode a string using punycode.
void	webDestroySession(Web *web)
	Destroy the web session object.
char *	webEncode(cchar *uri)
	Encode a string using punycode.
int	webError(Web web, int status, cchar fmt, ...)
	Respond to the request with an error.
void	webExtendTimeout(Web *web, Ticks timeout)
	Extend the request timeout.
ssize	webFinalize(Web *web)
	Finalize response output.
void	webFreeHost(WebHost *host)
	Free a host object.
cchar *	webGetDocs(WebHost *host)
	Get the web documents directory for a host.
cchar *	webGetHeader(Web web, cchar key)
	Get a request header value.
char *	webGetHostName(Web *web)
	Get the host name of the endpoint serving the request.
bool	webGetNextHeader(Web web, cchar pkey, cchar *pvalue)
	Get the next request header in sequence.
WebSession *	webGetSession(Web *web, int create)
	Get the session state object for the current request.
cchar *	webGetSessionVar(Web web, cchar name, cchar *defaultValue)
	Get a session variable.
cchar *	webGetStatusMsg(int status)
	Get a status message corresponding to a HTTP status code.
cchar *	webGetVar(Web web, cchar name, cchar *defaultValue)
	Get a request variable value from the request form/body.
int	webInit(void)
	Initialize the web module.
bool	webIsAuthenticated(Web *web)
	Test if the user has been authenticated.
void	webLogin(Web web, cchar username, cchar *role)
	Login a user by creating session state.
void	webLogout(Web *web)
	Logout a user and remove the user login session.
int	webNetError(Web web, cchar msg, ...)
	Close the current request and issue no response.
char *	webNormalizePath(cchar *path)
	Normalize a URL path.
char *	webParseCookie(Web web, char name)
	Parse a cookie header string and return a cookie value.
int	webParseUrl(Web *web)
	Parse a URL into its components.
ssize	webRead(Web web, char buf, ssize bufsize)
	Read request body data.
ssize	webReadUntil(Web web, cchar until, char *buf, ssize bufsize)
	Read request body data until a given pattern is reached.
void	webRedirect(Web web, int status, cchar uri)
	Redirect the client to a new URL.
void	webRemoveSessionVar(Web web, cchar name)
	Remove a session variable.
void	webRemoveVar(Web web, cchar name)
	Remove a request variable value.
ssize	webSendFile(Web *web, int fd)
	Write a file response.
void	webSetContentLength(Web *web, ssize len)
	Set the content length for the response.
void	webSetHook(WebHost *host, WebHook hook)
	Define a request hook.
cchar *	webSetSessionVar(Web web, cchar name, cchar *fmt, ...)
	Set a session variable name value.
void	webSetStatus(Web *web, int status)
	Set the response HTTP status code.
cchar *	webSetVar(Web web, cchar name, cchar *value)
	Set a request variable value.
int	webStartHost(WebHost *host)
	Start listening for requests on the host.
void	webStopHost(WebHost *host)
	Stop listening for requests on the host.
void	webTerm(void)
	Initialize the web module.
bool	webValidatePath(cchar *uri)
	Validate a URL.
ssize	webWrite(Web web, cvoid buf, ssize bufsize)
	Write response data.
ssize	webWriteFmt(Web web, cchar fmt, ...)
	Write string response data.
int	webWriteHeaders(Web *web)
	Write request response headers.
int	webWriteResponse(Web web, int status, cchar fmt, ...)
	Write a response.

Typedefs

WebAction	Action function bound to a URL prefix.
WebHook	WebHook callback procedure.
WebHost	Web host structure.
WebProc	WebAction callback procedure.
WebRedirect	Site wide redirection.
WebRoute	Routing object to match a request against a path prefix.

Defines

#define	WEB_CHUNK_DATA 2
	Start of chunk data.
#define	WEB_CHUNK_START 1
	Start of a new chunk.
#define	WEB_HOOK_ACTION 5
	Request an action.
#define	WEB_HOOK_CONNECT 1
	New socket connection.
#define	WEB_HOOK_DISCONNECT 2
	New socket connection.
#define	WEB_HOOK_END 8
	End of request.
#define	WEB_HOOK_ERROR 7
	Request error.
#define	WEB_HOOK_NOT_FOUND 6
	Document not found.
#define	WEB_HOOK_RUN 4
	Ready to run request or run custom request processing.
#define	WEB_HOOK_START 3
	Start new request.

Web

Embedded web server.

Description:: The web server requires the use of fibers from the portable runtime.

API Stability:: Evolving.

Fields:

uint	authChecked	Authentication has been checked.
uint	authenticated	User authenticated and roleId defined.
RBuf *	body	Receive boday buffer transferred from rx.
uint	chunked	Receive transfer chunk encoding state.
uint	close	Should the connection be closed after the request completes.
uint	complete	Is the request complete.
int64	conn	Web connection sequence.
cchar *	contentDisposition	Receive content disposition header value.
cchar *	contentType	Receive content type header value.
cchar *	cookie	Request cookie string.
uint	creatingHeaders	Are headers being created.
Ticks	deadline	Timeout deadline for when the next I/O must complete.
char *	error	Error string for any request errors.
uint	exists	Does the requested resource exist.
cchar *	ext	Request URL extension.
RFiber *	fiber	Original owning fiber.
uint	formBody	Is the current request a POSTed form.
char *	hash	Request URL reference portion.
WebHost *	host	Owning host object.
uint	http10	Is the current request a HTTP/1.0 request.
uint	jsonBody	Is the current request a POSTed json request.
WebListen *	listen	Listening endpoint.
cchar *	method	Request method in upper case.
cchar *	mime	Request mime type based on the extension.
uint	moreBody	More response body to trace.
cchar *	origin	Request origin header.
char *	path	Path portion of the request url.
cchar *	protocol	Request HTTP protocol. Set to HTTP/1.0 or HTTP/1.1.
char *	query	Request URL query portion.
Json *	qvars	Parsed query variables.
char *	redirect	Response redirect location. Used to set the Location header.
int64	reuse	Keep-alive reuse counter.
cchar *	role	Authorized role.
int	roleId	Index into roles for the authorized role.
WebRoute *	route	Matching route for this request.
RBuf *	rx	Receive data buffer.
RBuf *	rxHeaders	Request received headers.
ssize	rxLen	Receive content length (including chunked requests).
Offset	rxRemaining	Amount of data to receive in request.
uint	secure	Has secure listening endpoint.
struct WebSession *	session	Session state.
int	signature	Index into signature definition for this request.
time_t	since	Value of the if-modified-since value in seconds since epoch.
Ticks	started	Time when the request started.
uint	status	Request response HTTP status code.
RBuf *	trace	Packet trace buffer.
RBuf *	tx	Write data buffer.
RHash *	txHeaders	Output headers.
ssize	txLen	Transmit content length.
Offset	txRemaining	Transmit data remaining to send.
char *	url	Full request url.
cchar *	username	Username.
Json *	vars	Parsed request variables.
uint	wroteHeaders	Have the response headers been written.

void webAddAccessControlHeader (Web *web)

Add an Access-Control-Allow-Origin response header for the request host name.

Parameters:

web	Web object.

API Stability:: Evolving.

void webAddAction (WebHost *host, cchar *prefix, WebProc fn, cchar *role)

Add an action callback for a URL prefix.

Description:: An action routine is a C function that is bound to a set of URLs. The action routine will be invoked for URLs that match the leading URL prefix.

Parameters:

host	Host object.
prefix	Leading URL prefix to associate with this action.
fn	Function to invoke for requests matching this URL.
role	Required user role for the action.

API Stability:: Evolving.

void webAddHeader (Web *web, cchar *key, cchar *fmt, ...)

Add a header to the request response.

Parameters:

web	Web object.
key	HTTP header name.
fmt	Format string for the header value.
...	Format arguments.

API Stability:: Evolving.

WebHost * * webAllocHost (Json *config)

Allocate a new host object.

Description:: After allocating, the host may be started via webStartHost.

Parameters:

config

JSON configuration for the host.

Returns:: A host object.

API Stability:: Evolving.

bool webAuthenticate (Web *web)

Authenticate a user.

Description:: The user is authenticated if required by the selected request route.

Parameters:

web	Web request object.

Returns:: True if the route does not require authentication or the user is authenticated successfully.

API Stability:: Evolving.

ssize webBufferUntil (Web *web, cchar *until, ssize limit, bool discard)

Read data and buffer until a given pattern or limit is reached.

Description:: This reads the data into the buffer, but does not return the data or consume it.

Parameters:

web	Web object.
until	Pattern to read until. Set to NULL for no pattern.
limit	Number of bytes of data to read.
discard	If true, discard data. Used to consume remaining body data of a request that is not required.

Returns:: The number of bytes read into the buffer. Return zero if no bytes read and negative for errors.

API Stability:: Evolving.

bool webCan (Web *web, cchar *role)

Test if a user possesses the required role.

Parameters:

web	Web request object.
role	Required role.

Returns:: True if the user has the required role.

API Stability:: Evolving.

char * * webDate (char *buf, time_t when)

Convert a time to a date string.

Parameters:

buf	Buffer to hold the generated date string.
when	Timestamp to convert.

Returns:: A reference to the buffer.

API Stability:: Evolving.

char * * webDecode (char *str)

Decode a string using punycode.

Description:: The string is converted in-situ.

Parameters:

str	String to decode.

Returns:: The original string reference.

API Stability:: Evolving.

char * * webEncode (cchar *uri)

Encode a string using punycode.

Description:: The string is converted in-situ.

Parameters:

uri	Uri to encode.

Returns:: An allocated, escaped URI. Caller must free.

API Stability:: Evolving.

int webError (Web *web, int status, cchar *fmt, ...)

Respond to the request with an error.

Description:: This responds to the request with the given HTTP status and body data.

Parameters:

web	Web object.
status	HTTP response status code.
fmt	Body data to send as the response. This is a printf style string.
...	Body response arguments.

Returns:: Zero if successful.

API Stability:: Evolving.

void webExtendTimeout (Web *web, Ticks timeout)

Extend the request timeout.

Description:: Request duration is bounded by the timeouts.request and timeouts.inactivity limits. You can extend the timeout for a long running request via this call.

Parameters:

web	Web object.
timeout	Timeout in milliseconds use for both the request and inactivity timeouts for this request.

API Stability:: Evolving.

ssize webFinalize (Web *web)

Finalize response output.

Description:: This routine will call webWrite(web, NULL, 0);.

Parameters:

web	Web object.

API Stability:: Evolving.

void webFreeHost (WebHost *host)

Free a host object.

Parameters:

host	Host object.

API Stability:: Evolving.

cchar * * webGetDocs (WebHost *host)

Get the web documents directory for a host.

Description:: This is configured via the web.documents configuration property.

Parameters:

host	Host object.

Returns:: The web documents directory.

API Stability:: Evolving.

cchar * * webGetHeader (Web *web, cchar *key)

Get a request header value.

Parameters:

web	Web object.
key	HTTP header name. Case does not matter.

Returns:: Header value or null if not found.

API Stability:: Prototype.

char * * webGetHostName (Web *web)

Get the host name of the endpoint serving the request.

Description:: This will return the WebHost name if defined, otherwise it will use the listening endpoint. If all else fails, it will use the socket IP address.

Parameters:

web	Web object.

Returns:: Allocated string containing the host name. Caller must free.

API Stability:: Evolving.

bool webGetNextHeader (Web *web, cchar **pkey, cchar **pvalue)

Get the next request header in sequence.

Description:: Used to iterate over all headers.

Parameters:

web	Web object.
pkey	Pointer to key. Used to pass in the last key value and return the next key. Set to NULL initially.
pvalue	Pointer to header value.

Returns:: True if more headers to visit.

API Stability:: Prototype.

cchar * * webGetStatusMsg (int status)

Get a status message corresponding to a HTTP status code.

Parameters:

status

HTTP status code.

Returns:: A status message. Caller must not free.

API Stability:: Evolving.

cchar * * webGetVar (Web *web, cchar *name, cchar *defaultValue)

Get a request variable value from the request form/body.

Parameters:

web	Web object.
name	Variable name.
defaultValue	Default value to return if the variable is not defined.

Returns:: The value of the variable or the default value if not defined.

API Stability:: Evolving.

int webInit (void )

Initialize the web module.

Description:: Must call before using Web.

API Stability:: Evolving.

bool webIsAuthenticated (Web *web)

Test if the user has been authenticated.

Parameters:

web	Web request object.

Returns:: True if the user has been authenticated.

API Stability:: Evolving.

void webLogin (Web *web, cchar *username, cchar *role)

Login a user by creating session state.

Assumes the caller has already authenticated and authorized the user

Parameters:

web	Web request object.
username	User name.
role	Requested role.

API Stability:: Evolving.

void webLogout (Web *web)

Logout a user and remove the user login session.

Parameters:

web	Web request object.

API Stability:: Evolving.

int webNetError (Web *web, cchar *msg, ...)

Close the current request and issue no response.

Description:: This closes the request connection and issues no response. It should be used when a request is received that indicates the connection is compromised.

Parameters:

web	Web object.
msg	Message to the error log. This is a printf style string.
...	Message response arguments.

Returns:: Zero if successful.

API Stability:: Evolving.

char * * webNormalizePath (cchar *path)

Normalize a URL path.

Description:: Normalize a path to remove "./", "../" and redundant separators. This does not make an absolute path and does not map separators or change case. This validates the path and expects it to begin with "/".

Parameters:

path	Path string to normalize.

Returns:: An allocated path. Caller must free.

API Stability:: Evolving.

char * * webParseCookie (Web *web, char *name)

Parse a cookie header string and return a cookie value.

Parameters:

web	Web object.
name	Cookie name to extract.

Returns:: The cookie value or NULL if not defined.

API Stability:: Evolving.

int webParseUrl (Web *web)

Parse a URL into its components.

Description:: The parsed components are defined in the Web object including the path, extension (ext),.

Parameters:

web	Web object.

Returns:: Zero if successful.

API Stability:: Evolving.

ssize webRead (Web *web, char *buf, ssize bufsize)

Read request body data.

Description:: This routine will read the body data and return the number of bytes read. This routine will block the current fiber if necessary. Other fibers continue to run.

: Must only be called from a fiber.

Parameters:

web	Web object.
buf	Data buffer to read into.
bufsize	Size of the buffer.

Returns:: The number of bytes read. Return < 0 for errors and 0 when all the body data has been read.

API Stability:: Evolving.

ssize webReadUntil (Web *web, cchar *until, char *buf, ssize bufsize)

Read request body data until a given pattern is reached.

Description:: This routine will read the body data and return the number of bytes read. This routine will block the current fiber if necessary. Other fibers continue to run.

: Must only be called from a fiber.

Parameters:

web	Web object.
until	Pattern to read until. Set to NULL for no pattern.
buf	Data buffer to read into.
bufsize	Size of the buffer.

Returns:: The number of bytes read. Return < 0 for errors and 0 when all the body data has been read.

API Stability:: Internal.

void webRedirect (Web *web, int status, cchar *uri)

Redirect the client to a new URL.

: Must only be called from a fiber.

Parameters:

web	Web object.
status	HTTP status code. Must set to 301 or 302.
uri	URL to redirect the client toward.

API Stability:: Evolving.

void webRemoveVar (Web *web, cchar *name)

Remove a request variable value.

Parameters:

web	Web object.
name	Variable name.

API Stability:: Evolving.

ssize webSendFile (Web *web, int fd)

Write a file response.

Description:: This routine will read the contents of the open file descriptor and send as a response. This routine will block the current fiber if necessary. Other fibers continue to run.

: Must only be called from a fiber.

Parameters:

web	Web object.
fd	File descriptor for an open file or pipe.

Returns:: The number of bytes written.

API Stability:: Evolving.

void webSetContentLength (Web *web, ssize len)

Set the content length for the response.

Parameters:

web	Web object.
len	Content length.

API Stability:: Evolving.

void webSetHook (WebHost *host, WebHook hook)

Define a request hook.

Description:: The request hook will be invoked for important request events during the lifecycle of processing the request.

Parameters:

host	WebHost object.
hook	Callback hook function.

API Stability:: Evolving.

void webSetStatus (Web *web, int status)

Set the response HTTP status code.

Parameters:

web	Web object.
status	HTTP status code.

API Stability:: Evolving.

cchar * * webSetVar (Web *web, cchar *name, cchar *value)

Set a request variable value.

Parameters:

web	Web object.
name	Variable name.
value	Value to set.

Returns:: The value defined in the environment. Caller must NOT free the result.

API Stability:: Evolving.

int webStartHost (WebHost *host)

Start listening for requests on the host.

: Must only be called from a fiber.

Parameters:

host	Host object.

Returns:: Zero if successful.

API Stability:: Evolving.

void webStopHost (WebHost *host)

Stop listening for requests on the host.

: Must only be called from a fiber.

Parameters:

host	Host object.

API Stability:: Evolving.

void webTerm (void )

Initialize the web module.

API Stability:: Evolving.

bool webValidatePath (cchar *uri)

Validate a URL.

Description:: Check a url for invalid characters.

Parameters:

uri

Url path.

Returns:: True if the url contains only valid characters.

API Stability:: Evolving.

ssize webWrite (Web *web, cvoid *buf, ssize bufsize)

Write response data.

Description:: This routine will block the current fiber if necessary. Other fibers continue to run. Writing a null buffer or zero bufsize indicates there is no more output. The webFinalize API is a convenience call for this purpose.

: Must only be called from a fiber.

Parameters:

web	Web object.
buf	Buffer of data to write.
bufsize	Size of the buffer to write.

Returns:: The number of bytes written.

API Stability:: Evolving.

ssize webWriteFmt (Web *web, cchar *fmt, ...)

Write string response data.

Description:: This routine will block the current fiber if necessary. Other fibers continue to run.

: Must only be called from a fiber.

Parameters:

web	Web object.
fmt	Printf style message string.
...	Format arguments.

Returns:: The number of bytes written.

API Stability:: Evolving.

int webWriteHeaders (Web *web)

Write request response headers.

Description:: This will write the HTTP response headers. This writes the supplied headers and any required headers if not supplied. This routine will block the current fiber if necessary. Other fibers continue to run.

: Must only be called from a fiber.

Parameters:

web	Web object.

Returns:: The number of bytes written.

API Stability:: Evolving.

int webWriteResponse (Web *web, int status, cchar *fmt, ...)

Write a response.

Description:: This routine writes a single plain text response in one API. It will block the current fiber if necessary. Other fibers continue to run. This will set the Content-Type header to text/plain.

: Must only be called from a fiber.

Parameters:

web	Web object.
status	HTTP status code.
fmt	Printf style message string.
...	Format arguments.

Returns:: The number of bytes written.

API Stability:: Evolving.

WebUpload

File upload structure.

Fields:

char *	clientFilename	Client side name of the file.
char *	contentType	Content type.
int	fd	File descriptor used while writing the upload content.
char *	filename	Local (temp) name of the file.
char *	name	Symbolic name for the upload supplied by the client.
ssize	size	Uploaded file size.

Functions

WebSession * * webCreateSession (Web *web)

Create a login session.

Parameters:

web	Web request object.

Returns:: Allocated session object.

API Stability:: Evolving.

void webDestroySession (Web *web)

Destroy the web session object.

Description:: Useful to be called as part of the user logout process.

Parameters:

web	Web request object.

API Stability:: Prototype.

WebSession * * webGetSession (Web *web, int create)

Get the session state object for the current request.

Parameters:

web	Web request object.
create	Set to true to create a new session if one does not already exist.

Returns:: Session object.

API Stability:: Evolving.

cchar * * webGetSessionVar (Web *web, cchar *name, cchar *defaultValue)

Get a session variable.

Parameters:

web	Web request object.
name	Session variable name.
defaultValue	Default value to return if the variable does not exist.

Returns:: Session variable value or default value if it does not exist.

API Stability:: Evolving.

void webRemoveSessionVar (Web *web, cchar *name)

Remove a session variable.

Parameters:

web	Web request object.
name	Session variable name.

API Stability:: Evolving.

cchar * * webSetSessionVar (Web *web, cchar *name, cchar *fmt, ...)

Set a session variable name value.

Parameters:

web	Web request object.
name	Session variable name.
fmt	Format string for the value.
...	Format args.

Returns:: The value set for the variable. Caller must not free.

API Stability:: Evolving.

Typedefs

typedef int(* WebHook) (struct Web *web, int event).

WebHook callback procedure.

Parameters:

web	Web object.
event	ID of the event.

API Stability:: Evolving.

typedef void(* WebProc) (struct Web *web).

WebAction callback procedure.

Parameters:

web	Web object.

API Stability:: Evolving.

WebAction

Action function bound to a URL prefix.

API Stability:: Evolving.

Fields:

WebProc	fn	Function to invoke.
char *	match	Path prefix.
char *	role	Role to invoke action.

WebHost

Web host structure.

Description:: The web host defines a web server and its configuration. Multiple web hosts can be created.

Fields:

RList *	actions	Ordered list of configured actions.
Json *	config	Web server configuration for this host.
ssize	connections	Number of active connections.
bool	freeConfig	Config is allocated and must be freed.
int	headers	Base ID for headers in config.
WebHook	hook	Web notification hook.
int	inactivityTimeout	Timeout for inactivity on a connection.
cchar *	index	Index file to use for directory requests.
RList *	listeners	Listening endpoints for this host.
int64	maxBody	Max size of POST request.
int64	maxConnections	Max number of connections.
int64	maxHeader	Max header size.
int64	maxSessions	Max number of sessions.
int64	maxUpload	Max size of file upload.
RHash *	methods	Default HTTP methods verbs.
RHash *	mimeTypes	Mime types indexed by extension.
cchar *	name	Host name to use in canonical redirects.
int	parseTimeout	Timeout while parsing a request.
RList *	redirects	Ordered list of redirections.
int	requestTimeout	Total request timeout.
int	roles	Base ID of roles in config.
RList *	routes	Ordered list of configured routes.
cchar *	sameSite	Cookie same site property.
REvent	sessionEvent	Session timer event.
RHash *	sessions	Client session state.
int	sessionTimeout	Inactivity timeout for session state.
RHash *	users	Hash table of users.
RList *	webs	Active web requests for this host.

WebRedirect

Site wide redirection.

API Stability:: Evolving.

Fields:

cchar *	from	Original URL path.
int	status	Redirection HTTP status code.
cchar *	to	Target URL.

WebRoute

Routing object to match a request against a path prefix.

API Stability:: Evolving.

Fields:

bool	exact	Exact match vs prefix match. If trailing "/" in route.
cchar *	handler	Request handler (file, action).
char *	match	Matching URI path pattern.
RHash *	methods	HTTP methods verbs.
cchar *	redirect	Redirection if not authorized.
cchar *	role	Required user role.
bool	stream	Stream request body.
cchar *	trim	Portion to trim from path.