Weaver shards HTTP traffic by field, not by round robin

A proxy whose job is placement, not balancing

Weaver is described as a Layer-7 Load Balancer with Dynamic Sharding Strategies, and as a modern HTTP reverse proxy with advanced features. The name suggests one thing and the documentation says another, and the difference matters more than the marketing does. The README carries a note that quotes the saying that all load balancers are proxies but not every proxy is a load balancer, and then states that weaver currently does not support load balancing. So the accurate description is a router with a control plane. Its function is to decide which backend receives a particular request, based on a property of that request, and to be able to change those decisions while it is running. The feature list makes the mechanism concrete: sharding requests based on headers, path or body fields, support for multiple algorithms for sharding requests including consistent hashing, modulo and s2, dynamic configuration of different routes with no restarts, metrics emitted on requests per route per backend, a single self contained binary, and logging on failures as observability. If you came looking for a backend that will spread load evenly, this is the wrong tool.

Five sharding strategies and what each one keys on

The strategy list is the substance of the project. Consistent hashing is listed first and the module list backs it, since the dependencies include github.com/gojekfarm/hashring at a 2018 commit, a Go port of the hashring library. The point of a hashring is that a key keeps mapping to the same backend as the backend set grows and shrinks, so that adding a node does not move most of your keys. Simple lookup based is a straightforward map from a value to a backend. Modulo is the arithmetic version, hashing the value and taking it against the number of backends, which is fast and has the drawback that removing a backend remaps a large share of the traffic. Prefix lookup routes on a prefix of the value, which suits hierarchical identifiers such as a tenant path. S2 based is the non cryptographic consistent hashing variant, and the golang/geo dependency in the module list is there for the S2 geometry used by it. Choosing between them is mostly a question of whether the shard key is stable, how many keys there are and whether a topology change would reshuffle traffic.

etcd is the control plane, and that is what makes it dynamic

The architecture section is one sentence and it explains the design. Weaver uses etcd as a control plane to match incoming requests against a particular route config and shard the traffic to different backends based on some sharding strategy. The routes are configured through a document the README calls an ACL, and different routes can match different paths with different sharding strategies. The consequences of putting etcd in the path are worth spelling out. A route change is a write to etcd rather than a config file edit plus a restart, which is the feature the README calls dynamic configuring of different routes with no restarts. It also means etcd is a hard dependency at runtime, not just at build time, and a proxy that cannot reach its control plane has no route table. The module list shows the etcd client in use, github.com/coreos/etcd at 3.3.0, and the repository has a top level etcd/ directory of its own code alongside the client dependency. The compose file in the repository runs a dev_etcd service from quay.io/coreos/etcd:v2.3.8, which is a different major line from the client, and that mismatch is the kind of thing to check when the containerised development path does not behave the way a managed cluster does.

Building it and running it locally

The installation section is two steps. You clone the repository:

git clone [email protected]:gojektech/weaver.git

and you build to create the weaver binary:

make build

Prebuilt binaries for various architectures are offered from the releases page instead. The Makefile shows what the build actually does, since the build target chains deps, compile, fmt, vet and lint. The deps target runs go mod tidy, the compile target builds ./cmd/weaver into out/weaver with linker flags stamping the build date and the commit hash and stripping the binary, and the fmt, vet and lint targets run the corresponding Go tools, with the lint target using golint and failing the build on anything other than the missing comment warnings it filters out. The test target depends on copy-config, which copies weaver.conf.yaml.sample to weaver.conf.yaml, because the tests expect a config file to exist. The compose file brings up three services for local work, dev_statsd, dev_etcd and dev_weaver, with the proxy configured through environment variables for the statsd port and host and the etcd endpoints.

The container image and the Go version it froze on

The Dockerfile is worth a look because it shows how old this project is. The builder stage is FROM golang:1.11.5-alpine with GO111MODULE on, which predates the module mode becoming the default. It installs gcc, g++, make, ca-certificates and git, creates /weaver, adds go.mod and go.sum and runs go mod download, then a second stage based on it runs make setup and make build, and the final image is alpine:latest with the binary copied in from /weaver/out/weaver-server to /usr/local/bin/weaver and an ENTRYPOINT of weaver start. The Go 1.11 base and the GO111MODULE environment variable are the clearest evidence of the project's age, and the module dependency list matches it, with versions from 2018 and 2019 including jwt-go, the raven-go client and the New Relic agent at 1.11.0. The only tagged release is v0.0.1 from February 2019, the last push was on 2026-09-26, and the repository is not archived, so the code is being touched without new versioned releases.

Repository layout and the Kubernetes deployment path

The top level of the repository is organised around the four concepts the README names. acl.go with its test file covers the route configuration, sharder.go covers the sharding strategies, backend.go covers the upstream targets, and endpoint.go covers the routing surface, with the server/ directory holding the proxy itself and cmd/ holding the command, the latter being where the weaver start entry point comes from. There are also internal/ and pkg/ directories, an etcd/ directory, a config/ directory and a deployment/ directory. The deployment story is Kubernetes only, with the README pointing at the deployment/weaver documentation and at the examples/body_lookup directory for a worked example of deploying to Kubernetes and using ACLs. The examples directory and the docs directory together are the place to start, and the ACL details are documented separately in docs/weaver_acls.md. That is a modest documentation footprint for a proxy whose behaviour depends on how you write its route config, so reading both files is worth doing before you write the first one.

Editorial conclusion

Adopt Weaver when you need to route HTTP requests to a specific backend based on something in the request itself, a tenant identifier, a body field, a header, and you want that routing to change without restarting the proxy. Do not adopt it as a load balancer, because the README states plainly that it does not support load balancing. Verify first that the field you want to shard on is present on every request you intend to route, since a request without that field has no defined placement, that etcd is reachable and that its version matches the client the build expects, and that you read the ACL documentation before writing your first route config.

Frequently asked questions

Official sources

1. gojek/weaver on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases