system-runtime-spec 0.1.0__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. {system_runtime_spec-0.1.0 → system_runtime_spec-0.2.0}/.gitignore +1 -0
  2. system_runtime_spec-0.2.0/PKG-INFO +130 -0
  3. system_runtime_spec-0.2.0/README.md +115 -0
  4. {system_runtime_spec-0.1.0 → system_runtime_spec-0.2.0}/pyproject.toml +3 -3
  5. system_runtime_spec-0.2.0/system_runtime_spec/__init__.py +22 -0
  6. system_runtime_spec-0.2.0/system_runtime_spec/_clock.py +42 -0
  7. system_runtime_spec-0.1.0/system_runtime/components.py → system_runtime_spec-0.2.0/system_runtime_spec/_compatibility.py +35 -39
  8. system_runtime_spec-0.2.0/system_runtime_spec/_decoding.py +319 -0
  9. system_runtime_spec-0.2.0/system_runtime_spec/_discovery.py +262 -0
  10. system_runtime_spec-0.2.0/system_runtime_spec/_evaluation.py +361 -0
  11. system_runtime_spec-0.2.0/system_runtime_spec/_records.py +221 -0
  12. system_runtime_spec-0.2.0/system_runtime_spec/_snapshot.py +162 -0
  13. system_runtime_spec-0.2.0/system_runtime_spec/_version.py +140 -0
  14. {system_runtime_spec-0.1.0/system_runtime → system_runtime_spec-0.2.0/system_runtime_spec}/models/__init__.py +3 -2
  15. {system_runtime_spec-0.1.0/system_runtime → system_runtime_spec-0.2.0/system_runtime_spec}/models/_sidex.py +1 -1
  16. system_runtime_spec-0.2.0/system_runtime_spec/models/common.py +28 -0
  17. {system_runtime_spec-0.1.0/system_runtime → system_runtime_spec-0.2.0/system_runtime_spec}/models/component.py +55 -48
  18. system_runtime_spec-0.2.0/system_runtime_spec/models/filesystem.py +48 -0
  19. system_runtime_spec-0.2.0/system_runtime_spec/models/health.py +181 -0
  20. system_runtime_spec-0.2.0/system_runtime_spec/models/metric.py +61 -0
  21. system_runtime_spec-0.2.0/tests/test_conformance.py +178 -0
  22. system_runtime_spec-0.2.0/tests/test_readme.py +12 -0
  23. {system_runtime_spec-0.1.0 → system_runtime_spec-0.2.0}/uv.lock +1 -1
  24. system_runtime_spec-0.1.0/PKG-INFO +0 -186
  25. system_runtime_spec-0.1.0/README.md +0 -171
  26. system_runtime_spec-0.1.0/system_runtime/__init__.py +0 -22
  27. system_runtime_spec-0.1.0/system_runtime/_version.py +0 -86
  28. system_runtime_spec-0.1.0/system_runtime/clock.py +0 -35
  29. system_runtime_spec-0.1.0/system_runtime/filesystem.py +0 -168
  30. system_runtime_spec-0.1.0/system_runtime/health.py +0 -186
  31. system_runtime_spec-0.1.0/system_runtime/models/filesystem.py +0 -39
  32. system_runtime_spec-0.1.0/system_runtime/models/health.py +0 -172
  33. system_runtime_spec-0.1.0/system_runtime/models/value.py +0 -105
  34. system_runtime_spec-0.1.0/system_runtime/snapshot.py +0 -24
  35. system_runtime_spec-0.1.0/system_runtime/threshold.py +0 -150
  36. system_runtime_spec-0.1.0/tests/test_conformance.py +0 -246
  37. system_runtime_spec-0.1.0/tests/test_ownership_clock.py +0 -87
  38. {system_runtime_spec-0.1.0 → system_runtime_spec-0.2.0}/LICENSE-APACHE +0 -0
  39. {system_runtime_spec-0.1.0 → system_runtime_spec-0.2.0}/LICENSE-MIT +0 -0
  40. {system_runtime_spec-0.1.0/system_runtime → system_runtime_spec-0.2.0/system_runtime_spec}/models/py.typed +0 -0
  41. {system_runtime_spec-0.1.0/system_runtime → system_runtime_spec-0.2.0/system_runtime_spec}/py.typed +0 -0
@@ -8,3 +8,4 @@
8
8
  **/dist/
