Real-time messaging. Raw sockets. Pure C++.

Quick Start · Architecture · Protocol · Admin

---

SocketMessaging

SocketMessaging is a C++17 client/server stack that combines a thread-pooled TCP listener, a queued message dispatcher, and an administrative control surface for orchestrating multi-user messaging sessions. The code base targets Linux/POSIX environments and relies on raw sockets and lightweight utilities instead of heavyweight networking frameworks.

Screenshots

Server Console	Client Menu
Admin Commands	Unread Messages

Architecture Overview

• Server (Server::start) initialises sockets, loads configuration, spins up the dispatcher, thread pool, heartbeat monitor, and admin command loop. Client sockets are tracked with timestamps to back the heartbeat timeout logic.
• Dispatcher drains a thread-safe message queue, applying delay policies and ensuring that failed deliveries notify the sender. Broadcasting is implemented by queueing per-recipient messages.
• Command handler (CommandHandler) validates and routes protocol commands: CONNECT, DISCONNECT, SEND, LIST_USERS, GET_LOG, PING/PONG. It sanitises input, applies banlist checks, and forwards payloads to the dispatcher.
• Client runtime (Client and MessageHandler) wraps POSIX sockets, handles connection negotiation, maintains a listener thread for server events, and exposes callbacks for UI layers (ClientUI).
• Utilities provide shared services: structured logging, runtime configuration (RuntimeConfig), command-line constants, message parsing, string sanitation, and network stream framing with length-prefix and newline delimiters.

Message Pipeline

Sequence diagram showing the complete communication flow

1. Clients connect using the CONNECT;username request. Authentication enforces unique, validated usernames and checks the banlist.
2. Once registered, SEND commands (SEND;recipient;subject;body) are queued via the dispatcher. When recipient is all, the handler expands the broadcast into one queued message per user.
3. The dispatcher wakes when messages arrive, applies the configured queue policy, and formats the final MESSAGE;from;subject;body;timestamp payload for the destination socket.
4. Heartbeat threads issue periodic PING frames. Lack of PONG responses triggers a timeout path that delegates disconnection workflows to the command handler.
5. Administrator commands (prefixed with /) run in a dedicated stdin loop, allowing real-time broadcasts, user management, and runtime configuration adjustments.

Build and Run

Prerequisites

• g++ with C++17 support (tested with GCC 12+)
• POSIX sockets (Linux, macOS, WSL)
• Make

Build targets

make            # builds bin/server and bin/client
make clean      # removes obj/ and bin/

Launching the server

./bin/server -p 9000 -c 200 -v

• -p/--port: override listen port (default 8080)
• -c/--connections: cap simultaneous clients (default 100)
• -v/--verbose: emit DEBUG-level logs to stdout and server.log

The server spawns four background threads: client acceptor, dispatcher, heartbeat monitor, and admin shell. Use Ctrl+C to exit gracefully.

Launching a client

./bin/client --host 127.0.0.1 --port 9000 --user alice

The console client negotiates a username, starts a listener thread, and exposes interactive commands for sending direct or broadcast messages.

Runtime Administration

The admin console reads commands from standard input (prefix with /). Key commands:

• /help – list commands and usage
• /broadcast <message> – push a system message to all clients
• /send <user> <message> – target a specific user
• /list – display connected clients
• /kick <user> and /ban <user> – disconnect or permanently ban a user (persists to banlist)
• /unban <user> – remove bans
• /stats – uptime, counts, and per-minute message rate
• /config and /set <key> <value> – inspect or adjust runtime settings backed by RuntimeConfig
• /reset – restore runtime settings to defaults
• /stop – request an orderly shutdown

Configuration Surface

Runtime configuration keys are defined in RuntimeConfig and validated against constraints from Constants. Examples include:

• heartbeat.interval – seconds between PING frames (min 5)
• heartbeat.timeout – seconds before a client is considered offline (min 10)
• dispatcher.delay – inter-message delay in milliseconds
• queue.policy – behaviour when the dispatcher queue is at capacity (REJECT, DROP_OLDEST, DROP_NEWEST)

Changes via /set take effect immediately and survive until /reset or server restart.

Logging and Monitoring

• Server logs are written to server.log by default; clients log to client.log.
• Clients may request the trailing 50 lines of the server log with GET_LOG.
• Verbose mode (-v) mirrors DEBUG output to the console, aiding local debugging.
• Heartbeat warnings, queue overflows, and dispatcher errors are surfaced through the logger for quick diagnosis.

License

SocketMessaging is released under the MIT License. Review LICENSE before redistribution and update copyright notices as needed.