Faroxy

A modern HTTP proxy server with real-time traffic monitoring and analysis capabilities

---

A powerful HTTP proxy server built with Spring Boot, featuring real-time traffic monitoring, request/response logging, and an intuitive web interface.

Getting Started • Documentation • Features • Contributing

---

Features

• Forward HTTP requests and responses (GET, POST, and other methods)
• Support for form data and custom headers
• Store intercepted requests and responses in H2 in-memory database
• Modern and intuitive web interface with real-time traffic monitoring
• RESTful APIs to retrieve logged requests and responses
• Cross-platform support (macOS and Windows)
• Docker support for easy deployment
• Real-time response time monitoring with visual indicators
• HTTP status code display for each request
• Download request/response details as text files for easy sharing and analysis
• Dark/Light theme support for better visibility
• Robust error handling with detailed error messages
• Visual error indicators in the web interface
• Connection pool management for improved performance
• Automatic retry mechanism for failed requests
• URL validation and normalization

Web Interface

Faroxy comes with a sleek and modern web interface that makes it easy to monitor and analyze HTTP traffic in real-time. Key features include:

• Real-time traffic monitoring with WebSocket updates
• Response time display with visual indicators
• HTTP status code badges with error state visualization
• Request/response detail expansion
• Copy and download functionality for request/response data
• Dark/Light theme toggle for better visibility
• Error message display with detailed information
• Connection status monitoring

Key Features

• Real-time Updates: Watch HTTP traffic as it happens
• Smart Search: Filter messages instantly with the search bar
• Request Details: View headers, body, and form data
• Response Analysis: Examine response status, headers, and content
• Quick Copy: One-click copying of values with visual feedback
• Dark Mode: Easy on the eyes with a dark theme
• Responsive Design: Works great on all screen sizes
• Error Handling: Clear visualization of errors with detailed messages
• Connection Management: Automatic handling of connection issues
• URL Validation: Automatic URL validation and normalization

The web interface is accessible at http://localhost:8080/ui after starting Faroxy.

Error Handling

Faroxy provides comprehensive error handling for various scenarios:

Connection Issues

• Connection refused errors
• Premature connection closure
• Connection timeout
• SSL/TLS errors

Request/Response Issues

• Invalid URL format
• Malformed requests
• Server errors (4xx, 5xx)
• Response timeout

WebSocket Issues

• Connection drops
• Reconnection attempts
• Heartbeat monitoring

All errors are:

1. Logged with detailed information
2. Displayed in the web interface with clear indicators
3. Stored in the database for analysis
4. Available through the API

Tech Stack

Prerequisites

• Java 17 or higher
• Gradle 7.x or higher
• Docker (optional)

Quick Setup

1. Clone the repository:

   git clone https://github.com/vinipx/faroxy.git
   cd faroxy

2. Run the setup script:

   ./scripts/setup.sh

   This will:

   • Make the control script executable
   • Add the faroxy command to your shell
   • Configure necessary permissions

3. Activate the alias:

   source ~/.zshrc   # if using zsh
   source ~/.bashrc  # if using bash

4. Start using Faroxy:

   faroxy start    # Start the server
   faroxy status   # Check server status
   faroxy help     # Show all commands

The application will be available at http://localhost:8080.

Running the Application

Faroxy comes with a convenient control script to manage the application. After cloning the repository:

1. Make the control script executable:

   chmod +x scripts/faroxy.sh

2. Use the script to manage Faroxy:

   # Start the server
   ./scripts/faroxy.sh start
   
   # Stop the server
   ./scripts/faroxy.sh stop
   
   # Restart the server
   ./scripts/faroxy.sh restart
   
   # Check server status
   ./scripts/faroxy.sh status
   
   # Show help
   ./scripts/faroxy.sh help

3. Optional: Add an alias to your shell configuration (e.g., .bashrc or .zshrc):

   echo 'alias faroxy="$HOME/path/to/faroxy/scripts/faroxy.sh"' >> ~/.zshrc
   source ~/.zshrc

   Then you can use faroxy command from anywhere:

   faroxy start
   faroxy status

Using the Proxy

Web Interface

Access the web interface at http://localhost:8080 to:

• View all proxy traffic in real-time
• Filter and search through requests/responses
• Inspect request/response headers and bodies

API Usage

1. Send requests through the proxy:

# GET request
curl "http://localhost:8080/proxy?url=https://api.example.com/data"

# POST request with JSON body
curl -X POST "http://localhost:8080/proxy?url=https://api.example.com/data" \
     -H "Content-Type: application/json" \
     -d '{"key": "value"}'

# POST request with form data
curl -X POST "http://localhost:8080/proxy?url=https://api.example.com/data" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "key1=value1&key2=value2"

# Request with custom headers
curl "http://localhost:8080/proxy?url=https://api.example.com/data" \
     -H "X-Custom-Header: custom-value"

2. View logged requests/responses:

# Get all requests
curl http://localhost:8080/api/requests

# Get all responses
curl http://localhost:8080/api/responses

Documentation

Faroxy provides comprehensive documentation in multiple formats:

1. Live Documentation: Access the documentation directly from Faroxy at http://localhost:8080/docs
2. GitHub Pages: Visit our GitHub Pages for the latest documentation
3. README: Basic setup and usage information in this README file

The documentation includes detailed information about:

• Installation and setup
• Configuration options
• API reference
• Web interface features
• Troubleshooting guide

Configuration

Local Development Configuration

For local development, you can create your own configuration file that won't be tracked by Git:

1. Copy the template file:

cp src/main/resources/application-local.properties.template config/application-local.properties

2. Edit config/application-local.properties with your preferred settings:

# Example local configuration
server.port=9090
faroxy.proxy.port=9999
logging.level.io.faroxy=DEBUG

The application will:

1. First load the default settings from application.properties
2. Then override them with your local settings from config/application-local.properties if it exists
3. Finally, apply any environment variables or system properties

Application Properties

Edit src/main/resources/application.properties:

# Server Configuration
server.port=8080

# Database Configuration
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect

# H2 Console
spring.h2.console.enabled=true
spring.h2.console.path=/h2-console

Environment Variables

You can override configuration using environment variables:

export SERVER_PORT=9090
export SPRING_DATASOURCE_URL=jdbc:h2:mem:customdb

Development

Building and Running

1. Build the project:

   ./gradlew build

2. Run the application:

   ./gradlew bootRun

Debugging

For troubleshooting, use these Gradle logging levels:

1. Normal development (recommended):

   ./gradlew bootRun --info

2. Error investigation:

   ./gradlew bootRun --stacktrace

Note: Avoid using --debug flag as it may expose sensitive information. Use --info or --stacktrace instead.

Troubleshooting

Common Issues

1. Port Already in Use

   export SERVER_PORT=9090
   ./gradlew bootRun

2. Database Issues

   • Ensure H2 console is accessible at http://localhost:8080/h2-console
   • Check application logs for database-related errors
   • Try clearing the in-memory database by restarting the application

Contributing

We love your input! We want to make contributing to Faroxy as easy and transparent as possible, whether it's:

• Reporting a bug
• Discussing the current state of the code
• Submitting a fix
• Proposing new features
• Becoming a maintainer

Read our Contributing Guidelines to get started.

Development Process

We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.

1. Fork the repo and create your branch from main
2. If you've added code that should be tested, add tests
3. If you've changed APIs, update the documentation
4. Ensure the test suite passes
5. Make sure your code follows the existing style
6. Issue that pull request!

Stats

License

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

---

Made with ❤️ by vinipx