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

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

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

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

// 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

// 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

// 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

// 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:

# 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