AxlNet -- Networking
====================

TCP sockets, UDP sockets, URL parsing, HTTP server, HTTP client, TLS,
and network utilities (IPv4 address helpers, interface enumeration, ping).

Individual headers can be included separately or use the umbrella
``<axl/axl-net.h>``.

Headers:

- ``<axl/axl-net.h>`` -- Umbrella + network utilities
- ``<axl/axl-tcp.h>`` -- TCP sockets
- ``<axl/axl-udp.h>`` -- UDP sockets
- ``<axl/axl-url.h>`` -- URL parsing
- ``<axl/axl-http-server.h>`` -- HTTP server
- ``<axl/axl-http-client.h>`` -- HTTP client
- ``<axl/axl-tls.h>`` -- TLS support (optional, requires ``AXL_TLS=1``)

Overview
--------

AXL networking is built on UEFI's TCP4/UDP4 protocol stack. The stack
must be initialized before use -- either by the UEFI Shell (``ifconfig``)
or by calling ``axl_net_auto_init``.

.. code-block:: text

   Application
   ├─ axl_http_server / axl_http_client
   ├─ axl_tcp / axl_udp
   ├─ axl_tls (optional, wraps TCP)
   └─ UEFI TCP4 / UDP4 protocols
       └─ IP4 → ARP → SNP (NIC driver)

Network Initialization
~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: c

   // Auto-init: load drivers, run DHCP, wait for IP
   if (axl_net_auto_init(SIZE_MAX, 10) != 0) {
       axl_printf("Network not available\n");
       return -1;
   }

   // Or configure static IP
   uint8_t ip[]      = {192, 168, 1, 100};
   uint8_t netmask[] = {255, 255, 255, 0};
   uint8_t gateway[] = {192, 168, 1, 1};
   axl_net_set_static_ip(0, ip, netmask, gateway);

TCP Sockets
-----------

Blocking and async TCP sockets. The blocking API is simpler; the async
API integrates with the event loop for non-blocking I/O.

**Client (blocking):**

.. code-block:: c

   AxlTcp *sock;
   if (axl_tcp_connect("192.168.1.1", 8080, &sock) == 0) {
       axl_tcp_send(sock, "GET / HTTP/1.0\r\n\r\n", 18, 5000);

       char buf[4096];
       size_t len = sizeof(buf);
       axl_tcp_recv(sock, buf, &len, 5000);

       axl_tcp_close(sock);
   }

**Server (async with event loop):**

.. code-block:: c

   void on_client(AxlTcp *client, int status, void *data) {
       if (status != 0) return;
       // handle client connection...
       axl_tcp_close(client);
   }

   AxlTcp *listener;
   axl_tcp_listen(8080, &listener);
   axl_tcp_accept_async(listener, loop, on_client, NULL);
   axl_loop_run(loop);

UDP Sockets
-----------

Fire-and-forget datagram sending and request-response patterns.

.. code-block:: c

   AXL_AUTOPTR(AxlUdpSocket) sock = NULL;
   axl_udp_open(&sock, 0);  // ephemeral port

   AxlIPv4Address dest;
   axl_ipv4_parse("192.168.1.100", dest.addr);

   // Fire-and-forget
   axl_udp_send(sock, &dest, 514, msg, msg_len);

   // Request-response (e.g., DNS query)
   char reply[512];
   size_t reply_len;
   axl_udp_sendrecv(sock, &dest, 53, query, query_len,
                    reply, sizeof(reply), &reply_len, 3000);

HTTP Server
-----------

Create an HTTP server with route handlers:

.. code-block:: c

   void on_hello(AxlHttpRequest *req, AxlHttpResponse *resp, void *data) {
       axl_http_respond_text(resp, 200, "Hello from AXL!\n");
   }

   AXL_AUTOPTR(AxlHttpServer) s = axl_http_server_new(8080);
   axl_http_server_add_route(s, "GET", "/hello", on_hello, NULL);
   axl_http_server_run(s);  // blocks, serving requests

The server supports middleware, WebSocket endpoints, authentication,
response caching, and streaming uploads. See the API reference below
for details.

HTTP Client
-----------

.. code-block:: c

   AXL_AUTOPTR(AxlHttpClient) c = axl_http_client_new();
   AXL_AUTOPTR(AxlHttpClientResponse) resp = NULL;

   if (axl_http_get(c, "http://192.168.1.1:8080/api/status", &resp) == 0) {
       axl_printf("HTTP %zu\n", resp->status_code);
       if (resp->body != NULL) {
           axl_printf("%.*s\n", (int)resp->body_size, (char *)resp->body);
       }
   }

HTTPS URLs are automatically detected when built with ``AXL_TLS=1``.

TLS (HTTPS)
-----------

Optional TLS support using mbedTLS 3.6. Build with ``AXL_TLS=1`` to
enable. See :doc:`tls` for details.

Network Utilities
-----------------

.. doxygenfile:: axl-net.h

AxlTcp
------

.. doxygenfile:: axl-tcp.h

AxlUdp
------

.. doxygenfile:: axl-udp.h

AxlUrl
------

.. doxygenfile:: axl-url.h

AxlHttpServer
--------------

.. doxygenfile:: axl-http-server.h

AxlHttpClient
--------------

.. doxygenfile:: axl-http-client.h