net_shared.h

#pragma once
#include <cx/buffer/buffer.h>
#include <cx/buffer/bufchain.h>
#include <cx/buffer/bufring.h>
#include <cx/container/sarray.h>
#include <cx/stype/stype.h>
#include <cx/thread/prqueue.h>
 
typedef struct NetSocket NetSocket;
typedef struct NetQueue NetQueue;
typedef struct NetFlow NetFlow;
 
 
typedef intptr NetSockHandle;
 
#define NET_INVALID_HANDLE ((NetSockHandle)-1)
 
typedef enum {
    NQ_None = 0x00,
 
    NQ_SelectOnly = 0x01,
 
    NQ_AutoAccept = 0x02
} NetQueueFlags;
 
typedef enum {
    NCP_Default  = 0,   
    NCP_PreferV4 = 1,   
    NCP_PreferV6 = 2,   
    NCP_V4Only   = 3,   
    NCP_V6Only   = 4    
} NetConnectPref;
 
typedef struct NetQueueConfig {
    int32 nthreads;         
    flags_t flags;          
 
    size_t recvBufSize;     
    uint32 recvBufInitial;  
    uint32 recvBufMax;      
 
    uint32 maxflows;        
    uint32 reclaimBatch;    
    bool noReclaim;         
 
    int64 reclaimMinIdle;
 
    size_t sendHigh;        
    size_t sendLow;         
 
    int64 connectTimeout;
 
    int64 connectAttemptTimeout;
 
    NetConnectPref connectPref;
} NetQueueConfig;
 
// Backend hook called when a send leaves data queued on a socket, so the backend can arrange
// for it to drain later. Not used by application code; each backend supplies its own.
typedef void (*NetSendPumpFn)(void* ctx, NetSocket* sock);
 
// Backend hook that interrupts a parked wait so the loop recomputes its timeout. Arming a timer
// nearer than the deadline the backend is currently sleeping on calls this; without it the timer
// would not fire until whatever the backend was already waiting for woke it. Each backend supplies
// its own (a self-pipe write, a select wake socket, a posted completion).
typedef void (*NetWakeFn)(void* ctx);
 
typedef enum {
    NSO_None = 0x00,   
 
    NSO_Immediate = 0x01,
 
    NSO_Peek = 0x02
} NetSocketOpFlags;
 
typedef enum {
    NST_Stream = 1,
 
    NST_Datagram,
 
    NST_Quic
} NetSocketType;
 
typedef enum {
    NS_Init = 0,     
    NS_Connected,    
    NS_Listening,    
    NS_Connecting,   
    NS_Resolving,    
    NS_Closed        
} NetSocketState;
 
typedef enum {
    NCR_None         = 0,   
    NCR_Reclaimed    = 1,   
    NCR_AppClosed    = 2,   
    NCR_PeerClosed   = 3,   
    NCR_Error        = 4,   
    NCR_SocketClosed = 5,   
    NCR_Shutdown     = 6    
} NetCloseReason;
 
typedef enum {
    NCS_NotConnected = 0,   
    NCS_Connecting   = 1,   
    NCS_Connected    = 2,   
} NetConnectionState;
 
#define NET_FILTER_RING_SEGSZ 16384
 
typedef enum {
    NFN_None    = 0,   
    NFN_Secured = 1,   
 
    NFN_AppCustom = 1000
} NetFilterNotify;
 
typedef uint64 NetTimerId;
 
typedef enum {
    NTF_None = 0x00,
 
    NTF_Repeat = 0x01
} NetTimerFlags;
 
// Internal delivery hook for a timer armed by the framework itself rather than by an application.
// A timer with one of these attached is fired INLINE on whichever thread ran the sweep, not
// through the flow's inbox, so it must do no more than the connect state machine does: claim a
// transition and hand off. Application timers always leave this NULL and arrive as NET_Timer.
typedef void (*NetTimerFn)(NetFlow* flow, NetTimerId id, void* ctx);
 
