File espos_httpd.h¶

File List > espos_httpd > include > espos_httpd.h
/*
 * SPDX-FileCopyrightText: 2026 Dirk Wahrheit
 * SPDX-License-Identifier: Apache-2.0
 *
 * espos_httpd — the device's HTTP server (esp_http_server) and the versioned
 * REST API under /api/v1. Other espOS components register their endpoints
 * through espos_httpd_register(); the UI bundle is served from /.
 *
 * Every registered endpoint is protected by the REST authentication
 * (docs/security.md) unless registered with ESPOS_HTTPD_PUBLIC: when
 * httpd.api_key is set, a request must carry `Authorization: Bearer <key>`
 * or the session cookie from POST /api/v1/auth/login, else it is answered
 * 401 before the handler runs. With no key set everything is open.
 *
 * URI handlers run on the esp_http_server task — one task for every request
 * the device gets: build the reply, send it, return.
 *
 * API contract: docs/rest-api.md. Changing it is a cross-component decision.
 */
#pragma once

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "esp_err.h"
#include "esp_http_server.h"

#ifdef __cplusplus
extern "C" {
#endif

esp_err_t espos_httpd_start(void);
esp_err_t espos_httpd_stop(void);
httpd_handle_t espos_httpd_handle(void);

esp_err_t espos_httpd_register(const httpd_uri_t *uri);

/* Registration flags for espos_httpd_register_ex(). Values are ABI. */
typedef enum {
    ESPOS_HTTPD_PROTECTED = 0,     /* the default: 401 without a valid credential when a key is set */
    ESPOS_HTTPD_PUBLIC = 1u << 0,  /* reachable by anyone: the UI, liveness, the login itself */
} espos_httpd_flags_t;

esp_err_t espos_httpd_register_ex(const httpd_uri_t *uri, uint32_t flags);

bool espos_httpd_request_authenticated(httpd_req_t *req);

esp_err_t espos_httpd_auth_recovery_open(uint32_t seconds);

uint32_t espos_httpd_auth_recovery_s_left(void);

/* ------------------------------------------------- helpers for handlers */

esp_err_t espos_httpd_send_json(httpd_req_t *req, const char *status, const char *json);

esp_err_t espos_httpd_send_error(httpd_req_t *req, const char *status, const char *code, const char *msg);

bool espos_httpd_require_json(httpd_req_t *req);

esp_err_t espos_httpd_read_body(httpd_req_t *req, char **out, size_t *out_len);

#ifdef __cplusplus
}
#endif