Edge Net

https://github.com/sysgrok/edge-net
Admin
Edge Net provides async, `no_std`, and no-alloc implementations of various network protocols,...
Tokens:183,386
Snippets:1,191
Trust Score:7.8
License:Apache-2.0
Update:6 days ago
Show doc for...
Tokens:
Raw
### Usage example for run

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-captive.md

Example of setting up and running the DNS responder using the IO module.

```rust
use core::net::{IpAddr, Ipv4Addr, SocketAddr};
use core::time::Duration;
use edge_captive::io::run;

let stack = edge_nal_std::Stack::new();
let mut tx_buf = [0; 1500];
let mut rx_buf = [0; 1500];

// Port 53 needs root; examples use 8853.
let local = SocketAddr::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), 8853);

run(
    &stack,
    local,
    &mut tx_buf,
    &mut rx_buf,
    Ipv4Addr::new(192, 168, 0, 1), // IP every A query resolves to
    Duration::from_secs(60),       // reply TTL
)
.await?;
```

--------------------------------

### Example: sequential GET requests with Connection

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-http-io.md

Shows how to create a Connection, initiate requests, read responses, and complete the cycle. The example fetches /ip and /headers from httpbin.org, reading the response body into a Vec. Requires T: TcpConnect + Dns and uses embedded_io_async::Read.

```rust
use edge_http::io::client::Connection;
use edge_http::Method;
use edge_nal::{AddrType, Dns, TcpConnect};
use embedded_io_async::Read;

async fn read<T: TcpConnect + Dns>(
    stack: &T, buf: &mut [u8],
) -> Result<(), edge_http::io::Error<<T as TcpConnect>::Error>>
where <T as Dns>::Error: Into<<T as TcpConnect>::Error>,
{
    let ip = stack.get_host_by_name("httpbin.org", AddrType::IPv4).await
        .map_err(|e| edge_http::io::Error::Io(e.into()))?;

    let mut conn: Connection<_> = Connection::new(buf, stack, core::net::SocketAddr::new(ip, 80));

    for uri in ["/ip", "/headers"] {
        conn.initiate_request(true, Method::Get, uri, &[("Host", "httpbin.org")]).await?;
        conn.initiate_response().await?;

        let mut result = Vec::new();
        let mut buf = [0_u8; 1024];
        loop {
            let len = conn.read(&mut buf).await?;
            if len == 0 { break; }
            result.extend_from_slice(&buf[0..len]);
        }
        conn.complete().await?;
    }
    Ok(())
}
```

--------------------------------

### Lease Usage Example

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-dhcp-io.md

Example demonstrating how to initialize a client, bind a socket, and manage a lease using Lease::new and Lease::keep.

```rust
use edge_dhcp::client::Client;
use edge_dhcp::io::{client::Lease, DEFAULT_CLIENT_PORT, DEFAULT_SERVER_PORT};
use edge_nal::RawBind;
use edge_raw::io::RawSocket2Udp;

let mut client = Client::new(rand::rng(), [0x4c, 0xcc, 0x6a, 0xa2, 0x23, 0xf5]);
let stack = edge_nal_std::Interface::new(2); // interface index
let mut buf = [0; 1500];

let mut socket: RawSocket2Udp<_> = RawSocket2Udp::new(
    stack.bind().await?,
    Some(SocketAddrV4::new(Ipv4Addr::UNSPECIFIED, DEFAULT_CLIENT_PORT)),
    Some(SocketAddrV4::new(Ipv4Addr::UNSPECIFIED, DEFAULT_SERVER_PORT)),
    [255; 6],
);

let (mut lease, options) = Lease::new(&mut client, &mut socket, &mut buf).await?;
lease.keep(&mut client, &mut socket, &mut buf).await?;
```

--------------------------------

### Usage example (server)

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-http-io.md

Example of implementing the Handler trait and running a server with DefaultServer.

```APIDOC
## Usage example (server)

### Description
Example of implementing the Handler trait and running a server with DefaultServer.

### Code
```rust
use core::fmt::{Debug, Display};
use edge_http::io::server::{Connection, DefaultServer, Handler};
use edge_http::io::Error;
use edge_http::Method;
use edge_nal::TcpBind;

struct HttpHandler;

impl Handler for HttpHandler {
    type Error<E> = Error<E> where E: Debug;

    async fn handle<T, const N: usize>(
        &self,
        _task_id: impl Display + Copy,
        conn: &mut Connection<'_, T, N>,
    ) -> Result<(), Self::Error<T::Error>>
    where T: embedded_io_async::Read + embedded_io_async::Write,
    {
        let headers = conn.headers()?;
        if headers.method != Method::Get {
            conn.initiate_response(405, Some("Method Not Allowed"), &[]).await?;
        } else if headers.path != "/" {
            conn.initiate_response(404, Some("Not Found"), &[]).await?;
        } else {
            conn.initiate_response(200, Some("OK"), &[("Content-Type", "text/plain")]).await?;
            conn.write_all(b"Hello from edge-http!").await?;
        }
        Ok(())
    }
}

async fn run(server: &mut DefaultServer) -> Result<(), anyhow::Error> {
    let acceptor = edge_nal_std::Stack::new().bind("0.0.0.0:8881".parse().unwrap()).await?;
    server.run(None, acceptor, HttpHandler).await?;
    Ok(())
}
```
```

--------------------------------

