asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: create docs workspace (#5174)

Browse Source 
* docs: migrate ui docs to docs universe

* created yarn workspace

* added eslint and tsconfig configurations

* fix eslint configurations

* fixed eslint configurations

* shared tailwind configurations

* added shared ui package

* added more shared components

* migrating more components

* made details components shared

* move InlineCode component

* moved InputText

* moved Loading component

* Moved Modal component

* moved Select components

* Moved Tooltip component

* moved Search components

* moved ColorMode provider

* Moved Notification components and providers

* used icons package

* use UI colors in api-reference

* moved Navbar component

* used Navbar and Search in UI docs

* added Feedback to UI docs

* general enhancements

* fix color mode

* added copy colors file from ui-preset

* added features and enhancements to UI docs

* move Sidebar component and provider

* general fixes and preparations for deployment

* update docusaurus version

* adjusted versions

* fix output directory

* remove rootDirectory property

* fix yarn.lock

* moved code component

* added vale for all docs MD and MDX

* fix tests

* fix vale error

* fix deployment errors

* change ignore commands

* add output directory

* fix docs test

* general fixes

* content fixes

* fix announcement script

* added changeset

* fix vale checks

* added nofilter option

* fix vale error
This commit is contained in:
Shahed Nasser
2023-09-21 20:57:15 +03:00
committed by GitHub
parent 19c5d5ba36
commit fa7c94b4cc
3209 changed files with 32188 additions and 31018 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
www/apps/docs/content/development/idempotency-key/overview.mdx Normal file
View File

@@ -0,0 +1,72 @@
---
description: "Learn what an idempotency key is in Medusa. An Idempotency Key is a unique key associated with an operation that allows you to safely retry requests."
---
import DocCard from '@theme/DocCard';
import Icons from '@theme/Icon';
# Idempotency Key
In this document, you'll learn what an idempotency key is in Medusa.
## Overview
An Idempotency Key is a unique, randomly generated key associated with an operation, such as the cart completion process. The idempotency key can be passed in the header of a request to an endpoint. This allows you to safely retry requests without accidentally performing the same operation twice.
For example, if a connection error occurs while the customer is completing their cart and placing an order, you can retry from the last recovery point before the error occurred.
When an operation first starts, the idempotency key is generated using the `uuid` package's `v4` method. Then, the backend sets the following headers in the response:
```bash
Access-Control-Expose-Headers: Idempotency-Key
Idempotency-Key: <IDEM_VAL>
```
Where `<IDEM_VAL>` is the idempotency key generated.
These headers can then be passed again for subsequent retrying requests and will be available on the response of these requests as well. The value of the idempotency key remains the same across requests and responses, even if an error occurs and you retry the request.
For example, when the cart completion process starts, the Medusa backend generates the idempotency key and sets the necessary headers on the response. If an error occurs in the request, you can later retry the request by passing these same headers in your request.
---
## IdempotencyKey Entity Overview
The idempotency key's data is stored within the `IdempotencyKey` entity. Some of its attributes include:
- `idempotency_key`: a unique string indicating the value of the idempotency key.
- `request_method`: a string indicating the method of the latest request related to the idempotency key's operation. For example, `POST`.
- `request_params`: a JSONB object indicating the parameters of the latest request related to the idempotency key's operation.
- `request_path`: a string indicating the path of the latest request related to the idempotency key's operation.
- `response_code`: a number indicating the response code of the latest request related to the idempotency key's operation.
- `response_body`: a JSONB object indicating the response body of the latest request related to the idempotency key's operation.
- `recovery_point`: a string indicating the point to continue from when retrying the request. The default value is `started`.
---
## Idempotency Key Stages
Idempotency key stages are the different recovery points that are available for an operation. Every operation has at least the `started` and `finished` stages.
For example, the cart completion operation has the following stages or recovery points:
- `started`
- `tax_lines_created`
- `payment_authorized`
- `finished`
---
## Custom Development
You can use the `IdempotencyKeyService` in your custom development to ensure requests can be safely retried or continued.
<DocCard item={{
type: 'link',
href: '/development/idempotency-key/use-service',
label: 'Use IdempotencyKeyService',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to use the IdempotencyKeyService in your code.'
}
}} />

