Skip to content

Commit b11a480

Browse files
sbachmann-qorixsbachmann-qorix
committed
persistency_kvs: component requirements
Signed-off-by: Sven Bachmann <sven.bachmann.ext@qorix.ai>
1 parent 224320b commit b11a480

File tree

3 files changed

+556
-333
lines changed

3 files changed

+556
-333
lines changed

‎docs/features/persistency/kvs/requirements/component_requirements.rst‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
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 Requirements
16+
######################
17+
18+
.. comp_req:: Key Handling
19+
:id: comp_req__kvs__key_handling
20+
:reqtype: Functional
21+
:security: NO
22+
:safety: ASIL_B
23+
:satisfies: feat_req__kvs__supported_datatypes_keys
24+
:status: valid
25+
26+
The key must contain only alphanumerical characters, underscores and dashes.
27+
The key must be valid UTF-8.
28+
The key must be unique.
29+
The key must have a maximum length of 32 bytes.
30+
31+
.. comp_req:: Value Handling
32+
:id: comp_req__kvs__value_handling
33+
:reqtype: Functional
34+
:security: NO
35+
:safety: ASIL_B
36+
:satisfies: feat_req__kvs__supported_datatypes_values,feat_req__kvs__default_values
37+
:status: valid
38+
39+
The value must have one of these datatypes: Number, String, Null, Array[Value], Dictionary{Key:Value}.
40+
The value must be serializeable and deserializeable to JSON.
41+
The value must have a maximum length of 1024 bytes.
42+
The value can be no-set and provide a default value for this case.
43+
If the value has a default value assigned it must be resetable to the default value.
44+
45+
.. comp_req:: Default Value Handling
46+
:id: comp_req__kvs__default_value_handling
47+
:reqtype: Functional
48+
:security: NO
49+
:safety: QM
50+
:satisfies: feat_req__kvs__default_values,feat_req__kvs__default_value_retrieval,feat_req__kvs__default_value_reset,feat_req__kvs__default_value_file
51+
:status: valid
52+
53+
The default value can be available.
54+
The default value must contain any of the valid value datatypes.
55+
The default value must be retrieval through an extra API.
56+
The default value must be configurable either in code or in a separate file.
57+
If the default value is stored in a file the file must be secured by a checksum file.
58+
59+
.. comp_req:: Constraint Configuration
60+
:id: comp_req__kvs__constraints
61+
:reqtype: Functional
62+
:security: NO
63+
:safety: QM
64+
:satisfies: feat_req__kvs__maximum_size,feat_req__kvs__config_file
65+
:status: valid
66+
67+
The key-value-storage constraints must be configurable at compile-time
68+
through source code constants or dynamically at runtime with a config file.
69+
70+
.. comp_req:: Language Agnostic
71+
:id: comp_req__kvs__language_agnostic
72+
:reqtype: Functional
73+
:security: NO
74+
:safety: QM
75+
:satisfies: feat_req__kvs__cpp_rust_interoperability
76+
:status: valid
77+
78+
The key-value-storage must either provide an API that can be bind to other
79+
languages or use a storage and memory exchange-format that can be adapted to
80+
other languages.
81+
82+
.. comp_req:: Concurrency
83+
:id: comp_req__kvs__concurrency
84+
:reqtype: Functional
85+
:security: NO
86+
:safety: QM
87+
:satisfies: feat_req__kvs__thread_safety,feat_req__kvs__intra_process_comm
88+
:status: valid
89+
90+
The key-value-storage must implement thread-safe mechanisms to allow
91+
concurrent access to the data without data races.
92+
93+
.. comp_req:: Multi-Instance
94+
:id: comp_req__kvs__multi_instance
95+
:reqtype: Functional
96+
:security: NO
97+
:safety: ASIL_B
98+
:satisfies: feat_req__kvs__multiple_kvs
99+
:status: valid
100+
101+
The key-value-storage must manage all runtime variables in an instance so
102+
that multiple instances with different key-value-stores can be spawned and
103+
used at the same time per software architecture element.
104+
105+
.. comp_req:: Persistent Data Storage
106+
:id: comp_req__kvs__persistent_data_storage
107+
:reqtype: Functional
108+
:security: NO
109+
:safety: QM
110+
:satisfies: feat_req__kvs__persistency,feat_req__kvs__integrity_check,feat_req__kvs__persist_data
111+
:status: valid
112+
113+
The key-value-storage must use the file API and the JSON data format for
114+
persistent data storage.
115+
A checksum must be build over the data file and stored next to the data.
116+
On data load the checksum must be verified.
117+
118+
.. comp_req:: Persistent Data Schema Handling
119+
:id: comp_req__kvs__persistent_data_schema
120+
:reqtype: Functional
121+
:security: NO
122+
:safety: ASIL_B
123+
:satisfies: feat_req__kvs__versioning,feat_req__kvs__update_mechanism
124+
:status: valid
125+
126+
The key-value-storage doesn't support versioning directly.
127+
The used JSON file storage format allows the application to implement
128+
versioning, including up- and down-paths, by itself.
129+
130+
.. comp_req:: Snapshots
131+
:id: comp_req__kvs__snapshots
132+
:reqtype: Functional
133+
:security: NO
134+
:safety: ASIL_B
135+
:satisfies: feat_req__kvs__snapshots
136+
:status: valid
137+
138+
The key-value-storage must write a snapshot whenever the data is stored.
139+
It must maintain a configurable maximum number of snapshots.
140+
Each new snapshot has id 1 and all older snapshots get their id increased..
141+
After the maximum snapshot number is reached the snapshots are rotated and the oldest snapshot is dropped.
142+
Each snapshot can be restored by it's id.
143+
Snapshots must be deletable.
144+
145+
.. comp_req:: Develop Mode
146+
:id: comp_req__kvs__dev_mode
147+
:reqtype: Functional
148+
:security: NO
149+
:safety: ASIL_B
150+
:satisfies: feat_req__kvs__dev_mode
151+
:status: valid
152+
153+
The key-value-storage must provide a developer mode which can be enabled
154+
during build time. This mode can be used to show debug and other internal
155+
information.
156+
157+
.. comp_req:: Async API
158+
:id: comp_req__kvs__async_api
159+
:reqtype: Functional
160+
:security: NO
161+
:safety: QM
162+
:satisfies: feat_req__kvs__async_api
163+
:status: valid
164+
165+
Additional to the normal API the key-value-storage must provide an Async
166+
API.
167+
168+
.. comp_req:: Permission Handling
169+
:id: comp_req__kvs__permission_handling
170+
:reqtype: Functional
171+
:security: NO
172+
:safety: QM
173+
:satisfies: feat_req__kvs__access_control
174+
:status: valid
175+
176+
The key-value-storage must not implement access and permission handling.
177+
This is left to the underlying filesystem implementation.
178+
The key-value-storage must report access and permission errors that are
179+
thrown by the filesystem to the application.
180+
181+
.. comp_req:: Callback Support
182+
:id: comp_req__kvs__callback_support
183+
:reqtype: Functional
184+
:security: NO
185+
:safety: ASIL_B
186+
:satisfies: feat_req__kvs__events
187+
:status: valid
188+
189+
The key-value-storage must provide an API to register callbacks for
190+
data-change events.
191+
192+
.. comp_req:: Logging & Tracing
193+
:id: comp_req__kvs__log_trace
194+
:reqtype: Functional
195+
:security: NO
196+
:safety: QM
197+
:satisfies: feat_req__kvs__log_trace
198+
:status: valid
199+
200+
The key-value-storage must use the S-CORE provided logging and tracing
201+
framework.

0 commit comments

Comments
 (0)