Glossary

198 terms from System Design Basics in Go, in plain words, each with the chapter that teaches it.

Search the glossary

A

ACID (atomicity, consistency, isolation, durability): The four promises a database transaction makes: all of it happens or none of it, the rules still hold, transactions running at once don't see each other's half-done work, and committed changes survive a crash. They are why Kettle & Crane keeps orders and stock in a relational database.
alerts: Automatic messages to a person when a metric crosses a line, such as an error rate above 1% for 5 minutes.
API (application programming interface): The set of requests a program accepts from other programs, such as api.kettleandcrane.com's product and order endpoints.
API key: A long secret string a caller sends, usually in a header, to prove who it is.
asynchronous work: Work done a moment later by something else, so the customer's request doesn't wait for it. Sending the confirmation email after checkout is an example.
at-least-once delivery: A promise from most message brokers that every message arrives, but some may arrive twice, for example if a worker crashes before confirming. Consumers must therefore cope with duplicates.
atomic: A single step that can't be split, so nothing can happen between the check and the change. Reserving the last bag of coffee atomically stops two checkouts from both succeeding.
authentication: Proving who the caller is, usually with a token or API key. A failure gives a 401 response.
authorization: Deciding what a known caller is allowed to do, such as customers reading only their own orders. A failure gives a 403 response.
auto-increment ID: A number the database hands out in order (1, 2, 3...) for each new row. The shortener writes it in base62 to make a short code.
autoscaling: Automatically adding servers when load rises and removing them when it falls, following a rule such as keeping average CPU under 60%.
availability: The share of time a system answers requests, as a percentage such as 99.9%. It is one of the main non-functional requirements.

B

back pressure: Pushing back on producers when a queue is full so it can't grow without limit. A send to a full Go channel simply waits, which slows the producer to the workers' pace.
back-of-the-envelope estimate: A rough calculation, good enough to find the order of magnitude of requests per second or storage, so you don't over-build or under-build.
backups: Copies of data kept in a separate place so it can be restored after a disaster, such as a lost disk or a deleted database. A backup is only trustworthy once you have tested it by actually restoring one.
base62: Writing numbers with 62 symbols (0-9, a-z, A-Z) instead of 10 digits, so numbers become short strings. The URL shortener uses it to turn link IDs into short codes.
batching: Grouping many writes into one, such as a single commit or sync after many inserts, so the slow step happens once instead of once per row.
body: The data part of an HTTP request or response, after the headers and a blank line, such as a new order's JSON.
broker: The program that stores a message queue and hands messages to workers. Common brokers are RabbitMQ and Amazon SQS (a managed service from Amazon).
bufio.Writer: A Go writer that collects text in memory and writes it out when you call `Flush()`, used to batch writes to a file.

C

cache: A small, fast store holding copies of data that is slow to fetch, like a product page read thousands of times between price changes.
cache hit / cache miss: A hit means the data was found in the cache; a miss means it wasn't, so it must be fetched from the slow source such as the database.
cache invalidation: Removing or updating a cached copy when the underlying data changes. At Kettle & Crane, changing a price writes to the database and then deletes the cached key.
cache stampede: When a hot cache key expires and all requests miss at once, flooding the database. The fix is to let one request reload it while others wait.
cache-aside: A pattern where the app checks the cache first and, on a miss, reads the database and stores the result in the cache for next time.
Cache-Control header: An HTTP header telling browsers and CDNs how long to keep a file. `Cache-Control: max-age=86400` means keep it for a day.
CAP theorem: During a network partition, a system must choose between consistency (refuse rather than be wrong) and availability (answer, maybe with stale data). Designs choose per feature.
CDN (content delivery network): Servers in many cities that hold copies of files, so a customer in Miami gets product photos from nearby instead of from Portland.
celebrity problem: When a source with a huge number of followers makes fan-out on write too slow, because each post needs a write per follower.
channel: A Go type that goroutines use to pass values safely. A buffered channel works as a queue that holds a fixed number of messages.
circuit breaker: A guard that notices repeated failures of a service and stops calling it for a while. It is closed while calls go through, open when it refuses calls, and half-open when it allows trial calls again.
client: A program that asks for something, such as a browser or the Go `http.Client` program you write. The server is what answers.
commit: Saving a transaction's changes for good. Real databases wait until the data is safely on disk before a commit finishes.
component: One part of a system, such as a web server, database, cache or queue. System design is deciding the components and how they talk.
consensus: The problem of getting several servers to agree on one value, such as which replica is the new primary. It is solved by protocols that let a group reach the same decision even when some servers or network links fail.
consistency: Whether all readers see the latest data. It is traded against availability and speed, and chosen per feature.
consistent hashing: A sharding method that moves only a small share of keys when shards are added. Going from four to five shards with plain `%` moves 795 of 1,000 customers, but consistent hashing moves about 200.
container/list: Go's linked-list package, used in the LRU cache. `PushFront`, `MoveToFront`, `Back` and `Remove` keep entries ordered from newest to oldest.
Content-Type: An HTTP header saying what kind of data the body holds, such as `application/json`.
context: A Go value that can carry a deadline and cancel a request that takes too long. It is mentioned as a per-request alternative to the client timeout.
conversation ID: The identifier of one support-chat conversation, used as the key under which its messages are stored.
crc32.ChecksumIEEE: A Go function that turns bytes into a large whole number the same way every time on every machine. It is a stable hash suited to choosing shards.
cross-shard query: A question that doesn't include the shard key, so it must ask every shard and combine the answers, like finding this week's best sellers.
curl: A command-line tool that sends HTTP requests, used here to test the API, such as `curl localhost:8121/v1/health`.

