{"id":17473700,"url":"https://github.com/hvuhsg/gatego","last_synced_at":"2025-04-16T16:31:30.515Z","repository":{"id":258299883,"uuid":"872022888","full_name":"hvuhsg/gatego","owner":"hvuhsg","description":"Reverse Proxy Server","archived":false,"fork":false,"pushed_at":"2024-10-22T22:01:12.000Z","size":128,"stargazers_count":22,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-23T17:15:30.190Z","etag":null,"topics":["golang","load-balancer","openapi","reverse-proxy","server"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hvuhsg.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}},"created_at":"2024-10-13T15:31:47.000Z","updated_at":"2024-10-22T22:01:16.000Z","dependencies_parsed_at":"2024-10-25T12:50:12.900Z","dependency_job_id":"e33faa0d-0a0f-4dfd-b7e3-7e380ed2fe38","html_url":"https://github.com/hvuhsg/gatego","commit_stats":null,"previous_names":["hvuhsg/gatego"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hvuhsg%2Fgatego","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hvuhsg%2Fgatego/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hvuhsg%2Fgatego/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hvuhsg%2Fgatego/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hvuhsg","download_url":"https://codeload.github.com/hvuhsg/gatego/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249259146,"owners_count":21239422,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","load-balancer","openapi","reverse-proxy","server"],"created_at":"2024-10-18T18:06:31.642Z","updated_at":"2025-04-16T16:31:29.921Z","avatar_url":"https://github.com/hvuhsg.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Reverse Proxy Server\n\n[![Tests](https://github.com/hvuhsg/gatego/actions/workflows/go-tests.yml/badge.svg?branch=main)](https://github.com/hvuhsg/gatego/actions/workflows/go-tests.yml)\n\n## Overview\n\nThis reverse proxy server is designed to forward incoming requests to internal services, while offering advanced features such as SSL termination, rate limiting, content optimization, and OpenAPI-based request/response validation.\n\n## Supported Features\n\n- 🔒 SSL Termination - HTTPS support with configurable SSL certificates\n\n- 🚀 Content Optimization\n  - Minification for HTML, CSS, JS, XML, JSON, and SVG\n  - GZIP compression support\n\n\n- ⚡ Performance Controls\n  - Configurable request timeouts\n  - Maximum request size limits\n  - Response caching for cacheable content\n\n\n- 🛡️ Security \u0026 Protection\n\n  - IP-based rate limiting (per minute/day)\n  - Request/response validation via OpenAPI\n  - Anomaly detection score (per session)\n\n- ⚖️ Load Balancing\n\n  - Multiple backend server support\n  - Round-robin, random, and least-latency policies\n  - Weighted distribution options\n\n\n- 📁 File Serving - Static file serving with path stripping\n\n- 🏥 Health Monitoring\n\n  - Automated health checks with cron scheduling\nConfigurable failure notifications\n\n\n- 📊 Observability - OpenTelemetry integration for tracing and metrics\n\n## More About The Features\n### 1. SSL Termination\n\nThe proxy supports secure connections through SSL, with configurable paths to the SSL key and certificate files. This allows for secure HTTPS communication between clients and the reverse proxy.\n\n```yaml\n# Optional\nssl:\n  keyfile: /path/to/your/ssl/keyfile\n  certfile: /path/to/your/ssl/certfile\n```\n\n### 2. Content Optimization\n\n- Minification: The server can minify content (e.g., HTML, CSS, JavaScript, XML, JSON, SVG) before forwarding it to the client, reducing response sizes and improving load times.\n- Compression: GZIP compression is supported to further reduce the size of responses, optimizing bandwidth usage.\n\n```yaml\n- path: /\n\n  # Optional\n  minify: [js, html, css, json, xml, svg]\n  # You can use 'all' instaed to enable all content-types\n  \n  # Optional\n  gzip: true  # Enable GZIP compression\n```\n\n\n### 3. Request Limits and Timeouts\n\n- Timeout: Custom timeouts can be set to avoid slow backend services from hanging client requests.\n- Maximum Request Size: Limits can be placed on the size of incoming requests to prevent excessively large payloads from overwhelming the server.\n\n```yaml\n- path: /\n  timeout: 5s  # Custom timeout for backend responses (Default 30s)\n  max_size: 2048  # Max request size in bytes (Default 10MB)\n```\n\n### 4. Rate Limiting\n\nRate limiting can be applied to prevent abuse, restricting the number of requests an individual client (based on IP) can make within a specific time window. Multiple rate limit policies can be configured, such as:\n- Requests per minute from the same IP\n- Requests per day from the same IP\n\n```yaml\n- path: /\n\n  # Optional\n  ratelimits:\n    - ip-10/m  # Limit to 10 requests per minute per IP\n    - ip-500/d  # Limit to 500 requests per day per IP\n```\n\n### 5. OpenAPI-based Request and Response Validation\n\nThe server integrates OpenAPI for validating incoming requests and outgoing responses against an OpenAPI specification document. This ensures that:\n\n- Requests conform to the expected format, including parameters, headers, and body content.\n- Responses adhere to the defined API schema, ensuring consistent and reliable data exchange.\n\nYou can specify the OpenAPI file path in the configuration, and the server will use it to validate the requests and responses automatically.\n\n```yaml\n- path: /\n\n  # Optional\n  openapi: /path/to/openapi.yaml  # OpenAPI file for request/response validation\n```\n\n\n### 6. Routing Anomaly Detection\n\nThe Server will calculate an anomaly score for the request based on global avg routing and session avg routing.\nThe score is added as a header to the request `X-Anomaly-Score`.\nThe score ranging between 0 (normal request) to 1 (a-normal request)\n\n```yaml\nservices:\n  - domain: your-domain.com\n  \n    # Will add to downstream request an header with routing anomaly score between 0 (normal) and 1 (suspicuse)\n    anomaly_detection: \n      active: true\n      header_name: \"X-Anomaly-Score\" # (Optional) [Default: X-Anomaly-Score]\n      min_score: 100 # (Optional) Every internal score below this number is 0 [Default: 100]\n      max_score: 100 # (Optional) Every internal score above this number is 1 [Default: 200]\n      treshold_for_rating: 100 # (Optional) The amount of requests to collect stats on before starting to rate anomaly [Default: 100]\n```\n\n\n### 7. Load Balancing and File Serving\n\nFile serving is used when the `directory` field is set.\n\u003e The endpoint path is removed from the request path before the file lookup. For example a path of /static and request path of /static/file.txt and a directory /var/www will search the file in /var/www/file.txt and not /var/www/static/file.txt\n\n```yaml\n- path: /static\n  directory: /var/www/\n```\n\nThe Server support load balancing between a number of backend servers and allow you to choose the balancing policy.\n\n\n```yaml\n- path: /static\n  backend:\n    balance_policy: 'round-robin'\n    servers:\n      - url: http://backend-server-1/\n        weight: 1\n      - url: http://backend-server-2/\n        weight: 2\n```\n\n#### Supported Policies:\n- `round-robin` (affected by weights)\n- `random` (affected by weights)\n- `least-latency` (**not** affected by weights)\n\n\n### 8. Health Checks\n\nThe server supports automated health checks for backend services. You can configure periodic checks to monitor the health of your backend servers under each endpoint's configuration.\n\n```yaml\n- path: /\n  checks:\n    - name: \"Health Check\"      # Descriptive name for the check\n      cron: \"* * * * *\"        # Cron expression for check frequency\n      # Supported cron macros:\n      # - @yearly (or @annually) - Run once a year\n      # - @monthly              - Run once a month\n      # - @weekly               - Run once a week\n      # - @daily                - Run once a day\n      # - @hourly               - Run once an hour\n      # - @minutely             - Run once a minute\n      method: GET              # HTTP method for the health check\n      url: \"http://backend-server-1/up\"  # Health check endpoint\n      timeout: 5s             # Timeout for health check requests\n      headers:                # Optional custom headers\n        Host: domain.org\n        Authorization: \"Bearer abc123\"\n```\n\n### 9. OpenTelemetry Integration\nThe server includes built-in support for OpenTelemetry, enabling comprehensive observability through distributed tracing, metrics, and logging. This integration helps monitor application performance, troubleshoot issues, and understand system behavior in distributed environments.\n\n```yaml\nversion: '...'\n\nopen_telemetry:\n  endpoint: \"localhost:4317\"\n  sample_ratio: 0.01  # == 1%\n```\n\n## Configuration Example\n\nHere’s a generic example of how you can configure the reverse proxy:\n\n```yaml\nversion: '0.0.1'\nhost: your-host\nport: your-port\n\nssl:\n  keyfile: /path/to/your/ssl/keyfile\n  certfile: /path/to/your/ssl/certfile\n\nopen_telemetry:\n  endpoint: \"localhost:4317\"\n  sample_ratio: 0.01  # == 1%\n\nservices:\n  - domain: your-domain.com\n\n    # Will add to downstream request an header with routing anomaly score between 0 (normal) and 1 (suspicuse)\n    anomaly_detection: \n      active: true\n      header_name: \"X-Anomaly-Score\" # (Optional) [Default: X-Anomaly-Score]\n      min_score: 100 # (Optional) Every internal score below this number is 0 [Default: 100]\n      max_score: 100 # (Optional) Every internal score above this number is 1 [Default: 200]\n      treshold_for_rating: 100 # (Optional) The amount of requests to collect stats on before starting to rate anomaly [Default: 100]\n  \n    endpoints:\n      - path: /your-endpoint  # will be served for every request with path that start with /your-endpoint (Example: /your-endpoint/1)\n\n        # directory: /home/yoyo/  # For static files serving\n        # destination: http://your-backend-service/\n        backend:\n          balance_policy: 'round-robin'  # Can be 'round-robin', 'random', or 'least-latency'\n          servers:\n            - url: http://backend-server-1/\n              weight: 1\n            - url: http://backend-server-2/\n              weight: 2\n        \n        minify: [js, html, css, json, xml, svg]\n        # You can use 'all' instaed to enable all content-types\n\n        gzip: true  # Enable GZIP compression\n        \n        timeout: 5s  # Custom timeout for backend responses (Default 30s)\n        max_size: 2048  # Max request size in bytes (Default 10MB)\n        \n        ratelimits:\n          - ip-10/m  # Limit to 10 requests per minute per IP\n          - ip-500/d  # Limit to 500 requests per day per IP\n        \n        openapi: /path/to/openapi.yaml  # OpenAPI file for request/response validation\n\n        omit_headers: [Server]  # Omit response headers\n\n        checks:\n          - name: \"Health Check\"\n            \n            cron: \"* * * * *\" # == @minutely\n            # Support cron format and macros.\n            # Macros:\n            # - @yearly\n            # - @annually\n            # - @monthly\n            # - @weekly\n            # - @daily\n            # - @hourly\n            # - @minutely\n\n            method: GET  # HTTP Method\n            url: \"http://backend-server-1/up\"\n            timeout: 5s\n            headers:\n              Host: domain.org\n              Authorization: \"Bearer abc123\"\n\n            # on_failure runs a shell command if the check fails. Expands $date, $error, $check_name.\n            on_failure: |\n              curl -d \"Health check '$check_name' failed at $date due to: $error\" ntfy.sh/gatego\n        cache: true  # Cache responses that has cache headers (Cache-Control and Expire)\n\n```\n\n### Breakdown\nThe configuration is organized into three main sections:\n\n- Global Settings:\n  - Server configuration (host, port) \n  - SSL settings \n  - OpenTelemetry configuration\n\n\n- Services\n  - Domain-based routing\n  - Multiple endpoints per domain\n  - Path-based matching with longest-prefix wins\n\n\n- Endpoints\n  - Backend service configuration\n  - Performance optimizations\n  - Security controls\n  - Monitoring settings\n\nEach endpoint can be independently configured with its own set of features, allowing for flexible and granular control over different parts of your application.\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhvuhsg%2Fgatego","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhvuhsg%2Fgatego","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhvuhsg%2Fgatego/lists"}