forward.cpp

Go to the documentation of this file.

// Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file forward.cpp
 * @brief Interface forwarding plane - implementation.
 *
 * Static interface + rule tables. A frame on one interface is resolved against the rules
 * (a DENY wins, otherwise a matching ALLOW forwards, otherwise default-deny) for every
 * other registered interface, rate-capped per rule, then handed to that interface's send
 * callback. Zero heap, fail-closed.
 */
 
#include "services/net/forward/forward.h"
 
#if PC_ENABLE_FORWARD
 
#include <string.h>
 
#ifdef ARDUINO
#include "services/system/clock.h" // pc_millis()
#endif
 
namespace
{
struct iface
{
    pc_if_send_fn send;
    void *ctx;
    uint8_t id;
    pc_if_kind kind;
    bool used;
};
 
struct rule
{
    uint32_t window_start; // ms of the current rate window
    uint16_t rate_cap;     // frames per second (0 = unlimited)
    uint16_t count;        // frames forwarded in the current window
    uint8_t src;
    uint8_t dst;
    pc_fwd_action action;
    bool used;
};
 
struct acl_entry
{
    uint8_t pattern[PC_FWD_ACL_PATLEN];
    uint8_t mask[PC_FWD_ACL_PATLEN];
    uint16_t offset;
    uint8_t src;    // source interface, or PC_FWD_IF_ANY
    uint8_t patlen; // 0 = match any content
    pc_fwd_action action;
    bool used;
};
 
// A policy route: match a frame by byte pattern (as the ACL does) and bind it to one egress.
struct route
{
    uint32_t window_start; // ms of the current rate window
    uint8_t pattern[PC_FWD_ACL_PATLEN];
    uint8_t mask[PC_FWD_ACL_PATLEN];
    uint16_t offset;
    uint16_t rate_cap; // frames per second to the egress (0 = unlimited)
    uint16_t count;    // frames routed in the current window
    uint8_t src;       // source interface, or PC_FWD_IF_ANY
    uint8_t patlen;    // 0 = match any content
    uint8_t egress;    // egress interface id
    bool used;
};
 
// All forwarding-plane state, owned by one instance (internal linkage): interfaces,
// rules, ACL, and stats grouped so it is one named owner, unreachable cross-TU.
struct ForwardCtx
{
    iface if_[PC_FWD_MAX_IFACES];
    rule rules[PC_FWD_MAX_RULES];
    acl_entry acl[PC_FWD_MAX_ACL];
    route routes[PC_FWD_MAX_ROUTES];
    pc_fwd_action acl_default = pc_fwd_action::PC_FWD_ALLOW; // frames matching no ACL entry (opt-in ACL)
#if PC_FWD_INSPECT
    pc_fwd_inspect_fn inspector = nullptr; // opt-in ingress inspection hook
    void *inspect_ctx = nullptr;
#endif
    pc_forward_stats stats;
#ifndef ARDUINO
    uint32_t now_ms = 0; // host test clock (real builds use pc_millis())
#endif
};
ForwardCtx s_fwd;
 
#ifdef ARDUINO
uint32_t fwd_now()
{
    return pc_millis();
}
#else
uint32_t fwd_now()
{
    return s_fwd.now_ms;
}
#endif
 
const iface *find_if(const ForwardCtx &f, uint8_t id)
{
    for (uint8_t i = 0; i < PC_FWD_MAX_IFACES; i++)
    {
        if (f.if_[i].used && f.if_[i].id == id)
        {
            return &f.if_[i];
        }
    }
    return nullptr;
}
 
// Resolve the action for (src -> dst): a DENY wins; otherwise the first matching ALLOW
// governs (its index is returned via @p allow_idx); otherwise default-deny (no route).
enum class resolve_result : uint8_t
{
    R_NOROUTE,
    R_DENY,
    R_ALLOW,
};
resolve_result resolve(const ForwardCtx &f, uint8_t src, uint8_t dst, int *allow_idx)
{
    int allow = -1;
    bool deny = false;
    for (uint8_t i = 0; i < PC_FWD_MAX_RULES; i++)
    {
        if (!f.rules[i].used || f.rules[i].src != src || f.rules[i].dst != dst)
        {
            continue;
        }
        if (f.rules[i].action == pc_fwd_action::PC_FWD_DENY)
        {
            deny = true;
        }
        else if (allow < 0)
        {
            allow = (int)i;
        }
    }
    if (deny)
    {
        return resolve_result::R_DENY;
    }
    if (allow >= 0)
    {
        *allow_idx = allow;
        return resolve_result::R_ALLOW;
    }
    return resolve_result::R_NOROUTE;
}
 
// Fixed 1-second window rate cap; fail-closed (returns true = drop) once the cap is hit.
// Shared by the src->dst rules and the policy routes (same window bookkeeping fields).
bool rate_gate(uint32_t &window_start, uint16_t &count, uint16_t rate_cap)
{
    if (rate_cap == 0)
    {
        return false; // unlimited
    }
    uint32_t now = fwd_now();
    if ((now - window_start) >= 1000)
    {
        window_start = now;
        count = 0;
    }
    if (count >= rate_cap)
    {
        return true;
    }
    count++;
    return false;
}
 
bool rate_exceeded(rule *r)
{
    return rate_gate(r->window_start, r->count, r->rate_cap);
}
 
// Does a stored byte pattern match this frame? (already-masked @p pattern under @p mask at
// @p offset). @p patlen 0 matches any content; a frame too short for the pattern does not match.
bool pat_match(uint16_t offset, const uint8_t *pattern, const uint8_t *mask, uint8_t patlen, const uint8_t *data,
               uint16_t len)
{
    if (patlen == 0)
    {
        return true;
    }
    if ((uint32_t)offset + patlen > len)
    {
        return false;
    }
    for (uint8_t i = 0; i < patlen; i++)
    {
        if ((data[offset + i] & mask[i]) != pattern[i])
        {
            return false;
        }
    }
    return true;
}
 
// Does an ACL entry match this frame? (interface + byte pattern under mask).
bool acl_match(const acl_entry *a, uint8_t src, const uint8_t *data, uint16_t len)
{
    if (a->src != PC_FWD_IF_ANY && a->src != src)
    {
        return false;
    }
    return pat_match(a->offset, a->pattern, a->mask, a->patlen, data, len);
}
 
// Ingress ACL: the first matching entry's action decides; otherwise the default.
bool acl_permits(const ForwardCtx &f, uint8_t src, const uint8_t *data, uint16_t len)
{
    for (uint8_t i = 0; i < PC_FWD_MAX_ACL; i++)
    {
        if (f.acl[i].used && acl_match(&f.acl[i], src, data, len))
        {
            return f.acl[i].action == pc_fwd_action::PC_FWD_ALLOW;
        }
    }
    return f.acl_default == pc_fwd_action::PC_FWD_ALLOW;
}
} // namespace
 