D

data center: A building full of servers. A round trip inside one takes about 0.5 ms, compared with 70 ms from Portland to Virginia.
database: A program that stores data safely and finds it again, such as PostgreSQL or SQLite. Databases are either relational (tables and SQL) or NoSQL.
dead-letter queue: A separate queue where messages go after failing too many times, so a person such as Priya can look at them instead of the message retrying forever.
defer: A Go keyword that runs a call when the surrounding function returns, however it returns. It is used to unlock mutexes and close files.
denormalization: Storing a copy of data in the shape a page needs, even though it repeats data held elsewhere, to make reads cheap. Kettle & Crane's `best_sellers` table is an example.
design document: A short shared write-up of what you'll build and why, reviewed by the team before anyone writes code.
DNS (Domain Name System): The internet's phone book. It turns a name like shop.kettleandcrane.com into an IP address.
document store: A NoSQL database that holds JSON-like documents, good for products with varied fields. MongoDB is an example.
downtime: The time a system isn't answering. At 99.9% availability that is about 8.76 hours a year.
durability: The guarantee that saved data is never lost, even after a crash. It is one of the main non-functional requirements and the D in ACID.

E

edge location: A CDN server in one of many cities, close to customers, that holds copies of files.
endpoint: One method-and-path pair an API accepts, such as `GET /v1/products`.
error rate: The share of requests that fail. A metric commonly used for alerts.
error wrapping (%w): Adding context to an error with `fmt.Errorf` and `%w` while keeping the original inside, so `errors.Is` can still find it.
errors.As: A Go function that checks whether an error, or one it wraps, has a given type, and fills a variable with it. It is used for `net.Error` and `OutOfStockError`.
errors.Is: A Go function that checks whether an error, or one it wraps, is a particular sentinel error such as `ErrConnection`.
eventual consistency: Reads may be briefly out of date, but once writes stop every copy catches up, as with read replicas. It is fine for product pages.
eviction: Throwing entries out of a full cache to make room for new ones.
EXPLAIN: A PostgreSQL command that prints the plan for a query, showing whether the database scans every row or uses an index.
exponential backoff: Doubling the wait after each failed retry (0.1 s, 0.2 s, 0.4 s...), so a struggling server has room to recover.

F

failover: Switching to a standby when the main part fails, such as promoting a replica to primary or a spare load balancer taking over an address.
fake clock: A clock function a test swaps in and moves by hand, so tests of expiry don't have to wait real time.
fallback: A simpler answer shown when a part fails, such as a cached "Popular this week" list when recommendations are down.
fan-out: Copying one post or message to many readers, like a café's post going to all its followers' feeds.
fan-out on write / fan-out on read: On write, a post is pushed into every follower's feed when it is posted, so reads are fast. On read, posts are stored once and gathered when the feed is opened, so posting is cheap.
feed: A list of posts from the cafés a customer follows, newest first.
five-step design method: The same five steps for every design: requirements, estimates, API, data, then a sketch and the one hard part. Write each down, even as a few lines on a whiteboard.
fsync (File.Sync): Asking the operating system to push a file's data onto the physical disk and wait. It is the slow step that batching reduces.
functional requirement: A statement of what the system does, such as "customers can check out" or "Priya can look up an order by its ID".

G

go run / go test: `go run file.go` compiles and runs a Go file; `go test` runs the tests in `_test.go` files.
go vet: A Go command that looks for likely mistakes in code.
gofmt: The Go tool that checks and fixes code layout. `gofmt -l .` prints nothing when the layout is right.
goroutine: A lightweight concurrent function in Go, started with `go`. Go runs every HTTP request in its own goroutine, and the email worker is another.
graceful degradation: Offering less instead of nothing when a part fails, such as showing cached lists when recommendations are down.

