💥 Return existing connection to public DID (#1843)

cl0ete · ff137 · web-flow · commit a9e271d79dda · 2025-09-22T08:54:38.000Z
* add reuse param

* if reuse find and return conn

* 🎨 Rename query param; code cleanup

* add tests

* update openapi spec

* rename to reuse_connection

* update unit tests

* update e2e tests

* update openapi spec

* update doc strings

* update openapi spec

* deduplicate

---------

Co-authored-by: ff137 &lt;ff137@proton.me&gt;
diff --git a/app/routes/connections.py b/app/routes/connections.py
@@ -204,6 +204,7 @@ async def create_did_exchange_request(  # noqa: D417
     goal: str | None = None,
     goal_code: str | None = None,
     my_label: str | None = None,
+    reuse_connection: bool = True,
     use_did: str | None = None,
     use_did_method: str | None = None,
     use_public_did: bool = False,
@@ -213,6 +214,9 @@ async def create_did_exchange_request(  # noqa: D417
     ---
     This endpoint allows you to initiate a DID Exchange request with another party using their public DID.
 
+    NB: By default, returns existing completed connections with the same `their_public_did` instead of creating
+    new ones. Set `reuse_connection` to False to disable this behavior.
+
     The goal and goal_code parameters provide additional context for the request.
 
     Only one of `use_did`, `use_did_method` or `use_public_did` should be specified. If none of these are specified,
@@ -230,6 +234,9 @@ async def create_did_exchange_request(  # noqa: D417
             Optional self-attested code for sharing the intent of the connection.
         my_label: str, optional
             Your label for the request.
+        reuse_connection: bool
+            If a connection with `their_public_did` already exists, return it instead of creating a new one.
+            Defaults to True.
         use_did: str, optional
             Your local DID to use for the connection.
         use_did_method: str, optional
@@ -250,6 +257,7 @@ async def create_did_exchange_request(  # noqa: D417
             "goal": goal,
             "goal_code": goal_code,
             "my_label": my_label,
+            "reuse_connection": reuse_connection,
             "use_did": use_did,
             "use_did_method": use_did_method,
             "use_public_did": use_public_did,
@@ -258,6 +266,40 @@ async def create_did_exchange_request(  # noqa: D417
     bound_logger.debug("POST request received: Create DID exchange request")
 
     async with client_from_auth(auth) as aries_controller:
+        if reuse_connection:
+            bound_logger.debug(
+                "Checking for existing connections with the same their_public_did"
+            )
+            existing_connections = await handle_acapy_call(
+                logger=bound_logger,
+                acapy_call=aries_controller.connection.get_connections,
+                their_public_did=their_public_did,
+            )
+
+            # Filter for completed connections after DB query for better performance
+            completed_connections = [
+                conn
+                for conn in existing_connections.results
+                if conn.rfc23_state == "completed"
+            ]
+
+            if completed_connections:
+                bound_logger.debug(
+                    "Found {} completed connection(s) with `their_public_did`: {}",
+                    len(completed_connections),
+                    their_public_did,
+                )
+                # Return the first completed connection instead of creating a new one
+                result = conn_record_to_connection(completed_connections[0])
+                bound_logger.debug(
+                    "Returning existing completed connection instead of creating new one."
+                )
+                return result
+            else:
+                bound_logger.debug(
+                    "No existing completed connections found. Creating new one."
+                )
+
         connection_record = await handle_acapy_call(
             logger=bound_logger,
             acapy_call=aries_controller.did_exchange.create_request,
diff --git a/app/tests/e2e/test_did_exchange.py b/app/tests/e2e/test_did_exchange.py
@@ -41,7 +41,10 @@ async def test_create_did_exchange_request(
         controller=faber_anoncreds_acapy_client
     )
 
-    request_data = {"their_public_did": faber_public_did.did}
+    request_data = {
+        "their_public_did": faber_public_did.did,
+        "reuse_connection": False,
+    }
 
     if use_did:
         new_did = await acapy_wallet.create_did(
diff --git a/app/tests/e2e/test_did_rotate.py b/app/tests/e2e/test_did_rotate.py
@@ -25,7 +25,7 @@ async def test_rotate_did(
         controller=faber_anoncreds_acapy_client
     )
 
-    request_data = {"their_public_did": faber_public_did.did}
+    request_data = {"their_public_did": faber_public_did.did, "reuse_connection": False}
     response = await alice_member_client.post(
         f"{CONNECTIONS_BASE_PATH}/did-exchange/create-request", params=request_data
     )
@@ -67,7 +67,7 @@ async def test_hangup_did_rotation(
         controller=faber_anoncreds_acapy_client
     )
 
-    request_data = {"their_public_did": faber_public_did.did}
+    request_data = {"their_public_did": faber_public_did.did, "reuse_connection": False}
     response = await alice_member_client.post(
         f"{CONNECTIONS_BASE_PATH}/did-exchange/create-request", params=request_data
     )
diff --git a/app/tests/routes/connections/test_create_did_exchange_request.py b/app/tests/routes/connections/test_create_did_exchange_request.py
@@ -25,6 +25,88 @@
 )
 
 
+@pytest.fixture
+def mock_aries_controller():
+    """Create a mock aries controller with default setup."""
+    mock_controller = AsyncMock()
+    mock_controller.did_exchange.create_request = AsyncMock(
+        return_value=created_connection
+    )
+    mock_controller.connection.get_connections = AsyncMock(
+        return_value=AsyncMock(results=[])
+    )
+    return mock_controller
+
+
+@pytest.fixture
+def mock_patches():
+    """Setup common patches used across multiple tests."""
+    with (
+        patch("app.routes.connections.client_from_auth") as mock_client_from_auth,
+        patch(
+            "app.routes.connections.conn_record_to_connection",
+            return_value=created_connection,
+        ) as mock_conn_record,
+    ):
+        yield mock_client_from_auth, mock_conn_record
+
+
+def setup_controller_context(mock_client_from_auth, mock_controller):
+    """Setup the controller context for the mock client."""
+    mock_client_from_auth.return_value.__aenter__.return_value = mock_controller
+
+
+async def call_create_did_exchange_request(**kwargs):
+    """Helper to call create_did_exchange_request with default values."""
+    defaults = {
+        "their_public_did": test_their_public_did,
+        "alias": None,
+        "goal": None,
+        "goal_code": None,
+        "my_label": None,
+        "reuse_connection": True,
+        "use_did": None,
+        "use_did_method": None,
+        "use_public_did": False,
+        "auth": "mocked_auth",
+    }
+    defaults.update(kwargs)
+    return await create_did_exchange_request(**defaults)
+
+
+def assert_get_connections_called(mock_controller, should_be_called=True):
+    """Assert whether get_connections was called as expected."""
+    if should_be_called:
+        mock_controller.connection.get_connections.assert_awaited_once_with(
+            their_public_did=test_their_public_did
+        )
+    else:
+        mock_controller.connection.get_connections.assert_not_awaited()
+
+
+def assert_create_request_called(
+    mock_controller, should_be_called=True, **expected_params
+):
+    """Assert whether create_request was called as expected."""
+    if should_be_called:
+        defaults = {
+            "their_public_did": test_their_public_did,
+            "alias": None,
+            "auto_accept": True,
+            "goal": None,
+            "goal_code": None,
+            "my_label": None,
+            "protocol": "didexchange/1.1",
+            "use_did": None,
+            "use_did_method": None,
+            "use_public_did": False,
+        }
+        defaults.update(expected_params)
+        mock_controller.did_exchange.create_request.assert_awaited_once_with(**defaults)
+    else:
+        mock_controller.did_exchange.create_request.assert_not_awaited()
+
+
 @pytest.mark.anyio
 @pytest.mark.parametrize(
     "body_params, expected_alias, expected_use_did, expected_use_did_method, expected_use_public_did",
@@ -59,52 +141,38 @@ async def test_create_did_exchange_request_success(
     expected_use_did,
     expected_use_did_method,
     expected_use_public_did,
+    mock_aries_controller,
+    mock_patches,
 ):
-    mock_aries_controller = AsyncMock()
-    mock_aries_controller.did_exchange.create_request = AsyncMock(
-        return_value=created_connection
-    )
+    mock_client_from_auth, mock_conn_record = mock_patches
+    setup_controller_context(mock_client_from_auth, mock_aries_controller)
 
-    with (
-        patch("app.routes.connections.client_from_auth") as mock_client_from_auth,
-        patch(
-            "app.routes.connections.conn_record_to_connection",
-            return_value=created_connection,
-        ),
-    ):
-        mock_client_from_auth.return_value.__aenter__.return_value = (
-            mock_aries_controller
-        )
+    if not body_params:
+        body_params = {}
 
-        if not body_params:
-            body_params = {}
-
-        response = await create_did_exchange_request(
-            their_public_did=test_their_public_did,
-            alias=body_params.get("alias"),
-            goal=body_params.get("goal"),
-            goal_code=body_params.get("goal_code"),
-            my_label=body_params.get("my_label"),
-            use_did=body_params.get("use_did"),
-            use_did_method=body_params.get("use_did_method"),
-            use_public_did=body_params.get("use_public_did", False),
-            auth="mocked_auth",
-        )
+    response = await call_create_did_exchange_request(
+        alias=body_params.get("alias"),
+        goal=body_params.get("goal"),
+        goal_code=body_params.get("goal_code"),
+        my_label=body_params.get("my_label"),
+        reuse_connection=body_params.get("reuse_connection", True),
+        use_did=body_params.get("use_did"),
+        use_did_method=body_params.get("use_did_method"),
+        use_public_did=body_params.get("use_public_did", False),
+    )
 
-        assert response == created_connection
-
-        mock_aries_controller.did_exchange.create_request.assert_awaited_once_with(
-            their_public_did=test_their_public_did,
-            alias=expected_alias,
-            auto_accept=True,
-            goal=body_params.get("goal"),
-            goal_code=body_params.get("goal_code"),
-            my_label=body_params.get("my_label"),
-            protocol="didexchange/1.1",
-            use_did=expected_use_did,
-            use_did_method=expected_use_did_method,
-            use_public_did=expected_use_public_did,
-        )
+    assert response == created_connection
+
+    assert_create_request_called(
+        mock_aries_controller,
+        alias=expected_alias,
+        goal=body_params.get("goal"),
+        goal_code=body_params.get("goal_code"),
+        my_label=body_params.get("my_label"),
+        use_did=expected_use_did,
+        use_did_method=expected_use_did_method,
+        use_public_did=expected_use_public_did,
+    )
 
 
 @pytest.mark.anyio
@@ -117,26 +185,106 @@ async def test_create_did_exchange_request_success(
     ],
 )
 async def test_create_did_exchange_request_fail_acapy_error(
-    exception_class, expected_status_code, expected_detail
+    exception_class,
+    expected_status_code,
+    expected_detail,
+    mock_aries_controller,
+    mock_patches,
 ):
-    mock_aries_controller = AsyncMock()
+    mock_client_from_auth, mock_conn_record = mock_patches
     mock_aries_controller.did_exchange.create_request = AsyncMock(
         side_effect=exception_class(status=expected_status_code, reason=expected_detail)
     )
+    setup_controller_context(mock_client_from_auth, mock_aries_controller)
 
-    with (
-        patch("app.routes.connections.client_from_auth") as mock_client_from_auth,
-        pytest.raises(HTTPException, match=expected_detail) as exc,
-        patch("app.routes.connections.conn_record_to_connection"),
-    ):
-        mock_client_from_auth.return_value.__aenter__.return_value = (
-            mock_aries_controller
-        )
-
-        await create_did_exchange_request(
-            their_public_did=test_their_public_did,
-            alias=None,
-            auth="mocked_auth",
-        )
+    with pytest.raises(HTTPException, match=expected_detail) as exc:
+        await call_create_did_exchange_request(alias=None)
 
     assert exc.value.status_code == expected_status_code
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize(
+    "reuse_connection, existing_connections, should_get_connections, should_create_request, expected_response",
+    [
+        # When reuse_connection=True and completed connection exists, return existing
+        (
+            True,
+            [
+                ConnRecord(
+                    connection_id="existing_id",
+                    state="completed",
+                    rfc23_state="completed",
+                    their_did=test_their_public_did,
+                )
+            ],
+            True,
+            False,
+            "existing_connection",
+        ),
+        # When reuse_connection=True but only non-completed connections exist, create new
+        (
+            True,
+            [
+                ConnRecord(
+                    connection_id="non_completed_id",
+                    state="request-sent",
+                    rfc23_state="request-sent",
+                    their_did=test_their_public_did,
+                )
+            ],
+            True,
+            True,
+            "new_connection",
+        ),
+        # When reuse_connection=True but no existing connections, create new
+        (True, [], True, True, "new_connection"),
+        # When reuse_connection=False, always create new (don't check existing)
+        (
+            False,
+            [
+                ConnRecord(
+                    connection_id="existing_id",
+                    state="completed",
+                    rfc23_state="completed",
+                    their_did=test_their_public_did,
+                )
+            ],
+            False,
+            True,
+            "new_connection",
+        ),
+    ],
+)
+async def test_create_did_exchange_request_reuse_scenarios(
+    reuse_connection,
+    existing_connections,
+    should_get_connections,
+    should_create_request,
+    expected_response,
+    mock_aries_controller,
+    mock_patches,
+):
+    """Test various scenarios for connection reuse behavior."""
+    mock_client_from_auth, mock_conn_record = mock_patches
+
+    # Setup existing connections
+    mock_aries_controller.connection.get_connections = AsyncMock(
+        return_value=AsyncMock(results=existing_connections)
+    )
+
+    # Determine expected return value
+    if expected_response == "existing_connection" and existing_connections:
+        expected_connection = existing_connections[0]
+        mock_conn_record.return_value = expected_connection
+    else:
+        expected_connection = created_connection
+        mock_conn_record.return_value = created_connection
+
+    setup_controller_context(mock_client_from_auth, mock_aries_controller)
+
+    response = await call_create_did_exchange_request(reuse_connection=reuse_connection)
+
+    assert response == expected_connection
+    assert_get_connections_called(mock_aries_controller, should_get_connections)
+    assert_create_request_called(mock_aries_controller, should_create_request)
diff --git a/docs/openapi/tenant-openapi.json b/docs/openapi/tenant-openapi.json
diff --git a/docs/openapi/tenant-openapi.yaml b/docs/openapi/tenant-openapi.yaml

Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,7 @@ async def test_rotate_did(`
`25`	`25`	`controller=faber_anoncreds_acapy_client`
`26`	`26`	`)`
`27`	`27`
`28`		`- request_data = {"their_public_did": faber_public_did.did}`
	`28`	`+ request_data = {"their_public_did": faber_public_did.did, "reuse_connection": False}`
`29`	`29`	`response = await alice_member_client.post(`
`30`	`30`	`f"{CONNECTIONS_BASE_PATH}/did-exchange/create-request", params=request_data`
`31`	`31`	`)`
`@@ -67,7 +67,7 @@ async def test_hangup_did_rotation(`
`67`	`67`	`controller=faber_anoncreds_acapy_client`
`68`	`68`	`)`
`69`	`69`
`70`		`- request_data = {"their_public_did": faber_public_did.did}`
	`70`	`+ request_data = {"their_public_did": faber_public_did.did, "reuse_connection": False}`
`71`	`71`	`response = await alice_member_client.post(`
`72`	`72`	`f"{CONNECTIONS_BASE_PATH}/did-exchange/create-request", params=request_data`
`73`	`73`	`)`