feat: manual country target for runs and sessions

api/openapi.yaml

@@ -372,6 +372,7 @@ components:
         dial_timeout_ms: {type: integer, minimum: 100, maximum: 2147483647, default: 10000}
         max_samples: {type: integer, minimum: 1, maximum: 2147483647, nullable: true}
         max_duration_seconds: {type: integer, minimum: 1, maximum: 2147483647, nullable: true}
+        target_country: {type: string, pattern: '^([A-Za-z]{2})?$', nullable: true}
     Session:
       type: object
       required: [id, name, proxy_display, mode, status, cadence_seconds, probes_per_sample,
@@ -382,6 +383,7 @@ components:
         name: {type: string}
         proxy_display: {type: string}
         proxy_username: {type: string, nullable: true}
+        target_country: {type: string, nullable: true}
         mode: {type: string, enum: [sticky, pool]}
         status: {type: string, enum: [running, stopped, finished]}
         cadence_seconds: {type: integer, minimum: 1, maximum: 2147483647}
@@ -604,6 +606,7 @@ components:
         dial_timeout_ms: {type: integer, minimum: 100, maximum: 2147483647, default: 10000}
         max_samples: {type: integer, minimum: 1, maximum: 2147483647, nullable: true}
         max_duration_seconds: {type: integer, minimum: 1, maximum: 2147483647, nullable: true}
+        target_country: {type: string, pattern: '^([A-Za-z]{2})?$', nullable: true}
     RunConfig:
       type: object
       required: [max_variants_per_run]
@@ -630,6 +633,7 @@ components:
         params:
           type: object
           additionalProperties: {type: string}
+        target_country: {type: string, nullable: true}
         status: {type: string, enum: [running, stopped, finished]}
         samples_taken: {type: integer, minimum: 0}
         distinct_ips: {type: integer, minimum: 0}
@@ -646,6 +650,7 @@ components:
       required: [cell_key, params, variant_count, distinct_ips, composition]
       properties:
         cell_key: {type: string}
+        target_country: {type: string, nullable: true}
         params:
           type: object
           additionalProperties: {type: string}

internal/api/run_report.go

@@ -103,8 +103,8 @@ func mapCells(cells []variation.CellReport) []openapi.CellReport {
 		params := map[string]string{}
 		_ = json.Unmarshal(cell.Params, &params)
 		result = append(result, openapi.CellReport{
-			CellKey: cell.CellKey, Params: params, VariantCount: cell.VariantCount,
-			DistinctIps: cell.DistinctIPs, HonorRate: cell.HonorRate,
+			CellKey: cell.CellKey, Params: params, TargetCountry: optionalString(cell.TargetCountry),
+			VariantCount: cell.VariantCount, DistinctIps: cell.DistinctIPs, HonorRate: cell.HonorRate,
 			Composition: openapi.PoolComposition{
 				Mobile: cell.Composition.Mobile, Residential: cell.Composition.Residential,
 				Datacenter: cell.Composition.Datacenter, Unknown: cell.Composition.Unknown,

internal/api/runs.go

@@ -74,6 +74,10 @@ func (s *Server) CreateRun(ctx context.Context, request openapi.CreateRunRequest
 		!validOptionalPersistedInteger(body.MaxSamples) || !validOptionalPersistedInteger(body.MaxDurationSeconds) {
 		return nil, invalidRequest()
 	}
+	targetCountry, ok := normalizedTargetCountry(body.TargetCountry)
+	if !ok {
+		return nil, invalidRequest()
+	}
 
 	if s.runStore == nil || s.cipher == nil || s.store == nil || s.control == nil {
 		return nil, internalError()
@@ -142,7 +146,7 @@ func (s *Server) CreateRun(ctx context.Context, request openapi.CreateRunRequest
 			Cadence: time.Duration(body.CadenceSeconds) * time.Second, ProbesPerSample: probes,
 			ProbeTarget: probeTarget, DialTimeout: dialTimeout, MaxSamples: cloneInt(body.MaxSamples),
 			MaxDuration: secondsPointer(body.MaxDurationSeconds), Status: session.StatusRunning,
-			CreatedAt: now, StartedAt: timePointer(now),
+			TargetCountry: targetCountry, CreatedAt: now, StartedAt: timePointer(now),
 		}
 		children = append(children, variation.ChildSession{Session: child, Params: paramsJSON, CellKey: variant.CellKey})
 	}
@@ -547,7 +551,8 @@ func mapVariant(v variation.VariantSession) openapi.VariantSummary {
 	_ = json.Unmarshal(v.Params, &params)
 	return openapi.VariantSummary{
 		SessionId: v.SessionID, Name: v.Name, CellKey: v.CellKey, Params: params,
-		Status: openapi.VariantSummaryStatus(v.Status), SamplesTaken: v.Snapshot.SamplesTaken,
+		TargetCountry: optionalString(v.TargetCountry),
+		Status:        openapi.VariantSummaryStatus(v.Status), SamplesTaken: v.Snapshot.SamplesTaken,
 		DistinctIps: v.Snapshot.DistinctIPs,
 	}
 }

internal/api/runs_test.go

@@ -63,6 +63,42 @@ func TestCreateRunExpandsVariants(t *testing.T) {
 	}
 }
 
+func TestCreateRunPropagatesTargetCountryToChildren(t *testing.T) {
+	store := newMemoryStore()
+	runStore := newMemoryRunStore()
+	handler := testRunHandler(t, store, runStore, &fakeControl{})
+
+	body := `{"name":"geo","template":"socks5h://u-sid-{session}:pw@gate.example:1080","axes":{"session":{"kind":"random","count":2,"length":8}},"mode":"sticky","cadence_seconds":30,"target_country":"us"}`
+	resp := request(t, handler, http.MethodPost, "/api/runs", body)
+	if resp.Code != http.StatusCreated {
+		t.Fatalf("status = %d body=%s", resp.Code, resp.Body.String())
+	}
+	children := runStore.children[runStore.runs[0].ID]
+	if len(children) != 2 {
+		t.Fatalf("children = %d, want 2", len(children))
+	}
+	for _, child := range children {
+		if child.Session.TargetCountry != "US" {
+			t.Errorf("child target country = %q, want US (normalized uppercase)", child.Session.TargetCountry)
+		}
+	}
+}
+
+func TestCreateRunRejectsInvalidTargetCountry(t *testing.T) {
+	store := newMemoryStore()
+	runStore := newMemoryRunStore()
+	handler := testRunHandler(t, store, runStore, &fakeControl{})
+
+	body := `{"name":"geo","template":"socks5h://u:pw@gate.example:1080","axes":{},"mode":"sticky","cadence_seconds":30,"target_country":"usa"}`
+	resp := request(t, handler, http.MethodPost, "/api/runs", body)
+	if resp.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want 400; body=%s", resp.Code, resp.Body.String())
+	}
+	if len(runStore.runs) != 0 {
+		t.Fatal("run persisted despite invalid target country")
+	}
+}
+
 func TestCreateRunRejectsCapExceeded(t *testing.T) {
 	store := newMemoryStore()
 	runStore := newMemoryRunStore()