File syn_httpd.h¶

FileList > net > syn_httpd.h

Minimal HTTP/1.1 server — route-based, zero-alloc. More...

#include "../common/syn_defs.h"
#include "../port/syn_port_socket.h"
#include "../pt/syn_pt.h"
#include "../sched/syn_task.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_Httpd HTTP server context structure.
struct	SYN_HttpdRequest Parsed HTTP request container presented to route handlers.
struct	SYN_HttpdResponse HTTP response formatting state.
struct	SYN_HttpdRoute An HTTP routing entry configuration.

Public Types¶

Type	Name
enum	SYN_HttpMethod Supported HTTP request methods.
typedef void(*	SYN_HttpdHandler Route handler function.
enum	SYN_HttpdState Processing phase for the non-blocking request state machine.

Public Functions¶

Type	Name
void	syn_httpd_body (SYN_HttpdResponse * resp, const void * data, size_t len) Send response body data.
void	syn_httpd_body_str (SYN_HttpdResponse * resp, const char * str) Send a string as the response body.
void	syn_httpd_header (const SYN_HttpdResponse * resp, const char * name, const char * value) Add a response header.
SYN_Status	syn_httpd_init (SYN_Httpd * srv, uint16_t port, const SYN_HttpdRoute * routes, size_t route_count, uint8_t * work_buf, size_t work_buf_size) Initialize and start the HTTP server.
int	syn_httpd_read_body (const SYN_HttpdRequest * req, const SYN_HttpdResponse * resp, void * buf, size_t max_len) Read request body data (for POST/PUT).
void	syn_httpd_status (const SYN_HttpdResponse * resp, int code, const char * reason) Begin the response with a status line.
SYN_Status	syn_httpd_step (SYN_Httpd * srv) Handle one incoming request (non-protothread version).
void	syn_httpd_stop (SYN_Httpd * srv) Stop the server and close the listener socket.
SYN_PT_Status	syn_httpd_task (SYN_PT * pt, SYN_Task * task) Protothread task function for the HTTP server.

Detailed Description¶

Designed to run as a cooperative protothread task within the SyntropicOS scheduler. Yields between accepts so other tasks can run. Handles one request per scheduler tick.

** **

static void handle_status(const SYN_HttpdRequest *req,
                           SYN_HttpdResponse *resp, void *ctx) {
    syn_httpd_status(resp, 200, "OK");
    syn_httpd_header(resp, "Content-Type", "application/json");
    syn_httpd_body_str(resp, "{\"status\":\"ok\"}");
}

static const SYN_HttpdRoute routes[] = {
    { SYN_HTTP_GET, "/api/status", handle_status, NULL },
};

// In your task array:
static uint8_t httpd_buf[1024];
static SYN_Httpd httpd;
syn_httpd_init(&httpd, 80, routes, 1, httpd_buf, sizeof(httpd_buf));
syn_task_create(&tasks[N], "httpd", syn_httpd_task, 2, &httpd);

Public Types Documentation¶

enum SYN_HttpMethod¶

Supported HTTP request methods.

enum SYN_HttpMethod {
    SYN_HTTP_GET = 0,
    SYN_HTTP_POST = 1,
    SYN_HTTP_PUT = 2,
    SYN_HTTP_DELETE = 3
};

typedef SYN_HttpdHandler¶

Route handler function.

typedef void(* SYN_HttpdHandler) (const SYN_HttpdRequest *req, SYN_HttpdResponse *resp, void *ctx);

Called when a request matches the route. The handler sends the response using syn_httpd_status(), syn_httpd_header(), syn_httpd_body().

enum SYN_HttpdState¶

Processing phase for the non-blocking request state machine.

enum SYN_HttpdState {
    SYN_HTTPD_IDLE,
    SYN_HTTPD_READING_HEADERS,
    SYN_HTTPD_DISPATCHING
};

syn_httpd_step() advances through these phases without blocking: IDLE → READING_HEADERS → DISPATCHING → IDLE

Public Functions Documentation¶

function syn_httpd_body¶

Send response body data.

void syn_httpd_body (
    SYN_HttpdResponse * resp,
    const void * data,
    size_t len
)

Automatically finalizes headers on first call. Can be called multiple times for streaming responses.

Parameters:

resp HTTP response state to write to.
data Pointer to binary data to transmit.
len Length of data in bytes.

function syn_httpd_body_str¶

Send a string as the response body.

void syn_httpd_body_str (
    SYN_HttpdResponse * resp,
    const char * str
)

Convenience wrapper for syn_httpd_body().

Parameters:

resp HTTP response state to write to.
str Null-terminated string to send.

function syn_httpd_header¶

Add a response header.

void syn_httpd_header (
    const SYN_HttpdResponse * resp,
    const char * name,
    const char * value
)

Must be called after syn_httpd_status() and before syn_httpd_body().

Parameters:

resp HTTP response state to write to.
name Header key string (e.g. "Content-Type").
value Header value string (e.g. "text/plain").

function syn_httpd_init¶

Initialize and start the HTTP server.

SYN_Status syn_httpd_init (
    SYN_Httpd * srv,
    uint16_t port,
    const SYN_HttpdRoute * routes,
    size_t route_count,
    uint8_t * work_buf,
    size_t work_buf_size
)

Creates a listening socket on the given port.

Parameters:

srv Server instance to initialize.
port Port to listen on (typically 80).
routes Route table (must outlive the server).
route_count Number of routes.
work_buf Shared work buffer for request parsing + responses.
work_buf_size Buffer size (512+ recommended).

Returns:

SYN_OK on success, SYN_ERROR if bind/listen fails.

function syn_httpd_read_body¶

Read request body data (for POST/PUT).

int syn_httpd_read_body (
    const SYN_HttpdRequest * req,
    const SYN_HttpdResponse * resp,
    void * buf,
    size_t max_len
)

Parameters:

req Request info.
resp Response writer context.
buf Buffer to read into.
max_len Buffer capacity in bytes.

Returns:

Bytes read, 0 at end of body, -1 on error.

function syn_httpd_status¶

Begin the response with a status line.

void syn_httpd_status (
    const SYN_HttpdResponse * resp,
    int code,
    const char * reason
)

Must be called first. E.g., syn_httpd_status(resp, 200, "OK").

Parameters:

resp HTTP response state to write to.
code HTTP numeric status code (e.g. 200).
reason Human readable status message (e.g. "OK").

function syn_httpd_step¶

Handle one incoming request (non-protothread version).

SYN_Status syn_httpd_step (
    SYN_Httpd * srv
)

Accepts one connection, parses the request, dispatches to the matching route handler, and closes the connection. Use this if you prefer manual control over the server loop.

Parameters:

srv Server instance.

Returns:

SYN_OK if a request was handled, SYN_TIMEOUT if no client connected, SYN_ERROR on parse failure.

function syn_httpd_stop¶

Stop the server and close the listener socket.

void syn_httpd_stop (
    SYN_Httpd * srv
)

Parameters:

srv Server instance to stop.

function syn_httpd_task¶

Protothread task function for the HTTP server.

SYN_PT_Status syn_httpd_task (
    SYN_PT * pt,
    SYN_Task * task
)

Register this as a SYN_TaskFunc with user_data pointing to a SYN_Httpd instance. The task accepts a connection, handles one request, then yields back to the scheduler.

Parameters:

pt Pointer to the cooperative protothread context.
task Pointer to the scheduler task structure.

Returns:

PT_WAITING or PT_EXITED status.

The documentation for this class was generated from the following file src/syntropic/net/syn_httpd.h