feat(golang)!: the crypto guest steps instead of blocking on transport_send, and the client drives it outside its lock

The crypto guest no longer imports transport_send. An export that can
reach ZeroKMS (se_cipher_init, se_keyset, se_term, se_encrypt_record,
se_decrypt_record, se_query_term) runs its work through the step loop:
done, it returns its output as before; waiting on a request, it returns
STATUS_NEEDS_IO, the host takes the handle and requests with se_io,
performs them and calls se_resume with the responses, or gives up with
se_abort. A step and the responses are transport frames read and written
with serde (the guest's io module). Each paused operation owns its inputs,
plaintext included, and shares the cipher through an Rc, so se_shutdown
drops every paused operation before the cipher and its wipe is the last
owner's. A second se_cipher_init is refused while one is paused.

The Go client drives the loop. It holds its lock for each step only, and
performs the requests with the lock free, so other callers run meanwhile
instead of queuing behind a round trip. Each step runs under a context that
cannot be cancelled, so the runtime never closes the module under a caller
who gave up; the context is checked between steps, and an operation whose
caller has gone is aborted in the guest. The token is fetched before each
step, outside the lock, and token_get only hands it over. Steps of
different operations may interleave; a step is read from the guest before
the lock is released.

Tests: the import surface is token_get alone; one load-keyset request is
one step and spends its handle; a call runs while another's request is in
flight; a caller that gives up mid-request gets its context's error, the
operation is gone and the client still works; an ended context never
starts a call; the token is fetched outside the lock; an init paused and
aborted leaves neither the client key nor the bearer token in guest memory
(and without the abort, the bearer remains, so the test can fail).

Refs #1064.

Author: coderdan

languages/golang/CHANGELOG.md

@@ -93,6 +93,17 @@ listed under **Breaking**. Releases are tagged `languages/golang/vX.Y.Z`.
   open. A client or profile still closes itself (`ErrState`) when the
   guest traps, or when a call runs on for 30 seconds after its context
   ended.
+- **A call no longer holds the client across a ZeroKMS round trip.** The
+  guest returns each ZeroKMS request to the client instead of performing it
+  through a blocking host import (`transport_send` is gone; the guest's one
+  import is `token_get`). The client performs the request with its lock
+  free, so other callers run meanwhile, then resumes the call. A call whose
+  context ends between those steps returns the context's error, matching
+  `ErrTransport` too, and the guest drops the paused call, wiping what it
+  held; the client stays open.
+  The token is fetched once per call, before its first step and outside
+  the lock. This is the step loop an edge runtime's host needs, where
+  `fetch` cannot block.
 - **stashgen refuses a match index on an index-only field**
   (`stash:"name,index=match"` with no `encrypt`). A match query's rows are
   checked by decrypting them, and such a field stores no ciphertext.

languages/golang/encrypt/README.md

@@ -102,7 +102,11 @@ that stores separate byte columns (`index=`) against real ZeroKMS.
 
 A `Client` is one ZeroKMS client: its client key, its default keyset, and the
 keysets it has loaded since. Make one per process and share it; it is safe
-for concurrent use.
+for concurrent use. The guest runs one call at a time, but never holds the
+client across a ZeroKMS round trip: a call that needs ZeroKMS hands its
+request to the client, which performs it with the client free for other
+callers, and then carries on. A call whose context ends while its request
+is in flight returns the context's error and leaves the client open.
 
 ```go
 client, err := encrypt.NewClient(ctx)

languages/golang/encrypt/cancel_test.go

@@ -57,7 +57,8 @@ func (s *switchable) RoundTrip(r *http.Request) (*http.Response, error) {
 
 // cancelClient is a guest not yet given a key, whose ZeroKMS requests go to
 // rt and whose token comes from token. Its se_cipher_init is the call the
-// tests drive: it makes a load-keyset request, so it reaches the network.
+// tests drive: it pauses on a load-keyset request, so it reaches the
+// network between two steps.
 func cancelClient(t *testing.T, rt http.RoundTripper, token tokenSource) *Client {
 	t.Helper()
 	tr := &transport{rt: rt, token: token}
@@ -77,7 +78,7 @@ func cipherInit(ctx context.Context, c *Client) error {
 		return err
 	}
 	defer wipe(encoded)
-	_, err = c.call(ctx, func(ctx context.Context, inst *instance) ([]byte, error) {
+	_, err = c.callKMS(ctx, func(ctx context.Context, inst *instance) ([]byte, error) {
 		return inst.call(ctx, inst.cipherInit, buf(encoded))
 	})
 	return err
@@ -96,21 +97,28 @@ func wantOpen(t *testing.T, c *Client, rt *switchable) {
 	}
 }
 
-func TestACallCancelledDuringARequestFailsOnlyItself(t *testing.T) {
+// The request runs between two steps, under the caller's context, with the
+// guest paused: cancelling it ends the call and aborts the paused
+// operation, and the client stays open.
+func TestACallCancelledBetweenStepsFailsOnlyItself(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
 	rt := &switchable{rt: func(r *http.Request) (*http.Response, error) {
+		// The caller gives up once its request is in flight.
+		cancel()
 		<-r.Context().Done()
 		return nil, r.Context().Err()
 	}}
 	c := cancelClient(t, rt, staticToken("t"))
-	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
-	defer cancel()
 	err := cipherInit(ctx, c)
-	if !errors.Is(err, context.DeadlineExceeded) || !errors.Is(err, ErrTransport) {
-		t.Fatalf("cancelled call: %v, want the deadline and ErrTransport", err)
+	if !errors.Is(err, context.Canceled) || !errors.Is(err, ErrTransport) {
+		t.Fatalf("cancelled call: %v, want context.Canceled and ErrTransport", err)
 	}
 	wantOpen(t, c, rt)
 }
 
+// The token is fetched before the operation's first step: a caller that
+// gives up waiting on it never starts the operation.
 func TestACallCancelledDuringATokenFetchFailsOnlyItself(t *testing.T) {
 	rt := &switchable{rt: unauthorized}
 	var blocking atomic.Bool
@@ -126,8 +134,8 @@ func TestACallCancelledDuringATokenFetchFailsOnlyItself(t *testing.T) {
 	ctx, cancel := context.WithCancel(context.Background())
 	time.AfterFunc(50*time.Millisecond, cancel)
 	err := cipherInit(ctx, c)
-	if !errors.Is(err, context.Canceled) || !errors.Is(err, ErrTransport) {
-		t.Fatalf("cancelled call: %v, want context.Canceled and ErrTransport", err)
+	if !errors.Is(err, context.Canceled) || errors.Is(err, ErrState) {
+		t.Fatalf("cancelled call: %v, want context.Canceled", err)
 	}
 	if n := rt.sent.Load(); n != 0 {
 		t.Fatalf("%d request(s) sent without a token", n)
@@ -175,31 +183,53 @@ func TestACallWhoseContextEndsInTheQueueNeverReachesTheGuest(t *testing.T) {
 	wantOpen(t, c, rt)
 }
 
-// The backstop: a call still running long after its caller gave up is a
+// The backstop: a step still running long after its caller gave up is a
 // guest or host function that ignores cancellation. Its state is unknown,
-// so the client closes, and says so.
-func TestACallThatRunsOnAfterItsContextEndsClosesTheClient(t *testing.T) {
-	rt := &switchable{rt: func(*http.Request) (*http.Response, error) {
-		// A RoundTripper that ignores the request's context.
-		time.Sleep(300 * time.Millisecond)
-		return unauthorized(nil)
-	}}
+// so the client closes, and says so. The step here waits out its caller's
+// context and the backstop and only then enters the guest, as a guest
+// stuck in a loop would still be running when the backstop fired.
+func TestAStepThatRunsOnAfterItsContextEndsClosesTheClient(t *testing.T) {
+	rt := &switchable{rt: unauthorized}
 	c := cancelClient(t, rt, staticToken("t"))
 	c.stuck = 20 * time.Millisecond
-	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
-	err := cipherInit(ctx, c)
+	_, err := c.call(ctx, func(run context.Context, inst *instance) ([]byte, error) {
+		cancel()
+		<-run.Done()
+		return inst.call(run, inst.targets)
+	})
 	if err == nil || !strings.Contains(err.Error(), "the client is closed") {
 		t.Fatalf("stuck call: %v, want the client closed", err)
 	}
-	if !errors.Is(err, context.DeadlineExceeded) {
-		t.Errorf("stuck call: %v, want it to match the deadline", err)
+	if !errors.Is(err, context.Canceled) {
+		t.Errorf("stuck call: %v, want it to match context.Canceled", err)
 	}
 	if err := cipherInit(context.Background(), c); !errors.Is(err, ErrState) {
 		t.Fatalf("a call after the close: %v, want ErrState", err)
 	}
 }
 
+// A request that ignores its context holds up only its own call: the guest
+// is paused while it runs, so nothing is stuck, and the client stays open.
+func TestARequestThatIgnoresItsContextLeavesTheClientOpen(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	rt := &switchable{rt: func(*http.Request) (*http.Response, error) {
+		// The caller gives up once its request is in flight, and the
+		// request runs on past the backstop regardless.
+		cancel()
+		time.Sleep(100 * time.Millisecond)
+		return unauthorized(nil)
+	}}
+	c := cancelClient(t, rt, staticToken("t"))
+	c.stuck = 20 * time.Millisecond
+	if err := cipherInit(ctx, c); !errors.Is(err, context.Canceled) || !errors.Is(err, ErrTransport) {
+		t.Fatalf("call: %v, want context.Canceled and ErrTransport", err)
+	}
+	wantOpen(t, c, rt)
+}
+
 // A call that finishes in time stops the backstop: the client stays open
 // however long after the call its context ends.
 func TestAFinishedCallStopsTheBackstop(t *testing.T) {
@@ -236,6 +266,67 @@ func TestACallThatSucceedsAfterItsContextEndsFailsWithIt(t *testing.T) {
 	wantOpen(t, c, rt)
 }
 
+// A step that pauses after its caller gave up sends no request: the
+// operation is aborted in the guest, so its handle is spent, and the call
+// fails with the context's error.
+func TestAStepThatPausesAfterItsContextEndsSendsNothing(t *testing.T) {
+	rt := &switchable{rt: unauthorized}
+	c := cancelClient(t, rt, staticToken("t"))
+	encoded, err := encodeConfig(testInit("http://zerokms.invalid"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	_, err = c.callKMS(ctx, func(run context.Context, inst *instance) ([]byte, error) {
+		cancel()
+		return inst.call(run, inst.cipherInit, buf(encoded))
+	})
+	if !errors.Is(err, context.Canceled) || !errors.Is(err, ErrTransport) {
+		t.Fatalf("call: %v, want context.Canceled and ErrTransport", err)
+	}
+	if n := rt.sent.Load(); n != 0 {
+		t.Fatalf("%d request(s) sent for a caller that had given up", n)
+	}
+	if _, err := c.inst.call(context.Background(), c.inst.abort, scalar(1)); !errors.Is(err, ErrState) {
+		t.Fatalf("the paused operation's handle: %v, want ErrState (already dropped)", err)
+	}
+	wantOpen(t, c, rt)
+}
+
+// A caller whose context ends while its resume waits for the client never
+// resumes: the paused operation is still aborted in the guest once the
+// client is free.
+func TestAResumeWhoseContextEndsInTheQueueAbortsTheOperation(t *testing.T) {
+	stub := newHeldStub(t)
+	c := stepClient(t, staticToken("stub-token"))
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	done := make(chan error, 1)
+	go func() {
+		_, err := c.callKMS(ctx, initStep(t, stub.URL))
+		done <- err
+	}()
+	waitFor(t, stub.arrived, "the init's request")
+	// Another call holds the client when the response comes back.
+	if err := c.mu.Acquire(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	close(stub.release)
+	time.Sleep(50 * time.Millisecond)
+	cancel()
+	time.Sleep(20 * time.Millisecond)
+	c.mu.Unlock()
+	if err := <-done; !errors.Is(err, context.Canceled) {
+		t.Fatalf("call: %v, want context.Canceled", err)
+	}
+	if _, err := c.inst.call(context.Background(), c.inst.abort, scalar(1)); !errors.Is(err, ErrState) {
+		t.Fatalf("the paused operation's handle: %v, want ErrState (already dropped)", err)
+	}
+	if c.closed || c.inst.module.IsClosed() {
+		t.Fatal("giving up closed the client")
+	}
+}
+
 // A closed module is ErrState, and Close still releases the runtime.
 func TestAClosedModuleIsState(t *testing.T) {
 	ctx := context.Background()
@@ -382,8 +473,8 @@ func TestACallCancelledDuringATokenExchangeLeavesTheProfileOpen(t *testing.T) {
 	hold.Store(true)
 	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
 	defer cancel()
-	if err := cipherInit(ctx, c); !errors.Is(err, context.DeadlineExceeded) || !errors.Is(err, ErrTransport) {
-		t.Fatalf("call cancelled during the exchange: %v, want the deadline and ErrTransport", err)
+	if err := cipherInit(ctx, c); !errors.Is(err, context.DeadlineExceeded) || errors.Is(err, ErrState) {
+		t.Fatalf("call cancelled during the exchange: %v, want the deadline", err)
 	}
 	hold.Store(false)
 	wantOpen(t, c, rt)