ota_service.h

Go to the documentation of this file.

// ProtoCore v1.0.16 - Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file ota_service.h
 * @brief Optional authenticated OTA firmware update (PROTOCORE_ENABLE_OTA).
 *
 * Registers a POST endpoint that streams a firmware image straight into the
 * platform update API via the parser's streaming-body hook
 * (http_parser_set_stream_hooks), so the image never has to fit in RAM. On a
 * successful flash the device responds and reboots into the new firmware.
 * Compiled to a no-op stub when PROTOCORE_ENABLE_OTA is 0 or the platform has no updater.
 *
 * @author  Douglas Quigg (dstroy0)
 * @date    2026
 */
 
#ifndef PROTOCORE_OTA_SERVICE_H
#define PROTOCORE_OTA_SERVICE_H
 
#include "protocore_config.h" // the entry point: the enable gate below, and the widths
 
#if PROTOCORE_ENABLE_OTA && PROTOCORE_HAS_VENDOR_OTA
 
PROTOCORE_BEGIN_DECLS
 
/**
 * @brief Register an authenticated streaming OTA endpoint.
 *
 * Call after begin(). A `POST @p path` carrying a raw firmware image and valid
 * HTTP Basic credentials is streamed into `Update`; on success the device
 * replies `200` and reboots. Unauthorized or failed uploads get `401` / `400`.
 *
 * @param server  The running server (the route + stream hooks are installed on it).
 * @param path    URL to accept the upload on (e.g. "/update"). Persistent string.
 * @param user    Required HTTP Basic username.
 * @param pass    Required HTTP Basic password.
 *
 * @code
 * curl -u admin:s3cret --data-binary @firmware.bin http://<ip>/update
 * @endcode
 */
/** @brief What installing the upload route takes. */
typedef struct
{
    const char *path; ///< URL to accept the upload on (e.g. "/update"); a persistent string
    const char *user; ///< required HTTP Basic username
    const char *pass; ///< required HTTP Basic password
} OtaServiceArgs;
 
/**
 * @brief The firmware upload route.
 *
 * @var OtaServiceNs::args      what installing the route takes
 * @var OtaServiceNs::begin     install the route and the streaming-body hooks
 */
typedef struct
{
    OtaServiceArgs args;
} OtaServiceVars;
 
/** @brief The operands and the outcome. */
extern OtaServiceVars OtaServiceV;
 
/** @brief The entries. */
typedef struct
{
    void (*const begin)(uint8_t *work);
} OtaServiceNs;
 
// What the table binds, defined once in the .c and taking one parameter each: everything
// else an entry needs is an operand in OtaServiceV or a region of the borrow at a fixed offset.
void protocore_ota_service_begin(uint8_t *work);
 
// `static const`, initialised HERE rather than `extern` against a definition in the .c: a
// const object whose initializer every translation unit can see is a COMPILE-TIME FACT, so
// `OtaService.begin(work)` resolves to a named function and becomes a DIRECT call. An extern table
// leaves the call indirect and the symbol live at every level, -O2 -flto included.
static const OtaServiceNs OtaService __attribute__((unused)) = {
    .begin = protocore_ota_service_begin,
};
 
PROTOCORE_END_DECLS
 
#endif // PROTOCORE_ENABLE_OTA && PROTOCORE_HAS_VENDOR_OTA
 
#endif // PROTOCORE_OTA_SERVICE_H