github.com/voedger/voedger@v0.0.0-20240520144910-273e84102129/design/state/README.md (about)

     1  # State 2.0
     2  State 2.0 is a mechanism which provides I/O to [extensions](./ext-engines.md)
     3  
     4  ## Principles
     5  
     6  - CommandProcessor (CP), QueryProcessor (QP), SyncActualizer (SA) and AsyncActualizer (AA) uses States with different set of IStateStorages (see table below);
     7  - By making Insert- and Update- operations extension create *intents*. Intents applied when the extensions function ends and core calls `ApplyIntents` method. Get- and Read- operations do not see changes made in the intents.
     8  - CP and QP calls `ApplyIntents` after every command function execution (QP doesn't have any registered storages which is able to insert or update atm)
     9  - AA uses slightly different implementation of IState. When `ApplyIntents` called, the intents are stored in an internal buffer (*bundles*) and doesn't applied to internal storage immediately. There is separate method `FlushBundles` which is called:
    10    - by timer from actualizer
    11    - when bundles size is big enough
    12    - when the Read operation wants to read from the entity and there are key(s) for this entity in any bundle
    13  
    14  ## Architecture
    15  
    16  ```mermaid
    17  erDiagram
    18  QueryProcessor }|--|{ Extension: executes
    19  CommandProcessor }|--|{ Extension: executes
    20  AsyncActualizer ||--|| Actualizer: is
    21  SyncActualizer ||--|| Actualizer: is
    22  Actualizer }|--|{ Extension: executes
    23  Extension }|--|| IState: "reads from StateStorages with"
    24  Extension }|--|{ IIntents: "declares changes with"
    25  ```
    26  
    27  ## Different IState Implementations
    28  ```mermaid
    29  erDiagram
    30  QueryProcessor ||--|| QueryProcessorState: has
    31  CommandProcessor ||--|| CommandProcessorState: has
    32  SyncActualizer ||--|{ SyncActualizerState: "has, one per projector"
    33  AsyncActualizer ||--|| AsyncActualizerState: has
    34  QueryProcessorState ||--|| IHostState: implements
    35  CommandProcessorState ||--|| IHostState: implements
    36  SyncActualizerState ||--|| IHostState: implements
    37  AsyncActualizerState ||--|| IBundledHostState: implements
    38  IHostState ||--|| IState: implements
    39  IBundledHostState ||--|| IState: implements
    40  IHostState ||--|| IIntents: implements
    41  IBundledHostState ||--|| IIntents: implements
    42  IBundledHostState ||--|| FlushBundles: provides
    43  IState ||--|| Read_From_Storages: "used to"
    44  IIntents ||--|| Update_Storages: "used to"
    45  ```
    46  
    47  ## Limitations
    48  - It should not be allowed to update the same view from two different projectors, otherwise conflicts may happen.
    49  
    50  ## State Storage Availability
    51  - CRUG: Create, Read, Update, Get
    52  - CP - Command Processor, QP - Query Processor, AA - Async Actualizer, SA - Sync Actualizer
    53  
    54  | Storage             |  CP  |  SA  |  QP  |  AA  | 
    55  | ------------------- | ---- | ---- | ---- | ---- |
    56  | AppSecretsStorageID |  G   |  G   |  G   |  G   |
    57  | PLogStorageID       |  G   |  G   |  RG  |  RG  |
    58  | WLogStorageID       |  G   |  G   |  RG  |  RG  |
    59  | RecordStorageID     | CUG  |  G   |  G   | CUG* |
    60  | ViewStorageID       |  G   |  G   |  RG  | CRUG |
    61  | HTTPStorageID       |      |      |  R   |  R   |
    62  | MailStorageID       |      |      |      |  C   |
    63  
    64  * CU operations in Async Actualizers are done using commands (so called "federation post")
    65  
    66  ## Implementation
    67  - A new IState replaces old components:
    68    - old IQueryState components (provide to request data and apply modifications)
    69    - old IState (provides a way to access requested data)\\
    70    - old IStorages (working with different types of storages)
    71    - See [IState example](https://github.com/heeus/inv-wasm/blob/master/20220326-projector-api/src/state.go)
    72  - Instead of constructing PipelineStorages, a components (Command processor, Query processor, Actualizers) will construct new State and provide IState to ICommandFunction, IQueryFunction or IProjector
    73  
    74  ## See Also
    75  - [Exttension Engines / WASM ABI](./ext-engines.md)
    76  - [Projectors & Actualizers](../projectors/README.md)
    77  - [Query Processor](../queryprocessor/README.md)