### Usage example for TCP and DNS

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-nal-std.md

Demonstrates how to initialize the stack, resolve a hostname, and connect to a TCP server.

```rust
use edge_nal::{Dns, TcpConnect, AddrType};
use edge_nal_std::Stack;

let stack = Stack::new();   // or Stack::default()

let ip = stack.get_host_by_name("httpbin.org", AddrType::IPv4).await?;
let mut tcp = stack.connect(core::net::SocketAddr::new(ip, 80)).await?;
```

--------------------------------

### Run an mDNS responder example

Source: https://github.com/sysgrok/edge-net/blob/master/edge-mdns/README.md

This example demonstrates how to set up and run an mDNS responder that makes a host addressable via a .local domain name. It uses the edge-nal stack and requires defining the local IP address and hostname.

```rust
use core::net::{Ipv4Addr, Ipv6Addr};

use edge_mdns::buf::{BufferAccess, VecBufAccess};
use edge_mdns::domain::base::Ttl;
use edge_mdns::io::{self, MdnsIoError, DEFAULT_SOCKET};
use edge_mdns::{host::Host, HostAnswersMdnsHandler};
use edge_nal::{UdpBind, UdpSplit};

use embassy_sync::blocking_mutex::raw::NoopRawMutex;
use embassy_sync::signal::Signal;

use log::*;

// Change this to the IP address of the machine where you'll run this example
const OUR_IP: Ipv4Addr = Ipv4Addr::new(127, 0, 0, 1);

const OUR_NAME: &str = "mypc";

fn main() {
    env_logger::init_from_env(
        env_logger::Env::default().filter_or(env_logger::DEFAULT_FILTER_ENV, "info"),
    );

    let stack = edge_nal_std::Stack::new();

    let (recv_buf, send_buf) = (
        VecBufAccess::<NoopRawMutex, 1500>::new(),
        VecBufAccess::<NoopRawMutex, 1500>::new(),
    );

    futures_lite::future::block_on(run::<edge_nal_std::Stack, _, _>(
        &stack, &recv_buf, &send_buf, OUR_NAME, OUR_IP,
    ))
    .unwrap();
}

async fn run<T, RB, SB>(
    stack: &T,
    recv_buf: RB,
    send_buf: SB,
    our_name: &str,
    our_ip: Ipv4Addr,
) -> Result<(), MdnsIoError<T::Error>>
where
    T: UdpBind,
    RB: BufferAccess<[u8]>,
    SB: BufferAccess<[u8]>,
{
    info!("About to run an mDNS responder for our PC. It will be addressable using {our_name}.local, so try to `ping {our_name}.local`.");

    let mut socket = io::bind(stack, DEFAULT_SOCKET, Some(Ipv4Addr::UNSPECIFIED), Some(0)).await?;

    let (recv, send) = socket.split();

    let host = Host {
        hostname: our_name,
        ipv4: our_ip,
        ipv6: Ipv6Addr::UNSPECIFIED,
        ttl: Ttl::from_secs(60),
    };

    // A way to notify the mDNS responder that the data in `Host` had changed
    // We don't use it in this example, because the data is hard-coded
    let signal = Signal::<NoopRawMutex, _>::new();

    let mdns = io::Mdns::new(
        Some(Ipv4Addr::UNSPECIFIED),
        Some(0),
        recv,
        send,
        recv_buf,
        send_buf,
        rand::rng(),
        &signal,
    );

    mdns.run(HostAnswersMdnsHandler::new(&host)).await
}
```

--------------------------------

### DHCP Client Usage Example

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-dhcp.md

Demonstrates initializing a client, sending a discover packet, and processing an offer response.

```rust
use edge_dhcp::client::Client;
use edge_dhcp::{DhcpOption, MessageType, Options};

let mut client = Client::new(rand::rng(), [0x4c, 0xcc, 0x6a, 0xa2, 0x23, 0xf5]);
let mut opt_buf = Options::buf();
let (discover, xid) = client.discover(&mut opt_buf, 0, None);

// ... transmit `discover` and receive a reply, then:
if client.is_offer(&reply, xid) {
    // Offer received; request the offered IP
    let mut opt_buf = Options::buf();
    let (request, xid) = client.request(&mut opt_buf, 0, reply.yiaddr, true);
}
```

--------------------------------

### HTTPS server usage example

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-nal-tls.md

Demonstrates how to configure a server session and accept connections using TlsAcceptor.

```rust
use edge_nal_tls::{mbedtls, TlsAcceptor};
use edge_nal::TcpBind;

let mut cfg = mbedtls::ServerSessionConfig::default();
cfg.cert = /* PEM certificate */;
cfg.key  = /* PEM private key */;

let acceptor = TcpBind::bind(&stack, addr).await?;
let tls_acceptor = TlsAcceptor::new(tls_ref, acceptor, &cfg);

// tls_acceptor implements edge_nal::TcpAccept; pass it to
// edge_http::io::server::Server::run
server.run(None, tls_acceptor, handler).await?;
```

--------------------------------

### server::run usage example

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-dhcp-io.md

Example of running the DHCP server using a standard UDP stack, demonstrating binding to the default server port and executing the run loop.