void pc_forward_reset(void)
{
    memset(s_fwd.if_, 0, sizeof(s_fwd.if_));
    memset(s_fwd.rules, 0, sizeof(s_fwd.rules));
    memset(s_fwd.acl, 0, sizeof(s_fwd.acl));
    memset(s_fwd.routes, 0, sizeof(s_fwd.routes));
    s_fwd.acl_default = pc_fwd_action::PC_FWD_ALLOW;
#if PC_FWD_INSPECT
    s_fwd.inspector = nullptr;
    s_fwd.inspect_ctx = nullptr;
#endif
    memset(&s_fwd.stats, 0, sizeof(s_fwd.stats));
}
 
void pc_forward_acl_set_default(pc_fwd_action action)
{
    s_fwd.acl_default = action;
}
 
bool pc_forward_acl_add(uint8_t src_if, uint16_t offset, const uint8_t *pattern, const uint8_t *mask, uint8_t patlen,
                        pc_fwd_action action)
{
    if (patlen > PC_FWD_ACL_PATLEN || (patlen > 0 && (!pattern || !mask)))
    {
        return false;
    }
    for (uint8_t i = 0; i < PC_FWD_MAX_ACL; i++)
    {
        if (s_fwd.acl[i].used)
        {
            continue;
        }
        memset(s_fwd.acl[i].pattern, 0, sizeof(s_fwd.acl[i].pattern));
        memset(s_fwd.acl[i].mask, 0, sizeof(s_fwd.acl[i].mask));
        for (uint8_t k = 0; k < patlen; k++)
        {
            s_fwd.acl[i].pattern[k] = (uint8_t)(pattern[k] & mask[k]); // store already masked
            s_fwd.acl[i].mask[k] = mask[k];
        }
        s_fwd.acl[i].offset = offset;
        s_fwd.acl[i].src = src_if;
        s_fwd.acl[i].patlen = patlen;
        s_fwd.acl[i].action = action;
        s_fwd.acl[i].used = true;
        return true;
    }
    return false; // table full
}
 
