Feature: Persistency KVS

docs/_tooling/extensions/score_metamodel/checks/attributes_format.py

@@ -50,15 +50,15 @@ def check_id_format(app: Sphinx, need: NeedsInfoType, log: CheckLogger):
 @local_check
 def check_id_length(app: Sphinx, need: NeedsInfoType, log: CheckLogger):
     """
-    Validates that the requirement ID does not exceed the hard limit of 45 characters.
+    Validates that the requirement ID does not exceed the hard limit of 90 characters.
     While the recommended limit is 30 characters, this check enforces a strict maximum
-    of 45 characters.
-    If the ID exceeds 45 characters, a warning is logged specifying the actual length.
+    of 90 characters.
+    If the ID exceeds 90 characters, a warning is logged specifying the actual length.
     ---
     """
-    if len(need["id"]) > 45:
+    if len(need["id"]) > 90:
         msg = (
-            f"exceeds the maximum allowed length of 45 characters "
+            f"exceeds the maximum allowed length of 90 characters "
             f"(current length: {len(need['id'])})."
         )
         log.warning_for_option(need, "id", msg)

docs/features/persistency/index.rst

@@ -18,4 +18,4 @@ Persistency
 .. toctree::
 
    file-access/index.rst
-   key-value-storage/index.rst
+   kvs/index.rst

docs/features/persistency/kvs/architecture/_assets/kvs_dyn_builder.puml

@@ -0,0 +1,29 @@
+@startuml
+
+title Sequence Diagram: KVS Builder
+
+participant "User" as actor
+participant "«component» :builder" as builder
+participant "«component» :kvs" as kvs
+
+actor -> builder: Create KVS builder
+builder --> actor: KVS builder instance
+
+actor -> builder: Set need_defaults flag
+builder --> actor: KVS builder instance
+
+actor -> builder: Set need_kvs flag
+builder --> actor: KVS builder instance
+
+actor -> builder: Build KVS instance
+builder -> kvs: Open KVS with builder config
+
+alt kvs-open
+    kvs --> builder: KVS instance
+    builder --> actor: KVS instance
+else kvs-open-error
+    kvs --> builder: KVS ErrorCode
+    builder --> actor: KVS ErrorCode
+end
+
+@enduml

docs/features/persistency/kvs/architecture/_assets/kvs_dyn_check_value_default.puml

@@ -0,0 +1,24 @@
+@startuml
+
+title Sequence Diagram: Check if Key contains Default Value
+
+participant "User" as actor
+participant "«component» :kvs" as kvs
+
+actor -> kvs: Does key has default value
+
+alt default-key-exists
+    alt key-exists
+        alt default-and-key-match
+            kvs --> actor: Key contains default value
+        else key-doesnt-exist
+            kvs --> actor: Key doesn't containt default value
+        end
+    else key-doesnt-exist
+        kvs --> actor: Key contains default value
+    end
+else default-doesnt-exist
+    kvs --> actor: Key doesn't contain default value
+end
+
+@enduml

docs/features/persistency/kvs/architecture/_assets/kvs_dyn_delete_data_key.puml

@@ -0,0 +1,16 @@
+@startuml
+
+title Sequence Diagram: Delete Key from KVS Instance
+
+participant "User" as actor
+participant "«component» :kvs" as kvs
+
+actor -> kvs: Remove key
+
+alt key-exists
+    kvs --> actor: Successfully deleted key
+else key-doesnt-exist
+    kvs --> actor: Key-Not-Found-Error
+end
+
+@enduml

docs/features/persistency/kvs/architecture/_assets/kvs_dyn_flush_local_repr_to_file.puml

@@ -0,0 +1,60 @@
+@startuml
+
+title Sequence Diagram: Flush Local Representation to Data File
+
+participant "User" as actor
+participant "«component» :kvs" as kvs
+participant "«component» :snapshot" as snapshot
+participant "«component» :TinyJSON" as json_parser
+participant "«component» :fs" as fs
+participant "«component» :Adler32" as hasher
+
+actor -> kvs: Flush KVS
+
+kvs -> json_parser: Generate string from local representation
+
+alt json-string
+    json_parser --> kvs: JSON data string
+else json-string-error
+    json_parser --> kvs: JSON generator error
+    kvs --> actor: JSON generator error
+end
+
+kvs -> snapshot: Rotate snapshots
+
+alt snapshot-rotate
+    snapshot -> kvs: Snapshots rotated
+else snapshot-rotate-error
+    snapshot --> kvs: Snapshot-Rotate-Error
+    kvs --> actor: Snapshot-Rotate-Error
+end
+
+kvs -> hasher: Create JSON data string hash
+
+alt hash-created
+    hasher --> kvs: Data hash
+else hash-create-error
+    hasher --> kvs: Hash-Calc-Error
+    kvs --> actor: Hash-Calc-Error
+end
+
+kvs -> fs: Write JSON data string to file
+
+alt file-write
+    fs --> kvs: File successfully written
+else file-write-error
+    fs --> kvs: File-Write-Error
+    kvs --> actor: File-Write-Error
+end
+
+kvs -> fs: Write JSON data hash to file
+
+alt file-hash-write
+    fs --> kvs: Hash file successfully written
+    kvs --> actor: Flush successful
+else file-hash-write-error
+    fs --> kvs: File-Hash-Write-Error
+    kvs --> actor: File-Hash-Write-Error
+end
+
+@enduml

