HTTPServer
Inherits: Object
HTTP server singleton for creating REST APIs and serving content.
Description
HTTPServer is a singleton that provides a complete HTTP server implementation with support for REST APIs, static file serving, and Server-Sent Events (SSE). It uses a route-based system where you register callbacks for specific HTTP methods and path patterns.
The server runs in a background thread and handles multiple concurrent connections. Routes can include path parameters using the {variable} syntax.
# Start server
HTTPServer.listen(8080)
# Register a route with path parameters
HTTPServer.register_route("GET", "/api/users/{id}", func(req, res):
var user_id = req.get_path_param("id")
res.set_json({"user_id": user_id})
)
# Register a POST route
HTTPServer.register_route("POST", "/api/data", func(req, res):
var data = req.parse_json_body()
res.set_status(201)
res.set_json({"received": data})
)
Tutorials
Methods
void |
|
void |
close_sse_connection(connection_id: int) |
void |
enable_directory_listing(enable: bool) |
get_active_sse_connections() const |
|
get_cors_origin() const |
|
get_max_request_size() const |
|
get_port() const |
|
get_static_directory() const |
|
is_cors_enabled() const |
|
is_directory_listing_enabled() const |
|
is_listening() const |
|
listen(port: int, bind_address: String = "*", use_tls: bool = false, tls_key: String = "", tls_cert: String = "") |
|
void |
register_route(method: String, path: String, callback: Callable) |
send_sse_data(connection_id: int, data: String) |
|
send_sse_event(connection_id: int, event: String, data: String) |
|
void |
set_cors_enabled(enabled: bool) |
void |
set_cors_origin(origin: String) |
void |
set_max_request_size(size: int) |
void |
set_static_directory(path: String) |
void |
stop() |
void |
unregister_route(method: String, path: String) |
Signals
server_error(error_message: String) 🔗
Emitted when a server error occurs.
sse_connection_closed(connection_id: int) 🔗
Emitted when a Server-Sent Events connection is closed, either by the client or by calling close_sse_connection().
sse_connection_opened(connection_id: int, path: String, headers: Dictionary) 🔗
Emitted when a new Server-Sent Events connection is established. The connection_id can be used with send_sse_event() to send events to this client.
Method Descriptions
void clear_routes() 🔗
Removes all registered routes from the server.
void close_sse_connection(connection_id: int) 🔗
Closes an active Server-Sent Events connection with the given connection_id. Emits sse_connection_closed.
void enable_directory_listing(enable: bool) 🔗
Enables or disables directory listing for static file serving. When enabled, directories will show an index of files.
Array get_active_sse_connections() const 🔗
Returns an array of connection IDs for all active Server-Sent Events connections.
String get_cors_origin() const 🔗
Returns the current CORS (Cross-Origin Resource Sharing) origin setting.
int get_max_request_size() const 🔗
Returns the maximum allowed request size in bytes.
Returns the port number the server is listening on, or 0 if not listening.
String get_static_directory() const 🔗
Returns the directory path used for serving static files.
bool is_cors_enabled() const 🔗
Returns true if CORS headers are being added to responses.
bool is_directory_listing_enabled() const 🔗
Returns true if directory listing is enabled for static files.
Returns true if the server is currently listening for connections.
Error listen(port: int, bind_address: String = "*", use_tls: bool = false, tls_key: String = "", tls_cert: String = "") 🔗
Starts the HTTP server on the specified port and bind_address. Returns @GlobalScope.OK on success.
If use_tls is true, the server will use HTTPS. In this case, tls_key and tls_cert must point to valid key and certificate files.
The bind_address can be "*" to bind to all interfaces, "0.0.0.0" for IPv4, or a specific IP address.
# Start an HTTP server on port 8081
HTTPServer.listen(8081, "*", false, "", "")
void register_route(method: String, path: String, callback: Callable) 🔗
Registers a route handler for the given HTTP method and path pattern. The callback will be called with two arguments: HTTPRequestContext and HTTPResponse.
The path can include parameters using the {variable} syntax. For example: "/api/users/{id}/posts/{post_id}".
Supported methods: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD.
HTTPServer.register_route("GET", "/user/{id}", Callable(self, "_on_user_route"))
Error send_sse_data(connection_id: int, data: String) 🔗
Sends data to a Server-Sent Events connection without specifying an event type. This is equivalent to calling send_sse_event() with an empty event name.
Error send_sse_event(connection_id: int, event: String, data: String) 🔗
Sends a Server-Sent Event to the connection identified by connection_id. The event specifies the event type, and data contains the event payload.
Multi-line data is automatically formatted according to the SSE specification. Returns @GlobalScope.OK on success.
void set_cors_enabled(enabled: bool) 🔗
Enables or disables CORS (Cross-Origin Resource Sharing) headers in responses. When enabled, the server adds appropriate headers to allow cross-origin requests.
void set_cors_origin(origin: String) 🔗
Sets the allowed origin for CORS requests. Use "*" to allow all origins, or specify a specific origin like "https://example.com".
void set_max_request_size(size: int) 🔗
Sets the maximum allowed request size in bytes. Requests larger than this will be rejected with a 413 error. The value is clamped between 1KB and 1MB.
void set_static_directory(path: String) 🔗
Sets the directory path for serving static files. This is used as a base path for file serving routes.
void stop() 🔗
Stops the HTTP server, closes all connections, and shuts down the background thread. All active SSE connections will be closed and sse_connection_closed will be emitted for each.
void unregister_route(method: String, path: String) 🔗
Removes a previously registered route for the given method and path.