vatrog-vm-signaling/include/vmsig_core.h

#ifndef VMSIG_CORE_H
#define VMSIG_CORE_H
#include "vmsig_event.h"
#include "vmsig_ctx.h"
#include "vmsig_adapter.h"
#include "vmsig_control.h"

/* vmsig_core.h — non-blocking epoll core. It knows a single vocabulary: "here is
 * an fd — call the neutral handler on readiness; the handler produces/consumes
 * neutral events". All neighbor mechanisms are just different ways to spawn an
 * fd. The core structurally cannot name a neighbor's type: neighbor headers are
 * visible only from the adapter TUs. */

typedef struct vmsig_core vmsig_core;

/* Create the core over a transfer context (the core does NOT own ctx; ctx's
 * lifetime must cover the core). NULL on error. */
vmsig_core* vmsig_core_new(vmsig_ctx* ctx);

/* Stop, detach all adapters/control, free. Safe on NULL. */
void        vmsig_core_free(vmsig_core* c);

/* ===== Audit (observability of admissions/denials) ===== */
typedef enum {
    VMSIG_AUDIT_ADMIT         = 0,   /* poller admitted (socket accept)          */
    VMSIG_AUDIT_REJECT        = 1,   /* poller rejected at accept (empty grant)  */
    VMSIG_AUDIT_DOWN_DENIED   = 2,   /* DOWN command denied by grant/cap         */
    /* --- lease arbitration --- */
    VMSIG_AUDIT_LEASE_GRANTED = 3,   /* lease granted/preempted                  */
    VMSIG_AUDIT_LEASE_DENIED  = 4,   /* ACQUIRE denied OR destructive dropped by lease gate */
    VMSIG_AUDIT_LEASE_REVOKED = 5,   /* lease revoked by preemption              */
    VMSIG_AUDIT_LEASE_RECLAIMED = 6, /* lease reclaimed on owner death (reclaim) */
    VMSIG_AUDIT_MEMCTX_GRANTED  = 7  /* address-space context granted/replayed to holder */
} vmsig_audit_kind;

typedef struct {
    vmsig_audit_kind kind;
    uint32_t principal;   /* uid/token (grant.principal or peer uid)         */
    uint32_t endpoint;
    uint32_t cmd;         /* vmsig_kind for DOWN_DENIED                      */
    uint32_t detail;      /* extra (e.g. peer pid)                          */
} vmsig_audit;

/* Set the audit callback (NULL = off). Called on the loop thread. */
void        vmsig_core_set_audit(vmsig_core* c,
                                 void (*cb)(void* ud, const vmsig_audit* a), void* ud);

/* Set the lease arbitration policy (NULL => default: contender.arb_prio >
 * incumbent.arb_prio ? PREEMPT : DENY). Called on the loop thread. */
void        vmsig_core_set_arb_policy(vmsig_core* c, vmsig_arb_policy cb, void* ud);

/* Register an adapter for VM `endpoint`: open(cfg,endpoint) -> attach(...),
 * enroll each yielded fd into epoll and into the dispatch table fd->(adapter,cookie).
 * Returns the adapter id (>=0) or -1. Runtime-safe: may be called AFTER vmsig_core_run
 * has started, from a loop-thread callback (e.g. a discovery SLOT_SOURCE), to hot-plug
 * a VM's adapters; a freed adapter slot is reused so churn does not exhaust the table. */
int  vmsig_core_add_adapter(vmsig_core* c, const vmsig_adapter_ops* ops,
                            const void* cfg, uint32_t endpoint);

/* Request runtime detach of EVERY adapter currently attached to `endpoint` (the whole
 * VM trio). Deferred: the teardown (epoch settle + SEAM_DOWN + lease release + epoll DEL
 * + ops->close) runs after the current event batch, like core_request_drop for controls.
 * Safe to call from a loop-thread callback (e.g. inotify discovery). No-op if endpoint
 * is not attached or >= 64. The composing of the trio at attach is the caller's job
 * (3x add_adapter); detach is by endpoint so the caller needs no per-adapter ids. */
void vmsig_core_detach_endpoint(vmsig_core* c, uint32_t endpoint);

/* Attach a control endpoint (in-process or socket) with a GRANT (capability set).
 * grant == NULL => default-deny (poller inert). The core sees only the neutral
 * vtable + grant + (opt.) fd. Returns the control id (>=0) or -1. */
int  vmsig_core_add_control(vmsig_core* c, const vmsig_control_ops* ops, void* ctl,
                            const vmsig_grant* grant);

/* Spin the loop until a stop is requested. 0 — clean, -1 — fatal. */
int  vmsig_core_run(vmsig_core* c);

/* Asynchronous, signal-safe stop request: writes the wakeup eventfd. */
void vmsig_core_stop(vmsig_core* c);

#endif /* VMSIG_CORE_H */