jason/socktop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reference: Usage as a lib #8

Browse Source 
- Implement protocol versioning
- migrate to thisError
- general error handling improvements in socktop_connector lib
- improve documentation
- increment  version
This commit is contained in:
jason
2025-09-07 18:55:23 -07:00
parent ffc246b705
commit 06cd6d0c82
9 changed files with 462 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
socktop_connector/README.md
+172 -15
View File
@@ -6,6 +6,8 @@ A WebSocket connector library for communicating with socktop agents.
`socktop_connector` provides a high-level, type-safe interface for connecting to socktop agents over WebSocket connections. It handles connection management, TLS certificate pinning, compression, and protocol buffer decoding automatically.
The library is designed for professional use with structured error handling that allows you to pattern match on specific error types, making it easy to implement robust error recovery and monitoring strategies.
## Features
- **WebSocket Communication**: Support for both `ws://` and `wss://` connections
@@ -14,7 +16,7 @@ A WebSocket connector library for communicating with socktop agents.
- **Type Safety**: Strongly typed requests and responses
- **Automatic Compression**: Handles gzip compression/decompression transparently
- **Protocol Buffer Support**: Decodes binary process data automatically
- **Error Handling**: Comprehensive error handling with detailed error messages
- **Error Handling**: Comprehensive error handling with structured error types for pattern matching
## Connection Types
@@ -80,6 +82,46 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
}
```
### Error Handling with Pattern Matching
Take advantage of structured error types for robust error handling:
```rust
use socktop_connector::{connect_to_socktop_agent, ConnectorError, AgentRequest};
#[tokio::main]
async fn main() {
// Handle connection errors specifically
let mut connector = match connect_to_socktop_agent("ws://localhost:3000/ws").await {
Ok(conn) => conn,
Err(ConnectorError::WebSocketError(e)) => {
eprintln!("Failed to connect to WebSocket: {}", e);
return;
}
Err(ConnectorError::UrlError(e)) => {
eprintln!("Invalid URL provided: {}", e);
return;
}
Err(e) => {
eprintln!("Connection failed: {}", e);
return;
}
};
// Handle request errors specifically
match connector.request(AgentRequest::Metrics).await {
Ok(response) => println!("Success: {:?}", response),
Err(ConnectorError::JsonError(e)) => {
eprintln!("Failed to parse server response: {}", e);
}
Err(ConnectorError::WebSocketError(e)) => {
eprintln!("Communication error: {}", e);
}
Err(e) => eprintln!("Request failed: {}", e),
}
}
```
### TLS with Certificate Pinning
```rust
@@ -127,12 +169,42 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
}
```
### WebSocket Protocol Configuration
For version compatibility (if applies), you can configure WebSocket protocol version and sub-protocols:
```rust
use socktop_connector::{ConnectorConfig, SocktopConnector, connect_to_socktop_agent_with_config};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Method 1: Using the convenience function
let connector = connect_to_socktop_agent_with_config(
"ws://localhost:3000/ws",
Some(vec!["socktop".to_string(), "v1".to_string()]), // Sub-protocols
Some("13".to_string()), // WebSocket version (13 is standard)
).await?;
// Method 2: Using ConnectorConfig builder
let config = ConnectorConfig::new("ws://localhost:3000/ws")
.with_protocols(vec!["socktop".to_string()])
.with_version("13");
let mut connector = SocktopConnector::new(config);
connector.connect().await?;
Ok(())
}
```
**Note:** WebSocket version 13 is the current standard and is used by default. The sub-protocols feature is useful for protocol negotiation with servers that support multiple protocols.
## Continuous Updates
The socktop agent provides real-time system metrics. Each request returns the current snapshot, but you can implement continuous monitoring by making requests in a loop:
```rust
use socktop_connector::{connect_to_socktop_agent, AgentRequest, AgentResponse};
use socktop_connector::{connect_to_socktop_agent, AgentRequest, AgentResponse, ConnectorError};
use tokio::time::{sleep, Duration};
#[tokio::main]
@@ -156,7 +228,23 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
}
Err(e) => {
eprintln!("Error getting metrics: {}", e);
break;
// You can pattern match on specific error types for different handling
match e {
socktop_connector::ConnectorError::WebSocketError(_) => {
eprintln!("Connection lost, attempting to reconnect...");
// Implement reconnection logic here
break;
}
socktop_connector::ConnectorError::JsonError(_) => {
eprintln!("Data parsing error, continuing...");
// Continue with next iteration for transient parsing errors
}
_ => {
eprintln!("Other error, stopping monitoring");
break;
}
}
}
_ => unreachable!(),
}
@@ -185,9 +273,12 @@ fn format_bytes(bytes: u64) -> String {
The socktop agent implements intelligent caching to avoid overwhelming the system:
- **Metrics**: Cached for ~250ms by default (fast-changing data like CPU, memory)
- **Processes**: Cached for ~1500ms by default (moderately changing data)
- **Disks**: Cached for ~1000ms by default (slowly changing data)
- **Metrics**: Cached for ~250ms by default (cheap / fast-changing data like CPU, memory)
- **Processes**: Cached for ~1500ms by default (exppensive / moderately changing data)
- **Disks**: Cached for ~1000ms by default (cheap / slowly changing data)
These values have been generally tuned in advance. You should not need to override them. The reason for this cache is for the use case that multiple clients are requesting data. In general a single client should never really hit a cached response since the polling rates are slower that the cache intervals. Cache intervals have been tuned based on how much work the agent has to do in the case of reloading fresh data.
This means:
@@ -252,6 +343,8 @@ The library provides flexible configuration through the `ConnectorConfig` builde
- `with_hostname_verification(bool)` - Control hostname verification for TLS connections
- `true` (recommended): Verify the server hostname matches the certificate
- `false`: Skip hostname verification (useful for localhost or IP-based connections)
- `with_protocols(Vec<String>)` - Set WebSocket sub-protocols for protocol negotiation
- `with_version(String)` - Set WebSocket protocol version (default is "13", the current standard)
**Note**: Hostname verification only applies to TLS connections (`wss://`). Non-TLS connections (`ws://`) don't use certificates, so hostname verification is not applicable.
@@ -272,7 +365,7 @@ tokio = { version = "1", features = ["rt", "time", "macros"] }
# Note: "net" feature not needed in WASM - WebSocket connections use browser APIs
```
### Limitations
### WASM Limitations
- **No TLS support**: `wss://` connections are not available
- **No certificate pinning**: TLS-related features are disabled
- **Browser WebSocket API**: Uses browser's native WebSocket implementation
@@ -300,9 +393,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
## Security Considerations
- **Production TLS**: Always enable hostname verification (`verify_hostname: true`) for production
- **Development/Testing**: You may disable hostname verification for localhost or IP addresses
- **Certificate Pinning**: Use `with_tls_ca()` for self-signed certificates
- **Production TLS**: You can hostname verification (`verify_hostname: true`) for production systems, This will add an additional level of production of verifying the hostname against the certificate. Generally this is to stop a man in the middle attack, but since it will be the client who is fooled and not the server, the risk and likelyhood of this use case is rather low. Which is why this is disabled by default.
- **Certificate Pinning**: Use `with_tls_ca()` for self-signed certificates, the socktop agent will generate certificates on start. see main readme for more details.
- **Non-TLS**: Use only for development or trusted networks
## Environment Variables
@@ -311,12 +403,77 @@ Currently no environment variables are used. All configuration is done through t
## Error Handling
The library uses `anyhow::Error` for error handling, providing detailed error messages for common failure scenarios:
The library uses structured error types via `thiserror` for comprehensive error handling. You can pattern match on specific error types:
- Connection failures
- TLS certificate validation errors
- Protocol errors
- Parsing errors
```rust
use socktop_connector::{connect_to_socktop_agent, ConnectorError, AgentRequest};
#[tokio::main]
async fn main() {
match connect_to_socktop_agent("invalid://url").await {
Ok(mut connector) => {
// Handle successful connection
match connector.request(AgentRequest::Metrics).await {
Ok(response) => println!("Got response: {:?}", response),
Err(ConnectorError::WebSocketError(e)) => {
eprintln!("WebSocket communication failed: {}", e);
}
Err(ConnectorError::JsonError(e)) => {
eprintln!("Failed to parse response: {}", e);
}
Err(e) => eprintln!("Other error: {}", e),
}
}
Err(ConnectorError::UrlError(e)) => {
eprintln!("Invalid URL: {}", e);
}
Err(ConnectorError::WebSocketError(e)) => {
eprintln!("Failed to connect: {}", e);
}
Err(ConnectorError::TlsError(msg)) => {
eprintln!("TLS error: {}", msg);
}
Err(e) => {
eprintln!("Connection failed: {}", e);
}
}
}
```
### Error Types
The `ConnectorError` enum provides specific variants for different error conditions:
- `ConnectorError::WebSocketError` - WebSocket connection or communication errors
- `ConnectorError::TlsError` - TLS-related errors (certificate validation, etc.)
- `ConnectorError::UrlError` - URL parsing errors
- `ConnectorError::JsonError` - JSON serialization/deserialization errors
- `ConnectorError::ProtocolError` - Protocol-level errors
- `ConnectorError::CompressionError` - Gzip compression/decompression errors
- `ConnectorError::IoError` - I/O errors
- `ConnectorError::Other` - Other errors with descriptive messages
All errors implement `std::error::Error` so they work seamlessly with `Box<dyn std::error::Error>`, `anyhow`, and other error handling crates.
### Migration from Generic Errors
If you were previously using the library with generic error handling, your existing code will continue to work:
```rust
// This continues to work as before
async fn my_function() -> Result<(), Box<dyn std::error::Error>> {
let mut connector = connect_to_socktop_agent("ws://localhost:3000/ws").await?;
let response = connector.request(AgentRequest::Metrics).await?;
Ok(())
}
// But now you can also use structured error handling for better control
async fn improved_function() -> Result<(), ConnectorError> {
let mut connector = connect_to_socktop_agent("ws://localhost:3000/ws").await?;
let response = connector.request(AgentRequest::Metrics).await?;
Ok(())
}
```
## License