urlprobe 0.1.0__tar.gz

urlprobe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrew Vella
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

urlprobe-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: urlprobe
+Version: 0.1.0
+Summary: A tool to request a specified `url` and return the response.
+License-File: LICENSE
+Author: Andrew Vella
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: click (>=8.2.1,<9.0.0)
+Requires-Dist: flask (>=3.0.0,<4.0.0)
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Requires-Dist: rich (>=14.0.0,<15.0.0)
+Requires-Dist: toml (>=0.10.2,<0.11.0)
+Description-Content-Type: text/markdown
+
+# URL Probe
+
+[![Test Status](https://github.com/av603/urlprobe/actions/workflows/test.yml/badge.svg)](https://github.com/av603/urlprobe/actions/workflows/test.yml)
+[![Code Coverage](https://codecov.io/gh/av603/urlprobe/branch/main/graph/badge.svg)](https://codecov.io/gh/av603/urlprobe)
+
+This tool helps test complex cloud network setups, like those with private services that have specific exit points. It's especially useful for checking if your cloud services can talk to each other within a virtual private cloud and those services can make requests to the outside world as expected.
+
+**Use Case** Say you have a Cloud Load Balancer, two Cloud Run services (Service A and Service B) and a Cloud Subnetwork with a static egress IP. You have deployed this infrastructure and want to verify that the Cloud Load Balancer can access Service A, that Service A can access Service B and that requests from Service B appear from the subnetwork static egress IP.
+
+```
+    Internet
+        |
+        |
+    +-------+
+    |       |
+    | Cloud |
+    |  Run  |  (A) - Publicly Accessible
+    +-------+
+        | (Target URL Parameter)
+        |
+        v (Internal Network Traffic)
+    +-------+
+    |       |
+    | Cloud |
+    |  Run  |  (B) - Internal Service
+    +-------+
+        | (Outbound Request via Static IP)
+        |
+        v
+    +---------------+
+    | External      |
+    | Target Server |
+    +---------------+
+```
+
+The network connectivity and the public IP can be verified by deploying the `urlprobe` tool to Service A and Service B and sending a chained `curl` request to the exposed service and requesting the public IP from `https://api.ipify.org` as the last step in the chain. For example, if the network is configured as per this use case, a `curl` request:
+
+```bash
+curl -s http://external-cloud-run-service-a-ip/?url=http://internal-cloud-run-service-b-ip/?url=https://api.ipify.org?format=json
+```
+
+will be received at Service A, then at Service B and finally at `https://api.ipify.org` will return the public IP.
+
+## Installation
+
+The `urlprobe` tool is available on PiPy and can be installed via pip:
+
+1.  **Install Python 3.10+:** Ensure you have Python 3.10 or a later version installed.
+2.  **Install the package from PyPI using pip:**
+```bash
+pip install urlprobe
+```
+3.  **(optional) Install the package from TestPyPI using pip:**
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ urlprobe
+```
+
+How you deploy the `urlprobe` tool depends on the type of infrastructure under test e.g. packaged as a `Docker` image or deployed as a cloud function.
+
+## Usage
+
+### Running as a standalone application
+
+1.  **Run the server:**
+```bash
+python -m urlprobe
+```
+
+**(optionally) run the server with non-default args**
+```bash
+python -m urlprobe --host 0.0.0.0 --port 8081 --debug
+```
+
+2.  **Send a GET request to the server with the `url` parameter:**
+```bash
+curl -s "http://<edge-service-ip>:8080/?url=https://<internal-service-ip>"
+```
+
+Replace `<edge-service-ip>` with the IP address or hostname of your externally accessible edge service. For example, when running as a standalone application on localhost:
+
+```bash
+curl -s "http://localhost:8080/?url=https://api.ipify.org?format=json"
+```
+
+## Output
+
+The server will return a JSON object containing detailed information the request chain, including:
+
+* **Edge Service Response:** Status code, headers, and body from the target service."
+* **Error Messages:** Detailed error messages for any failures encountered during the request chain.
+
+## Contributing
+
+Please see [Contributing Guidelines](https://github.com/av603/urlprobe/blob/main/CONTRIBUTING.md) for details on:
+
+- Setting up your development environment
+- Code style and standards
+- Pull request process
+- Running tests
+
+# Versioning
+
+This project follows [Semantic Versioning](https://semver.org/). For the versions available, see the [tags on this repository](https://github.com/av603/urlprobe/tags).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/av603/urlprobe/blob/main/LICENSE) file for details.
+

urlprobe-0.1.0/README.md

@@ -0,0 +1,107 @@
+# URL Probe
+
+[![Test Status](https://github.com/av603/urlprobe/actions/workflows/test.yml/badge.svg)](https://github.com/av603/urlprobe/actions/workflows/test.yml)
+[![Code Coverage](https://codecov.io/gh/av603/urlprobe/branch/main/graph/badge.svg)](https://codecov.io/gh/av603/urlprobe)
+
+This tool helps test complex cloud network setups, like those with private services that have specific exit points. It's especially useful for checking if your cloud services can talk to each other within a virtual private cloud and those services can make requests to the outside world as expected.
+
+**Use Case** Say you have a Cloud Load Balancer, two Cloud Run services (Service A and Service B) and a Cloud Subnetwork with a static egress IP. You have deployed this infrastructure and want to verify that the Cloud Load Balancer can access Service A, that Service A can access Service B and that requests from Service B appear from the subnetwork static egress IP.
+
+```
+    Internet
+        |
+        |
+    +-------+
+    |       |
+    | Cloud |
+    |  Run  |  (A) - Publicly Accessible
+    +-------+
+        | (Target URL Parameter)
+        |
+        v (Internal Network Traffic)
+    +-------+
+    |       |
+    | Cloud |
+    |  Run  |  (B) - Internal Service
+    +-------+
+        | (Outbound Request via Static IP)
+        |
+        v
+    +---------------+
+    | External      |
+    | Target Server |
+    +---------------+
+```
+
+The network connectivity and the public IP can be verified by deploying the `urlprobe` tool to Service A and Service B and sending a chained `curl` request to the exposed service and requesting the public IP from `https://api.ipify.org` as the last step in the chain. For example, if the network is configured as per this use case, a `curl` request:
+
+```bash
+curl -s http://external-cloud-run-service-a-ip/?url=http://internal-cloud-run-service-b-ip/?url=https://api.ipify.org?format=json
+```
+
+will be received at Service A, then at Service B and finally at `https://api.ipify.org` will return the public IP.
+
+## Installation
+
+The `urlprobe` tool is available on PiPy and can be installed via pip:
+
+1.  **Install Python 3.10+:** Ensure you have Python 3.10 or a later version installed.
+2.  **Install the package from PyPI using pip:**
+```bash
+pip install urlprobe
+```
+3.  **(optional) Install the package from TestPyPI using pip:**
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ urlprobe
+```
+
+How you deploy the `urlprobe` tool depends on the type of infrastructure under test e.g. packaged as a `Docker` image or deployed as a cloud function.
+
+## Usage
+
+### Running as a standalone application
+
+1.  **Run the server:**
+```bash
+python -m urlprobe
+```
+
+**(optionally) run the server with non-default args**
+```bash
+python -m urlprobe --host 0.0.0.0 --port 8081 --debug
+```
+
+2.  **Send a GET request to the server with the `url` parameter:**
+```bash
+curl -s "http://<edge-service-ip>:8080/?url=https://<internal-service-ip>"
+```
+
+Replace `<edge-service-ip>` with the IP address or hostname of your externally accessible edge service. For example, when running as a standalone application on localhost:
+
+```bash
+curl -s "http://localhost:8080/?url=https://api.ipify.org?format=json"
+```
+
+## Output
+
+The server will return a JSON object containing detailed information the request chain, including:
+
+* **Edge Service Response:** Status code, headers, and body from the target service."
+* **Error Messages:** Detailed error messages for any failures encountered during the request chain.
+
+## Contributing
+
+Please see [Contributing Guidelines](https://github.com/av603/urlprobe/blob/main/CONTRIBUTING.md) for details on:
+
+- Setting up your development environment
+- Code style and standards
+- Pull request process
+- Running tests
+
+# Versioning
+
+This project follows [Semantic Versioning](https://semver.org/). For the versions available, see the [tags on this repository](https://github.com/av603/urlprobe/tags).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/av603/urlprobe/blob/main/LICENSE) file for details.

urlprobe-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[tool.poetry]
+name = "urlprobe"
+version = "0.1.0"
+description = "A tool to request a specified `url` and return the response."
+authors = ["Andrew Vella"]
+readme = "README.md"
+packages = [{include = "urlprobe", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+click = "^8.2.1"
+rich = "^14.0.0"
+flask = "^3.0.0"
+toml = "^0.10.2"
+requests = "^2.32.3"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.0.0"
+pytest-cov = "^6.0.0"
+flake8 = "^7.0.0"
+pre-commit = "^4.0.0"
+mypy = "^1.7.1"
+types-requests = "^2.31.0"
+types-toml = "^0.10.8"
+python-semantic-release = "^8.0.0"
+
+[tool.poetry.scripts]
+urlprobe = "urlprobe.__main__:main"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:tool.poetry.version"]
+branch = "main"
+upload_to_pypi = false
+build_command = "poetry build"
+upload_dists = true
+tag_commit = true
+tag_format = "{version}"
+commit_parser = "angular"
+changelog_file = "CHANGELOG.md"
+changelog_header = """
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+"""
+
+changelog_sections = [
+    { section = "Features", hidden = false, tags = ["feat"] },
+    { section = "Bug Fixes", hidden = false, tags = ["fix"] },
+    { section = "Documentation", hidden = false, tags = ["docs"] },
+    { section = "Refactoring", hidden = false, tags = ["refactor"] },
+    { section = "Dependencies", hidden = false, tags = ["chore", "build"] },
+    { section = "Performance", hidden = false, tags = ["perf"] },
+    { section = "Continuous Integration", hidden = true, tags = ["ci"] },
+]

urlprobe-0.1.0/src/urlprobe/__init__.py

@@ -0,0 +1,9 @@
+"""
+A utility to probe url endpoints.
+
+Requests a specified `url` and returns the response. Used for network
+infrastructure probing and diagnostics.
+
+For more detailed information, see the documentation at:
+https://github.com/av603/urlprobe
+"""

urlprobe-0.1.0/src/urlprobe/__main__.py

@@ -0,0 +1,49 @@
+"""
+Command-line entry point for the urlprobe Flask application.
+
+This script parses command-line arguments for configuring the host,
+port, and debug mode of the urlprobe web service and then starts
+the Flask development server.
+"""
+
+import argparse
+
+from urlprobe.app import create_app, logger
+
+
+def main():
+    """Entry point for the urlprobe Flask application."""
+    parser = argparse.ArgumentParser(
+        description="Run the urlprobe application."
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="0.0.0.0",
+        help="The interface to bind to (default: 0.0.0.0)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8080,
+        help="The port to listen on (default: 8080)",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        default=False,
+        help="Enable debug mode (default: False)",
+    )
+    args = parser.parse_args()
+
+    app = create_app()
+
+    logger.info(
+        f"Starting urlprobe on host {args.host}, port {args.port}, "
+        f"debug={args.debug}"
+    )
+    app.run(host=args.host, port=args.port, debug=args.debug)
+
+
+if __name__ == "__main__":
+    main()

urlprobe-0.1.0/src/urlprobe/app.py

@@ -0,0 +1,142 @@
+"""Flask application module for URL Probe."""
+
+import importlib.metadata
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict
+
+import requests
+import toml
+from flask import Flask, jsonify, request
+
+from urlprobe.utils import is_valid_url
+
+# Configure logging at module level
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT = 10  # seconds
+ALLOWED_METHODS = ["GET"]
+VERIFY_SSL = True
+
+
+@dataclass
+class Probe:
+    """Probe data structure.
+
+    Attributes:
+        url: URL that was probed
+
+        status_code: HTTP status code from the response
+        elapsed_ms: Response time in milliseconds
+        final_url: Final URL after redirects
+        headers: Response headers
+        body: Response body
+    """
+
+    url: str
+
+    status_code: int = 0
+    elapsed_ms: int = 0
+    final_url: str = ""
+    headers: Dict[str, str] = field(default_factory=dict)
+    body: str = ""
+
+    def to_json(self):
+        """Convert Probe to json."""
+        return jsonify(self.__dict__)
+
+
+def get_version() -> str:
+    """Read version from pyproject.toml."""
+    try:
+        pyproject_path = Path(__file__).parent.parent / "pyproject.toml"
+        with open(pyproject_path, "r") as f:
+            pyproject = toml.load(f)
+            return pyproject["tool"]["poetry"]["version"]
+    except Exception as e:
+        logger.warning(f"Failed to read version from pyproject.toml: {e}")
+        return "unknown"
+
+
+def handle_invalid_arg(logger, error_msg, code):
+    """Handle invalid args."""
+    logger.error(error_msg)
+    return {"error": error_msg}, code
+
+
+def handle_request():
+    """Handle probe requests.
+
+    Returns:
+        Probe: Object containing response information
+    """
+    url = request.args.get("url")
+
+    if not is_valid_url(url):
+        return handle_invalid_arg(
+            logger, f"Missing or invalid `url` arg:{url}", 400
+        )
+
+    # send request to the URL and get the response
+    logger.info("Probing URL: %s", url)
+    resp = requests.request(
+        method=request.method,
+        url=url,
+        timeout=DEFAULT_TIMEOUT,
+        verify=VERIFY_SSL,
+    )
+
+    probe_response = Probe(
+        url=url,
+        status_code=resp.status_code,
+        body=resp.text,
+        headers=dict(resp.headers),
+        elapsed_ms=resp.elapsed.total_seconds(),
+        final_url=resp.url,
+    )
+
+    return probe_response.to_json()
+
+
+def health_check():
+    """Check the health status and version of the service.
+
+    Returns:
+        dict: Health status and version information with format:
+            {"status": "healthy", "version": "x.y.z"}
+    """
+    try:
+        version = importlib.metadata.version("urlprobe")
+        logger.info("Health check requested, version: %s", version)
+    except importlib.metadata.PackageNotFoundError:
+        logger.warning(
+            "Package 'urlprobe' not found. Unable to determine version."
+        )
+        version = "unknown"
+
+    return {
+        "status": "healthy",
+        "version": version,
+    }
+
+
+def create_app():
+    """Create and configure the Flask application.
+
+    Returns:
+        Flask: Configured Flask application instance
+    """
+    app = Flask(__name__)
+    logger.debug("Creating Flask application")
+
+    app.route("/", methods=ALLOWED_METHODS)(handle_request)
+    app.route("/health")(health_check)
+
+    return app

urlprobe-0.1.0/src/urlprobe/cli.py

@@ -0,0 +1,30 @@
+"""Provide command line interface for URL Probe."""
+
+import click
+
+from urlprobe.app import create_app
+
+
+@click.group()
+def cli():
+    """Define URL Probe CLI group."""
+    pass
+
+
+@cli.command()
+@click.option("--host", default="127.0.0.1", help="Host to bind to")
+@click.option("--port", default=8080, help="Port to bind to")
+@click.option("--debug", is_flag=True, help="Enable debug mode")
+def serve(host: str, port: int, debug: bool):
+    """Start the Flask server."""
+    app = create_app()
+    app.run(host=host, port=port, debug=debug)
+
+
+def main():
+    """Execute the main CLI program."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

urlprobe-0.1.0/src/urlprobe/utils.py

@@ -0,0 +1,33 @@
+"""Utility functions for URL Probe."""
+
+from urllib.parse import urlparse
+
+
+def is_valid_url(url: str) -> bool:
+    """Check if a given string is a valid URL.
+
+    Args:
+        url: The URL string to validate
+
+    Returns:
+        bool: True if URL is valid, False otherwise
+
+    Examples:
+        >>> is_valid_url("https://example.com")
+        True
+        >>> is_valid_url("not_a_url")
+        False
+    """
+    if not url:
+        return False
+
+    try:
+        result = urlparse(url)
+        return all(
+            [
+                result.scheme in ("http", "https"),
+                result.netloc,
+            ]
+        )
+    except (AttributeError, ValueError):
+        return False