Protocol#

Join provides protocol classes that encapsulate network protocol specifications for socket programming. Each protocol class defines the address family, socket type, and protocol number needed to create sockets.

Protocols are:

type‑safe — compile‑time protocol selection
lightweight — zero‑overhead abstractions
composable — work with endpoints, sockets, and streams

Available protocols span multiple network layers:

Unix domain (local IPC)
Internet protocols (TCP, UDP, ICMP)
Secure protocols (TLS, HTTPS, SMTPS)
Application protocols (HTTP, SMTP, DNS, DoT, mDNS)
Low‑level protocols (Netlink, Raw packets)

Unix domain protocols#

Unix domain sockets provide local inter‑process communication with filesystem‑based addressing.

UnixDgram#

Connectionless datagram protocol using AF_UNIX and SOCK_DGRAM.

#include <join/protocol.hpp>

using namespace join;

UnixDgram::Socket socket;
UnixDgram::Endpoint endpoint("/tmp/socket");

UnixStream#

Connection‑oriented stream protocol using AF_UNIX and SOCK_STREAM.

UnixStream::Socket   socket;
UnixStream::Stream   stream;
UnixStream::Acceptor acceptor;

Internet protocols#

UDP#

User Datagram Protocol for connectionless packet transmission.

Udp::Socket socket4(Udp::v4());
Udp::Socket socket6(Udp::v6());

TCP#

Transmission Control Protocol for reliable stream communication.

Tcp::Socket   socket4(Tcp::v4());
Tcp::Stream   stream;
Tcp::Acceptor acceptor;

Tcp::Socket   socket6(Tcp::v6());

ICMP#

Internet Control Message Protocol for network diagnostics (ping, traceroute).

Icmp::Socket icmp4(Icmp::v4());
Icmp::Socket icmp6(Icmp::v6());

⚠️ ICMP sockets typically require CAP_NET_RAW.

Secure protocols#

TLS#

Transport Layer Security for encrypted TCP connections.

Tls::Socket   socket(Tls::v4());
Tls::Stream   stream;
Tls::Acceptor acceptor;

Application protocols#

HTTP / HTTPS#

Http::Client  client;
Http::Server  server;
Http::Worker  worker;

Https::Client secureClient;
Https::Server secureServer;

SMTP / SMTPS#

Smtp::Client  client(Smtp::v4());
Smtps::Client secureClient(Smtps::v4());

DNS (over UDP)#

DNS protocol over UDP. Default port 53, max message size 8192 bytes.

Dns::Socket     socket(Dns::v4());
Dns::Resolver   resolver("8.8.8.8");      // BasicDatagramResolver<Dns>
Dns::NameServer nameServer;               // BasicDatagramNameServer<Dns>

Both IPv4 and IPv6 are supported via Dns::v4() / Dns::v6().

See Dns::Resolver and Dns::NameServer for full documentation.

DoT — DNS over TLS#

DNS-over-TLS protocol. Default port 853, max message size 16384 bytes, RFC 7858 framing.

Dot::Socket   socket(Dot::v4());
Dot::Resolver resolver("1.1.1.1");        // BasicTlsResolver<Dot>

Dot uses SOCK_STREAM / IPPROTO_TCP under the hood. Both IPv4 and IPv6 are supported.

See Dot::Resolver for full documentation.

mDNS (Multicast DNS)#

Multicast DNS protocol. Default port 5353, max message size 8192 bytes.

Mdns::Socket socket(Mdns::v4());
Mdns::Peer   peer("eth0");                // BasicDatagramPeer<Mdns>

// Multicast group addresses
IpAddress v4group = Mdns::multicastAddress(AF_INET);   // 224.0.0.251
IpAddress v6group = Mdns::multicastAddress(AF_INET6);  // ff02::fb

Both IPv4 and IPv6 multicast groups are supported via Mdns::v4() / Mdns::v6().

See Mdns::Peer for full documentation.

Low‑level protocols#

Netlink#

Linux kernel communication protocol for routing, netfilter, and more.

Netlink::Socket routeSocket(Netlink::rt());   // NETLINK_ROUTE
Netlink::Socket nfSocket(Netlink::nf());      // NETLINK_NETFILTER

Netlink custom(NETLINK_USERSOCK);

Raw#

