Make Python first-run URL and workflow identity mistakes fail clearly

Author: durable-workflow-ops

CHANGELOG.md

@@ -6,10 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-The Python SDK advances to the synchronized Durable Workflow `2.0.0-rc.7`
-product train. PyPI displays the normalized PEP 440 identity `2.0.0rc7`. Earlier SDK
-versions remain historical releases and are not alternate supported 2.0
-baselines; no prerelease compatibility shim is provided.
+The Python SDK advances to prerelease `2.0.0-rc.8`. PyPI displays the normalized
+PEP 440 identity `2.0.0rc8`. This SDK release is qualified with Server
+`2.0.0-rc.12`; SDK and Server prerelease sequence numbers advance independently.
+Earlier SDK versions remain historical releases and are not alternate supported
+2.0 baselines; no prerelease compatibility shim is provided.
 
 ### Added
 - The optimized `fastavro` payload path now uses the fixed recursive
@@ -50,6 +51,10 @@ baselines; no prerelease compatibility shim is provided.
   `NamespaceDescription.deleted`.
 
 ### Fixed
+- Client construction now rejects base URLs with a terminal SDK-owned `/api`
+  suffix, query, or fragment while preserving self-hosted and managed-runtime
+  path prefixes. The quickstart also uses unique durable workflow identities
+  and documents typed duplicate-start handling.
 - Condition-timeout history is now identified by its durable wait identity as
   well as its timer kind, keeping internal timeout rows out of the ordinary
   activity cursor when updates and signals resolve a timed condition.

README.md

