From 9e9fc03a6ad6242148b61c901a69ff857fab2110 Mon Sep 17 00:00:00 2001 From: Javier Aliaga Date: Wed, 1 Jul 2026 12:27:20 +0200 Subject: [PATCH 1/2] docs: document UriUtils.encodePath for Java client service invocation newRequestBuilder no longer encodes the path; document that callers must encode segments containing URI-illegal characters (e.g. spaces) with UriUtils.encodePath, and that passing them raw throws IllegalArgumentException. Reflects dapr/java-sdk#1774. Signed-off-by: Javier Aliaga --- .../en/java-sdk-docs/java-client/_index.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/sdkdocs/java/content/en/java-sdk-docs/java-client/_index.md b/sdkdocs/java/content/en/java-sdk-docs/java-client/_index.md index 8cb265930f8..845e9c3b951 100644 --- a/sdkdocs/java/content/en/java-sdk-docs/java-client/_index.md +++ b/sdkdocs/java/content/en/java-sdk-docs/java-client/_index.md @@ -86,11 +86,26 @@ try (DaprClient client = new DaprClientBuilder().build()) { `DaprBodyPublishers.json(...)` serializes the payload using the SDK's default Jackson serializer, matching the JSON encoding the deprecated `invokeMethod` APIs applied internally. For raw payloads use any `HttpRequest.BodyPublisher` (for example `HttpRequest.BodyPublishers.ofString(...)`). +{{% alert title="Encode path segments with special characters" color="primary" %}} +`newRequestBuilder(relativePath)` resolves the path as-is — it does **not** encode it for you. If a path segment may contain characters that are illegal in a URI (for example spaces), encode it first with `io.dapr.utils.UriUtils.encodePath(...)`; passing such characters directly throws `IllegalArgumentException`. `encodePath` percent-encodes each `/`-delimited segment (preserving the separators and any leading slash) and appends the query string unchanged, mirroring the per-segment encoding the deprecated `invokeMethod` APIs applied internally. + +```java +import io.dapr.utils.UriUtils; + +// "Name With Spaces" -> "Name%20With%20Spaces" +HttpRequest request = invoker.newRequestBuilder( + UriUtils.encodePath("orders/Name With Spaces")) + .GET() + .build(); +``` +{{% /alert %}} + The table below summarizes which concerns `DaprInvokeHttpClient` handles for you (when configured with `DaprClientBuilder`) and which belong to the user: | Concern | Handled by the SDK | User's responsibility | |---|---|---| | Invoke URL (`/v1.0/invoke/{appId}/method/...`) | ✓ — resolved against the sidecar endpoint, which defaults to `http://localhost:3500` (override via `DAPR_HTTP_ENDPOINT`, or `DAPR_SIDECAR_IP` + `DAPR_HTTP_PORT`) | | +| URL path encoding | | Encode segments that may contain characters illegal in a URI (e.g. spaces) with `UriUtils.encodePath(...)`. `newRequestBuilder` resolves the path unchanged and throws `IllegalArgumentException` on illegal characters. | | `dapr-api-token` header | ✓ — attached only when configured via the `dapr.api.token` system property or `DAPR_API_TOKEN` environment variable | | | HTTP read timeout | ✓ — defaults to **60 seconds**; override via the `dapr.http.client.readTimeoutSeconds` system property or `DAPR_HTTP_CLIENT_READ_TIMEOUT_SECONDS` environment variable | | | `User-Agent: dapr-sdk-java/` header | ✓ — value tracks the SDK version automatically | | From ceef9768830dfef3f42433702570a9bd85ea4eb1 Mon Sep 17 00:00:00 2001 From: Javier Aliaga Date: Thu, 2 Jul 2026 15:34:18 +0200 Subject: [PATCH 2/2] docs: address review feedback on path-encoding section Drop the alert wrapper in favor of a plain paragraph, reword per review, and group the URL path encoding row with the user-responsibility rows. Signed-off-by: Javier Aliaga --- sdkdocs/java/content/en/java-sdk-docs/java-client/_index.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/sdkdocs/java/content/en/java-sdk-docs/java-client/_index.md b/sdkdocs/java/content/en/java-sdk-docs/java-client/_index.md index 845e9c3b951..3bd018a589a 100644 --- a/sdkdocs/java/content/en/java-sdk-docs/java-client/_index.md +++ b/sdkdocs/java/content/en/java-sdk-docs/java-client/_index.md @@ -86,8 +86,7 @@ try (DaprClient client = new DaprClientBuilder().build()) { `DaprBodyPublishers.json(...)` serializes the payload using the SDK's default Jackson serializer, matching the JSON encoding the deprecated `invokeMethod` APIs applied internally. For raw payloads use any `HttpRequest.BodyPublisher` (for example `HttpRequest.BodyPublishers.ofString(...)`). -{{% alert title="Encode path segments with special characters" color="primary" %}} -`newRequestBuilder(relativePath)` resolves the path as-is — it does **not** encode it for you. If a path segment may contain characters that are illegal in a URI (for example spaces), encode it first with `io.dapr.utils.UriUtils.encodePath(...)`; passing such characters directly throws `IllegalArgumentException`. `encodePath` percent-encodes each `/`-delimited segment (preserving the separators and any leading slash) and appends the query string unchanged, mirroring the per-segment encoding the deprecated `invokeMethod` APIs applied internally. +`newRequestBuilder(relativePath)` resolves the path as-is without encoding it for you. If a path segment may contain characters that are illegal in a URI (for example spaces), encode it first with `io.dapr.utils.UriUtils.encodePath(...)` method. Without this encoding, passing such characters directly throws an `IllegalArgumentException`. The `encodePath` method percent-encodes each forward-slash delimited segment (`/`), preserving the separators and any leading slashes, and appends the query string unchanged. This behavior mirrors the per-segment encoding that the deprecated `invokeMethod` APIs applied automatically: ```java import io.dapr.utils.UriUtils; @@ -98,17 +97,16 @@ HttpRequest request = invoker.newRequestBuilder( .GET() .build(); ``` -{{% /alert %}} The table below summarizes which concerns `DaprInvokeHttpClient` handles for you (when configured with `DaprClientBuilder`) and which belong to the user: | Concern | Handled by the SDK | User's responsibility | |---|---|---| | Invoke URL (`/v1.0/invoke/{appId}/method/...`) | ✓ — resolved against the sidecar endpoint, which defaults to `http://localhost:3500` (override via `DAPR_HTTP_ENDPOINT`, or `DAPR_SIDECAR_IP` + `DAPR_HTTP_PORT`) | | -| URL path encoding | | Encode segments that may contain characters illegal in a URI (e.g. spaces) with `UriUtils.encodePath(...)`. `newRequestBuilder` resolves the path unchanged and throws `IllegalArgumentException` on illegal characters. | | `dapr-api-token` header | ✓ — attached only when configured via the `dapr.api.token` system property or `DAPR_API_TOKEN` environment variable | | | HTTP read timeout | ✓ — defaults to **60 seconds**; override via the `dapr.http.client.readTimeoutSeconds` system property or `DAPR_HTTP_CLIENT_READ_TIMEOUT_SECONDS` environment variable | | | `User-Agent: dapr-sdk-java/` header | ✓ — value tracks the SDK version automatically | | +| URL path encoding | | Encode path segments that may contain characters illegal in a URI (e.g. spaces) with `UriUtils.encodePath(...)`. The `newRequestBuilder` method resolves the path unchanged and throws `IllegalArgumentException` on illegal characters. | | `Content-Type` header | | Set via `.header("Content-Type", "...")` | | Request body serialization | | Use `DaprBodyPublishers.json(...)` for default JSON, or any `HttpRequest.BodyPublisher` | | Response body deserialization | | Pick an `HttpResponse.BodyHandler` (`ofString`, `ofByteArray`, custom) |