Adding a Nexus link converter helper method

Evanthx · Evanthx · commit 480d289a1ffd · 2026-06-01T16:09:58.000-07:00
diff --git a/temporal-sdk/src/main/java/io/temporal/internal/common/InternalUtils.java b/temporal-sdk/src/main/java/io/temporal/internal/common/InternalUtils.java
@@ -22,14 +22,11 @@
 import io.temporal.internal.nexus.OperationTokenUtil;
 import java.util.*;
 import java.util.stream.Collectors;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
 /** Utility functions shared by the implementation code. */
 public final class InternalUtils {
   public static String TEMPORAL_RESERVED_PREFIX = "__temporal_";
 
-  private static final Logger log = LoggerFactory.getLogger(InternalUtils.class);
   private static String QUERY_TYPE_STACK_TRACE = "__stack_trace";
   private static String ENHANCED_QUERY_TYPE_STACK_TRACE = "__enhanced_stack_trace";
 
@@ -94,19 +91,12 @@ public static NexusWorkflowStarter createNexusBoundStub(
             : request.getLinks().stream()
                 .map(
                     (link) -> {
-                      if (io.temporal.api.common.v1.Link.WorkflowEvent.getDescriptor()
-                          .getFullName()
-                          .equals(link.getType())) {
-                        io.temporal.api.nexus.v1.Link nexusLink =
-                            io.temporal.api.nexus.v1.Link.newBuilder()
-                                .setType(link.getType())
-                                .setUrl(link.getUri().toString())
-                                .build();
-                        return LinkConverter.nexusLinkToWorkflowEvent(nexusLink);
-                      } else {
-                        log.warn("ignoring unsupported link data type: {}", link.getType());
-                        return null;
-                      }
+                      io.temporal.api.nexus.v1.Link nexusLink =
+                          io.temporal.api.nexus.v1.Link.newBuilder()
+                              .setType(link.getType())
+                              .setUrl(link.getUri().toString())
+                              .build();
+                      return LinkConverter.nexusLinkToCommonLink(nexusLink);
                     })
                 .filter(Objects::nonNull)
                 .collect(Collectors.toList());
diff --git a/temporal-sdk/src/main/java/io/temporal/internal/common/LinkConverter.java b/temporal-sdk/src/main/java/io/temporal/internal/common/LinkConverter.java
@@ -20,6 +20,8 @@ public class LinkConverter {
   private static final Logger log = LoggerFactory.getLogger(LinkConverter.class);
 
   private static final String linkPathFormat = "temporal:///namespaces/%s/workflows/%s/%s/history";
+  private static final String linkPathNexusOperationFormat =
+      "temporal:///namespaces/%s/nexus-operations/%s/%s/details";
   private static final String linkReferenceTypeKey = "referenceType";
   private static final String linkEventIDKey = "eventID";
   private static final String linkEventTypeKey = "eventType";
@@ -30,6 +32,13 @@ public class LinkConverter {
   private static final String requestIDReferenceType =
       Link.WorkflowEvent.RequestIdReference.getDescriptor().getName();
 
+  // Fully-qualified proto descriptor names used as the `type` field on nexus.v1.Link. Match the
+  // canonical server implementation at temporalio/temporal/common/nexus/link_converter.go so links
+  // round-trip cleanly across SDKs.
+  private static final String workflowEventType = Link.WorkflowEvent.getDescriptor().getFullName();
+  private static final String nexusOperationType =
+      Link.NexusOperation.getDescriptor().getFullName();
+
   public static io.temporal.api.nexus.v1.Link workflowEventToNexusLink(Link.WorkflowEvent we) {
     try {
 
@@ -160,6 +169,118 @@ public static Link nexusLinkToWorkflowEvent(io.temporal.api.nexus.v1.Link nexusL
     return link.build();
   }
 
+  /**
+   * Encode a {@link Link.NexusOperation} (a link to a standalone Nexus operation) into the (url,
+   * type) form used on the Nexus wire. URL format matches the canonical server implementation:
+   * {@code temporal:///namespaces/{ns}/nexus-operations/{op_id}/{run_id}/details}.
+   */
+  public static io.temporal.api.nexus.v1.Link nexusOperationToNexusLink(Link.NexusOperation no) {
+    try {
+      String url =
+          String.format(
+              linkPathNexusOperationFormat,
+              URLEncoder.encode(no.getNamespace(), StandardCharsets.UTF_8.toString()),
+              URLEncoder.encode(no.getOperationId(), StandardCharsets.UTF_8.toString())
+                  .replace("+", "%20"),
+              URLEncoder.encode(no.getRunId(), StandardCharsets.UTF_8.toString()));
+      return io.temporal.api.nexus.v1.Link.newBuilder()
+          .setUrl(url)
+          .setType(nexusOperationType)
+          .build();
+    } catch (Exception e) {
+      log.error("Failed to encode NexusOperation Nexus link URL", e);
+    }
+    return null;
+  }
+
+  /**
+   * Decode a {@code nexus.v1.Link} whose {@code type} is {@code Link.NexusOperation} into a {@code
+   * common.v1.Link} carrying a {@link Link.NexusOperation} variant. The URL must match the format
+   * produced by {@link #nexusOperationToNexusLink}.
+   */
+  public static Link nexusLinkToNexusOperation(io.temporal.api.nexus.v1.Link nexusLink) {
+    try {
+      URI uri = new URI(nexusLink.getUrl());
+      if (!"temporal".equals(uri.getScheme())) {
+        log.error(
+            "Failed to parse NexusOperation Nexus link URL: invalid scheme: {}", uri.getScheme());
+        return null;
+      }
+
+      StringTokenizer st = new StringTokenizer(uri.getRawPath(), "/");
+      if (!st.hasMoreTokens() || !"namespaces".equals(st.nextToken())) {
+        log.error(
+            "Failed to parse NexusOperation Nexus link URL: invalid path: {}", uri.getRawPath());
+        return null;
+      }
+      String namespace = URLDecoder.decode(st.nextToken(), StandardCharsets.UTF_8.toString());
+      if (!st.hasMoreTokens() || !"nexus-operations".equals(st.nextToken())) {
+        log.error(
+            "Failed to parse NexusOperation Nexus link URL: invalid path: {}", uri.getRawPath());
+        return null;
+      }
+      String operationId = URLDecoder.decode(st.nextToken(), StandardCharsets.UTF_8.toString());
+      String runId = URLDecoder.decode(st.nextToken(), StandardCharsets.UTF_8.toString());
+      if (!st.hasMoreTokens() || !"details".equals(st.nextToken())) {
+        log.error(
+            "Failed to parse NexusOperation Nexus link URL: invalid path: {}", uri.getRawPath());
+        return null;
+      }
+
+      return Link.newBuilder()
+          .setNexusOperation(
+              Link.NexusOperation.newBuilder()
+                  .setNamespace(namespace)
+                  .setOperationId(operationId)
+                  .setRunId(runId))
+          .build();
+    } catch (Exception e) {
+      log.error("Failed to parse NexusOperation Nexus link URL", e);
+      return null;
+    }
+  }
+
+  /**
+   * Encode a {@code common.v1.Link} into the Nexus-wire {@code nexus.v1.Link} (url, type) form,
+   * dispatching on the link's variant. Returns {@code null} (with a warn log) for variants the SDK
+   * does not yet know how to encode ({@code Activity}, {@code BatchJob}, unset) — match the
+   * server's link-converter behavior so we stay in lockstep.
+   */
+  public static io.temporal.api.nexus.v1.Link commonLinkToNexusLink(Link commonLink) {
+    switch (commonLink.getVariantCase()) {
+      case WORKFLOW_EVENT:
+        return workflowEventToNexusLink(commonLink.getWorkflowEvent());
+      case NEXUS_OPERATION:
+        return nexusOperationToNexusLink(commonLink.getNexusOperation());
+      default:
+        log.warn(
+            "Cannot encode common.v1.Link variant {} as nexus.v1.Link: no encoder implemented",
+            commonLink.getVariantCase());
+        return null;
+    }
+  }
+
+  /**
+   * Decode a Nexus-wire {@code nexus.v1.Link} (url, type) into a {@code common.v1.Link},
+   * dispatching on the link's {@code type} field. Returns {@code null} (with a warn log) for types
+   * the SDK does not yet know how to decode.
+   */
+  public static Link nexusLinkToCommonLink(io.temporal.api.nexus.v1.Link nexusLink) {
+    String type = nexusLink.getType();
+    if (workflowEventType.equals(type)) {
+      return nexusLinkToWorkflowEvent(nexusLink);
+    }
+    if (nexusOperationType.equals(type)) {
+      return nexusLinkToNexusOperation(nexusLink);
+    }
+    log.warn(
+        "Cannot decode nexus.v1.Link of type '{}' to common.v1.Link:"
+            + " no decoder implemented (url='{}')",
+        type,
+        nexusLink.getUrl());
+    return null;
+  }
+
   private static Map<String, String> parseQueryParams(URI uri) throws UnsupportedEncodingException {
     final String query = uri.getQuery();
     if (query == null || query.isEmpty()) {
diff --git a/temporal-sdk/src/main/java/io/temporal/internal/nexus/NexusTaskHandlerImpl.java b/temporal-sdk/src/main/java/io/temporal/internal/nexus/NexusTaskHandlerImpl.java
@@ -301,20 +301,12 @@ private StartOperationResponse handleStartOperation(
                     "Invalid link URL: " + link.getUrl(),
                     e);
               }
-              // LinkConverter only returns a WorkflowEvent-shaped common.v1.Link; nexus links of
-              // other shapes (e.g. non-temporal URLs) come back null and are intentionally not
-              // forwarded onto SignalWorkflowExecutionRequest.links, which requires the
-              // WorkflowEvent variant. Log so a debugging session can see what was dropped.
-              io.temporal.api.common.v1.Link commonLink =
-                  LinkConverter.nexusLinkToWorkflowEvent(link);
+              // Convert each inbound nexus.v1.Link to common.v1.Link, dispatching on the link's
+              // type field (WorkflowEvent, NexusOperation, etc.). LinkConverter logs the warn for
+              // any unknown type and returns null.
+              io.temporal.api.common.v1.Link commonLink = LinkConverter.nexusLinkToCommonLink(link);
               if (commonLink != null) {
                 inboundCommonLinks.add(commonLink);
-              } else {
-                log.warn(
-                    "Dropping inbound Nexus link from outbound signal propagation: type='{}',"
-                        + " url='{}' (not a parseable temporal WorkflowEvent link)",
-                    link.getType(),
-                    link.getUrl());
               }
             });
     CurrentNexusOperationContext.get().setNexusOperationLinks(inboundCommonLinks);
@@ -335,11 +327,7 @@ private StartOperationResponse handleStartOperation(
         List<io.temporal.api.nexus.v1.Link> backlinks = new ArrayList<>();
         for (io.temporal.api.common.v1.Link backlink :
             CurrentNexusOperationContext.get().getBacklinks()) {
-          if (!backlink.hasWorkflowEvent()) {
-            continue;
-          }
-          io.temporal.api.nexus.v1.Link converted =
-              LinkConverter.workflowEventToNexusLink(backlink.getWorkflowEvent());
+          io.temporal.api.nexus.v1.Link converted = LinkConverter.commonLinkToNexusLink(backlink);
           if (converted != null) {
             backlinks.add(converted);
           }
diff --git a/temporal-sdk/src/test/java/io/temporal/internal/common/LinkConverterTest.java b/temporal-sdk/src/test/java/io/temporal/internal/common/LinkConverterTest.java
