@opensoha/contracts 0.1.9 → 0.1.12

package/fixtures/openapi/MenuListEnvelope/valid/tree.json

@@ -0,0 +1,27 @@
+{
+  "items": [
+    {
+      "id": "settings",
+      "path": "/settings",
+      "labelZh": "设置中心",
+      "labelEn": "Settings",
+      "iconKey": "setting",
+      "section": "",
+      "sortOrder": 10,
+      "enabled": true,
+      "children": [
+        {
+          "id": "settings-overview",
+          "parentId": "settings",
+          "path": "/settings/overview",
+          "labelZh": "设置总览",
+          "labelEn": "Settings Overview",
+          "iconKey": "dashboard",
+          "section": "",
+          "sortOrder": 10,
+          "enabled": true
+        }
+      ]
+    }
+  ]
+}

package/fixtures/openapi/OIDCClient/invalid/missing-grant-types.json

@@ -0,0 +1,9 @@
+{
+  "id": "client-1",
+  "providerId": "provider-1",
+  "clientId": "grafana",
+  "redirectUris": ["https://grafana.example.com/login/oauth"],
+  "status": "active",
+  "createdAt": "2026-08-01T00:00:00Z",
+  "updatedAt": "2026-08-01T00:00:00Z"
+}

package/fixtures/openapi/OIDCClient/valid/current.json

@@ -0,0 +1,19 @@
+{
+  "id": "client-2",
+  "providerId": "provider-1",
+  "clientId": "tenant-app",
+  "clientType": "public",
+  "redirectUris": [],
+  "grantTypes": ["authorization_code"],
+  "redirectUriRegexes": ["https://tenant-[a-z0-9]+\\.example\\.com/callback"],
+  "postLogoutRedirectUris": ["https://app.example.com/logout/callback"],
+  "allowedScopes": ["openid", "profile"],
+  "allowedGrantTypes": ["authorization_code"],
+  "requirePkce": true,
+  "accessTokenTtlSeconds": 900,
+  "idTokenTtlSeconds": 900,
+  "refreshTokenTtlSeconds": 0,
+  "status": "active",
+  "createdAt": "2026-08-01T00:00:00Z",
+  "updatedAt": "2026-08-01T00:00:00Z"
+}

package/fixtures/openapi/OIDCClient/valid/v0.1.9.json

@@ -0,0 +1,10 @@
+{
+  "id": "client-1",
+  "providerId": "provider-1",
+  "clientId": "grafana",
+  "redirectUris": ["https://grafana.example.com/login/oauth"],
+  "grantTypes": ["authorization_code", "refresh_token"],
+  "status": "active",
+  "createdAt": "2026-08-01T00:00:00Z",
+  "updatedAt": "2026-08-01T00:00:00Z"
+}

package/fixtures/openapi/OIDCClientInput/invalid/empty-rules.json

@@ -0,0 +1,5 @@
+{
+  "clientId": "broken-client",
+  "redirectUris": [],
+  "redirectUriRegexes": []
+}

package/fixtures/openapi/OIDCClientInput/valid/regex.json

@@ -0,0 +1,4 @@
+{
+  "clientId": "tenant-app",
+  "redirectUriRegexes": ["https://tenant-[a-z0-9]+\\.example\\.com/callback"]
+}

package/fixtures/openapi/OIDCClientInput/valid/strict.json

@@ -0,0 +1,4 @@
+{
+  "clientId": "grafana",
+  "redirectUris": ["http://grafana.internal/login/oauth"]
+}

package/fixtures/openapi/OIDCClientInput/valid/v0.1.9.json

@@ -0,0 +1,7 @@
+{
+  "providerId": "provider-1",
+  "clientId": "grafana",
+  "redirectUris": ["https://grafana.example.com/login/oauth"],
+  "grantTypes": ["authorization_code", "refresh_token"],
+  "status": "active"
+}

package/fixtures/openapi/ObservabilityContext/invalid/missing-time-range.json

@@ -0,0 +1,6 @@
+{
+  "version": "v1",
+  "scope": {
+    "clusterId": "cluster-1"
+  }
+}

package/fixtures/openapi/ObservabilityContext/valid/scoped.json

