feat: add legend #54

README.md

@@ -122,6 +122,7 @@ Check out the result [here](https://github.com/compose-viz/compose-viz/blob/main
 | `-o, --output-filename FILENAME`  | Output filename for the generated visualization file. [default: compose-viz]                                                                                                        |
 | `-m, --format FORMAT`             | Output format for the generated visualization file. See [supported formats](https://github.com/compose-viz/compose-viz/blob/main/compose_viz/models/viz_formats.py). [default: png] |
 | `-r, --root-service SERVICE_NAME` | Root of the service tree (convenient for large compose yamls)                                                                                                                       |
+| `-l, --legend`                    | Include a legend in the visualization.                                                                                                                                              |
 | `-v, --version`                   | Show the version of compose-viz.                                                                                                                                                    |
 | `--help`                          | Show help and exit.                                                                                                                                                                 |
 

compose_viz/cli.py

@@ -42,6 +42,12 @@ def compose_viz(
         "-r",
         help="Root of the service tree (convenient for large compose yamls)",
     ),
+    include_legend: bool = typer.Option(
+        False,
+        "--legend",
+        "-l",
+        help="Include a legend in the visualization.",
+    ),
     _: Optional[bool] = typer.Option(
         None,
         "--version",
@@ -57,7 +63,7 @@ def compose_viz(
     if compose:
         typer.echo(f"Successfully parsed {input_path}")
 
-    Graph(compose, output_filename).render(format)
+    Graph(compose, output_filename, include_legend).render(format)
 
     raise typer.Exit()
 

compose_viz/graph.py

@@ -3,6 +3,7 @@
 import graphviz
 
 from compose_viz.models.compose import Compose
+from compose_viz.models.port import AppProtocol, Protocol
 
 
 def apply_vertex_style(type: str) -> dict:
@@ -69,12 +70,58 @@ def apply_edge_style(type: str) -> dict:
 
 
 class Graph:
-    def __init__(self, compose: Compose, filename: str) -> None:
+    def __init__(self, compose: Compose, filename: str, include_legend: bool) -> None:
         self.dot = graphviz.Digraph()
         self.dot.attr("graph", background="#ffffff", pad="0.5", ratio="fill")
         self.compose = compose
         self.filename = filename
 
+        if include_legend:
+            self.dot.attr(rankdir="LR")
+
+            with self.dot.subgraph(name="cluster_edge_") as edge:
+                edge.attr(label="Edge")
+                edge.node("line_0_l", style="invis")
+                edge.node("line_0_r", style="invis")
+                edge.edge("line_0_l", "line_0_r", label="exposes", **apply_edge_style("exposes"))
+
+                edge.node("line_1_l", style="invis")
+                edge.node("line_1_r", style="invis")
+                edge.edge("line_1_l", "line_1_r", label="links", **apply_edge_style("links"))
+
+                edge.node("line_2_l", style="invis")
+                edge.node("line_2_r", style="invis")
+                edge.edge("line_2_l", "line_2_r", label="volumes_rw", **apply_edge_style("volumes_rw"))
+
+                edge.node("line_3_l", style="invis")
+                edge.node("line_3_r", style="invis")
+                edge.edge("line_3_l", "line_3_r", label="volumes_ro", **apply_edge_style("volumes_ro"))
+
+                edge.node("line_4_l", style="invis")
+                edge.node("line_4_r", style="invis")
+                edge.edge("line_4_l", "line_4_r", label="depends_on", **apply_edge_style("depends_on"))
+
+                edge.node("line_5_l", style="invis")
+                edge.node("line_5_r", style="invis")
+                edge.edge("line_5_l", "line_5_r", label="extends", **apply_edge_style("extends"))
+
+            with self.dot.subgraph(name="cluster_node_") as node:
+                node.attr(label="Node")
+                node.node("service", shape="component", label="Service\n(image)")
+                node.node("volume", shape="cylinder", label="Volume")
+                node.node("network", shape="pentagon", label="Network")
+                node.node("port", shape="circle", label="Port")
+                node.node("env_file", shape="tab", label="Env File")
+                node.node("profile", shape="invhouse", label="Profile")
+                node.node("cgroup", shape="diamond", label="CGroupe")
+                node.node("device", shape="box3d", label="Device")
+
+                node.body.append("{ rank=source;service network env_file cgroup }")
+
+            self.dot.node("inv", style="invis")
+            self.dot.edge("inv", "network", style="invis")
+            self.dot.edge("port", "line_2_l", style="invis")
+
     def validate_name(self, name: str) -> str:
         # graphviz does not allow ':' in node name
         transTable = name.maketrans({":": ""})
@@ -117,7 +164,14 @@ def render(self, format: str, cleanup: bool = True) -> None:
                 self.add_edge(expose, service.name, "exposes")
             for port in service.ports:
                 self.add_vertex(port.host_port, "port", lable=port.host_port)
-                self.add_edge(port.host_port, service.name, "links", lable=port.container_port)
+                self.add_edge(
+                    port.host_port,
+                    service.name,
+                    "links",
+                    lable=port.container_port
+                    + (("/" + port.protocol) if port.protocol != Protocol.any.value else "")
+                    + (("\n(" + port.app_protocol + ")") if port.app_protocol != AppProtocol.na.value else ""),
+                )
             for env_file in service.env_file:
                 self.add_vertex(env_file, "env_file")
                 self.add_edge(env_file, service.name, "env_file")

compose_viz/models/port.py

@@ -7,11 +7,27 @@ class Protocol(str, Enum):
     any = "any"
 
 
+class AppProtocol(str, Enum):
+    rest = "REST"
+    mqtt = "MQTT"
+    wbsock = "WebSocket"
+    http = "http"
+    https = "https"
+    na = "NA"
+
+
 class Port:
-    def __init__(self, host_port: str, container_port: str, protocol: Protocol = Protocol.any):
+    def __init__(
+        self,
+        host_port: str,
+        container_port: str,
+        protocol: Protocol = Protocol.any,
+        app_protocol: AppProtocol = AppProtocol.na,
+    ):
         self._host_port = host_port
         self._container_port = container_port
         self._protocol = protocol
+        self._app_protocol = app_protocol
 
     @property
     def host_port(self):
@@ -24,3 +40,7 @@ def container_port(self):
     @property
     def protocol(self):
         return self._protocol
+
+    @property
+    def app_protocol(self):
+        return self._app_protocol

compose_viz/parser.py

@@ -7,7 +7,7 @@
 from compose_viz.models.compose import Compose, Service
 from compose_viz.models.device import Device
 from compose_viz.models.extends import Extends
-from compose_viz.models.port import Port, Protocol
+from compose_viz.models.port import AppProtocol, Port, Protocol
 from compose_viz.models.volume import Volume, VolumeType
 
 
@@ -101,6 +101,7 @@ def parse(self, file_path: str, root_service: Optional[str] = None) -> Compose:
                     host_port: Optional[str] = None
                     container_port: Optional[str] = None
                     protocol: Optional[str] = None
+                    app_protocol: Optional[str] = None
 
                     if type(port_data) is float:
                         container_port = str(int(port_data))
@@ -135,6 +136,7 @@ def parse(self, file_path: str, root_service: Optional[str] = None) -> Compose:
 
                         host_ip = port_data.host_ip
                         protocol = port_data.protocol
+                        app_protocol = port_data.app_protocol
 
                         if container_port is not None and host_port is None:
                             host_port = container_port
@@ -150,11 +152,15 @@ def parse(self, file_path: str, root_service: Optional[str] = None) -> Compose:
                     if protocol is None:
                         protocol = "any"
 
+                    if app_protocol is None:
+                        app_protocol = "na"
+
                     service_ports.append(
                         Port(
                             host_port=host_port,
                             container_port=container_port,
                             protocol=Protocol[protocol],
+                            app_protocol=AppProtocol[app_protocol],
                         )
                     )
 

examples/non-normative/docker-compose.yml

@@ -42,7 +42,13 @@ services:
     extends:
       service: frontend
     ports:
-      - "8000:5010"
+      - name: web-secured
+        target: 443
+        host_ip: 127.0.0.1
+        published: "8083-9000"
+        protocol: tcp
+        app_protocol: wbsock
+        mode : host
     links:
       - "db:database"
     cgroup_parent: awesome-parent