Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 36 ยท Projects and Practice

Project: An Order Service with Typed Faults and Idempotency

Build a SOAP order service that reports business errors as typed faults with structured detail, accepts idempotency keys, and is called by a client that retries safely, then lock the behavior in with tests.

Most real SOAP work is not "add two numbers". It is a business operation with rules (is there stock? is the customer allowed to buy?) and a promise to callers about what happens when things go wrong. In this project you will build an order service whose faults are typed: instead of an English sentence, each business failure comes with a structured detail element that code can read.

You will then write a client that reacts differently to each kind of failure, retry-safely, and finish with automated tests that pin the behavior down.

Typed faults: the idea

A plain faultstring such as "Not enough stock" is fine for a person. A program needs more: which product, how many are actually available, and whether trying again could ever help. A typed fault carries that in detail:

XML
<soap:Fault>
  <faultcode>soap:Client</faultcode>
  <faultstring>Insufficient stock</faultstring>
  <detail>
    <OutOfStock xmlns="urn:orders">
      <sku>A-1</sku><requested>10</requested><available>4</available>
    </OutOfStock>
  </detail>
</soap:Fault>

In a WSDL, each such fault type is declared per operation (a wsdl:fault pointing to a message whose part is the detail element), so generated clients throw a specific exception class, for example OutOfStockFault, rather than a generic one. Our version does the same by hand.

Fault Meaning Retry?
OutOfStock Business rule: not enough inventory No; show alternatives
InvalidRequest Malformed or invalid input No; fix the request
TemporarilyUnavailable Dependency down Yes, with backoff

Step 1: the service and a smart client

The service has one operation, PlaceOrder, with an idempotency key. The client maps each fault type to an action: it retries transient failures with the same key, and gives up on the others.

Node.js Order service, typed faults, retrying client

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Follow the four orders. The second A-1 order asks for 3 when only 1 is left, so the client receives an OutOfStock fault whose available field lets it offer "only 1 left". The B-2 order meets a transient failure on its first attempt and succeeds on the retry (attempts: 2). The last order is rejected as invalid without any retry.

The important line is where the key is created: once per order, outside the retry loop. If the key were generated inside the loop, every retry would look like a new order, and a lost response could create duplicates.

Step 2: lock in the behavior with tests

The business rules deserve fast tests that do not need HTTP. Here they are tested as plain functions through the Node test runner. Notice how each rule has a test, including the replay of a duplicate request.

Node.js Tests for the order rules

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The test about failed orders is easy to forget: a service that deducts stock first and checks afterwards would pass the "success" test and still corrupt data. Good fault tests assert that nothing changed when an operation failed.

Extensions

  1. Make the OutOfStock fault list two alternative SKUs from a substitutions table.
  2. Reject a replay whose payload differs from the first request with the same key (IdempotencyKeyReuse).
  3. Expire stored keys after 24 hours and test it by passing a fake clock into createOrderBook.
  4. Add CancelOrder with its own fault types and make it idempotent too.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does a typed fault carry fields like available in its detail?

    Structured detail lets callers offer alternatives or adjust the request programmatically.
  2. 2. Where must the idempotency key be generated in a retrying client?

    Reusing the key is what lets the server recognize a retry as the same order.
  3. 3. Which fault should a client NOT retry?

    OutOfStock is a business outcome. Repeating the request will not create stock.
  4. 4. What should a test of a failed operation also assert?

    Failure must be atomic: a failed order should leave stock exactly as it was.

Summary

  • Typed faults put structured, machine-readable detail in the fault so clients can respond precisely.
  • Classify faults as retryable or not; retry only transient ones, with the same idempotency key.
  • Idempotency makes duplicates harmless; failed operations must leave state unchanged.
  • Test every business rule, including replays and failure atomicity.

Next: Practice: Exercises and Interview Questions