Skip to content

[Internal] docs: Add address caches conceptual flow #3534

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kirankumarkolli merged 11 commits into from
Nov 2, 2022
Merged

[Internal] docs: Add address caches conceptual flow #3534

Changes from 3 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
11ec2d6
Rough draft
kirankumarkolli Oct 30, 2022
15a9d2e
Some more changes
kirankumarkolli Nov 1, 2022
b6e201e
Adding a new section
kirankumarkolli Nov 1, 2022
8d17737
Some more refinement
kirankumarkolli Nov 1, 2022
fe0d237
Some changes
kirankumarkolli Nov 1, 2022
3d9c41a
Some MISC changes
kirankumarkolli Nov 1, 2022
bb82e98
Merge branch 'master' into users/kirankk/arch_refresh
kirankumarkolli Nov 1, 2022
60f5c62
Merge branch 'master' into users/kirankk/arch_refresh
kirankumarkolli Nov 2, 2022
e237dcf
Update docs/SdkDesign.md
kirankumarkolli Nov 2, 2022
a06a69e
Update docs/SdkDesign.md
kirankumarkolli Nov 2, 2022
75daa95
Update docs/SdkDesign.md
kirankumarkolli Nov 2, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions docs/SdkDesign.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,77 @@ flowchart LR
TransportClient <--> Service[(Cosmos DB Service)]
```

## Address caches coneptual model

```mermaid
flowchart LR
subgraph CDB_account
subgraph CDB_Account_Endpoint
CDB_EP[[fa:fa-cloud CosmosDB-Account/Endpoint]]
end

subgraph CDB_Account_Region1
CDBR1_GW[[fa:fa-cloud CosmosDB-Account/Gateway/Region1]]
CDBR1_BE[[fa:fa-cloud CosmosDB-Account/Backend/Region1]]
end
subgraph CDB_Account_RegionN
CDBRN_GW[[fa:fa-cloud CosmosDB-Account/Gateway/Region1]]
CDBRN_BE[[fa:fa-cloud CosmosDB-Account/Backend/RegionN]]
end
end
subgraph AddressCaches
GAC1[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/Microsoft.Azure.Cosmos/src/Routing/GatewayAddressCache.cs'>GatewayAddressCache/R1</a>]
GACN[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/Microsoft.Azure.Cosmos/src/Routing/GatewayAddressCache.cs'>GatewayAddressCache/RN</a>]

GAC1 --> |NonBlockingAsyncCache| CDBR1_GW
GAC1 -.-> CDBR1_BE
GACN --> |NonBlockingAsyncCache| CDBRN_GW
GACN -.-> CDBRN_BE
end
subgraph GlobalEndpointManager
GEM[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/Microsoft.Azure.Cosmos/src/Routing/GlobalEndpointManager.cs'>GlobalEndpointManager</a>] ==> LC[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/Microsoft.Azure.Cosmos/src/Routing/LocationCache.cs'>LocationCache</a>]
PL[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/543294cd7e49c9322661422ea602bc911c434972/Microsoft.Azure.Cosmos/src/CosmosClientOptions.cs#L190'>PreferredLocations</a>]
GEPEM[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/Microsoft.Azure.Cosmos/src/Routing/GlobalPartitionEndpointManager.cs'>GlobalPartitionEndpointManager</a>]
GEPEMC[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/Microsoft.Azure.Cosmos/src/Routing/GlobalPartitionEndpointManagerCore.cs'>GlobalPartitionEndpointManagerCore</a>]

LC --> PL
GEPEM --> GEPEMC
GEPEMC --x GEM
end
subgraph AddressResolver
GAR[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/Microsoft.Azure.Cosmos/src/Routing/GlobalAddressResolver.cs'>GlobalAddressResolver</a>]
IAR[<a href=https://github.com/Azure/azure-cosmos-dotnet-v3/blob/msdata/direct/Microsoft.Azure.Cosmos/src/direct/IAddressResolver.cs'>IAddressResolver</a>]
AR[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/a94329d353aa8432d57270c3f3bc19cba1021855/Microsoft.Azure.Cosmos/src/direct/IAddressResolver.cs#L12'>AddressResolver</a>]

IAR --> AR
AR --> GAR
GAR --> |R1 Addresses| GAC1
GAR --> |RN Addresses| GACN
GAR -.-> |PeriodicRefresh| CDB_EP

GAR --x |PerPartitionRouting| GEPEM
GAR --x |RegionRoutng| GEM
end
subgraph addressselector
AS[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/a94329d353aa8432d57270c3f3bc19cba1021855/Microsoft.Azure.Cosmos/src/direct/AddressSelector.cs'>AddressSelector</a>]
CR[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/a94329d353aa8432d57270c3f3bc19cba1021855/Microsoft.Azure.Cosmos/src/direct/ConsistencyReader.cs'>ConsistencyReader</a>]
CW[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/a94329d353aa8432d57270c3f3bc19cba1021855/Microsoft.Azure.Cosmos/src/direct/ConsistencyWriter.cs'>ConsistencyWriter</a>]
RSC[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/a94329d353aa8432d57270c3f3bc19cba1021855/Microsoft.Azure.Cosmos/src/direct/ReplicatedResourceClient.cs'>ReplicatedResourceClient</a>]
SC[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/a94329d353aa8432d57270c3f3bc19cba1021855/Microsoft.Azure.Cosmos/src/direct/StoreClient.cs'>StoreClient</a>]
SSM[<a href='https://github.com/Azure/azure-cosmos-dotnet-v3/blob/a94329d353aa8432d57270c3f3bc19cba1021855/Microsoft.Azure.Cosmos/src/direct/ServerStoreModel.cs'>ServerStoreModel</a>]

AS --x IAR
CR --x AS
CW --x AS
RSC --x CR
RSC --x CW
SC --x RSC
SSM --x SC
end

```


## Handler pipeline

The handler pipeline processes the RequestMessage and each handler can choose to augment it in different ways, as shown in our [handler samples](../Microsoft.Azure.Cosmos.Samples/Usage/Handlers/) and also handle certain error conditions and retry, like our own [RetryHandler](../Microsoft.Azure.Cosmos/src/Handler/RetryHandler.cs). The RetryHandler will handle any failures from the [Transport layer](#transport) that should be [handled as regional failovers](#cross-region-retries).
Expand Down