// One armed timer, stored in the queue's binary min-heap (see NetQueue::timers). `flow` is a
// strong reference: an armed timer is a reason to keep its flow alive, and the flow drops them
// all on its terminal path so a long deadline on a dead connection cannot pin one indefinitely.
typedef struct NetTimerEntry {
    int64 deadline;    // absolute clockTimer() microseconds
    int64 interval;    // re-arm delay for NTF_Repeat; unused otherwise
    NetTimerId id;
    NetFlow* flow;     // owner, strong
    NetTimerFn fn;     // NULL -> deliver NET_Timer through the flow instead
    void* ctx;         // context for fn
    flags_t flags;     // NetTimerFlags
} NetTimerEntry;
 
typedef enum {
    NERR_None               = 0,    
    NERR_Unknown            = 1,    
    NERR_ConnectionRefused  = 2,    
    NERR_Timeout            = 3,    
    NERR_NetworkUnreachable = 4,    
    NERR_HostUnreachable    = 5,    
    NERR_NetworkDown        = 6,    
    NERR_AddressInUse       = 7,    
    NERR_AlreadyConnected   = 8,    
    NERR_NotConnected       = 9,    
    NERR_ConnectionReset    = 10,   
 
    NERR_WouldBlock         = 11,
 
    NERR_Interrupted        = 12,
} NetErrorCode;
 
typedef enum {
    NA_Unknown = 0,   
    NA_IPv4    = 1,   
    NA_IPv6    = 2    
} NetAddrType;
 
typedef struct NetAddr {
    NetAddrType type;     
    union {
        uint8 ipv4[4];    
        uint8 ipv6[16];   
    };
    uint32 scope;         
    uint16 port;          
} NetAddr;
saDeclare(NetAddr);
 
// NetAddr is a full stype so it can be used as a hashtable key -- the datagram flow table is
// keyed on it. Comparison and hashing look only at the bytes that are actually meaningful for
// the address's type, rather than doing a plain memcmp of the whole struct, which would treat
// two identical IPv4 peers as different since part of the union is left unset.
stDeclare(NetAddr);
#define SType_NetAddr                         NetAddr*
#define STStorageType_NetAddr                 NetAddr
#define STypeArg_NetAddr(type, val)           stgeneric(opaque, &(val))
#define STypeArgPtr_NetAddr(type, val)        &stgeneric(opaque, (val))
#define STypeCheckedArg_NetAddr(type, val)    stType(type), stArg(type, val)
#define STypeCheckedPtrArg_NetAddr(type, val) stType(type), stArgPtr(type, val)
 
typedef enum NetEcn {
    NET_ECN_NotEct = 0,   
    NET_ECN_Ect1   = 1,   
    NET_ECN_Ect0   = 2,   
    NET_ECN_CE     = 3    
} NetEcn;
 
typedef struct NetPktInfo {
    NetAddr local;
 
    uint8 ecn;         
    bool haveLocal;    
    bool haveEcn;      
} NetPktInfo;
 
// Hook that diverts a received datagram before it reaches the socket's flow table. cxquic installs
// one on the UDP endpoint socket behind a QUIC listener, so arriving packets are demultiplexed by
// Connection ID -- which is what lets a connection survive its peer changing address -- instead of
// by the peer address the flow table is keyed on. It takes ownership of `buf` and does its own
// submit; its return value becomes the ingest result. A socket with no hook installed is unchanged.
// `ctx` is the object the hook was installed with, referenced for the length of the call.
typedef bool (*NetDatagramRouteFn)(ObjInst* ctx, NetSocket* sock, NetAddr* peer,
                                   const NetPktInfo* info, Buffer* buf);
 
// Internally a NetMessage is any packet in flight: the library rides its own bookkeeping
// messages (NetMessageKind, net_private.h) through flow inboxes alongside data, but drainFlow()
// translates those into NetEvents and retires them before any handler runs, so an application
// never sees one -- hence the consumer-oriented documentation below.
 