@@ -2,16 +2,16 @@
 
 A Python SDK for the [Durable Workflow server](https://github.com/durable-workflow/server). Speaks the server's language-neutral HTTP/JSON worker protocol — no PHP runtime required.
 
-Status: **Beta** — this SDK is part of the synchronized Durable Workflow
-`2.0.0-rc.7` product train. Core features include workflows, activities,
+Status: **Beta** — this is Python SDK prerelease `2.0.0-rc.8` in the Durable
+Workflow 2.0 line. Core features include workflows, activities,
 schedules, signals, timers, child workflows, continue-as-new, side effects,
 version markers, worker-applied accepted updates, replay verification, the
 in-process `WorkflowEnvironment` test harness, and invocable activity carriers.
 
 ## Install
 
 ```bash
-pip install durable-workflow==2.0.0-rc.7
+pip install durable-workflow==2.0.0-rc.8
 ```
 
 Or for development:
@@ -24,6 +24,7 @@ pip install -e '.[dev]'
 
 ```python
 import asyncio
+from uuid import uuid4
 
 from durable_workflow import Client, Worker, workflow, activity
 
@@ -38,27 +39,46 @@ class GreeterWorkflow:
         return result
 
 async def main():
-    client = Client("http://server:8080", token="dev-token-123", namespace="default")
-    worker = Worker(
-        client,
-        task_queue="python-workers",
-        workflows=[GreeterWorkflow],
-        activities=[greet],
-    )
-    handle = await client.start_workflow(
-        workflow_type="greeter",
-        workflow_id="greet-1",
-        task_queue="python-workers",
-        input=["world"],
-    )
-    await worker.run_until(workflow_id="greet-1", timeout=30.0)
-    result = await client.get_result(handle)
-    print(result)  # "hello, world"
+    workflow_id = f"greet-{uuid4().hex}"
+    async with Client(
+        "http://server:8080",
+        token="dev-token-123",
+        namespace="default",
+    ) as client:
+        worker = Worker(
+            client,
+            task_queue="python-workers",
+            workflows=[GreeterWorkflow],
+            activities=[greet],
+        )
+        handle = await client.start_workflow(
+            workflow_type="greeter",
+            workflow_id=workflow_id,
+            task_queue="python-workers",
+            input=["world"],
+        )
+        await worker.run_until(workflow_id=workflow_id, timeout=30.0)
+        result = await client.get_result(handle)
+        print(result)  # "hello, world"
 
 if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+Pass the server or managed-runtime base URL to `Client`; the SDK appends its
+own `/api` routes. For example, use `http://server:8080`, not
+`http://server:8080/api`. Managed-runtime paths such as
+`https://cloud.example/api/runtime/v1/namespaces/acme` are valid as written.
+
+A workflow ID is the durable identity of an instance, not a per-attempt request
+ID. Starting the same ID again with the default `reject` duplicate policy raises
+the typed `WorkflowAlreadyStarted` exception. Generate a unique ID for each new
+instance, as the quickstart does. For an intentionally idempotent start, catch
+`WorkflowAlreadyStarted` and reconnect with
+`client.get_workflow_handle(workflow_id)`; choose `allow` or
+`terminate_existing` only when creating another run or replacing the current
+instance is the intended behavior.
+
 For a fuller deployable example, see
 [`examples/order_processing`](examples/order_processing), which runs a
 multi-activity order workflow against a local server with Docker Compose.
@@ -585,8 +605,11 @@ Full documentation is available at
 
 ## Compatibility
 
-SDK version `2.0.0-rc.7` is supported with server `2.0.0-rc.7`. The server
-must advertise these protocol manifests from `GET /api/cluster/info`:
+SDK version `2.0.0-rc.8` is qualified with
+`durableworkflow/server:2.0.0-rc.12`. The SDK package and Server release
+identities advance independently; matching RC sequence numbers are not
+required. The server must advertise these protocol manifests from
+`GET /api/cluster/info`:
 
 - `control_plane.version: "2"`
 - `control_plane.request_contract.schema: durable-workflow.v2.control-plane-request.contract` version `1`

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "durable-workflow"
-version = "2.0.0-rc.7"
+version = "2.0.0-rc.8"
 description = "Python SDK for the Durable Workflow server (language-neutral HTTP protocol)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -64,9 +64,9 @@ durable-workflow-replay-conformance = "durable_workflow.replay_conformance:main"
 durable-workflow-workflow-updates-conformance = "durable_workflow.workflow_updates_conformance:main"
 
 [tool.durable-workflow]
-product-train = "2.0.0-rc.7"
-registry-version = "2.0.0rc7"
-supported-server-versions = "2.0.0-rc.7"
+product-train = "2.0.0-rc.8"
+registry-version = "2.0.0rc8"
+supported-server-versions = "2.0.0-rc.12"
 worker-protocol-version = "1.1"
 control-plane-version = "2"
 

src/durable_workflow/client.py

@@ -29,7 +29,7 @@
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _pkg_version
 from typing import Any
-from urllib.parse import quote, urlencode
+from urllib.parse import quote, urlencode, urlsplit
 
 import httpx
 
@@ -97,6 +97,21 @@ def _protocol_version_from_env(name: str, default: str) -> str:
     return value.strip()
 
 
+def _normalize_base_url(base_url: str) -> str:
+    parsed = urlsplit(base_url)
+    if parsed.query or parsed.fragment:
+        raise ValueError("base_url must not include a query or fragment; pass only the server or managed-runtime URL")
+
+    normalized_path = parsed.path.rstrip("/")
+    if normalized_path.endswith("/api"):
+        raise ValueError(
+            "base_url must be the server or managed-runtime root without the SDK-owned '/api' suffix; "
+            "remove the trailing '/api' because Client appends it automatically"
+        )
+
+    return base_url.rstrip("/")
+
+
 def _route_for_metrics(path: str) -> str:
     clean_path = path.split("?", 1)[0]
     parts = [part for part in clean_path.strip("/").split("/") if part]
@@ -1232,6 +1247,9 @@ def iter_history(
 class Client:
     """Async HTTP client for Durable Workflow control-plane and worker APIs.
 
+    ``base_url`` is the server or managed-runtime prefix. Do not append the
+    SDK-owned ``/api`` route prefix or include a query string or fragment.
+
     The client owns one `httpx.AsyncClient` connection pool. Use it as an async
     context manager or call `aclose()` when finished.
     """
@@ -1254,7 +1272,7 @@ def __init__(
         external_storage_threshold_bytes: int | None = None,
         external_storage_cache: ExternalPayloadCache | None = None,
     ) -> None:
-        self.base_url = base_url.rstrip("/")
+        self.base_url = _normalize_base_url(base_url)
         self.token = token
         self.control_token = control_token
         self.worker_token = worker_token
@@ -1676,7 +1694,7 @@ async def execute_nexus_operation(
 
     # ── Health ─────────────────────────────────────────────────────────
     async def health(self) -> dict[str, Any]:
-        """Call the server's ``/health`` endpoint and return the JSON response."""
+        """Call the server's ``/api/health`` endpoint and return the JSON response."""
         result = await self._request("GET", "/health")
         if not isinstance(result, dict):
             raise ServerError(

tests/test_client.py

@@ -48,6 +48,70 @@ def client() -> Client:
     return Client("http://localhost:8080", token="test-token", namespace="ns1")
 
 
+class TestClientBaseUrl:
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        ("base_url", "expected"),
+        [
+            pytest.param(
+                "http://localhost:8080/",
+                "http://localhost:8080",
+                id="self-hosted-root",
+            ),
+            pytest.param(
+                "https://self-hosted.example/durable-workflow/",
+                "https://self-hosted.example/durable-workflow",
+                id="self-hosted-path-prefix",
+            ),
+            pytest.param(
+                "https://cloud.example/api/runtime/v1/namespaces/acme/",
+                "https://cloud.example/api/runtime/v1/namespaces/acme",
+                id="managed-runtime-prefix",
+            ),
+        ],
+    )
+    async def test_accepts_server_and_runtime_prefixes(self, base_url: str, expected: str) -> None:
+        client = Client(base_url)
+
+        assert client.base_url == expected
+        assert str(client._http.build_request("GET", "/api/health").url) == f"{expected}/api/health"
+
+        await client.aclose()
+
+    @pytest.mark.parametrize(
+        "base_url",
+        [
+            pytest.param("http://localhost:8080/api", id="self-hosted"),
+            pytest.param("http://localhost:8080/api/", id="self-hosted-trailing-slash"),
+            pytest.param(
+                "https://cloud.example/api/runtime/v1/namespaces/acme/api",
+                id="managed-runtime",
+            ),
+            pytest.param(
+                "https://cloud.example/api/runtime/v1/namespaces/acme/api/",
+                id="managed-runtime-trailing-slash",
+            ),
+        ],
+    )
+    def test_rejects_sdk_owned_api_suffix(self, base_url: str) -> None:
+        with pytest.raises(ValueError, match=r"remove the trailing '/api'"):
+            Client(base_url)
+
+    @pytest.mark.parametrize(
+        "base_url",
+        [
+            pytest.param("http://localhost:8080?region=local", id="self-hosted-query"),
+            pytest.param(
+                "https://cloud.example/api/runtime/v1/namespaces/acme#workers",
+                id="managed-runtime-fragment",
+            ),
+        ],
+    )
+    def test_rejects_query_and_fragment(self, base_url: str) -> None:
+        with pytest.raises(ValueError, match="query or fragment"):
+            Client(base_url)
+
+
 class TestHeaders:
     def test_control_plane_headers(self, client: Client) -> None:
         h = client._headers(worker=False)