Release v0.2.0: HTTP proxy support and expanded integration tests

Added:
- HTTP proxy support via CONNECT tunneling with authentication
- ProxyConfig for explicit proxy settings or from $HTTP_PROXY env
- Integration tests against SNIP Demo Caster and IGS
- Dynamic connection tests for RTK2go and Centipede

Changed:
- Expanded tested casters documentation in README
- Improved testing documentation

Author: gsokoll

CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-01-10
+
+### Added
+
+- HTTP proxy support via CONNECT tunneling
+- Integration tests against SNIP Demo Caster and IGS
+- Dynamic connection tests for RTK2go and Centipede (no credentials required)
+- `ProxyConfig` struct for proxy configuration
+- `NtripConfig::with_proxy()` for explicit proxy settings
+- `NtripConfig::with_proxy_from_env()` to read from `$HTTP_PROXY` environment variable
+- `ProxyConfig::from_url()` for parsing proxy URLs
+- Proxy authentication support (Basic auth)
+
+### Changed
+
+- Improved README with feature highlights and usage examples
+- Added documentation for logging via `tracing`
+- Expanded tested casters documentation in README
+
 ## [0.1.0] - 2025-12-20
 
 ### Added
@@ -27,5 +46,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Integration tests against public casters
 - GitHub Actions CI workflow
 
-[Unreleased]: https://github.com/greenforge-labs/ntrip-core/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/greenforge-labs/ntrip-core/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/greenforge-labs/ntrip-core/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/greenforge-labs/ntrip-core/releases/tag/v0.1.0

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ntrip-core"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 rust-version = "1.75"
 authors = ["GreenForge Labs"]

README.md

@@ -1,5 +1,11 @@
 # ntrip-core
 
