sal/net/README.md

# SAL Network Package

Network connectivity utilities for TCP, HTTP, and SSH operations.

## Overview

The `sal-net` package provides a comprehensive set of network connectivity tools for the SAL (System Abstraction Layer) ecosystem. It includes utilities for TCP port checking, HTTP/HTTPS connectivity testing, and SSH command execution.

## Features

### TCP Connectivity
- **Port checking**: Test if specific TCP ports are open
- **Multi-port checking**: Test multiple ports simultaneously  
- **ICMP ping**: Test host reachability using ping
- **Configurable timeouts**: Customize connection timeout values

### HTTP/HTTPS Connectivity
- **URL reachability**: Test if URLs are accessible
- **Status code checking**: Get HTTP status codes from URLs
- **Content fetching**: Download content from URLs
- **Status verification**: Verify URLs return expected status codes

### SSH Operations
- **Command execution**: Run commands on remote hosts via SSH
- **Connection testing**: Test SSH connectivity to hosts
- **Builder pattern**: Flexible SSH connection configuration
- **Custom authentication**: Support for identity files and custom ports

## Rust API

### TCP Operations

```rust
use sal_net::TcpConnector;
use std::time::Duration;

// Create a TCP connector
let connector = TcpConnector::new();

// Check if a port is open
let is_open = connector.check_port("127.0.0.1".parse().unwrap(), 80).await?;

// Check multiple ports
let ports = vec![22, 80, 443];
let results = connector.check_ports("example.com".parse().unwrap(), &ports).await?;

// Ping a host
let is_reachable = connector.ping("google.com").await?;
```

### HTTP Operations

```rust
use sal_net::HttpConnector;

// Create an HTTP connector
let connector = HttpConnector::new()?;

// Check if a URL is reachable
let is_reachable = connector.check_url("https://example.com").await?;

// Get status code
let status = connector.check_status("https://example.com").await?;

// Fetch content
let content = connector.get_content("https://api.example.com/data").await?;

// Verify specific status
let matches = connector.verify_status("https://example.com", reqwest::StatusCode::OK).await?;
```

### SSH Operations

```rust
use sal_net::SshConnectionBuilder;
use std::time::Duration;

// Build an SSH connection
let connection = SshConnectionBuilder::new()
    .host("example.com")
    .port(22)
    .user("username")
    .timeout(Duration::from_secs(30))
    .build();

// Execute a command
let (exit_code, output) = connection.execute("ls -la").await?;

// Test connectivity
let is_connected = connection.ping().await?;
```

## Rhai Integration

The package provides Rhai scripting integration for network operations:

### TCP Functions

```rhai
// Check if a TCP port is open
let is_open = tcp_check("127.0.0.1", 80);
print(`Port 80 is ${is_open ? "open" : "closed"}`);

// Ping a host (cross-platform)
let can_ping = tcp_ping("google.com");
print(`Can ping Google: ${can_ping}`);
```

### HTTP Functions

```rhai
// Check if an HTTP URL is reachable
let is_reachable = http_check("https://example.com");
print(`URL is ${is_reachable ? "reachable" : "unreachable"}`);

// Get HTTP status code
let status = http_status("https://example.com");
print(`HTTP status: ${status}`);
```

### SSH Functions

```rhai
// Execute SSH command and get exit code
let exit_code = ssh_execute("example.com", "user", "ls -la");
print(`SSH command exit code: ${exit_code}`);

// Execute SSH command and get output
let output = ssh_execute_output("example.com", "user", "whoami");
print(`SSH output: ${output}`);

// Test SSH connectivity
let can_connect = ssh_ping("example.com", "user");
print(`SSH connection: ${can_connect ? "success" : "failed"}`);
```

### Example Rhai Script

```rhai
// Network connectivity test script
print("=== Network Connectivity Test ===");

// Test TCP connectivity
let ports = [22, 80, 443];
for port in ports {
    let is_open = tcp_check("example.com", port);
    print(`Port ${port}: ${is_open ? "OPEN" : "CLOSED"}`);
}

// Test ping connectivity
let hosts = ["google.com", "github.com", "stackoverflow.com"];
for host in hosts {
    let can_ping = tcp_ping(host);
    print(`${host}: ${can_ping ? "REACHABLE" : "UNREACHABLE"}`);
}

// Test HTTP connectivity
let urls = ["https://google.com", "https://github.com", "https://httpbin.org/status/200"];
for url in urls {
    let is_reachable = http_check(url);
    let status = http_status(url);
    print(`${url}: ${is_reachable ? "REACHABLE" : "UNREACHABLE"} (Status: ${status})`);
}

// Test SSH connectivity (requires SSH access)
let ssh_hosts = ["example.com"];
for host in ssh_hosts {
    let can_connect = ssh_ping(host, "user");
    print(`SSH ${host}: ${can_connect ? "CONNECTED" : "FAILED"}`);
}
```

## Testing

The package includes comprehensive tests:

```bash
# Run all tests
cargo test

# Run specific test suites
cargo test --test tcp_tests
cargo test --test http_tests  
cargo test --test ssh_tests
cargo test --test rhai_integration_tests

# Run Rhai script tests
cargo test --test rhai_integration_tests
```

## Dependencies

- `tokio`: Async runtime for network operations
- `reqwest`: HTTP client functionality
- `anyhow`: Error handling
- `rhai`: Scripting integration

## Security Considerations

- SSH operations use the system's SSH client for security
- HTTP operations respect standard timeout and security settings
- No credentials are logged or exposed in error messages
- Network timeouts prevent hanging operations

## Platform Support

- **Linux**: Full support for all features
- **macOS**: Full support for all features  
- **Windows**: TCP and HTTP support (SSH requires SSH client installation)

## Error Handling

All network operations return `Result` types with meaningful error messages. Operations gracefully handle:

- Network timeouts
- Connection failures
- Invalid hostnames/URLs
- Authentication failures (SSH)
- System command failures

## Performance

- Async operations for non-blocking network calls
- Configurable timeouts for responsive applications
- Efficient connection reuse where possible
- Minimal memory footprint for network operations