WebSocket Close Codes — Understanding Connection Termination Status Codes

CLOSE_CODES = {
    1000: {'name': 'Normal Closure', 'description': 'Connection closed normally'},
    1001: {'name': 'Going Away', 'description': 'Client navigated away or server shutting down'},
    1002: {'name': 'Protocol Error', 'description': 'Protocol violation'},
    1003: {'name': 'Unsupported Data', 'description': 'Received unsupported data type'},
    1005: {'name': 'No Status Received', 'description': 'No close code was provided'},
    1006: {'name': 'Abnormal Closure', 'description': 'Connection closed without close frame'},
    1007: {'name': 'Invalid Frame Payload Data', 'description': 'Invalid UTF-8 or inconsistent data'},
    1008: {'name': 'Policy Violation', 'description': 'Message violates server policy'},
    1009: {'name': 'Message Too Big', 'description': 'Message exceeds maximum size'},
    1010: {'name': 'Mandatory Extension', 'description': 'Client required extension not negotiated'},
    1011: {'name': 'Internal Server Error', 'description': 'Unexpected server condition'},
    1012: {'name': 'Service Restart', 'description': 'Server is restarting'},
    1013: {'name': 'Try Again Later', 'description': 'Temporary server condition'},
    1014: {'name': 'Bad Gateway', 'description': 'Server acting as gateway received invalid response'},
    1015: {'name': 'TLS Handshake Failure', 'description': 'TLS handshake could not be completed'},
}

def describe_close_code(code):
    """Get a human-readable description of a close code"""
    info = CLOSE_CODES.get(code)
    if info:
        return f"{code}: {info['name']} - {info['description']}"

    if code >= 3000 and code <= 3999:
        return f"{code}: Registered (library/framework specific)"
    elif code >= 4000 and code <= 4999:
        return f"{code}: Private (application specific)"
    else:
        return f"{code}: Reserved (not to be used)"

def handle_close_frame(payload):
    """Parse a WebSocket close frame payload"""
    if len(payload) >= 2:
        close_code = int.from_bytes(payload[:2], 'big')
        reason = payload[2:].decode('utf-8', errors='replace')
        return {'code': close_code, 'reason': reason, 'description': describe_close_code(close_code)}
    return {'code': 1005, 'reason': '', 'description': 'No status code provided'}

def send_close(ws, code=1000, reason=''):
    """Send a WebSocket close frame with proper code"""
    payload = bytearray()
    payload.extend(code.to_bytes(2, 'big'))
    payload.extend(reason.encode('utf-8'))
    ws.send(payload, opcode=8)

# Application-specific close codes (4000-4999)
APP_CLOSE_CODES = {
    4000: 'Session expired - please re-authenticate',
    4001: 'Rate limit exceeded',
    4002: 'Insufficient permissions',
    4003: 'Invalid subscription tier',
    4004: 'Concurrent connections limit reached',
    4005: 'Client version outdated',
    4006: 'Server maintenance in progress',
}

def send_application_close(ws, code, reason=None):
    """Send an application-specific close"""
    if code not in APP_CLOSE_CODES:
        raise ValueError(f"Unknown close code: {code}")

    reason = reason or APP_CLOSE_CODES[code]
    send_close(ws, code, reason)

def is_valid_close_code(code):
    """Check if a close code is valid"""
    if code in (1000, 1001, 1002, 1003, 1007, 1008, 1009, 1010, 1011):
        return True
    return 3000 <= code <= 4999