// Part of JoeyLib, Copyright (c) 2026 Scott Duensing, under the MIT License.
// See LICENSE.md for license information.
// SPDX-License-Identifier: MIT
//
// gateNet.h - sockets, waits, and the clock shared by the gates' serial and
// network peers (tests/gate/serialLoopPeer.c and the rest), and received
// bytes shown printably in their logs. Their command lines are gateArg's,
// and gateTextFind finds bytes in what they receive.

#ifndef GATE_NET_H
#define GATE_NET_H

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>

#include <netinet/in.h>

// gateNetRecv: nothing arrived in time, or the stream ended (or failed).
#define GATE_NET_IDLE       0
#define GATE_NET_CLOSED     (-1)

// The only address the peers listen on or connect to, and the backlog a
// peer that takes one connection listens with.
#define GATE_NET_HOST       "127.0.0.1"
#define GATE_NET_ONE_PEER   1

// A connection on listener within seconds (its address in from, unless
// NULL); -1 when none came. A failed accept ends the tool.
int gateNetAccept(int listener, double seconds, struct sockaddr_in *from);

// Listen on port for one connection within seconds, then stop listening;
// -1 when none came.
int gateNetAcceptOne(uint16_t port, double seconds);

// A socket listening on GATE_NET_HOST:port (SO_REUSEADDR) with backlog
// connections waiting at most; a port it cannot have ends the tool.
int gateNetListen(uint16_t port, int backlog);

// Seconds on a clock that never steps.
double gateNetNow(void);

// Up to cap bytes from fd, waiting at most seconds: their count,
// GATE_NET_IDLE, or GATE_NET_CLOSED (errno 0 at the end of the stream,
// else what failed).
int32_t gateNetRecv(int fd, uint8_t *buf, size_t cap, double seconds);

// Every byte to fd; false (errno set) when it fails.
bool gateNetSendAll(int fd, const void *data, size_t len);

// len bytes in double quotes: printable ASCII as itself, a backslash or a
// double quote escaped with a backslash, \n \r \t, and any other byte as
// \xNN.
void gateNetShowBytes(FILE *out, const void *data, size_t len);

// Sleep seconds (none at all for 0 or less).
void gateNetSleep(double seconds);

// Each peer's first act: the name its messages begin with, stdout written a
// line at a time (so a killed peer's log is whole), and a closed connection
// an error from send rather than a SIGPIPE.
void gateNetStart(const char *toolName);

// Whether fd is ready for events (poll's) within seconds.
bool gateNetWait(int fd, short events, double seconds);

#endif