{"id":15492272,"url":"https://github.com/ethlo/cloud-gateway","last_synced_at":"2025-04-22T19:26:06.274Z","repository":{"id":150816963,"uuid":"616121060","full_name":"ethlo/cloud-gateway","owner":"ethlo","description":"Reverse-proxy and web-server built on top of Spring Cloud Gateway supporting full request/response logging","archived":false,"fork":false,"pushed_at":"2025-01-21T08:32:38.000Z","size":1439,"stargazers_count":5,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T18:11:21.339Z","etag":null,"topics":["access-log","http-traffic","rate-limiting","reverse-proxy","spring-boot","spring-cloud"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/ethlocom/cloud-gateway","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ethlo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2023-03-19T17:08:51.000Z","updated_at":"2025-01-21T08:32:41.000Z","dependencies_parsed_at":"2023-06-25T22:17:45.822Z","dependency_job_id":"faf8d5e5-9053-445d-8208-1304c5d7f7b7","html_url":"https://github.com/ethlo/cloud-gateway","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethlo%2Fcloud-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethlo%2Fcloud-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethlo%2Fcloud-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethlo%2Fcloud-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethlo","download_url":"https://codeload.github.com/ethlo/cloud-gateway/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250307572,"owners_count":21409097,"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":["access-log","http-traffic","rate-limiting","reverse-proxy","spring-boot","spring-cloud"],"created_at":"2024-10-02T07:59:55.182Z","updated_at":"2025-04-22T19:26:06.246Z","avatar_url":"https://github.com/ethlo.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cloud Gateway\n\nCloud Gateway is a Docker-packaged reverse proxy built on Spring Cloud Gateway, offering full request/response logging,\nincluding body content. It integrates with Grafana for traffic monitoring.\n\n## Features\n\n* Reverse proxy built on Spring Cloud Gateway.\n* Full HTTP request/response logging, including headers and body.\n* Dockerized deployment with Grafana for real-time monitoring.\n\n\u003cimg src=\"doc/basic_dashboard.png\" alt= \"Simple overview dashboard\"\u003e\n\n## Getting Started\n\n### Prerequisites\n\n* [Docker](https://www.docker.com/) installed.\n* `docker-compose` file provided in the `/docker` folder.\n\n### Installation\n\n1. **Clone the repository**:\n\n   ```\n   git clone https://github.com/ethlo/cloud-gateway.git\n   cd cloud-gateway/docker\n   ```\n\n2. **Start the services**:\n\n   ```\n   docker-compose up -d\n   ```\n\n3. **Generate traffic**:\n\n   ```\n   curl -uuser:pass http://localhost:6464/get\n   ```\n\n4. **View results in Grafana**:\n\n   Access Grafana at [http://localhost:3000](http://localhost:3000).\n\n    * **Username**: `admin`\n    * **Password**: `grafana`\n\n   Select the dashboard named `HTTP traffic` from the left-hand menu to view traffic data.\n\n## Configuration\n\n### Main Configuration\n\nThe main configuration file is located in `config/application.yaml`.\n\n### Logging Configuration\n\nCloud Gateway supports powerful and flexible logging configurations. Below is a sample configuration:\n\n#### Basic Example:\n\n```\nhttp-logging:\n  matchers:\n    - id: API writes\n      predicates:\n        - Path=/**\n        - NotMethod=GET\n      request:\n        headers:\n          excludes:\n            - X-My-App-Key\n            - Session\n        body: STORE\n        raw: SIZE\n```\n\n#### Header Logging Options\n\n* Configure lists of headers using `includes` and `excludes`.\n* By default, all headers are included except for `Authorization`.\n\n#### Body Logging Options\n\n* `NONE`: No logging (default).\n* `SIZE`: Logs the body size.\n* `STORE`: Logs the full body content.\n\n#### Raw Data Logging Options\n\n* `NONE`: No logging (default).\n* `SIZE`: Logs the request size.\n* `STORE`: Logs the full raw request, including headers and body.\n\n**Warning**: Storing raw data may include sensitive information such as usernames, passwords, and API keys.\n\nFor more details on logging in Spring Boot, see\nthe [official Spring documentation](https://docs.spring.io/spring-boot/how-to/logging.html#howto.logging.logback).\n\n### Logging Providers\n\n#### File-Based Logging\n\nLog requests to a file using a customizable template pattern:\n\n```\nhttp-logging:\n  providers:\n    file:\n      enabled: true\n      pattern: '{{gateway_request_id}} {{method}} {{path}} {{request_headers[\"Content-Length\"][0]}} {{status}}'\n```\n\n#### ClickHouse Logging\n\nLog data to a ClickHouse table for detailed analysis:\n\n```\nhttp-logging:\n  filter:\n    request-headers:\n      exclude: \n          # r = REDACT, default is DELETE\n        - Authorization,r \n        - Api-Access-Key\n  providers:\n    clickhouse:\n      enabled: true\n      url: jdbc:ch://localhost:18123?database=default\u0026async_insert=1,wait_for_async_insert=0\n```\n\n### Handling Unprocessed Requests\n\nIf the upstream server is down, the request contents may be lost. You can still capture the request by configuring a\nfallback:\n\n```\nspring:\n  cloud:\n    gateway:\n      routes:\n        - id: my-upstream-is-down\n          uri: http://my-service1\n          predicates:\n            - Path=/my-service\n          filters:\n            - name: CircuitBreaker\n              args:\n                name: upstream-down\n                fallbackUri: forward:/upstream-down\n```\n\n### Running Behind a Reverse Proxy or WAF\n\nIf Cloud Gateway is behind a load balancer or firewall, configure it to handle forwarded headers properly:\n\n```\nserver:\n  forward-headers-strategy: NATIVE\n```\n\nFor more information, refer to\nthe [Spring Boot documentation on using it behind a proxy server](https://docs.spring.io/spring-boot/how-to/webserver.html#howto.webserver.use-behind-a-proxy-server).\n\n## Custom filters\n\n### CorrelationIdHeader\n          \nA filter that injects a correlation-id header in both the request and response headers. Upstream servers should use this correlation-id to correlate the log entries. \n```yaml\nfilters:\n- CorrelationIdHeader\n```\nThe header name can be changed if necessary, by setting the `header-name` argument. The default is `X-Correlation-Id`.\n### TemplateRedirect\n\nIt supports regexp named parameters, otherwise you can also use numeric variables like `{{1}}` and `{{2}}`. You also\nhave access to query parameters via `query`\n\nExample shorthand:\n\n```yaml\nfilters:\n- TemplateRedirect=/foo/(?\u003cvar1\u003e.*)/21/(?\u003cvar2\u003e.*),https://example.com/{{var2}}?={{var1}},302\n```\n\nExample full:\n\n```yaml\nfilters:\n- name: TemplateRedirect\n  source: /foo/(?\u003cvar1\u003e.*)/21/(?\u003cvar2\u003e.*)\n  target: https://example.com/{{var2}}?={{var1}}\n  status: 301 # default is 302\n```\n\n### InjectAccessTokenAuth\n\nAllows to inject a JWT bearer-token that is fetched on behalf of the configured refresh token. In case the refresh token is not valid, or there is an error fetching a bearer token, an HTTP 403 Forbidden is returned from Cloud Gateway.\n```yaml\nfilters:\n  - name: InjectAccessTokenAuth\n    args:\n      client-id: my-client\n      token-url: https://sso.example.com/token\n      refresh-token: ey...\n      minimum-ttl: PT30S # Default is 1 minute\n```\n\n### InjectBasicAuth\n\nAllows the injection of basic auth credentials before forwarding the request upstream\n\n```yaml\nfilters:\n  - name: InjectBasicAuth\n    args:\n      username: ${SECRET_USERNAME}\n      password: ${SECRET_PASSWORD}\n```\n\n## Custom predicates\n\n### NotPath\n\nNegated version\nof [Path](https://cloud.spring.io/spring-cloud-gateway/multi/multi_gateway-request-predicates-factories.html#_path_route_predicate_factory).\n\n```yaml\n- NotPath=/secret\n```\n\n### NotMethod\n\nNegated version\nof [Method](https://cloud.spring.io/spring-cloud-gateway/multi/multi_gateway-request-predicates-factories.html#_method_route_predicate_factory).\n\n```yaml\n- NotMethod=GET\n```\n\n### NotHost\n\nNegated version\nof [Host](https://cloud.spring.io/spring-cloud-gateway/multi/multi_gateway-request-predicates-factories.html#_host_route_predicate_factory).\n\n```yaml\n- NotHost=sub.example.com\n```\n\n### NotExtension\n\nWithout any listed extension, it will skip all URLs ending with an extension.\n\nExample config for not logging anything with an extension (like `file.js`, `file.css`, etc.):\n\n```yaml\n- NotExtension=\n```\n\nExample config fo skipping specific extensions. Other extensions like `file.zip` would still be let through:\n\n```yaml\n- NotExtension=html,css,js\n```\n\n## Serving static resources\n\nWhen serving static resources, one can define multiple layers, where the first layers are taking precedence over later defined layers. This allows to share common files, but override specific ones where needed. \n\nThe `application.yaml` can define multiple instances of LayeredFileSystem.\n\n```yaml\nstatic-files:\n   url-prefix: myfiles # default prefix is `files`\n   directories:\n      mydir1:\n         - /path/to/layer1/for/mydir1\n         - /path/to/layer2/for/mydir1\n      mydir2:\n         - /path/to/layer1/for/mydir2\n         - /path/to/layer2/for/mydir2\n         - /path/to/layer3/for/mydir2\n```\n\nFor example, the files from `mydir1` will be available under `/myfiles/mydir1/\u003cfile\u003e`.\n\nThe prefix can be adjusted with the `static-files.url-prefix` setting as shown above.\n\n#### An example with 3 layers:\n```\n            ▼\n┌──────────────────────────┐\n│        [Layer 1]         │ ▶ Not found, continue\n└──────────────────────────┘\n            ▼         \n┌──────────────────────────┐\n│        [Layer 2]         │ ▶ Not found, continue\n└──────────────────────────┘\n            ▼\n┌──────────────────────────┐\n│        [Layer 3]         │ ▶ Found, return contents\n└──────────────────────────┘\n```\n\n* Layer 1: The request checks Layer 1 first. Since the file is not present, the system moves to the next layer.\n* Layer 2: The system checks Layer 2, where the file is also not found.\n* Layer 3: The file is finally located in Layer 3, so the system retrieves it from this layer.\nThis approach maintains a fallback order, with each layer serving as a backup if the file is not available in the layers above it.\n\n\u003e [!IMPORTANT]\n\u003e To define paths with multiple segments, you need to wrap the YAML key in quotes and brackets to avoid stripping of slashes from the key!\n\u003e I.e. to define `/foo/bar` you need to write `\"[/foo/bar]\"`.\n\n## Monitoring with Grafana\n\nGrafana is set up to visualize traffic data logged by Cloud Gateway. Access Grafana\nat [http://localhost:3000](http://localhost:3000) and view the `HTTP traffic` dashboard to monitor real-time traffic.\n\n## References\n\nFor more detailed documentation, refer to:\n\n* [Spring Cloud Gateway Reference](https://cloud.spring.io/spring-cloud-gateway/)\n* [Spring Boot Documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/)\n* [Docker Documentation](https://docs.docker.com/)\n\n## Guides\n\nFor practical use cases and guides on how to extend the functionalities of Cloud Gateway, you may refer to:\n\n* [Building a microservices gateway](https://spring.io/guides/gs/gateway/)\n* [Getting started with Spring Boot](https://spring.io/guides/gs/spring-boot/)\n* [Monitor your services with Grafana](https://grafana.com/docs/grafana/latest/getting-started/getting-started-grafana/)\n\n## Contributing\n\nContributions are welcome! Please submit issues or pull requests via\nthe [GitHub repository](https://github.com/ethlo/cloud-gateway).\n\n## License\n\nThis project is licensed under the Apache 2 License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethlo%2Fcloud-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethlo%2Fcloud-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethlo%2Fcloud-gateway/lists"}