[DPE-1657] Address launch_synstage error in demo.py (#53) (#54)

* robust error-handling for unexpected API changes

* pass flake8 tests

* serialize tower integration tests

* new client mock tests. new CONTRIBUTING.md section. removed xdist_grouping

* fix line too long

Author: jaymedina

CONTRIBUTING.md

@@ -302,3 +302,17 @@ on [PyPI], the following steps can be used to release a new version for
 [virtualenv]: https://virtualenv.pypa.io/en/stable/
 [repository]: https://github.com/sage-bionetworks-workflows/py-orca
 [issue tracker]: https://github.com/sage-bionetworks-workflows/py-orca/issues
+
+---
+
+## Troubleshooting CI
+
+> This is a living document. As new CI failures are diagnosed and resolved, add them here so future contributors don't have to rediscover the same issues.
+
+### Integration tests fail with `401 Unauthorized` or unexpected API errors
+
+**Symptom:** Integration tests (e.g., `test_that_a_workflow_can_be_launched`) fail in CI with authentication or API errors, even though the tests pass locally.
+
+**Cause:** The `NEXTFLOWTOWER_CONNECTION_URI` GitHub Actions secret MAY contain an expired or outdated API token.
+
+**Fix:** Regenerate a valid Nextflow Tower API token following the format outlined in `.env.example` and update the secret in the repository's GitHub Actions settings (`Settings > Secrets and variables > Actions > NEXTFLOWTOWER_CONNECTION_URI`).

src/orca/services/nextflowtower/client.py

@@ -1,3 +1,4 @@
+import warnings
 from typing import Any, Optional
 
 import requests
@@ -91,16 +92,24 @@ def request_json(self, method: str, path: str, **kwargs) -> dict[str, Any]:
         return response.json()
 
     def request_paged(self, method: str, path: str, **kwargs) -> dict[str, Any]:
-        """Iterate through pages of results for a given request.
+        """Paginate through all pages of a paged API endpoint and collect results.
+
+        Sends repeated requests, incrementing the offset each time, until all
+        items have been retrieved. Expects each response to contain a size key
+        (``totalSize`` or ``total``) and exactly one list-valued key holding
+        the items for that page. Warns if multiple list-valued keys are found
+        and uses the first. Raises if no list-valued key is found.
 
         See ``TowerClient.request`` for argument definitions.
 
         Raises:
-            HTTPError: If the response doesn't match the expectation
-                for a paged endpoint.
+            HTTPError: If the response contains no list-valued key, or if the
+                total number of collected items does not match the declared
+                total size.
 
         Returns:
-            The cumulative list of items from all pages.
+            A dict with ``totalSize`` (or ``total``) and the items key mapped
+            to the full combined list across all pages.
         """
         # Ensure defaults for pagination query parameters
         self.update_kwarg(kwargs, "params", "max", 50)
@@ -114,7 +123,21 @@ def request_paged(self, method: str, path: str, **kwargs) -> dict[str, Any]:
             kwargs["params"]["offset"] = num_items
             json = self.request_json(method, path, **kwargs)
             total_size = json.pop("totalSize", None) or json.pop("total", 0)
-            key_name, items = json.popitem()
+            list_keys = [(k, v) for k, v in json.items() if isinstance(v, list)]
+            if not list_keys:
+                received = {k: type(v).__name__ for k, v in json.items()}
+                raise HTTPError(
+                    f"Paged response contained no list-valued key. "
+                    f"Received keys/types: {received}"
+                )
+            if len(list_keys) > 1:
+                warnings.warn(
+                    f"Paged response contained multiple list-valued keys: "
+                    f"{[k for k, _ in list_keys]}. "
+                    f"Using the first: '{list_keys[0][0]}'.",
+                    stacklevel=2,
+                )
+            key_name, items = list_keys[0]
             num_items += len(items)
             all_items.extend(items)
 

tests/services/nextflowtower/test_client.py

@@ -1,3 +1,5 @@
+import warnings
+
 import pytest
 from requests.exceptions import HTTPError
 
@@ -166,3 +168,35 @@ def test_that_get_task_logs_works(client, mocker, get_response):
     )
     mock.assert_called()
     assert result == "Ciao world!"
+
+
+def test_that_request_paged_raises_when_no_list_key(client, mocker):
+    mock = mocker.patch.object(client, "request_json")
+    mock.return_value = {"totalSize": 1, "hasMore": True}
+    with pytest.raises(HTTPError, match="no list-valued key"):
+        client.list_labels(98765)
+
+
+def test_that_request_paged_warns_when_multiple_list_keys(client, mocker):
+    mock = mocker.patch.object(client, "request_json")
+    mock.return_value = {
+        "totalSize": 1,
+        "labels": [{"id": 1, "name": "foo", "value": None, "resource": False}],
+        "extras": [{"id": 2}],
+    }
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        client.list_labels(98765)
+    assert len(caught) == 1
+    assert "multiple list-valued keys" in str(caught[0].message)
+
+
+def test_that_request_paged_tolerates_extra_boolean_fields(client, mocker):
+    mock = mocker.patch.object(client, "request_json")
+    mock.return_value = {
+        "totalSize": 1,
+        "labels": [{"id": 1, "name": "foo", "value": None, "resource": False}],
+        "hasMoreEntries": True,
+    }
+    result = client.list_labels(98765)
+    assert len(result) == 1