153
www/apps/docs/content/development/idempotency-key/use-service.md Normal file
View File

@@ -0,0 +1,153 @@
---
description: 'Learn how to create a loader in Medusa. A loader can be created in the Medusa backend codebase, in a plugin, or in a module.'
addHowToData: true
---
# How to Use IdempotencyKeyService
In this document, you'll learn how to use the `IdempotencyKeyService`.
## Overview
You can use the `IdempotencyKeyService` within your custom development to ensure that your custom endpoints and operations can be safely retried or continued if an error occurs. This guide is also useful if you're overriding an existing feature in Medusa that uses the `IdempotencyKeyService` and you want to maintain its usage, such as if you're overriding the cart completion strategy.
The `IdempotencyKeyService` includes methods that can be used to create and update idempotency keys, among other functionalities.
---
## Create Idempotency Key
You can create an idempotency key within an endpoint using the `create` method of the `IdempotencyKeyService`:
```ts
router.post("/custom-route", async (req, res) => {
// ...
const idempotencyKey = await idempotencyKeyService.create({
request_method: req.method,
request_params: req.params,
request_path: req.path,
})
// ...
})
```
The method requires as a parameter an object having the following properties:
- `request_method`: a string indicating the request method to be associated with the idempotency key.
- `request_params`: an object indicating the request parameters to be associated with the idempotency key.
- `request_path`: a string indicating the request path to be associated with the idempotency key.
The method handles generating the idempotency key value and saving the idempotency key with its details in the database. It returns the full idempotency key object.
Alternatively, you can use the `initializeRequest` method that allows you to retrieve an idempotency key based on the value passed in the `Idempotency-Key` header of the request if it exists, or create a new key otherwise. For example:
```ts
router.post("/custom-route", async (req, res) => {
// ...
const headerKey = req.get("Idempotency-Key") || ""
const idempotencyKey = await idempotencyKeyService
.initializeRequest(
headerKey,
req.method,
req.params,
req.path
)
// ...
})
```
The method requires the following parameters:
1. The first parameter is the key existing in the header of the request, if there's any.
2. The second parameter is the request's method.
3. The third parameter is the request's parameters.
4. The fourth method is the request's path.
The method returns the full idempotency key object.
---
## Perform Actions Within Idempotency Key Stages
Each [idempotency key stage](./overview.mdx#idempotency-key-stages) typically has transactions performed within it. Using the `IdempotencyKeyService`'s `workStage` method allows you to perform related functionalities in transactional isolation within each stage. You can access the stage or recovery point of an idempotency key using the `recovery_point` attribute.
The following example is taken from the `CartCompletionStrategy` implemented in the Medusa backend:
<!-- eslint-disable no-fallthrough -->
```ts
class CartCompletionStrategy
extends AbstractCartCompletionStrategy {
// ...
async complete(
id: string,
ikey: IdempotencyKey,
context: RequestContext
): Promise<CartCompletionResponse> {
// ...
let inProgress = true
let err: unknown = false
while (inProgress) {
switch (idempotencyKey.recovery_point) {
case "started": {
await this.activeManager_
.transaction(
"SERIALIZABLE",
async (transactionManager) => {
idempotencyKey =
await this.idempotencyKeyService_
.withTransaction(transactionManager)
.workStage(
idempotencyKey.idempotency_key,
async (manager) =>
await this.handleCreateTaxLines(
id,
{
manager,
}
)
)
}
)
.catch((e) => {
inProgress = false
err = e
})
break
}
case "tax_lines_created": {
// ...
}
case "payment_authorized": {
// ...
}
case "finished": {
// ...
}
default: {
// ...
}
}
}
// ...
}
}
```
The method requires the following parameters:
1. The first parameter is the idempotency key value.
2. The second parameter is a callback function to be executed. The function should return an object that is used to update the idempotency key's details. The object can include the following parameters:
1. `recovery_point`: a string indicating the new recovery point associated with the idempotency key's operation. If no `recovery_point` is returned in the object, the `finished` recovery point is assigned by default.
2. `response_code`: a number indicating the latest response code of the idempotency key's operation.
3. `response_body`: an object indicating the latest response body of the idempotency key's operation.
The method returns an updated idempotency key object.