IFO - Identified Flying Object

A blazing-fast Rust CLI application for querying real-time aircraft information flying over any location worldwide.

🤖 Built with AI Assistance

This project was developed with the help of Claude Code and enhanced with ChunkHound semantic code search for efficient codebase navigation and understanding.

Features

• 🚀 Blazing fast: Sub-5ms startup time, efficient async I/O
• 🌍 Query by location: Use coordinates or place names
• ✈️ Real-time data: Live aircraft tracking via OpenSky Network API
• 🔍 Flexible search: Configurable search radius
• 🔒 Secure: Input validation, rate limiting, HTTPS-only
• 💾 Lightweight: Single 2.4MB binary, 12.5MB memory footprint

Performance

• Startup: 3.5ms (sub-5ms)
• Query time: 133ms average
• Memory: 12.5MB lightweight footprint
• Binary size: 2.4MB single executable

Installation

Pre-built binaries are available for Linux, macOS (Intel & Apple Silicon), and Windows. See INSTALL.md for detailed installation instructions.

Quick start:

• Download the latest release from GitLab Releases
• Or build from source: cargo build --release

Usage

Query by Coordinates

ifo --coords "37.7,-122.4"

Query by Place Name

ifo --place "San Francisco"
ifo --place "London, UK"
ifo --place "Tokyo, Japan"

Custom Search Radius

# Search radius in degrees (default: 0.5° ≈ 55km)
ifo --place "New York" --radius 1.0

Custom Timeout

ifo --coords "51.5,-0.1" --timeout 15

Example Output

Found location: San Francisco, California, USA (37.7749, -122.4194)
Found 52 aircraft near San Francisco, California, USA:

Callsign: UAL123
  ICAO24: abc123
  Country: United States
  Position: 37.7500, -122.4500
  Altitude: 10000 m
  Velocity: 250.5 m/s

Callsign: SWA456
  ICAO24: def456
  Country: United States
  Position: 37.8000, -122.3800
  Altitude: 8500 m
  Velocity: 220.0 m/s

...

Development

Run Tests

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_bounding_box_validation

Build

# Debug build
cargo build

# Release build (optimized)
cargo build --release

Project Structure

ifo/
├── Cargo.toml         # Package manifest and dependencies
├── src/
│   ├── main.rs        # CLI entry point
│   ├── lib.rs         # Library root
│   ├── api.rs         # OpenSky Network API client
│   ├── geocoding.rs   # Place name to coordinates converter
│   ├── models.rs      # Data structures (Aircraft, BoundingBox, etc.)
│   └── error.rs       # Error types
└── CHANGELOG.md       # Release history

Architecture

The application uses a modular async architecture:

1. CLI Layer (main.rs): Handles user input and output formatting with clap
2. Geocoding Layer (geocoding.rs): Converts place names to coordinates using Nominatim/OpenStreetMap
3. API Layer (api.rs): Queries OpenSky Network for aircraft data
4. Models Layer (models.rs): Type-safe data structures with validation
5. Error Layer (error.rs): Comprehensive error handling with thiserror

Data Sources

• Aircraft Data: OpenSky Network - Community-based ADS-B/Mode S data
• Geocoding: Nominatim - OpenStreetMap geocoding service

Key Technologies

• Async Runtime: Tokio for efficient async I/O
• HTTP Client: reqwest with connection pooling
• CLI Framework: clap v4 with derive macros
• Rate Limiting: governor crate for precise 1 req/sec limit
• Error Handling: thiserror for ergonomic error types
• Serialization: serde/serde_json for zero-copy JSON parsing

Security

• All API calls use HTTPS
• Type-safe input validation at compile time
• Rate limiting (1 req/sec for Nominatim API)
• No API keys or credentials required
• Memory-safe Rust implementation

Changelog

See CHANGELOG.md for a detailed history of changes, releases, and version notes. We follow Keep a Changelog format and Semantic Versioning.

Latest Release: v0.1.0 - Initial release with cross-platform binaries and automated CI/CD.

Branding

• GitLab project icon: assets/gitlab-project-icon.svg (512×512, vector, gradient background with aircraft motif)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please ensure:

• All tests pass (cargo test)
• Code follows Rust best practices (cargo clippy)
• Format code (cargo fmt)
• Sign your commits using SSH or GPG (see .signing-info for setup instructions)

Setting Up Commit Signing

This project requires signed commits for security and authenticity. We use SSH-based signing (Git 2.34+):

# Configure SSH signing (recommended)
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true
git config --global tag.gpgsign true

See .signing-info for detailed instructions.