{"id":30344484,"url":"https://github.com/7mza/spring-gateway-geolite","last_synced_at":"2026-05-14T03:32:40.268Z","repository":{"id":309762107,"uuid":"1037346433","full_name":"7mza/spring-gateway-geolite","owner":"7mza","description":"Spring Cloud Gateway GeoLite2 integration and bot detection","archived":false,"fork":false,"pushed_at":"2026-04-24T21:55:08.000Z","size":406,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-24T23:31:43.899Z","etag":null,"topics":["bots","geoip2","geolite2","kotlin","spring","spring-boot","spring-cloud","spring-cloud-gateway","springboot","webflux"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","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/7mza.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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-13T12:40:55.000Z","updated_at":"2026-04-24T21:55:14.000Z","dependencies_parsed_at":"2025-09-01T07:15:52.308Z","dependency_job_id":"6a6a41cc-634a-454e-9d45-103dbd8961c2","html_url":"https://github.com/7mza/spring-gateway-geolite","commit_stats":null,"previous_names":["7mza/spring-gateway-geolite"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/7mza/spring-gateway-geolite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7mza%2Fspring-gateway-geolite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7mza%2Fspring-gateway-geolite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7mza%2Fspring-gateway-geolite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7mza%2Fspring-gateway-geolite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/7mza","download_url":"https://codeload.github.com/7mza/spring-gateway-geolite/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7mza%2Fspring-gateway-geolite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33009479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["bots","geoip2","geolite2","kotlin","spring","spring-boot","spring-cloud","spring-cloud-gateway","springboot","webflux"],"created_at":"2025-08-18T12:42:28.875Z","updated_at":"2026-05-14T03:32:40.262Z","avatar_url":"https://github.com/7mza.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spring Cloud Gateway GeoLite2\n\nSCG auto configured filter for GeoLite2 integration and bot detection\n\n- automatically transforms X-Forwarded-For header to GeoIP2 data and add it to MDC/tracing baggage\n  using [MaxMind's local GeoLite2 dbs](https://github.com/P3TERX/GeoLite.mmdb)\n- basic bot scoring and detection (WIP)\n- reject request if bot score threshold is reached\n\n[data model](./core/src/main/kotlin/io/github/hamza/geolite/Models.kt)\n\n```json\n{\n  \"xForwardedFor\": \"128.101.101.101\",\n  \"path\": \"/stub\",\n  \"query\": \"toto=true\u0026tata=123\",\n  \"city\": {\n    \"name\": \"Minneapolis\",\n    \"isoCode\": \"MN\",\n    \"latitude\": 44.9696,\n    \"longitude\": -93.2348\n  },\n  \"country\": {\n    \"name\": \"United States\",\n    \"isoCode\": \"US\"\n  },\n  \"asn\": {\n    \"autonomousSystemNumber\": 217,\n    \"autonomousSystemOrganization\": \"University of Minnesota\",\n    \"ipAddress\": \"128.101.101.101\",\n    \"hostAddress\": \"128.101.0.0\",\n    \"prefixLength\": 16\n  },\n  \"additionalHeaders\": {\n    \"user-agent\": [\n      \"...\"\n    ]\n  },\n  \"botScore\": 10,\n  \"isBot\": false\n}\n```\n\nthis model will be accessible to log encoders in MDC \u0026 can be prepared by log collectors\n\n## usage\n\n```kotlin\nimplementation(\"io.github.7mza:spring-gateway-geolite:$latest\")\n```\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.7mza\u003c/groupId\u003e\n    \u003cartifactId\u003espring-gateway-geolite\u003c/artifactId\u003e\n    \u003cversion\u003e$latest\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nautoconfiguration conditional on\n\n- spring-cloud-starter-gateway-server-webflux\n- io.micrometer:micrometer-tracing-bridge-otel\n- actuator\n\nmicrometer is needed to [pass baggage to\nMDC](https://docs.spring.io/spring-boot/reference/actuator/tracing.html#actuator.micrometer-tracing.baggage)\n\ndownload latest GeoLite dbs from [P3TERX/GeoLite.mmdb](https://github.com/P3TERX/GeoLite.mmdb) and place in a spring\nResourceLoader relative path (src/main/resources/...) inside your SCG\n\n### configure on SCG\n\n```yaml\ngeolite:\n  baggage: visitor_info # MDC field / baggage name\n  blockBot: false # block request if bot score threshold is reached, return 429\n  botScoreThreshold: 12 # bot score detection threshold\n  cached: true # enable reactor cache over database files\n  db:\n    # spring ResourceLoader relative path to db file\n    asn: geolite/GeoLite2-ASN.mmdb\n    city: geolite/GeoLite2-City.mmdb\n    country: geolite/GeoLite2-Country.mmdb\n  exclude: [] # fields to exclude from MDC\n#    - asn.ipAddress # or\n#    - asn.* # or\n  maxTrustedIndex: 1\nmanagement:\n  tracing:\n    baggage:\n      correlation:\n        fields:\n          - ${geolite.baggage}\n#        remote-fields: # to forward in headers\n#          - ${geolite.baggage}\nlogging:\n  level:\n    io.github.hamza.geolite: WARN # log level you are using to send logs to collector\n```\n\ntrue non-proxy X-Forwarded-For is resolved\nusing [maxTrustedIndex](https://docs.spring.io/spring-cloud-gateway/reference/spring-cloud-gateway-server-webflux/request-predicates-factories.html#modifying-the-way-remote-addresses-are-resolved)\n\n### then apply as any other filter on your routes\n\n#### webflux\n\n```yaml\nspring:\n  cloud:\n    gateway:\n      server:\n        webflux:\n          routes:\n            # basic usage\n            - id: id1\n              uri: uri1\n              predicates:\n                - ...\n              filters:\n                - ReactiveGeoLite\n\n            # append specific headers\n            - id: id2\n              uri: uri2\n              predicates:\n                - ...\n              filters:\n                - ReactiveGeoLite\n                - name: ReactiveGeoLite\n                  args:\n                    additionalHeaders:\n                      - user-agent\n\n            # append all headers (useful to study bots behavior)\n            - id: id3\n              uri: uri3\n              predicates:\n                - ...\n              filters:\n                - ReactiveGeoLite\n                - name: ReactiveGeoLite\n                  args:\n                    additionalHeaders:\n                      - \"*\"\n```\n\n#### webmvc\n\n```yml\n# TODO\n```\n\n**because of how free GeoLite databases are distributed, this filter require increased Xms/Xmx reservation to prevent\nOOM**\n\n`-Xms1g -Xmx1536m` is recommend but you should test according to your traffic\n\n### support\n\n- v. 2.x: spring boot 4.x / spring cloud 2025.1.+\n- v. 1.x: spring boot 3.x / spring cloud 2025.0.0\n\n### archi\n\n- core: implementation\n- scg-\\*-test: integration tests on a real SCG / wiremock\n\n### local build\n\n[sdkman](https://sdkman.io)\n\n- jdk 21 for broader support\n\n```shell\nsdk env install\n```\n\n```shell\n# download latest DBs and place them in ./scg-webflux-test/src/main/resources/geolite/\n./download_geolite.sh\n```\n\n```yaml\n./gradlew clean ktlintFormat ktlintCheck build\n```\n\n```yaml\n./gradlew publishToMavenLocal\n```\n\nin your SCG pom/build\n\n```kotlin\nrepositories {\n    // ...\n    mavenLocal()\n}\n\ndependencies {\n    // ...\n    implementation(\"io.github.7mza:spring-gateway-geolite:${local_build_version}\")\n}\n```\n\n### TODO\n\n- SCG webmvc\n- cache auto plug\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7mza%2Fspring-gateway-geolite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F7mza%2Fspring-gateway-geolite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7mza%2Fspring-gateway-geolite/lists"}