+[![Crates.io](https://img.shields.io/crates/v/ntrip-core.svg)](https://crates.io/crates/ntrip-core)
+[![Documentation](https://docs.rs/ntrip-core/badge.svg)](https://docs.rs/ntrip-core)
+[![CI](https://github.com/greenforge-labs/ntrip-core/workflows/CI/badge.svg)](https://github.com/greenforge-labs/ntrip-core/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![MSRV](https://img.shields.io/badge/MSRV-1.75-blue.svg)](https://www.rust-lang.org)
+
 An async NTRIP client library for Rust.
 
 ## Features
@@ -9,6 +15,20 @@ An async NTRIP client library for Rust.
 - **Discovery**: Sourcetable retrieval and nearest mountpoint selection
 - **Async**: Built on Tokio for efficient async I/O
 - **Robust**: Read timeouts, automatic reconnection (configurable), proper error handling
+- **Proxy**: HTTP proxy support via CONNECT tunneling
+
+See the [API documentation](https://docs.rs/ntrip-core) for complete usage details.
+
+## Why ntrip-core?
+
+- **No OpenSSL dependency** - TLS via rustls simplifies cross-compilation and deployment
+- **Async-native** - Built on Tokio from the ground up, not blocking wrappers
+- **Complete protocol support** - Both NTRIP v1 and v2 with automatic version detection
+- **Sourcetable discovery** - Parse sourcetables and find nearest mountpoint by coordinates
+- **HTTP proxy support** - CONNECT tunneling with optional proxy authentication
+- **Cancellation-safe** - Works naturally with `tokio::select!` for timeouts and shutdown
+- **GGA position reporting** - Both in-stream and v2 header methods supported
+- **Automatic reconnection** - Configurable retry with GGA state preservation
 
 ## Quick Start
 
@@ -62,6 +82,25 @@ let config = NtripConfig::new("secure-caster.example.com", 443, "MOUNT")
 
 By default, connections use plain TCP. Call `.with_tls()` to enable TLS.
 
+## HTTP Proxy
+
+Connect through an HTTP proxy using the CONNECT method:
+
+```rust
+use ntrip_core::{NtripConfig, ProxyConfig};
+
+// Explicit proxy configuration
+let proxy = ProxyConfig::new("proxy.example.com", 8080)
+    .with_credentials("proxy_user", "proxy_pass");
+
+let config = NtripConfig::new("caster.example.com", 2101, "MOUNT")
+    .with_proxy(proxy);
+
+// Or read from $HTTP_PROXY environment variable
+let config = NtripConfig::new("caster.example.com", 2101, "MOUNT")
+    .with_proxy_from_env();
+```
+
 ## Sourcetable Discovery
 
 ```rust
@@ -95,13 +134,42 @@ cargo run --example connect -- rtk2go.com Laguna01 2101 --user=you@example.com -
 # Run unit tests
 cargo test
 
-# Run comprehensive test suite against real casters
-bash ./scripts/test_suite.sh --quick   # Sourcetable only
-bash ./scripts/test_suite.sh --full    # + nearest mountpoint tests
-bash ./scripts/test_suite.sh --connect # + connection tests (requires credentials)
+# Run integration tests against real public casters (no credentials needed)
+just test-integration
+# or: cargo test --test integration -- --ignored
+
+# Run shell-based test suite against real casters
+just test-suite          # Sourcetable only
+just test-suite-full     # + nearest mountpoint tests
+just test-suite-connect  # + connection tests (requires credentials)
+```
+
+The integration tests fetch sourcetables from all public casters listed below, and include dynamic connection tests that find active mountpoints and stream real RTCM data from RTK2go and Centipede - no private credentials required.
+
+For the shell-based connection tests, copy `scripts/credentials.env.template` to `scripts/credentials.env` and fill in your credentials.
+
+## Logging
+
+This crate uses [`tracing`](https://docs.rs/tracing) for structured logging. Enable with a subscriber:
+
+```rust
+tracing_subscriber::fmt::init();
 ```
 
-For connection tests, copy `scripts/credentials.env.template` to `scripts/credentials.env` and fill in your credentials.
+## Tested Casters
+
+This library is regularly tested against these public NTRIP casters:
+
+| Caster | Host | Auth | Notes |
+|--------|------|------|-------|
+| **RTK2go** | rtk2go.com:2101 | Email/none | Large public caster, 1000+ streams |
+| **Centipede** | caster.centipede.fr:2101 | None | Open French/EU RTK network |
+| **EUREF** | euref-ip.net:2101 | None* | European reference stations |
+| **IGS** | igs-ip.net:2101 | None* | International GNSS Service |
+| **SNIP Demo** | ntrip.use-snip.com:2101 | None | Demo caster for testing |
+| **AUSCORS** | ntrip.data.gnss.ga.gov.au:443 | Required | Geoscience Australia (HTTPS) |
+
+\* Some streams may require registration
 
 ## Development
 

scripts/test_suite.sh

@@ -127,18 +127,21 @@ print_summary() {
 # =============================================================================
 run_sourcetable_tests() {
     echo -e "\n${BLUE}=== SOURCETABLE TESTS ===${NC}"
-    
+
     # RTK2go - Large public caster
     run_test "RTK2go sourcetable" "$SOURCETABLE" rtk2go.com 2101
-    
+
     # EUREF - European reference stations
     run_test "EUREF sourcetable" "$SOURCETABLE" euref-ip.net 2101
-    
+
     # Centipede - French open community
     run_test "Centipede sourcetable" "$SOURCETABLE" caster.centipede.fr 2101
-    
+
     # IGS - International GNSS Service
     run_test "IGS sourcetable" "$SOURCETABLE" igs-ip.net 2101
+
+    # SNIP Demo Caster - Good for protocol testing
+    run_test "SNIP Demo sourcetable" "$SOURCETABLE" ntrip.use-snip.com 2101
 }
 
 # =============================================================================

src/client.rs

@@ -10,16 +10,17 @@
 //! - Auto-detection of protocol version from server response
 //! - Basic Authentication
 //! - TLS/HTTPS support for secure connections
+//! - HTTP proxy support via CONNECT tunneling
 //! - GGA position reporting
 
 use std::time::Duration;
-use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
 use tokio::net::TcpStream;
 use tracing::{debug, error, info, warn};
 
 use base64::{engine::general_purpose::STANDARD as BASE64, Engine as _};
 
-use crate::config::{NtripConfig, NtripVersion};
+use crate::config::{NtripConfig, NtripVersion, ProxyConfig};
 use crate::gga::GgaSentence;
 use crate::sourcetable::Sourcetable;
 use crate::stream::NtripStream;
@@ -79,6 +80,130 @@ impl NtripClient {
         self.connect_with_gga(None).await
     }
 
+    /// Establish a TCP connection, optionally through an HTTP proxy.
+    ///
+    /// If a proxy is configured, this connects to the proxy and uses HTTP CONNECT
+    /// to establish a tunnel to the target host:port.
+    async fn establish_tcp_connection(
+        target_host: &str,
+        target_port: u16,
+        proxy: Option<&ProxyConfig>,
+        timeout_secs: u32,
+    ) -> Result<TcpStream, Error> {
+        let timeout = Duration::from_secs(timeout_secs as u64);
+
+        match proxy {
+            Some(proxy_config) => {
+                let proxy_addr = format!("{}:{}", proxy_config.host, proxy_config.port);
+                info!(
+                    proxy = %proxy_addr,
+                    target = %format!("{}:{}", target_host, target_port),
+                    "Connecting via HTTP proxy"
+                );
+
+                // Connect to proxy
+                let mut stream =
+                    match tokio::time::timeout(timeout, TcpStream::connect(&proxy_addr)).await {
+                        Ok(Ok(s)) => s,
+                        Ok(Err(e)) => {
+                            return Err(Error::ProxyError {
+                                message: format!(
+                                    "Failed to connect to proxy {}:{}: {}",
+                                    proxy_config.host, proxy_config.port, e
+                                ),
+                            })
+                        }
+                        Err(_) => return Err(Error::Timeout { timeout_secs }),
+                    };
+
+                // Build HTTP CONNECT request
+                let mut connect_request = format!(
+                    "CONNECT {}:{} HTTP/1.1\r\nHost: {}:{}\r\n",
+                    target_host, target_port, target_host, target_port
+                );
+
+                // Add proxy authentication if configured
+                if let (Some(user), Some(pass)) = (&proxy_config.username, &proxy_config.password) {
+                    let credentials = format!("{}:{}", user, pass);
+                    let encoded = BASE64.encode(credentials);
+                    connect_request
+                        .push_str(&format!("Proxy-Authorization: Basic {}\r\n", encoded));
+                }
+
+                connect_request.push_str("\r\n");
+
+                debug!("Sending HTTP CONNECT request to proxy");
+
+                // Send CONNECT request
+                stream
+                    .write_all(connect_request.as_bytes())
+                    .await
+                    .map_err(|e| Error::ProxyError {
+                        message: format!("Failed to send CONNECT request: {}", e),
+                    })?;
+
+                // Read response (first line should be "HTTP/1.x 200 ...")
+                let mut reader = BufReader::new(&mut stream);
+                let mut response_line = String::new();
+
+                match tokio::time::timeout(timeout, reader.read_line(&mut response_line)).await {
+                    Ok(Ok(0)) => {
+                        return Err(Error::ProxyError {
+                            message: "Proxy closed connection without response".to_string(),
+                        })
+                    }
+                    Ok(Ok(_)) => {}
+                    Ok(Err(e)) => {
+                        return Err(Error::ProxyError {
+                            message: format!("Failed to read proxy response: {}", e),
+                        })
+                    }
+                    Err(_) => return Err(Error::Timeout { timeout_secs }),
+                }
+
+                // Check for 200 response
+                if !response_line.contains("200") {
+                    return Err(Error::ProxyError {
+                        message: format!("Proxy CONNECT failed: {}", response_line.trim()),
+                    });
+                }
+
+                debug!(response = %response_line.trim(), "Proxy tunnel established");
+
+                // Consume remaining headers until empty line
+                loop {
+                    let mut header_line = String::new();
+                    match tokio::time::timeout(timeout, reader.read_line(&mut header_line)).await {
+                        Ok(Ok(0)) => break,
+                        Ok(Ok(_)) => {
+                            if header_line.trim().is_empty() {
+                                break;
+                            }
+                        }
+                        Ok(Err(e)) => {
+                            return Err(Error::ProxyError {
+                                message: format!("Failed to read proxy headers: {}", e),
+                            })
+                        }
+                        Err(_) => return Err(Error::Timeout { timeout_secs }),
+                    }
+                }
+
+                info!("HTTP proxy tunnel established successfully");
+                Ok(stream)
+            }
+            None => {
+                // Direct connection (no proxy)
+                let addr = format!("{}:{}", target_host, target_port);
+                match tokio::time::timeout(timeout, TcpStream::connect(&addr)).await {
+                    Ok(Ok(s)) => Ok(s),
+                    Ok(Err(e)) => Err(Error::connection_failed(target_host, target_port, e)),
+                    Err(_) => Err(Error::Timeout { timeout_secs }),
+                }
+            }
+        }
+    }
+
     /// Connect to the NTRIP caster with an optional initial GGA position.
     ///
     /// For NTRIP v2, the GGA sentence is sent in the `Ntrip-GGA` header,
@@ -96,21 +221,14 @@ impl NtripClient {
 
         info!(addr = %addr, "Connecting to NTRIP caster");
 
-        // 1. Establish TCP connection
-        let tcp_stream = match tokio::time::timeout(
-            Duration::from_secs(self.config.connection.timeout_secs as u64),
-            TcpStream::connect(&addr),
+        // 1. Establish TCP connection (directly or via proxy)
+        let tcp_stream = Self::establish_tcp_connection(
+            host,
+            port,
+            self.config.proxy.as_ref(),
+            self.config.connection.timeout_secs,
         )
-        .await
-        {
-            Ok(Ok(s)) => s,
-            Ok(Err(e)) => return Err(Error::connection_failed(host, port, e)),
-            Err(_) => {
-                return Err(Error::Timeout {
-                    timeout_secs: self.config.connection.timeout_secs,
-                })
-            }
-        };
+        .await?;
 
         // 2. Optionally upgrade to TLS
         let mut stream: NtripStream = if self.config.use_tls {
@@ -488,21 +606,14 @@ impl NtripClient {
 
         info!(addr = %addr, "Fetching sourcetable from NTRIP caster");
 
-        // 1. Establish TCP connection
-        let tcp_stream = match tokio::time::timeout(
-            Duration::from_secs(config.connection.timeout_secs as u64),
-            TcpStream::connect(&addr),
+        // 1. Establish TCP connection (directly or via proxy)
+        let tcp_stream = Self::establish_tcp_connection(
+            host,
+            port,
+            config.proxy.as_ref(),
+            config.connection.timeout_secs,
         )
-        .await
-        {
-            Ok(Ok(s)) => s,
-            Ok(Err(e)) => return Err(Error::connection_failed(host, port, e)),
-            Err(_) => {
-                return Err(Error::Timeout {
-                    timeout_secs: config.connection.timeout_secs,
-                })
-            }
-        };
+        .await?;
 
         // 2. Optionally upgrade to TLS
         let mut stream: NtripStream = if config.use_tls {