A library for creating HTTP servers with WebSocket support using Alusus Language. This library is based on civetweb.
You can add it to the project using APM:
import "Apm.alusus";
Apm.importPackage("Alusus/Http@0.3");
import "Srl/Console.alusus";
import "Srl/String.alusus";
import "Srl/Memory.alusus";
import "Apm.alusus";
Apm.importPackage("Alusus/Http@0.3");
module TestModule {
use Srl;
func start() {
// define a pointer to the context of the server.
// the server is executing the given function on the port 8080
def context: ptr[Http.Context] = Http.startServer(callbackRequest~ptr, "8080");
Console.print("Server is listening on port 8080\nhttp://localhost:8080/\nPress enter to close server.");
// wait for a key press from the user to stop the server
Console.getChar();
// when we reach here the user was pressed a key
// so we should close the server
Http.stopServer(context);
Console.print("Server closed.\nPress enter to exit.");
Console.getChar();
};
// the function we want the server to execute
func callbackRequest(connection: ptr[Http.Connection]): Int {
// define a variable for holding connection request information.
def requestInfo: ptr[Http.RequestInfo] = Http.getRequestInfo(connection);
// define a variable to store the content we want to show
def content: array[Char, 1024];
// store a simple html code in `content`
String.assign(content~ptr, "<h1>Welcome from Alusus</h1><p> you are in \"%s\"", requestInfo~cnt.localUri);
// write the data through the given connection
// this data represent some information about the request in addition to the content.
Http.print(connection, "HTTP/1.1 200 OK\r\n");
Http.print(connection, "Content-Type: text/html\r\n");
Http.print(connection, "Content-Length: %d\r\n\r\n", String.getLength(content~ptr));
Http.print(connection, content~ptr);
return 1;
};
};
TestModule.start();
This library now includes comprehensive WebSocket support for real-time bidirectional communication. See the complete WebSocket Documentation for detailed information.
// Register WebSocket handler
Http.setWebSocketHandler(
context,
"/websocket",
onConnect~ptr,
onReady~ptr,
onData~ptr,
onClose~ptr
);
// Send text message
Http.writeTextToWebSocket(connection, "Hello WebSocket!");
For a complete working example, see websocket_server.alusus.
class Context{
def stopFlag: int;
};
This class holds the information about the context.
def stopFlag: int
Whether to stop the event loop.
class Callbacks{
def beginRequest: RequestCallback;
def endRequest: ptr[func (connection: ptr[Connection], replyStatusCode: Int)];
def logMessage: ptr[func (connection: ptr[Connection], message: CharsPtr): Int];
def logAccess: ptr[func (connection: ptr[Connection], message: CharsPtr): Int];
def initSsl: ptr[func (sslContext: ptr[Void], userData: ptr[Void]): Int];
def connectionClose: ptr[func (connection: ptr[Connection]): Void];
def httpError: ptr[func (connection: ptr[Connection], status: Int, msg: ptr[array[Char]]): Int];
def initContext: ptr[func (context: ptr[Context]): Void];
def exitContext: ptr[func (context: ptr[Context]): Void];
def initThread: ptr[func (context: ptr[Context], threadType: Int): Void];
};
This class holds the main callbacks that can be used with http protocol. Each callback is a pointer to a function that the server executes.
def beginRequest: RequestCallback
The server calls it when starting a request.
0: if the request was not processed.1~99: server let the function process the request.
def endRequest: ptr[func (connection: ptr[Connection], replyStatusCode: Int)]
Called by the server when a request on a given connection ends.
def logMessage: ptr[func (connection: ptr[Connection], message: CharsPtr): Int]
Used to log a message on a given connection.
0: The server should call the default routine to log the message.- Non-zero value: Message logging is done by the callback and default logger shouldn't be called.
def logAccess: ptr[func (connection: ptr[Connection], message: CharsPtr): Int]
Used to log an access message on a given connection.
0: The server should call the default logger.- Non-zero value: The server should not call the default logger.
def initSsl: ptr[func (sslContext: ptr[Void], userData: ptr[Void]): Int]
Called when initializing SSL.
0: Server should configure SSL certificate.1: SSL certificate is configured and the server should do nothing.-1: SSL initialization failed.
def connectionClose: ptr[func (connection: ptr[Connection]): Void]
Called when a given connection is closed.
def httpError: ptr[func (connection: ptr[Connection], status: Int, msg: ptr[array[Char]]): Int]
Called when an error occurs on a given connection with the status and a message.
0when the function sends the error page.- Non-zero value when the function does not send the error page and server should do that instead.
def initContext: ptr[func (context: ptr[Context]): Void]
Called to initialize the context of a given thread.
def exitContext: ptr[func (context: ptr[Context]): Void]
Called to exit the context.
def initThread: ptr[func (context: ptr[Context], threadType: Int): Void]
Called to initialize a thread with a given context, for a given type.
class RequestInfo {
def requestMethod: CharsPtr;
def requestUri: CharsPtr;
def localUri: CharsPtr;
def httpVersion: CharsPtr;
def queryString: CharsPtr;
def remoteUser: CharsPtr;
def remoteAddr: array[Char, 48];
def contentLength: Int[64];
def remotePort: Int;
def isSsl: Int;
def userData: ptr[Void];
def connData: ptr[Void];
def numberHeaders: Int;
def httpHeaders: array[Header, 64];
};
This class holds the information about a request.
def requestMethod: CharsPtr
Request type, for example: GET.
def requestUri: CharsPtr
The URI of the request.
def localUri: CharsPtr
The local URI of the request, used for requests on the same server.
def httpVersion: CharsPtr
HTTP protocol version used in the request.
def queryString: CharsPtr
Request parameters in the request.
def remoteUser: CharsPtr
The remote user we deal with.
def remoteAddr: array[Char, 48]
IP address of the remote user.
def contentLength: Int[64]
Request body length in bytes, -1 if nothing specified.
def remotePort: Int
The port used on the remote user machine.
def isSsl: Int
Whether the connection uses SSL.
def userData: ptr[Void]
Custom user data that is passed to startServer.
def connData: ptr[Void]
Data specific to the connection.
def numberHeaders: Int
Request headers number.
def httpHeaders: array[Header, 64]
Request headers.
class Header {
def name: CharsPtr;
def value: CharsPtr;
};
This class holds the information about request header.
def name: CharsPtr
Header name, which is the key.
def value: CharsPtr
Header value under the key name.
class Connection {
def requestInfo: ptr[RequestInfo];
def context: ptr[Context];
def ssl: ptr;
def clientSslContext: ptr;
def client: ptr;
def connectionBirthTime: Int;
def requestTime: Int;
def numberBytesSent: int[64];
def contentLen: int[64];
def consumedContent: int[64];
def isChunked: int;
def chunkRemainder: word[64];
def buf: CharsPtr;
def pathInfo: CharsPtr;
def mustClose: int;
def inErrorHandler: int;
def internalError: int;
def bufSize: int;
def requestLen: int;
def dataLen: int;
def statusCode: int;
def throttle: int;
def lastThrottleTime: int;
def lastThrottleBytes: int[64];
def mutex: int[64];
};
This class holds the information about the connection.
def requestInfo: ptr[RequestInfo]
Information about the request sent with the connection.
def context: ptr[Context]
Information about connection context.
def ssl: ptr
SSL descriptor.
def clientSslContext: ptr
Client context on SSL.
def client: ptr
The client connected to this connection.
def connectionBirthTime: Int
The time of creating the connection (wall time).
def requestTime: Int
The time of creating the connection (server time).
def numberBytesSent: int[64]
Number of bytes sent to the client.
def contentLen: int[64]
The value of "Content-length" header.
def consumedContent: int[64]
Number of bytes read from content.
def isChunked: int
Is data transfering chuncked? Takes one of those values:
0: Transfer is not chuncked.1: Transfer is not chuncked, and there is still some data to read.2: Transfer is not chuncked, and no data left to read.
def chunkRemainder: word[64]
Data not have been read yet from the last chunck.
def buf: CharsPtr
Buffer for recieved data.
def pathInfo: CharsPtr
Path info part of the URI.
def mustClose: int
Should we close the connection?
def inErrorHandler: int
Whether the errors are being handled.
def internalError: int
Whether an error occured while processing the request.
def bufSize: int
Buffer size.
def requestLen: int
Total size in bytes of the request and the headers in the buffer.
def dataLen: int
Total size in bytes of the data in the buffer.
def statusCode: int
Reply status code of the HTTP protocol.
def throttle: int
Throttle value.
def lastThrottleTime: int
Last time throttled data was sent.
def lastThrottleBytes: int[64]
The bytes recieved in this second.
def mutex: int[64]
Used for locking when we need to access synced data safely.
@expname[mg_set_user_connection_data]
func setUserConnectionData (connection: ptr[Connection], data : ptr[Void]);
Registers a data pointer to a connection.
connection: pointer to the connection you want to register data to.userData: pointer for data you want to register.
Calling this function again on the same connection pointer overwrites any previously registered data pointer.
You can retrieve the registered data by calling getUserConnectionData;
@expname[mg_get_user_connection_data]
func getUserConnectionData (connection: ptr[Connection]) : ptr[Void];
This function returns the data pointer that was previously registered for a connection via setUserConnectionData.
connection: pointer to the connection you want to get the data that was registered to.
Returns null if no data has been registered yet for this connection.
@expname[mg_start]
func startServer(callbacks: ptr[Callbacks], userData: ptr, options: ptr[CharsPtr]): ptr[Context]
func startServer(callback: RequestCallback, userData: ptr, options: ref[Srl.Array[CharsPtr]]): ptr[Context]
func startServer(callback: RequestCallback, options: ref[Srl.Array[CharsPtr]]): ptr[Context]
func startServer(callback: RequestCallback, userData: ptr, optsCount: Int, opts: ...CharsPtr): ptr[Context]
func startServer(callback: RequestCallback, optsCount: Int, opts: ...CharsPtr): ptr[Context]
func startServer(callback: RequestCallback, userData: ptr, port: CharsPtr): ptr[Context]
func startServer(callback: RequestCallback, port: CharsPtr): ptr[Context]
Initialize and start the server. Returns a pointer to the server's context, or null in case of initialization failure. In case a callback is not present in the list, the server will use a default one.
callbacks: The list of callbacks used to determine the behaviour of the server and how it processes requests.callback: Callback that the server will execute when receiving a request.userData: Optional custom user data passed tostartServer.options: Options related to server initialization, like port number. Can be a raw pointer or an array.optsCount: Number of options inopts.opts: Options related to server initialization, like port number.port: Port number that the server listens to.
@expname[mg_stop]
func stopServer(context: ptr[Context]): Void
Close the server and release any acquired resources. Waits until all threads have finished, then releases resources and closes the server.
context: Pointer to the server's context to close.
@expname[mg_read]
func read(connection: ptr[Connection], buffer: ptr, bufferSize: Int): Int
Read data from the connection in binary format and store it in buffer. Returns the number of bytes read on success, 0 when the connection is closed by a peer, or a negative value when there is no more data to read.
connection: Connection to read data from.buffer: The buffer to store data in.bufferSize: Max size in bytes of data we can store inbuffer.
@expname[mg_write]
func write(connection: ptr[Connection], buffer: CharsPtr, bufferSize: Int): Int
Send data through a given connection. Returns the number of sent bytes on success, or -1 on failure.
connection: Connection to send through.buffer: Buffer holding the data to send.bufferSize: The size in bytes ofbuffer.
@expname[mg_printf]
func print(connection: ptr[Connection], format: CharsPtr, ...any): Int
Send formatted messages through a given connection. Returns the number of bytes sent on success, 0 when the connection is closed, or -1 on error.
connection: Connection to send through.format: Message's format....any: Arguments needed to fillformat.
@expname[mg_send_file]
func sendFile(connection: ptr[Connection], fileName: CharsPtr): Void
Send a file through a connection. Adds the required headers automatically.
connection: The connection to send through.fileName: The name of the file to send.
@expname[mg_get_cookie]
func getCookie(cookiesString: CharsPtr, cookieName: CharsPtr, outCookieContent: CharsPtr, outCookieSize: Word[64]): Int
Get the value of a specific variable from a specific cookie. Returns the size of the cookie in bytes on success, -1 when the cookie is not found, or -2 on failure to store in the buffer.
cookiesString: Cookie name.cookieName: Name of the variable incookiesString.outCookieContent: Buffer to store the content of the variable in.outCookieSize: The size in bytes ofoutCookieContent.
@expname[mg_get_header]
func getHeader(connection: ptr[Connection], headerName: CharsPtr): CharsPtr
Get a header from a given connection. Returns a pointer to the header value or null on failure.
connection: The connection to get a header from.headerName: The name of the header to retrieve.
@expname[mg_get_request_info]
func getRequestInfo(connection: ptr[Connection]): ptr[RequestInfo]
Get the information about a request through a given connection. Returns a pointer to request information.
connection: The connection to get request information from.
@expname[mg_get_var]
func getVariable(data: CharsPtr, dataSize: Int, variableName: CharsPtr, outVariable: CharsPtr, outVariableSize: Int): Int
Get the value of a given variable passed to the server through POST (body) or GET (URI). Returns the size in bytes of the variable value on success, -1 when the variable is not found, or -2 on failure to store in the buffer.
data: The data the variable was passed through (POST body or GET URI).dataSize: Size in bytes ofdata.variableName: The name of the variable to retrieve.outVariable: Output buffer to store the value of the variable.outVariableSize: The size in bytes ofoutVariable.
Copyright (C) 2026 Sarmad Abdullah
This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). See the COPYING and COPYING.LESSER files for details.