fix(sdk): Various improvements to SDK UX (#136)

#### Relevant issue or PR
n/a

#### Description of changes
Various bits and pieces that improve UX when working with the Tesseract
SDK + Python API.

- Poll more aggressively when serving Tesseracts to reduce startup
delay.
- Improve error message when trying to serve a Tesseract multiple times.
- Pass a fixed serving port to docker-compose. This fixes a bug where
the port would change after a Tesseract restarts on failure, making the
restarted container unreachable.
- Ensure served Tesseracts are always torn down when Python exits (e.g.
when we exit before Tesseract objects go out of scope). This fixes a bug
where `__del__` was called too late (internal machinery was already torn
down), so `teardown` would fail, leaving dangling resources that even
persist after reboot.
- Disable served Tesseracts to restart even after restarting the Docker
daemon (such as during a system reboot). Now we only restart on error,
but not if the daemon is stopped.
- Allow string input paths to `tesseract_core.build_tesseract`.

#### Testing done
Manual

#### License

- [x] By submitting this pull request, I confirm that my contribution is
made under the terms of the [Apache 2.0
license](https://pasteurlabs.github.io/tesseract/LICENSE).
- [x] I sign the Developer Certificate of Origin below by adding my name
and email address to the `Signed-off-by` line.

<details>
<summary><b>Developer Certificate of Origin</b></summary>

```text
Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
```

</details>

Signed-off-by: Dion Häfner <dion.haefner@simulation.science>

Author: dionhaefner

tesseract_core/sdk/cli.py

@@ -356,10 +356,10 @@ def init(
     engine.init_api(target_dir, name, recipe=recipe)
 
 
-def _validate_port(port: str | None) -> str:
+def _validate_port(port: str | None) -> str | None:
     """Validate port input."""
     if port is None:
-        return ""
+        return None
 
     port = port.strip()
     if "-" in port:
@@ -438,19 +438,23 @@ def serve(
     command, as well as a list of all containers spawned and their respective
     ports.
     """
-    if port and len(image_names) > 1:
-        # TODO: Docker compose with multiple ports is not supported until
-        # docker/compose#7188 is resolved.
-        raise typer.BadParameter(
-            (
-                "Port specification only works if 1 Tesseract is being served."
-                f"Currently serving `{len(image_names)}` Tesseracts."
-            ),
-            param_hint="image_names",
-        )
+    if port is not None:
+        if len(image_names) > 1:
+            # TODO: Docker compose with multiple ports is not supported until
+            # docker/compose#7188 is resolved.
+            raise typer.BadParameter(
+                (
+                    "Port specification only works if exactly one Tesseract is being served. "
+                    f"Currently serving `{len(image_names)}` Tesseracts."
+                ),
+                param_hint="image_names",
+            )
+        ports = [port]
+    else:
+        ports = None
 
     try:
-        project_id = engine.serve(image_names, port, volume, gpus)
+        project_id = engine.serve(image_names, ports, volume, gpus)
         containers = engine.project_containers(project_id)
         _display_container_meta(containers)
         logger.info(

tesseract_core/sdk/engine.py

@@ -124,6 +124,16 @@ def wrapper_needs_docker(*args: Any, **kwargs: Any) -> None:
     return wrapper_needs_docker
 
 
+def get_free_port() -> int:
+    """Find a free port to use for HTTP."""
+    import socket
+    from contextlib import closing
+
+    with closing(socket.socket(socket.AF_INET, socket.SOCK_STREAM)) as s:
+        s.bind(("localhost", 0))
+        return s.getsockname()[1]
+
+
 def parse_requirements(
     filename: str | Path,
     session: PipSession | None = None,
@@ -417,7 +427,7 @@ def init_api(
 
 
 def build_tesseract(
-    src_dir: Path,
+    src_dir: str | Path,
     image_tag: str | None,
     build_dir: Path | None = None,
     inject_ssh: bool = False,
@@ -443,6 +453,8 @@ def build_tesseract(
         docker.models.images.Image representing the built Tesseract image,
         or path to build directory if `generate_only` is True.
     """
+    src_dir = Path(src_dir)
+
     validate_tesseract_api(src_dir)
     config = get_config(src_dir)
 
@@ -567,7 +579,7 @@ def _is_tesseract(
 
 def serve(
     images: list[str | docker.models.images.Image],
-    port: str = "",
+    ports: list[str] | None = None,
     volumes: list[str] | None = None,
     gpus: list[str] | None = None,
     debug: bool = False,
@@ -579,7 +591,7 @@ def serve(
     Args:
         images: a list of Tesseract image IDs as strings or `docker`'s
                 Image object.
-        port: port or port range to serve the tesseract on.
+        ports: port or port range to serve each Tesseract on.
         volumes: list of paths to mount in the Tesseract container.
         gpus: IDs of host Nvidia GPUs to make available to the Tesseracts.
         debug: whether to enable debug mode.
@@ -606,7 +618,12 @@ def serve(
             raise ValueError(f"Input ID {image.id} is not a valid Tesseract")
         image_ids.append(image.id)
 
-    template = _create_docker_compose_template(image_ids, port, volumes, gpus, debug)
+    if ports is not None and len(ports) != len(image_ids):
+        raise ValueError(
+            f"Number of ports ({len(ports)}) must match number of images ({len(image_ids)})"
+        )
+
+    template = _create_docker_compose_template(image_ids, ports, volumes, gpus, debug)
     compose_fname = _create_compose_fname()
 
     with tempfile.NamedTemporaryFile(
@@ -684,17 +701,15 @@ def _docker_compose_up(compose_fpath: str, project_name: str) -> bool:
 
 def _create_docker_compose_template(
     image_ids: list[str],
-    port: str = "",
+    ports: list[str] | None = None,
     volumes: list[str] | None = None,
     gpus: list[str] | None = None,
     debug: bool = False,
 ) -> str:
     """Create Docker Compose template."""
     services = []
-    if not port:
-        port = "8000"
-    else:
-        port = f"{port}:8000"
+    if ports is None:
+        ports = [str(get_free_port()) for _ in range(len(image_ids))]
 
     gpu_settings = None
     if gpus:
@@ -703,11 +718,11 @@ def _create_docker_compose_template(
         else:
             gpu_settings = f"device_ids: {gpus}"
 
-    for image_id in image_ids:
+    for image_id, port in zip(image_ids, ports, strict=True):
         service = {
             "name": _create_compose_service_id(image_id),
             "image": image_id,
-            "port": port,
+            "port": f"{port}:8000",
             "volumes": volumes,
             "gpus": gpu_settings,
             "environment": {

tesseract_core/sdk/templates/docker-compose.yml

@@ -2,7 +2,7 @@ services:
 {% for service in services %}
   {{ service.name }}:
     image: {{ service.image }}
-    restart: always
+    restart: unless-stopped
     entrypoint: tesseract-runtime serve
     ports:
       - {{ service.port }}
@@ -14,8 +14,8 @@ services:
     {% endif %}
     healthcheck:
       test: python -c "import requests; requests.get('http://localhost:8000/health').raise_for_status()" || exit 1
-      interval: 3s
-      retries: 10
+      interval: 0.1s
+      retries: 300
       start_period: 1s
     networks:
       - multi-tesseract-network

tesseract_core/sdk/tesseract.py

@@ -2,6 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 from __future__ import annotations
 
+import atexit
 import base64
 import json
 import subprocess
@@ -173,9 +174,7 @@ def __enter__(self) -> Tesseract:
         This will start the Tesseract server if it is not already running.
         """
         if self._serve_context is not None:
-            raise RuntimeError(
-                "Cannot nest the same `with Tesseract ...` context manager."
-            )
+            raise RuntimeError("Cannot serve the same Tesseract multiple times.")
 
         if self._client is not None:
             # Tesseract is already being served -> no-op
@@ -208,7 +207,7 @@ def server_logs(self) -> str:
             return self._lastlog
         return engine.logs(self._serve_context["container_id"])
 
-    def serve(self, port: str = "") -> None:
+    def serve(self, port: str | None = None) -> None:
         """Serve the Tesseract.
 
         Args:
@@ -232,6 +231,7 @@ def serve(self, port: str = "") -> None:
         )
         self._lastlog = None
         self._client = HTTPClient(f"http://localhost:{served_port}")
+        atexit.register(self.teardown)
 
     def teardown(self) -> None:
         """Teardown the Tesseract.
@@ -244,6 +244,7 @@ def teardown(self) -> None:
         engine.teardown(self._serve_context["project_id"])
         self._client = None
         self._serve_context = None
+        atexit.unregister(self.teardown)
 
     def __del__(self) -> None:
         """Destructor for the Tesseract class.
@@ -256,13 +257,18 @@ def __del__(self) -> None:
     @staticmethod
     def _serve(
         image: str,
-        port: str = "",
+        port: str | None = None,
         volumes: list[str] | None = None,
         gpus: list[str] | None = None,
         debug: bool = False,
     ) -> tuple[str, str, int]:
+        if port is not None:
+            ports = [port]
+        else:
+            ports = None
+
         project_id = engine.serve(
-            [image], port=port, volumes=volumes, gpus=gpus, debug=debug
+            [image], ports=ports, volumes=volumes, gpus=gpus, debug=debug
         )
 
         command = ["docker", "compose", "-p", project_id, "ps", "--format", "json"]

tests/endtoend_tests/test_endtoend.py

@@ -272,7 +272,7 @@ def test_tesseract_serve_ports_error(built_image_name):
     )
     assert run_res.exit_code
     assert (
-        "Port specification only works if 1 Tesseract is being served."
+        "Port specification only works if exactly one Tesseract is being served."
         in run_res.stderr
     )
 

tests/endtoend_tests/test_tesseract_sdk.py

@@ -40,7 +40,7 @@ def test_apply(built_image_name, dummy_tesseract_location, free_port):
 
     # Test URL access
     tesseract_url = f"http://localhost:{free_port}"
-    served_tesseract = engine.serve([built_image_name], port=str(free_port))
+    served_tesseract = engine.serve([built_image_name], ports=[str(free_port)])
     try:
         vecadd = Tesseract(tesseract_url)
         out = vecadd.apply(inputs)
@@ -102,7 +102,7 @@ def served_tesseract_remote(built_image_name):
     sock.close()
     # Serve the Tesseract image
     tesseract_url = f"http://localhost:{free_port}"
-    served_tesseract = engine.serve([built_image_name], port=str(free_port))
+    served_tesseract = engine.serve([built_image_name], ports=[str(free_port)])
     try:
         yield tesseract_url
     finally:

tests/sdk_tests/test_tesseract.py

@@ -107,7 +107,7 @@ def test_serve_lifecycle(mock_serving, mock_clients):
         pass
 
     mock_serving["serve_mock"].assert_called_with(
-        ["sometesseract:0.2.3"], port="", volumes=None, gpus=None, debug=True
+        ["sometesseract:0.2.3"], ports=None, volumes=None, gpus=None, debug=True
     )
 
     mock_serving["teardown_mock"].assert_called_with("proj-id-123")