edge_fetch.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
 
#ifndef PROTOCORE_EDGE_FETCH_H
#define PROTOCORE_EDGE_FETCH_H
 
#include "protocore_config.h" // the entry point: protocore_types.h for the widths
 
PROTOCORE_BEGIN_DECLS
 
/**
 * @file edge_fetch.h
 * @brief CDN edge-cache tier - async origin-fetch engine (PROTOCORE_ENABLE_EDGE_CACHE).
 *
 * A non-blocking origin fetch: open + send a request over a transport seam, accumulate the response
 * across poll loops into a bounded buffer, detect completion (Content-Length / chunked / connection
 * close), then parse it with the proven http_client codec. Pumped from the server poll loop so a miss
 * or revalidation never stalls the worker; the transport seam is protocore_client on the device and a mock in
 * host tests. Zero heap; the buffer is fixed (`PROTOCORE_EDGE_FETCH_BUF`).
 *
 * @c work is bytes the CALLER holds. This module reads none of them: it carries nothing
 * between calls, so there is no state to keep and nothing to wipe. The parameter is there so
 * a caller drives every namespace the same way.
 *
 * @author  Douglas Quigg (dstroy0)
 * @date    2026
 */
 
// PROTOCORE_EDGE_FETCHER_BORROW - the bytes this module runs out of - is stated in protocore_config.h, which sums
// it into its arena. Its size and its offset are each a static_assert, so a feature
// combination that does not fit fails to compile rather than overrunning at run time.
 
/** @brief The origin transport, bound to protocore_client on the device and a mock in host tests. */
typedef struct EdgeFetchTransport
{
    int (*open)(void *ctx, const char *host, uint16_t port, uint32_t timeout_ms); ///< cid >= 0, or < 0 on failure
    proto_bool (*connected)(void *ctx, int cid); ///< step the open along; true once it is up
    proto_bool (*send)(void *ctx, int cid, const void *data, size_t len);
    size_t (*read)(void *ctx, int cid, uint8_t *buf, size_t cap); ///< 0 = nothing available right now
    proto_bool (*closed)(void *ctx, int cid);                     ///< true once the origin closed its side
    void (*close)(void *ctx, int cid);
    void *ctx;
} EdgeFetchTransport;
 
/** @brief Fetch progress. */
typedef enum PROTO_ENUM_PACKED
{
    EDGE_FETCH_STATUS_PENDING,  ///< still receiving
    EDGE_FETCH_STATUS_DONE,     ///< a complete response is parsed (status / body_off / body_len valid)
    EDGE_FETCH_STATUS_OVERSIZE, ///< response exceeded the buffer - not cacheable (caller passes through / fails open)
    EDGE_FETCH_STATUS_FAILED,   ///< connect / send / timeout / closed-before-complete
} EdgeFetchStatus;
 
/** @brief One in-flight origin fetch (fixed-size, zero-heap). */
typedef struct
{
    EdgeFetchStatus st;
    int cid;
    uint32_t start_ms;
    uint32_t got;     ///< bytes accumulated
    uint32_t req_len; ///< request bytes parked at the head of buf until the connection is up
    proto_bool sent;  ///< the request reached the transport, so buf now takes the response
    int status;       ///< HTTP status (valid when DONE)
    size_t head_len;
    size_t body_off;
    size_t body_len;
    uint8_t buf[PROTOCORE_EDGE_FETCH_BUF];
} EdgeFetch;
 
/** @brief Dispatch table. Addressed by offset, so the layout is asserted below. */
typedef struct
{
    void (*begin)(uint8_t *, EdgeFetch *, const EdgeFetchTransport *, const char *, uint16_t, const void *, size_t,
                  uint32_t);
    EdgeFetchStatus (*pump)(uint8_t *, EdgeFetch *, const EdgeFetchTransport *, uint32_t);
    void (*end)(uint8_t *, EdgeFetch *, const EdgeFetchTransport *);
    proto_bool (*edge_resp_complete)(uint8_t *, const uint8_t *, size_t, proto_bool, size_t *);
} EdgeFetchNs;
PROTOCORE_NS_LAYOUT(EdgeFetchNs, begin, pump, end, edge_resp_complete);
 
/**
 * @brief Open the origin connection and park request; begin the fetch. Sets .
 * @param work PROTOCORE_EDGE_FETCHER_BORROW bytes the caller took. Not held past the call.
 * @param f F
 * @param t T
 * @param host Host
 * @param port Port
 * @param request Request
 * @param req_len Req len
 * @param now_ms Now ms
 */
void protocore_edge_fetcher_begin(uint8_t *work, EdgeFetch *f, const EdgeFetchTransport *t, const char *host,
                                  uint16_t port, const void *request, size_t req_len, uint32_t now_ms);
/**
 * @brief Drain available bytes and advance. On DONE the response is parsed .
 * @param work PROTOCORE_EDGE_FETCHER_BORROW bytes the caller took. Not held past the call.
 * @param f F
 * @param t T
 * @param now_ms Now ms
 * @return The EdgeFetchStatus.
 */
EdgeFetchStatus protocore_edge_fetcher_pump(uint8_t *work, EdgeFetch *f, const EdgeFetchTransport *t, uint32_t now_ms);
/**
 * @brief Release the transport connection (idempotent).
 * @param work PROTOCORE_EDGE_FETCHER_BORROW bytes the caller took. Not held past the call.
 * @param f F
 * @param t T
 */
void protocore_edge_fetcher_end(uint8_t *work, EdgeFetch *f, const EdgeFetchTransport *t);
/**
 * @brief Is the accumulated response complete? (headers terminated + body .
 * @param work PROTOCORE_EDGE_FETCHER_BORROW bytes the caller took. Not held past the call.
 * @param buf Buf
 * @param len Len
 * @param conn_closed Conn closed
 * @param head_len Head len
 * @return PROTO_TRUE on success.
 */
proto_bool protocore_edge_fetcher_edge_resp_complete(uint8_t *work, const uint8_t *buf, size_t len,
                                                     proto_bool conn_closed, size_t *head_len);
 
/** @brief Module namespace. */
PROTOCORE_NS EdgeFetchNs EdgeFetcher PROTOCORE_UNUSED = {.begin = protocore_edge_fetcher_begin,
                                                         .pump = protocore_edge_fetcher_pump,
                                                         .end = protocore_edge_fetcher_end,
                                                         .edge_resp_complete =
                                                             protocore_edge_fetcher_edge_resp_complete};
 
PROTOCORE_END_DECLS
 
#endif // PROTOCORE_EDGE_FETCH_H