cymongoose: python bindings for mongoose using with cython.

[shakfu]

Overview

cymongoose is a thin cython wrapper over the native mongoose C library and includes coverage of:

• HTTP/HTTPS: Server and client with TLS support, chunked transfer encoding, SSE
• WebSocket/WSS: Full WebSocket support with text/binary frames over TLS
• MQTT/MQTTS: Publish/subscribe messaging with QoS support
• TCP/UDP: Raw socket support with custom protocols
• DNS: Asynchronous hostname resolution
• SNTP: Network time synchronization
• TLS/SSL: Certificate-based encryption with custom CA support
• Timers: Periodic callbacks with precise timing control
• Flow Control: Backpressure handling and buffer management
• Authentication: HTTP Basic Auth, MQTT credentials
• JSON Parsing: Built-in JSON extraction utilities
• URL Encoding: Safe URL parameter encoding

The wrapper is:

• Compatible with Python 3.9+: Modern Python with type hints
• Comprehensive: 210 tests, 100% pass rate

It has:

• Production Examples: 17 complete examples from Mongoose tutorials
• GIL Optimization: 21 methods release GIL for true parallel execution
• High Performance: 60k+ req/sec (6-37x faster than pure Python frameworks)

A Few Examples

Simple HTTP Server

import signal
from cymongoose import Manager, MG_EV_HTTP_MSG

shutdown_requested = False

def signal_handler(sig, frame):
    global shutdown_requested
    shutdown_requested = True

def handler(conn, event, data):
    if event == MG_EV_HTTP_MSG:
        conn.reply(200, "Hello, World!")

signal.signal(signal.SIGINT, signal_handler)
signal.signal(signal.SIGTERM, signal_handler)

mgr = Manager(handler)
mgr.listen("http://0.0.0.0:8000", http=True)

print("Server running on http://localhost:8000. Press Ctrl+C to stop.")
try:
    while not shutdown_requested:
        mgr.poll(100)
    print("Shutting down...")
finally:
    mgr.close()

Serve Static Files

import signal
from cymongoose import Manager, MG_EV_HTTP_MSG

shutdown_requested = False

def signal_handler(sig, frame):
    global shutdown_requested
    shutdown_requested = True

def handler(conn, event, data):
    if event == MG_EV_HTTP_MSG:
        conn.serve_dir(data, root_dir="./public")

signal.signal(signal.SIGINT, signal_handler)
signal.signal(signal.SIGTERM, signal_handler)

mgr = Manager(handler)
mgr.listen("http://0.0.0.0:8000", http=True)

try:
    while not shutdown_requested:
        mgr.poll(100)
finally:
    mgr.close()

WebSocket Echo Server

import signal
from cymongoose import Manager, MG_EV_HTTP_MSG, MG_EV_WS_MSG

shutdown_requested = False

def signal_handler(sig, frame):
    global shutdown_requested
    shutdown_requested = True

def handler(conn, event, data):
    if event == MG_EV_HTTP_MSG:
        conn.ws_upgrade(data)  # Upgrade HTTP to WebSocket
    elif event == MG_EV_WS_MSG:
        conn.ws_send(data.text)  # Echo back

signal.signal(signal.SIGINT, signal_handler)
signal.signal(signal.SIGTERM, signal_handler)

mgr = Manager(handler)
mgr.listen("http://0.0.0.0:8000", http=True)

try:
    while not shutdown_requested:
        mgr.poll(100)
finally:
    mgr.close()

[shakfu]

The project has been renamed to cymongoose to prevent confusion with another project by the same name.

[shakfu]

cymongoose v0.2.0 Update

Hi, sharing a progress update on cymongoose, the Cython wrapper for the mongoose C library.

Since the initial post, the project has gone through several rounds of code review, security hardening, and test expansion. v0.2.0 marks the point where the codebase has stabilized and the core APIs are well-tested and documented.

What's New Since the Original Post

Performance

Throughput has improved from 60,973 req/sec to 88,710 req/sec (wrk, 4 threads, 100 connections, on a M1 MacBook Air). This puts cymongoose at:

Framework	Req/sec	vs cymongoose
cymongoose	88,710	baseline
aiohttp	42,452	2.1x slower
FastAPI/uvicorn	9,989	8.9x slower
Flask	1,627	54.5x slower

The gain comes from unconditional nogil on all C calls and general optimization across releases.

Asyncio Integration

AsyncManager runs the mongoose event loop in a background thread alongside Python's asyncio:

import asyncio
from cymongoose import AsyncManager, MG_EV_HTTP_MSG

def handler(conn, ev, data):
    if ev == MG_EV_HTTP_MSG:
        conn.reply(200, "Hello from async!")

