feat: add tutor dev hosts command to display status of services (#1223)

Author: mlabeeb03

changelog.d/20250423_154820_muhammad.labeeb_show_exited_containers.md

@@ -0,0 +1 @@
+ - [Feature] Add new command `tutor dev hosts` that displays status of services. (by @mlabeeb03) 

tests/commands/test_dev.py

@@ -1,5 +1,7 @@
 import unittest
 
+from tutor.commands import dev
+
 from .base import TestCommandMixin
 
 
@@ -8,3 +10,35 @@ def test_dev_help(self) -> None:
         result = self.invoke(["dev", "--help"])
         self.assertEqual(0, result.exit_code)
         self.assertIsNone(result.exception)
+
+
+class HostsParsing(unittest.TestCase):
+    def test_host_port_single(self) -> None:
+        ps_output = """{"Publishers":[{"PublishedPort":8000}]}"""
+        host_port = dev.parse_ports(ps_output)
+        self.assertEqual(host_port, [8000])
+
+    def test_host_port_single_empty(self) -> None:
+        ps_output = """{"Publishers":[{"PublishedPort":0}]}"""
+        host_port = dev.parse_ports(ps_output)
+        self.assertEqual(host_port, [])
+
+    def test_host_port_multiple_services(self) -> None:
+        ps_output = """{"Publishers":[{"PublishedPort":0}]}
+        {"Publishers":[{"PublishedPort":8000}]}
+        {"Publishers":[{"PublishedPort":8001}]}"""
+
+        host_port = dev.parse_ports(ps_output)
+        self.assertEqual(host_port, [8000, 8001])
+
+    def test_host_port_multiple_publishers(self) -> None:
+        ps_output = """{"Publishers":[{"PublishedPort":0}, {"PublishedPort":3276}, {"PublishedPort":8000}]}"""
+
+        host_port = dev.parse_ports(ps_output)
+        self.assertEqual(host_port, [3276, 8000])
+
+    def test_host_port_multiple_services_publishers(self) -> None:
+        ps_output = """{"Publishers":[{"PublishedPort":0}, {"PublishedPort":3276}, {"PublishedPort":8000}]}
+        {"Publishers":[{"PublishedPort":0}, {"PublishedPort":8001}, {"PublishedPort":8002}]}"""
+        host_port = dev.parse_ports(ps_output)
+        self.assertEqual(host_port, [3276, 8000, 8001, 8002])

tutor/commands/compose.py

@@ -5,12 +5,10 @@
 
 import click
 
-from tutor import bindmount
+from tutor import bindmount, fmt, hooks, utils
 from tutor import config as tutor_config
 from tutor import env as tutor_env
-from tutor import fmt, hooks
 from tutor import interactive as interactive_config
-from tutor import utils
 from tutor.commands import images, jobs
 from tutor.commands.config import save as config_save_command
 from tutor.commands.context import BaseTaskContext
@@ -31,9 +29,9 @@ def __init__(self, root: str, config: Config):
         self.docker_compose_files: list[str] = []
         self.docker_compose_job_files: list[str] = []
 
-    def docker_compose(self, *command: str) -> int:
+    def _get_docker_compose_args(self, *command: str) -> list[str]:
         """
-        Run docker-compose with the right yml files.
+        Returns appropriate arguments (yml files) to be used with the docker compose commmand
         """
         # Trigger the action just once per runtime
         start_commands = ("start", "up", "restart", "run")
@@ -48,8 +46,21 @@ def docker_compose(self, *command: str) -> int:
         for docker_compose_path in self.docker_compose_files:
             if os.path.exists(docker_compose_path):
                 args += ["-f", docker_compose_path]
-        return utils.docker_compose(
-            *args, "--project-name", self.project_name, *command
+        args += ["--project-name", self.project_name, *command]
+        return args
+
+    def docker_compose(self, *command: str) -> int:
+        """
+        Run docker-compose with the right yml files.
+        """
+        return utils.docker_compose(*self._get_docker_compose_args(*command))
+
+    def docker_compose_output(self, *command: str) -> bytes:
+        """
+        Same as the docker_compose method except that it returns the command output.
+        """
+        return utils.check_output(
+            "docker", "compose", *self._get_docker_compose_args(*command)
         )
 
     def run_task(self, service: str, command: str) -> int:

tutor/commands/dev.py

@@ -1,11 +1,14 @@
 from __future__ import annotations
 
+import json
 import typing as t
+from urllib.parse import urlparse
 
 import click
 
+from tutor import config as tutor_config
 from tutor import env as tutor_env
-from tutor import hooks
+from tutor import fmt, hooks, utils
 from tutor.commands import compose
 from tutor.types import Config, get_typed
 from tutor.utils import get_compose_stacks
@@ -45,6 +48,44 @@ def dev(context: click.Context) -> None:
     context.obj = DevContext(context.obj.root)
 
 
+def parse_ports(docker_compose_ps_output: str) -> list[int]:
+    """
+    Extracts the ports from the docker ps output in json format.
+    """
+    exposed_ports = []
+    for line in docker_compose_ps_output.splitlines():
+        publishers = json.loads(line)["Publishers"]
+        for publisher in publishers:
+            port = publisher["PublishedPort"]
+            if port:
+                exposed_ports.append(port)
+    return exposed_ports
+
+
+@click.command(help="List the status of all services.")
+@click.pass_obj
+def hosts(context: compose.BaseComposeContext) -> None:
+    config = tutor_config.load(context.root)
+    docker_compose_ps_output = (
+        context.job_runner(config)
+        .docker_compose_output("ps", "--format", "json")
+        .decode()
+    )
+    exposed_ports = parse_ports(docker_compose_ps_output)
+    public_app_hosts: list[tuple[str, ...]] = [("URL", "STATUS")]
+    for host in hooks.Filters.APP_PUBLIC_HOSTS.iterate(context.NAME):
+        public_app_host = tutor_env.render_str(
+            config, "{% if ENABLE_HTTPS %}https{% else %}http{% endif %}://" + host
+        )
+        port = urlparse(public_app_host).port
+        status_marker = " ✅" if port in exposed_ports else ""
+        public_app_hosts.append((public_app_host, status_marker))
+    fmt.echo(utils.format_table(public_app_hosts))
+
+
+dev.add_command(hosts)
+
+
 @hooks.Actions.COMPOSE_PROJECT_STARTED.add()
 def _stop_on_local_start(root: str, config: Config, project_name: str) -> None:
     """