Skip to content

Commit 0f54c8d

Browse files
sbachmann-qorixsbachmann-qorix
committed
persistency_kvs: add component architecture
Signed-off-by: Sven Bachmann <[email protected]>
1 parent 93e2613 commit 0f54c8d

File tree

3 files changed

+217
-124
lines changed

3 files changed

+217
-124
lines changed

‎docs/features/persistency/key-value-storage/architecture/component_architecture.rst

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
Component Architecture
16+
######################
17+
18+
Technical Concept Description
19+
*****************************
20+
21+
The key-value-storage feature (KVS) scope is very small so only the KVS itself
22+
and a another component to handle the persistent storage format are defined.
23+
24+
The API is stable for major version releases. Any changes are discussed in the
25+
CFT. Whenever possible, the existing API is not changed and new functionality
26+
is provided by new function calls.
27+
28+
Key-Value-Storage (KVS)
29+
=======================
30+
31+
The KVS is presented like a dictonary or hashmap implementation to the
32+
application with some extra APIs for flushing data, handling snapshots and
33+
other functionality. All API functions guarantee to not panic or throw
34+
exceptions that can't be handled. Error handling has one of the highest
35+
priorities.
36+
37+
All actions are log- and traceable. The component supports productive and
38+
develop environments.
39+
40+
The KVS is multi-threading safe and allows concurrent access to the same store.
41+
Tracking changes can be done by subscribing to specified keys or the whole
42+
store.
43+
44+
Values that are stored behind the keys can be numbers, text, null, arrays or
45+
objects. Objects and arrays can be used to nest values.
46+
47+
A snapshot logic ensures rollback capabilities if something goes wrong.
48+
49+
TinyJSON
50+
========
51+
52+
TinyJSON is used to serialize and deserialize the data as the well-known format
53+
JSON to and from the permanent storage.