typedef struct NetMessage {
    struct NetMessage* next;   // internal: intrusive link for the flow inbox / NetMsgQueue
 
    Buffer buf;
 
    // internal: how many bytes a stream receive appended to the socket's ring; overloaded as a
    // NetErrorCode by some internal message kinds
    size_t bytes;
 
    NetAddr addr;    
 
    NetPktInfo info;
 
    union {
        // internal: the accepted socket in transit to a NET_Accepted event
        NetSocket* asock;
        // internal: which timer fired, for NMSG_Timer. Shares storage with asock because the two
        // kinds are mutually exclusive, so on 64-bit this costs the message header nothing.
        NetTimerId timerId;
    };
 
    uint8 kind;      // internal: NetMessageKind (net_private.h)
    uint8 reason;    // internal: NetCloseReason, for a flow's terminal message
    uint8 flags;     // internal: NetMessageFlags (net_private.h) -- how `buf` must be reclaimed
} NetMessage;
 
// Type-specific socket buffers, selected by NetSocketType. Internal to the socket
// implementation -- application code does not touch this directly.
typedef struct NetSocketBufs {
    union {
        struct {
            BufRing recv;    // Inbound byte stream
            BufChain send;   // Outbound; owns app buffers with no copy on the way in
        } stream;
        struct {
            PrQueue send;   // NetMessage entries, each with its own destination address
        } dgram;
    };
} NetSocketBufs;
 
typedef struct NetMsgQueue {
    NetMessage* head;   
    NetMessage* tail;   
} NetMsgQueue;
 
#define netMsgQueueEmpty(q) ((q)->head == NULL)
 
_meta_inline void netMsgQueuePush(_Inout_ NetMsgQueue* q, _Inout_ NetMessage* msg)
{
    msg->next = NULL;
    if (q->tail)
        q->tail->next = msg;
    else
        q->head = msg;
    q->tail = msg;
}
 
_Check_return_ _Ret_maybenull_ _meta_inline NetMessage* netMsgQueuePop(_Inout_ NetMsgQueue* q)
{
    NetMessage* msg = q->head;
    if (!msg)
        return NULL;
 
    q->head = msg->next;
    if (!q->head)
        q->tail = NULL;
    msg->next = NULL;
    return msg;
}
 
 
 
typedef enum {
    NET_Connection = 1,
 
    NET_FilterNotify,
 
    NET_Accepted,
 
    NET_DataReceived,
 
    NET_SendReady,
 
    NET_Error,
 
    NET_FlowOpen,
 
    NET_FlowRefused,
 
    NET_FlowClosed,
 
    NET_Timer
} NetEventType;
 
typedef struct NetEvent {
    NetEventType event;   
    NetQueue* queue;      
    NetSocket* socket;    
 
    NetFlow* flow;
 
    void* ctx;
 
    union {
        struct {
            NetConnectionState state;   
            NetErrorCode err;   
        } conn;
 
        struct {
            NetSocket* newSocket;   //< Socket for newly accepted connection
        } accept;
 
        struct {
            size_t bytes;   
            size_t total;   
 
            struct NetMessage* msg;
        } recv;
 
        struct {
            NetErrorCode err;   
        } error;
 
        struct {
            NetFilterNotify notify;   
        } filter;
 
        struct {
            struct NetMessage* msg;   
        } refused;
 
        struct {
            NetCloseReason reason;   
        } closed;
 
        struct {
            NetTimerId id;   
        } timer;
    };
} NetEvent;
 
typedef void (*NetEventCB)(_In_ NetEvent* event);
 
typedef struct NetHandlers {
    NetEventCB connection;   
    NetEventCB filterNotify; 
    NetEventCB accepted;     
    NetEventCB recv;         
    NetEventCB sendReady;    
    NetEventCB flowOpen;     
    NetEventCB flowRefused;  
    NetEventCB flowClosed;   
    NetEventCB error;        
    NetEventCB timer;        
} NetHandlers;
 
typedef void (*NetConnectPrepCB)(_Inout_ NetSocket* sock, _In_opt_ void* ctx);