async def main():
    async with AsyncManager(handler) as am:
        am.listen("http://0.0.0.0:8080")
        await asyncio.sleep(3600)

asyncio.run(main())

Features: configurable shutdown_timeout, graceful shutdown with retry/warn loop, schedule() for pushing work from handlers back onto the asyncio loop, thread-safe wakeup().

Security Hardening

• HTTP header injection prevention: reply(), reply_json(), and ws_upgrade() now validate header names and values for CR/LF/NUL characters, preventing response-splitting attacks.
• Format string vulnerability fix: ws_upgrade() no longer passes user-supplied header text as a printf format string.

Test Suite

Grew from 210 tests to 372 tests across 42 files:

• Static file serving (serve_dir, serve_file)
• MQTT pub/sub round-trip with a MiniBroker
• WebSocket header injection
• poll() reentrancy guard
• Send operations on closed connections
• Connection churn stress tests (2000 sequential, 5 threads x 400)
• AddressSanitizer and macOS leaks integration

Network-dependent tests (DNS, SNTP) are excluded by default and run as a separate non-blocking CI job.

Documentation

Full MkDocs site at shakfu.github.io/cymongoose with:

• API reference for Manager, AsyncManager, Connection, Messages, Utilities
• User guides for HTTP, WebSocket, MQTT, TCP/UDP, TLS
• Advanced topics: nogil, performance tuning, threading model, graceful shutdown
• Benchmark methodology and Makefile targets (make bench, make bench-server)

API Summary

The current API surface:

Core classes: Manager, AsyncManager, Connection, Timer, TlsOpts

Message views: HttpMessage, WsMessage, MqttMessage (zero-copy, invalidated after handler returns)

Manager methods:

• listen(), connect(), ws_connect() -- HTTP/WS/TCP/UDP
• mqtt_connect(), mqtt_listen() -- MQTT client/broker
• sntp_connect() -- network time
• timer_add() -- one-shot and repeating timers
• wakeup() -- thread-safe event injection
• poll(), run(), close() -- event loop control
• connections -- snapshot of all active connections

Connection methods:

• reply(), reply_json(), serve_dir(), serve_file() -- HTTP responses
• ws_upgrade(), ws_send() -- WebSocket
• mqtt_pub(), mqtt_sub(), mqtt_ping(), mqtt_disconnect() -- MQTT
• http_chunk(), http_sse() -- streaming
• send(), drain(), close() -- raw I/O and lifecycle
• tls_init(), tls_free() -- TLS configuration
• resolve(), resolve_cancel() -- async DNS
• http_basic_auth(), sntp_request(), error()

Utilities: json_get(), json_get_num(), json_get_bool(), json_get_long(), json_get_str(), url_encode(), http_parse_multipart(), event_name(), log_set(), log_get()

Constants: 21 event types (MG_EV_*), 4 WebSocket opcodes, 5 log levels

CI

• Test matrix: 3 OS (Ubuntu, macOS, Windows) x 5 Python versions (3.10-3.14)
• Coverage gate at 80%
• AddressSanitizer job on Ubuntu
• Network tests as a separate non-blocking job
• Lint (ruff) and type check (mypy --strict)

Links

• Repository: https://github.com/shakfu/cymongoose
• Documentation: https://shakfu.github.io/cymongoose/
• PyPI: https://pypi.org/project/cymongoose/

Feedback and bug reports welcome at https://github.com/shakfu/cymongoose/issues.

[shakfu]

From a pip3 install .:

  ...
      1>Cythonizing _mongoose.pyx
      F:\gv\Python314\python.exe: No module named cython.__main__; 'cython' is a package and cannot be directly executed
      The system cannot find the batch label specified - VCEnd
 ...

OMG! I do have Cython. It works fine in my GNU-makefile.

you need to use uv for an editable install:

uv pip install -e .

[gvanem]

This editable and the .venv are just ugly hacks IMHO. Why do you insist on making things so f*ing hard?
I miss the old days with a py -3 setup.py build | install. Always worked.

[shakfu]

😄

I completely sympathize with your view, and I did at some point share it. The case could be made that I should have stuck to setuptools and setup.py, but I have switched all my python projects to use uv and pyproject.toml when they are pure python and uv and scikit-build-core when there is a need to compile c or c++ code as well.

You have to think of uv as a tool which integrates the features of pip and virtualenv and also allows you to build a python package on a system without python installed. A balanced article about it is here

[scaprile]

Gentlemen, please keep the internals of the project in the project repo, not here. Here Mongoose.
Thank you.

Reason: we don't have the time to deal with a lot of traffic, and this traffic is not even related to something that we could do anything about. Every comment pings the admins, so you should get the picture. Thank you for your understanding.

[shakfu]

Apologies. I'll try to it keep it relevant here and divert all cymongoose issues to the relevant issue tracker.