whois-cli 0.3.2

# WHOIS-COLOR Protocol Specification

## Version 1.1 (with Markdown and Image Support)

This document describes the WHOIS-COLOR protocol, a backward-compatible extension to standard WHOIS that enables server-side colorization, Markdown formatting, and image display.

## Design Goals

1. **Backward Compatibility**: Full compatibility with v1.0 servers and standard WHOIS servers
2. **Server-side Enhancement**: Servers can provide colored, formatted, and multimedia-rich responses
3. **Progressive Enhancement**: Features gracefully degrade based on server capabilities
4. **Extensibility**: Protocol designed for future enhancements while maintaining compatibility

## Protocol Flow

### 1. Capability Detection Phase

Client sends capability probe request:
```
X-WHOIS-COLOR-PROBE: v1.1\r\n\r\n
```

**v1.1 Server Response:**
```
X-WHOIS-COLOR-SUPPORT: v1.1 schemes=ripe,bgptools,mtf markdown=true images=png,jpg\r\n
```

**v1.0 Server Response (Legacy):**
```
X-WHOIS-COLOR-SUPPORT: v1.0 schemes=ripe,bgptools,mtf\r\n
```

**Non-supporting servers**:
- Ignore the request or return standard error
- Client uses server-side rendering by default if supported

### 2. Enhanced Query Phase

**v1.1 Enhanced Query (with all features):**
```
X-WHOIS-COLOR: scheme=ripe\r\n
X-WHOIS-MARKDOWN: true\r\n
X-WHOIS-IMAGES: png,jpg\r\n
example.com\r\n
```

**v1.0 Compatible Query (color only):**
```
X-WHOIS-COLOR: scheme=ripe\r\n
example.com\r\n
```

**Standard Query (no protocol support):**
```
example.com\r\n
```

### 3. Response Processing

**v1.1 Enhanced Response Processing:**
1. **Markdown Detection**: Check if response contains Markdown syntax
2. **Client Rendering**: Render Markdown with colored output and image display
3. **Hyperlink Processing**: Add clickable links for non-Markdown content
4. **Coloring Fallback**: Apply client-side colors if server doesn't provide them

**v1.0/Standard Response Processing:**
1. **Color Detection**: Check for ANSI escape sequences
2. **Hyperlink Processing**: Add clickable links for RIR responses  
3. **Client Coloring**: Apply colors if server doesn't provide them

## Protocol Headers

### Capability Probe
- `X-WHOIS-COLOR-PROBE: v1.1` - Probe server for protocol support

### Server Capability Response
- `X-WHOIS-COLOR-SUPPORT: v1.1 schemes=ripe,bgptools,mtf markdown=true images=png,jpg` - v1.1 capabilities
- `X-WHOIS-COLOR-SUPPORT: v1.0 schemes=ripe,bgptools,mtf` - v1.0 capabilities (legacy)

### Request Headers
- `X-WHOIS-COLOR: scheme=ripe` - Request specific coloring scheme
- `X-WHOIS-MARKDOWN: true` - Request Markdown-formatted response
- `X-WHOIS-IMAGES: png,jpg,gif` - Request image support with supported formats

## Supported Features

### Coloring Schemes
1. **ripe** - RIPE format standard coloring (field:value pairs)
2. **bgptools** - BGP.tools table format coloring
3. **mtf** - Rainbow flag color scheme (Easter egg)

### Markdown Support (v1.1)
- **Headers**: H1-H6 with colored styling
- **Text Formatting**: **Bold**, *italic*, `inline code`
- **Code Blocks**: Syntax-highlighted blocks with language hints
- **Lists**: Ordered and unordered lists with proper indentation
- **Links**: Clickable hyperlinks with terminal support
- **Blockquotes**: Visual indicators with colored borders
- **Rules**: Horizontal separators
- **Tables**: Formatted table display (future enhancement)

### Image Support (v1.1)
- **Embedded Images**: Base64-encoded data URLs (`data:image/png;base64,...`)
- **Local Files**: Direct file path references
- **Remote Images**: HTTP/HTTPS URLs (displayed as clickable links)
- **Supported Formats**: PNG, JPG, GIF, WebP (via viuer library)
- **Terminal Display**: Automatic sizing, color quantization, and aspect ratio preservation

## Backward Compatibility