‎docs/features/persistency/key-value-storage/architecture/feature_architecture.rst

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
Feature Architecture : persistency/key_val_storage
16+
==================================================
17+
18+
Overview
19+
--------
20+
21+
- key_val_storage provides the capability to efficiently store, retrieve, and
22+
manage key-value pairs in a persistent storage system.
23+
24+
Description
25+
-----------
26+
27+
- key_val_storage organize data as pairs, where each unique key is associated with a specific value.
28+
The key acts as a unique identifier for getting the value.
29+
- The data is persisted in JSON format to the file system, providing a human-readable,
30+
and widely supported way to store and manage key-value pairs.
31+
- The JSON data persisted is according to RFC-8259.
32+
33+
Rationale Behind Architecture Decomposition
34+
*******************************************
35+
36+
- The architecture is decomposed to include a dedicated JSON parser component (TinyJSON) to facilitate the persistent storage of data in JSON format.
37+
- The architecture is decomposed to include a FileStorage component (fs) to read and write to the file system.
38+
39+
40+
Static Architecture
41+
-------------------
42+
43+
.. feat_arc_sta:: Static Architecture
44+
:id: FEAT_ARC_STA__persistency_key_val_storage__key_value_storage
45+
:security: YES
46+
:safety: ASIL_B
47+
:satisfies: FEAT_REQ__KVS__safety_asil_b
48+
:status: valid
49+
50+
.. uml:: _assets/kvs_static_view.puml
51+
52+
Dynamic Architecture
53+
--------------------
54+
55+
.. feat_arc_dyn:: KVS Builder
56+
:id: FEAT_ARC_DYN__persistency_key_val_storage__builder_pattern
57+
:security: YES
58+
:safety: ASIL_B
59+
:satisfies: FEAT_REQ__KVS__safety_asil_b
60+
:status: valid
61+
62+
.. uml:: _assets/kvs_dyn_builder.puml
63+
64+
.. feat_arc_dyn:: Check if key contains default value
65+
:id: FEAT_ARC_DYN__persistency_key_val_storage__check_key_default_value
66+
:security: YES
67+
:safety: ASIL_B
68+
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__default_values,FEAT_REQ__KVS__default_value_retrieval
69+
:status: valid
70+
71+
.. uml:: _assets/kvs_dyn_check_value_default.puml
72+
73+
.. feat_arc_dyn:: Delete key from KVS instance
74+
:id: FEAT_ARC_DYN__persistency_key_val_storage__delete_key
75+
:security: YES
76+
:safety: ASIL_B
77+
:satisfies: FEAT_REQ__KVS__safety_asil_b
78+
:status: valid
79+
80+
.. uml:: _assets/kvs_dyn_delete_data_key.puml
81+
82+
.. feat_arc_dyn:: Flush to permanent storage
83+
:id: FEAT_ARC_DYN__persistency_key_val_storage__flush
84+
:security: YES
85+
:safety: ASIL_B
86+
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__persist_data,FEAT_REQ__KVS__persistency,FEAT_REQ__KVS__snapshots,FEAT_REQ__KVS__integrity_check,FEAT_REQ__KVS__snapshots
87+
:status: valid
88+
89+
.. uml:: _assets/kvs_dyn_flush_local_repr_to_file.puml
90+
91+
.. feat_arc_dyn:: Read key value
92+
:id: FEAT_ARC_DYN__persistency_key_val_storage__read_key
93+
:security: YES
94+
:safety: ASIL_B
95+
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__supported_datatypes_keys,FEAT_REQ__KVS__supported_datatypes_values,FEAT_REQ__KVS__default_values,FEAT_REQ__KVS__default_value_retrieval
96+
:status: valid
97+
98+
.. uml:: _assets/kvs_dyn_read_data_key.puml
99+
100+
.. feat_arc_dyn:: Read data from permanent storage
101+
:id: FEAT_ARC_DYN__persistency_key_val_storage__read_data_from_perm_storage
102+
:security: YES
103+
:safety: ASIL_B
104+
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__persist_data,FEAT_REQ__KVS__persistency,FEAT_REQ__KVS__integrity_check,FEAT_REQ__KVS__snapshots
105+
:status: valid
106+
107+
.. uml:: _assets/kvs_dyn_read_file_into_local_repr.puml
108+
109+
.. feat_arc_dyn:: Write value to key
110+
:id: FEAT_ARC_DYN__persistency_key_val_storage__write_key
111+
:security: YES
112+
:safety: ASIL_B
113+
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__supported_datatypes_keys,FEAT_REQ__KVS__supported_datatypes_values
114+
:status: valid
115+
116+
.. uml:: _assets/kvs_dyn_write_data_key.puml
117+
118+
.. feat_arc_dyn:: Restore snapshop
119+
:id: FEAT_ARC_DYN__persistency_key_val_storage__snapshot_restore
120+
:security: YES
121+
:safety: ASIL_B
122+
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__snapshots,FEAT_REQ__KVS__persist_data,FEAT_REQ__KVS__persistency
123+
:status: valid
124+
125+
.. uml:: _assets/kvs_dyn_restore_snapshot.puml
126+
127+
128+
Logical Interfaces
129+
------------------
130+
131+
.. feat_arc_int:: Ikvs
132+
:id: FEAT_ARC_INT__persistency_key_val_storage__keyvaluestorage
133+
:security: YES
134+
:safety: ASIL_B
135+
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__stable_api
136+
:status: valid
137+
138+
.. uml:: _assets/kvs_interface.puml

‎docs/features/persistency/key-value-storage/architecture/index.rst

