socks-abstract5 0.1.0

# socks-abstract5

A high-performance, RFC-compliant SOCKS5 proxy implementation in Rust.

## Features

- Full RFC 1928 SOCKS5 protocol implementation
- Asynchronous architecture using Tokio
- Support for all SOCKS5 commands:
  - CONNECT
  - BIND
  - UDP ASSOCIATE
- Comprehensive address type support:
  - IPv4
  - IPv6
  - Domain names
- Zero-copy data transfer
- Robust error handling
- No external dependencies beyond Tokio and thiserror

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
socks-abstract5 = "0.1.0"
```

## Quick Start

### Running as a Standalone Proxy

```rust
use socks_abstract5::Socks5Server;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = Socks5Server::new("127.0.0.1:1080").await?;
    server.run().await?;
    Ok(())
}
```

### Using as a Library

```rust
use socks_abstract5::{Socks5Server, Result};

async fn start_proxy(bind_address: &str) -> Result<()> {
    let server = Socks5Server::new(bind_address).await?;
    server.run().await
}
```

## Technical Documentation

### Architecture

socks-abstract5 is built on a fully asynchronous architecture, leveraging Tokio for high-performance I/O operations. The implementation follows a modular design with clear separation of concerns:

- Protocol handling (authentication, command processing)
- Address resolution
- Data transfer
- Error management

### Protocol Implementation

#### Authentication

Currently supports:
- No authentication (0x00)
- Extensible framework for adding additional authentication methods

#### Commands

1. CONNECT (0x01)
   - Establishes TCP connections to remote servers
   - Supports both direct IP connections and domain name resolution
   - Implements full duplex communication

2. BIND (0x02)
   - Supports reverse connection scenarios
   - Implements two-phase reply mechanism
   - Includes source address validation

3. UDP ASSOCIATE (0x03)
   - Creates UDP association for datagram transport
   - Maintains TCP control connection
   - Supports UDP relay functionality

#### Address Types

- IPv4 (0x01)
- Domain Name (0x03)
- IPv6 (0x04)

### Error Handling

Comprehensive error handling using custom error types:

```rust
pub enum Error {
    Io(std::io::Error),
    InvalidVersion,
    AuthFailed,
    InvalidCommand(u8),
    InvalidAddrType(u8),
    ConnectionNotAllowed,
    NetworkUnreachable,
    HostUnreachable,
    ConnectionRefused,
    TtlExpired,
    ProtocolError,
    AddrTypeNotSupported,
}
```

### Performance Considerations

- Zero-copy data transfer where possible
- Efficient memory usage with appropriate buffer sizes
- Asynchronous I/O for optimal resource utilization
- Connection pooling and reuse
- Minimal allocations during proxy operations

## Configuration

Default configuration values:

```rust
const DEFAULT_BACKLOG: u32 = 1024;
const BUFFER_SIZE: usize = 8192;
const DEFAULT_TIMEOUT: Duration = Duration::from_secs(300);
```

## Security Considerations

- No cleartext password authentication
- Connection validation
- Source address verification for BIND command
- Proper handling of connection timeouts
- Clean shutdown procedures

## License

Mozilla Public License 2.0 (MPL-2.0)

## Future Roadmap

- Authentication methods (Username/Password, GSSAPI)
- Configuration file support
- TLS/SSL support
- Connection pooling
- Advanced logging and metrics
- Rule-based access control
- HTTP/HTTPS proxy support
- Docker container support
- WebAssembly compilation target

## Acknowledgments

This implementation follows the SOCKS Protocol Version 5 specification as defined in RFC 1928.