Overview
Ghoti is a single-binary, in-memory server for small pieces of shared state that a fleet of services needs to agree on: a rate limit, a lease, a counter, a signal.
e response means.
What Ghoti is#
A Ghoti server exposes 1000 numbered slots, 000 to 999. You decide in config.yaml which slots exist and what kind each one is. Clients read and write slots with a plain-text protocol over TCP, or over HTTP. Each slot kind has a fixed behaviour:
| Kind | What it does | Status |
|---|---|---|
simple_memory | Holds a value of up to 36 bytes. | Implemented |
timeout_memory | A value with an owner: only the connection that last wrote it can write again, until the owner's timeout expires. | Implemented |
token_bucket | Hands out tokens refilled every period. | Implemented |
leaky_bucket | Accepts a request if the bucket has room, leaking one token every refresh_rate ms. | Implemented |
ticker | An integer that counts down by one every refresh_rate ms until it reaches zero. | Implemented |
atomic | A counter that increments on every read. | Implemented |
broadcast | A write is pushed to every connected client. | Implemented |
multicast | A write is pushed to the clients that subscribed to the slot. | Implemented |
| Random signal propagation | A write delivered to one subscriber chosen at random. | Planned |
Around the slots Ghoti has:
- Three transports:
standardTCP (the default),telnet, andhttpwith Server-Sent Events for broadcast slots. See Transports. - Optional users with per-slot read and write permissions. See Authentication.
- An optional Prometheus endpoint and a connection cap. See Operations.
- Leader election between several nodes, without replication. Experimental See Cluster.
What Ghoti is not#
- Not a database or a durable store. Nothing is written to disk. A restart empties every slot, and a newly elected cluster leader starts empty.
- Not a message queue. Broadcast and multicast deliver at most once, with no retries and no backlog for clients that were not connected.
- Not encrypted. No listener supports TLS, and the
plogin command sends the password in cleartext. Terminate TLS in a load balancer or reverse proxy, or keep traffic on a trusted network. See SECURITY.md. - Not a consensus system. Clustering elects a leader with the bully algorithm. There is no quorum and no replication, and split-brain is possible under network partitions.
Guarantees at a glance#
| Topic | What Ghoti does |
|---|---|
| Durability | None. All state is in memory and is lost on restart. |
| Ordering on one connection | Responses come back in the order the commands were sent. Async events never appear in the middle of a response. |
| Ordering across connections | No guarantee. |
| Requests in flight | One per connection. Send a command, wait for its response, then send the next. |
| Event delivery | At most once. One attempt per client and no retries. The writer receives a received/sent/errors summary. |
| Lease ownership | Tied to the TCP connection. It survives a dropped connection until the timeout expires and is forgotten on restart. |
| Values | Opaque byte strings of at most 36 bytes, returned exactly as written. |
| Transport security | None built in. Bring your own TLS termination. |
| High availability | Experimental Leader election only. Followers answer NOT_LEADER and do not redirect. |
Performance#
On a 2-core, 1 GiB AWS t4g.micro, Ghoti v0.3.0 answered with a 0.29 ms median round trip on one connection, served over 127,000 requests per second with 100 connections, and spent 7.6 µs on average inside the server per memory read. See Benchmarks for the method, every result and how to reproduce them.
When it fits#
Ghoti fits state that is cheap to lose and expensive to coordinate: a fleet-wide rate limit, a lease that picks one active worker, a counter for distinct numbers, or a push signal such as "reload the configuration". If the overall system must keep working when Ghoti is down, possibly degraded, Ghoti is a good fit. If losing the data is not acceptable, use a durable store instead.
Frequently asked questions#
Does Ghoti persist data?#
No. All state is in memory and nothing is written to disk. A restart empties every slot, and a newly elected cluster leader starts empty. Use Ghoti for state that is cheap to lose and expensive to coordinate.
Is Ghoti a replacement for Redis?#
Not as a general-purpose store. Ghoti has a fixed set of slot kinds, values of at most 36 bytes, no persistence and no data structures to query. It covers coordination primitives (rate limits, leases, counters and fan-out signals) with a one-line text protocol and a single binary.
Does Ghoti support TLS?#
No. No listener implements TLS, and the login password and HTTP Basic Auth credentials travel in cleartext. Terminate TLS in a load balancer or reverse proxy in front of Ghoti, or keep the traffic on a trusted network.
What happens to a lease when the client disconnects or the server restarts?#
A lease on a timeout_memory slot belongs to the TCP connection. If the client disconnects, the lease stays held until its timeout expires, and a reconnecting client is a new owner that gets error 007 until then. If Ghoti restarts, the lease is forgotten and the first connection to write takes it, so two clients can briefly both believe they hold it.
Are broadcast and multicast messages guaranteed to arrive?#
No. Delivery is at most once: one attempt per client, no retries and no replay for clients that were not connected. The writer receives a received/sent/errors count for each message.
Which languages and clients can use Ghoti?#
Any language that can open a TCP socket and send a line of text. There is no client library to install. Over the HTTP transport, slots are read and written with GET and POST, and browsers can receive broadcast events with Server-Sent Events. For manual testing, nc is enough.
How fast is Ghoti?#
In the v0.3.0 benchmark on a 2-vCPU, 1-GiB AWS t4g.micro, Ghoti served 134,343 memory reads per second at a 0.60 ms median round trip with 100 connections, and answered in 0.29 ms at the median with one connection, network included. The method and every result are on the Benchmarks page.
Can Ghoti run as a cluster?#
Experimentally. Nodes elect a leader with the bully algorithm, but there is no replication and no quorum, and split-brain is possible under network partitions. Followers answer with a NOT_LEADER error naming the leader instead of redirecting the client.
How many slots are there, and how large can values be?#
There are 1,000 slots, numbered 000 to 999, each defined in config.yaml. A value is an opaque byte string of at most 36 bytes, and a request is 4 to 40 bytes long.