fix account usage limit refresh handling

Author: james-6-23

api/docs/errors.md

@@ -57,6 +57,7 @@ All API errors follow this structure:
 |------|-------------|
 | `server_error` | Internal server error |
 | `service_unavailable` | Service temporarily unavailable |
+| `no_available_account` | No account is currently available for dispatch |
 | `upstream_error` | Error from upstream service |
 | `upstream_timeout` | Request to upstream timed out |
 

api/openapi.yaml

@@ -70,6 +70,8 @@ components:
                 - rate_limit_reached
                 - server_error
                 - service_unavailable
+                - no_available_account
+                - account_pool_usage_limit_reached
                 - upstream_error
                 - upstream_timeout
                 - resource_not_found

auth/session_affinity_test.go

@@ -2,6 +2,7 @@ package auth
 
 import (
 	"context"
+	"sync/atomic"
 	"testing"
 	"time"
 )
@@ -192,6 +193,52 @@ func TestWaitForSessionAvailableRespectsExcludeSet(t *testing.T) {
 	}
 }
 
+func TestWaitForSessionAvailableReturnsImmediatelyWhenNoDispatchCandidate(t *testing.T) {
+	store := &Store{
+		accounts:       []*Account{},
+		maxConcurrency: 1,
+	}
+
+	start := time.Now()
+	acc, proxyURL := store.WaitForSessionAvailable(context.Background(), "", 2*time.Second, 0, nil)
+	elapsed := time.Since(start)
+
+	if acc != nil {
+		t.Fatalf("account = %+v, want nil", acc)
+	}
+	if proxyURL != "" {
+		t.Fatalf("proxyURL = %q, want empty", proxyURL)
+	}
+	if elapsed > 150*time.Millisecond {
+		t.Fatalf("WaitForSessionAvailable took %s with no dispatch candidates; want fast failure", elapsed)
+	}
+}
+
+func TestWaitForSessionAvailableKeepsWaitingWhenCandidateIsBusy(t *testing.T) {
+	account := &Account{DBID: 1, AccessToken: "tok-1"}
+	store := &Store{
+		accounts:       []*Account{account},
+		maxConcurrency: 1,
+	}
+	atomic.StoreInt64(&account.ActiveRequests, 1)
+
+	go func() {
+		time.Sleep(75 * time.Millisecond)
+		store.Release(account)
+	}()
+
+	acc, proxyURL := store.WaitForSessionAvailable(context.Background(), "", 500*time.Millisecond, 0, nil)
+	if acc == nil {
+		t.Fatal("expected busy candidate to become available")
+	}
+	if acc.DBID != 1 {
+		t.Fatalf("account DBID = %d, want %d", acc.DBID, 1)
+	}
+	if proxyURL != "" {
+		t.Fatalf("proxyURL = %q, want empty", proxyURL)
+	}
+}
+
 func TestUnbindSessionAffinityRemovesMatchingBinding(t *testing.T) {
 	store := &Store{
 		accounts: []*Account{