Skip to content

minicorn 1.1.2

Choose a tag to compare

View all tags
@Shankar-105 Shankar-105 released this 16 Feb 15:25
· 5 commits to main since this release
v1.1.2
1e1eeb5

minicorn 1.1.2 - WebSocket Ping/Pong Keep-Alive

A patch release adding transport-level WebSocket ping/pong keep-alive to automatically detect and close dead connections, plus new CLI options to configure it.

New Features

  • WebSocket Ping/Pong Keep-Alive - The server can now periodically send WebSocket ping frames to connected clients to detect dead connections
    • Configurable ping interval: how often to send a ping
    • Configurable pong timeout: how long to wait for a pong reply before closing the connection
    • Sends minicorn as the ping payload for easy identification in network traces
  • New CLI Options - Two new flags for ASGI mode:
    • --ws-ping-interval <seconds> - Seconds between WebSocket pings (disabled by default)
    • --ws-ping-timeout <seconds> - Seconds to wait for pong before closing (requires --ws-ping-interval)
  • Startup Logging - When ping/pong is enabled, the server logs the configured interval and timeout on startup

Changes

  • Pong Handling - Incoming pong frames are no longer silently ignored; they now signal the keep-alive loop to confirm the client is alive
  • Graceful Close on Timeout - If a client fails to respond to a ping within the timeout, the server sends a close frame with code 1001 (Going Away) and shuts down the transport
  • Background Ping Task - A per-connection asyncio task runs the ping loop; it is automatically cancelled when the connection ends
  • Disconnect Code Fix - Abnormal close code (1006) is only set on disconnect if the connection wasn't already closed by the server

Quick Start

# Enable ping every 20 seconds, close if no pong within 10 seconds
minicorn main:app --asgi --ws-ping-interval 20 --ws-ping-timeout 10

# Enable ping only (no timeout enforcement)
minicorn main:app --asgi --ws-ping-interval 30

Programmatic Usage

from minicorn import run_asgi

run_asgi(app, ws_ping_interval=20.0, ws_ping_timeout=10.0)

Notes

  • Ping/pong is disabled by default - opt-in via CLI flags or function arguments
  • Only applies to ASGI mode (WebSocket connections)
  • The WSGI server is unaffected by this change
Assets 2
Loading