Jonathan Ellis

We often talk about how Cassandra is designed from the ground up for&nbsp;<a href="https://twitter.com/dehora/status/218911811725041665">fault-tolerance and availability</a>. Today I want to discuss how this actually works in practice, and in particular what Cassandra can tell clients about request state when machines go down.

First, let's start with a very basic diagram describing a non-distributed server:

<img alt="non-distributed server" data-entity-type="file" data-entity-uuid="59348eb4-2e56-464d-ada7-946a05657a5f" height="108" src="https://www.datastax.com/sites/default/files/inline-images/Screen-shot-2012-08-15-at-12.56.15-PM.png" width="314" />

Client makes a request and gets a response. Simple!

But what happens when the server goes down before it replies?

<img alt="server goes down before it replies" data-entity-type="file" data-entity-uuid="958d148a-e7ba-409d-8f45-9e2f81fe0090" height="114" src="https://www.datastax.com/sites/default/files/inline-images/Screen-shot-2012-08-15-at-12.56.30-PM.png" width="305" />

The client doesn't know what happened. If it was trying to perform an update, it will have to retry the request when the server comes back up.

Everything else we're going to cover here is just an extension of this to a distributed system.

First, let's look at how things work when everything goes according to plan:

&nbsp;

<img alt="when everything goes according to plan" data-entity-type="file" data-entity-uuid="658f062e-5083-40d0-a3de-bfef68f06e66" height="143" src="https://www.datastax.com/sites/default/files/inline-images/Screen-shot-2012-08-15-at-12.57.34-PM_0.png" width="295" />

A client may talk to any node in a Cassandra cluster, whether or not it is a replica of the data being read or updated. The node a client talks to, the "coordinator," is responsible for routing the request to appropriate replicas.

If the coordinator fails mid-request, we're in a similar situation to what we had in the non-distributed case: the client is in the dark and has no choice but to retry. The only difference is that the client can reconnect to any node in the cluster immediately.

The interesting case is when a replica fails but the coordinator does not. There are actually two distinct scenarios here. In the first, the coordinator's&nbsp;<a href="https://www.datastax.com/docs/1.1/cluster_architecture/gossip#about-failure-detection-and-recovery">failure detector</a>&nbsp;knows that the replica is down before the request arrives:

<img alt="replica is down before the request arrives" data-entity-type="file" data-entity-uuid="9e675506-b074-4147-9e9d-8da5512eff22" height="154" src="https://www.datastax.com/sites/default/files/inline-images/Screen-shot-2012-08-15-at-12.57.49-PM.png" width="307" />

Since the coordinator knows the replica is down, it doesn't even attempt to route the request to it. Instead, it immeditely responds to the client with an&nbsp;<tt>UnavailableException</tt>. This is the only time Cassandra will fail a write. (And even then, you can request that Cassandra allow the write with&nbsp;<a href="https://www.datastax.com/docs/1.1/dml/data_consistency#about-write-consistency">ConsistencyLevel.ANY</a>.)

Let me say that again, because it's the single greatest point of confusion I see:&nbsp;the only time Cassandra will fail a write is when too few replicas are alive when the coordinator receives the request.

So what happens if the replica doesn't fail until&nbsp;after&nbsp;the coordinator has forwarded the client's request?

<img alt="if the replica doesn't fail until after the coordinator has forwarded the client's request" data-entity-type="file" data-entity-uuid="9cb2575e-a794-4be9-9a96-e7059b1ec174" height="164" src="https://www.datastax.com/sites/default/files/inline-images/Screen-shot-2012-08-15-at-12.57.58-PM_0.png" width="311" />

In this case, the coordinator replies with a&nbsp;<tt>TimedOutException</tt>.&nbsp;<a href="https://issues.apache.org/jira/browse/CASSANDRA-4414">Starting in Cassandra 1.2</a>, it will also include an&nbsp;<tt>acknowledged_by</tt>&nbsp;count of how many replicas succeeded. Also in 1.2, Cassandra provides&nbsp;<a href="https://issues.apache.org/jira/browse/CASSANDRA-2819">different timeouts</a>&nbsp;for reads, writes, and other operations such as&nbsp;<tt>truncate</tt>.

The coordinator is in the same situation the client was in during the single-server failure scenario: it doesn't know whether the request succeeded or failed, so all it can tell the client is that the request timed out.

Remember that for writes,&nbsp;a timeout is not a failure. (To make this more clear, we&nbsp;<a href="https://issues.apache.org/jira/browse/CASSANDRA-4414">considered renaming</a>&nbsp;<tt>TimedOutException</tt>&nbsp;to&nbsp;<tt>InProgressException</tt>&nbsp;for Cassandra 1.2, but decided against it to preserve backwards compatibility.)How can we say that since we don't know what happened before the replica failed? The coordinator can force the results towards either the pre-update or post-update state. This is what Cassandra does with&nbsp;<a href="https://www.datastax.com/docs/1.1/dml/about_writes#about-hinted-handoff-writes">hinted handoff</a>:

<img alt="This is what Cassandra does with hinted handoff:" data-entity-type="file" data-entity-uuid="eff302e0-41a0-4305-9b29-967001b555ce" height="166" src="https://www.datastax.com/sites/default/files/inline-images/Screen-shot-2012-08-15-at-12.58.23-PM.png" width="315" />

I labeled "timeout response" step 5 in the previous diagram. Recording the hint is the missing step 4: the coordinator stores the update locally, and will re-send it to the failed replica when it recovers, thus forcing it to the post-update state that the client wanted originally.

In the next post, I'll cover how we generalize this to multiple replicas.

Build and scale cloud native apps

Discover the benefits of DBaaS and why your apps deserve an upgrade.

Learn about NoSQL Databases

Learn about NoSQL databases with Apache Cassandra and Astra DB.

2022 Recap: A Year for Customers, Community, and Real-Time Data

Highlights from 2022 and a glimpse into the year ahead.

ViewingTechnical How To’s

When a timeout is not a failure: how Cassandra delivers high availability, part 1

Sign up for our Developer Newsletter