SwiftFTR v0.3.0 Release Notes

Overview

SwiftFTR v0.3.0 is a major release that transforms the library into an actor-based architecture, adds comprehensive caching capabilities, reverse DNS support, and trace cancellation. This release maintains full backward compatibility while adding powerful new features for production use.

🎯 Key Features

Actor-Based Architecture

SwiftFTR is now an actor - Thread-safe by design with Swift 6 strict concurrency
TraceHandle actor - Enables cancellation of in-flight traces
RDNSCache actor - Manages reverse DNS lookups with TTL-based caching

Reverse DNS Support

Built-in rDNS lookups - Automatic hostname resolution for all hops
Configurable caching - Default 86400 second (24 hour) TTL
Batch operations - Efficient parallel lookups for all IPs
LRU eviction - Memory-efficient with configurable cache size

STUN Public IP Caching

Cached discovery - Public IP is cached between traces
Network-aware - Cache invalidates on network changes
Reduced latency - Saves 100-500ms per trace

Trace Cancellation

Responsive cancellation - 100ms polling intervals for quick response
Automatic cleanup - Cancelled traces free resources immediately
Task integration - Works with Swift's structured concurrency

Network Change Management

Single API - networkChanged() handles all cache invalidation
Comprehensive reset - Cancels active traces and clears all caches
Production ready - Ideal for mobile/laptop network transitions

Code Quality Improvements

Periphery integration - Automated unused code detection
Removed deprecated code - 109 lines of unused WHOIS implementation
Cleaner API - Removed deprecated properties

📝 API Changes

New Methods

// Network change handling
public func networkChanged() async

// Cache management
public var publicIP: String? { get }
public func clearCaches() async
public func invalidatePublicIP()

New Configuration Options

public struct SwiftFTRConfig {
    public let noReverseDNS: Bool        // Disable rDNS lookups
    public let rdnsCacheTTL: TimeInterval?  // Cache TTL in seconds
    public let rdnsCacheSize: Int?       // Max cache entries
}

Enhanced Data Models

// TraceHop now includes hostname
public struct TraceHop {
    public let hostname: String?  // New field
}

// ClassifiedHop includes hostname
public struct ClassifiedHop {
    public let hostname: String?  // New field
}

// ClassifiedTrace includes hostnames
public struct ClassifiedTrace {
    public let destinationHostname: String?  // New field
    public let publicHostname: String?       // New field
}

🚀 Performance Improvements

Caching Performance

ASN lookups: Already cached, no change
rDNS lookups: ~50ms uncached → ~0ms cached
STUN public IP: ~200ms uncached → ~0ms cached

Memory Usage

rDNS cache: Default 1000 entries with LRU eviction
Efficient batching: Parallel lookups reduce memory pressure
Actor isolation: Prevents race conditions and memory corruption

🔧 Migration Guide

For Library Users

The API is backward compatible, but note these changes:

SwiftFTR is now an actor - All methods already required await, no change needed
New hostname fields - Access via hop.hostname in results
Network changes - Call await tracer.networkChanged() when network changes

Example Migration

// v0.2.0 (still works)
let tracer = SwiftFTR()
let result = try await tracer.trace(to: "example.com")

// v0.3.0 (with new features)
let tracer = SwiftFTR(config: SwiftFTRConfig(
    noReverseDNS: false,  // Enable rDNS
    rdnsCacheTTL: 3600    // 1 hour cache
))

let result = try await tracer.trace(to: "example.com")
for hop in result.hops {
    if let hostname = hop.hostname {
        print("\(hop.ttl): \(hostname)")
    }
}

// Handle network changes
await tracer.networkChanged()

🐛 Bug Fixes

Fixed potential race conditions in concurrent traces
Improved error handling for network timeouts
Better handling of ICMP rate limiting

📚 Documentation

New AI_REFERENCE.md - Comprehensive 1000+ line API reference
Enhanced examples - Real-world trace data samples
Periphery setup - .periphery.yml for code quality

🧪 Testing

All 44 existing tests pass
Tested with Swift 6 strict concurrency checking
Verified on macOS 13, 14, and 15
Periphery scan shows cleaner codebase

💔 Breaking Changes

None. This release maintains full backward compatibility.

🗑️ Deprecated

Removed CymruWhoisResolver (unused TCP WHOIS implementation)
Removed deprecated host property from TraceHop

📦 Dependencies

Swift 6.1+ (required)
macOS 13+ (required)
No external dependencies

🙏 Acknowledgments

Thanks to all contributors and users who provided feedback for this release.

📊 Statistics

Added: 500+ lines of new functionality
Removed: 109 lines of unused code
Files changed: 11
Test coverage: 44 tests, all passing

🚦 Known Issues

IPv6 support still pending (planned for v0.4.0)
Some CLI warnings from swift-format (intentional for JSON compatibility)

📈 What's Next

See ROADMAP.md for upcoming features:

v0.4.0: VPN/Zero Trust/SASE support
v0.5.0: Offline ASN support
v0.6.0: Enhanced protocol support
v0.7.0: IPv6 support

📥 Installation

Swift Package Manager

dependencies: [
    .package(url: "https://github.com/Network-Weather/SwiftFTR.git", from: "0.3.0")
]

CLI Tool

swift build -c release
cp .build/release/swift-ftr /usr/local/bin/

📝 Full Changelog

See CHANGELOG.md for complete history.

Released: December 2024

v0.3.0 - Actor-based architecture with caching and cancellation