Raw packet protocol using AF_PACKET for link‑layer access.

Raw::Socket   socket;
Raw::Endpoint endpoint;

⚠️ Raw sockets require CAP_NET_RAW and handle Ethernet frames directly.

IPv4 vs IPv6#

Internet protocols support both address families through static factory methods:

Tcp::v4()   Tcp::v6()
Udp::v4()   Udp::v6()
Icmp::v4()  Icmp::v6()
Tls::v4()   Tls::v6()
Dns::v4()   Dns::v6()
Dot::v4()   Dot::v6()
Mdns::v4()  Mdns::v6()
Http::v4()  Http::v6()

Protocols can also be constructed with an explicit family:

Tcp  tcpv4(AF_INET);
Tcp  tcpv6(AF_INET6);
Dns  dnsv4(AF_INET);
Mdns mdnsv6(AF_INET6);

Protocol comparison#

Protocols with family selection support == and !=:

assert(Tcp::v4() == Tcp::v4());
assert(Tcp::v4() != Tcp::v6());
assert(Dns::v4() != Dns::v6());
assert(Netlink::rt() != Netlink::nf());

Protocol properties#

All protocol classes expose three core methods:

protocol.family();    // AF_INET, AF_UNIX, AF_NETLINK, AF_PACKET…
protocol.type();      // SOCK_STREAM, SOCK_DGRAM, SOCK_RAW
protocol.protocol();  // IPPROTO_TCP, IPPROTO_UDP, 0…

DNS and mDNS also expose protocol-level constants:

Dns::defaultPort   // 53
Dns::maxMsgSize    // 8192

Dot::defaultPort   // 853
Dot::maxMsgSize    // 16384

Mdns::defaultPort  // 5353
Mdns::maxMsgSize   // 8192

Associated types#

Each protocol defines type aliases for related components:

Protocol	Endpoint	Socket	Stream	Acceptor	Resolver	NameServer	Peer	Client	Server
UnixDgram	✅	✅	❌	❌	❌	❌	❌	❌	❌
UnixStream	✅	✅	✅	✅	❌	❌	❌	❌	❌
Udp	✅	✅	❌	❌	❌	❌	❌	❌	❌
Tcp	✅	✅	✅	✅	❌	❌	❌	❌	❌
Tls	✅	✅	✅	✅	❌	❌	❌	❌	❌
Dns	✅	✅	❌	❌	✅	✅	❌	❌	❌
Dot	✅	✅	❌	❌	✅	❌	❌	❌	❌
Mdns	✅	✅	❌	❌	❌	❌	✅	❌	❌
Http	✅	✅	✅	✅	❌	❌	❌	✅	✅
Https	✅	✅	✅	✅	❌	❌	❌	✅	✅
Smtp	✅	✅	✅	❌	❌	❌	❌	✅	❌
Smtps	✅	✅	✅	❌	❌	❌	❌	✅	❌
Netlink	✅	✅	❌	❌	❌	❌	❌	❌	❌
Raw	✅	✅	❌	❌	❌	❌	❌	❌	❌

Summary#

Protocol	Family	Type	Use Case
UnixDgram	AF_UNIX	SOCK_DGRAM	Local datagram IPC
UnixStream	AF_UNIX	SOCK_STREAM	Local stream IPC
Udp	AF_INET*	SOCK_DGRAM	Internet datagrams
Tcp	AF_INET*	SOCK_STREAM	Reliable internet streams
Icmp	AF_INET*	SOCK_RAW	Network diagnostics
Tls	AF_INET*	SOCK_STREAM	Encrypted TCP
Dns	AF_INET*	SOCK_DGRAM	DNS over UDP
Dot	AF_INET*	SOCK_STREAM	DNS over TLS
Mdns	AF_INET*	SOCK_DGRAM	Multicast DNS
Http	AF_INET*	SOCK_STREAM	Web requests
Https	AF_INET*	SOCK_STREAM	Secure web requests
Smtp	AF_INET*	SOCK_STREAM	Email transmission
Smtps	AF_INET*	SOCK_STREAM	Secure email transmission
Netlink	AF_NETLINK	SOCK_RAW	Kernel communication
Raw	AF_PACKET	SOCK_RAW	Link‑layer packet access

* Supports both AF_INET (IPv4) and AF_INET6 (IPv6)