URL-Checker

A lightweight Python CLI tool that validates URL format and checks server reachability.

---

Table of Contents

• About the Project
• Why This Project?
• Features
• Tech Stack
• Project Structure
• Installation
• Usage
• Commands
• Roadmap
• Contributing
• License
• Author
• Acknowledgments
• FAQ

---

About the Project

URL-Checker is a command-line utility that performs two core operations on any given URL:

1. Format Validation -- Parses and validates the URL against a comprehensive regex pattern, ensuring it uses a supported scheme (http or https), contains a valid hostname, and follows standard URL syntax.
2. Connectivity Check -- Sends an HTTP HEAD request to the validated URL and reports the server's response status and response time.

The tool is designed for quick, offline URL diagnostics without relying on web interfaces or external services.

---

Why This Project?

When working with URLs in development, scripting, or monitoring workflows, you often need a fast way to answer two questions:

• Is this URL syntactically valid?
• Is the server behind this URL actually reachable?

URL-Checker combines both checks into a single, lightweight CLI invocation. It parses URLs with named regex groups (scheme, host, port, path, query, fragment) and uses httpx for reliable HTTP connectivity testing with redirect following and configurable timeouts.

---

Features

Feature	Description
URL Format Validation	Regex-based parsing with named capture groups for scheme, host, port, path, query, and fragment
HTTP/HTTPS Support	Validates and tests URLs using both http:// and https:// schemes
IPv6 Support	Recognizes IPv6 addresses enclosed in brackets (e.g., [::1])
Domain Name Validation	Supports standard domain names with subdomains and TLDs
Port Detection	Parses and validates port numbers (1--65535 range)
HTTP HEAD Request	Uses lightweight HEAD requests to check reachability without downloading content
Redirect Following	Automatically follows HTTP redirects
Response Time Measurement	Reports server response time in milliseconds
Timeout Handling	Configurable request timeout (default: 10 seconds)
Detailed Error Reporting	Clear, descriptive error messages for each failure type
Custom User-Agent	Identifies requests with URL-Checker/1.0 User-Agent header

---

Tech Stack

Technology	Purpose
Python	Primary language
httpx	HTTP client for connectivity checks
pytest	Testing framework
re (stdlib)	Regular expression engine for URL parsing
time (stdlib)	High-resolution timing via time.monotonic()
argparse (stdlib)	Command-line argument parsing
json (stdlib)	JSON output support

---

Project Structure

URL-Checker/
├── app.py          # Entry point -- CLI interface and orchestration
├── config.py       # Constants, version, and compiled URL regex pattern
├── validator.py    # URL format validation logic with port validation
├── checker.py      # HTTP connectivity check via httpx (with injectable client)
├── requirements.txt # Project dependencies
├── LICENSE         # MIT License
├── README.md       # This file
└── tests/          # Test suite
    ├── test_validator.py
    └── test_checker.py

---

Installation

Prerequisites

• Python 3.10 or higher
• pip (Python package manager)

Steps

1. Clone the repository

   git clone https://github.com/Marsh-Edge/URL-Checker.git
   cd URL-Checker

2. Install dependencies

   pip install -r requirements.txt

3. Verify installation

   python app.py --version

---

Usage

Interactive Mode

Run the tool from the project directory without arguments to enter interactive mode:

python app.py

You will be prompted to enter a URL. The tool will validate its format and then test connectivity.

Non-Interactive Mode

You can also pass a URL directly as an argument:

python app.py https://www.example.com

If valid and reachable, it will exit with code 0. Otherwise, it will exit with a non-zero code.

Example -- Valid URL (Interactive)

Enter URL to check: https://www.example.com

--------------------------------------------------
[*] Validating URL format... OK
[*] Hostname: www.example.com
[*] Connecting to server... OK
[*] Server responded: 200
[*] Response time: 142 ms
--------------------------------------------------
Result: VALID and REACHABLE (200 - 142ms)

Example -- Invalid URL (Interactive)

Enter URL to check: not-a-url

--------------------------------------------------
[*] Validating URL format... FAILED
[!] Error: URL format is invalid
--------------------------------------------------

Example -- Unreachable Server (Interactive)

Enter URL to check: https://this-server-does-not-exist.invalid

--------------------------------------------------
[*] Validating URL format... OK
[*] Hostname: this-server-does-not-exist.invalid
[*] Connecting to server... FAILED
[!] Error: Connection failed: ...
--------------------------------------------------
Result: FAILED

---

Commands

Command	Description
python app.py	Run in interactive mode
python app.py <url>	Check a URL non-interactively
python app.py -t 5 https://example.com	Set custom timeout (seconds)
python app.py --json https://example.com	Output JSON for scripting/automation
python app.py --quiet https://example.com	Minimal output (useful for CI)
python app.py --version	Show version

Exit Codes

Code	Meaning
0	URL is valid and server is reachable
1	Invalid URL or server is unreachable
130	Interrupted by user (Ctrl+C)

---

Roadmap

Completed

• URL format validation via regex
• HTTP/HTTPS scheme support
• IPv6 address recognition
• Domain name and port parsing
• HTTP connectivity check with httpx
• Response time measurement
• Redirect following
• Timeout and error handling
• CLI arguments (URL, timeout, JSON, quiet modes)
• Proper exit codes for automation
• Port range validation (1-65535)
• requirements.txt for dependency management
• Unit test suite with pytest

Planned

• Machine learning-based URL classification (phishing / malicious detection)
• Batch URL checking from file input
• DNS resolution check
• SSL certificate validation
• pyproject.toml for packaging
• Colorized output

---

Contributing

Contributions are welcome. To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -m "Add your feature")
4. Push to the branch (git push origin feature/your-feature)
5. Open a Pull Request

Please ensure your code follows the existing style and includes clear commit messages.

---

License

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

MIT License

Copyright (c) 2025 Marsh

---

Author

Marsh -- GitHub Profile

---

Acknowledgments

• httpx -- A next-generation HTTP client for Python
• Python -- The programming language
• Inspired by the need for a simple, scriptable URL validation and reachability tool

---

FAQ

Does this tool support FTP or other protocols?

No. URL-Checker currently only supports http:// and https:// schemes. Other protocols are rejected during validation.

What happens if the server returns a redirect?

The tool follows redirects automatically. The final response status code and time are reported.

Can I use this in a script or automation pipeline?

Not yet. The current version is interactive (reads from stdin). A JSON output mode for non-interactive use is planned in the Roadmap.

---

Made with Python