http_server
Generated by tinox doc
HTTP/1.1 server: HttpServer for route registration (get/post/put/patch/delete, :param path segments, middleware), HttpRequest/HttpResponse for reading/building requests and responses, and HttpContext bundling both together for a handler. The foundation tinox.core.rest, http2_server, http3_server, oidc and sse all build on.
| Module | Version | Group |
|---|---|---|
json | 1.0.0 | tinox.core |
Hello server
import tinox.core.http_server;
class Main
{
fnc main() -> Int32
{
let server: HttpServer = HttpServer::new(8080);
server.get("/hello", ctx => {
ctx.response.text("Hello, World!");
});
server.get("/users/:id", ctx => {
let id: String = ctx.request.getParam("id");
ctx.response.json("{\"id\": \"" + id + "\"}");
});
server.listen();
return 0;
}
}
class HttpContext
* Request context passed to route handlers and middleware * * Contains both the incoming request and the outgoing response, * enabling handlers to read request data and modify the response.
Fields
request | HttpRequest | The incoming HTTP request |
response | HttpResponse | The outgoing HTTP response |
Methods
fn new(request: HttpRequest, response: HttpResponse) → HttpContext
* Creates a new HttpContext
*
* @param request the incoming request
* @param response the outgoing response (defaults to new 200 response)
* @return a new HttpContext instance
fn fromRequest(request: HttpRequest) → HttpContext
* Creates a context with a new default response
*
* @param request the incoming request
* @return a new HttpContext with a fresh 200 response
class HttpRequest
* Represents an incoming HTTP request * * Provides access to the method, path, headers, query parameters, * body, and path parameters.
Fields
method | String | The HTTP method (GET, POST, PUT, PATCH, DELETE) |
path | String | The request path (e.g., "/users/42") |
body | String | The raw request body |
headers | Map<String, String> | Request headers as key-value pairs |
queryString | String | The raw query string (e.g., "page=1&limit=10") |
params | Map<String, String> | Path parameters extracted from route patterns |
wasEarlyData | Bool | * True if this request arrived as TLS 1.3 0-RTT early data * (tinox.core.http3_server's Http3Server, when enableEarlyData() * is opted into) -- always false for HttpServer/Http2Server, * since neither supports 0-RTT. Early data is replayable by a * network attacker (no round trip to prove the client isn't * replaying a captured ClientHello+request), so handlers that * check this should avoid non-idempotent side effects when true. |
Methods
fn new(method: String, path: String, queryString: String, headers: Map<String, String>, body: String) → HttpRequest
* Creates a new HttpRequest
*
* @param method the HTTP method
* @param path the request path
* @param queryString the query string
* @param headers the request headers
* @param body the request body
* @return a new HttpRequest instance
fn getHeader(name: String) → String
* Returns the value of a request header
*
* @param name the header name (case-insensitive lookup)
* @return the header value, or empty string if not found
fn getParam(name: String) → String
* Returns the value of a path parameter
*
* @param name the parameter name
* @return the parameter value, or empty string if not found
fn getQuery(name: String) → String
* Returns the value of a query parameter
*
* @param name the query parameter name
* @return the parameter value, or empty string if not found
fn json() → JsonValue
* Parses the request body as JSON
*
* @return a JsonValue representing the parsed body
fn bodyAs() → T
* Deserializes the request body into an object of type T.
* T must be annotated with @JsonSerializable.
*
* Usage:
* let user: CreateUserRequest = ctx.request.bodyAs<CreateUserRequest>();
*
* @return the deserialized object
fn text() → String
* Returns the raw request body as a string
*
* @return the request body
fn setParams(params: Map<String, String>) → Nothing
* Sets path parameters (internal use by route matching)
*
* @param params the extracted path parameters
fn isContentType(contentType: String) → Bool
* Checks the Content-Type header
*
* @param contentType the content type to check for
* @return true if the request Content-Type matches
class HttpResponse
* Represents an outgoing HTTP response * * Provides a fluent API for building responses with * status codes, headers, and body content.
Fields
statusCode | Int64 | The HTTP status code |
headers | Map<String, String> | Response headers |
body | String | The response body |
Methods
fn new() → HttpResponse
* Creates a new HttpResponse with default status 200
*
* @return a new HttpResponse instance
fn status(code: Int64) → HttpResponse
* Sets the HTTP status code
*
* @param code the status code (e.g., 200, 404)
* @return this response for chaining
fn header(name: String, value: String) → HttpResponse
* Sets a response header
*
* @param name the header name
* @param value the header value
* @return this response for chaining
fn text(text: String) → HttpResponse
* Sets the response body as plain text with Content-Type: text/plain
*
* @param text the response text
* @return this response for chaining
fn json(json: String) → HttpResponse
* Sets the response body as JSON with Content-Type: application/json
*
* @param json the JSON string
* @return this response for chaining
fn jsonObject(obj: T) → HttpResponse
* Serializes a @JsonSerializable object and sets it as the JSON response body.
*
* Usage:
* ctx.response.json(user);
* ctx.response.json(userList);
*
* @param obj any object annotated with @JsonSerializable
* @return this response for chaining
fn html(html: String) → HttpResponse
* Sets the response body as HTML with Content-Type: text/html
*
* @param html the HTML string
* @return this response for chaining
fn content(content: String, contentType: String) → HttpResponse
* Sets the response body with a custom Content-Type
*
* @param content the response body
* @param contentType the MIME type
* @return this response for chaining
fn notFound(message: String) → HttpResponse
* Sets the response to a 404 Not Found with a message
*
* @param message the error message
* @return this response for chaining
fn badRequest(message: String) → HttpResponse
* Sets the response to a 400 Bad Request with a message
*
* @param message the error message
* @return this response for chaining
fn internalError(message: String) → HttpResponse
* Sets the response to a 500 Internal Server Error with a message
*
* @param message the error message
* @return this response for chaining
fn created(json: String) → HttpResponse
* Sets the response to a 201 Created with a JSON body
*
* @param json the JSON response body
* @return this response for chaining
fn noContent() → HttpResponse
* Sets the response to a 204 No Content (empty body)
*
* @return this response for chaining
fn redirect(url: String) → HttpResponse
* Sets the response to a redirect (302 Found)
*
* @param url the URL to redirect to
* @return this response for chaining
fn cors(origin: String) → HttpResponse
* Sets CORS headers to allow cross-origin requests
*
* @param origin the allowed origin (defaults to "*")
* @return this response for chaining
class HttpServer
* HTTP server for handling incoming HTTP requests * * Supports route registration for GET, POST, PUT, PATCH, DELETE, * middleware chains, and automatic request parsing. * * Example usage: * let server: HttpServer = HttpServer::new(8080); * server.get("/hello", ctx => { * ctx.response.text("Hello, World!"); * }); * server.post("/users", ctx => { * let data: JsonValue = ctx.request.json(); * ctx.response.status(201).json("{\"id\": 1}"); * }); * server.listen();
Fields
port | Int64 | The port to listen on |
routes | List<Route> | Registered routes |
middleware | List<fn(HttpContext) -> Bool> | Registered middleware functions |
socketHandle | Int64 | The underlying socket handle |
running | Bool | Whether the server is running |
Methods
fn new(port: Int64) → HttpServer
* Creates a new HttpServer listening on the given port
*
* @param port the port number to bind to
* @return a new HttpServer instance
fn get(path: String, handler: fn(HttpContext) -> Nothing) → HttpServer
* Registers a GET route handler
*
* @param path the URL path pattern (e.g., "/users/:id")
* @param handler the function to handle matching requests
* @return this server for chaining
fn post(path: String, handler: fn(HttpContext) -> Nothing) → HttpServer
* Registers a POST route handler
*
* @param path the URL path pattern
* @param handler the function to handle matching requests
* @return this server for chaining
fn put(path: String, handler: fn(HttpContext) -> Nothing) → HttpServer
* Registers a PUT route handler
*
* @param path the URL path pattern
* @param handler the function to handle matching requests
* @return this server for chaining
fn patch(path: String, handler: fn(HttpContext) -> Nothing) → HttpServer
* Registers a PATCH route handler
*
* @param path the URL path pattern
* @param handler the function to handle matching requests
* @return this server for chaining
fn delete(path: String, handler: fn(HttpContext) -> Nothing) → HttpServer
* Registers a DELETE route handler
*
* @param path the URL path pattern
* @param handler the function to handle matching requests
* @return this server for chaining
fn use(mware: fn(HttpContext) -> Bool) → HttpServer
* Registers a middleware function
*
* Middleware is executed in the order it is registered.
* If a middleware returns false, the request chain is interrupted.
*
* @param mware the middleware function
* @return this server for chaining
fn listen() → Nothing
* Starts the server and begins listening for connections
*
* This is a blocking call that enters the server event loop.
* Use stop() to shut down the server.
fn listenTls(certPath: String, keyPath: String) → Nothing
* Starts the server with TLS/HTTPS enabled.
*
* OpenSSL is linked by default (opt-out via TINOX_TLS=0 at build
* time). Without it, httpServerCreateTls returns -1 and this call
* throws.
*
* Certificate and key must both be PEM files. certPath may contain the
* full certificate chain (leaf first).
*
* Example:
* server.listenTls("cert.pem", "key.pem");
*
* @param certPath path to the PEM certificate (chain) file
* @param keyPath path to the PEM private key file
fn parseRawRequest(raw: String) → HttpContext
* Parses a raw HTTP/1.1 request string into an HttpContext
fn formatResponse(response: HttpResponse) → String
* Formats an HttpResponse into a raw HTTP/1.1 response string
fn statusText(code: Int64) → String
* Returns the HTTP status text for a given status code
fn stop() → Nothing
* Stops the running server
fn handleRequest(ctx: HttpContext, conn: Int64) → Nothing
* Processes an incoming request through middleware and route matching,
* then sends the response and closes the connection.
*
* @param ctx the request context
* @param conn the client connection handle (plaintext or TLS)
fn runMiddleware(ctx: HttpContext) → Bool
* Runs all registered middleware functions
*
* @param ctx the request context
* @return true if all middleware passed, false if any rejected
fn matchRoute(ctx: HttpContext) → Bool
* Matches an incoming request against registered routes
*
* Supports path parameters via :param syntax.
* For example, "/users/:id" matches "/users/42" with params { id: "42" }
*
* @param ctx the request context (modified in place with params)
* @return true if a matching route was found and executed
class QueryString
* Utility for parsing and working with query strings
Methods
fn parse(qs: String) → Map<String, String>
* Parses a query string into a map of key-value pairs
*
* @param qs the raw query string (e.g., "page=1&limit=10")
* @return a map of parameter names to values
fn get(qs: String, name: String) → String
* Gets a single value from a query string by parameter name
*
* @param qs the raw query string
* @param name the parameter name
* @return the parameter value, or empty string if not found
class Route
* A route definition mapping an HTTP method and path pattern to a handler
Fields
method | String | The HTTP method (GET, POST, etc.) |
path | String | The path pattern (e.g., "/users/:id") |
handler | fn(HttpContext) -> Nothing | The handler function to execute |
class RouteMatcher
* Utility for matching URL paths against route patterns * with support for path parameters (:param syntax)
Methods
fn matches(pattern: String, path: String) → Bool
* Checks if a request path matches a route pattern
*
* Pattern syntax:
* "/users" - exact match
* "/users/:id" - match with path parameter
* "/static/*" - wildcard match for remaining path
*
* @param pattern the route pattern
* @param path the actual request path
* @return true if the path matches the pattern
fn extractParams(pattern: String, path: String) → Map<String, String>
* Extracts path parameters from a request path based on a route pattern
*
* @param pattern the route pattern with :param placeholders
* @param path the actual request path
* @return a map of parameter names to their values
fn splitPath(path: String) → List<String>
* Splits a path into segments, filtering empty segments
*
* @param path the path to split
* @return a list of non-empty path segments