Claim Check
Table of Contents
This page defines the service architecture pattern Claim Check in the pattern language. A large payload goes to a store and the message carries only a key to it. In ORE Studio the trade and market data exports, the engine input and the engine output travel this way, through object storage.
1. Also known as
- Reference-based messaging.
2. Context
Some data is large: a portfolio of trades, a market data set, an engine archive. The bus limits message size and is a poor place for bulk bytes.
3. Problem
How does a service hand another a large payload without sending it through the bus?
4. Forces
- Messages have a size limit, and large messages slow every other message.
- The receiver may need the payload later, or more than once.
- The payload must be complete before anyone reads it.
- Access to the payload must follow the same tenancy rules as the message.
5. Solution
The producer writes the payload to object storage under a key that names exactly one object, then sends a small message with the key, the size and a count. The consumer fetches the bytes by key, with the caller's token, and streams them.
Figure 1: Claim Check: the producer stores the payload, the message carries the key, and the consumer fetches the bytes.
Source: [[./pattern_claim_check.puml][pattern_claim_check.puml]]. Regenerate with
plantuml -tpng doc/knowledge/service_architecture_patterns/pattern_claim_check.puml.
6. Failure handling
| Concern | What the pattern does |
|---|---|
| Errors | A missing or unreadable object fails the consumer's step with the key in the error. |
| Timeouts | A large transfer has its own timeout, longer than a request's. |
| Retries | Writing the same key twice replaces the object, so a retried producer converges. |
| Idempotency | Writing to a temporary key and renaming it means a reader never sees a partial object. |
| Observability | The key is logged by the producer and the consumer. |
7. Pitfalls
- A partial object read as complete. A reader that starts before the write ends reads a truncated archive. Write, then rename.
- A key that is not unique. Two runs that share a key overwrite each other. Put the run or the digest in the key.
- Objects nobody deletes. A claim check with no lifecycle fills the store. Each purpose states its retention.
- The payload fetched with the service's identity. Storage authorises the caller; use the relayed or run token.
8. Security
Storage authorises every read and write against the token presented. The key grants nothing by itself.
9. Resulting context
- Benefits
- Messages stay small, bulk data streams, and a payload can be read again.
- Liabilities
- Two systems must agree on the key, and objects need a retention policy.
10. In ORE Studio
- Report processing interfaces — the trades and market data exports write to storage and answer with the key.
- Object Storage — the bucket and key protocol every claim check names.
- Storage policy — a compute assignment carries the keys, and the node fetches them under a capability scoped to those keys.
- How the compute grid queues and claims work — the assignment carries the keys of a job and a token minted at the claim.
- The history call returns every tick of a range in one reply, or refuses the range — a reply over the message cap would travel as a key to the ticks in storage.
11. Related patterns
- Request-Reply — carries the key.
- Idempotent Receiver — a repeated write of the same key converges.
12. Sources
- Gregor Hohpe and Bobby Woolf, Enterprise Integration Patterns, Addison-Wesley, 2003, Claim Check.
- Microsoft, Azure Architecture Center, Cloud design patterns, Claim-Check pattern.
13. See also
- Service architecture patterns — the structure note that orders this pattern language, and where to read this page in it.