Improve error model and serialization

Author: Quinn-With-Two-Ns

nexus-sdk/src/main/java/io/nexusrpc/FailureInfo.java

@@ -20,11 +20,17 @@ public static Builder newBuilder(FailureInfo failure) {
   }
 
   private final String message;
+  private final String stackTrace;
   private final Map<String, String> metadata;
   private final @Nullable String detailsJson;
 
-  private FailureInfo(String message, Map<String, String> metadata, @Nullable String detailsJson) {
+  private FailureInfo(
+      String message,
+      String stackTrace,
+      Map<String, String> metadata,
+      @Nullable String detailsJson) {
     this.message = message;
+    this.stackTrace = stackTrace;
     this.metadata = metadata;
     this.detailsJson = detailsJson;
   }
@@ -34,6 +40,11 @@ public String getMessage() {
     return message;
   }
 
+  /** Failure stack trace. */
+  public String getStackTrace() {
+    return stackTrace;
+  }
+
   /** Failure metadata. */
   public Map<String, String> getMetadata() {
     return metadata;
@@ -50,13 +61,14 @@ public boolean equals(Object o) {
     if (o == null || getClass() != o.getClass()) return false;
     FailureInfo that = (FailureInfo) o;
     return Objects.equals(message, that.message)
+        && Objects.equals(stackTrace, that.stackTrace)
         && Objects.equals(metadata, that.metadata)
         && Objects.equals(detailsJson, that.detailsJson);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(message, metadata, detailsJson);
+    return Objects.hash(message, stackTrace, metadata, detailsJson);
   }
 
   @Override
@@ -65,6 +77,9 @@ public String toString() {
         + "message='"
         + message
         + '\''
+        + ", stackTrace='"
+        + stackTrace
+        + '\''
         + ", metadata="
         + metadata
         + ", details="
@@ -75,6 +90,7 @@ public String toString() {
   /** Builder for an operation failure. */
   public static class Builder {
     private @Nullable String message;
+    private @Nullable String stackTrace;
     private final Map<String, String> metadata;
     private @Nullable String detailsJson;
 
@@ -84,6 +100,7 @@ private Builder() {
 
     private Builder(FailureInfo failure) {
       message = failure.message;
+      stackTrace = failure.stackTrace;
       metadata = new HashMap<>(failure.metadata);
       detailsJson = failure.detailsJson;
     }
@@ -111,11 +128,17 @@ public Builder setDetailsJson(@Nullable String detailsJson) {
       return this;
     }
 
+    /** Set stack trace. */
+    public Builder setStackTrace(@Nullable String stackTrace) {
+      this.stackTrace = stackTrace;
+      return this;
+    }
+
     /** Build the operation failure. */
     public FailureInfo build() {
       Objects.requireNonNull(message, "Message required");
       return new FailureInfo(
-          message, Collections.unmodifiableMap(new HashMap<>(metadata)), detailsJson);
+          message, stackTrace, Collections.unmodifiableMap(new HashMap<>(metadata)), detailsJson);
     }
   }
 }

nexus-sdk/src/main/java/io/nexusrpc/OperationException.java

@@ -1,20 +1,76 @@
 package io.nexusrpc;
 
+import org.jspecify.annotations.Nullable;
+
 /** An operation has failed or was canceled. */
 public class OperationException extends Exception {
   private final OperationState state;
 
-  private OperationException(OperationState state, Throwable cause) {
-    super(cause);
+  private OperationException(OperationState state, String message, @Nullable Throwable cause) {
+    super(message, cause);
     this.state = state;
   }
 
+  /**
+   * Create a failed operation exception with a message.
+   *
+   * @param message The failure message.
+   * @return The operation exception.
+   */
+  public static OperationException failure(String message) {
+    return new OperationException(OperationState.FAILED, message, null);
+  }
+
+  /**
+   * Create a failed operation exception with a cause.
+   *
+   * @param cause The cause of the failure.
+   * @return The operation exception.
+   */
   public static OperationException failure(Throwable cause) {
-    return new OperationException(OperationState.FAILED, cause);
+    return new OperationException(OperationState.FAILED, cause.toString(), cause);
+  }
+
+  /**
+   * Create a failed operation exception with a message and cause.
+   *
+   * @param message The failure message.
+   * @param cause The cause of the failure.
+   * @return The operation exception.
+   */
+  public static OperationException failure(String message, Throwable cause) {
+    return new OperationException(OperationState.FAILED, message, cause);
   }
 
+  /**
+   * Create a canceled operation exception with a message.
+   *
+   * @param message The cancellation message.
+   * @return The operation exception.
+   */
+  public static OperationException canceled(String message) {
+    return new OperationException(OperationState.CANCELED, message, null);
+  }
+
+  /**
+   * Create a canceled operation exception with a cause.
+   *
+   * @param cause The cause of the cancellation.
+   * @return The operation exception.
+   */
   public static OperationException canceled(Throwable cause) {
-    return new OperationException(OperationState.CANCELED, cause);
+    return new OperationException(OperationState.CANCELED, cause.toString(), cause);
+  }
+
+  /**
+   * Create a canceled operation exception with a message and cause.
+   *
+   * @param message The cancellation message.
+   * @param cause The cause of the cancellation.
+   * @return The operation exception.
+   */
+  public static OperationException canceled(String message, Throwable cause) {
+    return new OperationException(OperationState.CANCELED, message, cause);
   }
 
   public OperationState getState() {

nexus-sdk/src/main/java/io/nexusrpc/handler/HandlerException.java

@@ -1,5 +1,6 @@
 package io.nexusrpc.handler;
 
+import io.nexusrpc.FailureInfo;
 import java.util.Arrays;
 import org.jspecify.annotations.Nullable;
 
@@ -33,36 +34,160 @@ public enum RetryBehavior {
   private final String rawErrorType;
   private final ErrorType errorType;
   private final RetryBehavior retryBehavior;
+  private final FailureInfo originalFailure;
 
-  public HandlerException(ErrorType errorType, String message) {
-    this(errorType, new RuntimeException(message), RetryBehavior.UNSPECIFIED);
+  /**
+   * Create a handler exception with the given error type and cause message.
+   *
+   * @param errorType The error type.
+   * @param causeMessage The cause message.
+   * @deprecated
+   */
+  public HandlerException(ErrorType errorType, String causeMessage) {
+    this(errorType, new RuntimeException(causeMessage), RetryBehavior.UNSPECIFIED);
+  }
+
+  /**
+   * Create a handler exception with the given error type and cause message.
+   *
+   * @param errorType The error type.
+   * @param causeMessage The cause message.
+   * @param retryBehavior The retry behavior for this exception.
+   * @deprecated
+   */
+  public HandlerException(ErrorType errorType, String causeMessage, RetryBehavior retryBehavior) {
+    this(errorType, new RuntimeException(causeMessage), retryBehavior);
   }
 
-  public HandlerException(ErrorType errorType, String message, RetryBehavior retryBehavior) {
-    this(errorType, new RuntimeException(message), retryBehavior);
+  /**
+   * Create a handler exception with the given error type, message, and cause.
+   *
+   * @param errorType The error type.
+   * @param message The error message.
+   * @param cause The cause of this exception.
+   */
+  public HandlerException(ErrorType errorType, String message, @Nullable Throwable cause) {
+    this(errorType, message, cause, RetryBehavior.UNSPECIFIED);
   }
 
+  /**
+   * Create a handler exception with the given error type and cause.
+   *
+   * @param errorType The error type.
+   * @param cause The cause of this exception.
+   */
   public HandlerException(ErrorType errorType, @Nullable Throwable cause) {
     this(errorType, cause, RetryBehavior.UNSPECIFIED);
   }
 
+  /**
+   * Create a handler exception with the given error type, cause, and retry behavior.
+   *
+   * @param errorType The error type.
+   * @param cause The cause of this exception.
+   * @param retryBehavior The retry behavior for this exception.
+   */
   public HandlerException(
       ErrorType errorType, @Nullable Throwable cause, RetryBehavior retryBehavior) {
-    super(cause == null ? "handler error" : "handler error: " + cause.getMessage(), cause);
+    this(
+        errorType,
+        cause == null ? "handler error" : "handler error: " + cause.getMessage(),
+        cause,
+        retryBehavior);
+  }
+
+  /**
+   * Create a handler exception with the given error type, message, cause, and retry behavior.
+   *
+   * @param errorType The error type.
+   * @param message The error message.
+   * @param cause The cause of this exception.
+   * @param retryBehavior The retry behavior for this exception.
+   */
+  public HandlerException(
+      ErrorType errorType, String message, @Nullable Throwable cause, RetryBehavior retryBehavior) {
+    this(errorType, message, cause, retryBehavior, null);
+  }
+
+  /**
+   * Create a handler exception with the given error type, message, cause, retry behavior, and
+   * original failure.
+   *
+   * @param errorType The error type.
+   * @param message The error message.
+   * @param cause The cause of this exception.
+   * @param retryBehavior The retry behavior for this exception.
+   * @param originalFailure The original failure information if available.
+   */
+  public HandlerException(
+      ErrorType errorType,
+      String message,
+      @Nullable Throwable cause,
+      RetryBehavior retryBehavior,
+      FailureInfo originalFailure) {
+    super(message, cause);
     this.rawErrorType = errorType.name();
-    this.errorType = errorType;
+    this.errorType =
+        Arrays.stream(ErrorType.values()).anyMatch((t) -> t.name().equals(rawErrorType))
+            ? ErrorType.valueOf(rawErrorType)
+            : ErrorType.UNKNOWN;
     this.retryBehavior = retryBehavior;
+    this.originalFailure = originalFailure;
   }
 
+  /**
+   * Create a handler exception with a raw error type string, cause, and retry behavior.
+   *
+   * @param rawErrorType The raw error type string.
+   * @param cause The cause of this exception.
+   * @param retryBehavior The retry behavior for this exception.
+   */
   public HandlerException(
       String rawErrorType, @Nullable Throwable cause, RetryBehavior retryBehavior) {
-    super(cause == null ? "handler error" : "handler error: " + cause.getMessage(), cause);
+    this(
+        rawErrorType,
+        cause == null ? "handler error" : "handler error: " + cause.getMessage(),
+        cause,
+        retryBehavior);
+  }
+
+  /**
+   * Create a handler exception with a raw error type string, message, cause, and retry behavior.
+   *
+   * @param rawErrorType The raw error type string.
+   * @param message The error message.
+   * @param cause The cause of this exception.
+   * @param retryBehavior The retry behavior for this exception.
+   */
+  public HandlerException(
+      String rawErrorType, String message, @Nullable Throwable cause, RetryBehavior retryBehavior) {
+    this(rawErrorType, message, cause, retryBehavior, null);
+  }
+
+  /**
+   * Create a handler exception with a raw error type string, message, cause, retry behavior, and
+   * original failure.
+   *
+   * @param rawErrorType The raw error type string.
+   * @param message The error message.
+   * @param cause The cause of this exception.
+   * @param retryBehavior The retry behavior for this exception.
+   * @param originalFailure The original failure information if available.
+   */
+  public HandlerException(
+      String rawErrorType,
+      String message,
+      @Nullable Throwable cause,
+      RetryBehavior retryBehavior,
+      @Nullable FailureInfo originalFailure) {
+    super(message, cause);
     this.rawErrorType = rawErrorType;
     this.errorType =
         Arrays.stream(ErrorType.values()).anyMatch((t) -> t.name().equals(rawErrorType))
             ? ErrorType.valueOf(rawErrorType)
             : ErrorType.UNKNOWN;
     this.retryBehavior = retryBehavior;
+    this.originalFailure = originalFailure;
   }
 
   /**
@@ -86,6 +211,12 @@ public RetryBehavior getRetryBehavior() {
     return retryBehavior;
   }
 
+  /** Original FailureInfo if available */
+  @Nullable
+  public FailureInfo getOriginalFailure() {
+    return originalFailure;
+  }
+
   public boolean isRetryable() {
     if (retryBehavior != RetryBehavior.UNSPECIFIED) {
       return retryBehavior == RetryBehavior.RETRYABLE;