vatrog-vm-signaling/include/vmsig_socket.h

#ifndef VMSIG_SOCKET_H
#define VMSIG_SOCKET_H
#include "vmsig_event.h"
#include "vmsig_control.h"   /* vmsig_grant */
#include "vmsig_core.h"      /* vmsig_core  */

/* vmsig_socket.h — out-of-process control over a unix socket (human/service poller).
 * signaling LISTENS; each accepted connection is authenticated (SO_PEERCRED) and,
 * per policy, receives a grant -> becomes a distinct control behind the same seam. */

/* Wire format: fixed-size, pointer-free — the same contract on the external
 * poller. Single host (unix socket) => native byte order. Only the event's
 * inline part is serialized (payload pointers do not go on the wire).
 *
 * Exception (DOWN only): a CMD_MEMWRITE frame with VMSIG_MW_SRC_PAYLOAD is followed
 * on the stream by exactly vmsig_memwrite.len SRC bytes (length-prefixed by the
 * contract's mw.len, no separate wire prefix). A client writes the 80-byte frame,
 * then the len SRC bytes (1..VMSIG_MEMWRITE_MAX). For len <= VMSIG_MEMWRITE_INLINE the
 * client uses VMSIG_MW_SRC_INLINE instead (SRC rides in the inln tail, no trailing
 * bytes). All other DOWN frames and all UP deliveries are a single fixed frame. */
#define VMSIG_WIRE_MAGIC   0x47495356u   /* 'VSIG' */
#define VMSIG_WIRE_VERSION 1u
typedef struct {
    uint32_t magic;
    uint32_t version;
    uint32_t kind;       /* vmsig_kind   */
    uint32_t source;     /* vmsig_source */
    uint32_t dir;        /* vmsig_dir    */
    uint32_t prio;       /* vmsig_prio   */
    uint32_t endpoint;
    uint32_t corr;
    uint8_t  inln[48];   /* inline event payload */
} vmsig_wire;

/* Frame <-> event codec (for external clients too). */
void vmsig_wire_encode(vmsig_wire* w, const vmsig_event* ev);
int  vmsig_wire_decode(const vmsig_wire* w, vmsig_event* ev);   /* 0 ok, -1 bad magic/ver */

/* Admission policy: given the authenticated peer (SO_PEERCRED), return a grant.
 * An empty grant (cap_mask==0 || endpoint_mask==0) => connection is rejected. */
typedef vmsig_grant (*vmsig_socket_policy)(uint32_t uid, uint32_t pid, void* ud);

/* Bring up a unix-socket control listener on `path` (prefix '@' => abstract socket).
 * Driven by the epoll core: accept -> SO_PEERCRED -> policy -> grant -> per-conn
 * control. Returns 0/-1. */
int vmsig_socket_attach(vmsig_core* core, const char* path,
                        vmsig_socket_policy policy, void* ud);

#endif /* VMSIG_SOCKET_H */