Add support for operation token and deprecate operation ID (#38)

- Also fix docstring for handler error types
- Also mark all exported functions and structs in completion.go as
experimental - those need to be redone to properly rehydrate errors

See also nexus-rpc/api#16

Author: bergundy

Diff for: nexus/api.go

@@ -29,8 +29,14 @@ const (
 	headerRetryable          = "nexus-request-retryable"
 	// HeaderOperationID is the unique ID returned by the StartOperation response for async operations.
 	// Must be set on callback headers to support completing operations before the start response is received.
+	//
+	// Deprecated: Use HeaderOperationToken instead.
 	HeaderOperationID = "nexus-operation-id"
 
+	// HeaderOperationToken is the unique token returned by the StartOperation response for async operations.
+	// Must be set on callback headers to support completing operations before the start response is received.
+	HeaderOperationToken = "nexus-operation-token"
+
 	// HeaderRequestTimeout is the total time to complete a Nexus HTTP request.
 	HeaderRequestTimeout = "request-timeout"
 	// HeaderOperationTimeout is the total time to complete a Nexus operation.
@@ -184,13 +190,13 @@ const (
 	// The caller does not have permission to execute the specified operation. Clients should not retry this
 	// request unless advised otherwise.
 	HandlerErrorTypeUnauthorized HandlerErrorType = "UNAUTHORIZED"
-	// The requested resource could not be found but may be available in the future. Subsequent requests by the
-	// client are permissible but not advised.
+	// The requested resource could not be found but may be available in the future. Clients should not retry this
+	// request unless advised otherwise.
 	HandlerErrorTypeNotFound HandlerErrorType = "NOT_FOUND"
 	// Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of
 	// space. Subsequent requests by the client are permissible.
 	HandlerErrorTypeResourceExhausted HandlerErrorType = "RESOURCE_EXHAUSTED"
-	// An internal error occured. Clients should not retry this request unless advised otherwise.
+	// An internal error occured. Subsequent requests by the client are permissible.
 	HandlerErrorTypeInternal HandlerErrorType = "INTERNAL"
 	// The server either does not recognize the request method, or it lacks the ability to fulfill the request.
 	// Clients should not retry this request unless advised otherwise.
@@ -287,7 +293,11 @@ var ErrOperationStillRunning = errors.New("operation still running")
 // OperationInfo conveys information about an operation.
 type OperationInfo struct {
 	// ID of the operation.
+	//
+	// Deprecated: Use Token instead.
 	ID string `json:"id"`
+	// Token for the operation.
+	Token string `json:"token"`
 	// State of the operation.
 	State OperationState `json:"state"`
 }

Diff for: nexus/cancel_test.go

@@ -15,19 +15,19 @@ type asyncWithCancelHandler struct {
 
 func (h *asyncWithCancelHandler) StartOperation(ctx context.Context, service, operation string, input *LazyValue, options StartOperationOptions) (HandlerStartOperationResult[any], error) {
 	return &HandlerStartOperationResultAsync{
-		OperationID: "a/sync",
+		OperationToken: "a/sync",
 	}, nil
 }
 
-func (h *asyncWithCancelHandler) CancelOperation(ctx context.Context, service, operation, operationID string, options CancelOperationOptions) error {
+func (h *asyncWithCancelHandler) CancelOperation(ctx context.Context, service, operation, token string, options CancelOperationOptions) error {
 	if service != testService {
 		return HandlerErrorf(HandlerErrorTypeBadRequest, "unexpected service: %s", service)
 	}
 	if operation != "f/o/o" {
 		return HandlerErrorf(HandlerErrorTypeBadRequest, "expected operation to be 'foo', got: %s", operation)
 	}
-	if operationID != "a/sync" {
-		return HandlerErrorf(HandlerErrorTypeBadRequest, "expected operation ID to be 'async', got: %s", operationID)
+	if token != "a/sync" {
+		return HandlerErrorf(HandlerErrorTypeBadRequest, "expected operation ID to be 'async', got: %s", token)
 	}
 	if h.expectHeader && options.Header.Get("foo") != "bar" {
 		return HandlerErrorf(HandlerErrorTypeBadRequest, "invalid 'foo' request header")
@@ -69,11 +69,11 @@ type echoTimeoutAsyncWithCancelHandler struct {
 
 func (h *echoTimeoutAsyncWithCancelHandler) StartOperation(ctx context.Context, service, operation string, input *LazyValue, options StartOperationOptions) (HandlerStartOperationResult[any], error) {
 	return &HandlerStartOperationResultAsync{
-		OperationID: "timeout",
+		OperationToken: "timeout",
 	}, nil
 }
 
-func (h *echoTimeoutAsyncWithCancelHandler) CancelOperation(ctx context.Context, service, operation, operationID string, options CancelOperationOptions) error {
+func (h *echoTimeoutAsyncWithCancelHandler) CancelOperation(ctx context.Context, service, operation, token string, options CancelOperationOptions) error {
 	deadline, set := ctx.Deadline()
 	if h.expectedTimeout > 0 && !set {
 		return HandlerErrorf(HandlerErrorTypeBadRequest, "expected operation to have timeout set but context has no deadline")

Diff for: nexus/client.go

@@ -33,6 +33,12 @@ type HTTPClientOptions struct {
 	// A [FailureConverter] to convert a [Failure] instance to and from an [error]. Defaults to
 	// [DefaultFailureConverter].
 	FailureConverter FailureConverter
+	// UseOperationID instructs the client to use an older format of the protocol where operation ID is sent
+	// as part of the URL path.
+	// This flag will be removed in a future release.
+	//
+	// NOTE: Experimental
+	UseOperationID bool
 }
 
 // User-Agent header set on HTTP requests.
@@ -42,7 +48,7 @@ const headerUserAgent = "User-Agent"
 
 var errEmptyOperationName = errors.New("empty operation name")
 
-var errEmptyOperationID = errors.New("empty operation ID")
+var errEmptyOperationToken = errors.New("empty operation token")
 
 var errOperationWaitTimeout = errors.New("operation wait timeout")
 
@@ -268,13 +274,16 @@ func (c *HTTPClient) StartOperation(
 		if info.State != OperationStateRunning {
 			return nil, newUnexpectedResponseError(fmt.Sprintf("invalid operation state in response info: %q", info.State), response, body)
 		}
+		if info.Token == "" && info.ID != "" {
+			info.Token = info.ID
+		}
+		handle, err := c.NewHandle(operation, info.Token)
+		if err != nil {
+			return nil, newUnexpectedResponseError("empty operation token in response", response, body)
+		}
 		return &ClientStartOperationResult[*LazyValue]{
-			Pending: &OperationHandle[*LazyValue]{
-				Operation: operation,
-				ID:        info.ID,
-				client:    c,
-			},
-			Links: links,
+			Pending: handle,
+			Links:   links,
 		}, nil
 	case statusOperationFailed:
 		state, err := getUnsuccessfulStateFromHeader(response, body)
@@ -366,24 +375,25 @@ func (c *HTTPClient) ExecuteOperation(ctx context.Context, operation string, inp
 	return handle.GetResult(ctx, gro)
 }
 
-// NewHandle gets a handle to an asynchronous operation by name and ID.
+// NewHandle gets a handle to an asynchronous operation by name and token.
 // Does not incur a trip to the server.
-// Fails if provided an empty operation or ID.
-func (c *HTTPClient) NewHandle(operation string, operationID string) (*OperationHandle[*LazyValue], error) {
+// Fails if provided an empty operation or token.
+func (c *HTTPClient) NewHandle(operation string, token string) (*OperationHandle[*LazyValue], error) {
 	var es []error
 	if operation == "" {
 		es = append(es, errEmptyOperationName)
 	}
-	if operationID == "" {
-		es = append(es, errEmptyOperationID)
+	if token == "" {
+		es = append(es, errEmptyOperationToken)
 	}
 	if len(es) > 0 {
 		return nil, errors.Join(es...)
 	}
 	return &OperationHandle[*LazyValue]{
 		client:    c,
 		Operation: operation,
-		ID:        operationID,
+		ID:        token, // Duplicate token as ID for the deprecation period.
+		Token:     token,
 	}, nil
 }