docs: clarify Varlink input and output policy
(cherry picked from commit 1c754bf06e1369c39abcff411a317a058e9b0b91)
This commit is contained in:
committed by
Luca Boccassi
parent
fa22119295
commit
3e39c54632
+12
-4
@@ -33,10 +33,10 @@ SPDX-License-Identifier: LGPL-2.1-or-later
|
||||
data that other functions can later consume to create a similar object.
|
||||
|
||||
Example: `io.systemd.Unit.List` outputs unit configuration, which can later
|
||||
be reused to create another unit via `io.systemd.Unit.StartTransient` (not
|
||||
implemented yet). The `io.systemd.Unit.StartTransient` call should accept
|
||||
only the 'context' portion of the output, without requiring any runtime data
|
||||
such as state (e.g. pid) or statistics.
|
||||
be reused to create another unit via `io.systemd.Unit.StartTransient`.
|
||||
The `io.systemd.Unit.StartTransient` call should accept only the 'context'
|
||||
portion of the output, without requiring any runtime data such as state
|
||||
(e.g. pid) or statistics.
|
||||
|
||||
- Following the guideline above, any field within 'context' should be nullable
|
||||
by default. This ensures that when a context structure is used as input, the
|
||||
@@ -46,6 +46,14 @@ SPDX-License-Identifier: LGPL-2.1-or-later
|
||||
Fields that cannot logically be omitted in input (e.g. a unit type) may remain
|
||||
non-nullable.
|
||||
|
||||
- Input may accept multiple representations of the same information. Output
|
||||
should be normalized and must not include the same information in multiple
|
||||
forms. Every output field in a reusable context must be accepted on input,
|
||||
so that the context can be fed back without conversion or removal of fields.
|
||||
For example, the context returned by `io.systemd.Unit.List` must be usable
|
||||
as input to `io.systemd.Unit.StartTransient`. The same principle applies to
|
||||
other interfaces that share structures between output and input.
|
||||
|
||||
# Enums
|
||||
|
||||
- Enum fields in the codebase must be exposed as string values in Varlink, not
|
||||
|
||||
Reference in New Issue
Block a user