### Protocol Version Compatibility
- **v1.1 ↔ v1.0**: v1.1 clients gracefully downgrade to v1.0 features
- **v1.1 ↔ Standard**: Full fallback to standard WHOIS behavior
- **v1.0 ↔ Standard**: Seamless color-only protocol operation

### Feature Degradation
1. **No Markdown Support**: Falls back to hyperlink processing + client-side coloring
2. **No Image Support**: Images displayed as text links with descriptions
3. **No Color Support**: Client-side coloring applied automatically
4. **No Protocol Support**: Standard WHOIS query with client-side enhancements

### Server Compatibility
- **Timeout Mechanism**: 2-second capability probe timeout
- **Error Recovery**: All protocol failures result in standard WHOIS fallback
- **Resource Safety**: Built-in limits prevent resource exhaustion

## Implementation Details

### Capability Probe Implementation
```rust
pub fn probe_capabilities(&self, server_address: &str) -> Result<ServerCapabilities> {
    // Connect to server
    let mut stream = TcpStream::connect(server_address)?;
    
    // Set short timeout
    stream.set_read_timeout(Some(Duration::from_millis(2000)))?;
    
    // Send probe request
    stream.write_all(b"X-WHOIS-COLOR-PROBE: v1.0\r\n\r\n")?;
    
    // Read and parse response
    let mut response = String::new();
    stream.read_to_string(&mut response)?;
    
    Ok(parse_capability_response(&response))
}
```

### Query Implementation
```rust
pub fn query_with_color(&self, query: &str, capabilities: &ServerCapabilities) -> Result<String> {
    let query_string = if capabilities.supports_color {
        format!("X-WHOIS-COLOR: scheme=ripe\r\n{}\r\n", query)
    } else {
        format!("{}\r\n", query)
    };
    
    // Standard TCP connection and query...
}
```

### Response Detection
```rust
pub fn is_server_colored(&self, response: &str) -> bool {
    // Check for ANSI color sequences
    response.contains("\x1b[") || 
    // Check for protocol markers (optional)
    response.contains("X-WHOIS-COLOR-APPLIED:")
}
```

## Usage Examples

### v1.1 Enhanced Features
```bash
# Enable all v1.1 features
whois example.com --markdown --images --verbose

# Markdown formatting only
whois example.com --markdown

# Image support only  
whois example.com --images

# Combine with other features
whois AS15169 --markdown --images --42 --verbose
```

### Legacy v1.0 Compatibility
```bash
# Standard color-only mode (v1.0 compatible)
whois example.com --verbose

# Disable server-side features completely
whois example.com --no-server-color
```

### Output Examples

#### v1.1 Server with Full Features
```
$ whois --markdown --images --verbose example.com
Query: example.com
Probing color capabilities for: whois.iana.org:43
Server capabilities: { supports_color: true, supports_markdown: true, supports_images: true, schemes: ["ripe"], image_formats: ["png", "jpg"] }
Requesting server-side coloring with scheme: ripe
Requesting Markdown format
Requesting image support
Querying IANA at: whois.iana.org:43
IANA referred to: whois.verisign-grs.com
Final server used: whois.verisign-grs.com
Server-side coloring: enabled
Rendering Markdown content

# WHOIS Result for example.com

## Domain Information
- **Domain**: example.com
- **Status**: Active
- **Registrar**: Example Registrar Inc.

### Network Diagram
![Network Topology](data:image/png;base64,iVBORw0KGgo...)

For more information, visit [Example Registrar](https://example-registrar.com)
```

#### v1.0 Legacy Server (Color Only)
```
$ whois --verbose example.com  
Query: example.com
Probing color capabilities for: whois.iana.org:43
Server capabilities: { supports_color: true, schemes: ["ripe"], protocol_version: "v1.0" }
Requesting server-side coloring with scheme: ripe
Final server used: whois.verisign-grs.com
Server-side coloring: enabled
Using server-provided coloring

domain:      example.com
registrar:   Example Registrar Inc.
status:      ACTIVE
```

#### Standard WHOIS Server (No Protocol Support)
```
$ whois --verbose example.com
Query: example.com
Probing color capabilities for: whois.iana.org:43
No capability response, assuming standard WHOIS
Final server used: whois.verisign-grs.com
Server coloring not available, using client-side coloring

domain:      example.com
registrar:   Example Registrar Inc.
status:      ACTIVE
```

