From 24ce5f281ddbd31f28ba0fcf71100d7df2308caf Mon Sep 17 00:00:00 2001 From: Bo Maryniuk Date: Tue, 29 Oct 2024 16:00:20 +0100 Subject: [PATCH 1/5] Add newline --- examples/models/inherited/model.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/models/inherited/model.cfg b/examples/models/inherited/model.cfg index 79d44bb9..01af6a7b 100644 --- a/examples/models/inherited/model.cfg +++ b/examples/models/inherited/model.cfg @@ -15,4 +15,4 @@ config: modules: target/debug #inherits: ../router -inherits: /home/bo/work/sysinspect/examples/models/router \ No newline at end of file +inherits: /home/bo/work/sysinspect/examples/models/router From b1e0556eb144d36400252e4d78b3146f98394da8 Mon Sep 17 00:00:00 2001 From: Bo Maryniuk Date: Tue, 29 Oct 2024 16:05:05 +0100 Subject: [PATCH 2/5] Change the "facts" to "claims" on entities, as should be This was a techdebt from the early prototyping. --- libsysinspect/src/intp/actions.rs | 2 +- libsysinspect/src/intp/entities.rs | 8 ++++---- libsysinspect/src/intp/inspector.rs | 10 +++++----- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/libsysinspect/src/intp/actions.rs b/libsysinspect/src/intp/actions.rs index 70ae5624..bf9320b7 100644 --- a/libsysinspect/src/intp/actions.rs +++ b/libsysinspect/src/intp/actions.rs @@ -190,7 +190,7 @@ impl Action { match inspector.call_function(eid, &modcall.state(), &func) { Ok(None) => { return Err(SysinspectError::ModelDSLError(format!( - "Entity {}.facts.{}.{} does not exist", + "Entity {}.claims.{}.{} does not exist", eid, &modcall.state(), func.namespace() diff --git a/libsysinspect/src/intp/entities.rs b/libsysinspect/src/intp/entities.rs index cbe9a4fc..7766b32b 100644 --- a/libsysinspect/src/intp/entities.rs +++ b/libsysinspect/src/intp/entities.rs @@ -22,7 +22,7 @@ impl Claim { #[derive(Serialize, Deserialize, Debug, Default)] pub struct Entity { descr: Option, - facts: Option>>, + claims: Option>>, inherits: Option>, depends: Option>, @@ -67,8 +67,8 @@ impl Entity { self.descr.to_owned().unwrap_or("".to_string()) } - /// Return facts - pub fn facts(&self) -> Option<&HashMap>> { - self.facts.as_ref() + /// Return claims + pub fn claims(&self) -> Option<&HashMap>> { + self.claims.as_ref() } } diff --git a/libsysinspect/src/intp/inspector.rs b/libsysinspect/src/intp/inspector.rs index 13b16bdc..634158d5 100644 --- a/libsysinspect/src/intp/inspector.rs +++ b/libsysinspect/src/intp/inspector.rs @@ -140,7 +140,7 @@ impl SysInspector { log::debug!("Action entity: {} (entity: {}, state: {state})", action.id(), &eid); // Actions are registered with a specific Entitiy Id (eid) // Because as the same Action gets registered with the another eid, - // it also corresponds to other facts and conditions, and that then + // it also corresponds to other claims and conditions, and that then // needs to be passed to the reactor. out.push(action.to_owned().setup(self, &eid, state.to_owned())?); } @@ -199,8 +199,8 @@ impl SysInspector { let entity = Entity::default(); let entity = self.get_entity(eid).unwrap_or(&entity); - if let Some(facts) = entity.facts() { - if let Some(claims) = facts.get(state) { + if let Some(claims) = entity.claims() { + if let Some(claims) = claims.get(state) { for claim in claims { if let Some(v) = claim.get(func.ns_parts().unwrap()[0]) { if let serde_yaml::Value::Mapping(v) = v { @@ -209,7 +209,7 @@ impl SysInspector { } } else { return Err(SysinspectError::ModelDSLError(format!( - "Claim {}.facts.{}.{} must be a key/value mapping", + "Claim {}.claims.{}.{} must be a key/value mapping", eid, state, func.namespace() @@ -218,7 +218,7 @@ impl SysInspector { } } } else { - return Err(SysinspectError::ModelDSLError(format!("No claims at {}.facts defined", eid))); + return Err(SysinspectError::ModelDSLError(format!("No claims at {}.claims defined", eid))); } } From 2e5eb7969268d5f7c9089d8e4fb8c030e46f2940 Mon Sep 17 00:00:00 2001 From: Bo Maryniuk Date: Tue, 29 Oct 2024 16:05:23 +0100 Subject: [PATCH 3/5] Adjust the DSL according to the spec --- examples/models/router/entities/ports.cfg | 10 +++++----- examples/models/router/entities/processes.cfg | 14 +++++++------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/examples/models/router/entities/ports.cfg b/examples/models/router/entities/ports.cfg index 44c3ad1f..cdfa1e10 100644 --- a/examples/models/router/entities/ports.cfg +++ b/examples/models/router/entities/ports.cfg @@ -11,7 +11,7 @@ entities: # Single entities ssh-sockets: - facts: + claims: $: - default: port: tcp,0.0.0.0:22,0.0.0.0:* @@ -23,21 +23,21 @@ entities: - ssh-sockets postgres-sockets: - facts: + claims: $: - default: port: tcp,0.0.0.0:5432,0.0.0.0:* port6: tcp,[::]:5432,[::]:* routes: - facts: + claims: $: - default: route_a: 192.168.2.0/24 route_b: 192.168.122.0/24 interfaces: - facts: + claims: $: - default: lo: lo @@ -46,7 +46,7 @@ entities: wifi: wlp0s20f3 addresses: - facts: + claims: # Fact label. It is referred # by a constraint, if needed interfaces: diff --git a/examples/models/router/entities/processes.cfg b/examples/models/router/entities/processes.cfg index b5554b15..fa91ddbd 100644 --- a/examples/models/router/entities/processes.cfg +++ b/examples/models/router/entities/processes.cfg @@ -2,7 +2,7 @@ entities: systemconf: descr: static system configuration - facts: + claims: default: - devices: storage: @@ -26,30 +26,30 @@ entities: - $ - "192.168.1.12" - local - facts: + claims: default: - label: path: /lib/systemd/systemd-journald udevd: descr: udevd enables autodetect USB devices - facts: + claims: default: - label: path: /lib/systemd/systemd-udevd resolved: descr: resolved daemon from systemd - facts: + claims: default: - label: path: /lib/systemd/systemd-resolved syslogd: descr: syslog daemon process - facts: + claims: # This is a state label, should match action descr - # It allows selecting different facts under different + # It allows selecting different claims under different # states. $: # This is a fact namespace in a free form @@ -62,7 +62,7 @@ entities: systemd: descr: system init system - facts: + claims: default: - label: path: /sbin/init From 584829bb2ac031391bf665255391bf5fb4ddcbf5 Mon Sep 17 00:00:00 2001 From: Bo Maryniuk Date: Tue, 29 Oct 2024 16:18:16 +0100 Subject: [PATCH 4/5] Update docs renaming "facts" to "claims" for entities. --- docs/modeldescr/actions.rst | 32 ++++++++--------- docs/modeldescr/constraints.rst | 6 ++-- docs/modeldescr/entities.rst | 64 ++++++++++++++++----------------- docs/modeldescr/functions.rst | 4 +-- docs/modeldescr/relations.rst | 2 +- 5 files changed, 54 insertions(+), 54 deletions(-) diff --git a/docs/modeldescr/actions.rst b/docs/modeldescr/actions.rst index 715f1ce2..1a5ef27b 100644 --- a/docs/modeldescr/actions.rst +++ b/docs/modeldescr/actions.rst @@ -12,8 +12,8 @@ data to modules. The following rules are applied to an action: - - An action is a consumer of facts of an entity - - One action applies only to one fact, but it may statically refer facts from other entities + - An action is a consumer of claims of an entity + - One action applies only to one claim, but it may statically refer claims from other entities Synopsis -------- @@ -78,7 +78,7 @@ Below is the description of configuration sections: If actions processing the system in a serial fashion without knowing what it is even discovered, then how exactly the state is determined? - They are not. An entity anyway is checked through all defined states. If facts are matching for one particular state, + They are not. An entity anyway is checked through all defined states. If claims are matching for one particular state, it is concluded that the device is in this state. Another option is to pass an argument to a module of a state. So if a module is able to request a state, then it can match the return result accordingly. @@ -150,25 +150,25 @@ Given there are entities, such as ``syslogd``, ``systemd`` etc, one can bind an .. warning:: - The *minimal* data structure of a facts must be identical! + The *minimal* data structure of a claims must be identical! -In this example of two entities that have additional facts and one action that is checking +In this example of two entities that have additional claims and one action that is checking those processes. Module ``sys.proc`` receives a flag ``is-running`` which puts it to a -process checking mode, accepting ``process`` parameter of a currently processed fact. +process checking mode, accepting ``process`` parameter of a currently processed claim. In this case, ``sys.proc`` will accept ``/sbin/init`` and ``/usr/bin/syslogd`` file. -The fact ``discspace`` from ``my-special`` fact will be omitted. +The claim ``discspace`` from ``my-special`` claim will be omitted. .. code-block:: yaml entities: systemd: - facts: - my-fact: + claims: + my-claim: - default: path: /sbin/init syslogd: - facts: + claims: my-special: - default: path: /usr/bin/syslogd @@ -198,7 +198,7 @@ to the Shell expression as such: ``$MY_VAR``. a clear arguments without complex interpolations. In some rare cases one might create a comma-separated string, if that is very necessary: - ``myfact: "claim(foo),claim(bar)"``, however this is very discouraged practice and it is strongly + ``myclaim: "claim(foo),claim(bar)"``, however this is very discouraged practice and it is strongly recommended to change the module so it accepts a list of values instead of a comma-separated string. Another example, showing static data references. Consider the following configuration: @@ -209,7 +209,7 @@ Another example, showing static data references. Consider the following configur # An entity, describing a static configuration systemconf: descr: static system configuration - facts: + claims: default: - storage: type: SSD @@ -223,7 +223,7 @@ Another example, showing static data references. Consider the following configur syslogd-possible: # Description of the action that will be logged # The shorter, the better - description: Validate syslogd facts + description: Validate syslogd claims # Path to the module namespace. # Modules are located in $module_root and namespace @@ -238,7 +238,7 @@ Another example, showing static data references. Consider the following configur $: args: # Variable $(foo.bar) always refers to a full path from the document root. - - free-disk: "static(entities.syslogd.facts.storage.free)" - - free-mem: "static(entities.systemconf.facts.mem.free)" + - free-disk: "static(entities.syslogd.claims.storage.free)" + - free-mem: "static(entities.systemconf.claims.mem.free)" -In the example above, function ``static(....)`` can statically reach any defined value of a fact. +In the example above, function ``static(....)`` can statically reach any defined value of a claim. diff --git a/docs/modeldescr/constraints.rst b/docs/modeldescr/constraints.rst index 0f27c708..4de071bd 100644 --- a/docs/modeldescr/constraints.rst +++ b/docs/modeldescr/constraints.rst @@ -6,13 +6,13 @@ Constraints This document explains how constraints work and what they are for. Constraints are declarative logic carriers. They provide clear rules what to *consume* within -a specific fact. +a specific claim. .. important:: The following rules are applied to a constraint: - - It provides declarative logic for modules those are consuming a specific fact + - It provides declarative logic for modules those are consuming a specific claim - It operates on actions, using entities's data Synopsis @@ -110,7 +110,7 @@ Example entities: # NOTE: An id of an entity, referred by a constraint below addresses: - facts: + claims: $: - wifi: if: wlp0s20f3 diff --git a/docs/modeldescr/entities.rst b/docs/modeldescr/entities.rst index 01fbc04e..12bbd7fc 100644 --- a/docs/modeldescr/entities.rst +++ b/docs/modeldescr/entities.rst @@ -8,7 +8,7 @@ The element ``entitles`` is the basis of the model. It contains the entire inven of a system in a CMDB fashion. Each entity can be described in a specific manner, holding all the -necessary attributes, facts, claims and other data that must be +necessary attributes, claims and other data that must be understood by the corresponding consumers. Consumers are actions that call specific modules, and constraints that process them. @@ -17,14 +17,14 @@ call specific modules, and constraints that process them. Entities the the following rules: - An entity is independent of the specific architecture of a system - - An entity may contain only self-applied facts, describing only that particular entity. + - An entity may contain only self-applied claims, describing only that particular entity. - A single entity exists on its own and is unaware of other entities. - A compound entity exists only when all its parts are active. Synopsis -------- -Entitles describe facts and relations within the architecture. These expectations should +Entitles describe claims and relations within the architecture. These expectations should be aligned with constraints. Each entity has a **true** or **false** state. A "true" state is when all constraints and checks produce the expected result. @@ -32,7 +32,7 @@ all constraints and checks produce the expected result. Each entity is a map. A map starts with an "id" and then contains the necessary attributes. The current attributes of an "entity" are as follows: -1. ``facts`` *(required)* contains all data to be consumed by any module, check, or constraint, which must be true in the end. +1. ``claims`` *(required)* contains all data to be consumed by any module, check, or constraint, which must be true in the end. 2. ``consists`` *(optional)* It is only for collection entities (e.g., a network) and contains a list of other single entities that together form such a collection. This determines the operational state of the entity **itself**. 3. ``depends`` *(optional)* It is for defining which other entities are required for this entity to be functional. @@ -50,7 +50,7 @@ Here is the full entity description: : inherits: - - facts: + claims: :