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

     1  ## Principles
     2  - SafeStateAPI is a low-level API for State which implements the following principles:
     3      - used by extension engines
     4      - automatically converts package paths (extensions work with full paths)
     5      - Keys, Values, Key- and Value-Builders are represented with numbers, to be transferred between Host and Extension environments.
     6  
     7  
     8  ## Design
     9  ```mermaid
    10  flowchart TD
    11      exttinygo:::G
    12      exttinygotests:::G
    13      state:::G
    14      isafeapi:::G
    15      safestate:::G
    16      teststate:::G
    17      iextengine:::G
    18      application:::G
    19      wazero:::G
    20      processors:::G
    21      subgraph exttinygo
    22          internal.State["var SafeStateAPI"]:::S
    23          hostAPI["hostSafeStateApi"]:::S
    24          clientStateAPI["Client State API"]:::S
    25          subgraph exttinygotests
    26              NewTestAPI["NewTestAPI(...)"]:::S
    27          end
    28      end
    29      subgraph state
    30          IState:::S
    31          subgraph isafeapi
    32              IStateSafeAPI["IStateSafeAPI"]:::S
    33          end
    34          subgraph teststate
    35              ITestState["ITestState"]:::S
    36              ITestAPI["ITestAPI"]:::S
    37          end
    38          subgraph safestate
    39              safestate.Provide["safestate.Provide(...)"]:::S
    40          end
    41      end
    42      subgraph application["application package"]
    43          Test:::S
    44          Extension:::S
    45      end
    46      subgraph iextengine
    47          subgraph wazero
    48              IExtensionEngineWazero["IExtensionEngineWazero"]:::S
    49          end
    50  
    51          IExtensionEngine["IExtensionEngine"]:::S
    52      end
    53      subgraph processors
    54          Processor:::S
    55      end
    56      
    57      internal.State -.-> |by default initialized with| hostAPI
    58      internal.State -.-> |of type| IStateSafeAPI
    59      internal.State -.-> |used by| clientStateAPI
    60  
    61      NewTestAPI -.-> |1. constructs| ITestState
    62      NewTestAPI -.-> |2. calls| safestate.Provide
    63      NewTestAPI -.-> |3. sets| internal.State
    64      ITestState -.-> |implements| ITestAPI
    65      ITestState -.-> |implements| IState
    66      
    67      ITestAPI -.-> |used by| Test
    68      safestate.Provide -.-> |to provide| IStateSafeAPI
    69  
    70      hostAPI -.-> |calls host functions| IExtensionEngineWazero
    71      IExtensionEngine -.-> |can be| IExtensionEngineWazero
    72  
    73      Processor --> |has| IState
    74      IState -.-> |passed to| safestate.Provide
    75      IState -.-> |"passed to Invoke(...)"| IExtensionEngine
    76      IExtensionEngineWazero -.-> |calls| safestate.Provide
    77      Test -.-> |calls| Extension
    78      clientStateAPI -.-> |used by|Extension
    79  
    80  classDef B fill:#FFFFB5,color:#333
    81  classDef S fill:#B5FFFF,color:#333
    82  classDef H fill:#C9E7B7,color:#333
    83  classDef G fill:#ffffff15, stroke:#999, stroke-width:2px, stroke-dasharray: 5 5
    84  
    85  ```