@@ -0,0 +1,27 @@
+{
+  "version": "v1",
+  "scope": {
+    "workspaceId": "default",
+    "clusterId": "cluster-1",
+    "environment": "production",
+    "namespace": "payments",
+    "service": "checkout-api"
+  },
+  "resource": {
+    "kind": "service",
+    "name": "checkout-api"
+  },
+  "timeRange": {
+    "from": "2026-08-13T00:00:00Z",
+    "to": "2026-08-13T01:00:00Z",
+    "timezone": "Asia/Shanghai"
+  },
+  "filter": {
+    "text": "error",
+    "labels": {
+      "deployment.environment.name": "production"
+    },
+    "traceId": "trace-1"
+  },
+  "scopeRestricted": true
+}

package/fixtures/openapi/ObservabilityDashboardImportResultEnvelope/valid/imported.json

@@ -4,8 +4,32 @@
       "id": "dashboard:8b9f35ba-6870-4f34-b45f-6f601d8b8c35",
       "name": "Kubernetes Overview",
       "source": "grafana",
+      "sourceFormat": "classic",
       "sourceSchemaVersion": 39,
+      "rawJson": "{\"title\":\"Kubernetes Overview\"}",
       "tags": ["kubernetes"],
+      "variables": [
+        {
+          "name": "namespace",
+          "label": "Namespace",
+          "type": "custom",
+          "current": "default",
+          "options": ["default", "production"]
+        }
+      ],
+      "dataSourceBindings": [
+        {
+          "type": "prometheus",
+          "uid": "prom",
+          "dataSourceId": "prometheus-main"
+        }
+      ],
+      "importWarnings": [
+        {
+          "code": "datasource_rebound",
+          "message": "Grafana data-source prom is mapped to prometheus-main."
+        }
+      ],
       "panels": [
         {
           "id": "1",
@@ -15,7 +39,10 @@
           "targets": [
             {
               "refId": "A",
-              "expression": "sum(rate(container_cpu_usage_seconds_total[5m]))"
+              "expression": "sum(rate(container_cpu_usage_seconds_total{namespace=\"$namespace\"}[5m]))",
+              "dataSourceType": "prometheus",
+              "dataSourceUid": "prom",
+              "dataSourceId": "prometheus-main"
             }
           ],
           "queryable": true

package/fixtures/openapi/ObservabilityDashboardPanelQueryInput/invalid/missing-time-to.json

@@ -0,0 +1,6 @@
+{
+  "timeFrom": "2026-08-08T07:00:00Z",
+  "variables": {
+    "namespace": "production"
+  }
+}

package/fixtures/openapi/ObservabilityDashboardPanelQueryInput/valid/variables.json

@@ -0,0 +1,8 @@
+{
+  "timeFrom": "2026-08-08T07:00:00Z",
+  "timeTo": "2026-08-08T08:00:00Z",
+  "stepSeconds": 60,
+  "variables": {
+    "namespace": "production"
+  }
+}

package/fixtures/openapi/ObservabilityMetricCatalogEnvelope/invalid/missing-availability.json

@@ -0,0 +1,10 @@
+{
+  "items": [
+    {
+      "key": "http.server.request.duration",
+      "label": "HTTP server request duration",
+      "unit": "s",
+      "signal": "metrics"
+    }
+  ]
+}

package/fixtures/openapi/ObservabilityMetricCatalogEnvelope/valid/catalog.json

@@ -0,0 +1,13 @@
+{
+  "items": [
+    {
+      "key": "http.server.request.duration",
+      "label": "HTTP server request duration",
+      "description": "Server request duration from OpenTelemetry HTTP semantic conventions.",
+      "unit": "s",
+      "semanticConvention": "http.server.request.duration",
+      "signal": "metrics",
+      "available": true
+    }
+  ]
+}

package/fixtures/openapi/ObservabilityQueryResultMeta/invalid/missing-state.json

@@ -0,0 +1,3 @@
+{
+  "durationMs": 42
+}

package/fixtures/openapi/ObservabilityQueryResultMeta/valid/partial.json

@@ -0,0 +1,15 @@
+{
+  "state": "partial",
+  "scopeRestricted": true,
+  "observedAt": "2026-08-13T01:00:02Z",
+  "durationMs": 42,
+  "warnings": ["One data source timed out."],
+  "errors": [
+    {
+      "code": "query_timeout",
+      "message": "The secondary source did not respond before the deadline.",
+      "retryable": true,
+      "sourceId": "secondary"
+    }
+  ]
+}

package/fixtures/openapi/ObservabilityQuerySnapshot/invalid/missing-context.json

@@ -0,0 +1,5 @@
+{
+  "version": "v1",
+  "signal": "traces",
+  "queryLanguage": "trace_filter"
+}

package/fixtures/openapi/ObservabilityQuerySnapshot/valid/prometheus.json

@@ -0,0 +1,22 @@
+{
+  "version": "v1",
+  "signal": "metrics",
+  "dataSourceId": "prometheus-main",
+  "backendType": "prometheus",
+  "context": {
+    "version": "v1",
+    "scope": {
+      "workspaceId": "default",
+      "clusterId": "cluster-1",
+      "namespace": "payments",
+      "service": "checkout-api"
+    },
+    "timeRange": {
+      "from": "2026-08-13T00:00:00Z",
+      "to": "2026-08-13T01:00:00Z"
+    }
+  },
+  "queryLanguage": "promql",
+  "query": "rate(http_server_request_duration_seconds_count[5m])",
+  "createdAt": "2026-08-13T01:00:01Z"
+}

package/fixtures/openapi/ObservabilityServiceEnvelope/invalid/missing-status.json

@@ -0,0 +1,12 @@
+{
+  "data": {
+    "id": "checkout-api",
+    "name": "checkout-api",
+    "clusterIds": [],
+    "instances": [],
+    "endpoints": []
+  },
+  "meta": {
+    "state": "success"
+  }
+}

package/fixtures/openapi/ObservabilityServiceEnvelope/valid/service.json

@@ -0,0 +1,29 @@
+{
+  "data": {
+    "id": "checkout-api",
+    "name": "checkout-api",
+    "environment": "production",
+    "namespace": "payments",
+    "clusterIds": ["cluster-1"],
+    "status": "unknown",
+    "instances": [
+      {
+        "id": "checkout-api-7b8f",
+        "name": "checkout-api-7b8f",
+        "status": "unknown"
+      }
+    ],
+    "endpoints": [
+      {
+        "id": "POST /checkout",
+        "name": "/checkout",
+        "method": "POST",
+        "status": "unknown"
+      }
+    ]
+  },
+  "meta": {
+    "state": "success",
+    "observedAt": "2026-08-13T01:00:00Z"
+  }
+}

package/fixtures/openapi/ObservabilityServiceListEnvelope/invalid/missing-meta.json

@@ -0,0 +1,3 @@
+{
+  "items": []
+}

package/fixtures/openapi/ObservabilityServiceListEnvelope/valid/services.json

@@ -0,0 +1,39 @@
+{
+  "items": [
+    {
+      "id": "checkout-api",
+      "name": "checkout-api",
+      "environment": "production",
+      "namespace": "payments",
+      "clusterIds": ["cluster-1"],
+      "status": "degraded",
+      "requestRate": 125.5,
+      "errorRate": 0.023,
+      "latencyP95Ms": 412,
+      "lastSeenAt": "2026-08-13T01:00:00Z",
+      "instances": [
+        {
+          "id": "checkout-api-7b8f",
+          "name": "checkout-api-7b8f",
+          "status": "healthy",
+          "lastSeenAt": "2026-08-13T01:00:00Z"
+        }
+      ],
+      "endpoints": [
+        {
+          "id": "POST /checkout",
+          "name": "/checkout",
+          "method": "POST",
+          "status": "degraded",
+          "requestRate": 125.5,
+          "errorRate": 0.023,
+          "latencyP95Ms": 412
+        }
+      ]
+    }
+  ],
+  "meta": {
+    "state": "success",
+    "observedAt": "2026-08-13T01:00:00Z"
+  }
+}

package/fixtures/openapi/ObservabilityTopologyEnvelope/invalid/missing-edge-status.json

@@ -0,0 +1,10 @@
+{
+  "data": {
+    "nodes": [],
+    "edges": [
+      {"sourceServiceId": "a", "targetServiceId": "b"}
+    ],
+    "beta": true,
+    "meta": {"state": "success"}
+  }
+}

package/fixtures/openapi/ObservabilityTopologyEnvelope/valid/topology.json

@@ -0,0 +1,22 @@
+{
+  "data": {
+    "nodes": [
+      {"serviceId": "checkout-api", "name": "checkout-api", "status": "degraded"},
+      {"serviceId": "payment-api", "name": "payment-api", "status": "healthy"}
+    ],
+    "edges": [
+      {
+        "sourceServiceId": "checkout-api",
+        "targetServiceId": "payment-api",
+        "status": "degraded",
+        "requestRate": 88,
+        "errorRate": 0.031,
+        "latencyP95Ms": 510
+      }
+    ],
+    "beta": true,
+    "meta": {
+      "state": "success"
+    }
+  }
+}

package/fixtures/openapi/ScopeGrantEnvelope/invalid/missing-id.json

@@ -0,0 +1,13 @@
+{
+  "data": {
+    "subjectType": "team",
+    "subjectId": "platform-team",
+    "businessLineId": "",
+    "scopeType": "platform",
+    "role": "readonly",
+    "effect": "allow",
+    "enabled": true,
+    "createdAt": "2026-08-13T08:00:00Z",
+    "updatedAt": "2026-08-13T08:00:00Z"
+  }
+}

package/fixtures/openapi/ScopeGrantEnvelope/valid/platform.json

@@ -0,0 +1,15 @@
+{
+  "data": {
+    "id": "grant-123",
+    "subjectType": "team",
+    "subjectId": "platform-team",
+    "businessLineId": "",
+    "scopeType": "platform",
+    "clusterIds": ["cluster-prod"],
+    "role": "readonly",
+    "effect": "allow",
+    "enabled": true,
+    "createdAt": "2026-08-13T08:00:00Z",
+    "updatedAt": "2026-08-13T08:00:00Z"
+  }
+}

package/fixtures/openapi/ScopeGrantInput/invalid/missing-subject.json

@@ -0,0 +1,7 @@
+{
+  "subjectType": "user",
+  "scopeType": "delivery",
+  "businessLineId": "payments",
+  "role": "developer",
+  "enabled": true
+}

package/fixtures/openapi/ScopeGrantInput/valid/delivery.json

@@ -0,0 +1,11 @@
+{
+  "subjectType": "user",
+  "subjectId": "user-123",
+  "businessLineId": "payments",
+  "environmentIds": ["production"],
+  "applicationIds": ["checkout-api"],
+  "scopeType": "delivery",
+  "role": "developer",
+  "effect": "allow",
+  "enabled": true
+}

package/fixtures/openapi/ScopeGrantListEnvelope/invalid/unknown-scope.json

@@ -0,0 +1,16 @@
+{
+  "items": [
+    {
+      "id": "grant-123",
+      "subjectType": "user",
+      "subjectId": "user-123",
+      "businessLineId": "payments",
+      "scopeType": "global",
+      "role": "developer",
+      "effect": "allow",
+      "enabled": true,
+      "createdAt": "2026-08-13T08:00:00Z",
+      "updatedAt": "2026-08-13T08:00:00Z"
+    }
+  ]
+}

package/fixtures/openapi/ScopeGrantListEnvelope/valid/list.json

@@ -0,0 +1,18 @@
+{
+  "items": [
+    {
+      "id": "grant-123",
+      "subjectType": "user",
+      "subjectId": "user-123",
+      "businessLineId": "payments",
+      "environmentIds": [],
+      "applicationIds": ["checkout-api"],
+      "scopeType": "delivery",
+      "role": "developer",
+      "effect": "allow",
+      "enabled": true,
+      "createdAt": "2026-08-13T08:00:00Z",
+      "updatedAt": "2026-08-13T08:00:00Z"
+    }
+  ]
+}

package/gen/go/sohaapi/client.go

@@ -14,7 +14,7 @@ import (
 	"time"
 )
 
-const defaultUserAgent = "opensoha-contracts/0.1.9"
+const defaultUserAgent = "opensoha-contracts/0.1.12"
 
 type Client struct {
 	BaseURL    string
@@ -404,6 +404,15 @@ func (c *Client) ClaimDockerOperation(ctx context.Context, req DockerOperationCl
 	return out.Data, nil
 }
 
+func (c *Client) ExchangeDockerHostAgentEnrollment(ctx context.Context, operationID string, req DockerHostAgentEnrollmentRequest) (DockerHostAgentCredentials, error) {
+	var out DockerHostAgentCredentialsEnvelope
+	path := "/docker/agent-installations/" + url.PathEscape(strings.TrimSpace(operationID)) + "/enroll"
+	if err := c.doJSON(ctx, http.MethodPost, path, false, req, &out); err != nil {
+		return DockerHostAgentCredentials{}, err
+	}
+	return out.Data, nil
+}
+
 func (c *Client) GetDockerOperationRunnerStatus(ctx context.Context, operationID string) (DockerOperation, error) {
 	var out DockerOperationEnvelope
 	path := "/docker/operations/" + url.PathEscape(strings.TrimSpace(operationID)) + "/runner-status"

package/gen/go/sohaapi/client_test.go

@@ -40,6 +40,24 @@ func TestObservabilityCredentialKeyLegacyTypes(t *testing.T) {
 	}
 }
 
+func TestSAMLAttributeMappingLegacyConstants(t *testing.T) {
+	targets := map[SAMLAttributeMappingTarget]string{
+		Subject:      "subject",
+		Username:     "username",
+		Email:        "email",
+		DisplayName:  "displayName",
+		Role:         "role",
+		Organization: "organization",
+		Team:         "team",
+		Project:      "project",
+	}
+	for target, want := range targets {
+		if string(target) != want || !target.Valid() {
+			t.Fatalf("SAMLAttributeMappingTarget %q is not the compatible value %q", target, want)
+		}
+	}
+}
+
 func TestSystemHealthAndReadinessUsePublicRequests(t *testing.T) {
 	cases := []struct {
 		name string
@@ -125,6 +143,35 @@ func TestRunnerClaimClientsAcceptNoContent(t *testing.T) {
 	}
 }
 
+func TestExchangeDockerHostAgentEnrollmentIsPublicAndReturnsCredentials(t *testing.T) {
+	issuedAt := time.Now().UTC().Truncate(time.Second)
+	client := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		assertPublicRequest(t, r, http.MethodPost, "/api/v1/docker/agent-installations/operation-1/enroll")
+		request := decodeJSONRequestBody[DockerHostAgentEnrollmentRequest](t, r)
+		if request.AgentID != "host-1" || request.EnrollmentToken != "enrollment-secret-0123456789012345" {
+			t.Fatalf("enrollment request = %#v", request)
+		}
+		w.Header().Set("Cache-Control", "no-store")
+		w.WriteHeader(http.StatusCreated)
+		writeJSON(t, w, map[string]any{"data": map[string]any{
+			"hostId": "host-1", "operationId": "operation-1", "agentId": "host-1",
+			"agentBearerToken": "agent-secret-012345678901234567890",
+			"runtimeBearerToken": "runtime-secret-012345678901234567",
+			"issuedAt": issuedAt,
+		}})
+	})
+
+	credentials, err := client.ExchangeDockerHostAgentEnrollment(context.Background(), "operation-1", DockerHostAgentEnrollmentRequest{
+		AgentID: "host-1", EnrollmentToken: "enrollment-secret-0123456789012345",
+	})
+	if err != nil {
+		t.Fatalf("exchange enrollment: %v", err)
+	}
+	if credentials.HostID != "host-1" || credentials.OperationID != "operation-1" || credentials.RuntimeBearerToken == "" || credentials.AgentBearerToken == "" {
+		t.Fatalf("credentials = %#v", credentials)
+	}
+}
+
 func TestRedeemSecretLeaseSendsRunnerBindingHeaders(t *testing.T) {
 	client := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
 		assertCommonRequest(t, r, http.MethodPost, "/api/v1/runner/secret-leases/lease%2Fone/redeem")