H

handler: A Go function called once per matching HTTP request, such as `getProduct`.
hash sharding: Choosing a shard by taking a stable hash of the key and the remainder after dividing by the shard count. It spreads rows evenly.
headers: Lines of `Name: value` in an HTTP request or response that carry extra information, such as Content-Type or a token.
health check: A regular test, such as `GET /v1/health` every few seconds, that a server is answering. A server that fails is marked down and gets no requests.
hit ratio: Cache hits divided by all lookups. A ratio of 0.9 means one lookup in ten reaches the database.
horizontal scaling: Adding more machines to share the work. It has no ceiling but the data or requests must be split between them.
hot key: One key, such as a café with hundreds of orders a week, that makes its shard busier than the rest.
hot spot: A shard or key that gets far more traffic than the rest, such as the newest shard when sharding by date.
HTTP (HyperText Transfer Protocol): The plain-text protocol browsers and servers use: a request goes out with a method, path and headers, and a response comes back with a status code.
HTTP method: The first word of an HTTP request, saying what to do: `GET` reads, `POST` creates, `PUT` replaces and `DELETE` removes.
HTTP status codes: The three-digit number that starts an HTTP response: 2xx means success, 4xx the client's mistake, 5xx the server's problem. Common ones are 200 OK, 201 Created (order placed), 301 Moved for good, 302 Moved for now, 400 Bad Request (invalid input), 401 Unauthorized (missing or wrong token), 403 Forbidden (known caller, not allowed), 404 Not Found (unknown SKU), 409 Conflict (clashes with current state), 429 Too Many Requests, 500 Internal Server Error (a bug) and 503 Service Unavailable (can't answer now).
HTTPS: HTTP encrypted with TLS, so nobody in between can read card numbers or tokens.
httptest.NewServer: A Go helper that starts a real local server for demos and tests, used to fake a slow service.
hybrid fan-out: Fanning out on write for ordinary cafés but fetching very popular cafés' posts at read time and merging them in.

I

idempotency key: A unique ID the app sends in an `Idempotency-Key` header so the server can recognise a retried request and return the first result instead of charging twice.
idempotent: Doing something twice has the same effect as doing it once. `GET`, `PUT` and `DELETE` are idempotent; a plain `POST` that creates an order is not.
idempotent consumer: A queue worker for which handling a message twice has the same effect as once, usually by recording which messages are done and skipping repeats.
index: A sorted list of one column's values pointing at their rows, like a book's index, so the database can jump to rows instead of scanning the whole table. It costs a little on each write.
IP address: A number such as 203.0.113.7 that identifies a machine on the network.

J

jitter: Randomness added to retry waits so thousands of clients don't all retry at the same instant.
join: A relational database query that combines rows from several tables.
JSON: A text format for data made of keys and values, such as `{"name":"Speckled blue mug","price":18}`. It is the usual format for the bodies of web API requests and responses.

K

Kafka: A popular message broker built around topics, used for event streaming.
key-value store: A NoSQL database with one value per key, like a Go map, good for sessions and carts. Redis and DynamoDB are examples.

L

latency: How long one request takes. It is a non-functional requirement measured in milliseconds or smaller units.
Layer 4 / Layer 7: A Layer 4 balancer looks only at addresses and ports and passes bytes on unread, so it is very fast. A Layer 7 balancer reads the HTTP request, so it can route by path and handle HTTPS.
least connections: A balancing rule that sends each request to the server with the fewest requests still open, which handles requests of unequal cost better than round robin.
load balancer: A server in front of the app servers that takes every request and passes it to one of them. Customers only see its address.
logs: Records of events, such as each failed charge, used for monitoring.
LRU (least recently used): An eviction rule that throws out the entry that hasn't been read or written for the longest time when the cache is full.

M

message: A small unit of work placed on a queue, such as an order ID for the email worker.
message queue: Holds messages from producers until consumers take them, so slow work happens later without delaying the reply.
metrics: Numbers measured over time, such as the error rate or latency percentiles.
microservices: A style of building a system as many small programs that talk to each other over APIs. It contrasts with a monolith, where all features live in one program.
monitoring: Watching what a system is doing through logs, metrics and alerts.
monolith: One program that holds all of a system's features. It is simple to build and run, which suits a small team like Kettle & Crane's.
mutex: A lock in Go: `Lock()` waits until nobody else holds it and `Unlock()` frees it, so one goroutine at a time runs the code in between. It protects shared maps and makes a check-and-change atomic.

N

net/http: Go's standard-library package for writing HTTP servers and clients. It runs a JSON API with `http.ListenAndServe` and a route multiplexer, and calls APIs with `http.Client`.
network partition: A failure where some servers can't reach others, such as replicas losing contact with the primary.
nginx / HAProxy: Two common load balancers that you run yourself. nginx is also a web server.
nines: A way of describing availability by the number of 9s: 99.9% is "three nines". Each extra nine cuts allowed downtime by ten and costs much more.
non-functional requirement: A statement of how well the system does its job: latency, availability, durability and scalability.
NoSQL: Databases that give up some of the relational model for simplicity and very large scale, such as key-value, document and wide-column stores.

O

object storage: A service that stores any number of files by name, cheaply and durably. Amazon S3 is the best-known; the CDN fetches Kettle & Crane's photos from it.
order of magnitude: The rough size of a number by powers of ten, such as whether traffic is 2, 200 or 20,000 requests per second. Each calls for a very different design.
outbox: A queue of work to do once an order is safely saved, such as sending its email. In the prototype it is a buffered channel of order IDs.

P

p99: The latency that 99% of requests beat; the slowest 1% take longer. An average of 80 ms can hide a p99 of 3 seconds.
pagination: Returning a long list a page at a time, with `?page=2` or `?after=K-1040`.
peak factor: How many times the average load the busiest moment reaches. For the shop's holiday sale hour it is about 10.
polling: Asking again and again whether anything is new, such as a chat browser asking every few seconds. It is simple but wasteful.
port: A numbered door on a machine that lets one machine run many network services at once. For example, 443 is used for secure web traffic and 8121 for a local demo server.
PostgreSQL / MySQL / SQLite: Relational databases. PostgreSQL and MySQL are full servers that handle indexes, replication and locking for you; SQLite is a small one.
precompute: Calculating a heavy result ahead of time and storing it for fast reads, like a job saving the top ten best sellers every 10 minutes.
presence: Whether someone is online. The chat design sets a key with a short TTL that expires when the person disconnects.
primary: The database copy that takes every write and sends changes on to the read replicas.
producer / consumer: The producer is the code that puts messages on a queue, such as checkout. The consumer is the worker that takes them off.
pub/sub (publish/subscribe): A pattern where one message is published to a topic and a copy goes to every subscriber, unlike a queue where one consumer gets each message.

R

race condition: A bug where the result depends on how two operations overlap in time, such as two checkouts both selling the last bag.
range sharding: Giving each shard a range of keys, such as months of the year. A query for one range hits one shard, but new data can create a hot spot.
rate limiting: Capping how many requests each client may make in a given time. It protects a service from being overwhelmed by a runaway script or abusive caller.
read replica: A copy of the database that receives the primary's changes and answers reads, so several servers can share the read load.
read-heavy / write-heavy: A read-heavy system is read far more than it's changed, like the shop at about 100 reads per order. A write-heavy one is the reverse. The ratio tells you which side to scale first.
read-your-writes: A promise that a user always sees their own latest changes, for example by reading their data from the primary for a short time after they write.
redirect: A response with status 301 or 302 that tells the browser to go to another address, given in the `Location` header. 301 is permanent and browsers remember it; 302 is temporary, so every click still reaches your server.
Redis / Memcached: Shared cache servers that app servers can use. Redis is also a key-value store, used for sessions and carts.
redundancy: Having two or more of each critical part, so one failure doesn't stop everything.
relational database: A database with tables of fixed columns that you query with SQL and can combine in one query. It is the default for orders, stock and money.
replication: Keeping copies of a database on several servers. The primary takes writes and the replicas receive each change.
replication lag: The delay before a replica has a change made on the primary. It is usually milliseconds, but a read right after a write may return the old value.
requirement: Something the system must do or be. Requirements are functional or non-functional.
resharding: Moving rows to new shards when you add or remove shards. With `% shard_count` most keys move, which is costly.
resource: A thing an API names with a noun in the URL, such as `orders`. The HTTP method says what to do with it.
REST: A common API style where URLs name resources (nouns like `orders`) and the HTTP method says what to do with them.
retry: Trying a failed call again, which helps with brief failures. It should be done only for idempotent work, with backoff and jitter.
rollback: Undoing a transaction's earlier changes when a later step fails, such as returning reserved mugs when the coffee is out of stock.
round robin: Giving requests to servers in turn: app1, app2, app3, then app1 again.
round trip: A request going to another machine and its reply coming back. A round trip takes about 0.5 ms inside one data center and about 70 ms from Portland to Virginia.
RPS (requests per second): How many requests arrive each second. Average RPS is daily requests divided by 86,400; peak RPS is that times the peak factor.

S

scalability: The ability to keep working as the load grows. It is one of the main non-functional requirements.
scan: The database reading every row of a table to answer a query, which is slow when the table is large.
select (with default): A Go statement that picks among channel operations. A `default` case makes a send happen only if there is room, otherwise it runs at once.
sentinel error: A named error value, such as `ErrConnection`, that code compares against with `errors.Is`.
ServeMux: Go's request router that matches method and path patterns, like `GET /v1/products/{sku}`, to handler functions.
server: A program, or the machine running it, that answers requests from clients, such as the shop's app server or database server.
session: What a server knows about one visitor, such as who is logged in and what's in their cart.
shard: One piece of a table that has been split across several databases.
shard key: The column that decides which shard a row lives on. For orders, `customer_id` keeps one customer's orders on a single shard.
sharding: Splitting one table's rows across several databases, each holding a shard. It scales writes but brings hot keys, cross-shard queries and resharding costs, so only do it when you must.
short code: The few symbols after the slash in a short link, such as `abc12` in `go.kettleandcrane.com/abc12`.
SKU (stock keeping unit): A product's code, such as `MUG-BLUE`, used as the key for products and stock.
SLO (service level objective): A team's target for a service, such as "checkout is available 99.9% of the time".
SPOF (single point of failure): One part whose failure stops everything, such as a lone database. The cure is redundancy.
SQL: The language used to ask a relational database questions and change its data.
stable hash: A hash that gives the same number for the same key on every machine and every run. Go's random-seeded map hashing is not stable, so sharding with it would move customers after a restart.
stale: Cached or replica data that no longer matches the source of truth, like an old price.
stateless server: A server that keeps no session data in its own memory but in a database or cache, so any server can answer any request and adding servers is easy.
sticky session: A load balancer rule that sends one user to the same server every time because that server holds their cart in memory. If it dies the cart is lost.
strong consistency: Every read sees the latest write, as when reading from the primary. It is used for stock and payments.
subscriber: A service that gets a copy of every message published to a topic, such as the email service for "order placed".
sync.WaitGroup: A Go counter for waiting on goroutines or messages: `Add(1)` for each, `Done()` when one finishes and `Wait()` blocks until the count is zero.
synchronous work: Work the reply must wait for, such as saving the order at checkout.
system design: Deciding a system's components and how they talk to each other, before or while you build it.

T

TCP: The connection protocol that delivers bytes in order and resends lost ones. HTTP runs over it.
timeout: The longest you will wait for a reply to a network call. Go's `http.Client` has none by default, so you set one, or a hung service ties up every thread.
TLS (Transport Layer Security): The encryption HTTPS uses so nobody in between can read the traffic.
token: A long secret string a caller sends in a header to prove who it is. A bearer token is sent as `Authorization: Bearer <token>`.
topic: The named channel in pub/sub that messages are published to and subscribers listen on, such as "order placed" or one per chat conversation.
transaction: A group of changes saved all together or not at all. If one step fails, they are rolled back.
TTL (time to live): How long a cached entry stays valid before it expires, so the next lookup misses and fetches a fresh copy.
type assertion: A Go expression like `el.Value.(*item)` that says a value of type `any` holds a particular type and gives it back.

U

units of time (ms, µs, ns): A millisecond (ms) is a thousandth of a second, a microsecond (µs) a millionth and a nanosecond (ns) a billionth. Latency is measured in these tiny units.
URL shortener: A service that turns long shop addresses into short links like `go.kettleandcrane.com/abc12` and redirects visitors to the long URL.

V

versioning: Putting a version such as `/v1/` in API paths so a `/v2/` can appear while old apps keep working.
vertical scaling: Moving to a bigger machine. It's simple, but there's a largest machine you can buy.

W

WebSocket: A connection that starts as an HTTP request and then stays open, so either side can send at any time. A support chat server uses one per person to push messages.
weighted round robin: Round robin where bigger servers appear more often in the list and so get more requests.
whiteboard sketch: A design drawn as boxes for components and arrows for the messages between them. A wrong box costs an eraser; a wrong server costs months.
wide-column store: A NoSQL database with huge tables spread over many machines, good for billions of events. Cassandra is an example.
worker: A program, often a goroutine, that takes messages off a queue and does the slow work, such as sending emails. It is the queue's consumer.
write-through cache: A cache that is written together with the database at the same time, instead of being deleted on change.