```rust
use core::net::{Ipv4Addr, SocketAddr};
use edge_dhcp::io::{self, DEFAULT_SERVER_PORT};
use edge_dhcp::server::{Server, ServerOptions};
use edge_nal::UdpBind;

let stack = edge_nal_std::Stack::new();
let mut buf = [0; 1500];
let ip = Ipv4Addr::new(192, 168, 0, 1);

let mut socket = stack.bind(SocketAddr::from((Ipv4Addr::UNSPECIFIED, DEFAULT_SERVER_PORT))).await?;
let mut gw_buf = [Ipv4Addr::UNSPECIFIED];

io::server::run(
    &mut Server::<_, 64>::new_with_et(ip),
    &ServerOptions::new(ip, Some(&mut gw_buf)),
    &mut socket,
    &mut buf,
).await?;
```

--------------------------------

### HTTP server implementation

Source: https://github.com/sysgrok/edge-net/blob/master/edge-http/README.md

An example of an HTTP server using edge-http to listen on a port and handle GET requests with a custom handler.

```rust
use core::fmt::{Debug, Display};

use edge_http::io::server::{Connection, DefaultServer, Handler};
use edge_http::io::Error;
use edge_http::Method;
use edge_nal::TcpBind;

use embedded_io_async::{Read, Write};

use log::info;

fn main() {
    env_logger::init_from_env(
        env_logger::Env::default().filter_or(env_logger::DEFAULT_FILTER_ENV, "info"),
    );

    let mut server = DefaultServer::new();

    futures_lite::future::block_on(run(&mut server)).unwrap();
}

pub async fn run(server: &mut DefaultServer) -> Result<(), anyhow::Error> {
    let addr = "0.0.0.0:8881";

    info!("Running HTTP server on {addr}");

    let acceptor = edge_nal_std::Stack::new()
        .bind(addr.parse().unwrap())
        .await?;

    server.run(None, acceptor, HttpHandler).await?;

    Ok(())
}

struct HttpHandler;

impl Handler for HttpHandler {
    type Error<E>
        = Error<E>
    where
        E: Debug;

    async fn handle<T, const N: usize>(
        &self,
        _task_id: impl Display + Copy,
        conn: &mut Connection<'_, T, N>,
    ) -> Result<(), Self::Error<T::Error>>
    where
        T: Read + Write,
    {
        let headers = conn.headers()?;

        if headers.method != Method::Get {
            conn.initiate_response(405, Some("Method Not Allowed"), &[])
                .await?;
        } else if headers.path != "/" {
            conn.initiate_response(404, Some("Not Found"), &[]).await?;
        } else {
            conn.initiate_response(200, Some("OK"), &[("Content-Type", "text/plain")])
                .await?;

            conn.write_all(b"Hello world!").await?;
        }

        Ok(())
    }
}
```

--------------------------------

### Usage example for OtUdpStack

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-nal-openthread.md

Demonstrates how to initialize the stack, bind a socket, and perform send/receive operations.

```rust
use edge_nal::{UdpBind, UdpReceive, UdpSend};
use edge_nal_openthread::OtUdpStack;
use openthread::OpenThread;

let ot: OpenThread<'_> = /* from the OpenThread runtime */;
let stack = OtUdpStack::new(ot);

let mut socket = stack.bind("[::]:0".parse().unwrap()).await?;

socket.send(remote_addr, b"hello").await?;
let (len, from) = socket.receive(&mut buf).await?;
```

--------------------------------

### HTTP client implementation

Source: https://github.com/sysgrok/edge-net/blob/master/edge-http/README.md

An example of an HTTP client using edge-http to connect to httpbin.org and perform GET requests for specific URIs.

```rust
use core::net::SocketAddr;

use embedded_io_async::Read;

use edge_http::io::{client::Connection, Error};
use edge_http::Method;
use edge_nal::{AddrType, Dns, TcpConnect};

use log::*;

fn main() {
    env_logger::init_from_env(
        env_logger::Env::default().filter_or(env_logger::DEFAULT_FILTER_ENV, "info"),
    );

    let stack: edge_nal_std::Stack = Default::default();

    let mut buf = [0_u8; 8192];

    futures_lite::future::block_on(read(&stack, &mut buf)).unwrap();
}

async fn read<T: TcpConnect + Dns>(
    stack: &T,
    buf: &mut [u8],
) -> Result<(), Error<<T as TcpConnect>::Error>>
where
    <T as Dns>::Error: Into<<T as TcpConnect>::Error>,
{
    info!("About to open an HTTP connection to httpbin.org port 80");

    let ip = stack
        .get_host_by_name("httpbin.org", AddrType::IPv4)
        .await
        .map_err(|e| Error::Io(e.into()))?;

    let mut conn: Connection<_> = Connection::new(buf, stack, SocketAddr::new(ip, 80));

    for uri in ["/ip", "/headers"] {
        request(&mut conn, uri).await?;
    }

    Ok(())
}

async fn request<const N: usize, T: TcpConnect>(
    conn: &mut Connection<'_, T, N>,
    uri: &str,
) -> Result<(), Error<T::Error>> {
    conn.initiate_request(true, Method::Get, uri, &[("Host", "httpbin.org")])
        .await?;

    conn.initiate_response().await?;

    let mut result = Vec::new();

    let mut buf = [0_u8; 1024];

    loop {
        let len = conn.read(&mut buf).await?;

        if len > 0 {
            result.extend_from_slice(&buf[0..len]);
        } else {
            break;
        }
    }

    info!(
        "Request to httpbin.org, URI \"{}\" returned:\nBody:\n=================\n{}\n=================\n\n\n\n",
        uri,
        core::str::from_utf8(&result).unwrap());

    Ok(())
}
```

