{"id":13564046,"url":"https://github.com/markdingo/cslb","last_synced_at":"2026-01-16T15:11:44.254Z","repository":{"id":57536360,"uuid":"196936238","full_name":"markdingo/cslb","owner":"markdingo","description":"A Go Client-Side Load-Balancer for HTTP/HTTPS","archived":false,"fork":false,"pushed_at":"2024-01-18T19:01:30.000Z","size":77,"stargazers_count":24,"open_issues_count":2,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-03T20:37:55.420Z","etag":null,"topics":["balancers","go","golang","golang-package","http","http-client","load-balancing","microservices","srv-rr"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markdingo.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","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":"AUTHORS","dei":null}},"created_at":"2019-07-15T06:17:57.000Z","updated_at":"2024-10-17T02:16:22.000Z","dependencies_parsed_at":"2024-03-16T22:58:50.538Z","dependency_job_id":"67f6c16c-fe96-484e-ae66-d6e64b729396","html_url":"https://github.com/markdingo/cslb","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/markdingo/cslb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdingo%2Fcslb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdingo%2Fcslb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdingo%2Fcslb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdingo%2Fcslb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markdingo","download_url":"https://codeload.github.com/markdingo/cslb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdingo%2Fcslb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["balancers","go","golang","golang-package","http","http-client","load-balancing","microservices","srv-rr"],"created_at":"2024-08-01T13:01:25.933Z","updated_at":"2026-01-16T15:11:44.221Z","avatar_url":"https://github.com/markdingo.png","language":"Go","readme":"## CSLB - A Go Client-Side Load-Balancer for HTTP/HTTPS\n\n`Cslb` is a client-side load-balancer for Go HTTP/HTTPS applications. `Cslb` is an alternative to\nserver-side load-balancers which add deployment and diagnostic complexity, cost, throughput\nconstraints and which also create an additional point of possible failure. `Cslb` puts load-balancer\nintelligence into your Go clients so you can simplify your deployment and potentially eliminate\nserver-side load-balancers.\n\nIn many cases the only action needed to take advantage of `cslb` is to import the package and add an\nSRV entry to your DNS. At that point, on behalf of your application, `cslb` automatically deals with\nfailed servers and spreads load across serving targets according to your load-distribution rules. In\naddition, once you have `cslb` in place you can also run a \"canary\" alerting service which can\nnotify you when clients are failing to reach their correct services.\n\nThe primary goal of `cslb` is to make client-side load-balancing a no-brainer for your Go application.\n\n[![Build](https://github.com/markdingo/cslb/actions/workflows/go.yml/badge.svg)](https://github.com/markdingo/cslb/actions/workflows/go.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/markdingo/cslb)](https://goreportcard.com/report/github.com/markdingo/cslb)\n[![codecov](https://codecov.io/gh/markdingo/cslb/branch/main/graph/badge.svg)](https://codecov.io/gh/markdingo/cslb)\n[![](https://godoc.org/github.com/markdingo/cslb?status.svg)](https://godoc.org/github.com/markdingo/cslb)\n\n### Installation\n\n`Cslb` is a standard Go package thus if your program is go-module aware (which is to say\nyou've run \"go mod init\") then `cslb` is pulled in when you run `\"go mod tidy\"` or you can\nspecifically pull it in with:\n\n\n```sh\n$ go get -u github.com/markdingo/cslb\n```\n\nAt this stage `cslb` has no package dependencies beyond the standard packages shipped with the Go\ncompiler. `Cslb` requires Go 1.12.x or greater.\n\n### Application Changes\n\nTo take advantage of `cslb` a program simply imports the package at which point `cslb` automatically\nstarts performing client-side load-balancing by over-riding the `DialContext` of the\n`http.DefaultTransport`. If the program uses its own `http.Transport` then its `DialContext` needs to\nbe similarly replaced. Here is the before and after code which shows the application changes needed:\n\n### Before\n\n```go\n\n import (\n         \"net/http\"\n )\n\n func main() {\n        resp, err := http.Get(\"http://example.net/resource\")\n        ...\n```\n\n### After\n\n```go\n\n import (\n         \"net/http\"\n         _ \"github.com/markdingo/cslb\"\n )\n\n func main() {\n        resp, err := http.Get(\"http://example.net/resource\")\n        ...\n```\n\nand that's it!\n\nOne line of import code and no changes to application code fetching HTTP resources. The package\ndocumentation describes what to do if your applications use its own `http.Transport`. Essentially\nyou have to enable `cslb` for that Transport.\n\n### SRV Resource Records\n\n`Cslb` processing is activated by the presence of SRV Resource Records (RRs) matching the requested\nhostname using the prescribed [RFC2782](https://tools.ietf.org/rfc/rfc2782.txt) formulation. If no\nSRV RR exists, `cslb` is completely transparent and passive. `Cslb` caches the presence or otherwise of\nSRVs to minimize its impact in a non-SRV environment. This means you can deploy with `cslb` at any\ntime and activate the functionality at a later stage.\n\n### Fail-Over and Load-Balancing Mechanism\n\n`Cslb` intercepts `DialContext` Requests made by `net/http` and makes internal `DialContext` Requests\nto the SRV targets. The first successful connection is returned to the calling application. In\neffect this provides a fail-over capability.\n\n`Cslb` achieves load-balancing by implementing the SRV selection algorithm which provides a lot of\nflexibility in terms of preferring targets by priority and distributing connections by weight within\npriority. The package documentation shows how this works.\n\n### No Server-side changes required\n\nNo server-side changes are required to use `cslb` - apart for possibly dispensing with your\nserver-side load-balancers! You can even use `cslb`-enabled applications on third-party services with\nappropriate DNS finagling. It's also possible to use `cslb` in conjunction with an existing\nserver-side load-balancer deployment by placing the load-balancers targets in an SRV RR.\n\n### Active Health Checks\n\nIn addition to the passive collection of fail-over data based on `DialContext` results, `cslb` has an\noptional \"active mode\" where a per-target health-check URL is periodically polled to determine the\nhealth of a target. If a health-check URL fails, that target is removed from the target candidate\nlist for a configured time period. The health-check URL is defined by a TXT RR in the DNS. The\npackage documentation describes the naming convention and syntax.\n\n### Status Web Page\n\nInsights into the behaviour of `cslb` within your application are available via an optional status\npage. When activated via an environment variable the web page provides statistics on intercepted\n`DialContext` Requests, information on cached SRV and healthcheck results.\n\n### Community\n\nIf you have any problems using `cslb` or suggestions on how it can do a better job, don't hesitate to\ncreate an [issue](https://github.com/markdingo/cslb/issues) or email the\n[authors](https://github.com/markdingo/cslb/blob/master/AUTHORS) directly. This package can only\nimprove with your feedback.\n\n### Copyright and License\n\nCslb is Copyright :copyright: 2019,2020,2021 Mark Delany. This software  is licensed under the BSD 2-Clause \"Simplified\" License.\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkdingo%2Fcslb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkdingo%2Fcslb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkdingo%2Fcslb/lists"}