{"id":13413825,"url":"https://github.com/fabiocicerchia/go-proxy-cache","last_synced_at":"2025-07-14T04:32:09.749Z","repository":{"id":42078603,"uuid":"312312935","full_name":"fabiocicerchia/go-proxy-cache","owner":"fabiocicerchia","description":"Simple Reverse Proxy with Caching, written in Go, using Redis.","archived":false,"fork":false,"pushed_at":"2024-04-24T09:14:04.000Z","size":1661,"stargazers_count":118,"open_issues_count":33,"forks_count":15,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-05-01T12:22:01.986Z","etag":null,"topics":["cache","golang","proxy-server","redis"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fabiocicerchia.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":"docs/CODE_OF_CONDUCT.md","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},"funding":{"github":"fabiocicerchia","patreon":"fabiocicerchia","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2020-11-12T15:10:40.000Z","updated_at":"2024-05-15T15:09:09.192Z","dependencies_parsed_at":"2024-01-13T22:39:43.777Z","dependency_job_id":"39e23477-b801-4e1d-abd5-93b4c9ae6795","html_url":"https://github.com/fabiocicerchia/go-proxy-cache","commit_stats":{"total_commits":163,"total_committers":5,"mean_commits":32.6,"dds":"0.13496932515337423","last_synced_commit":"2cfed3bd3998663e657d9dfeb1ef2a13aa638b82"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiocicerchia%2Fgo-proxy-cache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiocicerchia%2Fgo-proxy-cache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiocicerchia%2Fgo-proxy-cache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiocicerchia%2Fgo-proxy-cache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabiocicerchia","download_url":"https://codeload.github.com/fabiocicerchia/go-proxy-cache/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225950749,"owners_count":17550307,"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":["cache","golang","proxy-server","redis"],"created_at":"2024-07-30T20:01:50.420Z","updated_at":"2024-11-22T18:54:46.738Z","avatar_url":"https://github.com/fabiocicerchia.png","language":"Go","funding_links":["https://github.com/sponsors/fabiocicerchia","https://patreon.com/fabiocicerchia"],"categories":["Server Applications","Go","服务器应用程序","服务端应用","Relational Databases"],"sub_categories":["HTTP Clients","HTTP客户端","查询语"],"readme":"# Go Proxy Cache\n\n\u003ccenter\u003e\n\n![Logo](https://github.com/fabiocicerchia/go-proxy-cache/raw/main/docs/assets/logo_small.png)\n\nSimple Reverse Proxy with Caching, written in Go, using Redis.  \n    \u003e\u003e\u003e **(semi) production-ready** \u003c\u003c\u003c\n\n[![MIT License](https://img.shields.io/badge/License-MIT-brightgreen.svg?longCache=true)](LICENSE)\n[![Pull Requests](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?longCache=true)](https://github.com/fabiocicerchia/go-proxy-cache/pulls)\n![Maintenance](https://img.shields.io/maintenance/yes/2023)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)  \n  \n![Last Commit](https://img.shields.io/github/last-commit/fabiocicerchia/go-proxy-cache)\n![Release Date](https://img.shields.io/github/release-date/fabiocicerchia/go-proxy-cache)\n![GitHub all releases](https://img.shields.io/github/downloads/fabiocicerchia/go-proxy-cache/total)\n\n![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/fabiocicerchia/go-proxy-cache)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/fabiocicerchia/go-proxy-cache)\n\n![Docker pulls](https://img.shields.io/docker/pulls/fabiocicerchia/go-proxy-cache \"Docker pulls\")\n![Docker stars](https://img.shields.io/docker/stars/fabiocicerchia/go-proxy-cache \"Docker stars\")\n\n![GitHub Workflow Status](https://img.shields.io/github/workflow/status/fabiocicerchia/go-proxy-cache/Builds)\n\n[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4469/badge)](https://bestpractices.coreinfrastructure.org/projects/4469)\n[![BCH compliance](https://bettercodehub.com/edge/badge/fabiocicerchia/go-proxy-cache?branch=main)](https://bettercodehub.com/results/fabiocicerchia/go-proxy-cache)\n[![Go Report Card](https://goreportcard.com/badge/github.com/fabiocicerchia/go-proxy-cache)](https://goreportcard.com/report/github.com/fabiocicerchia/go-proxy-cache)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Ffabiocicerchia%2Fgo-proxy-cache.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Ffabiocicerchia%2Fgo-proxy-cache?ref=badge_shield)  \n[![codecov](https://codecov.io/gh/fabiocicerchia/go-proxy-cache/branch/main/graph/badge.svg)](https://codecov.io/gh/fabiocicerchia/go-proxy-cache)\n[![Maintainability](https://img.shields.io/codeclimate/maintainability/fabiocicerchia/go-proxy-cache)](https://codeclimate.com/github/fabiocicerchia/go-proxy-cache/maintainability)\n[![Technical Debt](https://img.shields.io/codeclimate/tech-debt/fabiocicerchia/go-proxy-cache)](https://codeclimate.com/github/fabiocicerchia/go-proxy-cache/maintainability)\n[![Total alerts](https://img.shields.io/lgtm/alerts/g/fabiocicerchia/go-proxy-cache.svg)](https://lgtm.com/projects/g/fabiocicerchia/go-proxy-cache/alerts/)\n\n\u003c/center\u003e\n\n---\n\n## 💗 Support the Project 💗\n\nThis project is only maintained by one person, [Fabio Cicerchia](https://github.com/fabiocicerchia).  \nIt started as a simple caching service, now it has a lot of pro functionalities just for FREE 😎  \nMaintaining a project is a very time consuming activity, especially when done alone 💪\nI really want to make this project better and become super cool 🚀\n\nTwo commercial versions have been planned: [PRO and PREMIUM](https://kodebeat.com/goproxycache.html).  \n\nThe development of the COMMUNITY version will continue, but priority will be given to the [COMMERCIAL versions](https://kodebeat.com/goproxycache.html).  \n- If you'd like to support this open-source project I'll appreciate any kind of [contribution](https://github.com/sponsors/fabiocicerchia).\n- If you'd like to sponsor the commercial version, please [get in touch with me](mail:info@fabiocicerchia.it).\n\n---\n\n## How it works\n\nWhen the request is cached:\n\n```text\n        .---------.       .---------.       .---------.\n        |         |       |         |       |         |\n        |         |       |         |       |         |\nyou ---\u003e|----\u003e----|---\u003e---|----\u003e----|---\u003e---|--\u003e--.   |\n        |         |       |         |       |     |   |\n    \u003c---|----\u003c----|---\u003c---|----\u003c----|---\u003c---|--\u003c--'   |\n        `---------´       `---------´       `---------´\n          network        go-proxy-cache        redis\n```\n\nWhen the request is not cached:\n\n```text\n          website\n            ,_,\n            | |\n        .---+-+---.       .---------.       .---------.\n        |   | '--\u003e|---\u003e---|----\u003e----|---\u003e---|--\u003e--,   |\n        |   '-\u003c---|---\u003c---|\u003c--,     |       |     |   |\n        |         |       |   |     |       |     |   |\nyou ---\u003e|----\u003e----|---\u003e---|---'     |       |     |   |\n        |         |       |         |       |     |   |\n    \u003c---|----\u003c----|---\u003c---|----\u003c----|---\u003c---|--\u003c--'   |\n        `---------´       `---------´       `---------´\n          network        go-proxy-cache        redis\n```\n\n## Features\n\n### Small, Pragmatic and Easy to Use\n\n- **Dockerized**\n- **Compiled**\n- **Easily Configurable**, via YAML or Environment Variables.\n- **Self-Contained**, does not require Go, Git or any other software installed. Just run the binary or the container.\n\n### Caching\n\n- **Full Page Caching**, via Redis.\n- **Cache Invalidation**, by calling HTTP Method `PURGE` on the resource URI.\n- **Cache Bypass**, by using the HTTP Header `X-Go-Proxy-Cache-Force-Fresh` the request will always be fresh.\n- **Support Chunking**, by replicating exactly the same original amount.\n- **Selective HTTP Status Codes/Methods**, allows caching for different response codes or HTTP methods.\n- **ETag Support**, generating non-weak tags, handling `304 Not Modified`, managing HTTP headers `If-Modified-Since`, `If-Unmodified-Since`, `If-None-Match`, `If-Match`.  \n  ETag wrapper doesn't work well with WebSocket and HTTP/2.\n- **Cache Stampede Prevention**, delaying invalidation request to the backend using an extra small random TTL (between 5s and 10s).\n- **Serving Stale Content**, used mainly for avoiding cache stampede, for maximum 10s.\n- **Upstream DNS Resolution Cache**, the upstream hostname will be cached to speed up the response and avoid the DNS resolution at each request.\n\n### Load Balancing\n\n- **HTTP \u0026 HTTPS Forward Traffic**\n- **Load Balancing**, uses a list of IPs/Hostnames as load balanced backend servers.\n- **Multiple Algorithms Available**, choose among IP Hash, Least Connections, Random or Round-Robin.\n- **Support for HTTP Basic Auth**, it's possible to provide the HTTP Basic Auth for each endpoint (by specify user:pass in the URL).\n\n### Security\n\n- **HTTP/2 Support**, HTTP/2 Pusher achievable only if upstream implements [HTTP header `Link`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link). Server Push is deprecated (since not really supported in the browsers).\n- **SSL/TLS Certificates via ACME**, provides automatic generation of SSL/TLS certificates from [Let's Encrypt](https://letsencrypt.org/) and any other ACME-based CA.\n- **Using your own SSL/TLS Certificates**, optional.\n\n### Reliability\n\n- **Healthcheck Endpoint**, exposes the route `/healthcheck` (internally).\n- **Upstream Healthcheck**, verifies periodically if upstream nodes are healthy.\n- **Respecting HTTP Cache Headers**, `Vary`, `ETag`, `Cache-Control` and `Expires`.\n- **Fully Tested**, Unit, Functional \u0026 Linted \u0026 0 Race Conditions Detected.\n- **Cache Circuit Breaker**, bypassing Redis when not available.\n\n### Scaling\n\n- **Multiple domains**, override and fine-tune the global settings per domain.\n\n### Customisations\n\n- **HTTP to HTTPS Redirects**, optional, status code to be used when redirecting HTTP to HTTPS.\n- **GZip Compression**, optional.\n- **Server Timeouts**, it is possible to configure in details the server overall timeouts (read, write, headers, handler, idle).\n- **Fine tuning circuit-breaker and TLS settings**, it is possible to adjust the settings about thresholds, timeouts and failure rate.\n- **Configure error handler**, stdout or file.\n- **Debug/Verbose mode**, it is possible to have additional levels of details by settings the flags `-verbose` or `-debug`.\n\n### Logging\n\n- **Request Tracing**, each line in logs has a RequestID to easily identify the response flow.\n- **OpenTelemetry Tracing**, each request has a deep tracing with Jaeger (optional).\n- **Prometheus Endpoint**, exposes the route `/metrics` (internally) to serve Prometheus metrics.\n- **Support for Sentry \u0026 Syslog**, all warning/error logs can be forwarded to Sentry and/or Syslog.\n\n## Configuration\n\n## YAML\n\nThis is a simple (and not comprehensive) configuration:\n\n```yaml\nserver:\n  port:\n    http: \"80\"\n    https: \"443\"\n  tls:\n    cert_file: server.pem\n    key_file: server.key\n  upstream:\n    host: ~\n    port: 443\n    scheme: https\n    endpoints:\n      - 127.0.0.1\n    http_to_https: true\n    redirect_status_code: 301\n\ncache:\n  hosts: \n    - localhost:6379\n\ndomains:\n  example_com:\n    server:\n      upstream:\n        host: example.com\n\n  example_org:\n    server:\n      upstream:\n        host: example.org\n```\n\nFor more details about the full server configuration check the relative documentation in [docs/CONFIGURATION.md](https://github.com/fabiocicerchia/go-proxy-cache/blob/main/docs/CONFIGURATION.md)\n\n## Examples\n\n## CLI\n\n```console\n$ go-proxy-cache -h\nUsage of go-proxy-cache:\n  -config string\n        config file (default \"config.yml\")\n  -debug\n        enable debug\n  -log string\n        log file (default stdout)\n  -test\n        test configuration\n  -verbose\n        enable verbose\n  -version\n        display version\n[...]\n```\n\nFor examples check the relative documentation in [docs/EXAMPLES.md](https://github.com/fabiocicerchia/go-proxy-cache/blob/main/docs/EXAMPLES.md)\n\n## Release Cycle\n\n- Bug-fixes (e.g. `1.1.1`, `1.1.2`, `1.2.1`, `1.2.3`) are released as needed (no additional features are delivered in those versions, bug-fixes only).\n- Each version is supported until the next one is released (e.g. `1.1.x` will be supported until `1.2.0` is out).\n- We use [Semantic Versioning](https://semver.org/).\n\n## Common Errors\n\n- `acme/autocert: server name component count invalid`  \n  Let's Encrypt cannot be used locally, as described in [this thread](https://community.letsencrypt.org/t/can-i-test-lets-encrypt-client-on-localhost/15627)\n- `acme/autocert: missing certificate`  \n  Let's Encrypt cannot be used locally, as described in [this thread](https://community.letsencrypt.org/t/can-i-test-lets-encrypt-client-on-localhost/15627)\n- `501 Not Implemented`  \n  If there's no domain defined in the main configuration nor in the domain overrides, and a client will request an\n  unknown domain the status `501` is returned.\n- WebSocket and TimeoutHandler are not working together, because TimeoutHandler doesn't support Hijacker, so in order to have WebSocket support the setting `TimeoutHandler` must be set to `-1`.\n- `context deadline exceeded`  \n  The reason is because the timeout on the context.Context of the client side of the request is shorter than the timeout\n  in the server side handler. This means that the client gives up before any response is written.\n\n## References\n\n- [Proxy servers and tunneling](https://developer.mozilla.org/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling)\n- [Make resilient Go net/http servers using timeouts, deadlines and context cancellation](https://ieftimov.com/post/make-resilient-golang-net-http-servers-using-timeouts-deadlines-context-cancellation/)\n- [So you want to expose Go on the Internet](https://blog.cloudflare.com/exposing-go-on-the-internet/)\n- [Writing a very fast cache service with millions of entries in Go](https://allegro.tech/2016/03/writing-fast-cache-service-in-go.html)\n- [RFC7234 - Hypertext Transfer Protocol (HTTP/1.1): Caching](https://tools.ietf.org/html/rfc7234#section-4.2.1)\n- [The complete guide to Go net/http timeouts](https://blog.cloudflare.com/the-complete-guide-to-golang-net-http-timeouts/)\n- [What Happens in a TLS Handshake? | SSL Handshake](https://www.cloudflare.com/en-gb/learning/ssl/what-happens-in-a-tls-handshake/)\n- [A step by step guide to mTLS in Go](https://venilnoronha.io/a-step-by-step-guide-to-mtls-in-go)\n- [Learning HTTP caching in Go](https://www.sanarias.com/blog/115LearningHTTPcachinginGo)\n- [Nginx HTTP2 Server Push](https://ops.tips/blog/nginx-http2-server-push/)\n- [Introducing HTTP/2 Server Push with NGINX 1.13.9](https://www.nginx.com/blog/nginx-1-13-9-http2-server-push)\n- [Preload - W3C Editor's Draft 20 August 2020](https://w3c.github.io/preload/#server-push)\n- [Web Linking](https://tools.ietf.org/html/rfc5988)\n- [HTTP Health Checks](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/)\n- [Types of load balancing algorithms](https://www.cloudflare.com/en-gb/learning/performance/types-of-load-balancing-algorithms/)\n\n## License\n\n## OpenSSL\n\nThis product includes software developed by the OpenSSL Project for use in the\nOpenSSL Toolkit. ([http://www.openssl.org/](http://www.openssl.org/))\n\n## Go Proxy Cache\n\nMIT License\n\nCopyright (c) 2023 Fabio Cicerchia \u003cinfo@fabiocicerchia.it\u003e\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Ffabiocicerchia%2Fgo-proxy-cache.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Ffabiocicerchia%2Fgo-proxy-cache?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabiocicerchia%2Fgo-proxy-cache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabiocicerchia%2Fgo-proxy-cache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabiocicerchia%2Fgo-proxy-cache/lists"}