--------------------------------

### HTTPS client usage example

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-nal-tls.md

Demonstrates how to configure a client session and connect using TlsConnector.

```rust
use edge_nal::{TcpConnect, Dns, AddrType};
use edge_nal_tls::{mbedtls, TlsConnector};

// Build an mbedtls client config (CA bundle, etc.)
let mut cfg = mbedtls::ClientSessionConfig::default();
cfg.ca = mbedtls::CaBundle::Roots(...);   // e.g. from certs/ca-bundle-small.pem

// TLS reference from the mbedtls instance
let tls = mbedtls::TlsReference::new(...);

// Wrap an edge-nal-std Stack connector:
let connector = TlsConnector::new(tls, stack, &cfg);

let socket = connector.connect((ip, 443).into()).await?;
// `socket` is a TlsSocket; it can be handed to edge_http::io::client::Connection
```

--------------------------------

### DHCP Server Implementation

Source: https://github.com/sysgrok/edge-net/blob/master/edge-dhcp/README.md

Demonstrates how to implement a DHCP server. This example also requires root privileges to bind to the network interface.

```rust
//! NOTE: Run this example with `sudo` to be able to bind to the interface, as it uses raw sockets which require root privileges.

use core::net::{Ipv4Addr, SocketAddrV4};

use edge_dhcp::io::{self, DEFAULT_CLIENT_PORT, DEFAULT_SERVER_PORT};
use edge_dhcp::server::{Server, ServerOptions};
use edge_nal::RawBind;
use edge_raw::io::RawSocket2Udp;

fn main() {
    env_logger::init_from_env(
        env_logger::Env::default().filter_or(env_logger::DEFAULT_FILTER_ENV, "info"),
    );

    futures_lite::future::block_on(run(
        0, // The interface index of the interface (e.g. eno0) to use; run `ip addr` to see it
    ))
    .unwrap();
}

async fn run(if_index: u32) -> Result<(), anyhow::Error> {
    let stack = edge_nal_std::Interface::new(if_index);

    let mut buf = [0; 1500];

    let ip = Ipv4Addr::new(192, 168, 0, 1);

    let mut socket: RawSocket2Udp<_> = RawSocket2Udp::new(
        stack.bind().await?,
        Some(SocketAddrV4::new(
            Ipv4Addr::UNSPECIFIED,
            DEFAULT_SERVER_PORT,
        )),
        Some(SocketAddrV4::new(
            Ipv4Addr::UNSPECIFIED,
            DEFAULT_CLIENT_PORT,
        )),
        [0; 6],
    );

    let mut gw_buf = [Ipv4Addr::UNSPECIFIED];

    io::server::run(
        &mut Server::<_, 64>::new_with_et(ip), // Will give IP addresses in the range 192.168.0.50 - 192.168.0.200, subnet 255.255.255.0
        &ServerOptions::new(ip, Some(&mut gw_buf)),
        &mut socket,
        &mut buf,
    )
    .await?;

    Ok(())
}
```

--------------------------------

### DHCP server request handling example

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-dhcp.md

Demonstrates initializing the server and processing incoming DHCP packets using handle_request.

```rust
use edge_dhcp::server::{Server, ServerOptions};

let mut server = Server::<_, 64>::new_with_et(Ipv4Addr::new(192, 168, 0, 1));
let mut gw_buf = [Ipv4Addr::UNSPECIFIED];
let server_options = ServerOptions::new(Ipv4Addr::new(192, 168, 0, 1), Some(&mut gw_buf));

// Per received packet:
let mut opt_buf = Options::buf();
if let Some(reply) = server.handle_request(&mut opt_buf, &server_options, &request) {
    let bytes = reply.encode(buf).unwrap();
    // ... send `bytes` back to the client
}
```

--------------------------------

### Usage example (responder + service)

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-mdns.md

Demonstrates how to create a Host and Service, then build a HostAnswersMdnsHandler that can be passed to edge_mdns::io::Mdns::run to answer queries for both host and service.

```APIDOC
## Usage example (responder + service)

### Description
Demonstrates how to create a Host and Service, then build a HostAnswersMdnsHandler that can be passed to edge_mdns::io::Mdns::run to answer queries for both host and service.

### Code Example
```rust
use core::net::{Ipv4Addr, Ipv6Addr};
use edge_mdns::domain::base::Ttl;
use edge_mdns::host::{Host, Service, ServiceAnswers};
use edge_mdns::{HostAnswersMdnsHandler};

let host = Host {
    hostname: "mypc",
    ipv4: Ipv4Addr::new(192, 168, 1, 2),
    ipv6: Ipv6Addr::UNSPECIFIED,
    ttl: Ttl::from_secs(60),
};

let service = Service {
    name: "my-service",
    priority: 1,
    weight: 5,
    service: "_https",
    protocol: "_tcp",
    port: 443,
    service_subtypes: &[],
    txt_kvs: &[],
};

// Build a handler chain that answers queries for both host and service:
let handler = HostAnswersMdnsHandler::new(ServiceAnswers::new(&host, &service));
// `handler` can now be passed to `edge_mdns::io::Mdns::run`.
```
```

--------------------------------

### Compute-only usage example

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-captive.md

Example of using the core reply function without IO.