## Server-side Implementation Guide

### v1.1 Full Implementation
1. **Capability Handling**: Respond to `X-WHOIS-COLOR-PROBE: v1.1` requests
2. **Feature Detection**: Parse and respond to all three request headers
3. **Markdown Generation**: Generate CommonMark-compatible responses
4. **Image Embedding**: Support data URLs, file references, or remote links
5. **Color Integration**: Combine with existing color schemes

### v1.0 Legacy Implementation  
1. **Color-only Support**: Handle `X-WHOIS-COLOR-PROBE: v1.0` requests
2. **ANSI Coloring**: Return responses with ANSI escape sequences
3. **Graceful Handling**: Ignore unknown v1.1 headers

### Example Server Responses

#### v1.1 Capability Response
```
X-WHOIS-COLOR-SUPPORT: v1.1 schemes=ripe,bgptools markdown=true images=png,jpg,gif\r\n
```

#### v1.1 Markdown Response
```
# WHOIS Information for example.com

## Registry Information
- **Domain**: example.com  
- **Registrar**: Example Registrar Inc.
- **Status**: **ACTIVE**
- **Created**: 1995-08-14
- **Expires**: 2025-08-13

## Technical Details
```rust
// DNS Configuration
A     93.184.216.34
AAAA  2606:2800:220:1:248:1893:25c8:1946
```

### Network Topology
![Network Diagram](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA...)

For technical support, contact [support@example.com](mailto:support@example.com)
```

#### v1.0 Colored Response
```
domain:      \x1b[1;37mexample.com\x1b[0m
registrar:   \x1b[1;36mExample Registrar Inc.\x1b[0m  
status:      \x1b[1;32mACTIVE\x1b[0m
created:     \x1b[0;33m1995-08-14\x1b[0m
expires:     \x1b[0;31m2025-08-13\x1b[0m
```

## Security Considerations

### Protocol Security
1. **Header Validation**: Strict validation of all protocol headers and parameters
2. **Resource Limits**: Maximum response sizes, timeouts, and connection limits  
3. **Safe Degradation**: All protocol failures result in safe standard WHOIS fallback
4. **Injection Protection**: Prevent command injection through malformed headers

### Content Security (v1.1)
1. **Markdown Sanitization**: Strip dangerous HTML and script elements from Markdown
2. **Image Validation**: Verify image formats, file sizes, and prevent path traversal
3. **URL Filtering**: Validate and sanitize remote image and link URLs
4. **Base64 Limits**: Restrict embedded image data size to prevent memory exhaustion

### Client Security
1. **Response Validation**: Validate all server responses before processing
2. **Resource Monitoring**: Monitor memory and CPU usage during rendering
3. **Timeout Controls**: Implement timeouts for image loading and rendering operations
4. **Privilege Restrictions**: Run with minimal required privileges

## Test Coverage

The protocol implementation includes comprehensive unit tests covering:

### Core Protocol Tests
- Capability response parsing (v1.0 and v1.1 formats)
- Header generation and validation
- Color scheme selection and fallback logic
- Protocol version detection and compatibility

### Enhanced Feature Tests  
- Markdown syntax detection and rendering
- Image format support and validation
- Base64 decoding and error handling
- Terminal display capabilities

### Compatibility Tests
- v1.1 ↔ v1.0 downgrade scenarios
- v1.1 ↔ Standard WHOIS fallback behavior  
- Error recovery and graceful degradation
- Resource limit enforcement

**Test Results**: All 35 tests pass, ensuring protocol stability and reliability.

## Version History

- **v1.0** (2024): Initial server-side coloring protocol
  - ANSI color support
  - Multiple color schemes (RIPE, BGP.tools, MTF)
  - Backward compatibility with standard WHOIS

- **v1.1** (2024): Enhanced multimedia protocol  
  - Markdown formatting support with colored terminal rendering
  - Inline image display (Base64, local files, remote URLs)
  - Full backward compatibility with v1.0 and standard WHOIS
  - Progressive feature enhancement based on server capabilities

## Implementation Status

This specification is fully implemented in the `whois` Rust client (v0.3.1) and is ready for server adoption. The protocol provides a foundation for rich, multimedia WHOIS responses while maintaining complete compatibility with existing infrastructure.