Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
## Unreleased

* Preserve host-provided Durable Functions management URL query parameters and support null, empty, or `?`-prefixed binding queries without extra URL separators. Key-free URLs are controlled by the host's opt-in setting; existing URL authentication remains unchanged by default.
* Send a unique `hostname:pid:uuid` identifier in the `workerid` gRPC header for each worker instance, matching Python. Retain the ID across requests and reconnects while keeping IDs distinct for workers sharing a channel or builder.
* Write self-describing v2 blob payload tokens by default while retaining v1 and v2 reads from the configured storage endpoint and container. Require complete token formats for direct downloads and account for URL token length in worker action-size estimates. Upgrade readers before deploying v2 writers; changing storage locations requires explicit migration or a store configured for the original location.
* Add explicit primary-account-wide and additional-account read scopes for Azure Blob payloads while retaining configured-container access by default. Additional accounts require identity authentication and exact HTTPS account service endpoints. Preserve named and nested v1/v2 references and ignore legacy v2 URL query and fragment suffixes.
Expand Down
41 changes: 41 additions & 0 deletions azurefunctions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -228,3 +228,44 @@ Server: Kestrel
```

At this point, you now have a fully function Durable Functions for Java development environment!

## Opt-in management URL key exclusion

The examples above show the default behavior: management URLs contain the Durable
system key in `code`. The Java SDK preserves the query parameters supplied by the
Functions host; it does not remove keys or return authentication headers.

On a host extension version that supports the option, an app can exclude the key
from generated management URLs by adding the following to `host.json`:

```json
{
"extensions": {
"durableTask": {
"httpSettings": {
"excludeManagementKeyFromUrls": true
}
}
}
}
```

This setting defaults to `false`. Before enabling it, ensure every HTTP management
caller can obtain an authorized Durable system key independently and send it in
`x-functions-key` on each request. Following `Location` alone will not authenticate
key-free URLs. For example, with the key and returned status URL supplied through
environment variables:

```bash
curl -i -H "x-functions-key: ${DURABLE_SYSTEM_KEY}" "${STATUS_QUERY_GET_URI}"
```

Do not log the key, append it to URLs, or forward it to unrelated origins. The
option does not redact incoming requests or existing logs, and callers that
continue sending `code` in query strings can still expose keys in HTTP logs.

The repository's CI currently tests the default mode. An authenticated opt-in CI
leg is tracked as a follow-up in the E2E workflow until the released host extension
Comment on lines +267 to +268

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: this says the authenticated opt-in CI leg is tracked as a follow-up, but I couldn't find an issue or workflow TODO for it. Could you open an issue and link it here (or in the PR description)? Alternatively, drop the tracking reference from the user-facing README and keep it in the issue.

bundle supports this setting. Local opt-in E2E runs require authentication and the
setting enabled on the host, the same setting enabled for the test process, and
the host's independently obtained system key in `E2E_TEST_DURABLE_SYSTEM_KEY`.
Original file line number Diff line number Diff line change
Expand Up @@ -120,11 +120,11 @@ public HttpResponseMessage createCheckStatusResponse(HttpRequestMessage<?> reque
// More info: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded.
// One potential workaround is to set ASPNETCORE_FORWARDEDHEADERS_ENABLED to true.

// Construct the response as an HTTP 202 with a JSON object payload
HttpManagementPayload payload = this.getClientResponseLinks(request, instanceId);
return request.createResponseBuilder(HttpStatus.ACCEPTED)
.header("Location", this.getInstanceStatusURL(request, instanceId) + "?" + this.requiredQueryStringParameters)
.header("Location", payload.getStatusQueryGetUri())
.header("Content-Type", "application/json")
.body(this.getClientResponseLinks(request, instanceId))
.body(payload)
.build();
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@

/**
* The class that holds the webhook URLs to manage orchestration instances.
* The Functions host controls whether these URLs include a system key.
* When {@code httpSettings.excludeManagementKeyFromUrls} is enabled, callers
* must obtain a key separately and send it in the {@code x-functions-key} request header.
*/
public class HttpManagementPayload {
private final String id;
Expand All @@ -25,21 +28,28 @@ public class HttpManagementPayload {
*
* @param instanceId The ID of the orchestration instance
* @param instanceStatusURL The base webhook url of the orchestration instance
* @param requiredQueryStringParameters The query parameters to include with the http request
* @param requiredQueryStringParameters The query parameters supplied by the Functions host, preserved unchanged
*/
public HttpManagementPayload(
String instanceId,
String instanceStatusURL,
String requiredQueryStringParameters) {
String query = requiredQueryStringParameters == null ? "" : requiredQueryStringParameters;
if (query.startsWith("?")) {
query = query.substring(1);
}

String querySuffix = query.isEmpty() ? "" : "?" + query;
String reasonSuffix = "?reason={text}" + (query.isEmpty() ? "" : "&" + query);
this.id = instanceId;
this.purgeHistoryDeleteUri = instanceStatusURL + "?" + requiredQueryStringParameters;
this.restartPostUri = instanceStatusURL + "/restart?" + requiredQueryStringParameters;
this.rewindPostUri = instanceStatusURL + "/rewind?reason={text}&" + requiredQueryStringParameters;
this.sendEventPostUri = instanceStatusURL + "/raiseEvent/{eventName}?" + requiredQueryStringParameters;
this.statusQueryGetUri = instanceStatusURL + "?" + requiredQueryStringParameters;
this.terminatePostUri = instanceStatusURL + "/terminate?reason={text}&" + requiredQueryStringParameters;
this.resumePostUri = instanceStatusURL + "/resume?reason={text}&" + requiredQueryStringParameters;
this.suspendPostUri = instanceStatusURL + "/suspend?reason={text}&" + requiredQueryStringParameters;
this.purgeHistoryDeleteUri = instanceStatusURL + querySuffix;
this.restartPostUri = instanceStatusURL + "/restart" + querySuffix;
this.rewindPostUri = instanceStatusURL + "/rewind" + reasonSuffix;
this.sendEventPostUri = instanceStatusURL + "/raiseEvent/{eventName}" + querySuffix;
this.statusQueryGetUri = instanceStatusURL + querySuffix;
this.terminatePostUri = instanceStatusURL + "/terminate" + reasonSuffix;
this.resumePostUri = instanceStatusURL + "/resume" + reasonSuffix;
this.suspendPostUri = instanceStatusURL + "/suspend" + reasonSuffix;
}

/**
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

package com.microsoft.durabletask.azurefunctions;

import com.google.gson.Gson;
import com.google.gson.JsonObject;
import com.microsoft.azure.functions.HttpRequestMessage;
import com.microsoft.azure.functions.HttpResponseMessage;
import com.microsoft.azure.functions.HttpStatus;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
import org.mockito.ArgumentCaptor;

import java.net.URI;

import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.Mockito.*;

class DurableClientContextTest {
private final Gson gson = new Gson();

@ParameterizedTest
// The host owns key filtering; these query spellings verify opaque SDK pass-through.
@ValueSource(strings = {
"taskHub=hub&connection=storage&code=synthetic%2Bkey",
"CoDe=synthetic%2Bkey&site=example",
"%63ode=synthetic%2Bkey&site=example&CODE=duplicate",
"taskHub=hub&connection=storage",
""
})
void bindingQueryPassesThroughToPayloadAndLocation(String query) {
JsonObject binding = new JsonObject();
binding.addProperty("rpcBaseUrl", "http://127.0.0.1:12345");
binding.addProperty("requiredQueryStringParameters", query);
assertCheckStatusResponse(binding, query.isEmpty() ? "" : "?" + query);
}

@Test
void bindingQueriesRemainScopedToEachContext() {
DurableClientContext first = this.gson.fromJson(
"{\"requiredQueryStringParameters\":\"code=first\"}", DurableClientContext.class);
DurableClientContext second = this.gson.fromJson(
"{\"requiredQueryStringParameters\":\"\"}", DurableClientContext.class);
HttpRequestMessage<?> request = request();

assertTrue(first.createHttpManagementPayload(request, "instance").getStatusQueryGetUri().endsWith("?code=first"));
assertEquals("https://example.com/runtime/webhooks/durabletask/instances/instance",
second.createHttpManagementPayload(request, "instance").getStatusQueryGetUri());
}

private void assertCheckStatusResponse(JsonObject binding, String query) {
DurableClientContext context = this.gson.fromJson(binding, DurableClientContext.class);
HttpRequestMessage<?> request = request();
HttpResponseMessage.Builder builder = mock(HttpResponseMessage.Builder.class, RETURNS_SELF);
HttpResponseMessage response = mock(HttpResponseMessage.class);
when(request.createResponseBuilder(HttpStatus.ACCEPTED)).thenReturn(builder);
when(builder.build()).thenReturn(response);

assertSame(response, context.createCheckStatusResponse(request, "instance"));

ArgumentCaptor<Object> body = ArgumentCaptor.forClass(Object.class);
verify(builder).body(body.capture());
HttpManagementPayload payload = (HttpManagementPayload) body.getValue();
String expectedUrl = "https://example.com/runtime/webhooks/durabletask/instances/instance" + query;
assertEquals(expectedUrl, payload.getStatusQueryGetUri());
verify(builder).header("Location", expectedUrl);
JsonObject json = this.gson.toJsonTree(payload).getAsJsonObject();
assertTrue(json.entrySet().stream().allMatch(entry -> entry.getValue().isJsonPrimitive()
&& entry.getValue().getAsJsonPrimitive().isString()));
assertFalse(this.gson.toJson(payload).contains("starter-key"));
}

private static HttpRequestMessage<?> request() {
HttpRequestMessage<?> request = mock(HttpRequestMessage.class);
when(request.getUri()).thenReturn(URI.create("https://example.com/api/start?code=starter-key"));
return request;
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;

import java.util.Arrays;

import static org.junit.jupiter.api.Assertions.*;

Expand All @@ -12,7 +16,7 @@ public class HttpManagementPayloadTest {

private static final String INSTANCE_ID = "test-instance-id";
private static final String INSTANCE_STATUS_URL = "http://localhost:7071/runtime/webhooks/durabletask/instances/test-instance-id";
private static final String QUERY_STRING = "code=abc123";
private static final String QUERY_STRING = "taskHub=hub&connection=storage";

private HttpManagementPayload createPayload() {
return new HttpManagementPayload(INSTANCE_ID, INSTANCE_STATUS_URL, QUERY_STRING);
Expand Down Expand Up @@ -80,4 +84,31 @@ public void getRewindPostUri_ReturnsCorrectUrl() {
HttpManagementPayload payload = createPayload();
assertEquals(INSTANCE_STATUS_URL + "/rewind?reason={text}&" + QUERY_STRING, payload.getRewindPostUri());
}

@ParameterizedTest
@ValueSource(strings = {
"code=synthetic%2Bkey%2F%3D&site=value%2Bone",
"site=value%2Bone&CoDe=synthetic%2Bkey%2F%3D",
"%63ode=synthetic%2Bkey%2F%3D&site=value%2Bone&CODE=duplicate"
})
void hostQueryIsPreservedWithoutMovingKeysToMetadata(String query) {
HttpManagementPayload payload = new HttpManagementPayload(INSTANCE_ID, INSTANCE_STATUS_URL, query);

assertEquals(INSTANCE_STATUS_URL + "?" + query, payload.getStatusQueryGetUri());
for (String url : Arrays.asList(
payload.getStatusQueryGetUri(), payload.getSendEventPostUri(), payload.getTerminatePostUri(),
payload.getRewindPostUri(), payload.getPurgeHistoryDeleteUri(), payload.getRestartPostUri(),
payload.getSuspendPostUri(), payload.getResumePostUri())) {
assertTrue(url.endsWith(query));
}
}

@Test
void missingOrEmptyQueryDoesNotAddNullOrTrailingSeparators() {
for (String query : new String[] { null, "" }) {
HttpManagementPayload payload = new HttpManagementPayload(INSTANCE_ID, INSTANCE_STATUS_URL, query);
assertEquals(INSTANCE_STATUS_URL, payload.getStatusQueryGetUri());
assertEquals(INSTANCE_STATUS_URL + "/terminate?reason={text}", payload.getTerminatePostUri());
}
}
}
Loading
Loading