```rust
use core::time::Duration;
use edge_captive::reply;

let request = /* a raw DNS query packet */;
let ip = [192, 168, 0, 1];
let mut buf = [0u8; 512];

let len = reply(request, &ip, Duration::from_secs(60), &mut buf)?;
// `buf[..len]` is the DNS response (an A record for the queried name)
```

--------------------------------

### Server usage example

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-ws.md

Demonstrates sending frames from a server, noting that servers must not mask their frames.

```rust
use edge_ws::{FrameHeader, FrameType};

// `socket` is the stream after `edge_http` server accepted the upgrade.
// Servers must NOT mask their frames:

let header = FrameHeader {
    frame_type: FrameType::Text(false),
    payload_len: data.len() as _,
    mask_key: None,  // server → client frames are unmasked
};
header.send(&mut socket).await?;
header.send_payload(&mut socket, data).await?;
```

--------------------------------

### GET / (WebSocket Upgrade)

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/endpoints.md

Initiates a WebSocket connection via an HTTP GET upgrade request. The server validates the upgrade headers and responds with a 101 status and the Sec-WebSocket-Accept value.

```APIDOC
## [GET] WebSocket Upgrade

### Description
Initiates a WebSocket connection via an HTTP GET upgrade request. The server validates the upgrade headers and responds with a 101 status and the Sec-WebSocket-Accept value.

### Method
GET

### Endpoint
HTTP Upgrade (WebSocket)

### Parameters
#### Request Headers
- **Connection** (string) - Required - Must be `Upgrade`
- **Upgrade** (string) - Required - Must be `websocket`
- **Sec-WebSocket-Version** (string) - Optional - Default `13`
- **Sec-WebSocket-Key** (string) - Required - Base64 of a 16-byte nonce

### Response
#### Success Response (101)
- **Connection** (string) - `Upgrade`
- **Upgrade** (string) - `websocket`
- **Sec-WebSocket-Accept** (string) - Base64 SHA-1 of key + GUID `258EAFA5-E914-47DA-95CA-C5AB0DC85B11`

### Validation
- `ws::upgrade_response_headers` returns `UpgradeError::{NoVersion, NoSecKey}` on missing headers
- `is_upgrade_accepted` requires `code == 101` and correct accept value

### Frames
- RFC 6455 framing; client-to-server frames masked, server-to-client unmasked
- Fragmentation via `FrameType::Continue`
- Control frames (`Ping`, `Pong`, `Close`) are decoded/encoded but not auto-replied
```

--------------------------------

### HTTP server usage example

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-http-io.md

Demonstrates implementing the Handler trait to process requests and running a DefaultServer instance.

```rust
use core::fmt::{Debug, Display};
use edge_http::io::server::{Connection, DefaultServer, Handler};
use edge_http::io::Error;
use edge_http::Method;
use edge_nal::TcpBind;

struct HttpHandler;

impl Handler for HttpHandler {
    type Error<E> = Error<E> where E: Debug;

    async fn handle<T, const N: usize>(
        &self,
        _task_id: impl Display + Copy,
        conn: &mut Connection<'_, T, N>,
    ) -> Result<(), Self::Error<T::Error>>
    where T: embedded_io_async::Read + embedded_io_async::Write,
    {
        let headers = conn.headers()?;
        if headers.method != Method::Get {
            conn.initiate_response(405, Some("Method Not Allowed"), &[]).await?;
        } else if headers.path != "/" {
            conn.initiate_response(404, Some("Not Found"), &[]).await?;
        } else {
            conn.initiate_response(200, Some("OK"), &[("Content-Type", "text/plain")]).await?;
            conn.write_all(b"Hello from edge-http!").await?;
        }
        Ok(())
    }
}

async fn run(server: &mut DefaultServer) -> Result<(), anyhow::Error> {
    let acceptor = edge_nal_std::Stack::new().bind("0.0.0.0:8881".parse().unwrap()).await?;
    server.run(None, acceptor, HttpHandler).await?;
    Ok(())
}
```

--------------------------------

### Configure mDNS responder with host and service

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-mdns.md

This example demonstrates how to define a host and service, then create a HostAnswersMdnsHandler to respond to mDNS queries.

```rust
use core::net::{Ipv4Addr, Ipv6Addr};
use edge_mdns::domain::base::Ttl;
use edge_mdns::host::{Host, Service, ServiceAnswers};
use edge_mdns::{HostAnswersMdnsHandler};

let host = Host {
    hostname: "mypc",
    ipv4: Ipv4Addr::new(192, 168, 1, 2),
    ipv6: Ipv6Addr::UNSPECIFIED,
    ttl: Ttl::from_secs(60),
};

let service = Service {
    name: "my-service",
    priority: 1,
    weight: 5,
    service: "_https",
    protocol: "_tcp",
    port: 443,
    service_subtypes: &[],
    txt_kvs: &[],
};

// Build a handler chain that answers queries for both host and service:
let handler = HostAnswersMdnsHandler::new(ServiceAnswers::new(&host, &service));
// `handler` can now be passed to `edge_mdns::io::Mdns::run`.
```

--------------------------------

### Usage example

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-nal-openthread.md

Demonstrates how to use the OtUdpStack to bind a UDP socket and send/receive data over a Thread network.