bool pc_forward_route_add(uint8_t src_if, uint16_t offset, const uint8_t *pattern, const uint8_t *mask, uint8_t patlen,
                          uint8_t egress_if, uint16_t rate_cap_per_sec)
{
    if (patlen > PC_FWD_ACL_PATLEN || (patlen > 0 && (!pattern || !mask)))
    {
        return false;
    }
    for (uint8_t i = 0; i < PC_FWD_MAX_ROUTES; i++)
    {
        if (s_fwd.routes[i].used)
        {
            continue;
        }
        memset(s_fwd.routes[i].pattern, 0, sizeof(s_fwd.routes[i].pattern));
        memset(s_fwd.routes[i].mask, 0, sizeof(s_fwd.routes[i].mask));
        for (uint8_t k = 0; k < patlen; k++)
        {
            s_fwd.routes[i].pattern[k] = (uint8_t)(pattern[k] & mask[k]); // store already masked
            s_fwd.routes[i].mask[k] = mask[k];
        }
        s_fwd.routes[i].window_start = 0;
        s_fwd.routes[i].offset = offset;
        s_fwd.routes[i].rate_cap = rate_cap_per_sec;
        s_fwd.routes[i].count = 0;
        s_fwd.routes[i].src = src_if;
        s_fwd.routes[i].patlen = patlen;
        s_fwd.routes[i].egress = egress_if;
        s_fwd.routes[i].used = true;
        return true;
    }
    return false; // table full
}
 
bool pc_forward_add_if(uint8_t if_id, pc_if_kind kind, pc_if_send_fn send, void *ctx)
{
    if (!send || find_if(s_fwd, if_id))
    {
        return false;
    }
    for (uint8_t i = 0; i < PC_FWD_MAX_IFACES; i++)
    {
        if (s_fwd.if_[i].used)
        {
            continue;
        }
        s_fwd.if_[i].send = send;
        s_fwd.if_[i].ctx = ctx;
        s_fwd.if_[i].id = if_id;
        s_fwd.if_[i].kind = kind;
        s_fwd.if_[i].used = true;
        return true;
    }
    return false; // table full
}
 
bool pc_forward_add_rule(uint8_t src_if, uint8_t dst_if, pc_fwd_action action, uint16_t rate_cap_per_sec)
{
    for (uint8_t i = 0; i < PC_FWD_MAX_RULES; i++)
    {
        if (s_fwd.rules[i].used)
        {
            continue;
        }
        s_fwd.rules[i].window_start = 0;
        s_fwd.rules[i].rate_cap = rate_cap_per_sec;
        s_fwd.rules[i].count = 0;
        s_fwd.rules[i].src = src_if;
        s_fwd.rules[i].dst = dst_if;
        s_fwd.rules[i].action = action;
        s_fwd.rules[i].used = true;
        return true;
    }
    return false; // table full
}
 
