v0.3.0 Latest release · Apache-2.0

Coordinate rate limits, counters and signals across your services.

One small server. A simple protocol. No client library required.

Ghoti is a single-binary, in-memory server. Configure up to 1,000 slots as rate limiters, leases, counters or broadcast channels, and reach them over plain-text TCP or HTTP with Server-Sent Events.

One Go binaryPlain-text protocolTCP · telnet · HTTP + SSEPrometheus metrics

Use cases

The coordination you'd otherwise build on Redis scripts or ZooKeeper.

Each one is a single slot. Every instance in the fleet talks to the same server, so they share one limit, one lease, one sequence, one channel.

Fleet-wide rate limiting

Twenty API instances, one upstream quota of 100 req/s. Each instance takes tokens from a shared bucket before it calls out, so the limit holds for the fleet instead of per process. tokens_per_req lets an instance take a batch and spend it locally, cutting the round trips.

token_bucketleaky_bucket

A read consumes tokens, so it isn't idempotent: don't retry it blindly.

Token bucket reference →

A lease for one active worker

The first connection to write the slot owns it. Everyone else gets e<slot>007 until the owner stops renewing for timeout seconds. That's leader election for a cron job, without running Raft.

timeout_memory

Owned by the TCP connection and held in memory, with no fencing token. A Ghoti restart drops the lease, so holders can overlap. Good for deduplicating work, not for guarding correctness.

Timeout memory reference →

Sequences without collisions

Every read is an atomic increment-and-get, so concurrent workers never draw the same number. Even with every connection hammering one counter, it benchmarks as fast as a plain read.

atomic

Volatile: the counter resets to 0 on restart. Monotonic for the life of the process, not unique forever.

Atomic counter reference →

Fan-out signals, all the way to the browser

Broadcast pushes a write to every open connection, with no subscription step. Multicast pushes only to connections that sent s. Over HTTP a broadcast slot is an SSE stream, so a browser tab can listen with a plain EventSource.

broadcastmulticast

At-most-once, no replay. The writer gets a received/sent/errors count and decides whether that's good enough.


How it works

Declare slots. Run one binary. Speak a line protocol.

No client library, no schema, no cluster to bootstrap. If your language can open a socket, it can use Ghoti.

  1. 1

    Map slots to primitives

    config.yaml assigns each slot number, 000 to 999, a kind and its options: a token bucket on 000, a lease on 001, a counter on 002. Clients know the map up front.

  2. 2

    ghoti run

    One Go binary, all state in memory, nothing written to disk. Optional per-slot ACLs, Prometheus metrics and an experimental leader-elected cluster mode.

  3. 3

    One command per line

    r000 reads, w001value writes, s/d subscribe and leave. Requests are at most 40 bytes and one is in flight per connection. Over HTTP it's GET/POST /001 plus SSE.


On the wire

The protocol fits on a napkin.

Two clients against the configuration on the left, replaying a session captured from ghoti run. One byte of command, three digits of slot, an optional value.

> sent< receivedr read · w writev value · e error · a async event
slot_000:            # rate limit
  kind: token_bucket
  bucket_size: 100
  period: second
  refresh_rate: 50
  tokens_per_req: 10
slot_001:            # lease
  kind: timeout_memory
  timeout: 10
slot_002:            # sequence
  kind: atomic
slot_003:            # fan-out
  kind: broadcast

000: A takes a batch of 10 tokens from the shared bucket.

001: A holds the lease. B is refused with 007 but can still read the holder.

002: A draws 1, B draws 2. No coordination between them.

003: B's write reaches both connections, B included. 2/2/0 is received/sent/errors.

nc localhost 9090

Client A

# take tokens
> r000
< v00010
# acquire the lease
> w001worker-a
< v001worker-a
# next sequence number
> r002
< v0021
# B's event lands first
> r003
< a003reload-config
< v003reload-config

Client B

# lease is held
> w001worker-b
< e001007
> r001
< v001worker-a
> r002
< v0022
# fan out
> w003reload-config
< a003reload-config
< v0032/2/0
Tutorial Walk through coordination with two clients Build leader election on a lease slot with two nc sessions, then see exactly where the approach stops being safe.

Benchmarks

Measured on a 2 vCPU, 1 GiB box.

Ghoti v0.3.0 ran alone on an AWS t4g.micro, with load from a c7g.xlarge in the same availability zone and one request in flight per connection. Every response was verified, and you can reproduce the run with ghoti-bench.

134k req/s

100 connections

Memory reads at 0.60 ms p50, with 82% of two cores busy.

0.29 ms

p50 round trip

1 connection, network included. p99.9 under 0.75 ms in every tested scenario.

7.6 µs

Mean time in the server

Per memory read, across 247M requests. The rest is network and kernel.

0 errors

255M requests, 21 runs

Counters matched every increment; buckets never over-issued.

For scale: the box under test

2 vCPU

Graviton2, burstable

Fewer cores than a typical laptop.

1 GiB

RAM

Less memory than most phones.

t4g.micro

Second-smallest t4g size

The kind of instance you'd give a sidecar, not a datastore.


Run it in a minute.

Install with Go, declare one counter, start the server, then read the counter from a second terminal. Each read increments it.

$ go install github.com/dankomiocevic/ghoti/cmd/ghoti@latest
$ printf 'slot_000:\n  kind: atomic\n' > config.yaml
$ ghoti run

Then, in a second terminal, nc localhost 9090:

> r000
< v0001
> r000
< v0002