9
9
  **/*.egg-info/
10
10
  *.tgz
11
+ *.cdx.json
@@ -0,0 +1,130 @@
1
+ Metadata-Version: 2.5
2
+ Name: system-runtime-spec
3
+ Version: 0.2.0
4
+ Summary: System component compatibility, health evaluation, and filesystem discovery.
5
+ Project-URL: Repository, https://github.com/rugix/system-runtime-spec
6
+ Project-URL: Documentation, https://github.com/rugix/system-runtime-spec#readme
7
+ Project-URL: Issues, https://github.com/rugix/system-runtime-spec/issues
8
+ Author-email: Silitics GmbH <info@silitics.com>
9
+ License-Expression: MIT OR Apache-2.0
10
+ License-File: LICENSE-APACHE
11
+ License-File: LICENSE-MIT
12
+ Requires-Python: >=3.12
13
+ Requires-Dist: pydantic<3,>=2.11
14
+ Description-Content-Type: text/markdown
15
+
16
+ # System Runtime Specification for Python
17
+
18
+ `system-runtime-spec` implements the
19
+ [System Runtime Specification](https://github.com/rugix/system-runtime-spec/blob/main/SPEC.md)
20
+ in Python: it discovers records on Linux, checks the compatibility of compositions and updates,
21
+ evaluates health, and sends records to other systems as snapshots.
22
+
23
+ ## Installation
24
+
25
+ Python 3.12 or later is required:
26
+
27
+ ```sh
28
+ python -m pip install system-runtime-spec
29
+ ```
30
+
31
+ Import the package as `system_runtime_spec`. `Records` holds the records of a system and the
32
+ diagnostics about them. The Pydantic models in `system_runtime_spec.models` are generated from the
33
+ specification's schemas.
34
+
35
+ ## Read and Check a System
36
+
37
+ ```python
38
+ from system_runtime_spec import Records, current_context
39
+
40
+ records = Records.discover("/")
41
+ compatibility = records.check_compatibility()
42
+ health = records.evaluate_health(current_context())
43
+ print("consistent:", compatibility.consistent)
44
+ for result in health.results:
45
+ print(f"{result.id}: usable {result.usable}, healthy {result.healthy}")
46
+ ```
47
+
48
+ `Records.discover` reads the standard directories and the directories that directory
49
+ configurations add, and applies overrides. Files that cannot be read or do not contain a valid
50
+ record are skipped and reported as diagnostics. Reports take the diagnostics of their part into
51
+ account: an error about component declarations makes a composition inconsistent, and a decision
52
+ should not rely on a health report with errors about health nodes or directory configurations.
53
+
54
+ ## Add Records in Code
55
+
56
+ `push` adds a record given as a model, and `push_json` one given as JSON, such as a record
57
+ received from another system. Both validate the record and skip it with an error diagnostic if it
58
+ is invalid:
59
+
60
+ ```python
61
+ from system_runtime_spec import Records
62
+ from system_runtime_spec.models.component import (
63
+ CapabilitySelectorDeclaration,
64
+ ComponentDeclaration,
65
+ )
66
+
67
+ records = Records()
68
+ records.push(ComponentDeclaration(id="os", version="2.1"))
69
+ records.push(
70
+ ComponentDeclaration(
71
+ id="app",
72
+ requires=[CapabilitySelectorDeclaration(id="os", version=">=2")],
73
+ )
74
+ )
75
+ records.push_json(ComponentDeclaration, {"id": "tool"})
76
+ assert records.check_compatibility().consistent
77
+ ```
78
+
79
+ ## Check an Update
80
+
81
+ `with_update` builds the composition that an update would produce: it replaces all component
82
+ declarations of the given owners with those of the update.
83
+
84
+ ```python
85
+ from system_runtime_spec import Records
86
+ from system_runtime_spec.models.component import ComponentDeclaration
87
+
88
+ records = Records.discover("/")
89
+ update = Records()
90
+ update.push(ComponentDeclaration(id="os", owner="rugix.system", version="2.0"))
91
+ candidate = records.with_update(["rugix.system"], update)
92
+ print("consistent:", candidate.check_compatibility().consistent)
93
+ ```
94
+
95
+ ## Send Records as a Snapshot
96
+
97
+ A `Snapshot` contains the original records, so the receiving system evaluates them as the sending
98
+ system read them. Take the clock sample after reading the records:
99
+
100
+ ```python
101
+ import json
102
+
103
+ from system_runtime_spec import (
104
+ Records,
105
+ Snapshot,
106
+ current_clock_sample,
107
+ estimate_timestamp,
108
+ )
109
+
110
+ records = Records.discover("/")
111
+ payload = json.dumps(Snapshot(records, current_clock_sample()).to_json())
112
+
113
+ # On the receiving system:
114
+ received = Snapshot.from_json(json.loads(payload))
115
+ report = received.records.evaluate_health(received.clock.context)
116
+ for status in received.records.health_statuses:
117
+ print(status.id, estimate_timestamp(received.clock, status))
118
+ ```
119
+
120
+ `Snapshot` takes `components=False` or `health=False` to leave out a part. `Snapshot.from_json`
121
+ raises a `SnapshotError` for snapshots of an unsupported version or with an invalid structure.
122
+ Evaluating a snapshot gives health at the time of its clock sample, and `estimate_timestamp`
123
+ places evidence in wall-clock time for display.
124
+
125
+ `Records.discover`, `current_context`, and `current_clock_sample` are available on Linux only.
126
+
127
+ ## License
128
+
129
+ Available under either the [MIT License](LICENSE-MIT) or the
130
+ [Apache License 2.0](LICENSE-APACHE).
@@ -0,0 +1,115 @@
1
+ # System Runtime Specification for Python
2
+
3
+ `system-runtime-spec` implements the
4
+ [System Runtime Specification](https://github.com/rugix/system-runtime-spec/blob/main/SPEC.md)
5
+ in Python: it discovers records on Linux, checks the compatibility of compositions and updates,
6
+ evaluates health, and sends records to other systems as snapshots.
7
+
8
+ ## Installation
9
+
10
+ Python 3.12 or later is required:
11
+
12
+ ```sh
13
+ python -m pip install system-runtime-spec
14
+ ```
15
+
16
+ Import the package as `system_runtime_spec`. `Records` holds the records of a system and the
17
+ diagnostics about them. The Pydantic models in `system_runtime_spec.models` are generated from the
18
+ specification's schemas.
19
+
20
+ ## Read and Check a System
21
+
22
+ ```python
23
+ from system_runtime_spec import Records, current_context
24
+
25
+ records = Records.discover("/")
26
+ compatibility = records.check_compatibility()
27
+ health = records.evaluate_health(current_context())
28
+ print("consistent:", compatibility.consistent)
29
+ for result in health.results:
30
+ print(f"{result.id}: usable {result.usable}, healthy {result.healthy}")
31
+ ```
32
+
33
+ `Records.discover` reads the standard directories and the directories that directory
34
+ configurations add, and applies overrides. Files that cannot be read or do not contain a valid
35
+ record are skipped and reported as diagnostics. Reports take the diagnostics of their part into
36
+ account: an error about component declarations makes a composition inconsistent, and a decision
37
+ should not rely on a health report with errors about health nodes or directory configurations.
38
+
39
+ ## Add Records in Code
40
+
41
+ `push` adds a record given as a model, and `push_json` one given as JSON, such as a record
42
+ received from another system. Both validate the record and skip it with an error diagnostic if it
43
+ is invalid:
44
+
45
+ ```python
46
+ from system_runtime_spec import Records
47
+ from system_runtime_spec.models.component import (
48
+ CapabilitySelectorDeclaration,
49
+ ComponentDeclaration,
50
+ )
51
+
52
+ records = Records()
53
+ records.push(ComponentDeclaration(id="os", version="2.1"))
54
+ records.push(
55
+ ComponentDeclaration(
56
+ id="app",
57
+ requires=[CapabilitySelectorDeclaration(id="os", version=">=2")],
58
+ )
59
+ )
60
+ records.push_json(ComponentDeclaration, {"id": "tool"})
61
+ assert records.check_compatibility().consistent
62
+ ```
63
+
64
+ ## Check an Update
65
+
66
+ `with_update` builds the composition that an update would produce: it replaces all component
67
+ declarations of the given owners with those of the update.
68
+
69
+ ```python
70
+ from system_runtime_spec import Records
71
+ from system_runtime_spec.models.component import ComponentDeclaration
72
+
73
+ records = Records.discover("/")
74
+ update = Records()
75
+ update.push(ComponentDeclaration(id="os", owner="rugix.system", version="2.0"))
76
+ candidate = records.with_update(["rugix.system"], update)
77
+ print("consistent:", candidate.check_compatibility().consistent)
78
+ ```
79
+
80
+ ## Send Records as a Snapshot
81
+
82
+ A `Snapshot` contains the original records, so the receiving system evaluates them as the sending
83
+ system read them. Take the clock sample after reading the records:
84
+
85
+ ```python
86
+ import json
87
+
88
+ from system_runtime_spec import (
89
+ Records,
90
+ Snapshot,
91
+ current_clock_sample,
92
+ estimate_timestamp,
93
+ )
94
+
95
+ records = Records.discover("/")
96
+ payload = json.dumps(Snapshot(records, current_clock_sample()).to_json())
97
+
98
+ # On the receiving system:
99
+ received = Snapshot.from_json(json.loads(payload))
100
+ report = received.records.evaluate_health(received.clock.context)
101
+ for status in received.records.health_statuses:
102
+ print(status.id, estimate_timestamp(received.clock, status))
103
+ ```
104
+
105
+ `Snapshot` takes `components=False` or `health=False` to leave out a part. `Snapshot.from_json`
106
+ raises a `SnapshotError` for snapshots of an unsupported version or with an invalid structure.
107
+ Evaluating a snapshot gives health at the time of its clock sample, and `estimate_timestamp`
108
+ places evidence in wall-clock time for display.
109
+
110
+ `Records.discover`, `current_context`, and `current_clock_sample` are available on Linux only.
111
+
112
+ ## License
113
+
114
+ Available under either the [MIT License](LICENSE-MIT) or the
115
+ [Apache License 2.0](LICENSE-APACHE).
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "system-runtime-spec"
7
- version = "0.1.0"
7
+ version = "0.2.0"
8
8
  description = "System component compatibility, health evaluation, and filesystem discovery."
9
9
  requires-python = ">=3.12"
10
10
  dependencies = ["pydantic>=2.11,<3"]
@@ -22,11 +22,11 @@ Issues = "https://github.com/rugix/system-runtime-spec/issues"
22
22
  dev = ["pytest>=8", "ruff>=0.11", "mypy>=1.15"]
23
23
 
24
24
  [tool.hatch.build.targets.wheel]
25
- packages = ["system_runtime"]
25
+ packages = ["system_runtime_spec"]
26
26
 
27
27
  [tool.ruff]
28
28
  target-version = "py312"
29
- extend-exclude = ["system_runtime/models"]
29
+ extend-exclude = ["system_runtime_spec/models"]
30
30
 
31
31
  [tool.ruff.lint]
32
32
  select = ["E", "F", "I"]
@@ -0,0 +1,22 @@
1
+ """Compatibility checking, health evaluation, and discovery of runtime records.
2
+
3
+ `Records` holds the records of a system and the diagnostics about them. The models in
4
+ `system_runtime_spec.models` are generated from the specification's schemas.
5
+ """
6
+
7
+ from ._clock import current_clock_sample, current_context, estimate_timestamp
8
+ from ._decoding import SPEC_VERSION, RecordModel
9
+ from ._records import Records
10
+ from ._snapshot import Parts, Snapshot, SnapshotError
11
+
12
+ __all__ = [
13
+ "SPEC_VERSION",
14
+ "Parts",
15
+ "RecordModel",
16
+ "Records",
17
+ "Snapshot",
18
+ "SnapshotError",
19
+ "current_clock_sample",
20
+ "current_context",
21
+ "estimate_timestamp",
22
+ ]
@@ -0,0 +1,42 @@
1
+ import time
2
+ from datetime import UTC, datetime, timedelta
3
+ from pathlib import Path
4
+
5
+ from .models.health import HealthClockSample, HealthContext, HealthStatus
6
+ from .models.metric import MetricSample
7
+
8
+
9
+ def current_context() -> HealthContext:
10
+ """Read the current Linux boot ID and boot-time clock."""
11
+ return HealthContext(
12
+ boot_id=Path("/proc/sys/kernel/random/boot_id").read_text().strip(),
13
+ now_ms=time.clock_gettime_ns(time.CLOCK_BOOTTIME) // 1_000_000,
14
+ )
15
+
16
+
17
+ def current_clock_sample() -> HealthClockSample:
18
+ """Sample the wall clock between two reads of the boot-time clock."""
19
+ context = current_context()
20
+ timestamp = datetime.now(UTC)
21
+ after = current_context().now_ms
22
+ context.now_ms += (after - context.now_ms) // 2
23
+ return HealthClockSample(context=context, timestamp=timestamp)
24
+
25
+
26
+ def estimate_timestamp(
27
+ clock: HealthClockSample, evidence: HealthStatus | MetricSample
28
+ ) -> datetime | None:
29
+ """Estimate the wall-clock time at which evidence was observed, in milliseconds.
30
+
31
+ Return None for evidence from another boot, evidence observed after the clock
32
+ sample, and estimates outside the years 0001 to 9999.
33
+ """
34
+ observed = evidence.observed_at_ms
35
+ if evidence.boot_id != clock.context.boot_id or observed > clock.context.now_ms:
36
+ return None
37
+ try:
38
+ timestamp = clock.timestamp.astimezone(UTC)
39
+ timestamp = timestamp.replace(microsecond=timestamp.microsecond // 1000 * 1000)
40
+ return timestamp - timedelta(milliseconds=clock.context.now_ms - observed)
41
+ except OverflowError:
42
+ return None
@@ -1,9 +1,8 @@
1
- """Evaluate the compatibility of a complete component composition."""
2
-
3
1
  from collections import Counter
4
2
  from collections.abc import Sequence
5
3
 
6
- from ._version import Version, matches_requirement, parse_requirement
4
+ from ._version import Comparator, Version, matches_requirement, parse_requirement
5
+ from .models.common import Diagnostic
7
6
  from .models.component import (
8
7
  CapabilityDeclaration,
9
8
  CapabilitySelectorDeclaration,
@@ -17,52 +16,52 @@ from .models.component import (
17
16
  )
18
17
 
19
18
 
20
- def check_components(components: Sequence[ComponentDeclaration]) -> CompatibilityReport:
21
- """Validate declarations and report every violated composition constraint.
22
-
23
- Invalid version syntax or simultaneous version and value fields raise ValueError.
24
- """
19
+ def check(
20
+ declarations: Sequence[ComponentDeclaration], diagnostics: Sequence[Diagnostic]
21
+ ) -> CompatibilityReport:
25
22
  provided: list[tuple[str, CapabilityDeclaration, Version | None]] = []
26
23
  selectors: list[
27
- tuple[
28
- str, bool, CapabilitySelectorDeclaration, list[tuple[str, Version]] | None
29
- ]
24
+ tuple[str, bool, CapabilitySelectorDeclaration, list[Comparator] | None]
30
25
  ] = []
31
26
  claims: dict[str, list[str]] = {}
32
- for component in components:
27
+ for component in declarations:
33
28
  implicit = CapabilityDeclaration(id=component.id, version=component.version)
34
29
  for capability in [implicit, *(component.provides or [])]:
35
- _validate(capability)
36
- version = (
37
- Version.parse(capability.version)
38
- if capability.version is not None
39
- else None
30
+ version = capability.version
31
+ provided.append(
32
+ (
33
+ component.id,
34
+ capability,
35
+ Version.parse(version) if version is not None else None,
36
+ )
40
37
  )
41
- provided.append((component.id, capability, version))
42
- for claim in sorted({claim.id for claim in component.claims or []}):
38
+ for claim in dict.fromkeys(claim.id for claim in component.claims or []):
43
39
  claims.setdefault(claim, []).append(component.id)
44
- for conflict, declarations in [
40
+ for conflict, entries in (
45
41
  (False, component.requires),
46
42
  (True, component.conflicts),
47
- ]:
48
- for selector in declarations or []:
49
- _validate(selector)
50
- requirement = (
51
- parse_requirement(selector.version)
52
- if selector.version is not None
53
- else None
43
+ ):
44
+ for selector in entries or []:
45
+ text = selector.version
46
+ selectors.append(
47
+ (
48
+ component.id,
49
+ conflict,
50
+ selector,
51
+ parse_requirement(text) if text is not None else None,
52
+ )
54
53
  )
55
- selectors.append((component.id, conflict, selector, requirement))
56
54
  problems: list[CompatibilityProblem] = [
57
55
  CompatibilityProblem_DuplicateComponent(id=id)
58
56
  for id, count in sorted(
59
- Counter(component.id for component in components).items()
57
+ Counter(component.id for component in declarations).items(),
58
+ key=lambda item: item[0].encode(),
60
59
  )
61
60
  if count > 1
62
61
  ]
63
62
  problems.extend(
64
63
  CompatibilityProblem_DuplicateClaim(id=id, components=owners)
65
- for id, owners in sorted(claims.items())
64
+ for id, owners in sorted(claims.items(), key=lambda item: item[0].encode())
66
65
  if len(owners) > 1
67
66
  )
68
67
  for component_id, conflict, selector, requirement in selectors:
@@ -92,12 +91,9 @@ def check_components(components: Sequence[ComponentDeclaration]) -> Compatibilit
92
91
  component=component_id, selector=selector
93
92
  )
94
93
  )
95
- return CompatibilityReport(consistent=not problems, problems=problems)
96
-
97
-
98
- def _validate(
99
- declaration: CapabilityDeclaration | CapabilitySelectorDeclaration,
100
- ) -> None:
101
- """Reject ambiguous capability declarations before matching."""
102
- if declaration.version is not None and declaration.value is not None:
103
- raise ValueError(f"Capability {declaration.id!r} has both version and value")
94
+ return CompatibilityReport(
95
+ consistent=not problems
96
+ and all(item.severity != "Error" for item in diagnostics),
97
+ problems=problems,
98
+ diagnostics=list(diagnostics),
99
+ )