From efe5c3da5e208dc92226a33a46629ea3052386b7 Mon Sep 17 00:00:00 2001 From: chandusailella Date: Fri, 20 Nov 2026 02:14:39 +0530 Subject: [PATCH 1/2] feat(integration-service): add execute_activity and execute_http Add an `integration_service` package to uipath-platform, exposed as `sdk.integration_service`, for parity with the TypeScript SDK (UiPath/uipath-typescript#864). - execute_activity: run a connector object operation, with body keys as paths, multipart file upload, file download as bytes, paging (`page` / `max_records`) and Base64 URL query fields. A connector of version 4 or later runs on the version 4 engine. - execute_http: send a raw HTTP request to the vendor behind a connection, through the version 3 passthrough or the version 4 engine. Neither raises on a non-2xx response. Both have async forms. The existing connections service is not changed. Co-Authored-By: Claude Fable 5.2 --- packages/uipath-platform/CLAUDE.md | 2 + packages/uipath-platform/pyproject.toml | 2 +- .../src/uipath/platform/_uipath.py | 5 + .../platform/integration_service/__init__.py | 24 + .../_integration_service.py | 820 +++++++++++ .../integration_service/execution/__init__.py | 67 + .../execution/_body_paths.py | 116 ++ .../execution/_multipart.py | 45 + .../execution/_pagination.py | 126 ++ .../execution/_proxy_response.py | 78 ++ .../integration_service/execution/_request.py | 73 + .../execution/_response_content.py | 105 ++ .../execution/_url_input.py | 51 + .../execution/_v4_execute.py | 245 ++++ .../integration_service/execution_types.py | 79 ++ .../services/test_integration_service.py | 1247 +++++++++++++++++ packages/uipath-platform/uv.lock | 2 +- .../uipath/docs/core/integration_service.md | 3 + packages/uipath/mkdocs.yml | 1 + packages/uipath/uv.lock | 2 +- 20 files changed, 3090 insertions(+), 3 deletions(-) create mode 100644 packages/uipath-platform/src/uipath/platform/integration_service/__init__.py create mode 100644 packages/uipath-platform/src/uipath/platform/integration_service/_integration_service.py create mode 100644 packages/uipath-platform/src/uipath/platform/integration_service/execution/__init__.py create mode 100644 packages/uipath-platform/src/uipath/platform/integration_service/execution/_body_paths.py create mode 100644 packages/uipath-platform/src/uipath/platform/integration_service/execution/_multipart.py create mode 100644 packages/uipath-platform/src/uipath/platform/integration_service/execution/_pagination.py create mode 100644 packages/uipath-platform/src/uipath/platform/integration_service/execution/_proxy_response.py create mode 100644 packages/uipath-platform/src/uipath/platform/integration_service/execution/_request.py create mode 100644 packages/uipath-platform/src/uipath/platform/integration_service/execution/_response_content.py create mode 100644 packages/uipath-platform/src/uipath/platform/integration_service/execution/_url_input.py create mode 100644 packages/uipath-platform/src/uipath/platform/integration_service/execution/_v4_execute.py create mode 100644 packages/uipath-platform/src/uipath/platform/integration_service/execution_types.py create mode 100644 packages/uipath-platform/tests/services/test_integration_service.py create mode 100644 packages/uipath/docs/core/integration_service.md diff --git a/packages/uipath-platform/CLAUDE.md b/packages/uipath-platform/CLAUDE.md index f695ef911..c3767dbb9 100644 --- a/packages/uipath-platform/CLAUDE.md +++ b/packages/uipath-platform/CLAUDE.md @@ -37,6 +37,7 @@ sdk.jobs # JobsService sdk.folders # FolderService sdk.tasks # TasksService (Action Center) sdk.connections # ConnectionsService +sdk.integration_service # IntegrationService (connector activity execution, vendor HTTP) sdk.context_grounding # ContextGroundingService sdk.documents # DocumentsService (DU Framework API v1.1) sdk.documents_v2 # DocumentsServiceV2 (DU Framework API v2) @@ -101,6 +102,7 @@ Services provide both sync and async variants (e.g., `.invoke()` and `.invoke_as | `business_rules/` | Business rule runs: rules deployed to Orchestrator, or undeployed rules in a debug job's Studio project, behind one `run()` | | `chat/` | LLM gateway, conversations, throttling | | `connections/` | External connection management | +| `integration_service/` | Integration Service execution: `execute_activity()` on a connector object and `execute_http()` to the vendor, neither raising on a non-2xx; pure request/response helpers in `execution/` | | `context_grounding/` | RAG services (DeepRAG, batch RAG, ephemeral indexes) | | `documents/` | Document Understanding (IXP) | | `entities/` | Data Service entity management | diff --git a/packages/uipath-platform/pyproject.toml b/packages/uipath-platform/pyproject.toml index 78f8bc068..fdafe30cd 100644 --- a/packages/uipath-platform/pyproject.toml +++ b/packages/uipath-platform/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "uipath-platform" -version = "0.3.12" +version = "0.3.13" description = "HTTP client library for programmatic access to UiPath Platform" readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.11" diff --git a/packages/uipath-platform/src/uipath/platform/_uipath.py b/packages/uipath-platform/src/uipath/platform/_uipath.py index dddbc2c37..f292dc011 100644 --- a/packages/uipath-platform/src/uipath/platform/_uipath.py +++ b/packages/uipath-platform/src/uipath/platform/_uipath.py @@ -25,6 +25,7 @@ from .external_applications import ExternalApplicationService from .governance import GovernanceService from .guardrails import GuardrailsService +from .integration_service import IntegrationService from .memory import MemoryService from .ontology import OntologyService from .orchestrator import ( @@ -120,6 +121,10 @@ def buckets(self) -> BucketsService: def connections(self) -> ConnectionsService: return ConnectionsService(self._config, self._execution_context, self.folders) + @cached_property + def integration_service(self) -> IntegrationService: + return IntegrationService(self._config, self._execution_context) + @property def context_grounding(self) -> ContextGroundingService: return ContextGroundingService( diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/__init__.py b/packages/uipath-platform/src/uipath/platform/integration_service/__init__.py new file mode 100644 index 000000000..a72c19414 --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/integration_service/__init__.py @@ -0,0 +1,24 @@ +"""UiPath Integration Service. + +Connector activity execution and vendor HTTP requests through a connection. +""" + +from ._integration_service import IntegrationService +from .execution_types import ( + ExecuteActivityResult, + ExecuteFile, + ExecuteHttpResult, + ExecuteMethod, + ExecutePage, + ExecuteResult, +) + +__all__ = [ + "IntegrationService", + "ExecuteActivityResult", + "ExecuteFile", + "ExecuteHttpResult", + "ExecuteMethod", + "ExecutePage", + "ExecuteResult", +] diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/_integration_service.py b/packages/uipath-platform/src/uipath/platform/integration_service/_integration_service.py new file mode 100644 index 000000000..0d867e845 --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/integration_service/_integration_service.py @@ -0,0 +1,820 @@ +"""Integration Service: connector activity execution and vendor HTTP requests.""" + +import asyncio +import time +from typing import Any, Dict, Optional, Sequence + +from httpx import Response, TransportError +from uipath.core.tracing import traced + +from ..common._base_service import BaseService, _inject_trace_context +from ..common._bindings import resource_override +from ..common._config import UiPathApiConfig, UiPathConfig +from ..common._execution_context import UiPathExecutionContext +from ..common._folder_context import header_folder +from ..common._service_url_overrides import ( + inject_routing_headers, + resolve_service_url, +) +from ..common._user_agent import user_agent_value +from ..common.retry import ( + RETRYABLE_STATUS_CODES, + exponential_backoff_with_jitter, + parse_retry_after, +) +from ..constants import HEADER_USER_AGENT +from . import execution as _exec +from .execution_types import ( + ExecuteActivityResult, + ExecuteFile, + ExecuteHttpResult, + ExecuteResult, +) + +HEADER_ORIGINATOR = "x-uipath-originator" +HEADER_SOURCE = "x-uipath-source" +# Lets GenAI activities be stitched back to the parent job for licensing attribution. +HEADER_ACTIVITY_JOB_ID = "x-uipath-job-id" +_ORIGINATOR_VALUE = "uipath-python" + +# Statuses of the Integration Service call that an opted-in retry sends again. +_EXECUTE_RETRYABLE_STATUS_CODES = RETRYABLE_STATUS_CODES | {500} +_EXECUTE_INITIAL_BACKOFF = 0.5 +_EXECUTE_MAX_BACKOFF = 10.0 + + +def _hide_file_bytes(inputs: Dict[str, Any]) -> Dict[str, Any]: + """Keep uploaded file content out of the trace.""" + hidden = dict(inputs) + for key in ("files", "file"): + if hidden.get(key): + hidden[key] = "" + return hidden + + +class IntegrationService(BaseService): + """Service for running Integration Service connector operations. + + Runs a connector activity (`execute_activity`) or sends a raw HTTP request + to the vendor behind a connection (`execute_http`). Neither raises on a + non-2xx response: the result carries the status and the vendor's body. + + For looking connections up and fetching their tokens, see + `ConnectionsService` (`sdk.connections`). + """ + + def __init__( + self, + config: UiPathApiConfig, + execution_context: UiPathExecutionContext, + ) -> None: + super().__init__(config=config, execution_context=execution_context) + + @resource_override( + "connection", + resource_identifier="connection_id", + folder_identifier="folder_key", + ) + @traced( + name="integration_service_execute_activity", + run_type="uipath", + input_processor=_hide_file_bytes, + hide_output=True, + ) + def execute_activity( + self, + connection_id: str, + object_name: str, + method: str = "GET", + *, + body: Any = None, + query_params: Optional[Dict[str, str]] = None, + files: Optional[Sequence[ExecuteFile]] = None, + body_part_name: Optional[str] = None, + url_input_fields: Optional[Sequence[str]] = None, + file_response: bool = False, + max_records: Optional[int] = None, + connector_version: Optional[str] = None, + connector_key: Optional[str] = None, + script_ref: Optional[str] = None, + headers: Optional[Dict[str, str]] = None, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + max_retries: int = 0, + retry_methods: Optional[Sequence[str]] = None, + timeout: Optional[float] = None, + ) -> ExecuteActivityResult: + """Run a connector activity: one operation on a connector object. + + Calls `elements_/v3/element/instances/{connection_id}/{object_name}`, or + the version 4 engine when `connector_version` is 4 or later, and adds what a connector activity needs: body keys given as paths, file + upload and download, paging, and query parameters that take a URL. + + Unlike most SDK methods, **this does not raise on a non-2xx response**. + The full HTTP envelope is returned so the caller can read the + connector's error body. Check `ok` and `status`. + + Preview: this method is experimental and may change. + + Args: + connection_id: The connection's id. + object_name: Connector object name, e.g. `tickets`. May be a + multi-segment path such as `curated_get_issue/ABC-1`. + method: HTTP method: `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. + body: Body for `POST`, `PUT` or `PATCH`, sent as JSON. A top-level + key of a dict can be a path: `{"fields.summary": "x"}` is sent + as `{"fields": {"summary": "x"}}`. A path can address an array + item (`items[0].name`) or every item (`items[*].name`). A + write sent without a body carries `{}`. + query_params: Query string parameters. + files: Files to upload. The call is sent as a multipart form with + one part per file, and a non-empty `body` travels as a JSON + part named by `body_part_name`. + body_part_name: Name of the form part that carries `body` when + `files` is set. Defaults to `body`. + url_input_fields: Names of the query parameters the connector + marks as accepting a URL. A listed parameter whose value is an + http or https URL is sent Base64-encoded. + file_response: Read a successful response as a file: `body` is + `bytes` whatever content type the connector reports. Without + it a file is still detected from the response headers. + max_records: How many records a `GET` list call should return in + total. The call follows the connector's pages until it has + this many records or the list ends. Pass `-1` for every + record. Without it a single page is returned, with `page` set + on the result when more records exist. + connector_version: Version of the connector behind the connection, + e.g. `4.0.0`. A connector of version 4 or later runs its + activities on the version 4 engine (`elements_/v4/execute`), + and the call is sent there; without a version, or with an + earlier one, the call uses the version 3 engine. The SDK does + not look the version up. On the version 4 engine `object_name` + names the activity's script, `files` is refused, and + `file_response`, `url_input_fields` and `max_records` do not + apply. + connector_key: Key of the connector behind the connection, e.g. + `uipath-salesforce-slack`. Required on the version 4 engine. + script_ref: Reference of the script the version 4 engine runs for + this activity, as the activity's metadata names it. Defaults + to `object_name`. + headers: Headers the activity's script reads from the call. + Version 4 engine only. + folder_key: Key of the folder the connection is in. + folder_path: Path of the folder the connection is in. Mutually + exclusive with `folder_key`. + max_retries: How many times to send a failed call again. Off by + default. + retry_methods: Methods that may be retried. Defaults to the + idempotent ones (`GET`, `PUT`, `DELETE`): a replayed `POST` + can create the same record twice. + timeout: Timeout of a single attempt, in seconds. + + Returns: + ExecuteActivityResult: The response envelope, whatever its status. + + Raises: + ValueError: If an argument is missing or invalid. + + Examples: + >>> result = sdk.integration_service.execute_activity("", "tickets") + >>> if result.ok: + ... print(result.body) + + >>> sdk.integration_service.execute_activity( + ... "", "tickets", "POST", + ... body={"subject": "New ticket", "fields.priority": "high"}, + ... ) + + >>> everything = sdk.integration_service.execute_activity( + ... "", "tickets", max_records=-1 + ... ) + + >>> # A connector of version 4 or later: pass its version and key + >>> sdk.integration_service.execute_activity( + ... "", "SendMessageToChannel", "POST", + ... connector_version="4.0.0", + ... connector_key="uipath-salesforce-slack", + ... query_params={"send_as": "bot"}, + ... body={"channel": "", "messageToSend": "Hello"}, + ... ) + """ + request, limit, on_v4 = self._activity_request( + connection_id, + object_name, + method, + body=body, + query_params=query_params, + files=files, + body_part_name=body_part_name, + url_input_fields=url_input_fields, + file_response=file_response, + max_records=max_records, + connector_version=connector_version, + connector_key=connector_key, + script_ref=script_ref, + headers=headers, + folder_key=folder_key, + folder_path=folder_path, + max_retries=max_retries, + retry_methods=retry_methods, + timeout=timeout, + ) + + first = self._send_execute(request) + if on_v4: + return _exec.to_v4_activity_result(first) + if limit is None or not _exec.needs_paging(request.method, limit, first): + return _exec.to_activity_result(first) + + records = list(first.body) + last = first + followed = False + page = _exec.extract_page(first.headers, first.body) + while page and page.has_more and len(records) < limit: + following = self._send_execute(_exec.next_page_request(request, page)) + if not following.ok: + # A page that fails is the result, so the caller sees the failure + return _exec.to_activity_result(following) + followed = True + last = following + if isinstance(following.body, list): + records.extend(following.body) + page = _exec.extract_page(following.headers, following.body) + return _exec.gathered_result(first, last, records, limit, followed) + + @resource_override( + "connection", + resource_identifier="connection_id", + folder_identifier="folder_key", + ) + @traced( + name="integration_service_execute_activity", + run_type="uipath", + input_processor=_hide_file_bytes, + hide_output=True, + ) + async def execute_activity_async( + self, + connection_id: str, + object_name: str, + method: str = "GET", + *, + body: Any = None, + query_params: Optional[Dict[str, str]] = None, + files: Optional[Sequence[ExecuteFile]] = None, + body_part_name: Optional[str] = None, + url_input_fields: Optional[Sequence[str]] = None, + file_response: bool = False, + max_records: Optional[int] = None, + connector_version: Optional[str] = None, + connector_key: Optional[str] = None, + script_ref: Optional[str] = None, + headers: Optional[Dict[str, str]] = None, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + max_retries: int = 0, + retry_methods: Optional[Sequence[str]] = None, + timeout: Optional[float] = None, + ) -> ExecuteActivityResult: + """Asynchronously run a connector activity. + + The asynchronous form of `execute_activity`: same arguments, same + result, and it does not raise on a non-2xx response either. + + Preview: this method is experimental and may change. + + Args: + connection_id: The connection's id. + object_name: Connector object name, e.g. `tickets`. + method: HTTP method: `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. + body: Body for `POST`, `PUT` or `PATCH`. Top-level keys of a dict + can be paths, e.g. `fields.summary`. + query_params: Query string parameters. + files: Files to upload as a multipart form. + body_part_name: Name of the form part that carries `body` when + `files` is set. Defaults to `body`. + url_input_fields: Names of the query parameters that take a URL. + file_response: Read a successful response as `bytes`. + max_records: Total records a `GET` list call should gather across + pages; `-1` for every record. + connector_version: Version of the connector behind the connection; + 4 or later selects the version 4 engine. + connector_key: Key of the connector behind the connection. + Required on the version 4 engine. + script_ref: Reference of the script the version 4 engine runs. + Defaults to `object_name`. + headers: Headers the activity's script reads (version 4 only). + folder_key: Key of the folder the connection is in. + folder_path: Path of the folder the connection is in. + max_retries: How many times to send a failed call again. + retry_methods: Methods that may be retried. + timeout: Timeout of a single attempt, in seconds. + + Returns: + ExecuteActivityResult: The response envelope, whatever its status. + + Raises: + ValueError: If an argument is missing or invalid. + + Examples: + >>> result = await sdk.integration_service.execute_activity_async( + ... "", "tickets" + ... ) + """ + request, limit, on_v4 = self._activity_request( + connection_id, + object_name, + method, + body=body, + query_params=query_params, + files=files, + body_part_name=body_part_name, + url_input_fields=url_input_fields, + file_response=file_response, + max_records=max_records, + connector_version=connector_version, + connector_key=connector_key, + script_ref=script_ref, + headers=headers, + folder_key=folder_key, + folder_path=folder_path, + max_retries=max_retries, + retry_methods=retry_methods, + timeout=timeout, + ) + + first = await self._send_execute_async(request) + if on_v4: + return _exec.to_v4_activity_result(first) + if limit is None or not _exec.needs_paging(request.method, limit, first): + return _exec.to_activity_result(first) + + records = list(first.body) + last = first + followed = False + page = _exec.extract_page(first.headers, first.body) + while page and page.has_more and len(records) < limit: + following = await self._send_execute_async( + _exec.next_page_request(request, page) + ) + if not following.ok: + # A page that fails is the result, so the caller sees the failure + return _exec.to_activity_result(following) + followed = True + last = following + if isinstance(following.body, list): + records.extend(following.body) + page = _exec.extract_page(following.headers, following.body) + return _exec.gathered_result(first, last, records, limit, followed) + + @resource_override( + "connection", + resource_identifier="connection_id", + folder_identifier="folder_key", + ) + @traced( + name="integration_service_execute_http", + run_type="uipath", + input_processor=_hide_file_bytes, + hide_output=True, + ) + def execute_http( + self, + connection_id: str, + url: str, + method: str = "GET", + *, + headers: Optional[Dict[str, str]] = None, + query_params: Optional[Dict[str, str]] = None, + body: Any = None, + connector_version: Optional[str] = None, + connector_key: Optional[str] = None, + file: Optional[ExecuteFile] = None, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + max_retries: int = 0, + retry_methods: Optional[Sequence[str]] = None, + timeout: Optional[float] = None, + ) -> ExecuteHttpResult: + """Send an HTTP request to a vendor API through a connection. + + Integration Service adds the connection's authentication, so the + vendor's key or token never reaches your code. Use this for a vendor + endpoint the connector has no object for; for a connector object use + `execute_activity`. + + The result describes the vendor's response. **This does not raise on a + non-2xx response**: check `ok`, and `is_vendor_error` to tell a vendor + error from a call that never reached the vendor. + + Preview: this method is experimental and may change. + + Args: + connection_id: The connection's id. + url: Vendor URL. A path such as `/v2/tickets` is resolved against + the connection's base URL. On the version 4 engine it must be + a full URL. + method: HTTP method to send to the vendor. + headers: Headers to send to the vendor. + query_params: Query string parameters to send to the vendor. + body: Body to send to the vendor. A string is sent as is; anything + else is serialized as JSON. + connector_version: Version of the connector behind the connection, + e.g. `4.0.0`. A connector of version 4 or later runs on the + version 4 engine (`elements_/v4/execute`); without a version, + or with an earlier one, the call uses the version 3 + passthrough. The SDK does not look the version up. + connector_key: Key of the connector behind the connection, e.g. + `uipath-zendesk`. Used on the version 4 engine. + file: A file to send as the whole body of the vendor request. + Needs a version 4 connector, and cannot be combined with + `body`. + folder_key: Key of the folder the connection is in. + folder_path: Path of the folder the connection is in. Mutually + exclusive with `folder_key`. + max_retries: How many times to send a failed call again. Off by + default. Only a failure of the Integration Service call itself + is retried; a vendor error status is returned as the result. + retry_methods: Vendor methods that may be retried. Defaults to the + idempotent ones, so a `GET` is retried and a `POST` is not. + timeout: Timeout of a single attempt, in seconds. + + Returns: + ExecuteHttpResult: The vendor's response, or the Integration + Service response when the call did not reach the vendor. + + Raises: + ValueError: If an argument is missing or invalid, or a version 4 + file response arrives incomplete. + + Examples: + >>> result = sdk.integration_service.execute_http("", "/v2/tickets") + >>> if result.ok: + ... print(result.body) + ... elif result.is_vendor_error: + ... print(f"Vendor returned {result.status}: {result.body}") + + >>> sdk.integration_service.execute_http( + ... "", "https://api.example.com/v2/tickets", "POST", + ... body={"subject": "New ticket"}, + ... connector_version="4.0.0", + ... ) + """ + request, on_v4 = self._http_request( + connection_id, + url, + method, + headers=headers, + query_params=query_params, + body=body, + connector_version=connector_version, + connector_key=connector_key, + file=file, + folder_key=folder_key, + folder_path=folder_path, + max_retries=max_retries, + retry_methods=retry_methods, + timeout=timeout, + ) + result = self._send_execute(request) + return ( + _exec.unwrap_v4_response(result) + if on_v4 + else _exec.unwrap_proxy_response(result) + ) + + @resource_override( + "connection", + resource_identifier="connection_id", + folder_identifier="folder_key", + ) + @traced( + name="integration_service_execute_http", + run_type="uipath", + input_processor=_hide_file_bytes, + hide_output=True, + ) + async def execute_http_async( + self, + connection_id: str, + url: str, + method: str = "GET", + *, + headers: Optional[Dict[str, str]] = None, + query_params: Optional[Dict[str, str]] = None, + body: Any = None, + connector_version: Optional[str] = None, + connector_key: Optional[str] = None, + file: Optional[ExecuteFile] = None, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + max_retries: int = 0, + retry_methods: Optional[Sequence[str]] = None, + timeout: Optional[float] = None, + ) -> ExecuteHttpResult: + """Asynchronously send an HTTP request to a vendor API through a connection. + + The asynchronous form of `execute_http`: same arguments, same result, + and it does not raise on a non-2xx response either. + + Preview: this method is experimental and may change. + + Args: + connection_id: The connection's id. + url: Vendor URL, or a path resolved against the connection's base + URL. A full URL on the version 4 engine. + method: HTTP method to send to the vendor. + headers: Headers to send to the vendor. + query_params: Query string parameters to send to the vendor. + body: Body to send to the vendor. + connector_version: Version of the connector behind the connection; + 4 or later selects the version 4 engine. + connector_key: Key of the connector behind the connection. + file: A file to send as the whole body (version 4 only). + folder_key: Key of the folder the connection is in. + folder_path: Path of the folder the connection is in. + max_retries: How many times to send a failed call again. + retry_methods: Vendor methods that may be retried. + timeout: Timeout of a single attempt, in seconds. + + Returns: + ExecuteHttpResult: The vendor's response, or the Integration + Service response when the call did not reach the vendor. + + Raises: + ValueError: If an argument is missing or invalid, or a version 4 + file response arrives incomplete. + + Examples: + >>> result = await sdk.integration_service.execute_http_async( + ... "", "/v2/tickets" + ... ) + """ + request, on_v4 = self._http_request( + connection_id, + url, + method, + headers=headers, + query_params=query_params, + body=body, + connector_version=connector_version, + connector_key=connector_key, + file=file, + folder_key=folder_key, + folder_path=folder_path, + max_retries=max_retries, + retry_methods=retry_methods, + timeout=timeout, + ) + result = await self._send_execute_async(request) + return ( + _exec.unwrap_v4_response(result) + if on_v4 + else _exec.unwrap_proxy_response(result) + ) + + def _activity_request( + self, + connection_id: str, + object_name: str, + method: str, + *, + body: Any, + query_params: Optional[Dict[str, str]], + files: Optional[Sequence[ExecuteFile]], + body_part_name: Optional[str], + url_input_fields: Optional[Sequence[str]], + file_response: bool, + max_records: Optional[int], + connector_version: Optional[str], + connector_key: Optional[str], + script_ref: Optional[str], + headers: Optional[Dict[str, str]], + folder_key: Optional[str], + folder_path: Optional[str], + max_retries: int, + retry_methods: Optional[Sequence[str]], + timeout: Optional[float], + ) -> tuple[_exec.ExecuteRequest, Optional[float], bool]: + """Validate the arguments of `execute_activity` and build its request.""" + caller = "execute_activity" + if not connection_id: + raise ValueError(f"connection_id is required for {caller}") + if not object_name: + raise ValueError(f"object_name is required for {caller}") + method = _exec.normalize_method(method, caller) + limit = _exec.resolve_max_records(max_records, caller) + if files: + _exec.validate_files(files, caller) + + if isinstance(body, dict): + body = _exec.expand_body_paths(body) + + if _exec.uses_v4_engine(connector_version): + if files: + raise ValueError( + f"files are not supported by {caller} on a version 4 connector" + ) + if not connector_key: + raise ValueError( + f"connector_key is required for {caller} on a version 4 connector" + ) + v4_request = _exec.ExecuteRequest( + # The activity always travels in a POST; `method` is the + # activity's own operation, and the retry settings describe it. + method="POST", + endpoint=_exec.ELEMENT_V4_EXECUTE, + body=_exec.build_v4_activity_manifest( + connection_id=connection_id, + connector_key=connector_key, + script_ref=script_ref or object_name, + body=body, + query_params=query_params, + headers=headers, + ), + has_body=True, + folder_key=folder_key, + folder_path=folder_path, + max_retries=max_retries, + retryable=_exec.is_retryable_method(method, retry_methods), + timeout=timeout, + ) + return v4_request, None, True + + writes = method in _exec.BODY_METHODS + request = _exec.ExecuteRequest( + method=method, + endpoint=_exec.activity_endpoint(connection_id, object_name), + params=_exec.encode_url_inputs(query_params, url_input_fields), + # Integration Service rejects a write that arrives with no body at all + body={} if body is None and writes else body, + has_body=writes and not files, + files=_exec.build_multipart(files, body, body_part_name) if files else None, + file_response=file_response, + folder_key=folder_key, + folder_path=folder_path, + max_retries=max_retries, + retryable=_exec.is_retryable_method(method, retry_methods), + timeout=timeout, + ) + return request, limit, False + + def _http_request( + self, + connection_id: str, + url: str, + method: str, + *, + headers: Optional[Dict[str, str]], + query_params: Optional[Dict[str, str]], + body: Any, + connector_version: Optional[str], + connector_key: Optional[str], + file: Optional[ExecuteFile], + folder_key: Optional[str], + folder_path: Optional[str], + max_retries: int, + retry_methods: Optional[Sequence[str]], + timeout: Optional[float], + ) -> tuple[_exec.ExecuteRequest, bool]: + """Validate the arguments of `execute_http` and build its request.""" + caller = "execute_http" + if not connection_id: + raise ValueError(f"connection_id is required for {caller}") + if not url: + raise ValueError(f"url is required for {caller}") + method = _exec.normalize_method(method, caller) + + on_v4 = _exec.uses_v4_engine(connector_version) + if file is not None: + if not on_v4: + raise ValueError( + "file needs a version 4 connector: pass connector_version" + ) + if body is not None: + raise ValueError(f"file and body cannot both be passed to {caller}") + _exec.validate_files([file], caller) + + # The vendor request always travels in a POST; the caller's retry + # settings describe the vendor request. + request = _exec.ExecuteRequest( + method="POST", + endpoint="", + has_body=True, + folder_key=folder_key, + folder_path=folder_path, + max_retries=max_retries, + retryable=_exec.is_retryable_method(method, retry_methods), + timeout=timeout, + ) + + if on_v4: + manifest = _exec.build_v4_manifest( + connection_id=connection_id, + connector_key=connector_key, + method=method, + url=url, + headers=headers, + query_params=query_params, + body=body, + file=file, + ) + request.endpoint = _exec.ELEMENT_V4_EXECUTE + request.body = manifest + if file is not None: + request.has_body = False + request.files = _exec.build_v4_upload(manifest, file) + else: + request.endpoint = _exec.http_request_endpoint(connection_id) + request.body = _exec.build_proxy_body( + method, url, headers, query_params, body + ) + return request, on_v4 + + def _execute_call( + self, request: _exec.ExecuteRequest + ) -> tuple[str, Dict[str, Any]]: + """The URL and httpx arguments of one execute call.""" + headers: Dict[str, str] = { + HEADER_ORIGINATOR: _ORIGINATOR_VALUE, + HEADER_SOURCE: _ORIGINATOR_VALUE, + **header_folder(request.folder_key, request.folder_path), + HEADER_USER_AGENT: user_agent_value("IntegrationService.execute"), + } + if job_key := UiPathConfig.job_key: + headers[HEADER_ACTIVITY_JOB_ID] = job_key + _inject_trace_context(headers) + + override = resolve_service_url(request.endpoint) + if override: + url = override + inject_routing_headers(headers) + else: + url = self._url.scope_url(request.endpoint, "tenant") + + kwargs: Dict[str, Any] = {"headers": headers} + if request.params: + kwargs["params"] = request.params + if request.files: + kwargs["files"] = request.files + elif request.has_body: + kwargs["json"] = request.body + if request.timeout is not None: + kwargs["timeout"] = request.timeout + return url, kwargs + + @staticmethod + def _execute_retry_delay( + request: _exec.ExecuteRequest, attempt: int, response: Optional[Response] + ) -> Optional[float]: + """Seconds to wait before sending a failed call again, or None to stop.""" + if not request.retryable or attempt > request.max_retries: + return None + if response is not None: + if response.status_code not in _EXECUTE_RETRYABLE_STATUS_CODES: + return None + retry_after = parse_retry_after(response.headers.get("retry-after", "")) + if retry_after is not None: + return min(retry_after, _EXECUTE_MAX_BACKOFF) + return min( + exponential_backoff_with_jitter(attempt, _EXECUTE_INITIAL_BACKOFF), + _EXECUTE_MAX_BACKOFF, + ) + + def _send_execute(self, request: _exec.ExecuteRequest) -> ExecuteResult: + """Send one execute call; a non-2xx response is returned, not raised.""" + url, kwargs = self._execute_call(request) + attempt = 0 + while True: + attempt += 1 + try: + response = self._client.request(request.method, url, **kwargs) + except TransportError: + delay = self._execute_retry_delay(request, attempt, None) + if delay is None: + raise + else: + delay = self._execute_retry_delay(request, attempt, response) + if delay is None: + return _exec.to_result(response, request.file_response) + time.sleep(delay) + + async def _send_execute_async(self, request: _exec.ExecuteRequest) -> ExecuteResult: + """Asynchronously send one execute call; a non-2xx response is returned.""" + url, kwargs = self._execute_call(request) + attempt = 0 + while True: + attempt += 1 + try: + response = await self._client_async.request( + request.method, url, **kwargs + ) + except TransportError: + delay = self._execute_retry_delay(request, attempt, None) + if delay is None: + raise + else: + delay = self._execute_retry_delay(request, attempt, response) + if delay is None: + return _exec.to_result(response, request.file_response) + await asyncio.sleep(delay) diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/execution/__init__.py b/packages/uipath-platform/src/uipath/platform/integration_service/execution/__init__.py new file mode 100644 index 000000000..01c668d6b --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/integration_service/execution/__init__.py @@ -0,0 +1,67 @@ +"""Request building and response reading for Integration Service execution. + +Pure helpers behind `IntegrationService.execute_activity` and +`IntegrationService.execute_http`. Nothing here performs I/O. +""" + +from ._body_paths import expand_body_paths +from ._multipart import build_multipart, validate_files +from ._pagination import ( + extract_page, + gathered_result, + needs_paging, + next_page_request, + resolve_max_records, + to_activity_result, +) +from ._proxy_response import build_proxy_body, unwrap_proxy_response +from ._request import ( + BODY_METHODS, + ELEMENT_V4_EXECUTE, + ExecuteRequest, + activity_endpoint, + http_request_endpoint, + is_retryable_method, + normalize_method, +) +from ._response_content import is_file_response, to_result +from ._url_input import encode_url_inputs, looks_like_url +from ._v4_execute import ( + build_v4_activity_manifest, + build_v4_manifest, + build_v4_upload, + to_v4_activity_result, + unwrap_v4_response, + uses_v4_engine, +) + +__all__ = [ + "BODY_METHODS", + "ELEMENT_V4_EXECUTE", + "ExecuteRequest", + "activity_endpoint", + "build_multipart", + "build_proxy_body", + "build_v4_activity_manifest", + "build_v4_manifest", + "build_v4_upload", + "encode_url_inputs", + "expand_body_paths", + "extract_page", + "gathered_result", + "http_request_endpoint", + "is_file_response", + "is_retryable_method", + "looks_like_url", + "needs_paging", + "next_page_request", + "normalize_method", + "resolve_max_records", + "to_activity_result", + "to_result", + "to_v4_activity_result", + "unwrap_proxy_response", + "unwrap_v4_response", + "uses_v4_engine", + "validate_files", +] diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/execution/_body_paths.py b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_body_paths.py new file mode 100644 index 000000000..669f7195e --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_body_paths.py @@ -0,0 +1,116 @@ +"""Body keys given as paths, expanded into the nested body a connector expects.""" + +import re +from typing import Any, Dict, List + +_INDEXED_SEGMENT_RE = re.compile(r"^(.*?)\[(\d+)]$") +_WILDCARD_SUFFIX = "[*]" + + +def _is_path_key(key: str) -> bool: + return "." in key or "[" in key + + +def expand_body_paths(body: Dict[str, Any]) -> Dict[str, Any]: + """Build the nested body a connector expects from a body whose keys are paths. + + `{"fields.summary": "x"}` becomes `{"fields": {"summary": "x"}}`. A segment + can address an array item (`items[2].name`) or every item of an array + (`items[*].name`). Keys without a path are copied as they are, and nested + values are never rewritten. A body with no path key is returned untouched. + """ + if not any(isinstance(key, str) and _is_path_key(key) for key in body): + return body + + output: Dict[str, Any] = {} + for key, value in body.items(): + if isinstance(key, str) and _is_path_key(key): + _assign_path(output, key, value) + else: + output[key] = value + return output + + +def _assign_path(target: Dict[str, Any], path: str, value: Any) -> None: + segments = path.split(".") + current = target + + for index, segment in enumerate(segments): + is_last = index == len(segments) - 1 + + indexed = _INDEXED_SEGMENT_RE.match(segment) + if indexed: + items = _list_in(current, indexed.group(1)) + position = int(indexed.group(2)) + while len(items) <= position: + items.append({}) + if is_last: + items[position] = value + return + current = _dict_at(items, position) + continue + + if segment.endswith(_WILDCARD_SUFFIX): + key = segment[: -len(_WILDCARD_SUFFIX)] + _assign_to_every_item(current, key, ".".join(segments[index + 1 :]), value) + return + + if is_last: + current[segment] = value + return + current = _dict_in(current, segment) + + +def _list_in(parent: Dict[str, Any], key: str) -> List[Any]: + existing = parent.get(key) + if isinstance(existing, list): + return existing + created: List[Any] = [] + parent[key] = created + return created + + +def _dict_in(parent: Dict[str, Any], key: str) -> Dict[str, Any]: + existing = parent.get(key) + if isinstance(existing, dict): + return existing + created: Dict[str, Any] = {} + parent[key] = created + return created + + +def _dict_at(items: List[Any], position: int) -> Dict[str, Any]: + existing = items[position] + if isinstance(existing, dict): + return existing + created: Dict[str, Any] = {} + items[position] = created + return created + + +def _assign_to_every_item( + parent: Dict[str, Any], key: str, remaining_path: str, value: Any +) -> None: + # A list value replaces the whole list + if isinstance(value, list): + parent[key] = value + return + + items = _list_in(parent, key) + if not items: + items.append({}) + + for position in range(len(items)): + item = _dict_at(items, position) + if remaining_path: + _assign_path(item, remaining_path, value) + elif isinstance(value, dict): + _merge_into(item, value) + + +def _merge_into(current: Dict[str, Any], incoming: Dict[str, Any]) -> None: + for key, value in incoming.items(): + if isinstance(value, dict): + _merge_into(_dict_in(current, key), value) + else: + current[key] = value diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/execution/_multipart.py b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_multipart.py new file mode 100644 index 000000000..21a30f6f3 --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_multipart.py @@ -0,0 +1,45 @@ +"""Multipart form of a connector call that uploads files.""" + +import json +from typing import Any, List, Optional, Sequence + +from ..execution_types import ( + ExecuteFile, +) +from ._request import OCTET_STREAM, MultipartPart + +_DEFAULT_BODY_PART_NAME = "body" +_DEFAULT_FILE_NAME = "file" + + +def validate_files(files: Sequence[ExecuteFile], caller: str) -> None: + """Check the files of a call before anything is sent.""" + for file in files: + if not isinstance(file, ExecuteFile): + raise ValueError(f"every file passed to {caller} must be an ExecuteFile") + if not file.name: + raise ValueError(f"every file passed to {caller} needs a name") + + +def _file_part(file: ExecuteFile, file_name: str) -> MultipartPart: + return (file.name, (file_name, file.content, file.content_type or OCTET_STREAM)) + + +def build_multipart( + files: Sequence[ExecuteFile], body: Any, body_part_name: Optional[str] = None +) -> List[MultipartPart]: + """Build the multipart form of a connector call that uploads files. + + Each file is one part, and a non-empty body travels as a JSON part of its + own, ahead of the files. + """ + parts: List[MultipartPart] = [] + + is_empty = body is None or (isinstance(body, (dict, list)) and len(body) == 0) + if not is_empty: + text = body if isinstance(body, str) else json.dumps(body) + parts.append((body_part_name or _DEFAULT_BODY_PART_NAME, (None, text, None))) + + for file in files: + parts.append(_file_part(file, file.file_name or _DEFAULT_FILE_NAME)) + return parts diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/execution/_pagination.py b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_pagination.py new file mode 100644 index 000000000..65807da7f --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_pagination.py @@ -0,0 +1,126 @@ +"""Paging state of a list response and following the connector's pages.""" + +import base64 +import binascii +import json +import math +from dataclasses import replace +from typing import Any, Dict, List, Mapping, Optional + +from ..execution_types import ( + ExecuteActivityResult, + ExecutePage, + ExecuteResult, +) +from ._request import ExecuteRequest +from ._response_content import header_value + +HAS_MORE_HEADER = "elements-has-more" +NEXT_PAGE_TOKEN_HEADER = "elements-next-page-token" +NEXT_PAGE_PARAM = "nextPage" + +_ALL_RECORDS = -1 +# Marker a connector puts in its page token once the list is exhausted. +_PROVIDER_DONE = "DONE" + + +def resolve_max_records(max_records: Optional[int], caller: str) -> Optional[float]: + """Turn the caller's `max_records` into the record limit to page up to. + + Returns None when paging is off and `math.inf` for every record. + """ + if max_records is None: + return None + if isinstance(max_records, bool) or not isinstance(max_records, int): + raise ValueError(f"max_records must be a positive integer or -1 for {caller}") + if max_records == _ALL_RECORDS: + return math.inf + if max_records <= 0: + raise ValueError(f"max_records must be a positive integer or -1 for {caller}") + return max_records + + +def _is_token_exhausted(token: str) -> bool: + """A page token is base64url JSON; the connector marks the end of the list in it.""" + try: + padded = token + "=" * (-len(token) % 4) + decoded = json.loads(base64.urlsafe_b64decode(padded).decode("utf-8")) + except (ValueError, binascii.Error): + # An unreadable token is still a usable token. + return False + if not isinstance(decoded, dict): + return False + provider_next_page = decoded.get("providerNextPage") + return ( + isinstance(provider_next_page, str) + and provider_next_page.upper() == _PROVIDER_DONE + ) + + +def extract_page(headers: Mapping[str, str], body: Any) -> Optional[ExecutePage]: + """Read the paging state of a list response. + + Returns None when the response is not a paged list or the connector + reported its last page. + """ + has_more = header_value(headers, HAS_MORE_HEADER) + next_page_token = header_value(headers, NEXT_PAGE_TOKEN_HEADER) + if not has_more or not next_page_token or not isinstance(body, list): + return None + if _is_token_exhausted(next_page_token): + return None + return ExecutePage( + has_more=has_more.lower() == "true", next_page_token=next_page_token + ) + + +def strip_pagination_headers(headers: Mapping[str, str]) -> Dict[str, str]: + """Drop the paging headers, for a result whose pages were already gathered.""" + dropped = (HAS_MORE_HEADER, NEXT_PAGE_TOKEN_HEADER) + return {key: value for key, value in headers.items() if key.lower() not in dropped} + + +def to_activity_result(result: ExecuteResult) -> ExecuteActivityResult: + """Add the paging state to a single-page result when the connector reported one.""" + return ExecuteActivityResult( + **result.model_dump(), page=extract_page(result.headers, result.body) + ) + + +def next_page_request(request: ExecuteRequest, page: ExecutePage) -> ExecuteRequest: + """The request for the page a token points to.""" + params = dict(request.params or {}) + params[NEXT_PAGE_PARAM] = page.next_page_token + return replace(request, params=params) + + +def needs_paging( + method: str, max_records: Optional[float], first: ExecuteResult +) -> bool: + """True when `max_records` asks the call to follow the connector's pages.""" + return ( + max_records is not None + and method == "GET" + and first.ok + and isinstance(first.body, list) + ) + + +def gathered_result( + first: ExecuteResult, + last: ExecuteResult, + records: List[Any], + max_records: float, + followed: bool, +) -> ExecuteActivityResult: + """The result of a call that followed pages: every record gathered, as one list.""" + if not followed and len(records) <= max_records: + return to_activity_result(first) + limit = len(records) if max_records == math.inf else int(max_records) + return ExecuteActivityResult( + ok=last.ok, + status=last.status, + status_text=last.status_text, + body=records[:limit], + headers=strip_pagination_headers(last.headers), + ) diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/execution/_proxy_response.py b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_proxy_response.py new file mode 100644 index 000000000..21ca1dc46 --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_proxy_response.py @@ -0,0 +1,78 @@ +"""The version 3 HTTP passthrough: its request body and its answer.""" + +import json +from typing import Any, Dict, Optional + +from ..execution_types import ( + ExecuteHttpResult, + ExecuteResult, +) + + +def build_proxy_body( + method: str, + url: str, + headers: Optional[Dict[str, str]], + query_params: Optional[Dict[str, str]], + body: Any, +) -> Dict[str, Any]: + """The request the version 3 passthrough accepts for one vendor call.""" + payload: Dict[str, Any] = {"method": method, "url": url} + if headers is not None: + payload["headers"] = headers + if query_params is not None: + payload["query"] = query_params + if body is not None: + # Integration Service takes the vendor body as a string + payload["body"] = body if isinstance(body, str) else json.dumps(body) + return payload + + +def unwrap_proxy_response(result: ExecuteResult) -> ExecuteHttpResult: + """Turn the answer to a version 3 passthrough call into the vendor's response. + + Integration Service answers 200 whatever the vendor said and reports the + vendor's status, headers and body inside the response body. When the call + never reached the vendor (the answer is not 2xx, or carries no vendor + status), the Integration Service response is returned as is. + """ + envelope = result.body + if ( + not result.ok + or not isinstance(envelope, dict) + or not _is_int(envelope.get("code")) + ): + return ExecuteHttpResult(**result.model_dump(), is_vendor_error=False) + + code = envelope["code"] + ok = 200 <= code < 300 + status_text = envelope.get("statusText") + body = envelope.get("body") + return ExecuteHttpResult( + ok=ok, + status=code, + status_text=status_text if isinstance(status_text, str) else "", + # The parsed body wins; `rawStringBody` carries a vendor body that is not JSON. + body=body if body is not None else envelope.get("rawStringBody"), + headers=_flatten_headers(envelope.get("headers")), + is_vendor_error=not ok, + ) + + +def _is_int(value: Any) -> bool: + return isinstance(value, int) and not isinstance(value, bool) + + +def _flatten_headers(value: Any) -> Dict[str, str]: + """One string per header name; a repeated header arrives as a list.""" + if not isinstance(value, dict): + return {} + headers: Dict[str, str] = {} + for name, entry in value.items(): + if entry is None: + continue + if isinstance(entry, list): + headers[name] = ", ".join(str(item) for item in entry) + else: + headers[name] = str(entry) + return headers diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/execution/_request.py b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_request.py new file mode 100644 index 000000000..7596854ab --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_request.py @@ -0,0 +1,73 @@ +"""The request of an execute call: constants, endpoints and method checks.""" + +from dataclasses import dataclass +from typing import Any, Dict, List, Optional, Sequence, Tuple +from urllib.parse import quote + +ELEMENT_INSTANCES_BASE = "/elements_/v3/element/instances" +ELEMENT_V4_EXECUTE = "/elements_/v4/execute" + +EXECUTE_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE"}) +BODY_METHODS = frozenset({"POST", "PUT", "PATCH"}) +# RFC 9110 idempotent methods: a replayed POST can create the same record twice. +DEFAULT_RETRY_METHODS = frozenset({"GET", "HEAD", "PUT", "DELETE", "OPTIONS"}) + +JSON_CONTENT_TYPE = "application/json" +OCTET_STREAM = "application/octet-stream" +CONTENT_TYPE = "content-type" +CONTENT_DISPOSITION = "content-disposition" + +MultipartPart = Tuple[str, Tuple[Optional[str], Any, Optional[str]]] + + +@dataclass +class ExecuteRequest: + """One request against a connection instance.""" + + method: str + endpoint: str + params: Optional[Dict[str, str]] = None + body: Any = None + has_body: bool = False + files: Optional[List[MultipartPart]] = None + file_response: bool = False + folder_key: Optional[str] = None + folder_path: Optional[str] = None + max_retries: int = 0 + retryable: bool = False + timeout: Optional[float] = None + + +def normalize_method(method: str, caller: str) -> str: + """Upper-case and validate the HTTP method of an execute call.""" + normalized = (method or "").upper() + if normalized not in EXECUTE_METHODS: + raise ValueError( + f"method must be one of {sorted(EXECUTE_METHODS)} for {caller}" + ) + return normalized + + +def is_retryable_method(method: str, retry_methods: Optional[Sequence[str]]) -> bool: + """True when a failed call with this method may be sent again.""" + allowed = ( + DEFAULT_RETRY_METHODS + if retry_methods is None + else {name.upper() for name in retry_methods} + ) + return method in allowed + + +def activity_endpoint(connection_id: str, object_name: str) -> str: + """Path of a connector object operation. + + `object_name` may be a multi-segment path such as `curated_get_issue/ABC-1`: + each segment is encoded on its own and the `/` separators are kept. + """ + path = "/".join(quote(segment, safe="") for segment in object_name.split("/")) + return f"{ELEMENT_INSTANCES_BASE}/{quote(connection_id, safe='')}/{path}" + + +def http_request_endpoint(connection_id: str) -> str: + """Path of the version 3 raw HTTP passthrough of a connection.""" + return f"{ELEMENT_INSTANCES_BASE}/{quote(connection_id, safe='')}/http-request" diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/execution/_response_content.py b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_response_content.py new file mode 100644 index 000000000..3ff7bd8d2 --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_response_content.py @@ -0,0 +1,105 @@ +"""Reading a response body: bytes for a file, parsed JSON, or text.""" + +import json +import logging +from typing import Any, Mapping, Optional + +from httpx import Response + +from ..execution_types import ( + ExecuteResult, +) +from ._request import CONTENT_DISPOSITION, CONTENT_TYPE + +logger: logging.Logger = logging.getLogger("uipath") + + +# Content types that carry data to read, even when marked as an attachment. +_DATA_CONTENT_TYPES = ( + "application/json", + "application/xml", + "text/xml", + "text/csv", + "text/plain", + "application/atom+xml", + "application/rss+xml", +) + +_BINARY_CONTENT_TYPE_PREFIXES = ( + "application/octet-stream", + "application/pdf", + "application/zip", + "image/", + "audio/", + "video/", + "application/vnd.", + "application/x-tar", + "application/gzip", + # A multipart answer is framed bytes; whoever asked for it parses it + "multipart/", +) + + +def header_value(headers: Mapping[str, str], name: str) -> Optional[str]: + """Read a header from a flat mapping whatever the case of its name.""" + direct = headers.get(name) + if direct is not None: + return direct + for key, value in headers.items(): + if key.lower() == name: + return value + return None + + +def _is_data_content_type(content_type: str) -> bool: + essence = content_type.split(";")[0].strip() + if essence.startswith(_DATA_CONTENT_TYPES): + return True + # Structured suffixes such as application/vnd.api+json are data, image/svg+xml is not + is_text_tree = essence.startswith(("application/", "text/")) + return is_text_tree and essence.endswith(("+json", "+xml")) + + +def is_file_response(headers: Mapping[str, str]) -> bool: + """True when the response headers describe a file instead of data to parse. + + That is: the content type is not a data type, and the response is an + attachment or has a binary content type. + """ + content_type = (header_value(headers, CONTENT_TYPE) or "").lower() + if _is_data_content_type(content_type): + return False + + disposition = (header_value(headers, CONTENT_DISPOSITION) or "").lower() + return "attachment" in disposition or content_type.startswith( + _BINARY_CONTENT_TYPE_PREFIXES + ) + + +def to_result(response: Response, as_file: bool = False) -> ExecuteResult: + """Read a response into its envelope, whatever its status. + + The body is `bytes` for a file, parsed JSON when the text is JSON, and the + text otherwise. `as_file` reads a 2xx response as bytes whatever its + content type. + """ + headers = dict(response.headers) + + body: Any + if (as_file and response.is_success) or is_file_response(headers): + body = response.content + else: + body = response.text + if body: + try: + body = json.loads(body) + except ValueError: + logger.debug("execute: response body is not JSON, returning text") + + return ExecuteResult( + ok=response.is_success, + status=response.status_code, + status_text=response.reason_phrase, + body=body, + headers=headers, + ) diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/execution/_url_input.py b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_url_input.py new file mode 100644 index 000000000..b2989d17a --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_url_input.py @@ -0,0 +1,51 @@ +"""Query parameters that take a URL, sent Base64-encoded.""" + +import base64 +import re +from typing import Dict, Optional, Sequence +from urllib.parse import unquote, urlsplit + +# Paging parameters. Their values are tokens the connector reads as they are. +_RESERVED_QUERY_KEYS = frozenset({"pagesize", "nextpage", "page", "providernextpage"}) +_ARRAY_MARKER_RE = re.compile(r"\[\*]$") + + +def looks_like_url(value: str) -> bool: + """True when `value` is an http or https URL, plain or percent-encoded once.""" + try: + parts = urlsplit(unquote(value)) + except ValueError: + return False + return parts.scheme.lower() in ("http", "https") and bool(parts.netloc) + + +def encode_url_inputs( + query: Optional[Dict[str, str]], fields: Optional[Sequence[str]] +) -> Optional[Dict[str, str]]: + """Base64-encode the query values that carry a URL. + + Integration Service rejects a request whose query holds an encoded slash, + so for the fields a connector marks as accepting a URL the value travels + as Base64 and the connector decodes it. A value is encoded only when its + name is listed and it is an http or https URL. Names match without regard + to case, and paging parameters are never encoded. + """ + if not query or not fields: + return query + + flagged = {_ARRAY_MARKER_RE.sub("", name).lower() for name in fields} + + encoded: Optional[Dict[str, str]] = None + for key, value in query.items(): + name = key.lower() + if ( + name in _RESERVED_QUERY_KEYS + or name not in flagged + or not isinstance(value, str) + or not looks_like_url(value) + ): + continue + if encoded is None: + encoded = dict(query) + encoded[key] = base64.b64encode(value.encode("utf-8")).decode("ascii") + return query if encoded is None else encoded diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/execution/_v4_execute.py b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_v4_execute.py new file mode 100644 index 000000000..39086c46e --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_v4_execute.py @@ -0,0 +1,245 @@ +"""The version 4 engine: its request manifest and its answer.""" + +import base64 +import json +import re +from typing import Any, Dict, List, Optional, Tuple +from urllib.parse import urlencode + +from ..execution_types import ( + ExecuteActivityResult, + ExecuteFile, + ExecuteHttpResult, + ExecuteResult, +) +from ._multipart import _file_part +from ._proxy_response import _flatten_headers, _is_int +from ._request import CONTENT_TYPE, JSON_CONTENT_TYPE, OCTET_STREAM, MultipartPart +from ._response_content import header_value + +_V4_MAJOR_VERSION = 4 +_MAJOR_VERSION_RE = re.compile(r"^v?(\d+)(?:\.|$)", re.IGNORECASE) +_MANIFEST_PART_NAME = "manifest" +_MULTIPART_MIXED = "multipart/mixed" +_BOUNDARY_RE = re.compile(r'boundary="?([^";]+)"?', re.IGNORECASE) +_CRLF = b"\r\n" +_HEADER_END = b"\r\n\r\n" + + +def uses_v4_engine(connector_version: Optional[str]) -> bool: + """True when a connector of this version runs on the version 4 engine. + + That is major version 4 or later. A missing or unreadable version means + the version 3 engine. + """ + if not connector_version: + return False + match = _MAJOR_VERSION_RE.match(connector_version.strip()) + return match is not None and int(match.group(1)) >= _V4_MAJOR_VERSION + + +def _with_query(url: str, query_params: Optional[Dict[str, str]]) -> str: + if not query_params: + return url + separator = "&" if "?" in url else "?" + return f"{url}{separator}{urlencode(query_params)}" + + +def build_v4_manifest( + *, + connection_id: str, + connector_key: Optional[str], + method: str, + url: str, + headers: Optional[Dict[str, str]], + query_params: Optional[Dict[str, str]], + body: Any, + file: Optional[ExecuteFile], +) -> Dict[str, Any]: + """Build the version 4 request for one vendor call. + + The engine sends the body as given and has no query field, so query + parameters join the URL and a serialized body is labelled as JSON. + """ + request_headers = dict(headers or {}) + + text: Optional[str] = None + if body is not None: + if isinstance(body, str): + text = body + else: + text = json.dumps(body) + if header_value(request_headers, CONTENT_TYPE) is None: + request_headers["Content-Type"] = JSON_CONTENT_TYPE + + outbound: Dict[str, Any] = {"method": method, "url": _with_query(url, query_params)} + if request_headers: + outbound["headers"] = [ + {"name": name, "value": value} for name, value in request_headers.items() + ] + + manifest: Dict[str, Any] = {"outboundRequestConfig": outbound} + if file is not None: + outbound["bodyRef"] = file.name + manifest["attachments"] = [ + { + "name": file.name, + "size": len(file.content), + "contentType": file.content_type or OCTET_STREAM, + } + ] + elif text is not None: + outbound["body"] = text + + context: Dict[str, Any] = {"connectionId": connection_id} + if connector_key: + context["connectorKey"] = connector_key + manifest["context"] = context + return manifest + + +def build_v4_activity_manifest( + *, + connection_id: str, + connector_key: str, + script_ref: str, + body: Any, + query_params: Optional[Dict[str, str]], + headers: Optional[Dict[str, str]], +) -> Dict[str, Any]: + """Build the version 4 request that runs one connector activity. + + The engine finds the activity's script by its reference and hands it the + body, query and headers as the inbound call. + """ + request: Dict[str, Any] = {} + if body is not None: + request["body"] = body + if query_params: + request["query"] = query_params + if headers: + request["headers"] = headers + return { + "context": { + "connectionId": connection_id, + "connectorKey": connector_key, + "script": {"reference": script_ref}, + }, + "request": request, + } + + +def to_v4_activity_result(result: ExecuteResult) -> ExecuteActivityResult: + """Turn the version 4 engine's answer to an activity call into its result.""" + vendor = unwrap_v4_response(result) + return ExecuteActivityResult( + ok=vendor.ok, + status=vendor.status, + status_text=vendor.status_text, + body=vendor.body, + headers=vendor.headers, + ) + + +def build_v4_upload(manifest: Dict[str, Any], file: ExecuteFile) -> List[MultipartPart]: + """The form of a version 4 call that uploads a file: the manifest, then the file.""" + return [ + (_MANIFEST_PART_NAME, ("blob", json.dumps(manifest), JSON_CONTENT_TYPE)), + _file_part(file, file.file_name or file.name), + ] + + +def unwrap_v4_response(result: ExecuteResult) -> ExecuteHttpResult: + """Turn the version 4 engine's answer into the vendor's response. + + The engine answers 2xx whenever it reached the vendor and reports the + vendor's status, headers and body inside the answer; any other status + means the engine itself failed. The answer is a JSON object, or a two-part + document (the same object without the body, then the bytes) when the + vendor sent a file or a large body. + """ + as_is = ExecuteHttpResult(**result.model_dump(), is_vendor_error=False) + if not result.ok: + return as_is + + if isinstance(result.body, (bytes, bytearray)): + content_type = header_value(result.headers, CONTENT_TYPE) or "" + if not content_type.lower().startswith(_MULTIPART_MIXED): + return as_is + envelope, content = _parse_two_part_answer(bytes(result.body), content_type) + return _to_vendor_result(envelope, content) + + if not isinstance(result.body, dict) or not _is_int(result.body.get("status")): + return as_is + + body = result.body.get("body") + if result.body.get("bodyEncoding") == "base64" and isinstance(body, str): + body = base64.b64decode(body) + return _to_vendor_result(result.body, body) + + +def _to_vendor_result(envelope: Dict[str, Any], body: Any) -> ExecuteHttpResult: + reported = envelope.get("status") + status: int = reported if isinstance(reported, int) and _is_int(reported) else 0 + ok = 200 <= status < 300 + return ExecuteHttpResult( + ok=ok, + status=status, + status_text="", + body=body, + headers=_flatten_headers(envelope.get("headers")), + is_vendor_error=not ok, + ) + + +def _parse_two_part_answer( + document: bytes, content_type: str +) -> Tuple[Dict[str, Any], bytes]: + """Read the two-part answer: the JSON description, then the vendor's bytes. + + An answer without its closing delimiter was cut short and is refused. + """ + + def fail(reason: str) -> ValueError: + return ValueError( + f"Integration Service returned an incomplete file response: {reason}" + ) + + boundary_match = _BOUNDARY_RE.search(content_type) + if not boundary_match: + raise fail("no boundary") + + delimiter = f"--{boundary_match.group(1)}".encode("utf-8") + closing = _CRLF + delimiter + b"--" + + first = document.find(delimiter) + first_body_start = _end_of_headers(document, first) + second = ( + document.find(_CRLF + delimiter, first_body_start) + if first_body_start >= 0 + else -1 + ) + if first < 0 or first_body_start < 0 or second < 0: + raise fail("first part not found") + + second_body_start = _end_of_headers(document, second + len(_CRLF)) + end = document.rfind(closing) + if second_body_start < 0 or end < second_body_start: + raise fail("closing delimiter not found") + + try: + envelope = json.loads(document[first_body_start:second].decode("utf-8")) + except ValueError as error: + raise fail("first part is not JSON") from error + if not isinstance(envelope, dict): + raise fail("first part is not an object") + + return envelope, document[second_body_start:end] + + +def _end_of_headers(document: bytes, start: int) -> int: + """Position just after the blank line that ends a part's headers, or -1.""" + if start < 0: + return -1 + position = document.find(_HEADER_END, start) + return -1 if position < 0 else position + len(_HEADER_END) diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/execution_types.py b/packages/uipath-platform/src/uipath/platform/integration_service/execution_types.py new file mode 100644 index 000000000..ab18ba035 --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/integration_service/execution_types.py @@ -0,0 +1,79 @@ +"""Models for running connector activities and vendor HTTP requests. + +Used by `IntegrationService.execute_activity` and `IntegrationService.execute_http`. +""" + +from typing import Any, Dict, Literal, Optional + +from pydantic import BaseModel + +ExecuteMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE"] +"""HTTP method of an execute call.""" + + +class ExecuteFile(BaseModel): + """A file sent with an `execute_activity` or `execute_http` call.""" + + name: str + """Name of the form part the connector reads the file from, e.g. `file`.""" + content: bytes + """The file's bytes.""" + file_name: Optional[str] = None + """File name reported to the connector.""" + content_type: Optional[str] = None + """Content type of the file. Defaults to `application/octet-stream`.""" + + +class ExecutePage(BaseModel): + """Where a paged list stands after an `execute_activity` call.""" + + has_more: bool + """True when the connector has more records after this page.""" + next_page_token: str + """Token for the next page. Pass it as the `nextPage` query parameter.""" + + +class ExecuteResult(BaseModel): + """The HTTP envelope of an execute call. + + Unlike most SDK methods, an execute call does not raise on a non-2xx + response: Integration Service proxies third-party calls, and the body + carries the vendor's error details. Check `ok` and `status`. + """ + + ok: bool + """True for an HTTP 2xx response.""" + status: int + """HTTP status code.""" + status_text: str = "" + """HTTP reason phrase.""" + body: Any = None + """Parsed JSON when the response is JSON, the raw text otherwise, `bytes` for a file.""" + headers: Dict[str, str] = {} + """Response headers.""" + + +class ExecuteActivityResult(ExecuteResult): + """Result of `IntegrationService.execute_activity`.""" + + page: Optional[ExecutePage] = None + """Paging state of a list response. + + None when the response is not a paged list, when the connector reported + its last page, or when `max_records` already gathered the pages. + """ + + +class ExecuteHttpResult(ExecuteResult): + """Result of `IntegrationService.execute_http`. + + `ok`, `status`, `status_text`, `headers` and `body` describe the vendor's + response, not the Integration Service call that carried it. + """ + + is_vendor_error: bool = False + """True when the vendor answered with a non-2xx status. + + False when the call failed before reaching the vendor, in which case the + fields describe the Integration Service response. + """ diff --git a/packages/uipath-platform/tests/services/test_integration_service.py b/packages/uipath-platform/tests/services/test_integration_service.py new file mode 100644 index 000000000..6914a6d2d --- /dev/null +++ b/packages/uipath-platform/tests/services/test_integration_service.py @@ -0,0 +1,1247 @@ +import base64 +import json +from typing import Any, Dict + +import httpx +import pytest +from pytest_httpx import HTTPXMock + +from uipath.platform import UiPathApiConfig, UiPathExecutionContext +from uipath.platform.common._bindings import ( + ConnectionResourceOverwrite, + _resource_overwrites, +) +from uipath.platform.constants import HEADER_FOLDER_KEY, HEADER_USER_AGENT +from uipath.platform.integration_service import ( + ExecuteActivityResult, + ExecuteFile, + ExecuteHttpResult, + ExecuteResult, + IntegrationService, +) +from uipath.platform.integration_service import execution as ex + +CONNECTION_ID = "conn-123" + + +@pytest.fixture +def service( + config: UiPathApiConfig, execution_context: UiPathExecutionContext +) -> IntegrationService: + return IntegrationService(config=config, execution_context=execution_context) + + +@pytest.fixture +def instance_url(base_url: str, org: str, tenant: str) -> str: + return f"{base_url}{org}{tenant}/elements_/v3/element/instances/{CONNECTION_ID}" + + +@pytest.fixture +def v4_url(base_url: str, org: str, tenant: str) -> str: + return f"{base_url}{org}{tenant}/elements_/v4/execute" + + +def page_token(provider_next_page: str = "2") -> str: + raw = json.dumps({"providerNextPage": provider_next_page}).encode() + return base64.urlsafe_b64encode(raw).decode().rstrip("=") + + +def paging_headers(has_more: bool = True, token: str | None = None) -> Dict[str, str]: + return { + "elements-has-more": "true" if has_more else "false", + "elements-next-page-token": token or page_token(), + } + + +def sent(httpx_mock: HTTPXMock, index: int = -1) -> httpx.Request: + return httpx_mock.get_requests()[index] + + +class TestBodyPaths: + def test_body_without_paths_is_untouched(self) -> None: + body = {"subject": "x", "nested": {"a.b": 1}} + assert ex.expand_body_paths(body) is body + + def test_dotted_key_becomes_nested(self) -> None: + assert ex.expand_body_paths( + {"fields.summary": "x", "fields.project.key": "P", "plain": 1} + ) == {"fields": {"summary": "x", "project": {"key": "P"}}, "plain": 1} + + def test_indexed_segment(self) -> None: + assert ex.expand_body_paths({"items[1].name": "b", "tags[0]": "t"}) == { + "items": [{}, {"name": "b"}], + "tags": ["t"], + } + + def test_wildcard_applies_to_every_item(self) -> None: + assert ex.expand_body_paths( + {"items[0].id": 1, "items[1].id": 2, "items[*].kind": "k"} + ) == {"items": [{"id": 1, "kind": "k"}, {"id": 2, "kind": "k"}]} + + def test_wildcard_with_list_value_replaces_list(self) -> None: + assert ex.expand_body_paths({"items[*]": [1, 2]}) == {"items": [1, 2]} + + def test_wildcard_with_dict_value_merges(self) -> None: + assert ex.expand_body_paths({"items[0].a": 1, "items[*]": {"b": {"c": 2}}}) == { + "items": [{"a": 1, "b": {"c": 2}}] + } + + +class TestUrlInputs: + def test_encodes_only_listed_url_values(self) -> None: + query = {"link": "https://a.com/x?y=1", "other": "https://b.com", "q": "text"} + encoded = ex.encode_url_inputs(query, ["Link[*]", "q"]) + assert encoded == { + "link": base64.b64encode(b"https://a.com/x?y=1").decode(), + "other": "https://b.com", + "q": "text", + } + assert query["link"] == "https://a.com/x?y=1" + + def test_percent_encoded_url_is_recognised(self) -> None: + assert ex.looks_like_url("https%3A%2F%2Fa.com%2Fx") + assert not ex.looks_like_url("ftp://a.com") + assert not ex.looks_like_url("just text") + + def test_paging_parameters_are_never_encoded(self) -> None: + query = {"nextPage": "https://a.com"} + assert ex.encode_url_inputs(query, ["nextPage"]) is query + + def test_no_fields_returns_same_query(self) -> None: + query = {"a": "https://a.com"} + assert ex.encode_url_inputs(query, None) is query + + +class TestResponseContent: + @pytest.mark.parametrize( + "headers,expected", + [ + ({"content-type": "application/pdf"}, True), + ({"content-type": "image/png"}, True), + ({"Content-Type": "application/octet-stream"}, True), + ({"content-type": "application/json"}, False), + ( + { + "content-type": "text/csv", + "content-disposition": "attachment; filename=a.csv", + }, + False, + ), + ({"content-type": "application/vnd.api+json"}, False), + ({"content-type": "application/vnd.ms-excel"}, True), + ({"content-type": "image/svg+xml"}, True), + ( + { + "content-type": "text/html", + "content-disposition": "attachment; filename=a.html", + }, + True, + ), + ({}, False), + ], + ) + def test_is_file_response(self, headers: Dict[str, str], expected: bool) -> None: + assert ex.is_file_response(headers) is expected + + def test_to_result_parses_json_and_keeps_text(self) -> None: + assert ex.to_result(httpx.Response(200, json={"a": 1})).body == {"a": 1} + assert ex.to_result(httpx.Response(200, text="plain")).body == "plain" + assert ex.to_result(httpx.Response(204)).body == "" + + def test_as_file_applies_to_success_only(self) -> None: + assert ex.to_result(httpx.Response(200, json={"a": 1}), True).body == b'{"a":1}' + assert ex.to_result(httpx.Response(404, json={"a": 1}), True).body == {"a": 1} + + +class TestPagination: + def test_resolve_max_records(self) -> None: + assert ex.resolve_max_records(None, "m") is None + assert ex.resolve_max_records(-1, "m") == float("inf") + assert ex.resolve_max_records(5, "m") == 5 + for bad in (0, -2, 1.5, True): + with pytest.raises(ValueError, match="max_records"): + ex.resolve_max_records(bad, "m") # type: ignore[arg-type] + + def test_extract_page(self) -> None: + token = page_token() + page = ex.extract_page(paging_headers(token=token), [1]) + assert page is not None + assert page.has_more is True + assert page.next_page_token == token + + def test_extract_page_none_cases(self) -> None: + assert ex.extract_page({}, [1]) is None + assert ex.extract_page(paging_headers(), {"not": "a list"}) is None + assert ex.extract_page(paging_headers(token=page_token("done")), [1]) is None + + def test_unreadable_token_is_still_a_token(self) -> None: + page = ex.extract_page(paging_headers(token="!!not-base64!!"), [1]) + assert page is not None and page.next_page_token == "!!not-base64!!" + + +class TestV4Helpers: + @pytest.mark.parametrize( + "version,expected", + [ + ("4.0.0", True), + ("v4", True), + ("12.1", True), + (" 4.2 ", True), + ("3.9.9", False), + ("", False), + (None, False), + ("latest", False), + ], + ) + def test_uses_v4_engine(self, version: str | None, expected: bool) -> None: + assert ex.uses_v4_engine(version) is expected + + def test_manifest_for_json_body(self) -> None: + manifest = ex.build_v4_manifest( + connection_id="c", + connector_key="uipath-x", + method="POST", + url="https://api.example.com/t?a=1", + headers={"X-A": "1"}, + query_params={"b": "2 3"}, + body={"k": "v"}, + file=None, + ) + assert manifest == { + "outboundRequestConfig": { + "method": "POST", + "url": "https://api.example.com/t?a=1&b=2+3", + "headers": [ + {"name": "X-A", "value": "1"}, + {"name": "Content-Type", "value": "application/json"}, + ], + "body": '{"k": "v"}', + }, + "context": {"connectionId": "c", "connectorKey": "uipath-x"}, + } + + def test_manifest_keeps_caller_content_type_and_string_body(self) -> None: + manifest = ex.build_v4_manifest( + connection_id="c", + connector_key=None, + method="POST", + url="https://x", + headers={"content-type": "text/plain"}, + query_params=None, + body="raw", + file=None, + ) + assert manifest["outboundRequestConfig"] == { + "method": "POST", + "url": "https://x", + "headers": [{"name": "content-type", "value": "text/plain"}], + "body": "raw", + } + assert manifest["context"] == {"connectionId": "c"} + + def test_unwrap_base64_body(self) -> None: + result = ex.unwrap_v4_response( + ExecuteResult( + ok=True, + status=200, + body={ + "status": 200, + "headers": {"set-cookie": ["a", "b"], "x": 1, "n": None}, + "body": base64.b64encode(b"\x00\x01").decode(), + "bodyEncoding": "base64", + }, + ) + ) + assert result.ok and not result.is_vendor_error + assert result.body == b"\x00\x01" + assert result.headers == {"set-cookie": "a, b", "x": "1"} + + def test_unwrap_engine_failure_is_not_a_vendor_error(self) -> None: + result = ex.unwrap_v4_response( + ExecuteResult(ok=False, status=400, body={"message": "relative url"}) + ) + assert result.status == 400 and not result.ok and not result.is_vendor_error + + def test_unwrap_two_part_answer(self) -> None: + payload = b"%PDF\r\n--b1\r\nbinary\x00" + document = ( + b"--b1\r\nContent-Type: application/json\r\n\r\n" + + json.dumps({"status": 404, "headers": {"a": "b"}}).encode() + + b"\r\n--b1\r\nContent-Type: application/pdf\r\n\r\n" + + payload + + b"\r\n--b1--\r\n" + ) + result = ex.unwrap_v4_response( + ExecuteResult( + ok=True, + status=200, + body=document, + headers={"content-type": 'multipart/mixed; boundary="b1"'}, + ) + ) + assert result.status == 404 and result.is_vendor_error + assert result.body == payload + assert result.headers == {"a": "b"} + + def test_truncated_two_part_answer_is_refused(self) -> None: + document = b'--b1\r\n\r\n{"status": 200}\r\n--b1\r\n\r\npartial' + with pytest.raises(ValueError, match="incomplete file response"): + ex.unwrap_v4_response( + ExecuteResult( + ok=True, + status=200, + body=document, + headers={"content-type": "multipart/mixed; boundary=b1"}, + ) + ) + + +class TestProxyResponse: + def test_vendor_response_is_unwrapped(self) -> None: + result = ex.unwrap_proxy_response( + ExecuteResult( + ok=True, + status=200, + body={ + "code": 404, + "statusText": "Not Found", + "headers": {"x": "y"}, + "rawStringBody": "nope", + }, + ) + ) + assert result.model_dump() == { + "ok": False, + "status": 404, + "status_text": "Not Found", + "body": "nope", + "headers": {"x": "y"}, + "is_vendor_error": True, + } + + def test_parsed_body_wins(self) -> None: + result = ex.unwrap_proxy_response( + ExecuteResult( + ok=True, + status=200, + body={"code": 200, "body": {"a": 1}, "rawStringBody": '{"a":1}'}, + ) + ) + assert result.ok and result.body == {"a": 1} and not result.is_vendor_error + + @pytest.mark.parametrize( + "raw", + [ + ExecuteResult(ok=False, status=401, body={"code": 200}), + ExecuteResult(ok=True, status=200, body={"no": "code"}), + ExecuteResult(ok=True, status=200, body="text"), + ], + ) + def test_integration_service_response_is_returned_as_is( + self, raw: ExecuteResult + ) -> None: + result = ex.unwrap_proxy_response(raw) + assert result.status == raw.status and result.body == raw.body + assert result.is_vendor_error is False + + +class TestExecuteActivity: + def test_get( + self, + httpx_mock: HTTPXMock, + service: IntegrationService, + instance_url: str, + version: str, + ) -> None: + httpx_mock.add_response( + url=f"{instance_url}/tickets?limit=10", json=[{"id": 1}] + ) + + result = service.execute_activity( + CONNECTION_ID, "tickets", query_params={"limit": "10"} + ) + + assert isinstance(result, ExecuteActivityResult) + assert result.ok and result.status == 200 + assert result.body == [{"id": 1}] + assert result.page is None + request = sent(httpx_mock) + assert request.method == "GET" + assert request.content == b"" + assert request.headers["x-uipath-originator"] == "uipath-python" + assert HEADER_FOLDER_KEY not in request.headers + assert request.headers[HEADER_USER_AGENT].endswith( + f"IntegrationService.execute/{version}" + ) + + def test_non_2xx_is_returned_not_raised( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response( + url=f"{instance_url}/tickets", status_code=404, json={"message": "no"} + ) + + result = service.execute_activity(CONNECTION_ID, "tickets") + + assert not result.ok + assert result.status == 404 + assert result.body == {"message": "no"} + assert len(httpx_mock.get_requests()) == 1 + + def test_server_error_is_not_retried_by_default( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response(url=f"{instance_url}/tickets", status_code=503) + + assert service.execute_activity(CONNECTION_ID, "tickets").status == 503 + assert len(httpx_mock.get_requests()) == 1 + + def test_post_expands_body_paths( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response(url=f"{instance_url}/issues", json={"id": "1"}) + + service.execute_activity( + CONNECTION_ID, + "issues", + "post", + body={"fields.summary": "x", "key": "K"}, + folder_key="folder-1", + ) + + request = sent(httpx_mock) + assert request.method == "POST" + assert json.loads(request.content) == {"fields": {"summary": "x"}, "key": "K"} + assert request.headers["content-type"] == "application/json" + assert request.headers[HEADER_FOLDER_KEY] == "folder-1" + + @pytest.mark.parametrize("method", ["POST", "PUT", "PATCH"]) + def test_write_without_body_sends_empty_object( + self, + httpx_mock: HTTPXMock, + service: IntegrationService, + instance_url: str, + method: str, + ) -> None: + httpx_mock.add_response(url=f"{instance_url}/tickets", json={}) + + service.execute_activity(CONNECTION_ID, "tickets", method) + + assert json.loads(sent(httpx_mock).content) == {} + + def test_delete_carries_no_body( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response(url=f"{instance_url}/tickets/1", status_code=204) + + result = service.execute_activity( + CONNECTION_ID, "tickets/1", "DELETE", body={"ignored": True} + ) + + assert result.ok and result.body == "" + assert sent(httpx_mock).content == b"" + + def test_object_name_segments_are_encoded( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response(json={}) + + service.execute_activity(CONNECTION_ID, "curated_get/A B#1") + + assert ( + sent(httpx_mock) + .url.raw_path.decode() + .endswith(f"/instances/{CONNECTION_ID}/curated_get/A%20B%231") + ) + + def test_file_upload_is_multipart( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response(url=f"{instance_url}/files", json={"id": "f"}) + + service.execute_activity( + CONNECTION_ID, + "files", + "POST", + body={"title": "Report"}, + files=[ + ExecuteFile( + name="file", + content=b"%PDF-1", + file_name="r.pdf", + content_type="application/pdf", + ), + ExecuteFile(name="extra", content=b"abc"), + ], + ) + + request = sent(httpx_mock) + assert request.headers["content-type"].startswith("multipart/form-data") + content = request.content + assert b'name="body"\r\n\r\n{"title": "Report"}' in content + assert b'name="file"; filename="r.pdf"' in content + assert b"Content-Type: application/pdf\r\n\r\n%PDF-1" in content + assert b'name="extra"; filename="file"' in content + assert b"Content-Type: application/octet-stream\r\n\r\nabc" in content + assert content.index(b'name="body"') < content.index(b'name="file"') + + def test_file_upload_without_body_has_no_body_part( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response(url=f"{instance_url}/files", json={}) + + service.execute_activity( + CONNECTION_ID, + "files", + "POST", + files=[ExecuteFile(name="file", content=b"abc")], + body_part_name="meta", + ) + + content = sent(httpx_mock).content + assert b'name="meta"' not in content and b'name="body"' not in content + + def test_file_download_detected_from_headers( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response( + url=f"{instance_url}/files/1/content", + content=b"\x89PNG", + headers={"content-type": "image/png"}, + ) + + result = service.execute_activity(CONNECTION_ID, "files/1/content") + + assert result.body == b"\x89PNG" + + def test_file_response_forces_bytes( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response(url=f"{instance_url}/export", text="a,b") + + result = service.execute_activity(CONNECTION_ID, "export", file_response=True) + + assert result.body == b"a,b" + + def test_url_input_fields_are_base64_encoded( + self, httpx_mock: HTTPXMock, service: IntegrationService + ) -> None: + httpx_mock.add_response(json=[]) + + service.execute_activity( + CONNECTION_ID, + "pages", + query_params={"url": "https://a.com/x", "q": "t"}, + url_input_fields=["url"], + ) + + params = sent(httpx_mock).url.params + assert params["url"] == base64.b64encode(b"https://a.com/x").decode() + assert params["q"] == "t" + + def test_single_page_reports_paging_state( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + token = page_token() + httpx_mock.add_response( + url=f"{instance_url}/tickets", + json=[1, 2], + headers=paging_headers(token=token), + ) + + result = service.execute_activity(CONNECTION_ID, "tickets") + + assert result.body == [1, 2] + assert result.page is not None + assert result.page.has_more and result.page.next_page_token == token + + def test_max_records_follows_pages( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + first, second = page_token("2"), page_token("3") + httpx_mock.add_response( + url=f"{instance_url}/tickets?pageSize=2", + json=[1, 2], + headers=paging_headers(token=first), + ) + httpx_mock.add_response( + url=f"{instance_url}/tickets?pageSize=2&nextPage={first}", + json=[3, 4], + headers=paging_headers(token=second), + ) + httpx_mock.add_response( + url=f"{instance_url}/tickets?pageSize=2&nextPage={second}", + json=[5, 6], + headers=paging_headers(token=page_token("4")), + ) + + result = service.execute_activity( + CONNECTION_ID, "tickets", query_params={"pageSize": "2"}, max_records=5 + ) + + assert result.body == [1, 2, 3, 4, 5] + assert result.page is None + assert "elements-has-more" not in result.headers + assert "elements-next-page-token" not in result.headers + assert len(httpx_mock.get_requests()) == 3 + + def test_max_records_all_stops_at_done_token( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + first = page_token("2") + httpx_mock.add_response( + url=f"{instance_url}/tickets", + json=[1], + headers=paging_headers(token=first), + ) + httpx_mock.add_response( + url=f"{instance_url}/tickets?nextPage={first}", + json=[2], + headers=paging_headers(token=page_token("DONE")), + ) + + result = service.execute_activity(CONNECTION_ID, "tickets", max_records=-1) + + assert result.body == [1, 2] + + def test_max_records_within_first_page_keeps_page( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response( + url=f"{instance_url}/tickets", json=[1, 2], headers=paging_headers() + ) + + result = service.execute_activity(CONNECTION_ID, "tickets", max_records=2) + + assert result.body == [1, 2] + assert result.page is not None + assert len(httpx_mock.get_requests()) == 1 + + def test_failed_page_is_the_result( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + first = page_token("2") + httpx_mock.add_response( + url=f"{instance_url}/tickets", + json=[1], + headers=paging_headers(token=first), + ) + httpx_mock.add_response( + url=f"{instance_url}/tickets?nextPage={first}", + status_code=500, + json={"message": "boom"}, + ) + + result = service.execute_activity(CONNECTION_ID, "tickets", max_records=10) + + assert result.status == 500 and result.body == {"message": "boom"} + + def test_opt_in_retry( + self, + httpx_mock: HTTPXMock, + service: IntegrationService, + instance_url: str, + monkeypatch: pytest.MonkeyPatch, + ) -> None: + monkeypatch.setattr("time.sleep", lambda _: None) + httpx_mock.add_response(url=f"{instance_url}/tickets", status_code=503) + httpx_mock.add_exception(httpx.ConnectError("down")) + httpx_mock.add_response(url=f"{instance_url}/tickets", json=[1]) + + result = service.execute_activity(CONNECTION_ID, "tickets", max_retries=2) + + assert result.ok and result.body == [1] + assert len(httpx_mock.get_requests()) == 3 + + def test_retry_gives_up_with_last_response( + self, + httpx_mock: HTTPXMock, + service: IntegrationService, + instance_url: str, + monkeypatch: pytest.MonkeyPatch, + ) -> None: + monkeypatch.setattr("time.sleep", lambda _: None) + httpx_mock.add_response( + url=f"{instance_url}/tickets", status_code=503, is_reusable=True + ) + + result = service.execute_activity(CONNECTION_ID, "tickets", max_retries=1) + + assert result.status == 503 + assert len(httpx_mock.get_requests()) == 2 + + def test_post_is_not_retried_unless_listed( + self, + httpx_mock: HTTPXMock, + service: IntegrationService, + instance_url: str, + monkeypatch: pytest.MonkeyPatch, + ) -> None: + monkeypatch.setattr("time.sleep", lambda _: None) + httpx_mock.add_response( + url=f"{instance_url}/tickets", status_code=503, is_reusable=True + ) + + service.execute_activity(CONNECTION_ID, "tickets", "POST", max_retries=2) + assert len(httpx_mock.get_requests()) == 1 + + service.execute_activity( + CONNECTION_ID, "tickets", "POST", max_retries=2, retry_methods=["post"] + ) + assert len(httpx_mock.get_requests()) == 4 + + def test_client_error_is_not_retried( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response(url=f"{instance_url}/tickets", status_code=400) + + service.execute_activity(CONNECTION_ID, "tickets", max_retries=3) + + assert len(httpx_mock.get_requests()) == 1 + + @pytest.mark.parametrize( + "kwargs,message", + [ + ({"connection_id": "", "object_name": "t"}, "connection_id is required"), + ({"connection_id": "c", "object_name": ""}, "object_name is required"), + ({"connection_id": "c", "object_name": "t", "method": "HEAD"}, "method"), + ( + {"connection_id": "c", "object_name": "t", "max_records": 0}, + "max_records", + ), + ( + { + "connection_id": "c", + "object_name": "t", + "files": [ExecuteFile(name="", content=b"x")], + }, + "needs a name", + ), + ( + { + "connection_id": "c", + "object_name": "t", + "folder_key": "k", + "folder_path": "p", + }, + "Only one of folder_key or folder_path", + ), + ], + ) + def test_validation( + self, + httpx_mock: HTTPXMock, + service: IntegrationService, + kwargs: Dict[str, Any], + message: str, + ) -> None: + with pytest.raises(ValueError, match=message): + service.execute_activity(**kwargs) + assert httpx_mock.get_requests() == [] + + def test_connection_overwrite_is_applied( + self, + httpx_mock: HTTPXMock, + service: IntegrationService, + base_url: str, + org: str, + tenant: str, + ) -> None: + httpx_mock.add_response( + url=f"{base_url}{org}{tenant}/elements_/v3/element/instances/mapped/tickets", + json=[], + ) + token = _resource_overwrites.set( + { + f"connection.{CONNECTION_ID}": ConnectionResourceOverwrite( + resource_type="connection", + connection_id="mapped", + folder_key="mapped-folder", + ) + } + ) + try: + service.execute_activity(CONNECTION_ID, "tickets", folder_path="Shared") + finally: + _resource_overwrites.reset(token) + + assert sent(httpx_mock).headers[HEADER_FOLDER_KEY] == "mapped-folder" + + async def test_async_get_and_paging( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + first = page_token("2") + httpx_mock.add_response( + url=f"{instance_url}/tickets", + json=[1], + headers=paging_headers(token=first), + ) + httpx_mock.add_response( + url=f"{instance_url}/tickets?nextPage={first}", + json=[2], + headers=paging_headers(has_more=False), + ) + + result = await service.execute_activity_async( + CONNECTION_ID, "tickets", max_records=-1 + ) + + assert result.body == [1, 2] + + async def test_async_non_2xx_is_returned( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response( + url=f"{instance_url}/tickets", status_code=401, text="denied" + ) + + result = await service.execute_activity_async( + CONNECTION_ID, "tickets", "POST", body={"a.b": 1} + ) + + assert result.status == 401 and result.body == "denied" + assert json.loads(sent(httpx_mock).content) == {"a": {"b": 1}} + + +class TestExecuteActivityV4: + def test_runs_on_the_v4_engine( + self, httpx_mock: HTTPXMock, service: IntegrationService, v4_url: str + ) -> None: + httpx_mock.add_response( + url=v4_url, + json={"status": 200, "headers": {"x-v": ["a", "b"]}, "body": {"ts": "1"}}, + headers=paging_headers(), + ) + + result = service.execute_activity( + CONNECTION_ID, + "SendMessageToChannel", + "POST", + connector_version="4.0.0", + connector_key="uipath-salesforce-slack", + query_params={"send_as": "bot"}, + headers={"X-Trace": "t"}, + body={"channel": "C1", "blocks[0].type": "section"}, + folder_key="f1", + # None of these apply on the version 4 engine + url_input_fields=["send_as"], + file_response=True, + max_records=5, + ) + + assert isinstance(result, ExecuteActivityResult) + assert result.model_dump() == { + "ok": True, + "status": 200, + "status_text": "", + "body": {"ts": "1"}, + "headers": {"x-v": "a, b"}, + "page": None, + } + request = sent(httpx_mock) + assert request.method == "POST" + assert request.url.query == b"" + assert request.headers[HEADER_FOLDER_KEY] == "f1" + assert "x-trace" not in request.headers + assert json.loads(request.content) == { + "context": { + "connectionId": CONNECTION_ID, + "connectorKey": "uipath-salesforce-slack", + "script": {"reference": "SendMessageToChannel"}, + }, + "request": { + "body": {"channel": "C1", "blocks": [{"type": "section"}]}, + "query": {"send_as": "bot"}, + "headers": {"X-Trace": "t"}, + }, + } + assert len(httpx_mock.get_requests()) == 1 + + def test_script_ref_overrides_object_name_and_empty_request( + self, httpx_mock: HTTPXMock, service: IntegrationService, v4_url: str + ) -> None: + httpx_mock.add_response(url=v4_url, json={"status": 200, "body": []}) + + service.execute_activity( + CONNECTION_ID, + "ListChannels", + "POST", + connector_version="v5", + connector_key="uipath-x", + script_ref="scripts/list-channels", + ) + + assert json.loads(sent(httpx_mock).content) == { + "context": { + "connectionId": CONNECTION_ID, + "connectorKey": "uipath-x", + "script": {"reference": "scripts/list-channels"}, + }, + # A write without a body is not given `{}` on the version 4 engine + "request": {}, + } + + def test_vendor_error_is_returned( + self, httpx_mock: HTTPXMock, service: IntegrationService, v4_url: str + ) -> None: + httpx_mock.add_response( + url=v4_url, json={"status": 404, "body": {"error": "channel_not_found"}} + ) + + result = service.execute_activity( + CONNECTION_ID, "GetChannel", connector_version="4.0.0", connector_key="k" + ) + + assert not result.ok and result.status == 404 + assert result.body == {"error": "channel_not_found"} + assert not hasattr(result, "is_vendor_error") + + def test_engine_failure_is_returned_as_is( + self, httpx_mock: HTTPXMock, service: IntegrationService, v4_url: str + ) -> None: + httpx_mock.add_response( + url=v4_url, status_code=400, json={"error": "unknown script"} + ) + + result = service.execute_activity( + CONNECTION_ID, "Nope", connector_version="4.0.0", connector_key="k" + ) + + assert result.status == 400 and result.body == {"error": "unknown script"} + + def test_older_version_stays_on_v3( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response(url=f"{instance_url}/tickets", json=[]) + + assert service.execute_activity( + CONNECTION_ID, "tickets", connector_version="3.9.0", headers={"X": "1"} + ).ok + assert "x" not in sent(httpx_mock).headers + + def test_retry_follows_the_activity_method( + self, + httpx_mock: HTTPXMock, + service: IntegrationService, + v4_url: str, + monkeypatch: pytest.MonkeyPatch, + ) -> None: + monkeypatch.setattr("time.sleep", lambda _: None) + httpx_mock.add_response(url=v4_url, status_code=503, is_reusable=True) + v4 = {"connector_version": "4.0.0", "connector_key": "k"} + + service.execute_activity(CONNECTION_ID, "Send", "POST", max_retries=2, **v4) + assert len(httpx_mock.get_requests()) == 1 + + service.execute_activity(CONNECTION_ID, "List", "GET", max_retries=2, **v4) + assert len(httpx_mock.get_requests()) == 4 + + @pytest.mark.parametrize( + "kwargs,message", + [ + ({}, "connector_key is required"), + ( + { + "connector_key": "k", + "files": [ExecuteFile(name="file", content=b"x")], + }, + "files are not supported", + ), + ({"connector_key": "k", "max_records": 0}, "max_records"), + ], + ) + def test_validation( + self, + httpx_mock: HTTPXMock, + service: IntegrationService, + kwargs: Dict[str, Any], + message: str, + ) -> None: + with pytest.raises(ValueError, match=message): + service.execute_activity( + CONNECTION_ID, "Send", "POST", connector_version="4.0.0", **kwargs + ) + assert httpx_mock.get_requests() == [] + + async def test_async( + self, httpx_mock: HTTPXMock, service: IntegrationService, v4_url: str + ) -> None: + httpx_mock.add_response(url=v4_url, json={"status": 201, "body": {"id": 1}}) + + result = await service.execute_activity_async( + CONNECTION_ID, + "Create", + "POST", + connector_version="4.0.0", + connector_key="k", + body={"a.b": 1}, + ) + + assert result.ok and result.status == 201 and result.body == {"id": 1} + assert json.loads(sent(httpx_mock).content)["request"] == { + "body": {"a": {"b": 1}} + } + + +class TestExecuteHttp: + def test_v3_passthrough( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response( + url=f"{instance_url}/http-request", + json={ + "code": 201, + "statusText": "Created", + "headers": {"x-v": "1"}, + "body": {"id": 7}, + }, + ) + + result = service.execute_http( + CONNECTION_ID, + "/v2/tickets", + "POST", + headers={"X-Src": "app"}, + query_params={"notify": "true"}, + body={"subject": "s"}, + folder_key="f1", + ) + + assert isinstance(result, ExecuteHttpResult) + assert result.model_dump() == { + "ok": True, + "status": 201, + "status_text": "Created", + "body": {"id": 7}, + "headers": {"x-v": "1"}, + "is_vendor_error": False, + } + request = sent(httpx_mock) + assert request.method == "POST" + assert request.headers[HEADER_FOLDER_KEY] == "f1" + assert json.loads(request.content) == { + "method": "POST", + "url": "/v2/tickets", + "headers": {"X-Src": "app"}, + "query": {"notify": "true"}, + "body": '{"subject": "s"}', + } + + def test_v3_minimal_request_and_string_body( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response( + url=f"{instance_url}/http-request", json={"code": 200}, is_reusable=True + ) + + service.execute_http(CONNECTION_ID, "/v2/tickets") + assert json.loads(sent(httpx_mock).content) == { + "method": "GET", + "url": "/v2/tickets", + } + + service.execute_http(CONNECTION_ID, "/v2/tickets", "PUT", body="raw") + assert json.loads(sent(httpx_mock).content)["body"] == "raw" + + def test_v3_vendor_error( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response( + url=f"{instance_url}/http-request", + json={"code": 404, "rawStringBody": "missing"}, + ) + + result = service.execute_http(CONNECTION_ID, "/v2/none") + + assert not result.ok and result.status == 404 + assert result.is_vendor_error and result.body == "missing" + + def test_integration_service_failure_is_not_a_vendor_error( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response( + url=f"{instance_url}/http-request", + status_code=403, + json={"message": "forbidden"}, + ) + + result = service.execute_http(CONNECTION_ID, "/v2/tickets") + + assert result.status == 403 and not result.is_vendor_error + assert result.body == {"message": "forbidden"} + + def test_older_connector_version_uses_v3( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response(url=f"{instance_url}/http-request", json={"code": 200}) + + assert service.execute_http(CONNECTION_ID, "/x", connector_version="3.2.1").ok + + def test_v4_engine( + self, httpx_mock: HTTPXMock, service: IntegrationService, v4_url: str + ) -> None: + httpx_mock.add_response( + url=v4_url, + json={"status": 200, "headers": {"h": ["a", "b"]}, "body": {"ok": 1}}, + ) + + result = service.execute_http( + CONNECTION_ID, + "https://api.example.com/v2/tickets", + query_params={"a": "1"}, + connector_version="4.0.0", + connector_key="uipath-x", + ) + + assert result.ok and result.body == {"ok": 1} + assert result.headers == {"h": "a, b"} + assert json.loads(sent(httpx_mock).content) == { + "outboundRequestConfig": { + "method": "GET", + "url": "https://api.example.com/v2/tickets?a=1", + }, + "context": {"connectionId": CONNECTION_ID, "connectorKey": "uipath-x"}, + } + + def test_v4_vendor_error( + self, httpx_mock: HTTPXMock, service: IntegrationService, v4_url: str + ) -> None: + httpx_mock.add_response(url=v4_url, json={"status": 404, "body": "nope"}) + + result = service.execute_http( + CONNECTION_ID, "https://api.example.com/x", connector_version="4.1" + ) + + assert result.status == 404 and result.is_vendor_error + + def test_v4_file_upload( + self, httpx_mock: HTTPXMock, service: IntegrationService, v4_url: str + ) -> None: + httpx_mock.add_response(url=v4_url, json={"status": 200}) + + service.execute_http( + CONNECTION_ID, + "https://api.example.com/files", + "PUT", + connector_version="4.0.0", + file=ExecuteFile( + name="file", content=b"%PDF-1", content_type="application/pdf" + ), + ) + + request = sent(httpx_mock) + assert request.headers["content-type"].startswith("multipart/form-data") + content = request.content + assert content.index(b'name="manifest"') < content.index(b'name="file"') + assert b'"bodyRef": "file"' in content + assert ( + b'"attachments": [{"name": "file", "size": 6, "contentType": "application/pdf"}]' + in content + ) + assert b"Content-Type: application/pdf\r\n\r\n%PDF-1" in content + + def test_v4_binary_download( + self, httpx_mock: HTTPXMock, service: IntegrationService, v4_url: str + ) -> None: + document = ( + b'--xyz\r\nContent-Type: application/json\r\n\r\n{"status": 200, "headers": {"content-type": "image/png"}}' + b"\r\n--xyz\r\nContent-Type: application/octet-stream\r\n\r\n\x89PNG\r\n\x00" + b"\r\n--xyz--\r\n" + ) + httpx_mock.add_response( + url=v4_url, + content=document, + headers={"content-type": "multipart/mixed; boundary=xyz"}, + ) + + result = service.execute_http( + CONNECTION_ID, "https://api.example.com/img", connector_version="4.0.0" + ) + + assert result.ok and result.body == b"\x89PNG\r\n\x00" + assert result.headers == {"content-type": "image/png"} + + def test_retry_follows_vendor_method( + self, + httpx_mock: HTTPXMock, + service: IntegrationService, + instance_url: str, + monkeypatch: pytest.MonkeyPatch, + ) -> None: + monkeypatch.setattr("time.sleep", lambda _: None) + httpx_mock.add_response( + url=f"{instance_url}/http-request", status_code=502, is_reusable=True + ) + + service.execute_http(CONNECTION_ID, "/x", "POST", max_retries=2) + assert len(httpx_mock.get_requests()) == 1 + + service.execute_http(CONNECTION_ID, "/x", "GET", max_retries=2) + assert len(httpx_mock.get_requests()) == 4 + + @pytest.mark.parametrize( + "kwargs,message", + [ + ({"connection_id": "c", "url": ""}, "url is required"), + ({"connection_id": "", "url": "/x"}, "connection_id is required"), + ( + { + "connection_id": "c", + "url": "/x", + "file": ExecuteFile(name="f", content=b"x"), + }, + "version 4 connector", + ), + ( + { + "connection_id": "c", + "url": "https://x", + "connector_version": "4.0.0", + "body": {"a": 1}, + "file": ExecuteFile(name="f", content=b"x"), + }, + "file and body cannot both", + ), + ], + ) + def test_validation( + self, + httpx_mock: HTTPXMock, + service: IntegrationService, + kwargs: Dict[str, Any], + message: str, + ) -> None: + with pytest.raises(ValueError, match=message): + service.execute_http(**kwargs) + assert httpx_mock.get_requests() == [] + + async def test_async_v3_and_v4( + self, + httpx_mock: HTTPXMock, + service: IntegrationService, + instance_url: str, + v4_url: str, + ) -> None: + httpx_mock.add_response( + url=f"{instance_url}/http-request", json={"code": 500, "body": {"e": 1}} + ) + httpx_mock.add_response(url=v4_url, json={"status": 200, "body": "ok"}) + + v3 = await service.execute_http_async(CONNECTION_ID, "/x") + v4 = await service.execute_http_async( + CONNECTION_ID, "https://api.example.com/x", connector_version="4.0.0" + ) + + assert v3.status == 500 and v3.is_vendor_error and v3.body == {"e": 1} + assert v4.ok and v4.body == "ok" + + +def test_sdk_exposes_integration_service_and_leaves_connections_alone() -> None: + from uipath.platform import UiPath + from uipath.platform.connections import ConnectionsService + + sdk = UiPath(base_url="https://test.uipath.com/org/tenant", secret="secret") + + assert isinstance(sdk.integration_service, IntegrationService) + assert isinstance(sdk.connections, ConnectionsService) + assert not hasattr(sdk.connections, "execute_activity") diff --git a/packages/uipath-platform/uv.lock b/packages/uipath-platform/uv.lock index 479b3bdca..17d0ca82d 100644 --- a/packages/uipath-platform/uv.lock +++ b/packages/uipath-platform/uv.lock @@ -1082,7 +1082,7 @@ dev = [ [[package]] name = "uipath-platform" -version = "0.3.12" +version = "0.3.13" source = { editable = "." } dependencies = [ { name = "anyio" }, diff --git a/packages/uipath/docs/core/integration_service.md b/packages/uipath/docs/core/integration_service.md new file mode 100644 index 000000000..bfb68ae74 --- /dev/null +++ b/packages/uipath/docs/core/integration_service.md @@ -0,0 +1,3 @@ +::: uipath.platform.integration_service._integration_service + +::: uipath.platform.integration_service.execution_types diff --git a/packages/uipath/mkdocs.yml b/packages/uipath/mkdocs.yml index f4572c0c5..b5012bb54 100644 --- a/packages/uipath/mkdocs.yml +++ b/packages/uipath/mkdocs.yml @@ -74,6 +74,7 @@ nav: - Entities: core/entities.md - Jobs: core/jobs.md - Guardrails: core/guardrails.md + - Integration Service: core/integration_service.md - LLM Gateway: core/llm_gateway.md - Queues: core/queues.md - Processes: core/processes.md diff --git a/packages/uipath/uv.lock b/packages/uipath/uv.lock index ab608bcd9..ffe400b67 100644 --- a/packages/uipath/uv.lock +++ b/packages/uipath/uv.lock @@ -2883,7 +2883,7 @@ wheels = [ [[package]] name = "uipath-platform" -version = "0.3.12" +version = "0.3.13" source = { editable = "../uipath-platform" } dependencies = [ { name = "anyio" }, From c2abebccb7c16f422ae72e85a4b5c060ea808cd1 Mon Sep 17 00:00:00 2001 From: chandusailella Date: Fri, 20 Nov 2026 02:19:06 +0530 Subject: [PATCH 2/2] fix(integration-service): reject dot path segments and trace only safe inputs - execute_activity refuses an object_name with a '.' or '..' segment, and both methods refuse a connection_id of '.' or '..', so a call cannot be resolved off the connection it names. - The trace of an execute call records an allowlist of arguments. The body, headers, query parameters and files are left out, and the execute_http URL is recorded without its query string or credentials. Co-Authored-By: Claude Fable 5.2 --- .../_integration_service.py | 55 ++++++++++++---- .../integration_service/execution/_request.py | 19 +++++- .../services/test_integration_service.py | 62 +++++++++++++++++++ 3 files changed, 122 insertions(+), 14 deletions(-) diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/_integration_service.py b/packages/uipath-platform/src/uipath/platform/integration_service/_integration_service.py index 0d867e845..bf8a0dfa0 100644 --- a/packages/uipath-platform/src/uipath/platform/integration_service/_integration_service.py +++ b/packages/uipath-platform/src/uipath/platform/integration_service/_integration_service.py @@ -3,6 +3,7 @@ import asyncio import time from typing import Any, Dict, Optional, Sequence +from urllib.parse import urlsplit from httpx import Response, TransportError from uipath.core.tracing import traced @@ -43,13 +44,45 @@ _EXECUTE_MAX_BACKOFF = 10.0 -def _hide_file_bytes(inputs: Dict[str, Any]) -> Dict[str, Any]: - """Keep uploaded file content out of the trace.""" - hidden = dict(inputs) - for key in ("files", "file"): - if hidden.get(key): - hidden[key] = "" - return hidden +# The arguments of an execute call that are safe to record in a trace. The body, +# headers, query parameters and files can carry secrets or personal data. +_TRACED_INPUTS = frozenset( + { + "connection_id", + "object_name", + "method", + "connector_version", + "connector_key", + "script_ref", + "folder_key", + "folder_path", + "file_response", + "max_records", + "max_retries", + "retry_methods", + "timeout", + } +) + + +def _traced_inputs(inputs: Any) -> Dict[str, Any]: + """Keep only the non-sensitive arguments of an execute call in the trace.""" + if not isinstance(inputs, dict): + return {} + traced_inputs = { + key: value for key, value in inputs.items() if key in _TRACED_INPUTS + } + url = inputs.get("url") + if isinstance(url, str): + # Scheme, host and path only: a query string or userinfo can hold a secret + try: + parts = urlsplit(url) + host = parts.hostname or "" + origin = f"{parts.scheme}://{host}" if parts.scheme and host else "" + traced_inputs["url"] = f"{origin}{parts.path}" + except ValueError: + traced_inputs["url"] = "" + return traced_inputs class IntegrationService(BaseService): @@ -78,7 +111,7 @@ def __init__( @traced( name="integration_service_execute_activity", run_type="uipath", - input_processor=_hide_file_bytes, + input_processor=_traced_inputs, hide_output=True, ) def execute_activity( @@ -250,7 +283,7 @@ def execute_activity( @traced( name="integration_service_execute_activity", run_type="uipath", - input_processor=_hide_file_bytes, + input_processor=_traced_inputs, hide_output=True, ) async def execute_activity_async( @@ -375,7 +408,7 @@ async def execute_activity_async( @traced( name="integration_service_execute_http", run_type="uipath", - input_processor=_hide_file_bytes, + input_processor=_traced_inputs, hide_output=True, ) def execute_http( @@ -491,7 +524,7 @@ def execute_http( @traced( name="integration_service_execute_http", run_type="uipath", - input_processor=_hide_file_bytes, + input_processor=_traced_inputs, hide_output=True, ) async def execute_http_async( diff --git a/packages/uipath-platform/src/uipath/platform/integration_service/execution/_request.py b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_request.py index 7596854ab..10c701bd4 100644 --- a/packages/uipath-platform/src/uipath/platform/integration_service/execution/_request.py +++ b/packages/uipath-platform/src/uipath/platform/integration_service/execution/_request.py @@ -64,10 +64,23 @@ def activity_endpoint(connection_id: str, object_name: str) -> str: `object_name` may be a multi-segment path such as `curated_get_issue/ABC-1`: each segment is encoded on its own and the `/` separators are kept. """ - path = "/".join(quote(segment, safe="") for segment in object_name.split("/")) - return f"{ELEMENT_INSTANCES_BASE}/{quote(connection_id, safe='')}/{path}" + segments = object_name.split("/") + if any(segment in _DOT_SEGMENTS for segment in segments): + raise ValueError("object_name must not contain a '.' or '..' path segment") + path = "/".join(quote(segment, safe="") for segment in segments) + return f"{_instance_base(connection_id)}/{path}" def http_request_endpoint(connection_id: str) -> str: """Path of the version 3 raw HTTP passthrough of a connection.""" - return f"{ELEMENT_INSTANCES_BASE}/{quote(connection_id, safe='')}/http-request" + return f"{_instance_base(connection_id)}/http-request" + + +# A client or proxy resolves these, which would move the call off the connection +_DOT_SEGMENTS = frozenset({".", ".."}) + + +def _instance_base(connection_id: str) -> str: + if connection_id in _DOT_SEGMENTS: + raise ValueError("connection_id must not be '.' or '..'") + return f"{ELEMENT_INSTANCES_BASE}/{quote(connection_id, safe='')}" diff --git a/packages/uipath-platform/tests/services/test_integration_service.py b/packages/uipath-platform/tests/services/test_integration_service.py index 6914a6d2d..4aa452bb8 100644 --- a/packages/uipath-platform/tests/services/test_integration_service.py +++ b/packages/uipath-platform/tests/services/test_integration_service.py @@ -705,6 +705,9 @@ def test_client_error_is_not_retried( ({"connection_id": "", "object_name": "t"}, "connection_id is required"), ({"connection_id": "c", "object_name": ""}, "object_name is required"), ({"connection_id": "c", "object_name": "t", "method": "HEAD"}, "method"), + ({"connection_id": "c", "object_name": "../other/tickets"}, "path segment"), + ({"connection_id": "c", "object_name": "a/./b"}, "path segment"), + ({"connection_id": "..", "object_name": "tickets"}, "connection_id"), ( {"connection_id": "c", "object_name": "t", "max_records": 0}, "max_records", @@ -1184,6 +1187,7 @@ def test_retry_follows_vendor_method( [ ({"connection_id": "c", "url": ""}, "url is required"), ({"connection_id": "", "url": "/x"}, "connection_id is required"), + ({"connection_id": "..", "url": "/x"}, "connection_id"), ( { "connection_id": "c", @@ -1245,3 +1249,61 @@ def test_sdk_exposes_integration_service_and_leaves_connections_alone() -> None: assert isinstance(sdk.integration_service, IntegrationService) assert isinstance(sdk.connections, ConnectionsService) assert not hasattr(sdk.connections, "execute_activity") + + +class TestTracedInputs: + def test_only_non_sensitive_arguments_are_kept(self) -> None: + from uipath.platform.integration_service._integration_service import ( + _traced_inputs, + ) + + assert _traced_inputs( + { + "self": object(), + "connection_id": "c", + "object_name": "tickets", + "method": "POST", + "body": {"password": "p"}, + "headers": {"X-Api-Key": "k"}, + "query_params": {"token": "t"}, + "files": [ExecuteFile(name="f", content=b"x")], + "file": ExecuteFile(name="f", content=b"x"), + "connector_key": "uipath-x", + "folder_key": "f1", + "max_records": 5, + } + ) == { + "connection_id": "c", + "object_name": "tickets", + "method": "POST", + "connector_key": "uipath-x", + "folder_key": "f1", + "max_records": 5, + } + + @pytest.mark.parametrize( + "url,expected", + [ + ("/v2/tickets?api_key=secret", "/v2/tickets"), + ( + "https://user:pass@api.example.com/v2/t?token=s#frag", + "https://api.example.com/v2/t", + ), + ], + ) + def test_url_keeps_no_query_or_credentials(self, url: str, expected: str) -> None: + from uipath.platform.integration_service._integration_service import ( + _traced_inputs, + ) + + assert _traced_inputs({"connection_id": "c", "url": url}) == { + "connection_id": "c", + "url": expected, + } + + def test_object_name_dots_inside_a_segment_are_allowed( + self, httpx_mock: HTTPXMock, service: IntegrationService, instance_url: str + ) -> None: + httpx_mock.add_response(url=f"{instance_url}/files/report..v1.pdf", json={}) + + assert service.execute_activity(CONNECTION_ID, "files/report..v1.pdf").ok