MSQ

My Simple Queue — where "My" means mine, yours, everyone's.

A lightweight, persistent message queue in C. No cloud dependencies, no enterprise bloat, no vendor lock-in. Just a binary that runs on your machine and does one thing well.

Features

• Persistent: Messages survive server restarts.
• Pull-based: Consumers control their pace. No surprise floods.
• Text protocol: Debug with netcat. Implement a client in an afternoon.
• Single binary: No dependencies beyond libc.
• Fast: Circular buffers, epoll, zero-copy where it matters.

Quick Start

# Build
make

# Run server
./server

In another terminal (use nc -C for CRLF line endings):

# Publish a message (payload requires printf)
$ printf 'PUBLISH orders 14\r\n{"orderId":42}' | nc -C localhost 9876
+OK 1

# Consume and acknowledge (interactive)
$ nc -C localhost 9876
CONSUME orders
+MSG 1 14
{"orderId":42}
ACK 1
+OK

That's it. You now have a working message queue.

Protocol

Human-readable. Commands are CRLF-terminated, payloads are length-prefixed.

PUBLISH <queue> <size>\r\n<payload>    -> +OK <msg_id>\r\n
CONSUME <queue>\r\n                    -> +MSG <id> <size>\r\n<payload>
ACK <msg_id>\r\n                       -> +OK\r\n
NACK <msg_id>\r\n                      -> +OK requeued\r\n
PING\r\n                               -> +PONG\r\n

Full spec: docs/PROTOCOL.md

Client Library

libmsq.a — a minimal C library for talking to MSQ servers.

uint8_t mem[msq_conn_size()];
msq_conn_t *conn = (msq_conn_t *)mem;

msq_connect(conn, "localhost", 9876);
msq_send(conn, "PING", 4, NULL, 0);

uint8_t resp[MSQ_RESP_MAX];
size_t len;
msq_recv(conn, resp, sizeof(resp), &len);
// resp: "+PONG\r\n"

msq_close(conn);

5 functions. No allocations. Caller owns all memory.

Full docs: docs/LIBMSQ.md

Guarantees

Property	Behavior
Ordering	FIFO per queue
Delivery	At-least-once
Durability	Persisted to disk before +OK
Overflow	Drop oldest

Details: docs/DESIGN.md

Building

make          # builds server, client, libmsq.a
make test     # runs test suite

Requirements: GCC, Linux (uses epoll). No external dependencies.

Status

MSQ is in Phase 1: single-node, in-memory + persistence.

What works:

• Publish/consume/ack/nack cycle
• Append-only log persistence with crash recovery
• Client library

This is early software. Feedback is appreciated.

License

MSQ is free software, released under the GNU Affero General Public License v3.0.

Free as in freedom:

• Freedom 0: Run the program for any purpose
• Freedom 1: Study and modify the source code
• Freedom 2: Redistribute copies
• Freedom 3: Distribute your modified versions

The name says it all: My Simple Queue. Not Amazon's. Not Google's. Not some VC-funded startup's. Yours. Software that belongs to the people who use it.

Learn more about free software: gnu.org/philosophy/free-sw.html