+26-124
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,26 @@
1-
Feature Architecture : persistency/key_val_storage
2-
==================================================
3-
4-
Overview
5-
--------
6-
7-
- key_val_storage provides the capability to efficiently store, retrieve, and
8-
manage key-value pairs in a persistent storage system.
9-
10-
Description
11-
-----------
12-
13-
- key_val_storage organize data as pairs, where each unique key is associated with a specific value.
14-
The key acts as a unique identifier for getting the value.
15-
- The data is persisted in JSON format to the file system, providing a human-readable,
16-
and widely supported way to store and manage key-value pairs.
17-
- The JSON data persisted is according to RFC-8259.
18-
19-
Rationale Behind Architecture Decomposition
20-
*******************************************
21-
22-
- The architecture is decomposed to include a dedicated JSON parser component (TinyJSON) to facilitate the persistent storage of data in JSON format.
23-
- The architecture is decomposed to include a FileStorage component (fs) to read and write to the file system.
24-
25-
26-
Static Architecture
27-
-------------------
28-
29-
.. feat_arc_sta:: Static Architecture
30-
:id: FEAT_ARC_STA__persistency_key_val_storage__key_value_storage
31-
:security: YES
32-
:safety: ASIL_B
33-
:satisfies: FEAT_REQ__KVS__safety_asil_b
34-
:status: valid
35-
36-
.. uml:: _assets/kvs_static_view.puml
37-
38-
Dynamic Architecture
39-
--------------------
40-
41-
.. feat_arc_dyn:: KVS Builder
42-
:id: FEAT_ARC_DYN__persistency_key_val_storage__builder_pattern
43-
:security: YES
44-
:safety: ASIL_B
45-
:satisfies: FEAT_REQ__KVS__safety_asil_b
46-
:status: valid
47-
48-
.. uml:: _assets/kvs_dyn_builder.puml
49-
50-
.. feat_arc_dyn:: Check if key contains default value
51-
:id: FEAT_ARC_DYN__persistency_key_val_storage__check_key_default_value
52-
:security: YES
53-
:safety: ASIL_B
54-
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__default_values,FEAT_REQ__KVS__default_value_retrieval
55-
:status: valid
56-
57-
.. uml:: _assets/kvs_dyn_check_value_default.puml
58-
59-
.. feat_arc_dyn:: Delete key from KVS instance
60-
:id: FEAT_ARC_DYN__persistency_key_val_storage__delete_key
61-
:security: YES
62-
:safety: ASIL_B
63-
:satisfies: FEAT_REQ__KVS__safety_asil_b
64-
:status: valid
65-
66-
.. uml:: _assets/kvs_dyn_delete_data_key.puml
67-
68-
.. feat_arc_dyn:: Flush to permanent storage
69-
:id: FEAT_ARC_DYN__persistency_key_val_storage__flush
70-
:security: YES
71-
:safety: ASIL_B
72-
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__persist_data,FEAT_REQ__KVS__persistency,FEAT_REQ__KVS__snapshots,FEAT_REQ__KVS__integrity_check,FEAT_REQ__KVS__snapshots
73-
:status: valid
74-
75-
.. uml:: _assets/kvs_dyn_flush_local_repr_to_file.puml
76-
77-
.. feat_arc_dyn:: Read key value
78-
:id: FEAT_ARC_DYN__persistency_key_val_storage__read_key
79-
:security: YES
80-
:safety: ASIL_B
81-
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__supported_datatypes_keys,FEAT_REQ__KVS__supported_datatypes_values,FEAT_REQ__KVS__default_values,FEAT_REQ__KVS__default_value_retrieval
82-
:status: valid
83-
84-
.. uml:: _assets/kvs_dyn_read_data_key.puml
85-
86-
.. feat_arc_dyn:: Read data from permanent storage
87-
:id: FEAT_ARC_DYN__persistency_key_val_storage__read_data_from_perm_storage
88-
:security: YES
89-
:safety: ASIL_B
90-
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__persist_data,FEAT_REQ__KVS__persistency,FEAT_REQ__KVS__integrity_check,FEAT_REQ__KVS__snapshots
91-
:status: valid
92-
93-
.. uml:: _assets/kvs_dyn_read_file_into_local_repr.puml
94-
95-
.. feat_arc_dyn:: Write value to key
96-
:id: FEAT_ARC_DYN__persistency_key_val_storage__write_key
97-
:security: YES
98-
:safety: ASIL_B
99-
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__supported_datatypes_keys,FEAT_REQ__KVS__supported_datatypes_values
100-
:status: valid
101-
102-
.. uml:: _assets/kvs_dyn_write_data_key.puml
103-
104-
.. feat_arc_dyn:: Restore snapshop
105-
:id: FEAT_ARC_DYN__persistency_key_val_storage__snapshot_restore
106-
:security: YES
107-
:safety: ASIL_B
108-
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__snapshots,FEAT_REQ__KVS__persist_data,FEAT_REQ__KVS__persistency
109-
:status: valid
110-
111-
.. uml:: _assets/kvs_dyn_restore_snapshot.puml
112-
113-
114-
Logical Interfaces
115-
------------------
116-
117-
.. feat_arc_int:: Ikvs
118-
:id: FEAT_ARC_INT__persistency_key_val_storage__keyvaluestorage
119-
:security: YES
120-
:safety: ASIL_B
121-
:satisfies: FEAT_REQ__KVS__safety_asil_b,FEAT_REQ__KVS__stable_api
122-
:status: valid
123-
124-
.. uml:: _assets/kvs_interface.puml
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
Architecture
16+
#############
17+
18+
.. note::
19+
For now we store the component architecture in the feature tree, because multi-repo docs are not yet supported.
20+
Once this support becomes available the component architecture will be moved to the module.
21+
22+
.. toctree::
23+
:titlesonly:
24+
25+
feature_architecture
26+
component_architecture

0 commit comments

Comments
 (0)