```APIDOC
## Usage example

### Description
Example of using `OtUdpStack` to bind a socket and send/receive UDP data.

### Prerequisites
- An `OpenThread` instance.
- The `edge_nal` traits `UdpBind`, `UdpReceive`, `UdpSend` in scope.

### Example
```rust
use edge_nal::{UdpBind, UdpReceive, UdpSend};
use edge_nal_openthread::OtUdpStack;
use openthread::OpenThread;

let ot: OpenThread<'_> = /* from the OpenThread runtime */;
let stack = OtUdpStack::new(ot);

let mut socket = stack.bind("[::]:0".parse().unwrap()).await?;

socket.send(remote_addr, b"hello").await?;
let (len, from) = socket.receive(&mut buf).await?;
```

### Notes
- The `bind` method is from the `UdpBind` trait.
- The `send` and `receive` methods are from the `UdpSend` and `UdpReceive` traits respectively.
- All methods are async and require an embedded async executor.
```

--------------------------------

### Usage example for raw sockets

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-nal-std.md

Demonstrates binding to a raw socket on a specific interface index. This operation requires root privileges.

```rust
use edge_nal::RawBind;
use edge_nal_std::Interface;

let stack = Interface::new(2); // interface index, e.g. eno0
let mut raw = stack.bind().await?; // requires root privileges
```

--------------------------------

### Run Websocket client against local server

Source: https://github.com/sysgrok/edge-net/blob/master/edge-ws/README.md

Command to run the Websocket client example against a local server instead of the public echo server.

```sh
./target/debug/examples/ws_client 1
```

--------------------------------

### Client usage example

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-ws.md

Demonstrates sending and receiving frames after an HTTP WebSocket upgrade, noting that clients must mask their frames.

```rust
use edge_ws::{FrameHeader, FrameType};

// `socket` is the TCP stream returned by e.g. `edge_http::io::client::Connection::release`
// after a successful WS upgrade.

let header = FrameHeader {
    frame_type: FrameType::Text(false),
    payload_len: "Hello world!".len() as _,
    mask_key: Some(0xdead_beef),  // clients must mask
};
header.send(&mut socket).await?;
header.send_payload(&mut socket, b"Hello world!").await?;

let header = FrameHeader::recv(&mut socket).await?;
let payload = header.recv_payload(&mut socket, buf).await?;
match header.frame_type {
    FrameType::Text(_) => { /* echo received */ }
    FrameType::Close => { /* peer closed */ }
    _ => {}
}
```

--------------------------------

### Connection::initiate_ws_upgrade_request

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-http-io.md

Convenience method for a GET request with WebSocket upgrade headers.

```APIDOC
## Connection::initiate_ws_upgrade_request

### Description
Convenience method for a GET request with WebSocket upgrade headers.

### Method
initiate_ws_upgrade_request

### Signature
pub async fn initiate_ws_upgrade_request(&mut self, host: Option<&str>, origin: Option<&str>, uri: &str, version: Option<&str>, nonce: &[u8; NONCE_LEN], nonce_base64_buf: &mut [u8; MAX_BASE64_KEY_LEN]) -> Result<(), Error<T::Error>>

### Parameters
- **host** (Option<&str>) - Required - Host header value.
- **origin** (Option<&str>) - Required - Origin header value.
- **uri** (&str) - Required - Request URI.
- **version** (Option<&str>) - Required - WebSocket version.
- **nonce** (&[u8; NONCE_LEN]) - Required - WebSocket nonce.
- **nonce_base64_buf** (&mut [u8; MAX_BASE64_KEY_LEN]) - Required - Buffer for base64-encoded nonce.

### Returns
Result<(), Error<T::Error>> - Ok on success, Err on failure.
```

--------------------------------

### Connection::new

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-http-io.md

Starts an unbound connection. The TCP socket is opened lazily on the first request.

```APIDOC
## Connection::new

### Description
Starts an unbound connection. The TCP socket is opened lazily on the first request.

### Method
new

### Signature
pub fn new(buf: &'b mut [u8], socket: &'b T, addr: SocketAddr) -> Self

### Parameters
- **buf** (&'b mut [u8]) - Required - Work buffer for the connection.
- **socket** (&'b T) - Required - TCP factory.
- **addr** (SocketAddr) - Required - Target address.

### Returns
Self - A new Connection instance in the Unbound state.
```

--------------------------------

### HTTP server with socket queue implementation

Source: https://github.com/sysgrok/edge-net/blob/master/edge-http/README.md

This example demonstrates how to use the socket queue architecture to handle HTTP connections, which is recommended for TCP stacks without accept queues. It defines a custom HttpHandler to process incoming requests.

