{"id":39230502,"url":"https://github.com/ibrahimraimi/caching-proxy-server","last_synced_at":"2026-01-17T23:40:40.131Z","repository":{"id":311919452,"uuid":"1045595118","full_name":"ibrahimraimi/caching-proxy-server","owner":"ibrahimraimi","description":"A high-performance caching proxy server built in Go that forwards requests to origin servers and caches responses","archived":false,"fork":false,"pushed_at":"2025-12-04T04:31:23.000Z","size":30,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-07T10:47:23.945Z","etag":null,"topics":["golang","proxy-server","server"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ibrahimraimi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-27T12:28:58.000Z","updated_at":"2025-09-18T12:38:51.000Z","dependencies_parsed_at":"2025-12-05T05:05:40.867Z","dependency_job_id":null,"html_url":"https://github.com/ibrahimraimi/caching-proxy-server","commit_stats":null,"previous_names":["ibrahimraimi/caching-proxy-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ibrahimraimi/caching-proxy-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibrahimraimi%2Fcaching-proxy-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibrahimraimi%2Fcaching-proxy-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibrahimraimi%2Fcaching-proxy-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibrahimraimi%2Fcaching-proxy-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ibrahimraimi","download_url":"https://codeload.github.com/ibrahimraimi/caching-proxy-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibrahimraimi%2Fcaching-proxy-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28522311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T22:11:28.393Z","status":"ssl_error","status_checked_at":"2026-01-17T22:11:27.841Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","proxy-server","server"],"created_at":"2026-01-17T23:40:40.069Z","updated_at":"2026-01-17T23:40:40.118Z","avatar_url":"https://github.com/ibrahimraimi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Caching Proxy Server\n\nA high-performance caching proxy server built in Go that forwards requests to origin servers and caches responses. If the same request is made again, it returns the cached response instead of forwarding to the server.\n\n**✨ Now featuring a beautiful Terminal User Interface (TUI) built with Bubble Tea!**\n\n## Features\n\n- **Smart Caching**: In-memory cache with configurable TTL (default: 5 minutes)\n- **Cache Headers**: Automatic `X-Cache: HIT/MISS` headers to indicate cache status\n- **Thread-Safe**: Concurrent request handling with proper locking\n- **CLI Interface**: Easy-to-use command-line interface with Cobra\n- **Flexible Configuration**: Customizable port and origin server\n- **Cache Management**: Built-in cache clearing functionality\n- **Comprehensive Testing**: Unit tests covering all major functionality\n- **Automated Examples**: Scripts for testing and demonstration\n- **🎨 Beautiful TUI**: Terminal User Interface with real-time monitoring and control\n\n## Requirements\n\n- Go 1.21 or higher\n- Linux/macOS/Windows (cross-platform)\n- Terminal with support for colors and UTF-8\n\n## Installation\n\n1. Clone the repository:\n\n```bash\ngit clone \u003crepository-url\u003e\ncd caching-proxy-server\n```\n\n2. Install dependencies:\n\n```bash\nmake deps\n# or manually:\ngo mod download\n```\n\n3. Build the project:\n\n```bash\nmake build\n# or manually:\ngo build -o caching-proxy main.go\n```\n\n## Usage\n\n### Basic Usage\n\nStart the caching proxy server:\n\n```bash\ncaching-proxy --port \u003cnumber\u003e --origin \u003curl\u003e\n```\n\n**Parameters:**\n\n- `--port` (required): Port on which the caching proxy server will run\n- `--origin` (required): URL of the server to which requests will be forwarded\n\n### TUI Mode (Recommended)\n\nFor the best experience, run with the beautiful terminal interface:\n\n```bash\ncaching-proxy --port \u003cnumber\u003e --origin \u003curl\u003e --tui\n```\n\n**TUI Features:**\n\n- 🎯 Real-time request monitoring\n- 📊 Live cache statistics\n- 🎨 Beautiful color-coded interface\n- ⌨️ Interactive keyboard controls\n\n**TUI Controls:**\n\n- `↑/↓` - Navigate through requests\n- `c` - Clear cache\n- `r` - Refresh data\n- `q` - Quit\n\n### Examples\n\n#### Example 1: Forward to DummyJSON API with TUI\n\n```bash\ncaching-proxy --port 3000 --origin http://dummyjson.com --tui\n```\n\nThis will:\n\n- Start the proxy server on port 3000\n- Forward requests to http://dummyjson.com\n- Cache responses for 5 minutes\n- Display beautiful TUI interface\n\n#### Example 2: Forward to a different API\n\n```bash\ncaching-proxy --port 8080 --origin https://api.example.com --tui\n```\n\n#### Example 3: Using short flags\n\n```bash\ncaching-proxy -p 3000 -o http://dummyjson.com -t\n```\n\n### Testing the Proxy\n\nOnce the server is running, you can test it:\n\n1. **First request** (cache miss):\n\n```bash\ncurl http://localhost:3000/products\n# Response will include: X-Cache: MISS\n```\n\n2. **Second request** (cache hit):\n\n```bash\ncurl http://localhost:3000/products\n# Response will include: X-Cache: HIT\n```\n\n3. **Check cache headers**:\n\n```bash\ncurl -I http://localhost:3000/products\n```\n\n### Cache Management\n\n#### Clear the Cache\n\n```bash\ncaching-proxy clear-cache\n```\n\n#### Using Makefile Commands\n\nThe project includes a Makefile for easier management:\n\n```bash\n# Build and run with example settings\nmake run\n\n# Build and run with TUI (recommended)\nmake run-tui\n\n# Run with custom settings\nmake run-custom PORT=8080 ORIGIN=http://api.example.com\n\n# Run custom with TUI\nmake run-custom-tui PORT=8080 ORIGIN=http://api.example.com\n\n# Clear cache\nmake clear-cache\n\n# Clean build artifacts\nmake clean\n\n# Show all available commands\nmake help\n```\n\n#### Automated Testing\n\nRun the complete example script to test all functionality:\n\n```bash\n./example.sh\n```\n\nThis script will:\n\n- Build the project\n- Start the server\n- Test cache hits and misses\n- Clean up automatically\n\n## How It Works\n\n1. **Request Processing**: When a request comes in, the proxy generates a unique cache key based on the HTTP method, URL, and User-Agent header.\n\n2. **Cache Lookup**: The proxy checks if a cached response exists for the request.\n\n3. **Cache Hit**: If found and not expired, returns the cached response with `X-Cache: HIT` header.\n\n4. **Cache Miss**: If not found or expired, forwards the request to the origin server.\n\n5. **Response Caching**: Successful responses (status 200-399) are cached with a 5-minute TTL.\n\n6. **Response Delivery**: The response is returned to the client with `X-Cache: MISS` header.\n\n7. **TUI Updates**: All requests are logged and displayed in real-time in the beautiful interface.\n\n## Cache Key Generation\n\nThe cache key is generated using MD5 hash of:\n\n- HTTP method (GET, POST, etc.)\n- Full request URL\n- User-Agent header\n\nThis ensures that different types of requests are cached separately.\n\n## Configuration\n\n### Cache TTL\n\nThe default cache TTL is 5 minutes. To modify this, edit the `TTL` field in the `CacheEntry` struct in `main.go`.\n\n### Cache Storage\n\nCurrently uses in-memory storage. For production use, consider implementing:\n\n- Redis backend\n- File-based persistence\n- Database storage\n\n## Project Structure\n\n```\ncaching-proxy-server/\n├── main.go              # Main application with server logic and TUI\n├── main_test.go         # Comprehensive test suite\n├── go.mod               # Go module definition\n├── go.sum               # Dependency checksums\n├── Makefile             # Build and management commands\n├── example.sh           # Automated testing script\n├── demo-tui.sh          # TUI demonstration script\n├── config.example.yaml  # Future configuration structure\n└── README.md            # This file\n```\n\n## Dependencies\n\n- **github.com/spf13/cobra**: CLI framework for command-line interface\n- **github.com/charmbracelet/bubbletea**: TUI framework for beautiful terminal interfaces\n- **github.com/charmbracelet/lipgloss**: Styling library for terminal UI\n- **Standard Go libraries**: net/http, crypto/md5, sync, etc.\n\n## Performance Considerations\n\n- **Memory Usage**: Cache entries are stored in memory, so monitor memory usage for high-traffic scenarios\n- **Concurrency**: Uses read-write mutexes for optimal concurrent access\n- **TTL Management**: Expired entries are automatically cleaned up on access\n- **Cache Efficiency**: MD5-based keys provide fast lookups with minimal collision probability\n- **TUI Performance**: Real-time updates with minimal overhead\n\n## Testing\n\n### Run Unit Tests\n\n```bash\nmake test\n```\n\n### Run Example Script\n\n```bash\n./example.sh\n```\n\n### Manual Testing\n\n```bash\n# Start server with TUI\nmake run-tui\n\n# In another terminal, test caching\ncurl http://localhost:3000/products\ncurl http://localhost:3000/products  # Should show cache HIT\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Port already in use**: Choose a different port or stop the service using the current port\n2. **Invalid origin URL**: Ensure the origin URL is properly formatted (include http:// or https://)\n3. **Permission denied**: Make sure you have permission to bind to the specified port\n4. **Build failures**: Ensure Go 1.21+ is installed and dependencies are downloaded\n5. **TUI display issues**: Ensure your terminal supports colors and UTF-8\n\n### Debug Mode\n\nThe server logs all cache hits and misses. Check the console output for debugging information:\n\n```\n2024/01/15 10:30:00 Starting caching proxy server on port 3000\n2024/01/15 10:30:00 Forwarding requests to: http://dummyjson.com\n2024/01/15 10:30:00 Cache size: 0 entries\n2024/01/15 10:30:05 Cache MISS for /products\n2024/01/15 10:30:05 Cached response for /products\n2024/01/15 10:30:10 Cache HIT for /products\n```\n\n## CLI Commands\n\n### Main Command\n\n```bash\ncaching-proxy --port \u003cport\u003e --origin \u003curl\u003e\n```\n\n### TUI Mode\n\n```bash\ncaching-proxy --port \u003cport\u003e --origin \u003curl\u003e --tui\n```\n\n### Subcommands\n\n```bash\ncaching-proxy clear-cache    # Clear the cache\ncaching-proxy help          # Show help\ncaching-proxy completion    # Generate shell completion\n```\n\n### Flags\n\n- `-p, --port`: Port number (1-65535)\n- `-o, --origin`: Origin server URL\n- `-t, --tui`: Enable beautiful terminal user interface\n- `-h, --help`: Show help information\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n### Development Setup\n\n```bash\n# Install dependencies\nmake deps\n\n# Run tests\nmake test\n\n# Build\nmake build\n\n# Clean\nmake clean\n```\n\n## Example Output\n\n### TUI Interface\n\n```\n🚀 Caching Proxy Server\n\nStatus: Running\nPort: 3000 | Origin: http://dummyjson.com | Cache Size: 5 entries\n\nControls: ↑/↓ Navigate | c Clear Cache | r Refresh | q Quit\n\nRecent Requests:\nTime                Method  Path                           Status  Cache   Response Time\n15:04:05           GET     /products                      200     HIT     1.2ms\n15:04:03           GET     /users                         200     MISS    45.8ms\n15:04:01           GET     /products                      200     MISS    52.1ms\n\nPress 'q' to quit\n```\n\n## Quick Reference\n\n| Command                | Description               |\n| ---------------------- | ------------------------- |\n| `make build`           | Build the project         |\n| `make run`             | Run with example settings |\n| `make run-tui`         | Run with beautiful TUI    |\n| `make test`            | Run unit tests            |\n| `make clear-cache`     | Clear the cache           |\n| `./example.sh`         | Run automated testing     |\n| `./demo-tui.sh`        | Demo TUI functionality    |\n| `caching-proxy --help` | Show CLI help             |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibrahimraimi%2Fcaching-proxy-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibrahimraimi%2Fcaching-proxy-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibrahimraimi%2Fcaching-proxy-server/lists"}