{"id":15058979,"url":"https://github.com/chargetrip/clusterbuster","last_synced_at":"2025-10-05T01:53:03.527Z","repository":{"id":35602615,"uuid":"215876544","full_name":"chargetrip/clusterbuster","owner":"chargetrip","description":"A Mapbox Vector Tile (MVT) map tiling server with built-in clustering and filtering","archived":false,"fork":false,"pushed_at":"2023-11-23T14:51:38.000Z","size":4057,"stargazers_count":95,"open_issues_count":29,"forks_count":17,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-09-15T03:55:43.288Z","etag":null,"topics":["clustering-algorithm","geospatial","mapbox-vector-tile","maps","mercator-projection","mvt","openstreetmap","openstreetmap-protobuffer-format","postgis","postgresql"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/chargetrip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-10-17T20:06:54.000Z","updated_at":"2025-07-21T09:57:39.000Z","dependencies_parsed_at":"2024-01-17T03:17:36.297Z","dependency_job_id":"146de117-d290-481e-8682-ed656ee2422b","html_url":"https://github.com/chargetrip/clusterbuster","commit_stats":{"total_commits":70,"total_committers":7,"mean_commits":10.0,"dds":"0.30000000000000004","last_synced_commit":"e66243d4ad29325407adbbccfb35ac1fd0b90f22"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/chargetrip/clusterbuster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargetrip%2Fclusterbuster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargetrip%2Fclusterbuster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargetrip%2Fclusterbuster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargetrip%2Fclusterbuster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chargetrip","download_url":"https://codeload.github.com/chargetrip/clusterbuster/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargetrip%2Fclusterbuster/sbom","scorecard":{"id":274135,"data":{"date":"2025-08-11","repo":{"name":"github.com/chargetrip/clusterbuster","commit":"e66243d4ad29325407adbbccfb35ac1fd0b90f22"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.8,"checks":[{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Code-Review","score":7,"reason":"Found 20/28 approved changesets -- score normalized to 7","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: containerImage not pinned by hash: Dockerfile:1: pin your Docker image by updating node:10.15.1 to node:10.15.1@sha256:91d4f8b1d5094d413afdcae4af37e4361686019691c441c09a021864ddeb468e","Info:   0 out of   1 containerImage dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 28 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"76 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92","Warn: Project is vulnerable to: GHSA-h5c3-5r3r-rr8q","Warn: Project is vulnerable to: GHSA-rmvr-2pp2-xj38","Warn: Project is vulnerable to: GHSA-xx4v-prfh-6cgc","Warn: Project is vulnerable to: GHSA-v88g-cgmw-v5xw","Warn: Project is vulnerable to: GHSA-93q8-gq69-wqmw","Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg","Warn: Project is vulnerable to: GHSA-w8qv-6jwh-64r5","Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x","Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275","Warn: Project is vulnerable to: GHSA-gxpj-cx7g-858c","Warn: Project is vulnerable to: GHSA-w573-4hg7-7wgq","Warn: Project is vulnerable to: GHSA-ff7x-qrg7-qggm","Warn: Project is vulnerable to: GHSA-rv95-896h-c2vc","Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx","Warn: Project is vulnerable to: GHSA-fjxv-7rqg-78g4","Warn: Project is vulnerable to: GHSA-ww39-953v-wcq6","Warn: Project is vulnerable to: GHSA-pfrx-2q88-qq97","Warn: Project is vulnerable to: GHSA-765h-qjxv-5f44","Warn: Project is vulnerable to: GHSA-f2jv-r9rf-7988","Warn: Project is vulnerable to: GHSA-43f8-2h32-f4cj","Warn: Project is vulnerable to: GHSA-rc47-6667-2j5j","Warn: Project is vulnerable to: GHSA-qqgx-2p2h-9c37","Warn: Project is vulnerable to: GHSA-78xj-cgh5-2h22","Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp","Warn: Project is vulnerable to: GHSA-896r-f27r-55mw","Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h","Warn: Project is vulnerable to: GHSA-p6mc-m468-83gw","Warn: Project is vulnerable to: GHSA-29mw-wpgm-hmr9","Warn: Project is vulnerable to: GHSA-35jh-r3h4-6jhm","Warn: Project is vulnerable to: GHSA-5v2h-r2cx-5xgj","Warn: Project is vulnerable to: GHSA-rrrm-qjm4-v8hf","Warn: Project is vulnerable to: GHSA-4xcv-9jjx-gfj3","Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv","Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3","Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h","Warn: Project is vulnerable to: GHSA-w7rc-rwvf-8q5r","Warn: Project is vulnerable to: GHSA-r683-j2x4-v87g","Warn: Project is vulnerable to: GHSA-5fw9-fq32-wv5p","Warn: Project is vulnerable to: GHSA-px4h-xg32-q955","Warn: Project is vulnerable to: GHSA-93f3-23rq-pjfp","Warn: Project is vulnerable to: GHSA-jmqm-f2gx-4fjv","Warn: Project is vulnerable to: GHSA-pw54-mh39-w3hc","Warn: Project is vulnerable to: GHSA-xgh6-85xh-479p","Warn: Project is vulnerable to: GHSA-hj48-42vr-x3v9","Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j","Warn: Project is vulnerable to: GHSA-rhx6-c78j-4q9w","Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp","Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6","Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm","Warn: Project is vulnerable to: GHSA-r2j6-p67h-q639","Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw","Warn: Project is vulnerable to: GHSA-44c6-4v22-4mhx","Warn: Project is vulnerable to: GHSA-4x5v-gmq8-25ch","Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg","Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p","Warn: Project is vulnerable to: GHSA-vx3p-948g-6vhq","Warn: Project is vulnerable to: GHSA-3jfq-g458-7qm9","Warn: Project is vulnerable to: GHSA-r628-mhmh-qjhw","Warn: Project is vulnerable to: GHSA-9r2w-394v-53qc","Warn: Project is vulnerable to: GHSA-5955-9wpr-37jh","Warn: Project is vulnerable to: GHSA-qq89-hq3f-393p","Warn: Project is vulnerable to: GHSA-f5x3-32g6-xq36","Warn: Project is vulnerable to: GHSA-jgrx-mgxx-jf9v","Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3","Warn: Project is vulnerable to: GHSA-w5p7-h5w8-2hfq","Warn: Project is vulnerable to: GHSA-7p7h-4mm5-852v","Warn: Project is vulnerable to: GHSA-38fc-wpqx-33j7","Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7","Warn: Project is vulnerable to: GHSA-6fc8-4gx4-v693","Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q","Warn: Project is vulnerable to: GHSA-c4w7-xm78-47vh","Warn: Project is vulnerable to: GHSA-p9pc-299p-vxgp"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-17T14:03:12.701Z","repository_id":35602615,"created_at":"2025-08-17T14:03:12.701Z","updated_at":"2025-08-17T14:03:12.701Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278399611,"owners_count":25980332,"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","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"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":["clustering-algorithm","geospatial","mapbox-vector-tile","maps","mercator-projection","mvt","openstreetmap","openstreetmap-protobuffer-format","postgis","postgresql"],"created_at":"2024-09-24T22:34:48.233Z","updated_at":"2025-10-05T01:53:03.511Z","avatar_url":"https://github.com/chargetrip.png","language":"TypeScript","funding_links":[],"categories":["Servers"],"sub_categories":[],"readme":"## Intro\n\nClusterbuster is a tile server that produces map tiles (in MVT format) from a table with a PostGIS geometry column. It uses this table to first filter the row (based on a query you provide) and the resulting points are then clustered dynamically. The combination of clusters and points is transformed into a vector tile. The MVT tiles are much smaller than the original data, moving all the heavy lifting from the front-end to the tile server. This allows the display of large data sets, that change regularly, on maps in resource constrained environments, such as mobile devices and embedded systems. Clusterbuster has a built-in and configurable in-memory LRU-cache for the resulting tiles, with which it can serve many concurrent users.\n\n## Getting started\n\nClusterbuster is designed to be used in a NodeJS server connected to a PostgreSQL database, with PostGIS extensions installed. You have to bring your own web framework, allowing clusterbuster to be easily integrated in any existing API that uses express.js, Koa, Hapi, etc..\n\n```Javascript\nconst { TileServer } = require('clusterbuster');\n\nTileServer({\n    // types/TileServerConfig.ts\n  maxZoomLevel,\n  attributes: ['status', 'speed'],\n  filtersToWhere: filters =\u003e {\n    // You are responsible for protecting against SQL injection in this function. Because there are many ways to filter, it depends on the filter type on how to approach this.\n\n    // For example a number can be safely used by passing it through parseFloat, strings are best treated by checking for a set of allowed values\n    const whereStatements = [];\n\n    // The below statement checks that filters.status is one of 'free' or 'busy' to prevent potential SQL injection\n    if (filters.status \u0026\u0026 ['busy', 'free'].includes(filters.status)) {\n      whereStatements.push(`status = '${filters.status}'`);\n    }\n    if (filters.speed \u0026\u0026 ['slow', 'fast'].includes(filters.speed)) {\n      whereStatements.push(`speed = '${filters.speed}'`);\n    }\n    return whereStatements;\n  },\n}).then(async tileServer =\u003e {\n    const tile = await tileServer({\n        // types/TileRequest.ts\n        z: 1,\n        x: 0,\n        y: 1,\n        table: 'public.my_points_table',\n        geometry: 'my_geometry_column'\n        extent: 4096,\n        bufferSize: 256,\n    });\n    // send the tile in binary MVT format to the front-end\n});\n```\n\nSee the [express.js example](/example) for a fully functioning server that exposes the above tile server on a REST endpoint. You can see the [TileServerConfig](/lib/types/TileServerConfig.ts) for the initial configuration options, to configure the cache, connection pool, filters, etc..\n\nThe [TileRequest](/lib/types/TileRequest.ts) defines the per tile request options.\n\nThe above example assumes a postgres database with a `public.my_points_table` table matching:\n\n```SQL\nCREATE EXTENSION postgis;\n\n-- Table: public.my_points_table\nCREATE TABLE public.my_points_table\n(\n    id TEXT,\n    my_geometry_column geometry(Point,4326),\n    speed TEXT,\n    status TEXT,\n\n    PRIMARY KEY(id)\n)\n\nTABLESPACE pg_default;\n\nGRANT ALL ON TABLE public.my_points_table TO \"tiler\";\n```\n\nThe internal [postgress client](https://node-postgres.com/) can be configured with the following env vars:\n\n```ENV\nPGUSER=tiler\nPGHOST=localhost\nPGPASSWORD=\nPGDATABASE=points\nPGPORT=5432\n```\n\n## Filtering\n\nThe `filtersToWhere` function can be used to implement custom filtering logic. It should return an array of SQL snippets, which clusterbuster transforms into the WHERE clause using AND between each statement.\n\nThe resulting SQL query looks something like this:\n\n```SQL\nSELECT ...\nWHERE whereStatement1 AND whereStatement2\n```\n\n## Caching\n\nThe default cache is a in-memory LRU cache local to the tile server. This cache is ideal for a single instance tile server. If you are going to use clusterbuster in a loadbalanced multi instance server environment, the cache can be a redis instance or cluster instead, allowing all tile server instances to share the same tile cache.\n\nYou need to install the peer dependency `npm i ioredis` and configure the tile server to use redis instead of LRU. See the [TileCacheOptions](/TileCacheOptions.ts) for all the configuration options.\n\n```json\n{ \"cacheOptions\": { \"type\": \"redis\" } }\n```\n\n## Internals\n\nThe tile server creates clusters using the PostGIS ST_ClusterDBSCAN starting at the maximum zoomlevel and continues clustering iteratively for each zoom level until the zoom level of the tile request is reached. This 'cluster of clusters' clustering algorithm is inspired by the excellent [supercluster](https://github.com/mapbox/supercluster) library, which many people use to cluster on the front-end and even on the back-end (using something like supertiler).\n\nPostGIS is used for all the work such as selecting points in the region of the tile and even for creating the binary tiles themselves, using ST_asMVT. The NodeJS server only creates the SQL statements which then create the tiles in the database. These tiles are then gzipped and stored in an in-memory LRU cache inside the NodeJS process.\n\nThe main performance bottleneck for clusterbuster is the PostgreSQL server as the clustering algorithm requires a lot of CPU cycles, especially at low (1-5) zoom levels. Because the lower zoom levels contain fewer total tiles to cover the whole map (1 tile for the whold world at zoom level 0),the LRU cache effectively shields the database from becoming overloaded when many users are using the map concurrently. The number of different filters reduces the effectiveness of the LRU cache, as each filter combination creates a unique set of cache keys for all tiles. Typically the 'default' filter settings will provide enough caching to keep the database from becoming overloaded by many concurrent users, but mileage may vary per use case.\n\n## Alternative tile servers (which inspired clusterbuster)\n\n- [Martin](https://github.com/urbica/martin) - A Rust based tile server, which has the option to provide PL/pgSQL function instead of a table, allows for filtering of data before tiling.\n- [Tilestrata](https://github.com/naturalatlas/tilestrata) (and especially [tilestrata-postgis-mvt](https://github.com/Stezii/tilestrata-postgismvt)) - Tilestrata is a tile server framework with an elaborate plugin architecture. The tilestrata-postgis-mvt plugin uses the same ST_asMvt functions provided by PostGIS as ClusterBuster does.\n- [Tegola](https://tegola.io/) - A Go based tile server\n\n## Alternative static tile generators\n\n- [tippecanoe](https://github.com/mapbox/tippecanoe)\n- [supertiler](https://github.com/ChrisLoer/supertiler)\n\nAll of these tile servers and tile generators offer some subset of the functionality we required, but lacked atleast one, which is our motivation for making clusterbuster.\n\n| Tiler         | dynamic data | filtering | backend clustering |\n| ------------- | ------------ | --------- | ---------- |\n| Clusterbuster | ✓            | ✓         | ✓          |\n| Martin        | ✓            | ✓         | x          |\n| Tilestrata    | ✓            | x         | x          |\n| Tegola        | ✓            | x         | x          |\n| Tippecanoe    | x            | x         | ✓          |\n| Supertiler    | x            | x         | ✓          |\n\n## When not to use clusterbuster\n\n- Your data is static (and no filtering is required) - use tippecanoe or supertiler to prerender all tiles and serve from a file hosting service such as S3 (which is much more economical and loads faster to the front-end)\n- Your data needs to be filtered, but not clustered:\n  Using Martin you can implement filtering using PL/pgSQL\n- You don't need filtering or clustering, you just need tiles from a dynamic data set: You can use any of the dynamic tile servers in the table above.\n\n## Sponsors\n\n[![Chargetrip logo](https://chargetrip-files.s3.eu-central-1.amazonaws.com/logo-1.png)](https://www.chargetrip.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchargetrip%2Fclusterbuster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchargetrip%2Fclusterbuster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchargetrip%2Fclusterbuster/lists"}