build out public api header

.gitignore

@@ -1,3 +1,4 @@
 build/
 build*/
 .DS_Store
+.vscode/

README.md

@@ -0,0 +1,3 @@
+# libbravais
+
+C library for working with Bravais VPN packets.

include/bravais.h

@@ -1,4 +1,170 @@
+// libbravais public api header file
+
 #ifndef BRAVAIS_H
 #define BRAVAIS_H
 
+#include <stddef.h>
+#include <stdint.h>
+
+#include "bravais/export.h" // Generated by cmake
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define BRAVAIS_VERSION_MAJOR 0
+#define BRAVAIS_VERSION_MINOR 1
+#define BRAVAIS_VERSION_PATCH 0
+#define BRAVAIS_VERSION ((BRAVAIS_VERSION_MAJOR << 16) | (BRAVAIS_VERSION_MINOR << 8) | BRAVAIS_VERSION_PATCH)
+
+#define BRAVAIS_NO_TIMEOUT UINT64_MAX
+
+typedef enum {
+    // Error codes; Generally <0 = error, 0 = success
+    BRAVAIS_EMPTY = 1, // Nothing to emit right now
+    BRAVAIS_OK = 0,
+    BRAVAIS_ERR_INVALID_ARG = -1,
+    BRAVAIS_ERR_BUFFER_TOO_SMALL = -2,
+    BRAVAIS_ERR_MALFORMED = -3,
+    BRAVAIS_ERR_OUT_OF_MEMORY = -4,
+    BRAVAIS_ERR_UNSUPPORTED = -5,
+
+    BRAVAIS_ERR_UNKNOWN = -1000
+} bravais_result_t;
+
+typedef enum {
+    BRAVAIS_ROLE_INITIATOR,
+    BRAVAIS_ROLE_RESPONDER
+} bravais_role_t;
+
+typedef enum {
+    BRAVAIS_TRANSPORT_MODE_RAW,
+    BRAVAIS_TRANSPORT_MODE_QUIC
+} bravais_transport_mode_t;
+
+typedef enum {
+    BRAVAIS_LOG_LEVEL_DEBUG,
+    BRAVAIS_LOG_LEVEL_INFO,
+    BRAVAIS_LOG_LEVEL_WARN,
+    BRAVAIS_LOG_LEVEL_ERROR
+} bravais_log_level_t;
+
+/**
+ * @brief Logging callback function type
+ * @param userData User-defined data passed to the logging function
+ * @param level The log level of the message
+ * @param message The log message string
+ */
+typedef void (*bravais_log_fn_t)(void* userData, bravais_log_level_t level, const char* message);
+
+typedef struct {
+    bravais_role_t role;
+    bravais_transport_mode_t transportMode;
+    bravais_log_fn_t logFn;
+    void* logUserData;
+
+    // TODO: Add more configuration options here as needed
+} bravais_config_t;
+
+typedef struct bravais_conn bravais_conn_t; // Opaque connection type
+
+// =============================================================================
+// Public API functions
+// =============================================================================
+
+/**
+ * @brief Runtime library version number, packed as (major << 16) | (minor << 8) | patch
+ * @return The version number, packed as (major << 16) | (minor << 8) | patch
+ */
+BRAVAIS_API uint32_t bravais_version(void);
+
+/**
+ * @brief Initialize the config struct with defaults for all optional fields.
+ * @param config Pointer to a bravais_config_t struct to initialize.
+ * @return BRAVAIS_OK on success, or BRAVAIS_ERR_INVALID_ARG if the config pointer is NULL.
+ * @attention The caller must still set role and transportMode manually.
+ */
+BRAVAIS_API bravais_result_t bravais_config_init(const bravais_config_t* config);
+
+/**
+ * @brief Create a new connection.
+ * @param config The configuration to use for the new connection.
+ * @param outConn A pointer to a bravais_conn_t pointer that will be set to the new connection. Set to NULL on failure.
+ * @return BRAVAIS_OK on success, BRAVAIS_ERR_INVALID_ARG, or BRAVAIS_ERR_OUT_OF_MEMORY.
+ * @attention The config is copied. The caller may reuse or discard it afterwards.
+ */
+BRAVAIS_API bravais_result_t bravais_conn_create(const bravais_config_t* config, bravais_conn_t** outConn);
+
+/**
+ * @brief Destroy a connection.
+ * @param conn The connection to destroy.
+ * @attention NULL is a no-op.
+ */
+BRAVAIS_API void bravais_conn_destroy(bravais_conn_t* conn);
+
+/**
+ * @brief Feed one datagram received from the network.
+ * @param conn The connection to feed the datagram to.
+ * @param data The datagram data received from the network.
+ * @param dataLen The length of the datagram data.
+ * @param nowMs The current time in milliseconds (unix epoch).
+ * @return BRAVAIS_OK on success, BRAVAIS_ERR_INVALID_ARG, or BRAVAIS_ERR_MALFORMED (datagram is malformed).
+ * @attention Any resulting output is queued. Drain it with the poll functions.
+ */
+BRAVAIS_API bravais_result_t bravais_recv_datagram(bravais_conn_t* conn, const uint8_t* data, size_t dataLen, uint64_t nowMs);
+
+/**
+ * @brief Submit one plaintext packet read from the TUN device.
+ * @param conn The connection to submit the packet to.
+ * @param data The packet data read from the TUN device.
+ * @param dataLen The length of the packet data.
+ * @param nowMs The current time in milliseconds (unix epoch).
+ * @return BRAVAIS_OK on success, or BRAVAIS_ERR_INVALID_ARG.
+ * @attention The packet is encrypted and queued for sending. Drain it with bravais_poll_datagram().
+ */
+BRAVAIS_API bravais_result_t bravais_send_packet(bravais_conn_t* conn, const uint8_t* data, size_t dataLen, uint64_t nowMs);
+
+/**
+ * @brief Take the next datagram to send to the network, if any.
+ * @param conn The connection to poll for datagrams.
+ * @param out A buffer to write the datagram to.
+ * @param outCap The capacity of the output buffer.
+ * @param outLen A pointer to a size_t that will be set to the length of the datagram written to the output buffer.
+ * @return BRAVAIS_OK on success, BRAVAIS_EMPTY if no datagram is available (this is NOT an error), or BRAVAIS_ERR_BUFFER_TOO_SMALL.
+ * @attention The caller must provide a buffer large enough to hold the datagram.
+ */
+BRAVAIS_API bravais_result_t bravais_poll_datagram(bravais_conn_t* conn, uint8_t* out, size_t outCap, size_t* outLen);
+
+/**
+ * @brief Take the next decrypted packet to write to the TUN device, if any.
+ * @param conn The connection to poll for packets.
+ * @param out A buffer to write the packet to.
+ * @param outCap The capacity of the output buffer.
+ * @param outLen A pointer to a size_t that will be set to the length of the packet written to the output buffer.
+ * @return BRAVAIS_OK on success, BRAVAIS_EMPTY if no packet is available (this is NOT an error), or BRAVAIS_ERR_BUFFER_TOO_SMALL.
+ * @attention The caller must provide a buffer large enough to hold the packet.
+ * @attention Same buffer semantics as bravais_poll_datagram().
+ *
+ */
+BRAVAIS_API bravais_result_t bravais_poll_plaintext(bravais_conn_t* conn, uint8_t* out, size_t outCap, size_t* outLen);
+
+/**
+ * @brief Earliest time the connection needs bravais_on_timeout() called.
+ * @return Absolute deadline in milliseconds (unix epoch) for the next timeout, or BRAVAIS_NO_TIMEOUT if no timeout is needed.
+ */
+BRAVAIS_API uint64_t bravais_get_next_timeout(bravais_conn_t* conn);
+
+/**
+ * @brief Run any timers due at nowMs.
+ * @param conn The connection to run timers for.
+ * @param nowMs The current time in milliseconds (unix epoch).
+ * @return BRAVAIS_OK on success, or BRAVAIS_ERR_INVALID_ARG.
+ * @attention Safe to call early. No-op if no timers are due yet.
+ */
+BRAVAIS_API bravais_result_t bravais_on_timeout(bravais_conn_t* conn, uint64_t nowMs);
+
+#ifdef __cplusplus
+}
+#endif
+
 #endif // BRAVAIS_H

src/bravais_internal.h

@@ -0,0 +1,4 @@
+#ifndef BRAVAIS_INTERNAL_H
+#define BRAVAIS_INTERNAL_H
+
+#endif // BRAVAIS_INTERNAL_H