{"id":18151271,"url":"https://github.com/msantos/runhash-go","last_synced_at":"2025-09-08T00:44:05.099Z","repository":{"id":136621502,"uuid":"351751867","full_name":"msantos/runhash-go","owner":"msantos","description":"runhash: command line interface for distributed node selection","archived":false,"fork":false,"pushed_at":"2023-12-19T12:34:11.000Z","size":30,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2023-12-19T15:09:11.777Z","etag":null,"topics":["load-balancing","rendezvous-hash"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/msantos.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}},"created_at":"2021-03-26T10:59:24.000Z","updated_at":"2023-12-19T15:09:19.120Z","dependencies_parsed_at":"2023-12-19T15:09:12.345Z","dependency_job_id":null,"html_url":"https://github.com/msantos/runhash-go","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"purl":"pkg:github/msantos/runhash-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msantos%2Frunhash-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msantos%2Frunhash-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msantos%2Frunhash-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msantos%2Frunhash-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msantos","download_url":"https://codeload.github.com/msantos/runhash-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msantos%2Frunhash-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274117522,"owners_count":25225104,"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-09-07T02:00:09.463Z","response_time":67,"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":["load-balancing","rendezvous-hash"],"created_at":"2024-11-02T01:07:09.780Z","updated_at":"2025-09-08T00:44:05.072Z","avatar_url":"https://github.com/msantos.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SYNOPSIS\n\nrunhash *options* *subcommand* [*key* [*...*]]\n\n# DESCRIPTION\n\nrunhash: command line interface for distributed node selection\n\n`runhash` uses [Rendezvous or highest random weight\nhashing](http://www.eecs.umich.edu/techreports/cse/96/CSE-TR-316-96.pdf)\nto deterministically choose one or more nodes from a pool of nodes:\n\n\u003e Rendezvous or highest random weight (HRW) hashing is\n\u003e an algorithm that allows clients to achieve distributed\n\u003e agreement on a set of `k` options out of a possible set of\n\u003e `n` options. A typical application is when clients need\n\u003e to agree on which sites (or proxies) objects are assigned\n\u003e to. ([Wikipedia](https://en.wikipedia.org/wiki/Rendezvous_hashing))\n\n`runhash` deterministically chooses:\n\n* a node from a group of nodes to run a command\n\n* a node or nodes to use for a service\n\n## SUBCOMMANDS\n\n### sort\n\nSelect one or more nodes from a list of nodes. Nodes are read:\n\n* as command line arguments\n* space delimited nodes from the RUNHASH_NODES environment variable\n* from stdin if '-' is provided as the argument\n\n#### Example\n\n```\nrunhash sort mykey 127.0.0.1 192.168.1.1 10.0.0.1\n\nRUNHASH_NODES=\"127.0.0.1 192.168.1.1 10.0.0.1\" runhash sort mykey\n\necho -e \"127.0.0.1\\n192.168.1.1\\n10.0.0.1\" | runhash sort mykey -\n```\n\n### exec\n\nExecute a command on a subset of nodes chosen from the list of nodes\nbased on the key. The number of nodes chosen is set by the `-n` option.\n\nThe command will always run on this node if either:\n* RUNHASH_NODES is empty\n* the node is included in `RUNHASH_NODES` and `-n` is 0 (all nodes)\n\n#### Example\n\n```\nRUNHASH_NODES=\"$(uname -n) foo bar\" runhash -n 1 exec mykey ls -al\n```\n\n### xargs\n\nFailover a command between a sorted list of nodes. The command is executed\nsequentially on the sorted list of nodes. If the command exits non-0,\nthe command is run again with the next node in the list.\n\n'{}' in the command arguments is replaced with the selected node.\n\n#### Example\n\n```\nRUNHASH_NODES=\"127.0.0.1 127.1.1.1\" runhash xargs mykey nc \"{}\" 443\n\n# set an environment variable for a command\nRUNHASH_NODES=\"127.0.0.1 127.1.1.1\" runhash xargs mykey \\\n  env TEST_VARIABLE=\"{}\" env\n```\n\n# Build\n\n```\ngo install codeberg.org/msantos/runhash-go/cmd/runhash@latest\n```\n\nTo build a reproducible executable from the git repository:\n\n```\nCGO_ENABLED=0 go build -trimpath -ldflags \"-w\" ./cmd/runhash\n\n# to include the version number\nmake\n```\n\n# OPTIONS\n\nn *int*\n: number of nodes to return. Set to `0` to return all nodes.\n\nnode *string*\n: overrides `RUNHASH_NODE` environment variable\n\nnodes *string*\n: overrides `RUNHASH_NODES` environment variable\n\nsorted *true|false*\n: use the existing sort order for nodes, provided in the environment or\ncommand line (default false)\n\n## xargs\n\nokexit *true|false*\n: The \"--okexit\" option is the opposite of bash's \"set -o errexit\": `xargs`\nterminates if the command exits with status 0.\n\nIf \"--okexit=false\", xargs will run the command on all nodes in\nthe list.\n\nreplace *string*\n: template string (default \"{}\")\n\n# ENVIRONMENT VARIABLES\n\nRUNHASH_NODE=\"*hostname*\"\n: Tag used to identify this node in the node list. Usually this will be\nset to the hostname or an IP address. Defaults to `uname -n`.\n\nRUNHASH_NODES=\"\"\n: Pool of nodes to choose from.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsantos%2Frunhash-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsantos%2Frunhash-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsantos%2Frunhash-go/lists"}