Skip to content

Commit 3f1dd06

Browse files
hug-devhug-dev
authored
Merge pull request #108 from hug-dev/stability
Add a Parsec Stability page
2 parents eab202e + 949effd commit 3f1dd06

File tree

3 files changed

+79
-0
lines changed

3 files changed

+79
-0
lines changed

‎src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@
5757
- [Parsec Configuration](parsec_service/configuration.md)
5858
- [How to test Parsec](parsec_service/tests/README.md)
5959
- [List of existing tests](parsec_service/tests/existing_tests.md)
60+
- [Parsec Stability](parsec_service/stability.md)
6061
- [Parsec Security](parsec_security/README.md)
6162
- [Parsec Threat Model](parsec_security/parsec_threat_model/threat_model.md)
6263
- [Recommendations for Secure Deployment](parsec_security/secure_deployment.md)

‎src/parsec_service/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,5 +20,6 @@ They cover the following concepts:
2020
- [Configuration](configuration.md) - how to configure Parsec
2121
- [Testing](tests) - details about the kinds of tests we employ and how to set up your environment
2222
in preparation for running them
23+
- [Stability](stability.md) - how stability is ensured in the Parsec service
2324

2425
*Copyright 2019 Contributors to the Parsec project.*

‎src/parsec_service/stability.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Parsec Stability
2+
3+
Work in progress, see the [related issue](https://github.com/parallaxsecond/parsec-book/issues/83).
4+
5+
## Why is stability important?
6+
7+
Parsec is a long-running service that will be configured, deployed, upgraded and maintained over a
8+
long period of time. The environment will also have client applications that are calling it, and
9+
persistent state that is collected on storage. Components will be upgraded over time. For Parsec to
10+
be supportable in enterprise system, it must not be brittle against upgrades. If Parsec is upgraded
11+
and restarted, client applications should continue working, and all persistent state from prior
12+
versions should remain valid and usable.
13+
14+
## What does stability mean for the Parsec service?
15+
16+
The following definition of stability is chosen for the Parsec service: *whatever two versions A and
17+
B of the Parsec binary, B being newer than A, A and B are stable if A can be removed and replaced by
18+
B without breaking anything*.
19+
20+
Note that we are not looking at stability in the reverse direction: B cannot be replaced by A
21+
without breaking anything. The only exception is for the communication channel with clients where
22+
any version of the client library can successfully communicate with any version of the service.
23+
24+
The principle of [semantic versioning](https://semver.org/) is used to describe the stability of
25+
Parsec versions and when breaking changes are done. If `parsec` version is at `1.0.0` then all
26+
future stable version to that will be `1.x.y`. Note that, although semver is used to describe Parsec
27+
stability, it is a strong goal for Parsec to remain stable at a `1.x.y` version. This document
28+
introduces the efforts that are made so that a `MAJOR` version bump should hopefully never happen.
29+
30+
## What needs to be stable?
31+
32+
With the above definition, Parsec stays stable if it keeps the exact same communication channels and
33+
format with its environment. Those are already described in the [dataflow
34+
diagram](../parsec_security/parsec_threat_model/threat_model.md#dataflow-diagram) in the threat
35+
model.
36+
37+
The communication channels that need to be stable are (some of them are not in the diagram):
38+
39+
1. Communication with clients
40+
1. Definition of requests/responses (their format)
41+
2. Definition of operation contracts (their intended behaviour)
42+
3. Definition of Listeners endpoints (how to contact Parsec)
43+
2. Communication with authenticators
44+
3. Communication received from the CLI invocation
45+
4. Configuration file (including default configuration options)
46+
5. Persistent data stored internally
47+
1. Key mappings
48+
6. OS signals
49+
7. systemd communication
50+
8. Dynamic libraries dependencies
51+
52+
Those will be described as "stability requirement" in the remainder of this document. As new
53+
features are added to the codebase, new stability requirements might appear. Those should be added
54+
to the list above and looked in detail below.
55+
56+
## Stability Review
57+
58+
Let's look at each of the points above and check:
59+
60+
- what stability exactly means
61+
- how stability is ensured
62+
- how stability is tested
63+
64+
| Stability Requirement | Stability Definition | Stability Enforcement | Stability Test |
65+
|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|
66+
| Communication with clients (requests/responses) | Requests and responses must be understood correctly by different versions of the service/clients. | The Wire Protocol is [stable by design](../parsec_client/wire_protocol.md#wire-protocol-versions). | TODO |
67+
| Communication with clients (operation contracts) | The behaviour of operations must remain the same for all versions of the service. | There is a [defined behaviour](https://parallaxsecond.github.io/parsec-book/parsec_client/operations/index.html) for all operations that is respected. | TODO |
68+
| Communication with clients (listeners endpoint) | Listeners endpoint must be discovered in a stable way. | A [service discovery mechanism](../parsec_client/api_overview.md#service-discovery) exists. | TODO |
69+
| Authenticators | Authentication requests sent by future stable versions of Parsec should be understood by the same version of the authenticators present on the system. | Unix Peer Crendentials: based on top of stable C standard library APIs. JWT SVID: authentication is based on the [SPIFFE Workload API](https://github.com/spiffe/spiffe/blob/master/standards/SPIFFE_Workload_API.md) which is a standard and should remain stable. | TODO |
70+
| CLI invocation | Old CLI invocations of Parsec should still work with for future stable Parsec versions. | CLI flags should not be removed. New flags should be optional. | TODO |
71+
| Configuration file | Old configuration files should still work with future stable Parsec versions, with the same default for optional options. | Configuration options should not disappear in future stable Parsec versions. Configuration defaults should remain the same. New options should be optional. | TODO |
72+
| Persistent state (key mappings) | Old key mappings should still be read correctly by future stable Parsec versions. | The way the KIM persistently stores the mappings need to be backward-compatible in regards with reading/writing. | TODO |
73+
| OS signals | OS signals should still have the same behaviour in future stable Parsec versions. | Signal handlers must not be removed in Parsec. | TODO |
74+
| systemd communication | systemd should receive the same status information from Parsec in future stable versions. | Status notifications must not be removed. | TODO |
75+
| Dynamic libraries dependencies | Linking and loading the same versions of libraries should still work in future stable versions of Parsec. | Stable versions of Parsec should not require newer dependencies. | TODO |
76+
77+
*Copyright 2021 Contributors to the Parsec project.*

0 commit comments

Comments
 (0)