diff --git a/docs/get_started/tour.mdx b/docs/get_started/tour.mdx index 826e7cf9..3305d7bc 100644 --- a/docs/get_started/tour.mdx +++ b/docs/get_started/tour.mdx @@ -32,7 +32,7 @@ Restate manages their invocation and execution. Services communicate with one another using Remote Procedure Calls (RPC). Our ticket example consists of three services: - + As we go, you will discover how Restate can help you with some intricacies in this application. @@ -1473,6 +1473,35 @@ npm run part4 +## Idempotency for any request +As you saw, generating idempotency keys inside your handlers and storing them in Restate is easy. + +But this doesn't guard us yet against retries of the HTTP request to Restate. +If the system invoking the `checkout` handler retries the request, the handler gets executed twice. + +To cover this, you can add an `idempotency-key` header to the incoming request to let Restate deduplicate them. + +Our `CartObject/checkout` handler is robust against retries since it checks the state content. +So instead, check out how this works by calling the `CheckoutService/handle` handler with an idempotency key: + +```shell +curl localhost:8080/CheckoutService/handle \ + -H 'idempotency-key: ad5472esg4dsg525dssdfa5loi' \ + -H 'content-type: application/json' \ + -d '{"userId": "Mary", "tickets":["123", "236"]}' +``` + +The first time you call it, Restate will execute the handler. +The second time Restate returns the previous result of the invocation, without executing the handler (see the service logs). + + + Restate gives you idempotency for any service, handler and request for free. + No extra setup. + + +Note that you only need this when invoking handlers over HTTP. +When a handler calls another handler, Restate automatically takes care of the idempotency. + ## Tracing @@ -1540,15 +1569,16 @@ Let's recap what you did! You have built a ticket reservation system that is res We used Restate to provide us with durable, distributed building blocks to simplify the implementation of the system. Let's list a few of them: -| What you implemented | What you didn't implement, as Restate handles it for you | -|--------------------------------------------------------------|------------------------------------------------------------------------------------------------| -| ✅ Request-response invocations | ❌ Handling retries, timeouts, etc. | -| ✅ Sending messages | ❌ Deploy and operate message queues for async requests | +| What you implemented | What you didn't implement, as Restate handles it for you | +|--------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| +| ✅ Request-response invocations | ❌ Handling retries, timeouts, etc. | +| ✅ Sending messages | ❌ Deploy and operate message queues for async requests | +| ✅ Idempotent HTTP calls | ❌ Write deduplication logic | | ✅ Durable Execution: retries, partial progress recovery, and suspensions | ❌ Manual retry logic and partial progress recovery | -| ✅ Durable timers: sleeping and scheduling async tasks | ❌ Workflow orchestrators or cron jobs for scheduling tasks | -| ✅ Virtual Objects: concurrency guarantees and shared state | ❌ Guards for keeping state consistent across retries, concurrent requests, and scaling out. | -| ✅ K/V state: storing and inspecting | ❌ Session databases for state. State consistency guards. | -| ✅ Storing computation results in the journal | ❌ Logic to make operations idempotent (e.g. generate idempotency keys) | +| ✅ Durable timers: sleeping and scheduling async tasks | ❌ Workflow orchestrators or cron jobs for scheduling tasks | +| ✅ Virtual Objects: concurrency guarantees and shared state | ❌ Guards for keeping state consistent across retries, concurrent requests, and scaling out. | +| ✅ K/V state: storing and inspecting | ❌ Session databases for state. State consistency guards. | +| ✅ Storing computation results in the journal | ❌ Logic to make operations idempotent (e.g. generate idempotency keys) | You now know the essentials to start developing Restate services! Have a look at the next steps to explore further.