Prep for stable API (#42)

- [Remove EXPERIMENTAL warning from README and mark specific exports as
experimental](694a754)
- [Sanitize token
header](1f6799b)
- [Add AddHandlerLinks method and deprecate links on result
objects](8f448a7)

Author: bergundy

README.md

@@ -5,8 +5,6 @@
 
 Client and server package for working with the Nexus [HTTP API](https://github.com/nexus-rpc/api).
 
-**⚠️ EXPERIMENTAL ⚠️**
-
 ## What is Nexus?
 
 Nexus is a synchronous RPC protocol. Arbitrary length operations are modelled on top of a set of pre-defined synchronous

nexus/api.go

@@ -288,6 +288,8 @@ func (e *HandlerError) Unwrap() error {
 }
 
 // ErrOperationStillRunning indicates that an operation is still running while trying to get its result.
+//
+// NOTE: Experimental
 var ErrOperationStillRunning = errors.New("operation still running")
 
 // OperationInfo conveys information about an operation.

nexus/handle.go

@@ -25,6 +25,8 @@ type OperationHandle[T any] struct {
 }
 
 // GetInfo gets operation information, issuing a network request to the service handler.
+//
+// NOTE: Experimental
 func (h *OperationHandle[T]) GetInfo(ctx context.Context, options GetOperationInfoOptions) (*OperationInfo, error) {
 	var u *url.URL
 	if h.client.options.UseOperationID {
@@ -77,6 +79,8 @@ func (h *OperationHandle[T]) GetInfo(ctx context.Context, options GetOperationIn
 // context deadline to the max allowed wait period to ensure this call returns in a timely fashion.
 //
 // ⚠️ If a [LazyValue] is returned (as indicated by T), it must be consumed to free up the underlying connection.
+//
+// NOTE: Experimental
 func (h *OperationHandle[T]) GetResult(ctx context.Context, options GetOperationResultOptions) (T, error) {
 	var result T
 	var u *url.URL

nexus/operation.go

@@ -88,8 +88,12 @@ type Operation[I, O any] interface {
 	// It is the implementor's responsiblity to respect the client's wait duration and return in a timely fashion.
 	// Consider using a derived context that enforces the wait timeout when implementing this method and return
 	// [ErrOperationStillRunning] when that context expires as shown in the [Handler] example.
+	//
+	// NOTE: Experimental
 	GetResult(ctx context.Context, token string, options GetOperationResultOptions) (O, error)
 	// GetInfo handles requests to get information about an asynchronous operation.
+	//
+	// NOTE: Experimental
 	GetInfo(ctx context.Context, token string, options GetOperationInfoOptions) (*OperationInfo, error)
 	// Cancel handles requests to cancel an asynchronous operation.
 	// Cancelation in Nexus is:

nexus/server.go

@@ -13,9 +13,30 @@ import (
 	"net/url"
 	"strconv"
 	"strings"
+	"sync"
 	"time"
 )
 
+type handlerCtxKeyType struct{}
+
+var handlerCtxKey = handlerCtxKeyType{}
+
+type handlerCtx struct {
+	mu    sync.Mutex
+	links []Link
+}
+
+// AddHandlerLinks associates links with the current operation to be propagated back to the caller. This method
+// Can be called from an [Operation] handler Start method or from a [Handler] StartOperation method. The context
+// provided must be the context passed to the handler. This method may be called multiple times for a given handler,
+// each call appending additional links. Links will only be attached on successful responses.
+func AddHandlerLinks(ctx context.Context, links ...Link) {
+	hctx := ctx.Value(handlerCtxKey).(*handlerCtx)
+	hctx.mu.Lock()
+	hctx.links = append(hctx.links, links...)
+	hctx.mu.Unlock()
+}
+
 // An HandlerStartOperationResult is the return type from the [Handler] StartOperation and [Operation] Start methods. It
 // has two implementations: [HandlerStartOperationResultSync] and [HandlerStartOperationResultAsync].
 type HandlerStartOperationResult[T any] interface {
@@ -27,6 +48,8 @@ type HandlerStartOperationResultSync[T any] struct {
 	// Value is the output of the operation.
 	Value T
 	// Links to be associated with the operation.
+	//
+	// Deprecated: Use AddHandlerLinks instead.
 	Links []Link
 }
 
@@ -51,6 +74,8 @@ type HandlerStartOperationResultAsync struct {
 	// OperationToken is a unique token to identify the operation.
 	OperationToken string
 	// Links to be associated with the operation.
+	//
+	// Deprecated: Use AddHandlerLinks instead.
 	Links []Link
 }
 
@@ -115,8 +140,12 @@ type Handler interface {
 	// It is the implementor's responsiblity to respect the client's wait duration and return in a timely fashion.
 	// Consider using a derived context that enforces the wait timeout when implementing this method and return
 	// [ErrOperationStillRunning] when that context expires as shown in the example.
+	//
+	// NOTE: Experimental
 	GetOperationResult(ctx context.Context, service, operation, token string, options GetOperationResultOptions) (any, error)
 	// GetOperationInfo handles requests to get information about an asynchronous operation.
+	//
+	// NOTE: Experimental
 	GetOperationInfo(ctx context.Context, service, operation, token string, options GetOperationInfoOptions) (*OperationInfo, error)
 	// CancelOperation handles requests to cancel an asynchronous operation.
 	// Cancelation in Nexus is:
@@ -271,6 +300,8 @@ func (h *httpHandler) startOperation(service, operation string, writer http.Resp
 	}
 
 	ctx, cancel, ok := h.contextWithTimeoutFromHTTPRequest(writer, request)
+	hctx := &handlerCtx{}
+	ctx = context.WithValue(ctx, handlerCtxKey, hctx)
 	if !ok {
 		return
 	}
@@ -280,6 +311,13 @@ func (h *httpHandler) startOperation(service, operation string, writer http.Resp
 	if err != nil {
 		h.writeFailure(writer, err)
 	} else {
+		if err := addLinksToHTTPHeader(hctx.links, writer.Header()); err != nil {
+			h.logger.Error("failed to serialize links into header", "error", err)
+			// clear any previous links already written to the header
+			writer.Header().Del(headerLink)
+			writer.WriteHeader(http.StatusInternalServerError)
+			return
+		}
 		response.applyToHTTPResponse(writer, h)
 	}
 }
@@ -445,9 +483,19 @@ func (h *httpHandler) handleRequest(writer http.ResponseWriter, request *http.Re
 		h.writeFailure(writer, HandlerErrorf(HandlerErrorTypeBadRequest, "failed to parse URL path"))
 		return
 	}
+
+	// First handle StartOperation at /{service}/{operation}
+	if len(parts) == 3 && request.Method == "POST" {
+		h.startOperation(service, operation, writer, request)
+		return
+	}
+
 	token := request.Header.Get(HeaderOperationToken)
 	if token == "" {
 		token = request.URL.Query().Get("token")
+	} else {
+		// Sanitize this header as it is explicitly passed in as an argument.
+		request.Header.Del(HeaderOperationToken)
 	}
 
 	if token != "" {
@@ -479,21 +527,13 @@ func (h *httpHandler) handleRequest(writer http.ResponseWriter, request *http.Re
 			h.writeFailure(writer, HandlerErrorf(HandlerErrorTypeNotFound, "not found"))
 		}
 	} else {
-		if len(parts) > 3 {
-			token, err = url.PathUnescape(parts[3])
-			if err != nil {
-				h.writeFailure(writer, HandlerErrorf(HandlerErrorTypeBadRequest, "failed to parse URL path"))
-				return
-			}
+		token, err = url.PathUnescape(parts[3])
+		if err != nil {
+			h.writeFailure(writer, HandlerErrorf(HandlerErrorTypeBadRequest, "failed to parse URL path"))
+			return
 		}
 
 		switch len(parts) {
-		case 3: // /{service}/{operation}
-			if request.Method != "POST" {
-				h.writeFailure(writer, HandlerErrorf(HandlerErrorTypeBadRequest, "invalid request method: expected POST, got %q", request.Method))
-				return
-			}
-			h.startOperation(service, operation, writer, request)
 		case 4: // /{service}/{operation}/{operation_id}
 			if request.Method != "GET" {
 				h.writeFailure(writer, HandlerErrorf(HandlerErrorTypeBadRequest, "invalid request method: expected GET, got %q", request.Method))

nexus/start_test.go

@@ -134,7 +134,6 @@ func TestClientRequestID(t *testing.T) {
 		t.Run(c.name, func(t *testing.T) {
 			result, err := client.StartOperation(ctx, "foo", nil, c.request)
 			require.NoError(t, err)
-			require.Equal(t, c.request.Links, result.Links)
 			response := result.Successful
 			require.NotNil(t, response)
 			var responseBody []byte
@@ -190,7 +189,8 @@ func (h *echoHandler) StartOperation(ctx context.Context, service, operation str
 			Data:   data,
 		}
 	}
-	return &HandlerStartOperationResultSync[any]{Value: output, Links: options.Links}, nil
+	AddHandlerLinks(ctx, options.Links...)
+	return &HandlerStartOperationResultSync[any]{Value: output}, nil
 }
 
 func TestReaderIO(t *testing.T) {