```rust
use core::fmt::{Debug, Display};

use edge_http::io::server::{Connection, DefaultServer, Handler};
use edge_http::io::Error;
use edge_http::Method;
use edge_nal::TcpBind;

use embedded_io_async::{Read, Write};

use log::info;

fn main() {
    env_logger::init_from_env(
        env_logger::Env::default().filter_or(env_logger::DEFAULT_FILTER_ENV, "info"),
    );

    let mut server = DefaultServer::new();

    futures_lite::future::block_on(run(&mut server)).unwrap();
}

pub async fn run(server: &mut DefaultServer) -> Result<(), anyhow::Error> {
    let addr = "0.0.0.0:8881";

    info!("Running HTTP server with socket queue on {addr}");

    let acceptor = edge_nal_std::Stack::new()
        .bind(addr.parse().unwrap())
        .await?;

    // Use the socket queue architecture for better connection handling
    server.run_with_socket_queue(None, acceptor, HttpHandler).await?;

    Ok(())
}

struct HttpHandler;

impl Handler for HttpHandler {
    type Error<E>
        = Error<E>
    where
        E: Debug;

    async fn handle<T, const N: usize>(
        &self,
        _task_id: impl Display + Copy,
        conn: &mut Connection<'_, T, N>,
    ) -> Result<(), Self::Error<T::Error>>
    where
        T: Read + Write,
    {
        let headers = conn.headers()?;

        if headers.method != Method::Get {
            conn.initiate_response(405, Some("Method Not Allowed"), &[])
                .await?;
        } else if headers.path != "/" {
            conn.initiate_response(404, Some("Not Found"), &[]).await?;
        } else {
            conn.initiate_response(200, Some("OK"), &[("Content-Type", "text/plain")])
                .await?;

            conn.write_all(b"Hello world!").await?;
        }

        Ok(())
    }
}
```

--------------------------------

### Run Captive Portal DNS

Source: https://github.com/sysgrok/edge-net/blob/master/edge-captive/README.md

Example of running a Captive Portal DNS server on UDP port 8853 using the edge-captive crate.

```rust
use core::net::{IpAddr, Ipv4Addr, SocketAddr};
use core::time::Duration;

use edge_captive::io::run;

use log::*;

fn main() {
    env_logger::init_from_env(
        env_logger::Env::default().filter_or(env_logger::DEFAULT_FILTER_ENV, "info"),
    );

    let stack = edge_nal_std::Stack::new();

    let mut tx_buf = [0; 1500];
    let mut rx_buf = [0; 1500];

    info!("Running Captive Portal DNS on UDP port 8853...");

    futures_lite::future::block_on(run(
        &stack,
        // Can't use DEFAULT_SOCKET because it uses DNS port 53 which needs root
        SocketAddr::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), 8853),
        &mut tx_buf,
        &mut rx_buf,
        Ipv4Addr::new(192, 168, 0, 1),
        Duration::from_secs(60),
    ))
    .unwrap();
}
```

--------------------------------

### RequestHeaders::new

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-http.md

Creates a new RequestHeaders instance with default values: GET / HTTP/1.1.

```APIDOC
## RequestHeaders::new

### Description
Creates a new RequestHeaders instance with default values: GET / HTTP/1.1.

### Method
new

### Signature
pub const fn new() -> Self

### Parameters
None

### Returns
RequestHeaders<'b, N> - A new RequestHeaders instance with defaults.
```

--------------------------------

### Server::new

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-http-io.md

Creates a new zero-allocation Server instance.

```APIDOC
## Server::new

### Description
Creates a new zero-allocation Server instance.

### Method
new

### Signature
```rust
pub const fn new() -> Self
```

### Parameters
None

### Return Value
- Self - A new Server instance.
```

--------------------------------

### Settings::new

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-dhcp.md

Creates a Settings instance from a DHCP packet, extracting IP, gateway, DNS, server IP, and captive URL.

```APIDOC
## Settings::new

### Description
Creates a Settings instance from a DHCP packet, extracting IP, gateway, DNS, server IP, and captive URL.

### Method
new

### Signature
pub fn new(packet: &Packet<'a>) -> Self

### Parameters
- **packet** (&Packet<'a>) - Required - The DHCP packet to extract settings from.

### Returns
- **Settings<'a>** - The extracted settings.

### Details
- ip comes from packet.yiaddr
- gateway is the first Router option
- dns1 and dns2 are the first two DomainNameServer entries
- server_ip comes from ServerIdentifier
- captive_url comes from the CaptiveUrl option
```

--------------------------------

### Initialize and run mDNS service

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-mdns-io.md

Demonstrates how to bind a socket, configure buffers, and run an mDNS handler using the edge-mdns-io library.

```rust
use core::net::Ipv4Addr;
use edge_mdns::buf::VecBufAccess;
use edge_mdns::host::{Host, ServiceAnswers};
use edge_mdns::io::{self, DEFAULT_SOCKET};
use edge_mdns::{HostAnswersMdnsHandler};
use edge_nal::{UdpBind, UdpSplit};
use embassy_sync::blocking_mutex::raw::NoopRawMutex;
use embassy_sync::signal::Signal;

let stack = edge_nal_std::Stack::new();
let (recv_buf, send_buf) = (
    VecBufAccess::<NoopRawMutex, 1500>::new(),
    VecBufAccess::<NoopRawMutex, 1500>::new(),
);

let mut socket = io::bind(&stack, DEFAULT_SOCKET, Some(Ipv4Addr::UNSPECIFIED), Some(0)).await?;
let (recv, send) = socket.split();

let host = /* Host { ... } */;
let service = /* Service { ... } */;
let signal = Signal::<NoopRawMutex, _>::new();

let mdns = io::Mdns::new(
    Some(Ipv4Addr::UNSPECIFIED),
    Some(0),
    recv,
    send,
    recv_buf,
    send_buf,
    rand::rng(),
    &signal,
);

mdns.run(HostAnswersMdnsHandler::new(ServiceAnswers::new(&host, &service))).await?;
```

--------------------------------

### Server::run

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-http-io.md

Runs the server, spawning P tasks to accept and handle connections concurrently.