docs/features/persistency/kvs/architecture/_assets/kvs_dyn_read_data_key.puml

@@ -0,0 +1,20 @@
+@startuml
+
+title Sequence Diagram: Read Key from KVS Instance
+
+participant "User" as actor
+participant "«component» :kvs" as kvs
+
+actor -> kvs: Get value for key
+
+alt key-exists
+    kvs --> actor: Return value for key
+else key-doesnt-exist
+    alt default-exists
+        kvs --> actor: Return default value for key
+    else default-doesnt-exist
+        kvs --> actor: Key-Not-Found error
+    end
+end
+
+@enduml

docs/features/persistency/kvs/architecture/_assets/kvs_dyn_read_file_into_local_repr.puml

@@ -0,0 +1,49 @@
+@startuml
+
+title Sequence Diagram: Read Data into Local Representation (KvsValue)
+
+participant "Builder" as actor
+participant "«component» :kvs" as kvs
+participant "«component» :TinyJSON" as json_parser
+participant "«component» :fs" as fs
+participant "«component» :Adler32" as hasher
+
+actor -> kvs: Open KVS
+
+kvs -> fs: Read defaults file
+
+alt file-exists
+    fs --> kvs: Defaults file content (JSON)
+else file-based-error
+    fs --> kvs: File-Error
+    kvs -> actor: File-Error
+end
+
+kvs -> fs: Read defaults file hash
+
+alt file-exists
+    fs --> kvs: Defaults file hash
+else file-based-error
+    fs --> kvs: File-Error
+    kvs -> actor: File-Error
+end
+
+kvs -> hasher: Generate defaults file hash
+hasher --> kvs: Defaults file generated hash
+
+alt hash-matches
+    kvs -> json_parser: Parse JSON data
+else hash-match-error
+    kvs -> actor: Hash-Error
+end
+
+alt parsing-success
+    json_parser --> kvs: Parsed JSON object
+else parsing-based-error
+    json_parser -> kvs: Parser-Error
+    kvs -> actor: Parser-Error
+end
+
+kvs --> actor: KVS instance
+
+@enduml

docs/features/persistency/kvs/architecture/_assets/kvs_dyn_restore_snapshot.puml

@@ -0,0 +1,19 @@
+@startuml
+
+title Sequence Diagram: Restore Snapshot
+
+participant "User" as actor
+participant "«component» :kvs" as kvs
+participant "«component» :snapshot" as snapshot
+
+actor -> kvs: Restore snapshot
+
+alt snapshot-found
+    snapshot --> kvs: Snapshot restored into local representation
+    kvs --> actor: Snapshot restored successfully
+else snapshot-error
+    snapshot --> kvs: Snapshot-Not-Available-Error
+    kvs --> actor: Snapshot-Not-Available-Error
+end
+
+@enduml

docs/features/persistency/kvs/architecture/_assets/kvs_dyn_write_data_key.puml

@@ -0,0 +1,11 @@
+@startuml
+
+title Sequence Diagram: Write Key to KVS Instance
+
+participant "User" as actor
+participant "«component» :kvs" as kvs
+
+actor -> kvs: Set value for key
+kvs --> actor: Value set for key
+
+@enduml

docs/features/persistency/kvs/architecture/_assets/kvs_interface.puml

@@ -0,0 +1,23 @@
+@startuml
+
+interface Kvs {
+    open
+    flush_on_exit
+    reset
+    get_all_keys
+    key_exists
+    get_value
+    get_default_value
+    has_default_value
+    set_default_value
+    set_value
+    remove_key
+    flush
+    snapshot_count
+    snapshot_max_count
+    snapshot_restore
+    get_kvs_filename
+    get_hash_filename
+}
+
+@enduml

docs/features/persistency/kvs/architecture/_assets/kvs_static_view.puml

@@ -0,0 +1,32 @@
+@startuml
+allowmixing
+
+title Static View - kvs
+
+!include kvs_interface.puml
+
+
+skinparam package {
+    BackgroundColor #E0E0D0
+    BorderColor Black
+    backgroundColor<<feature>> yellow
+}
+
+skinparam component {
+    backgroundColor<<component>> white
+}
+
+' Define Features
+package "kvs" <<feature>> {
+    component kvs <<component>>
+    component fs <<component>>
+    component tiny_json <<component>>
+}
+
+kvs -u- Kvs
+
+kvs  ..>  tiny_json : use
+kvs  ..>  fs : use
+
+
+@enduml