feat: implement SoftwareSystemInstance

Author: yt-ms

src/structurizr/model/deployment_node.py

@@ -21,6 +21,7 @@
 
 from .container_instance import ContainerInstance, ContainerInstanceIO
 from .deployment_element import DeploymentElement, DeploymentElementIO
+from .software_system_instance import SoftwareSystemInstance, SoftwareSystemInstanceIO
 
 
 if TYPE_CHECKING:
@@ -59,6 +60,9 @@ class Config:
     container_instances: List[ContainerInstanceIO] = Field(
         default=(), alias="containerInstances"
     )
+    software_system_instances: List[SoftwareSystemInstanceIO] = Field(
+        default=(), alias="softwareSystemInstances"
+    )
 
 
 DeploymentNodeIO.update_forward_refs()
@@ -89,6 +93,7 @@ def __init__(
         instances: int = 1,
         children: Iterable["DeploymentNode"] = (),
         container_instances: Iterable[ContainerInstance] = (),
+        software_system_instances: Iterable[SoftwareSystemInstance] = (),
         **kwargs,
     ) -> None:
         """Initialize a deployment node."""
@@ -98,6 +103,7 @@ def __init__(
         self.instances = instances
         self._children = set(children)
         self._container_instances = set(container_instances)
+        self._software_system_instances = set(software_system_instances)
 
     @property
     def children(self) -> Iterable["DeploymentNode"]:
@@ -109,6 +115,11 @@ def container_instances(self) -> Iterable[ContainerInstance]:
         """Return read-only list of container instances."""
         return list(self._container_instances)
 
+    @property
+    def software_system_instances(self) -> Iterable[SoftwareSystemInstance]:
+        """Return read-only list of software system instances."""
+        return list(self._software_system_instances)
+
     def add_deployment_node(self, **kwargs) -> "DeploymentNode":
         """Add a new child deployment node to this node."""
         node = DeploymentNode(**kwargs)

src/structurizr/model/software_system_instance.py

@@ -0,0 +1,72 @@
+# Copyright (c) 2020, Moritz E. Beber.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Provide a softwrae system instance model."""
+
+
+from typing import TYPE_CHECKING
+
+from pydantic import Field
+
+from .software_system import SoftwareSystem
+from .static_structure_element_instance import (
+    StaticStructureElementInstance,
+    StaticStructureElementInstanceIO,
+)
+
+
+if TYPE_CHECKING:
+    from .model import Model
+
+
+__all__ = ("SoftwareSystemInstance", "SoftwareSystemInstanceIO")
+
+
+class SoftwareSystemInstanceIO(StaticStructureElementInstanceIO):
+    """Represents a software system instance which can be added to a deployment node."""
+
+    software_system_id: str = Field(alias="softwareSystemId")
+
+
+class SoftwareSystemInstance(StaticStructureElementInstance):
+    """Represents a software system instance which can be added to a deployment node."""
+
+    def __init__(self, *, software_system: SoftwareSystem, **kwargs) -> None:
+        """Initialize a software system instance."""
+        super().__init__(element=software_system, **kwargs)
+        self.software_system = software_system
+
+    @property
+    def software_system_id(self) -> str:
+        """Return the ID of the software system for this instance."""
+        return self.software_system.id
+
+    @classmethod
+    def hydrate(
+        cls,
+        system_instance_io: SoftwareSystemInstanceIO,
+        model: "Model",
+    ) -> "SoftwareSystemInstance":
+        """Hydrate a new SoftwareSystemInstance instance from its IO.
+
+        This will also automatically register with the model.
+        """
+        system = model.get_element(system_instance_io.software_system_id)
+        instance = cls(
+            **cls.hydrate_arguments(system_instance_io),
+            software_system=system,
+        )
+        model += instance
+        return instance

tests/unit/model/test_software_system_instance.py

@@ -0,0 +1,136 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Ensure the expected behaviour of the software_system element."""
+
+
+import pytest
+
+from structurizr.model.http_health_check import HTTPHealthCheck, HTTPHealthCheckIO
+from structurizr.model.software_system_instance import (
+    SoftwareSystemInstance,
+    SoftwareSystemInstanceIO,
+)
+
+
+class MockModel:
+    """Implement a mock model for testing."""
+
+    def __init__(self):
+        """Create an mock software_system for testing."""
+        self.mock_system = MockSystem()
+
+    def __iadd__(self, instance: SoftwareSystemInstance):
+        """Simulate the model assigning IDs to new elements."""
+        if not instance.id:
+            instance.id = "id"
+        instance.set_model(self)
+        return self
+
+    def get_element(self, id: str):
+        """Simulate fetching the software_system by ID."""
+        return self.mock_system
+
+
+class MockSystem:
+    """Implement a mock system for testing."""
+
+    def __init__(self):
+        """Create a new mock."""
+        self.id = "19"
+        self.name = "Mock System"
+
+
+@pytest.fixture(scope="function")
+def model_with_system() -> MockModel:
+    """Provide a mock model for test cases to use."""
+    return MockModel()
+
+
+@pytest.mark.parametrize(
+    "attributes",
+    [
+        pytest.param({}, marks=pytest.mark.raises(exception=TypeError)),
+        {
+            "environment": "Development",
+            "software_system": MockSystem(),
+            "instance_id": "17",
+            "properties": {"a": "b"},
+        },
+    ],
+)
+def test_software_system_instance_init(attributes):
+    """Expect proper initialization from arguments."""
+    instance = SoftwareSystemInstance(**attributes)
+    for attr, expected in attributes.items():
+        assert getattr(instance, attr) == expected
+
+
+def test_software_system_instance_hydration_retrieves_software_system_from_id(
+    model_with_system,
+):
+    """Check that the software_system instance is retrieved on hydration."""
+    io = SoftwareSystemInstanceIO(
+        software_system_id="19", instance_id=3, environment="Live"
+    )
+
+    instance = SoftwareSystemInstance.hydrate(io, model_with_system)
+
+    assert instance.instance_id == 3
+    assert instance.environment == "Live"
+    assert instance.software_system is model_with_system.mock_system
+    assert instance.software_system_id == "19"
+
+
+def test_software_system_instance_name_is_software_system_name(model_with_system):
+    """Ensure software_system instance takes its name from its software system."""
+    io = SoftwareSystemInstanceIO(
+        software_system_id="19", instance_id=3, environment="Live"
+    )
+
+    instance = SoftwareSystemInstance.hydrate(io, model_with_system)
+
+    assert instance.name == "Mock System"
+
+
+def test_software_system_instance_hyrdates_http_health_checks(model_with_system):
+    """Check that health checks are hydrated into the SoftwareSystemInstance."""
+    health_check_io = HTTPHealthCheckIO(name="name", url="http://a.b.com")
+    io = SoftwareSystemInstanceIO(
+        software_system_id="19",
+        instance_id=3,
+        environment="Live",
+        health_checks=[health_check_io],
+    )
+
+    instance = SoftwareSystemInstance.hydrate(io, model_with_system)
+
+    assert len(instance.health_checks) == 1
+    assert list(instance.health_checks)[0].name == "name"
+
+
+def test_software_system_instance_serialization(model_with_system):
+    """Test that system instances serialise properly."""
+    health_check = HTTPHealthCheck(name="health", url="http://a.b.com")
+    instance = SoftwareSystemInstance(
+        software_system=model_with_system.mock_system,
+        instance_id=7,
+        health_checks=[health_check],
+    )
+
+    io = SoftwareSystemInstanceIO.from_orm(instance)
+
+    assert io.software_system_id == "19"
+    assert io.instance_id == 7
+    assert len(io.health_checks) == 1
+    assert io.health_checks[0].name == "health"