```APIDOC
## Server::run

### Description
Runs the server, spawning P tasks to accept and handle connections concurrently. The keepalive_timeout_ms parameter closes idle keep-alive connections.

### Method
run

### Signature
```rust
pub async fn run<A, H>(&mut self, keepalive_timeout_ms: Option<u32>, acceptor: A, handler: H) -> Result<(), Error<A::Error>>
where A: edge_nal::TcpAccept, H: Handler
```

### Parameters
- **keepalive_timeout_ms** (Option<u32>) - Required - Timeout in milliseconds for idle keep-alive connections. None disables the timeout.
- **acceptor** (A) - Required - The TCP acceptor (implements edge_nal::TcpAccept).
- **handler** (H) - Required - The handler for each connection (implements Handler).

### Return Value
- Result<(), Error<A::Error>> - Ok on success, or an error from the acceptor.

### Notes
All tasks call accept() concurrently, which is important for stacks without accept queues (e.g., smoltcp/embassy-net).
```

--------------------------------

### Server::handle_request

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-dhcp.md

Processes one BOOTP request and returns a reply packet, or None for Release/Decline/ignored messages.

```APIDOC
## Server::handle_request

### Description
Processes one BOOTP request and returns a reply packet, or None for Release/Decline/ignored messages.

### Method
Method

### Signature
pub fn handle_request<'o>(&mut self, opt_buf: &'o mut [DhcpOption<'o>], server_options: &'o ServerOptions, request: &Packet) -> Option<Packet<'o>>

### Parameters
- **opt_buf** (&'o mut [DhcpOption<'o>]) - Required - Buffer for DHCP options in the reply.
- **server_options** (&'o ServerOptions) - Required - Server configuration options.
- **request** (&Packet) - Required - The incoming BOOTP request packet.

### Returns
- **Option<Packet<'o>>** - A reply packet, or None for Release/Decline/ignored messages.

### Behavior
- Discover: offer the requested IP if available, else the client's current lease, else the first free address in range.
- Request: if the address is available (same MAC, or in range and unleased, or lease expired) it is leased (expires = now + lease_duration_secs) and DHCPACK sent; otherwise DHCPNAK.
- Release / Decline: remove the MAC's lease, no reply.

### Example
```rust
let mut opt_buf = Options::buf();
if let Some(reply) = server.handle_request(&mut opt_buf, &server_options, &request) {
    let bytes = reply.encode(buf).unwrap();
    // ... send bytes back to the client
}
```
```

--------------------------------

### DHCP Client Implementation

Source: https://github.com/sysgrok/edge-net/blob/master/edge-dhcp/README.md

Demonstrates how to implement a DHCP client using raw sockets. Note that this requires root privileges (sudo) to bind to the network interface.

```rust
//! NOTE: Run this example with `sudo` to be able to bind to the interface, as it uses raw sockets which require root privileges.

use core::net::{Ipv4Addr, SocketAddrV4};

use edge_dhcp::client::Client;
use edge_dhcp::io::{client::Lease, DEFAULT_CLIENT_PORT, DEFAULT_SERVER_PORT};
use edge_nal::{MacAddr, RawBind};
use edge_raw::io::RawSocket2Udp;

use log::info;

fn main() {
    env_logger::init_from_env(
        env_logger::Env::default().filter_or(env_logger::DEFAULT_FILTER_ENV, "info"),
    );

    futures_lite::future::block_on(run(
        2, // The interface index of the interface (e.g. eno0) to use; run `ip addr` to see it
        [0x4c, 0xcc, 0x6a, 0xa2, 0x23, 0xf5], // Your MAC addr here; run `ip addr` to see it
    ))
    .unwrap();
}

async fn run(if_index: u32, if_mac: MacAddr) -> Result<(), anyhow::Error> {
    let mut client = Client::new(rand::rng(), if_mac);

    let stack = edge_nal_std::Interface::new(if_index);
    let mut buf = [0; 1500];

    loop {
        let mut socket: RawSocket2Udp<_> = RawSocket2Udp::new(
            stack.bind().await?,
            Some(SocketAddrV4::new(
                Ipv4Addr::UNSPECIFIED,
                DEFAULT_CLIENT_PORT,
            )),
            Some(SocketAddrV4::new(
                Ipv4Addr::UNSPECIFIED,
                DEFAULT_SERVER_PORT,
            )),
            [255; 6], // Broadcast
        );

        let (mut lease, options) = Lease::new(&mut client, &mut socket, &mut buf).await?;

        info!("Got lease {lease:?} with options {options:?}");

        info!("Entering an endless loop to keep the lease...");

        lease.keep(&mut client, &mut socket, &mut buf).await?;
    }
}
```

--------------------------------

### RequestHeaders::is_ws_upgrade_request

Source: https://github.com/sysgrok/edge-net/blob/master/_autodocs/api-reference/edge-http.md

Checks if the request headers indicate a WebSocket upgrade request: GET method with Connection: Upgrade and Upgrade: websocket headers.

```APIDOC
## RequestHeaders::is_ws_upgrade_request

### Description
Checks if the request headers indicate a WebSocket upgrade request: GET method with Connection: Upgrade and Upgrade: websocket headers.

### Method
is_ws_upgrade_request

### Signature
pub fn is_ws_upgrade_request(&self) -> bool

### Parameters
None

### Returns
bool - True if the request is a WebSocket upgrade request.
```
Tokens:
Raw