// First matching policy route decides the frame (send to its egress only, or drop) - the same
// precedence and guarantees as a rule. *handled=false means no route matched; run normal fan-out.
static uint8_t forward_policy_route(uint8_t src_if, const uint8_t *data, uint16_t len, bool *handled)
{
    *handled = true;
    for (uint8_t i = 0; i < PC_FWD_MAX_ROUTES; i++)
    {
        route &rt = s_fwd.routes[i];
        if (!rt.used || (rt.src != PC_FWD_IF_ANY && rt.src != src_if))
        {
            continue;
        }
        if (!pat_match(rt.offset, rt.pattern, rt.mask, rt.patlen, data, len))
        {
            continue;
        }
        s_fwd.stats.policy_routed++;
        if (rt.egress == src_if) // never reflect to the source interface
        {
            return 0;
        }
        const iface *out = find_if(s_fwd, rt.egress);
        if (!out) // egress not registered -> drop, fail-closed
        {
            s_fwd.stats.send_fail++;
            return 0;
        }
        if (rate_gate(rt.window_start, rt.count, rt.rate_cap))
        {
            s_fwd.stats.rate_dropped++;
            return 0;
        }
        if (out->send(out->id, data, len, out->ctx))
        {
            s_fwd.stats.forwarded++;
            return 1;
        }
        s_fwd.stats.send_fail++;
        return 0;
    }
    *handled = false;
    return 0;
}
 
uint8_t pc_forward_ingress(uint8_t src_if, const uint8_t *data, uint16_t len)
{
    s_fwd.stats.frames_in++;
    if (!acl_permits(s_fwd, src_if, data, len)) // ingress ACL runs before any forwarding rule
    {
        s_fwd.stats.acl_denied++;
        return 0;
    }
#if PC_FWD_INSPECT
    // Opt-in inspection hook: an app callback observes/filters the frame before routing.
    if (s_fwd.inspector && s_fwd.inspector(src_if, data, len, s_fwd.inspect_ctx) == pc_fwd_verdict::PC_FWD_INSPECT_DROP)
    {
        s_fwd.stats.inspect_dropped++;
        return 0;
    }
#endif
    // Policy routes take precedence over the src->dst fan-out: the first matching route sends
    // the frame only to its chosen egress and ends the decision (same guarantees as a rule).
    bool routed = false;
    uint8_t verdict = forward_policy_route(src_if, data, len, &routed);
    if (routed)
    {
        return verdict;
    }
    uint8_t n = 0;
    for (uint8_t i = 0; i < PC_FWD_MAX_IFACES; i++)
    {
        if (!s_fwd.if_[i].used || s_fwd.if_[i].id == src_if) // never reflect to the source interface
        {
            continue;
        }
        int idx = -1;
        resolve_result r = resolve(s_fwd, src_if, s_fwd.if_[i].id, &idx);
        if (r == resolve_result::R_NOROUTE)
        {
            continue; // default-deny, silent
        }
        if (r == resolve_result::R_DENY)
        {
            s_fwd.stats.blocked++;
            continue;
        }
        if (rate_exceeded(&s_fwd.rules[idx]))
        {
            s_fwd.stats.rate_dropped++;
            continue;
        }
        if (s_fwd.if_[i].send(s_fwd.if_[i].id, data, len, s_fwd.if_[i].ctx))
        {
            s_fwd.stats.forwarded++;
            n++;
        }
        else
        {
            s_fwd.stats.send_fail++;
        }
    }
    return n;
}
 
void pc_forward_get_stats(pc_forward_stats *out)
{
    if (out)
    {
        *out = s_fwd.stats;
    }
}
 
#if PC_FWD_INSPECT
void pc_forward_set_inspector(pc_fwd_inspect_fn fn, void *ctx)
{
    s_fwd.inspector = fn;
    s_fwd.inspect_ctx = ctx;
}
#endif
 
#if !defined(ARDUINO)
void pc_forward_test_set_now(uint32_t ms)
{
    s_fwd.now_ms = ms;
}
#endif
 
#endif // PC_ENABLE_FORWARD