Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

Project import generated by Copybara.

Copybara Syncf4f91f68a8a5
diff --git a/libs/fleet/backend/auth/policy_test.go b/libs/fleet/backend/auth/policy_test.go
index 0a7095b71d..642fc4165c 100644
--- a/libs/fleet/backend/auth/policy_test.go
+++ b/libs/fleet/backend/auth/policy_test.go
@@ -202,12 +202,12 @@ func TestK8sAllow_RequiresSpaClient(t *testing.T) {
}
}
-func TestK8sAllow_UserKeyCannotReachCapsuleTenantLifecycle(t *testing.T) {
+func TestK8sAllow_UserKeyCannotReachCapsuleTenantAPI(t *testing.T) {
in := k8sInput("apis/capsule.clastix.io/v1beta2/tenants", false)
in["method"] = http.MethodPost
in["user"] = map[string]any{"sub": "u-1", "azp": "ukey-u-1"}
if evalAllow(t, in) {
- t.Fatal("expected user key to be denied on Capsule Tenant lifecycle")
+ t.Fatal("expected user key to be denied on the Capsule Tenant API")
}
}
diff --git a/libs/fleet/backend/config/config.go b/libs/fleet/backend/config/config.go
index 1b77aa14a3..8a77e7fd6b 100644
--- a/libs/fleet/backend/config/config.go
+++ b/libs/fleet/backend/config/config.go
@@ -6,8 +6,8 @@
// hardcoded literals, so behaviour is unchanged unless explicitly overridden.
//
// Cross-service identity prefixes (user-/oidc:) are NOT here — they live in
-// OpenFeature/SSM so backend Tenant provisioning and impersonation use the same
-// values (see package identity). The key-/ukey- client-id prefixes are
+// OpenFeature/SSM so backend impersonation and the standalone Tenant controller
+// use the same values (see package identity). The key-/ukey- client-id prefixes are
// cyclops-only, so they stay in this local config.
package config
diff --git a/libs/fleet/backend/handlers/namespaces.go b/libs/fleet/backend/handlers/namespaces.go
index 56ff1d7859..0eaa8fa2e4 100644
--- a/libs/fleet/backend/handlers/namespaces.go
+++ b/libs/fleet/backend/handlers/namespaces.go
@@ -50,52 +50,39 @@ var (
k8sClientOnce sync.Once
k8sClient *http.Client
k8sAPIServer string
- // k8sDirectAPIServer always targets the in-cluster apiserver. The
- // impersonated path may instead use Capsule Proxy for tenant filtering.
- k8sDirectAPIServer string
- k8sSAToken string
+ k8sSAToken string
)
// overrideK8sClient is used by tests to inject a fake K8s API server.
// It sets the client AND marks the Once as done so initK8sClient() is a no-op.
func overrideK8sClient(client *http.Client, apiServer, saToken string) {
- overrideK8sClientTargets(client, apiServer, apiServer, saToken)
-}
-
-func overrideK8sClientTargets(
- client *http.Client, impersonatedServer, directServer, saToken string,
-) {
k8sClientOnce.Do(func() {}) // exhaust the Once
k8sClient = client
- k8sAPIServer = impersonatedServer
- k8sDirectAPIServer = directServer
+ k8sAPIServer = apiServer
k8sSAToken = saToken
}
func initK8sClient() {
k8sClientOnce.Do(func() {
- // Direct in-cluster apiserver address. ServiceAccount-only control-plane
- // operations must not depend on Capsule Proxy behavior.
- host := os.Getenv("KUBERNETES_SERVICE_HOST")
- port := os.Getenv("KUBERNETES_SERVICE_PORT")
- if host == "" {
- host = "kubernetes.default.svc"
- }
- if port == "" {
- port = "443"
- }
- if strings.Contains(host, ":") {
- host = "[" + host + "]"
- }
- k8sDirectAPIServer = fmt.Sprintf("https://%s:%s", host, port)
-
// Capsule Proxy — filters list responses by Tenant ownership.
// Falls back to direct K8s API if CAPSULE_PROXY_ADDR is not set.
if proxyAddr := os.Getenv("CAPSULE_PROXY_ADDR"); proxyAddr != "" {
k8sAPIServer = proxyAddr
slog.Info("k8sImpersonate: using Capsule Proxy", "addr", proxyAddr)
} else {
- k8sAPIServer = k8sDirectAPIServer
+ // In-cluster: KUBERNETES_SERVICE_HOST + KUBERNETES_SERVICE_PORT
+ host := os.Getenv("KUBERNETES_SERVICE_HOST")
+ port := os.Getenv("KUBERNETES_SERVICE_PORT")
+ if host == "" {
+ host = "kubernetes.default.svc"
+ }
+ if port == "" {
+ port = "443"
+ }
+ if strings.Contains(host, ":") {
+ host = "[" + host + "]"
+ }
+ k8sAPIServer = fmt.Sprintf("https://%s:%s", host, port)
slog.Info("k8sImpersonate: using K8s API directly", "addr", k8sAPIServer)
}
@@ -147,14 +134,27 @@ func (h Handlers) k8sImpersonate(
// K8s impersonation headers — the SA needs the "impersonate" verb
// on users and groups (granted by cyclops-cs-impersonator ClusterRole).
- // Prefixes resolve from OpenFeature (see package identity) so Tenant
- // provisioning, impersonation, and apiserver flags stay aligned.
+ // Prefixes resolve from OpenFeature (see package identity) so the backend,
+ // standalone Tenant controller, and apiserver flags stay aligned.
req.Header.Set("Impersonate-User", identity.ImpersonateUser(ctx, userSub))
req.Header.Set("Impersonate-Group", identity.ImpersonateGroup(ctx, userSub))
return k8sClient.Do(req)
}
+const k8sResponseBodyLimit = 64 << 10
+
+func readBoundedK8sBody(r io.Reader) ([]byte, error) {
+ body, err := io.ReadAll(io.LimitReader(r, k8sResponseBodyLimit+1))
+ if err != nil {
+ return nil, err
+ }
+ if len(body) > k8sResponseBodyLimit {
+ return nil, fmt.Errorf("response body exceeds %d bytes", k8sResponseBodyLimit)
+ }
+ return body, nil
+}
+
// Adoption-wait tuning. Capsule normally adopts within a second or two; the
// cap just keeps a wedged Capsule controller from stalling namespace creation.
const (
@@ -229,8 +229,8 @@ func (h Handlers) ListNamespaces(w http.ResponseWriter, r *http.Request) {
// fail-closed: even if Capsule Proxy isn't filtering (e.g. while
// CapsuleConfiguration.userGroups is being reconciled, or right after a
// capsule-proxy restart with a cold cache), the apiserver only returns the
- // caller's namespaces. The personal Tenant name follows the "user-<sub>"
- // convention, and the selector is derived from the authenticated subject,
+ // caller's namespaces. The Tenant name follows the standalone controller
+ // convention "user-<sub>" and is derived from the authenticated subject,
// so a caller can never widen it to another tenant.
selector := "capsule.clastix.io/tenant=" + identity.PersonalGroup(ctx, user.ID)
path := "/api/v1/namespaces?labelSelector=" + url.QueryEscape(selector)
@@ -332,23 +332,11 @@ func (h Handlers) CreateNamespace(w http.ResponseWriter, r *http.Request) {
))
defer span.End()
- // Tenant provisioning is just-in-time so a freshly authenticated user can
- // create their first namespace without waiting for a separate reconciler.
- // This request runs as the backend ServiceAccount (not as the user) and
- // fails closed if an existing Tenant has unexpected ownership or roles.
- tenantName, err := h.ensurePersonalTenant(ctx, user.ID)
- if err != nil {
- span.RecordError(err)
- span.SetStatus(codes.Error, "personal tenant ensure failed")
- slog.Warn("namespace create: personal tenant ensure failed", "err", err)
- writeErr(w, http.StatusBadGateway, "could not ensure personal tenant")
- return
- }
-
// Build K8s Namespace object with Capsule tenant label.
// The label tells Capsule which Tenant owns this namespace.
- // The prefix resolves from OpenFeature through the same identity helper used
- // above, so the Tenant and namespace label cannot drift.
+ // Tenant name follows the standalone controller convention (user-<sub>);
+ // the shared identity helper keeps the label and controller in sync.
+ tenantName := identity.PersonalGroup(ctx, user.ID)
nsObj := map[string]interface{}{
"apiVersion": "v1",
"kind": "Namespace",
@@ -367,58 +355,34 @@ func (h Handlers) CreateNamespace(w http.ResponseWriter, r *http.Request) {
return
}
- // Capsule's admission webhook observes Tenants through an informer cache.
- // Immediately after first-use Tenant creation, that cache can briefly lag
- // both the object and its status.owners update. Retry only the exact Capsule
- // missing-Tenant 500 and non-owned-Tenant 400; every other transport or
- // admission failure is returned immediately.
- retryCtx, cancelRetry := context.WithTimeout(ctx, tenantInformerWaitTimeout)
- defer cancelRetry()
- var respStatus int
- var respBody []byte
- for {
- resp, requestErr := h.k8sImpersonate(
- retryCtx, "POST", "/api/v1/namespaces", bytes.NewReader(body), user.ID,
- )
- if requestErr != nil {
- span.RecordError(requestErr)
- span.SetStatus(codes.Error, "namespace create request failed")
- slog.Warn("namespace create: k8s request failed", "err", requestErr)
- writeErr(w, http.StatusBadGateway, "kubectl-proxy unavailable")
- return
- }
- respStatus = resp.StatusCode
- respBody, err = readBoundedK8sBody(resp.Body)
- resp.Body.Close()
- if err != nil {
- span.RecordError(err)
- span.SetStatus(codes.Error, "namespace create response failed")
- writeErr(w, http.StatusBadGateway, "bad response from k8s")
- return
- }
- if !isPersonalTenantAdmissionCacheLag(respStatus, respBody, tenantName) {
- break
- }
- select {
- case <-time.After(tenantInformerWaitStep):
- case <-retryCtx.Done():
- span.RecordError(retryCtx.Err())
- span.SetStatus(codes.Error, "namespace create cancelled during tenant readiness wait")
- writeErr(w, http.StatusBadGateway, "namespace create cancelled")
- return
- }
+ resp, err := h.k8sImpersonate(ctx, "POST", "/api/v1/namespaces", bytes.NewReader(body), user.ID)
+ if err != nil {
+ span.RecordError(err)
+ span.SetStatus(codes.Error, "namespace create request failed")
+ slog.Warn("namespace create: k8s request failed", "err", err)
+ writeErr(w, http.StatusBadGateway, "kubectl-proxy unavailable")
+ return
+ }
+ defer resp.Body.Close()
+
+ respBody, err := readBoundedK8sBody(resp.Body)
+ if err != nil {
+ span.RecordError(err)
+ span.SetStatus(codes.Error, "namespace create response failed")
+ writeErr(w, http.StatusBadGateway, "bad response from k8s")
+ return
}
- if respStatus == http.StatusConflict {
+ if resp.StatusCode == http.StatusConflict {
span.SetAttributes(attribute.Int("http.status_code", http.StatusConflict))
writeErr(w, http.StatusConflict, "namespace already exists")
return
}
- if respStatus != http.StatusCreated {
+ if resp.StatusCode != http.StatusCreated {
span.SetStatus(codes.Error, "namespace create returned non-201")
- span.SetAttributes(attribute.Int("http.status_code", respStatus))
- slog.Warn("namespace create: k8s error", "status", respStatus, "body", string(respBody))
- writeErr(w, respStatus, "k8s: "+string(respBody))
+ span.SetAttributes(attribute.Int("http.status_code", resp.StatusCode))
+ slog.Warn("namespace create: k8s error", "status", resp.StatusCode, "body", string(respBody))
+ writeErr(w, resp.StatusCode, "k8s: "+string(respBody))
return
}
diff --git a/libs/fleet/backend/handlers/namespaces_test.go b/libs/fleet/backend/handlers/namespaces_test.go
index 433118082b..6e5ff444ac 100644
--- a/libs/fleet/backend/handlers/namespaces_test.go
+++ b/libs/fleet/backend/handlers/namespaces_test.go
@@ -50,13 +50,6 @@ type fakeK8s struct {
}
func newFakeK8s(status int, respBody string) *fakeK8s {
- return newFakeK8sHandler(func(w http.ResponseWriter, _ *http.Request) {
- w.WriteHeader(status)
- _, _ = w.Write([]byte(respBody))
- })
-}
-
-func newFakeK8sHandler(handler http.HandlerFunc) *fakeK8s {
fk := &fakeK8s{}
fk.server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
fk.method = r.Method
@@ -64,7 +57,6 @@ func newFakeK8sHandler(handler http.HandlerFunc) *fakeK8s {
fk.rawQuery = r.URL.RawQuery
fk.headers = r.Header.Clone()
fk.body, _ = io.ReadAll(r.Body)
- r.Body = io.NopCloser(bytes.NewReader(fk.body))
fk.requests = append(fk.requests, recordedReq{
method: fk.method,
path: fk.path,
@@ -72,7 +64,8 @@ func newFakeK8sHandler(handler http.HandlerFunc) *fakeK8s {
headers: fk.headers,
body: fk.body,
})
- handler(w, r)
+ w.WriteHeader(status)
+ _, _ = w.Write([]byte(respBody))
}))
return fk
}
@@ -115,44 +108,8 @@ func nsCreatedResponse(name string) string {
return string(b)
}
-func existingPersonalTenantResponse(userSub string) string {
- tenant := desiredPersonalTenant(context.Background(), userSub)
- tenant.Status = &capsuleTenantStatus{Owners: []capsuleTenantOwner{
- tenant.Spec.Owners[0],
- }}
- b, _ := json.Marshal(tenant)
- return string(b)
-}
-
-func pendingPersonalTenantResponse(userSub string) string {
- b, _ := json.Marshal(desiredPersonalTenant(context.Background(), userSub))
- return string(b)
-}
-
-func newNamespaceCreateK8s(userSub string, status int, respBody string) *fakeK8s {
- tenantPath := capsuleTenantCollectionPath + "/user-" + userSub
- return newFakeK8sHandler(func(w http.ResponseWriter, r *http.Request) {
- switch {
- case r.Method == http.MethodGet && r.URL.Path == tenantPath:
- w.WriteHeader(http.StatusOK)
- _, _ = w.Write([]byte(existingPersonalTenantResponse(userSub)))
- case r.Method == http.MethodPost && r.URL.Path == "/api/v1/namespaces":
- w.WriteHeader(status)
- _, _ = w.Write([]byte(respBody))
- case r.Method == http.MethodGet && strings.HasPrefix(
- r.URL.Path, "/apis/rbac.authorization.k8s.io/v1/namespaces/",
- ):
- w.WriteHeader(http.StatusOK)
- _, _ = w.Write([]byte(`{"items":[]}`))
- default:
- w.WriteHeader(http.StatusInternalServerError)
- _, _ = w.Write([]byte(`{"error":"unexpected test request"}`))
- }
- })
-}
-
func TestCreateNamespace_ValidName(t *testing.T) {
- fk := newNamespaceCreateK8s("test-uuid", http.StatusCreated, nsCreatedResponse("my-workspace"))
+ fk := newFakeK8s(http.StatusCreated, nsCreatedResponse("my-workspace"))
defer fk.server.Close()
overrideK8sClient(fk.server.Client(), fk.server.URL, "fake-sa-token")
@@ -168,12 +125,12 @@ func TestCreateNamespace_ValidName(t *testing.T) {
t.Fatalf("status = %d, want %d; body = %s", w.Code, http.StatusCreated, w.Body.String())
}
- // The handler validates the Tenant, creates the namespace, then probes for
- // adoption; inspect the namespace POST explicitly.
- if len(fk.requests) < 3 {
- t.Fatalf("expected tenant GET + namespace POST + adoption probe GET, got %d request(s)", len(fk.requests))
+ // The handler issues the create POST followed by the adoption-wait GET
+ // probe; inspect the POST explicitly.
+ if len(fk.requests) < 2 {
+ t.Fatalf("expected create POST + adoption probe GET, got %d request(s)", len(fk.requests))
}
- post := fk.requests[1]
+ post := fk.requests[0]
// Verify impersonation headers sent to k8s proxy.
if got := post.headers.Get("Impersonate-User"); got != "oidc:test-uuid" {
@@ -197,6 +154,10 @@ func TestCreateNamespace_ValidName(t *testing.T) {
if meta["name"] != "my-workspace" {
t.Fatalf("upstream ns name = %v, want my-workspace", meta["name"])
}
+ labels, _ := meta["labels"].(map[string]any)
+ if got, want := labels["capsule.clastix.io/tenant"], "user-test-uuid"; got != want {
+ t.Fatalf("tenant label = %v, want %q", got, want)
+ }
// Verify the adoption probe: an impersonated RoleBinding LIST in the new
// namespace (only authorized once Capsule's owner RoleBindings exist —
@@ -302,7 +263,7 @@ func TestCreateNamespace_MissingUser(t *testing.T) {
}
func TestCreateNamespace_CreatesTracingSpan(t *testing.T) {
- fk := newNamespaceCreateK8s("test-uuid", http.StatusCreated, nsCreatedResponse("my-workspace"))
+ fk := newFakeK8s(http.StatusCreated, nsCreatedResponse("my-workspace"))
defer fk.server.Close()
overrideK8sClient(fk.server.Client(), fk.server.URL, "fake-sa-token")
diff --git a/libs/fleet/backend/handlers/tenants.go b/libs/fleet/backend/handlers/tenants.go
deleted file mode 100644
index b5027c30bd..0000000000
--- a/libs/fleet/backend/handlers/tenants.go
+++ /dev/null
@@ -1,331 +0,0 @@
-package handlers
-
-import (
- "bytes"
- "context"
- "encoding/json"
- "fmt"
- "io"
- "net/http"
- "net/url"
- "slices"
- "strings"
- "time"
-
- "cyclops-cs-backend/identity"
-)
-
-const (
- capsuleTenantCollectionPath = "/apis/capsule.clastix.io/v1beta2/tenants"
- personalTenantEnsureTimeout = 15 * time.Second
- personalTenantReadyWaitStep = 250 * time.Millisecond
- k8sResponseBodyLimit = 64 << 10
- tenantInformerWaitTimeout = 5 * time.Second
- tenantInformerWaitStep = 250 * time.Millisecond
-)
-
-var personalTenantClusterRoles = [...]string{
- "admin",
- "capsule-namespace-deleter",
- "capsule-tenant-cluster-resources",
-}
-
-type capsuleTenant struct {
- APIVersion string `json:"apiVersion"`
- Kind string `json:"kind"`
- Metadata capsuleTenantMetadata `json:"metadata"`
- Spec capsuleTenantSpec `json:"spec"`
- Status *capsuleTenantStatus `json:"status,omitempty"`
-}
-
-type capsuleTenantMetadata struct {
- Name string `json:"name"`
-}
-
-type capsuleTenantSpec struct {
- Owners []capsuleTenantOwner `json:"owners"`
- Permissions *capsuleTenantPermissions `json:"permissions,omitempty"`
- AdditionalRoleBindings []json.RawMessage `json:"additionalRoleBindings,omitempty"`
-}
-
-type capsuleTenantPermissions struct {
- MatchOwners []json.RawMessage `json:"matchOwners,omitempty"`
-}
-
-type capsuleTenantStatus struct {
- Owners []capsuleTenantOwner `json:"owners,omitempty"`
-}
-
-type capsuleTenantOwner struct {
- Kind string `json:"kind"`
- Name string `json:"name"`
- ClusterRoles []string `json:"clusterRoles"`
- ProxySettings []json.RawMessage `json:"proxySettings,omitempty"`
-}
-
-func desiredPersonalTenant(ctx context.Context, userSub string) capsuleTenant {
- return capsuleTenant{
- APIVersion: "capsule.clastix.io/v1beta2",
- Kind: "Tenant",
- Metadata: capsuleTenantMetadata{
- Name: identity.PersonalGroup(ctx, userSub),
- },
- Spec: capsuleTenantSpec{
- Owners: []capsuleTenantOwner{{
- Kind: "User",
- Name: identity.ImpersonateUser(ctx, userSub),
- ClusterRoles: append([]string(nil), personalTenantClusterRoles[:]...),
- }},
- },
- }
-}
-
-// k8sServiceAccount performs a direct Kubernetes apiserver request as the
-// backend's ServiceAccount. Unlike k8sImpersonate, it bypasses Capsule Proxy
-// and deliberately sends no Impersonate-* headers; personal Tenant lifecycle
-// is a backend responsibility, not a capability delegated to the caller.
-func (h Handlers) k8sServiceAccount(
- ctx context.Context, method, path string, body io.Reader,
-) (*http.Response, error) {
- if k8sClient == nil {
- initK8sClient()
- }
- if k8sClient == nil {
- return nil, fmt.Errorf("k8s client not initialised (missing SA token)")
- }
-
- if k8sDirectAPIServer == "" {
- return nil, fmt.Errorf("direct k8s apiserver is not initialised")
- }
- req, err := http.NewRequestWithContext(ctx, method, k8sDirectAPIServer+path, body)
- if err != nil {
- return nil, fmt.Errorf("build request: %w", err)
- }
- req.Header.Set("Authorization", "Bearer "+k8sSAToken)
- req.Header.Set("Content-Type", "application/json")
- return k8sClient.Do(req)
-}
-
-// ensurePersonalTenant creates the authenticated user's Capsule Tenant on
-// first use. Existing Tenants are accepted only when their single static owner
-// matches the expected user, carries every required role, and dynamic owner
-// matching is disabled. A mismatched object is never patched or replaced, so a
-// name collision fails closed instead of changing ownership.
-func (h Handlers) ensurePersonalTenant(ctx context.Context, userSub string) (string, error) {
- if userSub == "" {
- return "", fmt.Errorf("authenticated subject is empty")
- }
-
- ctx, cancel := context.WithTimeout(ctx, personalTenantEnsureTimeout)
- defer cancel()
-
- desired := desiredPersonalTenant(ctx, userSub)
- if !dnsLabel.MatchString(desired.Metadata.Name) || len(desired.Metadata.Name) > 63 {
- return "", fmt.Errorf("personal tenant name is not a DNS-1123 label")
- }
-
- exists, ready, err := h.getAndValidatePersonalTenant(ctx, desired)
- if err != nil {
- return "", err
- }
- if exists {
- if ready {
- return desired.Metadata.Name, nil
- }
- return h.waitForPersonalTenantReady(ctx, desired)
- }
-
- body, err := json.Marshal(desired)
- if err != nil {
- return "", fmt.Errorf("marshal personal tenant: %w", err)
- }
- resp, err := h.k8sServiceAccount(
- ctx, http.MethodPost, capsuleTenantCollectionPath, bytes.NewReader(body),
- )
- if err != nil {
- return "", fmt.Errorf("create personal tenant: %w", err)
- }
- if _, err := readBoundedK8sBody(resp.Body); err != nil {
- resp.Body.Close()
- return "", fmt.Errorf("create personal tenant response: %w", err)
- }
- resp.Body.Close()
-
- switch resp.StatusCode {
- case http.StatusCreated:
- // Admission webhooks can mutate a submitted object. Read the persisted
- // Tenant back and apply the same fail-closed ownership validation used
- // for pre-existing and concurrently-created objects. Capsule authorizes
- // namespace creation from status.owners, so also wait for the controller
- // to publish the exact effective owner before continuing.
- return h.waitForPersonalTenantReady(ctx, desired)
- case http.StatusConflict:
- // Another request may have created the same Tenant between our GET and
- // POST. Re-read it and verify ownership rather than trusting the 409.
- return h.waitForPersonalTenantReady(ctx, desired)
- default:
- return "", fmt.Errorf("create personal tenant: k8s returned status %d", resp.StatusCode)
- }
-}
-
-func (h Handlers) waitForPersonalTenantReady(
- ctx context.Context, desired capsuleTenant,
-) (string, error) {
- for {
- exists, ready, err := h.getAndValidatePersonalTenant(ctx, desired)
- if err != nil {
- return "", err
- }
- if !exists {
- return "", fmt.Errorf("personal tenant was not found after creation")
- }
- if ready {
- return desired.Metadata.Name, nil
- }
-
- select {
- case <-time.After(personalTenantReadyWaitStep):
- case <-ctx.Done():
- return "", fmt.Errorf("wait for personal tenant readiness: %w", ctx.Err())
- }
- }
-}
-
-func (h Handlers) getAndValidatePersonalTenant(
- ctx context.Context, desired capsuleTenant,
-) (bool, bool, error) {
- path := capsuleTenantCollectionPath + "/" + url.PathEscape(desired.Metadata.Name)
- resp, err := h.k8sServiceAccount(ctx, http.MethodGet, path, nil)
- if err != nil {
- return false, false, fmt.Errorf("get personal tenant: %w", err)
- }
- defer resp.Body.Close()
- body, err := readBoundedK8sBody(resp.Body)
- if err != nil {
- return false, false, fmt.Errorf("get personal tenant response: %w", err)
- }
-
- switch resp.StatusCode {
- case http.StatusNotFound:
- return false, false, nil
- case http.StatusOK:
- var existing capsuleTenant
- if err := json.Unmarshal(body, &existing); err != nil {
- return false, false, fmt.Errorf("decode existing personal tenant: %w", err)
- }
- if err := validatePersonalTenant(existing, desired); err != nil {
- return false, false, err
- }
- ready := existing.Status != nil && len(existing.Status.Owners) == 1
- return true, ready, nil
- default:
- return false, false, fmt.Errorf("get personal tenant: k8s returned status %d", resp.StatusCode)
- }
-}
-
-func validatePersonalTenant(existing, desired capsuleTenant) error {
- if existing.APIVersion != desired.APIVersion || existing.Kind != desired.Kind {
- return fmt.Errorf("existing personal tenant type does not match")
- }
- if existing.Metadata.Name != desired.Metadata.Name {
- return fmt.Errorf("existing personal tenant metadata does not match")
- }
- if len(existing.Spec.Owners) != 1 {
- return fmt.Errorf("existing personal tenant owner does not match")
- }
- // Capsule promotes TenantOwner resources selected by matchOwners into the
- // effective owner list. Personal Tenants must never enable that second
- // ownership path, even when their static owner looks correct.
- if existing.Spec.Permissions != nil &&
- len(existing.Spec.Permissions.MatchOwners) != 0 {
- return fmt.Errorf("existing personal tenant owner does not match")
- }
- if len(existing.Spec.AdditionalRoleBindings) != 0 {
- return fmt.Errorf("existing personal tenant role bindings do not match")
- }
- existingOwner := existing.Spec.Owners[0]
- desiredOwner := desired.Spec.Owners[0]
- if existingOwner.Kind != desiredOwner.Kind ||
- existingOwner.Name != desiredOwner.Name ||
- !sameClusterRoleSet(existingOwner.ClusterRoles, desiredOwner.ClusterRoles) ||
- len(existingOwner.ProxySettings) != 0 {
- return fmt.Errorf("existing personal tenant owner does not match")
- }
- // status.owners is what Capsule uses for authorization. It may be empty
- // immediately after creation, before the controller's first reconcile. Once
- // populated, reject stale or dynamically-added effective owners as well.
- if existing.Status != nil && len(existing.Status.Owners) != 0 {
- if len(existing.Status.Owners) != 1 {
- return fmt.Errorf("existing personal tenant effective owner does not match")
- }
- effectiveOwner := existing.Status.Owners[0]
- if effectiveOwner.Kind != desiredOwner.Kind ||
- effectiveOwner.Name != desiredOwner.Name ||
- !sameClusterRoleSet(effectiveOwner.ClusterRoles, desiredOwner.ClusterRoles) {
- return fmt.Errorf("existing personal tenant effective owner does not match")
- }
- }
- return nil
-}
-
-func sameClusterRoleSet(existing, required []string) bool {
- if len(existing) != len(required) {
- return false
- }
- for _, role := range required {
- if !slices.Contains(existing, role) {
- return false
- }
- }
- return true
-}
-
-func readBoundedK8sBody(r io.Reader) ([]byte, error) {
- body, err := io.ReadAll(io.LimitReader(r, k8sResponseBodyLimit+1))
- if err != nil {
- return nil, err
- }
- if len(body) > k8sResponseBodyLimit {
- return nil, fmt.Errorf("response body exceeds %d bytes", k8sResponseBodyLimit)
- }
- return body, nil
-}
-
-// isPersonalTenantAdmissionCacheLag identifies the two retryable namespace
-// admission failures after a Tenant is first created. Capsule's webhook reads
-// both the Tenant and status.owners from its controller-runtime cache, which
-// can briefly lag the successful direct-apiserver reads above. Match only the
-// exact Capsule errors so unrelated admission failures return immediately.
-func isPersonalTenantAdmissionCacheLag(statusCode int, body []byte, tenantName string) bool {
- var status struct {
- Kind string `json:"kind"`
- Status string `json:"status"`
- Message string `json:"message"`
- Code int `json:"code"`
- }
- if json.Unmarshal(body, &status) != nil ||
- status.Kind != "Status" ||
- status.Status != "Failure" ||
- status.Code != statusCode {
- return false
- }
- if statusCode == http.StatusBadRequest {
- return strings.Contains(
- status.Message,
- "can not assign the desired namespace to a non-owned Tenant",
- )
- }
- if statusCode != http.StatusInternalServerError {
- return false
- }
- for _, resource := range []string{
- "Tenant.capsule.clastix.io",
- "tenants.capsule.clastix.io",
- } {
- want := fmt.Sprintf("%s %q not found", resource, tenantName)
- if strings.Contains(status.Message, want) {
- return true
- }
- }
- return false
-}
diff --git a/libs/fleet/backend/handlers/tenants_test.go b/libs/fleet/backend/handlers/tenants_test.go
deleted file mode 100644
index 9adcbaee99..0000000000
--- a/libs/fleet/backend/handlers/tenants_test.go
+++ /dev/null
@@ -1,621 +0,0 @@
-package handlers
-
-import (
- "context"
- "encoding/json"
- "net/http"
- "net/http/httptest"
- "reflect"
- "strings"
- "sync/atomic"
- "testing"
- "time"
-
- "cyclops-cs-backend/auth"
-)
-
-type roundTripperFunc func(*http.Request) (*http.Response, error)
-
-func (f roundTripperFunc) RoundTrip(r *http.Request) (*http.Response, error) {
- return f(r)
-}
-
-func TestCreateNamespace_FirstUseCreatesPersonalTenant(t *testing.T) {
- const userSub = "test-uuid"
- desired := desiredPersonalTenant(context.Background(), userSub)
- tenantPath := capsuleTenantCollectionPath + "/" + desired.Metadata.Name
- tenantGetCount := 0
- namespacePostCount := 0
-
- fk := newFakeK8sHandler(func(w http.ResponseWriter, r *http.Request) {
- switch {
- case r.Method == http.MethodGet && r.URL.Path == tenantPath:
- tenantGetCount++
- if tenantGetCount == 1 {
- w.WriteHeader(http.StatusNotFound)
- _, _ = w.Write([]byte(`{"kind":"Status","reason":"NotFound"}`))
- return
- }
- if tenantGetCount == 2 {
- w.WriteHeader(http.StatusOK)
- _, _ = w.Write([]byte(pendingPersonalTenantResponse(userSub)))
- return
- }
- w.WriteHeader(http.StatusOK)
- _, _ = w.Write([]byte(existingPersonalTenantResponse(userSub)))
- case r.Method == http.MethodPost && r.URL.Path == capsuleTenantCollectionPath:
- w.WriteHeader(http.StatusCreated)
- _, _ = w.Write([]byte(existingPersonalTenantResponse(userSub)))
- case r.Method == http.MethodPost && r.URL.Path == "/api/v1/namespaces":
- namespacePostCount++
- if namespacePostCount == 1 {
- status, _ := json.Marshal(map[string]any{
- "kind": "Status",
- "status": "Failure",
- "code": http.StatusBadRequest,
- "message": "admission webhook denied the request: can not assign the desired namespace to a non-owned Tenant",
- })
- w.WriteHeader(http.StatusBadRequest)
- _, _ = w.Write(status)
- return
- }
- if namespacePostCount == 2 {
- status, _ := json.Marshal(map[string]any{
- "kind": "Status",
- "status": "Failure",
- "code": http.StatusInternalServerError,
- "message": "admission failed: Tenant.capsule.clastix.io \"" +
- desired.Metadata.Name + "\" not found",
- })
- w.WriteHeader(http.StatusInternalServerError)
- _, _ = w.Write(status)
- return
- }
- w.WriteHeader(http.StatusCreated)
- _, _ = w.Write([]byte(nsCreatedResponse("my-workspace")))
- case r.Method == http.MethodGet && strings.HasPrefix(
- r.URL.Path, "/apis/rbac.authorization.k8s.io/v1/namespaces/",
- ):
- w.WriteHeader(http.StatusOK)
- _, _ = w.Write([]byte(`{"items":[]}`))
- default:
- t.Errorf("unexpected k8s request: %s %s", r.Method, r.URL.Path)
- w.WriteHeader(http.StatusInternalServerError)
- }
- })
- defer fk.server.Close()
- overrideK8sClient(fk.server.Client(), fk.server.URL, "fake-sa-token")
-
- h := Handlers{}
- r := httptest.NewRequest(
- http.MethodPost, "/api/namespaces", strings.NewReader(`{"name":"my-workspace"}`),
- )
- r = withUser(r, &auth.User{ID: userSub})
- w := httptest.NewRecorder()
-
- h.CreateNamespace(w, r)
-
- if w.Code != http.StatusCreated {
- t.Fatalf("status = %d, want %d; body = %s", w.Code, http.StatusCreated, w.Body.String())
- }
- if len(fk.requests) != 8 {
- t.Fatalf("request count = %d, want 8", len(fk.requests))
- }
- wantSequence := []struct {
- method string
- path string
- }{
- {http.MethodGet, tenantPath},
- {http.MethodPost, capsuleTenantCollectionPath},
- {http.MethodGet, tenantPath},
- {http.MethodGet, tenantPath},
- {http.MethodPost, "/api/v1/namespaces"},
- {http.MethodPost, "/api/v1/namespaces"},
- {http.MethodPost, "/api/v1/namespaces"},
- {http.MethodGet, "/apis/rbac.authorization.k8s.io/v1/namespaces/my-workspace/rolebindings"},
- }
- for i, want := range wantSequence {
- got := fk.requests[i]
- if got.method != want.method || got.path != want.path {
- t.Fatalf("request[%d] = %s %s, want %s %s", i, got.method, got.path, want.method, want.path)
- }
- }
-
- for i := 0; i < 4; i++ {
- request := fk.requests[i]
- if got := request.headers.Get("Authorization"); got != "Bearer fake-sa-token" {
- t.Fatalf("tenant request[%d] Authorization = %q", i, got)
- }
- if got := request.headers.Get("Impersonate-User"); got != "" {
- t.Fatalf("tenant request[%d] Impersonate-User = %q, want empty", i, got)
- }
- if got := request.headers.Get("Impersonate-Group"); got != "" {
- t.Fatalf("tenant request[%d] Impersonate-Group = %q, want empty", i, got)
- }
- }
-
- var created capsuleTenant
- if err := json.Unmarshal(fk.requests[1].body, &created); err != nil {
- t.Fatalf("decode Tenant create body: %v", err)
- }
- if created.APIVersion != "capsule.clastix.io/v1beta2" || created.Kind != "Tenant" {
- t.Fatalf("unexpected Tenant type: %s %s", created.APIVersion, created.Kind)
- }
- if err := validatePersonalTenant(created, desired); err != nil {
- t.Fatalf("Tenant create body mismatch: %v; body = %s", err, fk.requests[1].body)
- }
- wantRoles := []string{
- "admin",
- "capsule-namespace-deleter",
- "capsule-tenant-cluster-resources",
- }
- if got := created.Spec.Owners[0].ClusterRoles; !reflect.DeepEqual(got, wantRoles) {
- t.Fatalf("Tenant clusterRoles = %#v, want literal roles %#v", got, wantRoles)
- }
-
- namespaceRequest := fk.requests[6]
- if got := namespaceRequest.headers.Get("Impersonate-User"); got != "oidc:"+userSub {
- t.Fatalf("namespace Impersonate-User = %q, want %q", got, "oidc:"+userSub)
- }
-}
-
-func TestValidatePersonalTenant_RejectsRoleAndOwnerDrift(t *testing.T) {
- desired := desiredPersonalTenant(context.Background(), "test-uuid")
- tests := []struct {
- name string
- mutate func(*capsuleTenant)
- }{
- {
- name: "extra role",
- mutate: func(tenant *capsuleTenant) {
- tenant.Spec.Owners[0].ClusterRoles = append(
- tenant.Spec.Owners[0].ClusterRoles, "cluster-admin",
- )
- },
- },
- {
- name: "missing role",
- mutate: func(tenant *capsuleTenant) {
- tenant.Spec.Owners[0].ClusterRoles = tenant.Spec.Owners[0].ClusterRoles[:2]
- },
- },
- {
- name: "substituted role",
- mutate: func(tenant *capsuleTenant) {
- tenant.Spec.Owners[0].ClusterRoles[1] = "cluster-admin"
- },
- },
- {
- name: "duplicate role",
- mutate: func(tenant *capsuleTenant) {
- tenant.Spec.Owners[0].ClusterRoles[1] = "admin"
- },
- },
- {
- name: "extra owner",
- mutate: func(tenant *capsuleTenant) {
- tenant.Spec.Owners = append(tenant.Spec.Owners, tenant.Spec.Owners[0])
- },
- },
- {
- name: "dynamic owner selector",
- mutate: func(tenant *capsuleTenant) {
- tenant.Spec.Permissions = &capsuleTenantPermissions{
- MatchOwners: []json.RawMessage{json.RawMessage(`{"matchLabels":{"team":"all"}}`)},
- }
- },
- },
- {
- name: "additional role binding",
- mutate: func(tenant *capsuleTenant) {
- tenant.Spec.AdditionalRoleBindings = []json.RawMessage{
- json.RawMessage(`{"clusterRoleName":"cluster-admin"}`),
- }
- },
- },
- {
- name: "owner proxy settings",
- mutate: func(tenant *capsuleTenant) {
- tenant.Spec.Owners[0].ProxySettings = []json.RawMessage{
- json.RawMessage(`{"kind":"Nodes","operations":["List"]}`),
- }
- },
- },
- {
- name: "extra effective owner",
- mutate: func(tenant *capsuleTenant) {
- tenant.Status = &capsuleTenantStatus{Owners: []capsuleTenantOwner{
- tenant.Spec.Owners[0],
- {Kind: "Group", Name: "oidc:someone-else"},
- }}
- },
- },
- {
- name: "wrong effective owner",
- mutate: func(tenant *capsuleTenant) {
- tenant.Status = &capsuleTenantStatus{Owners: []capsuleTenantOwner{{
- Kind: "User",
- Name: "oidc:someone-else",
- ClusterRoles: append([]string(nil), personalTenantClusterRoles[:]...),
- }}}
- },
- },
- }
- for _, tc := range tests {
- t.Run(tc.name, func(t *testing.T) {
- existing := desiredPersonalTenant(context.Background(), "test-uuid")
- tc.mutate(&existing)
- if err := validatePersonalTenant(existing, desired); err == nil {
- t.Fatal("validatePersonalTenant() accepted mismatched Tenant")
- }
- })
- }
-}
-
-func TestValidatePersonalTenant_RejectsPrivilegeFieldsFromKubernetesJSON(t *testing.T) {
- desired := desiredPersonalTenant(context.Background(), "test-uuid")
- const base = `{
- "apiVersion":"capsule.clastix.io/v1beta2",
- "kind":"Tenant",
- "metadata":{"name":"user-test-uuid"},
- "spec":{
- "owners":[{
- "kind":"User",
- "name":"oidc:test-uuid",
- "clusterRoles":["admin","capsule-namespace-deleter","capsule-tenant-cluster-resources"]
- }]
- PRIVILEGE_FIELD
- }
- }`
- fields := []string{
- `,"permissions":{"matchOwners":[{}]}`,
- `,"additionalRoleBindings":[{"clusterRoleName":"cluster-admin"}]`,
- }
- for _, field := range fields {
- var existing capsuleTenant
- raw := strings.Replace(base, "PRIVILEGE_FIELD", field, 1)
- if err := json.Unmarshal([]byte(raw), &existing); err != nil {
- t.Fatalf("decode test Tenant: %v", err)
- }
- if err := validatePersonalTenant(existing, desired); err == nil {
- t.Fatalf("accepted Kubernetes Tenant privilege field %s", field)
- }
- }
-}
-
-func TestValidatePersonalTenant_AcceptsEquivalentRoleOrderAndEmptyDynamicOwners(t *testing.T) {
- desired := desiredPersonalTenant(context.Background(), "test-uuid")
- existing := desiredPersonalTenant(context.Background(), "test-uuid")
- existing.Spec.Owners[0].ClusterRoles = []string{
- "capsule-tenant-cluster-resources",
- "admin",
- "capsule-namespace-deleter",
- }
- existing.Spec.Permissions = &capsuleTenantPermissions{MatchOwners: []json.RawMessage{}}
- existing.Status = &capsuleTenantStatus{Owners: []capsuleTenantOwner{
- existing.Spec.Owners[0],
- }}
-
- if err := validatePersonalTenant(existing, desired); err != nil {
- t.Fatalf("validatePersonalTenant() rejected equivalent Tenant: %v", err)
- }
-}
-
-func TestPersonalTenantAdmissionCacheLag_OnlyMatchesExactCapsuleErrors(t *testing.T) {
- for _, resource := range []string{"Tenant.capsule.clastix.io", "tenants.capsule.clastix.io"} {
- body := []byte(`{"kind":"Status","status":"Failure","code":500,"message":"` +
- resource + ` \"user-test-uuid\" not found"}`)
- if !isPersonalTenantAdmissionCacheLag(http.StatusInternalServerError, body, "user-test-uuid") {
- t.Fatalf("expected %s cache miss to be retryable", resource)
- }
- }
- body := []byte(`{"kind":"Status","status":"Failure","code":500,"message":"Tenant.capsule.clastix.io \"user-test-uuid\" not found"}`)
- if isPersonalTenantAdmissionCacheLag(http.StatusInternalServerError, body, "user-someone-else") {
- t.Fatal("matched a different Tenant name")
- }
- if isPersonalTenantAdmissionCacheLag(http.StatusBadGateway, body, "user-test-uuid") {
- t.Fatal("matched a non-500 response")
- }
- if isPersonalTenantAdmissionCacheLag(
- http.StatusInternalServerError,
- []byte(`{"kind":"Status","status":"Failure","code":500,"message":"another admission webhook failed"}`),
- "user-test-uuid",
- ) {
- t.Fatal("matched an unrelated admission failure")
- }
- for _, malformed := range [][]byte{
- []byte(`Tenant.capsule.clastix.io "user-test-uuid" not found`),
- []byte(`{"message":"Tenant.capsule.clastix.io \"user-test-uuid\" not found"}`),
- []byte(`{"kind":"Status","status":"Failure","code":500`),
- } {
- if isPersonalTenantAdmissionCacheLag(
- http.StatusInternalServerError, malformed, "user-test-uuid",
- ) {
- t.Fatalf("matched malformed or non-Status body: %q", malformed)
- }
- }
- nonOwned := []byte(`{"kind":"Status","status":"Failure","code":400,"message":"admission webhook denied the request: can not assign the desired namespace to a non-owned Tenant"}`)
- if !isPersonalTenantAdmissionCacheLag(http.StatusBadRequest, nonOwned, "user-test-uuid") {
- t.Fatal("expected exact non-owned Tenant cache lag to be retryable")
- }
- if isPersonalTenantAdmissionCacheLag(http.StatusInternalServerError, nonOwned, "user-test-uuid") {
- t.Fatal("matched non-owned Tenant message with mismatched HTTP status")
- }
-}
-
-func TestK8sTenantLifecycleBypassesCapsuleProxy(t *testing.T) {
- const userSub = "test-uuid"
- direct := newFakeK8s(http.StatusOK, existingPersonalTenantResponse(userSub))
- defer direct.server.Close()
- proxy := newFakeK8s(http.StatusCreated, nsCreatedResponse("my-workspace"))
- defer proxy.server.Close()
- overrideK8sClientTargets(
- direct.server.Client(), proxy.server.URL, direct.server.URL, "fake-sa-token",
- )
-
- h := Handlers{}
- if _, err := h.ensurePersonalTenant(context.Background(), userSub); err != nil {
- t.Fatalf("ensurePersonalTenant() error = %v", err)
- }
- resp, err := h.k8sImpersonate(
- context.Background(), http.MethodPost, "/api/v1/namespaces", nil, userSub,
- )
- if err != nil {
- t.Fatalf("k8sImpersonate() error = %v", err)
- }
- resp.Body.Close()
-
- if len(direct.requests) != 1 || direct.requests[0].path != capsuleTenantCollectionPath+"/user-"+userSub {
- t.Fatalf("direct apiserver requests = %+v, want only Tenant GET", direct.requests)
- }
- if got := direct.requests[0].headers.Get("Impersonate-User"); got != "" {
- t.Fatalf("direct Tenant request Impersonate-User = %q, want empty", got)
- }
- if len(proxy.requests) != 1 || proxy.requests[0].path != "/api/v1/namespaces" {
- t.Fatalf("Capsule Proxy requests = %+v, want only Namespace POST", proxy.requests)
- }
- if got := proxy.requests[0].headers.Get("Impersonate-User"); got != "oidc:"+userSub {
- t.Fatalf("proxy Namespace request Impersonate-User = %q", got)
- }
-}
-
-func TestCreateNamespace_CancellationBoundsInformerRetryRequest(t *testing.T) {
- const userSub = "test-uuid"
- direct := newFakeK8s(http.StatusOK, existingPersonalTenantResponse(userSub))
- defer direct.server.Close()
-
- var posts atomic.Int32
- started := make(chan struct{}, 1)
- baseTransport := direct.server.Client().Transport
- client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
- if r.URL.Host == "capsule-proxy.test" {
- posts.Add(1)
- started <- struct{}{}
- <-r.Context().Done()
- return nil, r.Context().Err()
- }
- return baseTransport.RoundTrip(r)
- })}
- overrideK8sClientTargets(
- client, "http://capsule-proxy.test", direct.server.URL, "fake-sa-token",
- )
-
- ctx, cancel := context.WithCancel(context.Background())
- defer cancel()
- r := httptest.NewRequest(
- http.MethodPost, "/api/namespaces", strings.NewReader(`{"name":"my-workspace"}`),
- ).WithContext(ctx)
- r = withUser(r, &auth.User{ID: userSub})
- w := httptest.NewRecorder()
- done := make(chan struct{})
- go func() {
- (Handlers{}).CreateNamespace(w, r)
- close(done)
- }()
-
- select {
- case <-started:
- cancel()
- case <-time.After(2 * time.Second):
- cancel()
- select {
- case <-done:
- case <-time.After(time.Second):
- }
- t.Fatal("namespace POST did not start")
- }
- select {
- case <-done:
- case <-time.After(time.Second):
- t.Fatal("handler did not stop after request cancellation")
- }
-
- if w.Code != http.StatusBadGateway {
- t.Fatalf("status = %d, want %d; body = %s", w.Code, http.StatusBadGateway, w.Body.String())
- }
- if got := posts.Load(); got != 1 {
- t.Fatalf("namespace POST count = %d, want 1", got)
- }
-}
-
-func TestEnsurePersonalTenant_AlreadyExists(t *testing.T) {
- const userSub = "test-uuid"
- fk := newFakeK8s(http.StatusOK, existingPersonalTenantResponse(userSub))
- defer fk.server.Close()
- overrideK8sClient(fk.server.Client(), fk.server.URL, "fake-sa-token")
-
- if _, err := (Handlers{}).ensurePersonalTenant(context.Background(), userSub); err != nil {
- t.Fatalf("ensurePersonalTenant() error = %v", err)
- }
- if len(fk.requests) != 1 {
- t.Fatalf("request count = %d, want 1 GET", len(fk.requests))
- }
- if got := fk.requests[0].method; got != http.MethodGet {
- t.Fatalf("method = %q, want GET", got)
- }
- if got := fk.requests[0].headers.Get("Impersonate-User"); got != "" {
- t.Fatalf("Impersonate-User = %q, want empty", got)
- }
-}
-
-func TestCreateNamespace_PendingTenantStatusStopsBeforeNamespace(t *testing.T) {
- const userSub = "test-uuid"
- var gets atomic.Int32
- secondGet := make(chan struct{}, 1)
- direct := newFakeK8sHandler(func(w http.ResponseWriter, _ *http.Request) {
- if gets.Add(1) == 2 {
- secondGet <- struct{}{}
- }
- w.WriteHeader(http.StatusOK)
- _, _ = w.Write([]byte(pendingPersonalTenantResponse(userSub)))
- })
- defer direct.server.Close()
- proxy := newFakeK8s(http.StatusInternalServerError, "unexpected namespace request")
- defer proxy.server.Close()
- overrideK8sClientTargets(
- direct.server.Client(), proxy.server.URL, direct.server.URL, "fake-sa-token",
- )
-
- ctx, cancel := context.WithCancel(context.Background())
- defer cancel()
- r := httptest.NewRequest(
- http.MethodPost, "/api/namespaces", strings.NewReader(`{"name":"my-workspace"}`),
- ).WithContext(ctx)
- r = withUser(r, &auth.User{ID: userSub})
- w := httptest.NewRecorder()
- done := make(chan struct{})
- go func() {
- (Handlers{}).CreateNamespace(w, r)
- close(done)
- }()
-
- select {
- case <-secondGet:
- cancel()
- case <-time.After(2 * time.Second):
- cancel()
- select {
- case <-done:
- case <-time.After(time.Second):
- }
- t.Fatal("Tenant readiness was not polled")
- }
- select {
- case <-done:
- case <-time.After(time.Second):
- t.Fatal("handler did not stop after readiness wait cancellation")
- }
-
- if w.Code != http.StatusBadGateway {
- t.Fatalf("status = %d, want %d; body = %s", w.Code, http.StatusBadGateway, w.Body.String())
- }
- if len(proxy.requests) != 0 {
- t.Fatalf("namespace requests = %+v, want none before status.owners is ready", proxy.requests)
- }
-}
-
-func TestEnsurePersonalTenant_CreateConflictRevalidatesWinner(t *testing.T) {
- const userSub = "test-uuid"
- getCount := 0
- fk := newFakeK8sHandler(func(w http.ResponseWriter, r *http.Request) {
- switch r.Method {
- case http.MethodGet:
- getCount++
- if getCount == 1 {
- w.WriteHeader(http.StatusNotFound)
- return
- }
- w.WriteHeader(http.StatusOK)
- _, _ = w.Write([]byte(existingPersonalTenantResponse(userSub)))
- case http.MethodPost:
- w.WriteHeader(http.StatusConflict)
- default:
- t.Errorf("unexpected method: %s", r.Method)
- w.WriteHeader(http.StatusInternalServerError)
- }
- })
- defer fk.server.Close()
- overrideK8sClient(fk.server.Client(), fk.server.URL, "fake-sa-token")
-
- if _, err := (Handlers{}).ensurePersonalTenant(context.Background(), userSub); err != nil {
- t.Fatalf("ensurePersonalTenant() error = %v", err)
- }
- if len(fk.requests) != 3 {
- t.Fatalf("request count = %d, want GET, POST, GET", len(fk.requests))
- }
- if fk.requests[0].method != http.MethodGet ||
- fk.requests[1].method != http.MethodPost ||
- fk.requests[2].method != http.MethodGet {
- t.Fatalf("unexpected request sequence: %+v", fk.requests)
- }
-}
-
-func TestCreateNamespace_MismatchedTenantFailsClosed(t *testing.T) {
- existing := desiredPersonalTenant(context.Background(), "test-uuid")
- existing.Spec.Owners[0].Name = "oidc:someone-else"
- body, err := json.Marshal(existing)
- if err != nil {
- t.Fatal(err)
- }
-
- fk := newFakeK8s(http.StatusOK, string(body))
- defer fk.server.Close()
- overrideK8sClient(fk.server.Client(), fk.server.URL, "fake-sa-token")
-
- h := Handlers{}
- r := httptest.NewRequest(
- http.MethodPost, "/api/namespaces", strings.NewReader(`{"name":"my-workspace"}`),
- )
- r = withUser(r, &auth.User{ID: "test-uuid"})
- w := httptest.NewRecorder()
- h.CreateNamespace(w, r)
-
- if w.Code != http.StatusBadGateway {
- t.Fatalf("status = %d, want %d; body = %s", w.Code, http.StatusBadGateway, w.Body.String())
- }
- if len(fk.requests) != 1 || fk.requests[0].method != http.MethodGet {
- t.Fatalf("requests = %+v, want only Tenant GET", fk.requests)
- }
- if strings.Contains(w.Body.String(), "someone-else") {
- t.Fatalf("response exposed Tenant details: %s", w.Body.String())
- }
-}
-
-func TestCreateNamespace_TenantBackendFailureStopsBeforeNamespace(t *testing.T) {
- fk := newFakeK8s(http.StatusInternalServerError, "backend unavailable")
- defer fk.server.Close()
- overrideK8sClient(fk.server.Client(), fk.server.URL, "fake-sa-token")
-
- h := Handlers{}
- r := httptest.NewRequest(
- http.MethodPost, "/api/namespaces", strings.NewReader(`{"name":"my-workspace"}`),
- )
- r = withUser(r, &auth.User{ID: "test-uuid"})
- w := httptest.NewRecorder()
- h.CreateNamespace(w, r)
-
- if w.Code != http.StatusBadGateway {
- t.Fatalf("status = %d, want %d; body = %s", w.Code, http.StatusBadGateway, w.Body.String())
- }
- if len(fk.requests) != 1 || fk.requests[0].method != http.MethodGet {
- t.Fatalf("requests = %+v, want only Tenant GET", fk.requests)
- }
- if got, want := w.Body.String(), "{\"error\":\"could not ensure personal tenant\"}\n"; got != want {
- t.Fatalf("body = %q, want bounded generic error %q", got, want)
- }
-}
-
-func TestCreateNamespace_EmptySubjectIsUnauthorized(t *testing.T) {
- h := Handlers{}
- r := httptest.NewRequest(
- http.MethodPost, "/api/namespaces", strings.NewReader(`{"name":"my-workspace"}`),
- )
- r = withUser(r, &auth.User{})
- w := httptest.NewRecorder()
-
- h.CreateNamespace(w, r)
-
- if w.Code != http.StatusUnauthorized {
- t.Fatalf("status = %d, want %d; body = %s", w.Code, http.StatusUnauthorized, w.Body.String())
- }
-}
diff --git a/libs/fleet/backend/identity/identity.go b/libs/fleet/backend/identity/identity.go
index ba0f9cf2d7..e435e91c85 100644
--- a/libs/fleet/backend/identity/identity.go
+++ b/libs/fleet/backend/identity/identity.go
@@ -1,7 +1,7 @@
// Package identity resolves the cross-service identity prefixes (Keycloak
// group / Capsule tenant prefix and the OIDC username/groups prefixes) from
-// OpenFeature, so the cyclops-cs backend's Tenant lifecycle and impersonation
-// headers stay aligned with the k3s apiserver flags instead of hardcoding
+// OpenFeature, so backend impersonation and the standalone Tenant controller
+// stay aligned with the k3s apiserver flags instead of hardcoding
// separate copies — the drift that previously broke tenant RBAC.
//
// Flag keys (SSM Parameter Store paths):
@@ -55,8 +55,8 @@ var (
clientOnce sync.Once
client *openfeature.Client
- mu sync.Mutex
- cache = map[string]cached{}
+ mu sync.Mutex
+ cache = map[string]cached{}
)
type cached struct {
diff --git a/libs/fleet/docs/sdk-schema-flow.svg b/libs/fleet/docs/sdk-schema-flow.svg
new file mode 100644
index 0000000000..93700aab75
--- /dev/null
+++ b/libs/fleet/docs/sdk-schema-flow.svg
@@ -0,0 +1,59 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="1080" viewBox="0 0 1600 1080" role="img" aria-labelledby="title desc">
+ <title id="title">Cyclops multi-language SDK schema and runtime flow</title>
+ <desc id="desc">Kubernetes CRDs generate shared plumbing types for WIT, Rust, TypeScript, Python, and Go. Handwritten porcelain operations use those types. Language bindings call the Rust core, which constructs Kubernetes resources, authenticates requests, and waits for claims to bind into sandboxes.</desc>
+ <defs>
+ <linearGradient id="background" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#f7f1e6"/><stop offset="0.56" stop-color="#edf3e8"/><stop offset="1" stop-color="#e7eff0"/></linearGradient>
+ <linearGradient id="sourceFill" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#182724"/><stop offset="1" stop-color="#29483f"/></linearGradient>
+ <linearGradient id="coreFill" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#d9633b"/><stop offset="1" stop-color="#bd3f2a"/></linearGradient>
+ <pattern id="grid" width="28" height="28" patternUnits="userSpaceOnUse"><path d="M 28 0 L 0 0 0 28" fill="none" stroke="#17352f" stroke-opacity="0.05" stroke-width="1"/></pattern>
+ <filter id="shadow" x="-20%" y="-20%" width="140%" height="150%"><feDropShadow dx="0" dy="8" stdDeviation="10" flood-color="#18332e" flood-opacity="0.13"/></filter>
+ <marker id="arrowDark" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#24433b"/></marker>
+ <marker id="arrowOrange" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#cf5335"/></marker>
+ <style>
+ .display { font-family: Georgia, 'Times New Roman', serif; }
+ .sans { font-family: 'Trebuchet MS', 'Segoe UI', sans-serif; }
+ .mono { font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', monospace; }
+ .eyebrow { font-size: 14px; font-weight: 700; }
+ .section { font-size: 14px; font-weight: 700; }
+ .card-title { font-size: 23px; font-weight: 700; }
+ .body { font-size: 16px; }
+ .small { font-size: 14px; }
+ .tiny { font-size: 12px; }
+ .muted { fill: #60716c; }
+ .ink { fill: #182724; }
+ .cream { fill: #fffaf1; }
+ .line { fill: none; stroke: #24433b; stroke-width: 3; marker-end: url(#arrowDark); }
+ .line-orange { fill: none; stroke: #cf5335; stroke-width: 3; marker-end: url(#arrowOrange); }
+ .dash { stroke-dasharray: 8 8; }
+ </style>
+ </defs>
+ <rect width="1600" height="1080" fill="url(#background)"/><rect width="1600" height="1080" fill="url(#grid)"/>
+ <circle cx="1480" cy="104" r="190" fill="#d9633b" opacity="0.08"/><circle cx="92" cy="990" r="220" fill="#497b68" opacity="0.08"/>
+ <g class="sans">
+ <text x="76" y="62" class="eyebrow" fill="#bd4c31">Cyclops SDK architecture</text>
+ <text x="76" y="118" class="display ink" font-size="46" font-weight="700">One schema. Many languages. One core.</text>
+ <text x="78" y="151" class="body muted">Generated plumbing stays synchronized with Kubernetes; handwritten porcelain owns behavior.</text>
+ <g transform="translate(1258 55)"><rect width="266" height="88" rx="20" fill="#fffaf1" stroke="#d6cbbc"/><circle cx="35" cy="31" r="8" fill="#d9633b"/><text x="55" y="36" class="small ink" font-weight="700">Generated plumbing</text><line x1="27" y1="62" x2="43" y2="62" stroke="#24433b" stroke-width="3" stroke-dasharray="5 4"/><text x="55" y="67" class="small muted">Handwritten porcelain</text></g>
+ <text x="76" y="216" class="section" fill="#526660">Build time · schema flow</text><line x1="76" y1="229" x2="1524" y2="229" stroke="#72847e" stroke-opacity="0.35"/>
+ <g transform="translate(76 262)"><rect width="292" height="248" rx="26" fill="url(#sourceFill)"/><rect x="22" y="22" width="132" height="28" rx="14" fill="#f1b14d"/><text x="88" y="41" class="tiny" text-anchor="middle" fill="#182724" font-weight="700">SOURCE OF TRUTH</text><text x="24" y="87" class="card-title cream">Kubernetes CRDs</text><text x="24" y="119" class="mono small" fill="#d4e3dc">clusters/base/osgym/</text><text x="24" y="141" class="mono small" fill="#d4e3dc">crd.yaml</text><line x1="24" y1="164" x2="268" y2="164" stroke="#fffaf1" stroke-opacity="0.2"/><text x="24" y="194" class="small" fill="#fffaf1">Pool <tspan fill="#91c5ae">spec schema</tspan></text><text x="24" y="219" class="small" fill="#fffaf1">Claim <tspan fill="#91c5ae">spec schema</tspan></text></g>
+ <path d="M 368 386 C 402 386, 414 386, 444 386" class="line-orange"/><text x="406" y="368" class="tiny" text-anchor="middle" fill="#bd4c31" font-weight="700">READ</text>
+ <g transform="translate(444 283)"><rect width="286" height="206" rx="26" fill="#fffaf1" stroke="#d6cbbc"/><rect x="22" y="20" width="104" height="28" rx="14" fill="#f2d28f"/><text x="74" y="39" class="tiny ink" text-anchor="middle" font-weight="700">GENERATOR</text><text x="24" y="82" class="card-title ink">Schema generator</text><text x="24" y="111" class="mono small muted">sdk-schema-generator</text><text x="24" y="146" class="small ink">Parses OpenAPI v3 schema</text><text x="24" y="171" class="small ink">Preserves fields, enums, lists, maps</text></g>
+ <path d="M 730 386 C 765 386, 770 386, 800 386" class="line-orange"/><text x="765" y="368" class="tiny" text-anchor="middle" fill="#bd4c31" font-weight="700">EMIT</text>
+ <g transform="translate(800 251)"><rect width="724" height="270" rx="26" fill="#fffaf1" stroke="#d6cbbc"/><text x="26" y="48" class="card-title ink">Generated plumbing</text><text x="26" y="73" class="small muted">The same PoolSpec and ClaimSpec shape everywhere.</text>
+ <g transform="translate(26 96)"><rect width="206" height="139" rx="18" fill="#e3eee8" stroke="#a9c5b7"/><text x="18" y="31" class="small ink" font-weight="700">WIT types</text><text x="18" y="58" class="mono tiny muted">generated-crd.wit</text><text x="18" y="90" class="mono small ink">pool-spec</text><text x="18" y="115" class="mono small ink">claim-spec</text></g>
+ <g transform="translate(252 96)"><rect width="210" height="139" rx="18" fill="#eef1dc" stroke="#c7cc9d"/><text x="18" y="31" class="small ink" font-weight="700">Rust core models</text><text x="18" y="58" class="mono tiny muted">generated_crd.rs</text><text x="18" y="90" class="mono tiny muted">generated_crd_</text><text x="18" y="110" class="mono tiny muted">component.rs</text></g>
+ <g transform="translate(482 96)"><rect width="216" height="139" rx="18" fill="#f7e3d8" stroke="#dfb7a4"/><text x="18" y="31" class="small ink" font-weight="700">Language types</text><text x="18" y="61" class="small ink">TypeScript</text><text x="18" y="86" class="small ink">Python</text><text x="18" y="111" class="small ink">Go</text></g>
+ </g>
+ <g transform="translate(76 550)"><rect width="1448" height="88" rx="22" fill="#fffaf1" fill-opacity="0.72" stroke="#b8c5bd" stroke-dasharray="8 8"/><text x="24" y="35" class="section" fill="#526660">Handwritten porcelain WIT</text><text x="24" y="62" class="mono small ink">create-pool({ namespace, spec }) · create-claim({ pool, spec? }) · CRUD · wait-claim</text><text x="1418" y="51" class="small" text-anchor="end" fill="#60716c">Stable intent, generated data</text></g>
+ <text x="76" y="696" class="section" fill="#526660">Runtime · request flow</text><line x1="76" y1="709" x2="1524" y2="709" stroke="#72847e" stroke-opacity="0.35"/>
+ <g transform="translate(76 749)"><rect width="250" height="226" rx="26" fill="#fffaf1" stroke="#d6cbbc"/><text x="24" y="42" class="card-title ink">Your application</text><text x="24" y="74" class="small muted">Choose any binding</text><g transform="translate(24 96)"><rect width="89" height="36" rx="18" fill="#dce9e2"/><text x="44.5" y="23" class="small ink" text-anchor="middle">Python</text><rect x="99" width="103" height="36" rx="18" fill="#f3e2c2"/><text x="150.5" y="23" class="small ink" text-anchor="middle">TypeScript</text><rect y="48" width="89" height="36" rx="18" fill="#e4ebcd"/><text x="44.5" y="71" class="small ink" text-anchor="middle">Go</text><rect x="99" y="48" width="103" height="36" rx="18" fill="#f2d9ce"/><text x="150.5" y="71" class="small ink" text-anchor="middle">Rust</text></g><text x="24" y="202" class="mono tiny muted">PoolSpec / ClaimSpec</text></g>
+ <path d="M 326 862 C 352 862, 363 862, 387 862" class="line"/><text x="356" y="843" class="tiny" text-anchor="middle" fill="#526660" font-weight="700">CALL</text>
+ <g transform="translate(387 749)"><rect width="410" height="226" rx="26" fill="url(#coreFill)"/><text x="24" y="42" class="card-title cream">Rust core · porcelain</text><text x="24" y="72" class="small" fill="#ffe6da">Native runner or WASM component</text><line x1="24" y1="91" x2="386" y2="91" stroke="#fffaf1" stroke-opacity="0.25"/><text x="24" y="122" class="small cream">Adds apiVersion, kind, metadata</text><text x="24" y="148" class="small cream">Derives claim namespace + template ref</text><text x="24" y="174" class="small cream">Builds URLs · OAuth · 401 retry</text><text x="24" y="200" class="small cream">CRUD + claim polling</text></g>
+ <path d="M 797 862 C 823 862, 834 862, 858 862" class="line"/><text x="827" y="843" class="tiny" text-anchor="middle" fill="#526660" font-weight="700">HTTP</text>
+ <g transform="translate(858 749)"><rect width="274" height="226" rx="26" fill="#fffaf1" stroke="#d6cbbc"/><text x="24" y="42" class="card-title ink">Cyclops API</text><text x="24" y="73" class="mono small muted">/api/k8s/{path}</text><line x1="24" y1="93" x2="250" y2="93" stroke="#d6cbbc"/><text x="24" y="124" class="small ink">Authenticated proxy</text><text x="24" y="150" class="small ink">Resource CRUD</text><text x="24" y="176" class="small ink">Returns live status</text><rect x="24" y="191" width="127" height="23" rx="11" fill="#e3eee8"/><text x="87.5" y="207" class="tiny ink" text-anchor="middle">generic endpoint</text></g>
+ <path d="M 1132 862 C 1157 862, 1169 862, 1193 862" class="line"/>
+ <g transform="translate(1193 749)"><rect width="331" height="226" rx="26" fill="#203a34"/><text x="24" y="42" class="card-title cream">Kubernetes + OSGym</text><g transform="translate(24 72)"><rect width="283" height="43" rx="14" fill="#31554a"/><text x="16" y="27" class="small cream">OSGymWorkspacePool</text><rect y="54" width="283" height="43" rx="14" fill="#31554a"/><text x="16" y="81" class="small cream">OSGymSandboxClaim</text><path d="M 142 102 L 142 121" stroke="#f1b14d" stroke-width="3" marker-end="url(#arrowOrange)"/><rect y="127" width="283" height="43" rx="14" fill="#f1b14d"/><text x="141.5" y="154" class="small ink" text-anchor="middle" font-weight="700">Bound → Sandbox</text></g></g>
+ <path d="M 1340 986 C 1340 1024, 592 1034, 592 986" class="line-orange dash"/><rect x="797" y="1005" width="337" height="36" rx="18" fill="#fffaf1" stroke="#dfb7a4"/><text x="965.5" y="1028" class="small" text-anchor="middle" fill="#9d3c28" font-weight="700">wait_claim polls until status.phase = Bound</text>
+ <text x="76" y="1043" class="tiny muted">Generated files are checked for drift in CI. Edit the CRDs, rerun the generator, and every language follows.</text><text x="1524" y="1043" class="tiny muted" text-anchor="end">Protocol v5</text>
+ </g>
+</svg>
diff --git a/libs/fleet/rbac-e2e/pool_rbac_test.go b/libs/fleet/rbac-e2e/pool_rbac_test.go
index 577ee0d5df..86d13f2f79 100644
--- a/libs/fleet/rbac-e2e/pool_rbac_test.go
+++ b/libs/fleet/rbac-e2e/pool_rbac_test.go
@@ -21,10 +21,9 @@
// verbs into `admin`. Capsule creates that binding only for a governed owner.
// This package preserves the historical group-owner regression from the
// retired Kopf lifecycle: dynamic oidc:user-<sub> groups could be removed when
-// Flux reapplied CapsuleConfiguration.userGroups. The current backend creates
-// and validates direct User owners before namespace creation; its first-use
-// lifecycle is covered by the backend Tenant tests, not by this historical
-// negative-control package.
+// Flux reapplied CapsuleConfiguration.userGroups. The standalone controller
+// now reconciles direct User owners independently of namespace creation;
+// controller tests cover that lifecycle instead of this historical negative control.
//
// Two tests, both against a real apiserver with no Capsule operator:
//
diff --git a/libs/fleet/sdk-bindings/README.md b/libs/fleet/sdk-bindings/README.md
new file mode 100644
index 0000000000..b6bd988588
--- /dev/null
+++ b/libs/fleet/sdk-bindings/README.md
@@ -0,0 +1,111 @@
+# Cyclops multi-language SDK
+
+Rust, TypeScript, Go, and Python expose typed `Pool`, `Claim`, and `Sandbox` resources. `connect` configures the Cyclops base URL and OAuth credentials once. The Rust core owns service routing, tokens, authorization headers, network execution, and one retry after `401`.
+
+## Porcelain API
+
+Pool operations:
+
+```text
+pool = create_pool({ namespace, spec: pool_spec })
+list_pools(namespace)
+get_pool(pool)
+update_pool(pool)
+delete_pool(pool)
+```
+
+Claim operations:
+
+```text
+claim = create_claim({ pool })
+claim = create_claim({ pool, spec: claim_spec }) # optional advanced override
+list_claims(namespace)
+get_claim(claim)
+update_claim(claim)
+delete_claim(claim)
+sandbox = wait_claim(claim)
+```
+
+`PoolSpec` and `ClaimSpec` come from the checked-in Kubernetes CRDs. `wait_claim` returns sandbox identity and the pool's available service names. It does not expose service endpoint URLs.
+
+## Named service HTTP
+
+Select a client with a `Sandbox` and a user-defined pool service name. Requests use relative paths only. Unknown services raise a structured error with the requested name and sorted available names.
+
+Python returns an `httpx.Client` backed by an SDK transport:
+
+```python
+with sdk.service_client(sandbox, "mcp") as mcp:
+ response = mcp.post("/mcp", json={"jsonrpc": "2.0", "method": "initialize"})
+```
+
+TypeScript returns a fetch-compatible function:
+
+```ts
+const mcp = sdk.serviceFetch(sandbox, "mcp")
+const response = await mcp("/mcp", { method: "POST", body: JSON.stringify(payload) })
+```
+
+Go provides a `net/http`-style request adapter whose `Do` method executes through the core:
+
+```go
+mcp, err := sdk.ServiceClient(sandbox, "mcp")
+request, err := mcp.NewRequest("POST", "/mcp", bytes.NewReader(body))
+response, err := mcp.Do(request)
+```
+
+Rust provides an SDK-owned request builder:
+
+```rust
+let mut mcp = sdk.service_client(&sandbox, "mcp")?;
+let response = mcp.post("/mcp").body(body).send()?;
+```
+
+Applications never construct service endpoint URLs or receive OAuth tokens. The SDK does not expose a generic authenticated URL client; service selection plus a relative path is the only application-controlled HTTP route surface.
+
+## App-controlled sequence
+
+Each example creates a pool with an `mcp` service, creates and waits for a claim, selects `mcp`, and sends MCP `initialize` to `/mcp`. Because binding resets the guest, examples retry transient `502`, `503`, and `504` responses for up to five minutes. Cleanup deletes the claim before the pool and then closes the SDK host.
+
+```text
+cyclops-cs/sdk-bindings/examples/python/app_controlled.py
+cyclops-cs/sdk-bindings/examples/typescript/app-controlled.ts
+cyclops-cs/sdk-bindings/go/examples/app_controlled.go
+cyclops-cs/sdk-bindings/rust/examples/app_controlled.rs
+```
+
+## Live example validation
+
+Build the shared Rust core runner and provide credentials through environment variables. Enter the client secret interactively so it does not enter shell history:
+
+```sh
+cargo build --locked --manifest-path cyclops-cs/sdk-core/Cargo.toml --bin cyclops-core-runner
+export CYCLOPS_CORE_RUNNER="$(pwd)/cyclops-cs/sdk-core/target/debug/cyclops-core-runner"
+export CUA_CLIENT_ID="<client-id>"
+read -rsp "CUA client secret: " CUA_CLIENT_SECRET && export CUA_CLIENT_SECRET && printf '\n'
+export CUA_IMAGE="296062593712.dkr.ecr.us-west-2.amazonaws.com/desktop-workspace@sha256:b9e74dbff4cc727c33ff4b8483bffa0860bb99213041c88f11260ac31db7628f"
+export CUA_IMAGE_PULL_SECRET="ecr-credentials"
+```
+
+`CUA_BASE_URL` defaults to `https://run.cua.ai`. `CUA_TOKEN_URL` defaults to the production Cyclops OAuth endpoint. Run examples independently so each receives a generated namespace:
+
+```sh
+uv run --project cyclops-cs/sdk-bindings/python python cyclops-cs/sdk-bindings/examples/python/app_controlled.py
+(cd cyclops-cs/sdk-bindings/typescript && npm run build && node dist-examples/app-controlled.js)
+(cd cyclops-cs/sdk-bindings/go && go run ./examples)
+cargo run --locked --manifest-path cyclops-cs/sdk-bindings/rust/Cargo.toml --example app_controlled
+```
+
+## Validation
+
+```sh
+(cd cyclops-cs/sdk-schema-generator && go run . -root ../.. -check)
+cargo fmt --manifest-path cyclops-cs/sdk-core/Cargo.toml -- --check
+cargo clippy --locked --manifest-path cyclops-cs/sdk-core/Cargo.toml --all-targets -- -D warnings
+cargo test --locked --manifest-path cyclops-cs/sdk-core/Cargo.toml
+cargo clippy --locked --manifest-path cyclops-cs/sdk-bindings/rust/Cargo.toml --all-targets -- -D warnings
+cargo test --locked --manifest-path cyclops-cs/sdk-bindings/rust/Cargo.toml --all-targets
+(cd cyclops-cs/sdk-bindings/typescript && npm ci && npm run typecheck && npm test)
+(cd cyclops-cs/sdk-bindings/go && test -z "$(gofmt -l .)" && go vet ./... && go test ./...)
+(cd cyclops-cs/sdk-bindings/python && uv run --with ruff==0.9.10 ruff check cyclops_sdk tests ../examples && uv run python -m unittest discover -s tests && uv build)
+```
diff --git a/libs/fleet/sdk-bindings/examples/python/app_controlled.py b/libs/fleet/sdk-bindings/examples/python/app_controlled.py
new file mode 100644
index 0000000000..34afd58472
--- /dev/null
+++ b/libs/fleet/sdk-bindings/examples/python/app_controlled.py
@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Application-controlled pool, claim, and sandbox operation flow."""
+import json
+import os
+import time
+import uuid
+
+from cyclops_sdk import Claim, Pool, Sandbox, SDK, connect
+
+
+def run_agent(sdk: SDK, sandbox: Sandbox):
+ deadline = time.monotonic() + 300
+ with sdk.service_client(sandbox, "mcp") as mcp:
+ while True:
+ response = mcp.post(
+ "/mcp",
+ headers={
+ "accept": "application/json, text/event-stream",
+ "content-type": "application/json",
+ },
+ json={
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "initialize",
+ "params": {
+ "protocolVersion": "2025-03-26",
+ "capabilities": {},
+ "clientInfo": {"name": "cyclops-sdk-python-example", "version": "0.1.0"},
+ },
+ },
+ )
+ if 200 <= response.status_code < 300:
+ return {"namespace": sandbox["namespace"], "claim": sandbox["claim"], "sandbox": sandbox["sandbox"], "mcp_status": response.status_code}
+ if response.status_code not in (502, 503, 504) or time.monotonic() >= deadline:
+ raise RuntimeError(f"MCP initialize failed with HTTP {response.status_code}: {response.text}")
+ time.sleep(5)
+
+
+def main():
+ namespace = os.getenv("CYCLOPS_NAMESPACE", f"sdk-example-{uuid.uuid4().hex[:8]}")
+ sdk = connect({
+ "base_url": os.getenv("CUA_BASE_URL", "https://run.cua.ai"),
+ "oauth": {
+ "token_url": os.getenv("CUA_TOKEN_URL", "https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token"),
+ "client_id": os.environ["CUA_CLIENT_ID"],
+ "client_secret": os.environ["CUA_CLIENT_SECRET"],
+ },
+ })
+ pool: Pool | None = None
+ claim: Claim | None = None
+ try:
+ pool = sdk.create_pool({
+ "namespace": namespace,
+ "spec": {
+ "replicas": 1,
+ "services": [{"name": "mcp", "targetPort": 3000, "protocol": "TCP"}],
+ "template": {
+ "containerDiskImage": os.environ["CUA_IMAGE"],
+ "imagePullSecret": os.environ["CUA_IMAGE_PULL_SECRET"],
+ "cpuCores": 4,
+ "memory": "4Gi",
+ },
+ },
+ })
+ claim = sdk.create_claim({"pool": pool})
+ sandbox = sdk.wait_claim(claim)
+ result = run_agent(sdk, sandbox)
+ print(json.dumps(result, sort_keys=True))
+ finally:
+ try:
+ if claim is not None:
+ sdk.delete_claim(claim)
+ finally:
+ try:
+ if pool is not None:
+ sdk.delete_pool(pool)
+ finally:
+ sdk.close()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/libs/fleet/sdk-bindings/examples/typescript/app-controlled.ts b/libs/fleet/sdk-bindings/examples/typescript/app-controlled.ts
new file mode 100644
index 0000000000..98ff071171
--- /dev/null
+++ b/libs/fleet/sdk-bindings/examples/typescript/app-controlled.ts
@@ -0,0 +1,76 @@
+#!/usr/bin/env -S node --enable-source-maps
+import { randomUUID } from "node:crypto"
+import { connect, type Claim, type Pool, type Sandbox, type SDK } from "../../typescript/dist/index.js"
+
+async function runAgent(sdk: SDK, sandbox: Sandbox): Promise<unknown> {
+ const deadline = Date.now() + 300_000
+ const mcp = sdk.serviceFetch(sandbox, "mcp")
+ while (true) {
+ const response = await mcp("/mcp", {
+ method: "POST",
+ headers: { accept: "application/json, text/event-stream", "content-type": "application/json" },
+ body: JSON.stringify({
+ jsonrpc: "2.0",
+ id: 1,
+ method: "initialize",
+ params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "cyclops-sdk-typescript-example", version: "0.1.0" } },
+ }),
+ })
+ if (response.status >= 200 && response.status < 300) {
+ return { namespace: sandbox.namespace, claim: sandbox.claim, sandbox: sandbox.sandbox, mcp_status: response.status }
+ }
+ const body = await response.text()
+ if (![502, 503, 504].includes(response.status) || Date.now() >= deadline) {
+ throw new Error(`MCP initialize failed with HTTP ${response.status}: ${body}`)
+ }
+ await new Promise((resolve) => setTimeout(resolve, 5_000))
+ }
+}
+
+
+const namespace = process.env.CYCLOPS_NAMESPACE ?? `sdk-example-${randomUUID().replaceAll("-", "").slice(0, 8)}`
+const sdk = await connect({
+ baseUrl: process.env.CUA_BASE_URL ?? "https://run.cua.ai",
+ oauth: {
+ tokenUrl: process.env.CUA_TOKEN_URL ?? "https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token",
+ clientId: required("CUA_CLIENT_ID"),
+ clientSecret: required("CUA_CLIENT_SECRET"),
+ },
+})
+let pool: Pool | undefined
+let claim: Claim | undefined
+try {
+ pool = await sdk.createPool({
+ namespace,
+ spec: {
+ replicas: 1,
+ services: [{ name: "mcp", targetPort: 3000, protocol: "TCP" }],
+ template: {
+ containerDiskImage: required("CUA_IMAGE"),
+ imagePullSecret: required("CUA_IMAGE_PULL_SECRET"),
+ cpuCores: 4,
+ memory: "4Gi",
+ },
+ },
+ })
+ claim = await sdk.createClaim({ pool })
+ const sandbox = await sdk.waitClaim(claim)
+ const result = await runAgent(sdk, sandbox)
+ console.log(JSON.stringify(result))
+} finally {
+ try {
+ if (claim) await sdk.deleteClaim(claim)
+ } finally {
+ try {
+ if (pool) await sdk.deletePool(pool)
+ } finally {
+ sdk.close()
+ }
+ }
+}
+
+function required(name: string): string {
+ const value = process.env[name]
+ if (!value) throw new Error(`${name} is required`)
+ return value
+}
diff --git a/libs/fleet/sdk-bindings/go/.gitignore b/libs/fleet/sdk-bindings/go/.gitignore
new file mode 100644
index 0000000000..fc522ce6b9
--- /dev/null
+++ b/libs/fleet/sdk-bindings/go/.gitignore
@@ -0,0 +1,3 @@
+/go
+/cyclops-sdk-go
+/cyclops-sdk-raw
diff --git a/libs/fleet/sdk-bindings/go/examples/app_controlled.go b/libs/fleet/sdk-bindings/go/examples/app_controlled.go
new file mode 100644
index 0000000000..f661d85f36
--- /dev/null
+++ b/libs/fleet/sdk-bindings/go/examples/app_controlled.go
@@ -0,0 +1,106 @@
+package main
+
+import (
+ "bytes"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "os"
+ "time"
+
+ cyclopssdk "github.com/trycua/cloud/cyclops-cs/sdk-bindings/go"
+)
+
+func runAgent(sdk *cyclopssdk.SDK, sandbox cyclopssdk.Sandbox) (any, error) {
+ mcp, err := sdk.ServiceClient(sandbox, "mcp")
+ if err != nil {
+ return nil, err
+ }
+ body := []byte(`{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"cyclops-sdk-go-example","version":"0.1.0"}}}`)
+ deadline := time.Now().Add(5 * time.Minute)
+ for {
+ request, err := mcp.NewRequest("POST", "/mcp", bytes.NewReader(body))
+ if err != nil {
+ return nil, err
+ }
+ request.Header.Set("accept", "application/json, text/event-stream")
+ request.Header.Set("content-type", "application/json")
+ response, err := mcp.Do(request)
+ if err != nil {
+ return nil, err
+ }
+ responseBody, readErr := io.ReadAll(response.Body)
+ response.Body.Close()
+ if readErr != nil {
+ return nil, readErr
+ }
+ if response.StatusCode >= 200 && response.StatusCode < 300 {
+ return map[string]any{"namespace": sandbox.Namespace, "claim": sandbox.Claim, "sandbox": sandbox.Sandbox, "mcp_status": response.StatusCode}, nil
+ }
+ transient := response.StatusCode == 502 || response.StatusCode == 503 || response.StatusCode == 504
+ if !transient || time.Now().After(deadline) {
+ return nil, fmt.Errorf("MCP initialize failed with HTTP %d: %s", response.StatusCode, responseBody)
+ }
+ time.Sleep(5 * time.Second)
+ }
+}
+
+func main() {
+ namespace := env("CYCLOPS_NAMESPACE", fmt.Sprintf("sdk-example-%08x", uint32(time.Now().UnixNano())))
+ sdk, err := cyclopssdk.Connect(cyclopssdk.Configuration{
+ BaseURL: env("CUA_BASE_URL", "https://run.cua.ai"),
+ OAuth: cyclopssdk.OAuthConfiguration{
+ TokenURL: env("CUA_TOKEN_URL", "https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token"),
+ ClientID: required("CUA_CLIENT_ID"), ClientSecret: required("CUA_CLIENT_SECRET"),
+ },
+ })
+ must(err)
+ defer func() { must(sdk.Close()) }()
+ cpuCores := uint32(4)
+ memory := "4Gi"
+ imagePullSecret := required("CUA_IMAGE_PULL_SECRET")
+ protocol := cyclopssdk.PoolSpecServiceProtocolTCP
+ pool, err := sdk.CreatePool(cyclopssdk.CreatePoolRequest{
+ Namespace: namespace,
+ Spec: cyclopssdk.PoolSpec{
+ Replicas: 1,
+ Services: []cyclopssdk.PoolSpecService{{
+ Name: "mcp", TargetPort: 3000, Protocol: &protocol,
+ }},
+ Template: cyclopssdk.PoolTemplate{
+ ContainerDiskImage: required("CUA_IMAGE"), ImagePullSecret: &imagePullSecret, CpuCores: &cpuCores, Memory: &memory,
+ },
+ },
+ })
+ must(err)
+ defer func() { must(sdk.DeletePool(pool)) }()
+ claim, err := sdk.CreateClaim(cyclopssdk.CreateClaimRequest{Pool: pool})
+ must(err)
+ defer func() { must(sdk.DeleteClaim(claim)) }()
+ sandbox, err := sdk.WaitClaim(claim)
+ must(err)
+ result, err := runAgent(sdk, sandbox)
+ must(err)
+ output, err := json.Marshal(result)
+ must(err)
+ fmt.Println(string(output))
+}
+
+func env(name, fallback string) string {
+ if value := os.Getenv(name); value != "" {
+ return value
+ }
+ return fallback
+}
+func required(name string) string {
+ if value := os.Getenv(name); value != "" {
+ return value
+ }
+ panic(name + " is required")
+}
+func must(err error) {
+ if err != nil && !errors.Is(err, os.ErrProcessDone) {
+ panic(err)
+ }
+}
diff --git a/libs/fleet/sdk-bindings/go/generated_crd.go b/libs/fleet/sdk-bindings/go/generated_crd.go
new file mode 100644
index 0000000000..2e3ec1bec1
--- /dev/null
+++ b/libs/fleet/sdk-bindings/go/generated_crd.go
@@ -0,0 +1,83 @@
+// Code generated from clusters/base/osgym/crd.yaml; DO NOT EDIT.
+package cyclopssdk
+
+type ClaimSpec struct {
+ BindDeadline *uint32 `json:"bindDeadline,omitempty"`
+ Lifecycle *ClaimSpecLifecycle `json:"lifecycle,omitempty"`
+ SandboxTemplateRef SandboxTemplateRef `json:"sandboxTemplateRef"`
+ Warmpool *string `json:"warmpool,omitempty"`
+}
+
+type ClaimSpecLifecycle struct {
+ AutoRenew *bool `json:"autoRenew,omitempty"`
+ ShutdownPolicy *string `json:"shutdownPolicy,omitempty"`
+ ShutdownTime *string `json:"shutdownTime,omitempty"`
+}
+
+type PoolSpec struct {
+ Autoscaling *PoolSpecAutoscaling `json:"autoscaling,omitempty"`
+ Replicas uint32 `json:"replicas"`
+ Services []PoolSpecService `json:"services,omitempty"`
+ Template PoolTemplate `json:"template"`
+}
+
+type PoolSpecAutoscaling struct {
+ InitialPoolSize *uint32 `json:"initialPoolSize,omitempty"`
+ MaxPoolSize *uint32 `json:"maxPoolSize,omitempty"`
+ MinPoolSize *uint32 `json:"minPoolSize,omitempty"`
+}
+
+type PoolSpecService struct {
+ Name string `json:"name"`
+ Protocol *PoolSpecServiceProtocol `json:"protocol,omitempty"`
+ TargetPort uint32 `json:"targetPort"`
+}
+
+type PoolSpecServiceProtocol string
+
+const (
+ PoolSpecServiceProtocolTCP PoolSpecServiceProtocol = "TCP"
+ PoolSpecServiceProtocolUDP PoolSpecServiceProtocol = "UDP"
+)
+
+type PoolTemplate struct {
+ Command []string `json:"command,omitempty"`
+ ContainerDiskImage string `json:"containerDiskImage"`
+ CpuCores *uint32 `json:"cpuCores,omitempty"`
+ Firmware *PoolTemplateFirmware `json:"firmware,omitempty"`
+ ImagePullSecret *string `json:"imagePullSecret,omitempty"`
+ Memory *string `json:"memory,omitempty"`
+ NodeSelector map[string]string `json:"nodeSelector,omitempty"`
+ Oidc *PoolTemplateOidc `json:"oidc,omitempty"`
+ Probes any `json:"probes,omitempty"`
+ Runtime *PoolTemplateRuntime `json:"runtime,omitempty"`
+ RuntimeClassName *string `json:"runtimeClassName,omitempty"`
+ Tolerations []any `json:"tolerations,omitempty"`
+}
+
+type PoolTemplateFirmware string
+
+const (
+ PoolTemplateFirmwareBios PoolTemplateFirmware = "bios"
+ PoolTemplateFirmwareEfi PoolTemplateFirmware = "efi"
+)
+
+type PoolTemplateOidc struct {
+ AwsRegion *string `json:"awsRegion,omitempty"`
+ AwsRoleArn *string `json:"awsRoleArn,omitempty"`
+ CredentialsSecret string `json:"credentialsSecret"`
+ RefreshIntervalSeconds *uint32 `json:"refreshIntervalSeconds,omitempty"`
+ TokenUrl string `json:"tokenUrl"`
+}
+
+type PoolTemplateRuntime string
+
+const (
+ PoolTemplateRuntimeKubevirt PoolTemplateRuntime = "kubevirt"
+ PoolTemplateRuntimeMacos PoolTemplateRuntime = "macos"
+ PoolTemplateRuntimeGvisor PoolTemplateRuntime = "gvisor"
+)
+
+type SandboxTemplateRef struct {
+ Name string `json:"name"`
+}
diff --git a/libs/fleet/sdk-bindings/go/go.mod b/libs/fleet/sdk-bindings/go/go.mod
new file mode 100644
index 0000000000..54d0750622
--- /dev/null
+++ b/libs/fleet/sdk-bindings/go/go.mod
@@ -0,0 +1,3 @@
+module github.com/trycua/cloud/cyclops-cs/sdk-bindings/go
+
+go 1.23.6
diff --git a/libs/fleet/sdk-bindings/go/public_api_test.go b/libs/fleet/sdk-bindings/go/public_api_test.go
new file mode 100644
index 0000000000..6e729748d8
--- /dev/null
+++ b/libs/fleet/sdk-bindings/go/public_api_test.go
@@ -0,0 +1,52 @@
+package cyclopssdk
+
+import (
+ "net/http"
+ "testing"
+)
+
+func TestTypedResourceAPIOnly(t *testing.T) {
+ var _ func(Configuration) (*SDK, error) = Connect
+ var _ func(*SDK, CreatePoolRequest) (Pool, error) = (*SDK).CreatePool
+ var _ func(*SDK, string) ([]Pool, error) = (*SDK).ListPools
+ var _ func(*SDK, Pool) (Pool, error) = (*SDK).GetPool
+ var _ func(*SDK, Pool) (Pool, error) = (*SDK).UpdatePool
+ var _ func(*SDK, Pool) error = (*SDK).DeletePool
+ var _ func(*SDK, CreateClaimRequest) (Claim, error) = (*SDK).CreateClaim
+ var _ func(*SDK, string) ([]Claim, error) = (*SDK).ListClaims
+ var _ func(*SDK, Claim) (Claim, error) = (*SDK).GetClaim
+ var _ func(*SDK, Claim) (Claim, error) = (*SDK).UpdateClaim
+ var _ func(*SDK, Claim) error = (*SDK).DeleteClaim
+ var _ func(*SDK, Claim) (Sandbox, error) = (*SDK).WaitClaim
+ var _ func(*SDK, Sandbox, string) (*ServiceClient, error) = (*SDK).ServiceClient
+ var _ func(*ServiceClient, *http.Request) (*http.Response, error) = (*ServiceClient).Do
+ var _ func(*SDK) error = (*SDK).Close
+}
+
+func TestUnknownServiceErrorListsAvailableNames(t *testing.T) {
+ _, err := (&SDK{}).ServiceClient(Sandbox{Services: []string{"novnc", "mcp", "mcp"}}, "metrics")
+ serviceErr, ok := err.(*UnknownServiceError)
+ if !ok {
+ t.Fatalf("error = %T, want *UnknownServiceError", err)
+ }
+ if serviceErr.Requested != "metrics" {
+ t.Fatalf("requested = %q", serviceErr.Requested)
+ }
+ if got := serviceErr.Available; len(got) != 2 || got[0] != "mcp" || got[1] != "novnc" {
+ t.Fatalf("available = %v", got)
+ }
+}
+
+func TestServiceClientBuildsRelativeRequests(t *testing.T) {
+ client := &ServiceClient{}
+ request, err := client.NewRequest("POST", "/mcp?session=one", nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if request.URL.IsAbs() || request.URL.Host != "" {
+ t.Fatalf("URL = %s, want relative", request.URL)
+ }
+ if path, err := relativeRequestPath(request.URL); err != nil || path != "/mcp?session=one" {
+ t.Fatalf("path = %q, err = %v", path, err)
+ }
+}
diff --git a/libs/fleet/sdk-bindings/go/sdk.go b/libs/fleet/sdk-bindings/go/sdk.go
new file mode 100644
index 0000000000..14b1f951d3
--- /dev/null
+++ b/libs/fleet/sdk-bindings/go/sdk.go
@@ -0,0 +1,361 @@
+package cyclopssdk
+
+import (
+ "bufio"
+ "bytes"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "net/url"
+ "os"
+ "os/exec"
+ "sort"
+ "strings"
+ "time"
+)
+
+type OAuthConfiguration struct {
+ TokenURL string `json:"token_url"`
+ ClientID string `json:"client_id"`
+ ClientSecret string `json:"client_secret"`
+}
+type Configuration struct {
+ BaseURL string `json:"base_url"`
+ OAuth OAuthConfiguration `json:"oauth"`
+}
+type ResourceMetadata struct {
+ Namespace string `json:"namespace"`
+ Name string `json:"name"`
+ Labels map[string]string `json:"labels,omitempty"`
+}
+type Pool struct {
+ APIVersion string `json:"apiVersion"`
+ Kind string `json:"kind"`
+ Metadata ResourceMetadata `json:"metadata"`
+ Spec map[string]any `json:"spec"`
+ Status map[string]any `json:"status,omitempty"`
+}
+type Claim struct {
+ APIVersion string `json:"apiVersion"`
+ Kind string `json:"kind"`
+ Metadata ResourceMetadata `json:"metadata"`
+ Spec map[string]any `json:"spec"`
+ Status map[string]any `json:"status,omitempty"`
+}
+type Sandbox struct {
+ Namespace string `json:"namespace"`
+ Claim string `json:"claim"`
+ Sandbox string `json:"sandbox"`
+ Services []string `json:"services"`
+}
+type CreatePoolRequest struct {
+ Namespace string `json:"namespace"`
+ Spec PoolSpec `json:"spec"`
+}
+type CreateClaimRequest struct {
+ Pool Pool `json:"pool"`
+ Spec *ClaimSpec `json:"spec,omitempty"`
+}
+type serviceRequest struct {
+ Method string `json:"method"`
+ Path string `json:"path"`
+ Headers [][2]string `json:"headers"`
+ Body *string `json:"body,omitempty"`
+}
+type serviceResponse struct {
+ Status int `json:"status"`
+ Body string `json:"body"`
+}
+type UnknownServiceError struct {
+ Requested string
+ Available []string
+}
+
+func (error *UnknownServiceError) Error() string {
+ return fmt.Sprintf("unknown sandbox service %q; available services: %v", error.Requested, error.Available)
+}
+
+type SDK struct {
+ configuration Configuration
+ command *exec.Cmd
+ input io.WriteCloser
+ output *bufio.Reader
+ token map[string]any
+}
+type ServiceClient struct {
+ sdk *SDK
+ sandbox Sandbox
+ service string
+}
+
+type hostCall struct {
+ Kind string `json:"kind"`
+ Request *struct {
+ Method string `json:"method"`
+ URL string `json:"url"`
+ Headers [][2]string `json:"headers"`
+ Body *string `json:"body"`
+ } `json:"request,omitempty"`
+ Milliseconds int64 `json:"milliseconds,omitempty"`
+ Token map[string]any `json:"token,omitempty"`
+}
+type reply struct {
+ OK bool `json:"ok"`
+ Value json.RawMessage `json:"value"`
+ Error string `json:"error,omitempty"`
+}
+
+func Connect(configuration Configuration) (*SDK, error) {
+ command := exec.Command(env("CYCLOPS_CORE_RUNNER", "cyclops-core-runner"))
+ input, err := command.StdinPipe()
+ if err != nil {
+ return nil, err
+ }
+ output, err := command.StdoutPipe()
+ if err != nil {
+ return nil, err
+ }
+ command.Stderr = os.Stderr
+ if err := command.Start(); err != nil {
+ return nil, err
+ }
+ sdk := &SDK{configuration: configuration, command: command, input: input, output: bufio.NewReader(output)}
+ if err := sdk.call(map[string]any{"op": "configure", "configuration": map[string]any{"protocol_version": 7, "base_url": configuration.BaseURL}}, nil); err != nil {
+ _ = sdk.Close()
+ return nil, err
+ }
+ return sdk, nil
+}
+func (sdk *SDK) CreatePool(request CreatePoolRequest) (Pool, error) {
+ var value Pool
+ return value, sdk.call(map[string]any{"op": "create_pool", "request": request}, &value)
+}
+func (sdk *SDK) ListPools(namespace string) ([]Pool, error) {
+ var value []Pool
+ return value, sdk.call(map[string]any{"op": "list_pools", "namespace": namespace}, &value)
+}
+func (sdk *SDK) GetPool(pool Pool) (Pool, error) {
+ var value Pool
+ return value, sdk.call(map[string]any{"op": "get_pool", "pool": pool}, &value)
+}
+func (sdk *SDK) UpdatePool(pool Pool) (Pool, error) {
+ var value Pool
+ return value, sdk.call(map[string]any{"op": "update_pool", "pool": pool}, &value)
+}
+func (sdk *SDK) DeletePool(pool Pool) error {
+ return sdk.call(map[string]any{"op": "delete_pool", "pool": pool}, nil)
+}
+func (sdk *SDK) CreateClaim(request CreateClaimRequest) (Claim, error) {
+ var value Claim
+ return value, sdk.call(map[string]any{"op": "create_claim", "request": request}, &value)
+}
+func (sdk *SDK) ListClaims(namespace string) ([]Claim, error) {
+ var value []Claim
+ return value, sdk.call(map[string]any{"op": "list_claims", "namespace": namespace}, &value)
+}
+func (sdk *SDK) GetClaim(claim Claim) (Claim, error) {
+ var value Claim
+ return value, sdk.call(map[string]any{"op": "get_claim", "claim": claim}, &value)
+}
+func (sdk *SDK) UpdateClaim(claim Claim) (Claim, error) {
+ var value Claim
+ return value, sdk.call(map[string]any{"op": "update_claim", "claim": claim}, &value)
+}
+func (sdk *SDK) DeleteClaim(claim Claim) error {
+ return sdk.call(map[string]any{"op": "delete_claim", "claim": claim}, nil)
+}
+func (sdk *SDK) WaitClaim(claim Claim) (Sandbox, error) {
+ var value Sandbox
+ return value, sdk.call(map[string]any{"op": "wait_claim", "claim": claim}, &value)
+}
+func (sdk *SDK) ServiceClient(sandbox Sandbox, service string) (*ServiceClient, error) {
+ available := append([]string(nil), sandbox.Services...)
+ sort.Strings(available)
+ available = compactStrings(available)
+ for _, candidate := range available {
+ if candidate == service {
+ return &ServiceClient{sdk: sdk, sandbox: sandbox, service: service}, nil
+ }
+ }
+ return nil, &UnknownServiceError{Requested: service, Available: available}
+}
+func (client *ServiceClient) NewRequest(method, path string, body io.Reader) (*http.Request, error) {
+ if err := validateServicePath(path); err != nil {
+ return nil, err
+ }
+ request, err := http.NewRequest(method, "https://cyclops.invalid"+path, body)
+ if err != nil {
+ return nil, err
+ }
+ request.URL.Scheme = ""
+ request.URL.Host = ""
+ request.Host = ""
+ return request, nil
+}
+func (client *ServiceClient) Do(request *http.Request) (*http.Response, error) {
+ path, err := relativeRequestPath(request.URL)
+ if err != nil {
+ return nil, err
+ }
+ var body *string
+ if request.Body != nil {
+ data, readErr := io.ReadAll(request.Body)
+ if readErr != nil {
+ return nil, readErr
+ }
+ value := string(data)
+ body = &value
+ }
+ headers := make([][2]string, 0, len(request.Header))
+ for name, values := range request.Header {
+ for _, value := range values {
+ headers = append(headers, [2]string{name, value})
+ }
+ }
+ var response serviceResponse
+ err = client.sdk.call(map[string]any{
+ "op": "service_request",
+ "sandbox": client.sandbox,
+ "service": client.service,
+ "request": serviceRequest{Method: request.Method, Path: path, Headers: headers, Body: body},
+ }, &response)
+ if err != nil {
+ return nil, err
+ }
+ return &http.Response{
+ StatusCode: response.Status,
+ Status: fmt.Sprintf("%d %s", response.Status, http.StatusText(response.Status)),
+ Header: make(http.Header),
+ Body: io.NopCloser(strings.NewReader(response.Body)),
+ Request: request,
+ }, nil
+}
+func (sdk *SDK) Close() error {
+ if sdk.input != nil {
+ _ = sdk.input.Close()
+ }
+ if sdk.command != nil {
+ return sdk.command.Wait()
+ }
+ return nil
+}
+
+func (sdk *SDK) call(request any, result any) error {
+ if err := json.NewEncoder(sdk.input).Encode(request); err != nil {
+ return err
+ }
+ for {
+ line, err := sdk.output.ReadBytes('\n')
+ if err != nil {
+ return err
+ }
+ var message map[string]json.RawMessage
+ if err := json.Unmarshal(line, &message); err != nil {
+ return err
+ }
+ if kindRaw, ok := message["kind"]; ok {
+ var call hostCall
+ if err := json.Unmarshal(line, &call); err != nil {
+ return err
+ }
+ value, dispatchErr := sdk.dispatch(call)
+ response := map[string]any{"ok": dispatchErr == nil, "value": value}
+ if dispatchErr != nil {
+ response["error"] = map[string]string{"transport": dispatchErr.Error()}
+ }
+ if err := json.NewEncoder(sdk.input).Encode(response); err != nil {
+ return err
+ }
+ _ = kindRaw
+ continue
+ }
+ var response reply
+ if err := json.Unmarshal(line, &response); err != nil {
+ return err
+ }
+ if !response.OK {
+ return fmt.Errorf("%s", response.Error)
+ }
+ if result != nil && len(response.Value) > 0 && string(response.Value) != "null" {
+ return json.Unmarshal(response.Value, result)
+ }
+ return nil
+ }
+}
+func (sdk *SDK) dispatch(call hostCall) (any, error) {
+ switch call.Kind {
+ case "http":
+ body := io.Reader(nil)
+ if call.Request.Body != nil {
+ body = bytes.NewBufferString(*call.Request.Body)
+ }
+ request, err := http.NewRequest(call.Request.Method, call.Request.URL, body)
+ if err != nil {
+ return nil, err
+ }
+ for _, header := range call.Request.Headers {
+ request.Header.Add(header[0], header[1])
+ }
+ client := &http.Client{CheckRedirect: func(_ *http.Request, _ []*http.Request) error { return http.ErrUseLastResponse }}
+ response, err := client.Do(request)
+ if err != nil {
+ return nil, err
+ }
+ defer response.Body.Close()
+ data, err := io.ReadAll(response.Body)
+ return map[string]any{"status": response.StatusCode, "body": string(data)}, err
+ case "sleep":
+ time.Sleep(time.Duration(call.Milliseconds) * time.Millisecond)
+ return nil, nil
+ case "now_ms":
+ return time.Now().UnixMilli(), nil
+ case "acquire_oauth_credentials":
+ return map[string]string{"token_url": sdk.configuration.OAuth.TokenURL, "client_id": sdk.configuration.OAuth.ClientID, "client_secret": sdk.configuration.OAuth.ClientSecret}, nil
+ case "load_access_token":
+ return sdk.token, nil
+ case "store_access_token":
+ sdk.token = call.Token
+ return nil, nil
+ default:
+ return nil, fmt.Errorf("unknown host call %s", call.Kind)
+ }
+}
+func validateServicePath(path string) error {
+ if !strings.HasPrefix(path, "/") || strings.HasPrefix(path, "//") || strings.Contains(path, "#") {
+ return fmt.Errorf("service request path must be relative and start with '/': %s", path)
+ }
+ return nil
+}
+func relativeRequestPath(value *url.URL) (string, error) {
+ if value == nil || value.IsAbs() || value.Host != "" {
+ return "", fmt.Errorf("service requests must use relative URLs")
+ }
+ path := value.EscapedPath()
+ if path == "" {
+ path = "/"
+ }
+ if value.RawQuery != "" {
+ path += "?" + value.RawQuery
+ }
+ return path, validateServicePath(path)
+}
+func compactStrings(values []string) []string {
+ if len(values) == 0 {
+ return values
+ }
+ result := values[:1]
+ for _, value := range values[1:] {
+ if value != result[len(result)-1] {
+ result = append(result, value)
+ }
+ }
+ return result
+}
+
+func env(name, fallback string) string {
+ if value := os.Getenv(name); value != "" {
+ return value
+ }
+ return fallback
+}
diff --git a/libs/fleet/sdk-bindings/python/cyclops_sdk/__init__.py b/libs/fleet/sdk-bindings/python/cyclops_sdk/__init__.py
new file mode 100644
index 0000000000..3e538570f0
--- /dev/null
+++ b/libs/fleet/sdk-bindings/python/cyclops_sdk/__init__.py
@@ -0,0 +1,226 @@
+import json
+import logging
+import os
+import subprocess
+import time
+import urllib.error
+import urllib.request
+from typing import Any, NotRequired, TypedDict
+
+import httpx
+
+from .generated_crd import (
+ ClaimSpec as ClaimSpec,
+ ClaimSpecLifecycle as ClaimSpecLifecycle,
+ PoolSpec as PoolSpec,
+ PoolSpecAutoscaling as PoolSpecAutoscaling,
+ PoolSpecService as PoolSpecService,
+ PoolSpecServiceProtocol as PoolSpecServiceProtocol,
+ PoolTemplate as PoolTemplate,
+ PoolTemplateFirmware as PoolTemplateFirmware,
+ PoolTemplateOidc as PoolTemplateOidc,
+ PoolTemplateRuntime as PoolTemplateRuntime,
+ SandboxTemplateRef as SandboxTemplateRef,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ResourceMetadata(TypedDict):
+ namespace: str
+ name: str
+ labels: NotRequired[dict[str, str]]
+
+
+class Pool(TypedDict):
+ apiVersion: str
+ kind: str
+ metadata: ResourceMetadata
+ spec: dict[str, Any]
+ status: NotRequired[dict[str, Any]]
+
+
+class Claim(TypedDict):
+ apiVersion: str
+ kind: str
+ metadata: ResourceMetadata
+ spec: dict[str, Any]
+ status: NotRequired[dict[str, Any]]
+
+
+class Sandbox(TypedDict):
+ namespace: str
+ claim: str
+ sandbox: str
+ services: list[str]
+
+
+class CreatePoolRequest(TypedDict):
+ namespace: str
+ spec: PoolSpec
+
+
+class CreateClaimRequest(TypedDict):
+ pool: Pool
+ spec: NotRequired[ClaimSpec]
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+ def redirect_request(self, *_args):
+ return None
+
+
+class UnknownServiceError(ValueError):
+ def __init__(self, requested: str, available: list[str]):
+ self.requested = requested
+ self.available = available
+ super().__init__(
+ f"unknown sandbox service {requested!r}; available services: {available!r}"
+ )
+
+
+class _ServiceTransport(httpx.BaseTransport):
+ def __init__(self, sdk, sandbox: Sandbox, service: str):
+ self._sdk = sdk
+ self._sandbox = sandbox
+ self._service = service
+
+ def handle_request(self, request: httpx.Request) -> httpx.Response:
+ path = request.url.raw_path.decode("ascii")
+ if not path.startswith("/") or path.startswith("//") or "#" in path:
+ raise ValueError(
+ f"service request path must be relative and start with '/': {path}"
+ )
+ body = request.read()
+ response = self._sdk._call({
+ "op": "service_request",
+ "sandbox": self._sandbox,
+ "service": self._service,
+ "request": {
+ "method": request.method,
+ "path": path,
+ "headers": list(request.headers.multi_items()),
+ "body": body.decode("utf-8") if body else None,
+ },
+ })
+ return httpx.Response(
+ response["status"],
+ content=response["body"].encode(),
+ request=request,
+ )
+
+
+class SDK:
+ def __init__(self, configuration):
+ self._configuration = configuration
+ self._token = None
+ self._process = subprocess.Popen(
+ [os.environ.get("CYCLOPS_CORE_RUNNER", "cyclops-core-runner")],
+ stdin=subprocess.PIPE,
+ stdout=subprocess.PIPE,
+ text=True,
+ )
+ try:
+ self._call({"op": "configure", "configuration": {"protocol_version": 7, "base_url": configuration["base_url"]}})
+ except BaseException:
+ self.close()
+ raise
+
+ def create_pool(self, request: CreatePoolRequest) -> Pool:
+ return self._call({"op": "create_pool", "request": request})
+
+ def list_pools(self, namespace: str) -> list[Pool]:
+ return self._call({"op": "list_pools", "namespace": namespace})
+
+ def get_pool(self, pool: Pool) -> Pool:
+ return self._call({"op": "get_pool", "pool": pool})
+
+ def update_pool(self, pool: Pool) -> Pool:
+ return self._call({"op": "update_pool", "pool": pool})
+
+ def delete_pool(self, pool: Pool) -> None:
+ self._call({"op": "delete_pool", "pool": pool})
+
+ def create_claim(self, request: CreateClaimRequest) -> Claim:
+ return self._call({"op": "create_claim", "request": request})
+
+ def list_claims(self, namespace: str) -> list[Claim]:
+ return self._call({"op": "list_claims", "namespace": namespace})
+
+ def get_claim(self, claim: Claim) -> Claim:
+ return self._call({"op": "get_claim", "claim": claim})
+
+ def update_claim(self, claim: Claim) -> Claim:
+ return self._call({"op": "update_claim", "claim": claim})
+
+ def delete_claim(self, claim: Claim) -> None:
+ self._call({"op": "delete_claim", "claim": claim})
+
+ def wait_claim(self, claim: Claim) -> Sandbox:
+ return self._call({"op": "wait_claim", "claim": claim})
+
+ def service_client(self, sandbox: Sandbox, service: str) -> httpx.Client:
+ available = sorted(set(sandbox["services"]))
+ if service not in available:
+ raise UnknownServiceError(service, available)
+ return httpx.Client(
+ base_url="https://cyclops.invalid",
+ transport=_ServiceTransport(self, sandbox, service),
+ )
+
+ def close(self):
+ if self._process.poll() is None:
+ self._process.stdin.close()
+ self._process.terminate()
+ self._process.wait()
+
+ def _call(self, request):
+ self._process.stdin.write(json.dumps(request) + "\n")
+ self._process.stdin.flush()
+ for line in self._process.stdout:
+ message = json.loads(line)
+ if "kind" not in message:
+ if not message["ok"]:
+ raise RuntimeError(message.get("error", "core operation failed"))
+ return message.get("value")
+ try:
+ value = self._dispatch(message)
+ reply = {"ok": True, "value": value}
+ except BaseException as error:
+ logger.warning("Cyclops host call failed: %s", error)
+ reply = {"ok": False, "error": {"transport": str(error)}}
+ self._process.stdin.write(json.dumps(reply) + "\n")
+ self._process.stdin.flush()
+ raise RuntimeError("core runner exited")
+
+ def _dispatch(self, message):
+ kind = message["kind"]
+ if kind == "http":
+ request = message["request"]
+ body = request.get("body")
+ http_request = urllib.request.Request(request["url"], data=body.encode() if body is not None else None, headers=dict(request["headers"]), method=request["method"])
+ opener = urllib.request.build_opener(_NoRedirect())
+ try:
+ with opener.open(http_request, timeout=30) as response:
+ return {"status": response.status, "body": response.read().decode()}
+ except urllib.error.HTTPError as error:
+ logger.debug("HTTP request returned status %s", error.code)
+ return {"status": error.code, "body": error.read().decode()}
+ if kind == "sleep":
+ time.sleep(message["milliseconds"] / 1000)
+ return None
+ if kind == "now_ms":
+ return int(time.time() * 1000)
+ if kind == "acquire_oauth_credentials":
+ oauth = self._configuration["oauth"]
+ return {"token_url": oauth["token_url"], "client_id": oauth["client_id"], "client_secret": oauth["client_secret"]}
+ if kind == "load_access_token":
+ return self._token
+ if kind == "store_access_token":
+ self._token = message["token"]
+ return None
+ raise RuntimeError(f"unknown host call {kind}")
+
+
+def connect(configuration):
+ return SDK(configuration)
diff --git a/libs/fleet/sdk-bindings/python/cyclops_sdk/generated_crd.py b/libs/fleet/sdk-bindings/python/cyclops_sdk/generated_crd.py
new file mode 100644
index 0000000000..c928464606
--- /dev/null
+++ b/libs/fleet/sdk-bindings/python/cyclops_sdk/generated_crd.py
@@ -0,0 +1,62 @@
+# Code generated from clusters/base/osgym/crd.yaml; DO NOT EDIT.
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, TypedDict
+
+class ClaimSpec(TypedDict):
+ bindDeadline: NotRequired[int]
+ lifecycle: NotRequired[ClaimSpecLifecycle]
+ sandboxTemplateRef: SandboxTemplateRef
+ warmpool: NotRequired[str]
+
+class ClaimSpecLifecycle(TypedDict):
+ autoRenew: NotRequired[bool]
+ shutdownPolicy: NotRequired[str]
+ shutdownTime: NotRequired[str]
+
+class PoolSpec(TypedDict):
+ autoscaling: NotRequired[PoolSpecAutoscaling]
+ replicas: int
+ services: NotRequired[list[PoolSpecService]]
+ template: PoolTemplate
+
+class PoolSpecAutoscaling(TypedDict):
+ initialPoolSize: NotRequired[int]
+ maxPoolSize: NotRequired[int]
+ minPoolSize: NotRequired[int]
+
+class PoolSpecService(TypedDict):
+ name: str
+ protocol: NotRequired[PoolSpecServiceProtocol]
+ targetPort: int
+
+PoolSpecServiceProtocol = Literal["TCP", "UDP"]
+
+class PoolTemplate(TypedDict):
+ command: NotRequired[list[str]]
+ containerDiskImage: str
+ cpuCores: NotRequired[int]
+ firmware: NotRequired[PoolTemplateFirmware]
+ imagePullSecret: NotRequired[str]
+ memory: NotRequired[str]
+ nodeSelector: NotRequired[dict[str, str]]
+ oidc: NotRequired[PoolTemplateOidc]
+ probes: NotRequired[Any]
+ runtime: NotRequired[PoolTemplateRuntime]
+ runtimeClassName: NotRequired[str]
+ tolerations: NotRequired[list[Any]]
+
+PoolTemplateFirmware = Literal["bios", "efi"]
+
+class PoolTemplateOidc(TypedDict):
+ awsRegion: NotRequired[str]
+ awsRoleArn: NotRequired[str]
+ credentialsSecret: str
+ refreshIntervalSeconds: NotRequired[int]
+ tokenUrl: str
+
+PoolTemplateRuntime = Literal["kubevirt", "macos", "gvisor"]
+
+class SandboxTemplateRef(TypedDict):
+ name: str
+
diff --git a/libs/fleet/sdk-bindings/python/pyproject.toml b/libs/fleet/sdk-bindings/python/pyproject.toml
new file mode 100644
index 0000000000..358a217b9d
--- /dev/null
+++ b/libs/fleet/sdk-bindings/python/pyproject.toml
@@ -0,0 +1,10 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+[project]
+name = "cyclops-sdk"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1"]
+[tool.hatch.build.targets.wheel]
+packages = ["cyclops_sdk"]
diff --git a/libs/fleet/sdk-bindings/python/tests/test_examples.py b/libs/fleet/sdk-bindings/python/tests/test_examples.py
new file mode 100644
index 0000000000..c6704b226e
--- /dev/null
+++ b/libs/fleet/sdk-bindings/python/tests/test_examples.py
@@ -0,0 +1,112 @@
+from pathlib import Path
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[3]
+EXAMPLES = {
+ "python": ROOT / "sdk-bindings/examples/python/app_controlled.py",
+ "typescript": ROOT / "sdk-bindings/examples/typescript/app-controlled.ts",
+ "go": ROOT / "sdk-bindings/go/examples/app_controlled.go",
+ "rust": ROOT / "sdk-bindings/rust/examples/app_controlled.rs",
+}
+
+
+class ExampleContractTest(unittest.TestCase):
+ def test_examples_use_app_controlled_sequence(self):
+ sequences = {
+ "python": ["connect(", "create_pool(", "create_claim(", "wait_claim(", "run_agent(sdk, sandbox)", "print(", "finally:", "delete_claim(", "delete_pool(", "close("],
+ "typescript": ["connect(", "createPool(", "createClaim(", "waitClaim(", "runAgent(sdk, sandbox)", "console.log(", "finally {", "deleteClaim(", "deletePool(", "close("],
+ "go": ["Connect(", "sdk.Close()", "CreatePool(", "sdk.DeletePool(pool)", "CreateClaim(", "sdk.DeleteClaim(claim)", "WaitClaim(", "runAgent(sdk, sandbox)", "fmt.Println("],
+ "rust": ["Sdk::connect(", "create_pool(", "create_claim(", "wait_claim(", "run_agent(&mut sdk, sandbox)", "println!(", "delete_claim(", "delete_pool(", "close("],
+ }
+ for language, path in EXAMPLES.items():
+ source = path.read_text(encoding="utf-8")
+ flow = source[source.index("def main"):] if language == "python" else source[source.index("const sdk"):] if language == "typescript" else source[source.index("func main"):] if language == "go" else source[source.index("fn main"):]
+ positions = [flow.index(token) for token in sequences[language]]
+ self.assertEqual(positions, sorted(positions), language)
+ self.assertIn("initialize", source, language)
+ self.assertRegex(source, r"service_client|serviceFetch|ServiceClient", language)
+ self.assertIn("/mcp", source, language)
+ self.assertNotIn("external run_agent", source.lower(), language)
+
+ def test_examples_emit_machine_readable_resource_results(self):
+ tokens = {
+ "python": ['sandbox["claim"]', "json.dumps(result"],
+ "typescript": ["sandbox.claim", "JSON.stringify(result)"],
+ "go": ["sandbox.Claim", "json.Marshal(result)"],
+ "rust": ['"claim": sandbox.claim', 'println!("{result}")'],
+ }
+ for language, path in EXAMPLES.items():
+ source = path.read_text(encoding="utf-8")
+ for token in tokens[language]:
+ self.assertIn(token, source, language)
+
+
+ def test_examples_create_mcp_service_alias(self):
+ tokens = {
+ "python": ['"services": [{"name": "mcp", "targetPort": 3000, "protocol": "TCP"}]'],
+ "typescript": ['services: [{ name: "mcp", targetPort: 3000, protocol: "TCP" }]'],
+ "go": ['Services: []cyclopssdk.PoolSpecService{', 'Name: "mcp"', 'TargetPort: 3000'],
+ "rust": ['PoolSpecService::builder()', '.name("mcp".into())', '.target_port(3000)'],
+ }
+ for language, path in EXAMPLES.items():
+ source = path.read_text(encoding="utf-8")
+ for token in tokens[language]:
+ self.assertIn(token, source, language)
+
+ def test_examples_retry_transient_mcp_gateway_errors(self):
+ tokens = {
+ "python": ["time.monotonic()", "(502, 503, 504)", "time.sleep("],
+ "typescript": ["Date.now()", "[502, 503, 504]", "setTimeout"],
+ "go": ["time.Now()", "response.StatusCode == 502", "time.Sleep("],
+ "rust": ["Instant::now()", "matches!(response.status, 502..=504)", "thread::sleep("],
+ }
+ for language, path in EXAMPLES.items():
+ source = path.read_text(encoding="utf-8")
+ for token in tokens[language]:
+ self.assertIn(token, source, language)
+
+ def test_examples_use_named_service_clients_with_relative_paths(self):
+ tokens = {
+ "python": ['service_client(sandbox, "mcp")', "mcp.post(", '"/mcp"'],
+ "typescript": ['serviceFetch(sandbox, "mcp")', 'mcp("/mcp"'],
+ "go": ['ServiceClient(sandbox, "mcp")', 'NewRequest("POST", "/mcp"'],
+ "rust": ['service_client(&sandbox, "mcp")', '.post("/mcp")'],
+ }
+ prohibited = ["mcp_url", "MCPURL", "mcpUrl", "-mcp"]
+ for language, path in EXAMPLES.items():
+ source = path.read_text(encoding="utf-8")
+ for token in tokens[language]:
+ self.assertIn(token, source, language)
+ for token in prohibited:
+ self.assertNotIn(token, source, language)
+
+ def test_bindings_do_not_expose_url_based_http_clients(self):
+ binding_files = [
+ ROOT / "sdk-bindings/python/cyclops_sdk/__init__.py",
+ ROOT / "sdk-bindings/typescript/src/index.ts",
+ ROOT / "sdk-bindings/go/sdk.go",
+ ROOT / "sdk-bindings/rust/src/lib.rs",
+ ROOT / "sdk-core/wit/cyclops-sdk.wit",
+ ]
+ prohibited = ["raw_client", "rawClient", "RawClient", "raw-request", '"raw_request"']
+ for path in binding_files:
+ source = path.read_text(encoding="utf-8")
+ for token in prohibited:
+ self.assertNotIn(token, source, path)
+
+ def test_private_image_examples_pass_pull_secret(self):
+ tokens = {
+ "python": ['os.environ["CUA_IMAGE_PULL_SECRET"]', '"imagePullSecret"'],
+ "typescript": ['required("CUA_IMAGE_PULL_SECRET")', 'imagePullSecret'],
+ "go": ['required("CUA_IMAGE_PULL_SECRET")', 'ImagePullSecret'],
+ "rust": ['required("CUA_IMAGE_PULL_SECRET")', '.image_pull_secret('],
+ }
+ for language, path in EXAMPLES.items():
+ source = path.read_text(encoding="utf-8")
+ for token in tokens[language]:
+ self.assertIn(token, source, language)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/libs/fleet/sdk-bindings/python/tests/test_public_api.py b/libs/fleet/sdk-bindings/python/tests/test_public_api.py
new file mode 100644
index 0000000000..4426f7593a
--- /dev/null
+++ b/libs/fleet/sdk-bindings/python/tests/test_public_api.py
@@ -0,0 +1,104 @@
+import inspect
+import unittest
+
+import cyclops_sdk
+import httpx
+
+
+class PublicApiTest(unittest.TestCase):
+ def test_typed_resource_api_only(self):
+ self.assertEqual(list(inspect.signature(cyclops_sdk.connect).parameters), ["configuration"])
+ expected = {
+ "create_pool": ["self", "request"],
+ "list_pools": ["self", "namespace"],
+ "get_pool": ["self", "pool"],
+ "update_pool": ["self", "pool"],
+ "delete_pool": ["self", "pool"],
+ "create_claim": ["self", "request"],
+ "list_claims": ["self", "namespace"],
+ "get_claim": ["self", "claim"],
+ "update_claim": ["self", "claim"],
+ "delete_claim": ["self", "claim"],
+ "wait_claim": ["self", "claim"],
+ "service_client": ["self", "sandbox", "service"],
+ "close": ["self"],
+ }
+ public = {
+ name: value
+ for name, value in inspect.getmembers(cyclops_sdk.SDK, inspect.isfunction)
+ if not name.startswith("_")
+ }
+ self.assertEqual(set(public), set(expected))
+ for name, parameters in expected.items():
+ self.assertEqual(list(inspect.signature(public[name]).parameters), parameters)
+ expected_annotations = {
+ "create_pool": ({"request": cyclops_sdk.CreatePoolRequest}, cyclops_sdk.Pool),
+ "list_pools": ({"namespace": str}, list[cyclops_sdk.Pool]),
+ "get_pool": ({"pool": cyclops_sdk.Pool}, cyclops_sdk.Pool),
+ "update_pool": ({"pool": cyclops_sdk.Pool}, cyclops_sdk.Pool),
+ "delete_pool": ({"pool": cyclops_sdk.Pool}, None),
+ "create_claim": ({"request": cyclops_sdk.CreateClaimRequest}, cyclops_sdk.Claim),
+ "list_claims": ({"namespace": str}, list[cyclops_sdk.Claim]),
+ "get_claim": ({"claim": cyclops_sdk.Claim}, cyclops_sdk.Claim),
+ "update_claim": ({"claim": cyclops_sdk.Claim}, cyclops_sdk.Claim),
+ "delete_claim": ({"claim": cyclops_sdk.Claim}, None),
+ "wait_claim": ({"claim": cyclops_sdk.Claim}, cyclops_sdk.Sandbox),
+ "service_client": ({"sandbox": cyclops_sdk.Sandbox, "service": str}, httpx.Client),
+ }
+ for name, (parameters, return_annotation) in expected_annotations.items():
+ signature = inspect.signature(public[name])
+ self.assertEqual(
+ {parameter: signature.parameters[parameter].annotation for parameter in parameters},
+ parameters,
+ )
+ self.assertEqual(signature.return_annotation, return_annotation)
+ self.assertFalse(hasattr(cyclops_sdk, "RawClient"))
+ self.assertTrue(hasattr(cyclops_sdk, "CreatePoolRequest"))
+ self.assertTrue(hasattr(cyclops_sdk, "CreateClaimRequest"))
+ self.assertTrue(hasattr(cyclops_sdk, "Pool"))
+ self.assertTrue(hasattr(cyclops_sdk, "PoolSpec"))
+ self.assertTrue(hasattr(cyclops_sdk, "Claim"))
+ self.assertTrue(hasattr(cyclops_sdk, "ClaimSpec"))
+ self.assertTrue(hasattr(cyclops_sdk, "Sandbox"))
+ self.assertTrue(issubclass(cyclops_sdk.UnknownServiceError, ValueError))
+
+ def test_service_client_sends_relative_request_through_core(self):
+ sdk = object.__new__(cyclops_sdk.SDK)
+ calls = []
+
+ def call(request):
+ calls.append(request)
+ return {"status": 201, "body": "initialized"}
+
+ sdk._call = call
+ sandbox = {
+ "namespace": "pool-one",
+ "claim": "claim-one",
+ "sandbox": "sandbox-one",
+ "services": ["mcp"],
+ }
+ with sdk.service_client(sandbox, "mcp") as client:
+ response = client.post("/mcp?session=one", json={"jsonrpc": "2.0"})
+ self.assertEqual(response.status_code, 201)
+ self.assertEqual(response.text, "initialized")
+ self.assertEqual(calls[0]["op"], "service_request")
+ self.assertEqual(calls[0]["service"], "mcp")
+ self.assertEqual(calls[0]["request"]["path"], "/mcp?session=one")
+ self.assertNotIn("url", calls[0]["request"])
+
+ def test_unknown_service_error_lists_available_names(self):
+ sdk = object.__new__(cyclops_sdk.SDK)
+ sandbox = {
+ "namespace": "pool-one",
+ "claim": "claim-one",
+ "sandbox": "sandbox-one",
+ "services": ["novnc", "mcp", "mcp"],
+ }
+ with self.assertRaises(cyclops_sdk.UnknownServiceError) as raised:
+ sdk.service_client(sandbox, "metrics")
+ self.assertEqual(raised.exception.requested, "metrics")
+ self.assertEqual(raised.exception.available, ["mcp", "novnc"])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/libs/fleet/sdk-bindings/python/uv.lock b/libs/fleet/sdk-bindings/python/uv.lock
new file mode 100644
index 0000000000..403793fe0d
--- /dev/null
+++ b/libs/fleet/sdk-bindings/python/uv.lock
@@ -0,0 +1,104 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"
+
+[[package]]
+name = "anyio"
+version = "4.14.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+ { name = "idna" },
+ { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/61/cc/a381afa6efea9f496eff839d4a6a1aed3bfafc7b3ab4b0d1b243a12573dd/anyio-4.14.2.tar.gz", hash = "sha256:cfa139f3ed1a23ee8f88a145ddb5ac7605b8bbfd8592baacd7ce3d8bb4313c7f", size = 260176, upload-time = "2026-07-12T20:29:07.082Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/da/35/f2287558c17e29fafc8ef3daf819bb9834061cfa43bff8014f7df7f63bdc/anyio-4.14.2-py3-none-any.whl", hash = "sha256:9f505dda5ac9f0c8309b5e8bd445a8c2bf7246f3ce950121e45ea15bc41d1494", size = 125813, upload-time = "2026-07-12T20:29:05.763Z" },
+]
+
+[[package]]
+name = "certifi"
+version = "2026.6.17"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c9/c7/424b75da314c1045981bd9777432fad05a9e0c69daa4ed7e308bbaffe405/certifi-2026.6.17.tar.gz", hash = "sha256:024c88eeec92ca068db80f02b8b07c9cef7b9fe261d1d535abfd5abd6f6af432", size = 134594, upload-time = "2026-06-17T10:31:07.894Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ef/2f/c5464532e965badff2f4c4c1a3a83f5697f0d7c407ed0cda44aaa99bb451/certifi-2026.6.17-py3-none-any.whl", hash = "sha256:2227dcbaafe0d2f59279d1762ddddc37783ed4354594f194ffc31d20f41fc3db", size = 133289, upload-time = "2026-06-17T10:31:06.348Z" },
+]
+
+[[package]]
+name = "cyclops-sdk"
+version = "0.1.0"
+source = { editable = "." }
+dependencies = [
+ { name = "httpx" },
+]
+
+[package.metadata]
+requires-dist = [{ name = "httpx", specifier = ">=0.27,<1" }]
+
+[[package]]
+name = "exceptiongroup"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8a/0e/97c33bf5009bdbac74fd2beace167cab3f978feb69cc36f1ef79360d6c4e/exceptiongroup-1.3.1-py3-none-any.whl", hash = "sha256:a7a39a3bd276781e98394987d3a5701d0c4edffb633bb7a5144577f82c773598", size = 16740, upload-time = "2025-11-21T23:01:53.443Z" },
+]
+
+[[package]]
+name = "h11"
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
+]
+
+[[package]]
+name = "httpcore"
+version = "1.0.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "certifi" },
+ { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/94/82699a10bca87a5556c9c59b5963f2d039dbd239f25bc2a63907a05a14cb/httpcore-1.0.9.tar.gz", hash = "sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8", size = 85484, upload-time = "2025-04-24T22:06:22.219Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" },
+]
+
+[[package]]
+name = "httpx"
+version = "0.28.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "anyio" },
+ { name = "certifi" },
+ { name = "httpcore" },
+ { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/df/48c586a5fe32a0f01324ee087459e112ebb7224f646c0b5023f5e79e9956/httpx-0.28.1.tar.gz", hash = "sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc", size = 141406, upload-time = "2024-12-06T15:37:23.222Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" },
+]
+
+[[package]]
+name = "idna"
+version = "3.18"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/cd/63/9496c57188a2ee585e0f1db071d75089a11e98aa86eb99d9d7618fc1edce/idna-3.18.tar.gz", hash = "sha256:ffb385a7e039654cef1ab9ef32c6fafe283c0c0467bba1d9029738ce4a14a848", size = 196711, upload-time = "2026-06-02T14:34:07.794Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/1e/5e/d4e9f1a599fb8e573b7b87160658329fbf28d19eac2718f51fc3def3aa5a/idna-3.18-py3-none-any.whl", hash = "sha256:7f952cbe720b688055e3f87de14f5c3e5fdaa8bc3928985c4077ca689de849a2", size = 65455, upload-time = "2026-06-02T14:34:06.319Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f6/cc/6253133b5bb138fc3306cebfbda2c520f545d36b5be2c7255cc528bb45d6/typing_extensions-4.16.0.tar.gz", hash = "sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5", size = 113555, upload-time = "2026-07-02T08:40:05.92Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/49/d3/b8441a820a491ddfc024b0b0cf0393375b75ea13866d9c66727e54c2fc80/typing_extensions-4.16.0-py3-none-any.whl", hash = "sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8", size = 45571, upload-time = "2026-07-02T08:40:04.659Z" },
+]
diff --git a/libs/fleet/sdk-bindings/rust/Cargo.lock b/libs/fleet/sdk-bindings/rust/Cargo.lock
new file mode 100644
index 0000000000..0799a4583f
--- /dev/null
+++ b/libs/fleet/sdk-bindings/rust/Cargo.lock
@@ -0,0 +1,1173 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "anyhow"
+version = "1.0.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a4385e2e34eb35d6b3efe798b9eb88096925d87726c0798709bf56d9ed84af3"
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "cc"
+version = "1.2.67"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e17dd265a7d0f31ef544e1b20e03add05d3b45b491b633b10d67145d2acc1a38"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cookie"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ddef33a339a91ea89fb53151bd0a4689cfce27055c291dfa69945475d22c747"
+dependencies = [
+ "percent-encoding",
+ "time",
+ "version_check",
+]
+
+[[package]]
+name = "cookie_store"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15b2c103cf610ec6cae3da84a766285b42fd16aad564758459e6ecf128c75206"
+dependencies = [
+ "cookie",
+ "document-features",
+ "idna",
+ "indexmap",
+ "log",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "time",
+ "url",
+]
+
+[[package]]
+name = "crc32fast"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "cyclops-sdk-core"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "serde_json",
+ "thiserror",
+ "url",
+ "wit-bindgen",
+]
+
+[[package]]
+name = "cyclops-sdk-host"
+version = "0.1.0"
+dependencies = [
+ "cyclops-sdk-core",
+ "serde_json",
+ "ureq",
+]
+
+[[package]]
+name = "deranged"
+version = "0.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
+
+[[package]]
+name = "displaydoc"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "document-features"
+version = "0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4b8a88685455ed29a21542a33abd9cb6510b6b129abadabdcef0f4c55bc8f61"
+dependencies = [
+ "litrs",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+
+[[package]]
+name = "flate2"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+]
+
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+
+[[package]]
+name = "futures"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b147ee9d1f6d097cef9ce628cd2ee62288d963e16fb287bd9286455b241382d"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-executor",
+ "futures-io",
+ "futures-sink",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-channel"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d"
+dependencies = [
+ "futures-core",
+ "futures-sink",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
+
+[[package]]
+name = "futures-executor"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "baf29c38818342a3b26b5b923639e7b1f4a61fc5e76102d4b1981c6dc7a7579d"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-io"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cecba35d7ad927e23624b22ad55235f2239cfa44fd10428eecbeba6d6a717718"
+
+[[package]]
+name = "futures-macro"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e835b70203e41293343137df5c0664546da5745f82ec9b84d40be8336958447b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "futures-sink"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c39754e157331b013978ec91992bde1ac089843443c49cbc7f46150b0fad0893"
+
+[[package]]
+name = "futures-task"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
+
+[[package]]
+name = "futures-util"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-io",
+ "futures-macro",
+ "futures-sink",
+ "futures-task",
+ "memchr",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "http"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
+[[package]]
+name = "icu_collections"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "utf8_iter",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38"
+
+[[package]]
+name = "icu_properties"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de"
+dependencies = [
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14"
+
+[[package]]
+name = "icu_provider"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "id-arena"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954"
+
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown 0.17.1",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "leb128fmt"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "litemap"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
+
+[[package]]
+name = "litrs"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
+
+[[package]]
+name = "log"
+version = "0.4.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "num-conv"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "potential_utf"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
+dependencies = [
+ "zerovec",
+]
+
+[[package]]
+name = "powerfmt"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"
+
+[[package]]
+name = "prettyplease"
+version = "0.2.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
+dependencies = [
+ "proc-macro2",
+ "syn",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "ring"
+version = "0.17.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "getrandom",
+ "libc",
+ "untrusted",
+ "windows-sys",
+]
+
+[[package]]
+name = "rustls"
+version = "0.23.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c54fcab019b409d04215d3a17cb438fd7fbf192ee61461f20f4fe18704bc138"
+dependencies = [
+ "log",
+ "once_cell",
+ "ring",
+ "rustls-pki-types",
+ "rustls-webpki",
+ "subtle",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-pki-types"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "764899a24af3980067ee14bc143654f297b22eaebfe3c7b6b211920a5a59b046"
+dependencies = [
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-webpki"
+version = "0.103.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
+dependencies = [
+ "ring",
+ "rustls-pki-types",
+ "untrusted",
+]
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "simd-adler32"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+
+[[package]]
+name = "spdx"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3e17e880bafaeb362a7b751ec46bdc5b61445a188f80e0606e68167cd540fa3"
+dependencies = [
+ "smallvec",
+]
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
+[[package]]
+name = "subtle"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "synstructure"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "time"
+version = "0.3.53"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "18dfaaeddcb932337b5e7866ee7d0ce9b76d2fd092997146f187ec09b4558a50"
+dependencies = [
+ "deranged",
+ "num-conv",
+ "powerfmt",
+ "serde_core",
+ "time-core",
+ "time-macros",
+]
+
+[[package]]
+name = "time-core"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109"
+
+[[package]]
+name = "time-macros"
+version = "0.2.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c431b87111666e491a90baa837f914fb45cd5dc3c268591b0220ff5057f2085f"
+dependencies = [
+ "num-conv",
+ "time-core",
+]
+
+[[package]]
+name = "tinystr"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-xid"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
+
+[[package]]
+name = "untrusted"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
+
+[[package]]
+name = "ureq"
+version = "3.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dea7109cdcd5864d4eeb1b58a1648dc9bf520360d7af16ec26d0a9354bafcfc0"
+dependencies = [
+ "base64",
+ "cookie_store",
+ "flate2",
+ "log",
+ "percent-encoding",
+ "rustls",
+ "rustls-pki-types",
+ "serde",
+ "serde_json",
+ "ureq-proto",
+ "utf8-zero",
+ "webpki-roots",
+]
+
+[[package]]
+name = "ureq-proto"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e994ba84b0bd1b1b0cf92878b7ef898a5c1760108fe7b6010327e274917a808c"
+dependencies = [
+ "base64",
+ "http",
+ "httparse",
+ "log",
+]
+
+[[package]]
+name = "url"
+version = "2.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+]
+
+[[package]]
+name = "utf8-zero"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8c0a043c9540bae7c578c88f91dda8bd82e59ae27c21baca69c8b191aaf5a6e"
+
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasm-encoder"
+version = "0.225.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f7eac0445cac73bcf09e6a97f83248d64356dccf9f2b100199769b6b42464e5"
+dependencies = [
+ "leb128fmt",
+ "wasmparser",
+]
+
+[[package]]
+name = "wasm-metadata"
+version = "0.225.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1d20d0bf2c73c32a5114cf35a5c10ccf9f9aa37a3a2c0114b3e11cbf6faac12"
+dependencies = [
+ "anyhow",
+ "indexmap",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "spdx",
+ "url",
+ "wasm-encoder",
+ "wasmparser",
+]
+
+[[package]]
+name = "wasmparser"
+version = "0.225.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36e5456165f81e64cb9908a0fe9b9d852c2c74582aa3fe2be3c2da57f937d3ae"
+dependencies = [
+ "bitflags",
+ "hashbrown 0.15.5",
+ "indexmap",
+ "semver",
+]
+
+[[package]]
+name = "webpki-roots"
+version = "1.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf85cb06032201fa7c6f829d7db5a7e5aa45bcc0655327713065f6f0576731bf"
+dependencies = [
+ "rustls-pki-types",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "wit-bindgen"
+version = "0.39.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4dd9a372b25d6f35456b0a730d2adabeb0c4878066ba8f8089800349be6ecb5"
+dependencies = [
+ "wit-bindgen-rt",
+ "wit-bindgen-rust-macro",
+]
+
+[[package]]
+name = "wit-bindgen-core"
+version = "0.39.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f108fa9b77a346372858b30c11ea903680e7e2b9d820b1a5883e9d530bf51c7e"
+dependencies = [
+ "anyhow",
+ "heck",
+ "wit-parser",
+]
+
+[[package]]
+name = "wit-bindgen-rt"
+version = "0.39.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f42320e61fe2cfd34354ecb597f86f413484a798ba44a8ca1165c58d42da6c1"
+dependencies = [
+ "bitflags",
+ "futures",
+ "once_cell",
+]
+
+[[package]]
+name = "wit-bindgen-rust"
+version = "0.39.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5ba5b852e976d35dbf6cb745746bf1bd4fc26782bab1e0c615fc71a7d8aac05"
+dependencies = [
+ "anyhow",
+ "heck",
+ "indexmap",
+ "prettyplease",
+ "syn",
+ "wasm-metadata",
+ "wit-bindgen-core",
+ "wit-component",
+]
+
+[[package]]
+name = "wit-bindgen-rust-macro"
+version = "0.39.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "401529c9af9304a20ed99fa01799e467b7d37727126f0c9a958895471268ad7a"
+dependencies = [
+ "anyhow",
+ "prettyplease",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wit-bindgen-core",
+ "wit-bindgen-rust",
+]
+
+[[package]]
+name = "wit-component"
+version = "0.225.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2505c917564c1d74774563bbcd3e4f8c216a6508050862fd5f449ee56e3c5125"
+dependencies = [
+ "anyhow",
+ "bitflags",
+ "indexmap",
+ "log",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "wasm-encoder",
+ "wasm-metadata",
+ "wasmparser",
+ "wit-parser",
+]
+
+[[package]]
+name = "wit-parser"
+version = "0.225.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebefaa234e47224f10ce60480c5bfdece7497d0f3b87a12b41ff39e5c8377a78"
+dependencies = [
+ "anyhow",
+ "id-arena",
+ "indexmap",
+ "log",
+ "semver",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "unicode-xid",
+ "wasmparser",
+]
+
+[[package]]
+name = "writeable"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
+
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "synstructure",
+]
+
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "synstructure",
+]
+
+[[package]]
+name = "zeroize"
+version = "1.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+
+[[package]]
+name = "zerotrie"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
diff --git a/libs/fleet/sdk-bindings/rust/Cargo.toml b/libs/fleet/sdk-bindings/rust/Cargo.toml
new file mode 100644
index 0000000000..839e829878
--- /dev/null
+++ b/libs/fleet/sdk-bindings/rust/Cargo.toml
@@ -0,0 +1,8 @@
+[package]
+name="cyclops-sdk-host"
+version="0.1.0"
+edition="2021"
+[dependencies]
+cyclops-sdk-core={path="../../sdk-core"}
+serde_json="1.0.150"
+ureq={version="3.1.4",features=["json"]}
diff --git a/libs/fleet/sdk-bindings/rust/examples/app_controlled.rs b/libs/fleet/sdk-bindings/rust/examples/app_controlled.rs
new file mode 100644
index 0000000000..df5a3805a5
--- /dev/null
+++ b/libs/fleet/sdk-bindings/rust/examples/app_controlled.rs
@@ -0,0 +1,100 @@
+use cyclops_sdk_host::{
+ Claim, Configuration, CreateClaimRequest, CreatePoolRequest, OAuthConfiguration, Pool,
+ PoolSpec, PoolSpecService, PoolSpecServiceProtocol, PoolTemplate, Sandbox, Sdk,
+};
+use std::{
+ env, thread,
+ time::{Duration, Instant, SystemTime, UNIX_EPOCH},
+};
+
+fn run_agent(sdk: &mut Sdk, sandbox: Sandbox) -> Result<serde_json::Value, String> {
+ let body = r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"cyclops-sdk-rust-example","version":"0.1.0"}}}"#;
+ let deadline = Instant::now() + Duration::from_secs(300);
+ let mut mcp = sdk
+ .service_client(&sandbox, "mcp")
+ .map_err(|error| error.to_string())?;
+ loop {
+ let response = mcp
+ .post("/mcp")
+ .header("accept", "application/json, text/event-stream")
+ .header("content-type", "application/json")
+ .body(body)
+ .send()
+ .map_err(|error| error.to_string())?;
+ if (200..300).contains(&response.status) {
+ return Ok(
+ serde_json::json!({"namespace": sandbox.namespace, "claim": sandbox.claim, "sandbox": sandbox.sandbox, "mcp_status": response.status}),
+ );
+ }
+ if !matches!(response.status, 502..=504) || Instant::now() >= deadline {
+ return Err(format!(
+ "MCP initialize failed with HTTP {}: {}",
+ response.status, response.body
+ ));
+ }
+ thread::sleep(Duration::from_secs(5));
+ }
+}
+
+fn main() -> Result<(), String> {
+ let suffix = format!(
+ "{:08x}",
+ SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .map_err(|error| error.to_string())?
+ .as_nanos() as u32
+ );
+ let namespace =
+ env::var("CYCLOPS_NAMESPACE").unwrap_or_else(|_| format!("sdk-example-{suffix}"));
+ let mut sdk = Sdk::connect(Configuration {
+ base_url: env::var("CUA_BASE_URL").unwrap_or_else(|_| "https://run.cua.ai".into()),
+ oauth: OAuthConfiguration {
+ token_url: env::var("CUA_TOKEN_URL").unwrap_or_else(|_| {
+ "https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token".into()
+ }),
+ client_id: required("CUA_CLIENT_ID")?,
+ client_secret: required("CUA_CLIENT_SECRET")?,
+ },
+ })?;
+ let mut pool: Option<Pool> = None;
+ let mut claim: Option<Claim> = None;
+ let result = (|| {
+ let created_pool = sdk.create_pool(CreatePoolRequest {
+ namespace: namespace.clone(),
+ spec: PoolSpec::builder()
+ .replicas(1)
+ .services(vec![PoolSpecService::builder()
+ .name("mcp".into())
+ .target_port(3000)
+ .protocol(PoolSpecServiceProtocol::TCP)
+ .build()?])
+ .template(
+ PoolTemplate::builder()
+ .container_disk_image(required("CUA_IMAGE")?)
+ .image_pull_secret(required("CUA_IMAGE_PULL_SECRET")?)
+ .cpu_cores(4)
+ .memory("4Gi".into())
+ .build()?,
+ )
+ .build()?,
+ })?;
+ pool = Some(created_pool.clone());
+ let created_claim = sdk.create_claim(CreateClaimRequest {
+ pool: created_pool,
+ spec: None,
+ })?;
+ claim = Some(created_claim.clone());
+ let sandbox = sdk.wait_claim(created_claim)?;
+ let result = run_agent(&mut sdk, sandbox)?;
+ println!("{result}");
+ Ok(())
+ })();
+ let claim_cleanup = claim.map_or(Ok(()), |claim| sdk.delete_claim(claim));
+ let pool_cleanup = pool.map_or(Ok(()), |pool| sdk.delete_pool(pool));
+ sdk.close();
+ result.and(claim_cleanup).and(pool_cleanup)
+}
+
+fn required(name: &str) -> Result<String, String> {
+ env::var(name).map_err(|_| format!("{name} is required"))
+}
diff --git a/libs/fleet/sdk-bindings/rust/src/lib.rs b/libs/fleet/sdk-bindings/rust/src/lib.rs
new file mode 100644
index 0000000000..5baf4c255f
--- /dev/null
+++ b/libs/fleet/sdk-bindings/rust/src/lib.rs
@@ -0,0 +1,259 @@
+use cyclops_sdk_core::{
+ AccessToken, Configuration as CoreConfiguration, HttpRequest, HttpResponse, OAuthCredentials,
+ Platform, PlatformError,
+};
+use std::time::Duration;
+
+pub use cyclops_sdk_core::generated_crd::*;
+pub use cyclops_sdk_core::{
+ Claim, CreateClaimRequest, CreatePoolRequest, Pool, Sandbox, SdkError, ServiceHttpRequest,
+ ServiceHttpResponse,
+};
+
+#[derive(Debug, Clone)]
+pub struct OAuthConfiguration {
+ pub token_url: String,
+ pub client_id: String,
+ pub client_secret: String,
+}
+#[derive(Debug, Clone)]
+pub struct Configuration {
+ pub base_url: String,
+ pub oauth: OAuthConfiguration,
+}
+#[derive(Default)]
+struct NativePlatform {
+ oauth: Option<OAuthCredentials>,
+ token: Option<AccessToken>,
+}
+pub struct Sdk {
+ core: cyclops_sdk_core::Sdk<NativePlatform>,
+}
+pub struct ServiceClient<'a> {
+ core: &'a mut cyclops_sdk_core::Sdk<NativePlatform>,
+ sandbox: Sandbox,
+ service: String,
+}
+pub struct ServiceRequestBuilder<'client, 'sdk> {
+ client: &'client mut ServiceClient<'sdk>,
+ request: ServiceHttpRequest,
+}
+
+impl<'sdk> ServiceClient<'sdk> {
+ pub fn request<'client>(
+ &'client mut self,
+ method: impl Into<String>,
+ path: impl Into<String>,
+ ) -> ServiceRequestBuilder<'client, 'sdk> {
+ ServiceRequestBuilder {
+ client: self,
+ request: ServiceHttpRequest::new(method, path, None),
+ }
+ }
+ pub fn get<'client>(
+ &'client mut self,
+ path: impl Into<String>,
+ ) -> ServiceRequestBuilder<'client, 'sdk> {
+ self.request("GET", path)
+ }
+ pub fn post<'client>(
+ &'client mut self,
+ path: impl Into<String>,
+ ) -> ServiceRequestBuilder<'client, 'sdk> {
+ self.request("POST", path)
+ }
+}
+
+impl ServiceRequestBuilder<'_, '_> {
+ pub fn header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
+ self.request.headers.push((name.into(), value.into()));
+ self
+ }
+ pub fn body(mut self, body: impl Into<String>) -> Self {
+ self.request.body = Some(body.into());
+ self
+ }
+ pub fn send(self) -> Result<ServiceHttpResponse, SdkError> {
+ self.client
+ .core
+ .service_request(&self.client.sandbox, &self.client.service, self.request)
+ }
+}
+
+impl Sdk {
+ pub fn connect(configuration: Configuration) -> Result<Self, String> {
+ let platform = NativePlatform {
+ oauth: Some(OAuthCredentials {
+ token_url: configuration.oauth.token_url,
+ client_id: configuration.oauth.client_id,
+ client_secret: configuration.oauth.client_secret,
+ }),
+ token: None,
+ };
+ let core = cyclops_sdk_core::Sdk::connect(
+ platform,
+ CoreConfiguration {
+ protocol_version: cyclops_sdk_core::PROTOCOL_VERSION,
+ base_url: configuration.base_url,
+ },
+ )
+ .map_err(|error| error.to_string())?;
+ Ok(Self { core })
+ }
+ pub fn create_pool(&mut self, request: CreatePoolRequest) -> Result<Pool, String> {
+ self.core
+ .create_pool(request)
+ .map_err(|error| error.to_string())
+ }
+ pub fn list_pools(&mut self, namespace: &str) -> Result<Vec<Pool>, String> {
+ self.core
+ .list_pools(namespace)
+ .map_err(|error| error.to_string())
+ }
+ pub fn get_pool(&mut self, pool: Pool) -> Result<Pool, String> {
+ self.core.get_pool(pool).map_err(|error| error.to_string())
+ }
+ pub fn update_pool(&mut self, pool: Pool) -> Result<Pool, String> {
+ self.core
+ .update_pool(pool)
+ .map_err(|error| error.to_string())
+ }
+ pub fn delete_pool(&mut self, pool: Pool) -> Result<(), String> {
+ self.core
+ .delete_pool(pool)
+ .map_err(|error| error.to_string())
+ }
+ pub fn create_claim(&mut self, request: CreateClaimRequest) -> Result<Claim, String> {
+ self.core
+ .create_claim(request)
+ .map_err(|error| error.to_string())
+ }
+ pub fn list_claims(&mut self, namespace: &str) -> Result<Vec<Claim>, String> {
+ self.core
+ .list_claims(namespace)
+ .map_err(|error| error.to_string())
+ }
+ pub fn get_claim(&mut self, claim: Claim) -> Result<Claim, String> {
+ self.core
+ .get_claim(claim)
+ .map_err(|error| error.to_string())
+ }
+ pub fn update_claim(&mut self, claim: Claim) -> Result<Claim, String> {
+ self.core
+ .update_claim(claim)
+ .map_err(|error| error.to_string())
+ }
+ pub fn delete_claim(&mut self, claim: Claim) -> Result<(), String> {
+ self.core
+ .delete_claim(claim)
+ .map_err(|error| error.to_string())
+ }
+ pub fn wait_claim(&mut self, claim: Claim) -> Result<Sandbox, String> {
+ self.core
+ .wait_claim(claim)
+ .map_err(|error| error.to_string())
+ }
+ pub fn service_client<'a>(
+ &'a mut self,
+ sandbox: &Sandbox,
+ service: &str,
+ ) -> Result<ServiceClient<'a>, SdkError> {
+ if !sandbox
+ .services
+ .iter()
+ .any(|available| available == service)
+ {
+ let mut available = sandbox.services.clone();
+ available.sort();
+ available.dedup();
+ return Err(SdkError::UnknownService {
+ requested: service.into(),
+ available,
+ });
+ }
+ Ok(ServiceClient {
+ core: &mut self.core,
+ sandbox: sandbox.clone(),
+ service: service.into(),
+ })
+ }
+ pub fn close(self) {}
+}
+
+fn send_without_body(
+ mut request: ureq::RequestBuilder<ureq::typestate::WithoutBody>,
+ headers: Vec<(String, String)>,
+) -> Result<ureq::http::Response<ureq::Body>, ureq::Error> {
+ for (name, value) in headers {
+ request = request.header(&name, &value);
+ }
+ request.call()
+}
+fn send_with_body(
+ mut request: ureq::RequestBuilder<ureq::typestate::WithBody>,
+ headers: Vec<(String, String)>,
+ body: Option<String>,
+) -> Result<ureq::http::Response<ureq::Body>, ureq::Error> {
+ for (name, value) in headers {
+ request = request.header(&name, &value);
+ }
+ match body {
+ Some(body) => request.send(body),
+ None => request.send_empty(),
+ }
+}
+impl Platform for NativePlatform {
+ fn http(&mut self, request: HttpRequest) -> Result<HttpResponse, PlatformError> {
+ let response = match request.method.as_str() {
+ "GET" => send_without_body(ureq::get(&request.url), request.headers),
+ "DELETE" => send_without_body(ureq::delete(&request.url), request.headers),
+ "HEAD" => send_without_body(ureq::head(&request.url), request.headers),
+ "OPTIONS" => send_without_body(ureq::options(&request.url), request.headers),
+ "POST" => send_with_body(ureq::post(&request.url), request.headers, request.body),
+ "PUT" => send_with_body(ureq::put(&request.url), request.headers, request.body),
+ "PATCH" => send_with_body(ureq::patch(&request.url), request.headers, request.body),
+ method => {
+ return Err(PlatformError::Transport(format!(
+ "unsupported HTTP method {method}"
+ )))
+ }
+ };
+ match response {
+ Ok(mut response) => {
+ let status = response.status().as_u16();
+ let body = response
+ .body_mut()
+ .read_to_string()
+ .map_err(|error| PlatformError::Transport(error.to_string()))?;
+ Ok(HttpResponse { status, body })
+ }
+ Err(ureq::Error::StatusCode(status)) => Ok(HttpResponse {
+ status,
+ body: String::new(),
+ }),
+ Err(error) => Err(PlatformError::Transport(error.to_string())),
+ }
+ }
+ fn sleep(&mut self, milliseconds: u64) -> Result<(), PlatformError> {
+ std::thread::sleep(Duration::from_millis(milliseconds));
+ Ok(())
+ }
+ fn now_ms(&mut self) -> u64 {
+ std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .unwrap_or_default()
+ .as_millis() as u64
+ }
+ fn acquire_oauth_credentials(&mut self) -> Result<OAuthCredentials, PlatformError> {
+ self.oauth
+ .clone()
+ .ok_or_else(|| PlatformError::Credentials("OAuth is not configured".into()))
+ }
+ fn load_access_token(&mut self) -> Result<Option<AccessToken>, PlatformError> {
+ Ok(self.token.clone())
+ }
+ fn store_access_token(&mut self, token: &AccessToken) -> Result<(), PlatformError> {
+ self.token = Some(token.clone());
+ Ok(())
+ }
+}
diff --git a/libs/fleet/sdk-bindings/rust/tests/public_api.rs b/libs/fleet/sdk-bindings/rust/tests/public_api.rs
new file mode 100644
index 0000000000..93d79b0d34
--- /dev/null
+++ b/libs/fleet/sdk-bindings/rust/tests/public_api.rs
@@ -0,0 +1,35 @@
+use cyclops_sdk_host::{
+ Claim, Configuration, CreateClaimRequest, CreatePoolRequest, Pool, Sandbox, Sdk, SdkError,
+ ServiceHttpResponse,
+};
+
+#[test]
+fn typed_resource_api_only() {
+ let _: fn(Configuration) -> Result<Sdk, String> = Sdk::connect;
+ let _: fn(&mut Sdk, CreatePoolRequest) -> Result<Pool, String> = Sdk::create_pool;
+ let _: fn(&mut Sdk, &str) -> Result<Vec<Pool>, String> = Sdk::list_pools;
+ let _: fn(&mut Sdk, Pool) -> Result<Pool, String> = Sdk::get_pool;
+ let _: fn(&mut Sdk, Pool) -> Result<Pool, String> = Sdk::update_pool;
+ let _: fn(&mut Sdk, Pool) -> Result<(), String> = Sdk::delete_pool;
+ let _: fn(&mut Sdk, CreateClaimRequest) -> Result<Claim, String> = Sdk::create_claim;
+ let _: fn(&mut Sdk, &str) -> Result<Vec<Claim>, String> = Sdk::list_claims;
+ let _: fn(&mut Sdk, Claim) -> Result<Claim, String> = Sdk::get_claim;
+ let _: fn(&mut Sdk, Claim) -> Result<Claim, String> = Sdk::update_claim;
+ let _: fn(&mut Sdk, Claim) -> Result<(), String> = Sdk::delete_claim;
+ let _: fn(&mut Sdk, Claim) -> Result<cyclops_sdk_host::Sandbox, String> = Sdk::wait_claim;
+}
+
+fn service_http_contract(sdk: &mut Sdk, sandbox: &Sandbox) -> Result<(), SdkError> {
+ let mut service = sdk.service_client(sandbox, "mcp")?;
+ let _: ServiceHttpResponse = service
+ .post("/mcp")
+ .header("content-type", "application/json")
+ .body("{}")
+ .send()?;
+ Ok(())
+}
+
+#[test]
+fn service_http_is_sdk_owned() {
+ let _: fn(&mut Sdk, &Sandbox) -> Result<(), SdkError> = service_http_contract;
+}
diff --git a/libs/fleet/sdk-bindings/typescript/.gitignore b/libs/fleet/sdk-bindings/typescript/.gitignore
new file mode 100644
index 0000000000..afef9bc672
--- /dev/null
+++ b/libs/fleet/sdk-bindings/typescript/.gitignore
@@ -0,0 +1,2 @@
+dist-examples/
+node_modules/
diff --git a/libs/fleet/sdk-bindings/typescript/package-lock.json b/libs/fleet/sdk-bindings/typescript/package-lock.json
new file mode 100644
index 0000000000..c404f0bf03
--- /dev/null
+++ b/libs/fleet/sdk-bindings/typescript/package-lock.json
@@ -0,0 +1,47 @@
+{
+ "name": "@trycua/cyclops-sdk",
+ "version": "0.1.0",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "@trycua/cyclops-sdk",
+ "version": "0.1.0",
+ "devDependencies": {
+ "@types/node": "22.10.5",
+ "typescript": "5.7.2"
+ }
+ },
+ "node_modules/@types/node": {
+ "version": "22.10.5",
+ "resolved": "https://registry.npmjs.org/@types/node/-/node-22.10.5.tgz",
+ "integrity": "sha512-F8Q+SeGimwOo86fiovQh8qiXfFEh2/ocYv7tU5pJ3EXMSSxk1Joj5wefpFK2fHTf/N6HKGSxIDBT9f3gCxXPkQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "undici-types": "~6.20.0"
+ }
+ },
+ "node_modules/typescript": {
+ "version": "5.7.2",
+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.7.2.tgz",
+ "integrity": "sha512-i5t66RHxDvVN40HfDd1PsEThGNnlMCMT3jMUuoh9/0TaqWevNontacunWyN02LA9/fIbEWlcHZcgTKb9QoaLfg==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "bin": {
+ "tsc": "bin/tsc",
+ "tsserver": "bin/tsserver"
+ },
+ "engines": {
+ "node": ">=14.17"
+ }
+ },
+ "node_modules/undici-types": {
+ "version": "6.20.0",
+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.20.0.tgz",
+ "integrity": "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg==",
+ "dev": true,
+ "license": "MIT"
+ }
+ }
+}
diff --git a/libs/fleet/sdk-bindings/typescript/package.json b/libs/fleet/sdk-bindings/typescript/package.json
new file mode 100644
index 0000000000..066ffb3c8c
--- /dev/null
+++ b/libs/fleet/sdk-bindings/typescript/package.json
@@ -0,0 +1,21 @@
+{
+ "name": "@trycua/cyclops-sdk",
+ "version": "0.1.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "tsc -p tsconfig.json && tsc -p tsconfig.examples.json",
+ "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.contract.json && tsc -p tsconfig.examples.json --noEmit",
+ "test": "npm run build && node --test test/*.test.js"
+ },
+ "devDependencies": {
+ "typescript": "5.7.2",
+ "@types/node": "22.10.5"
+ },
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ }
+}
diff --git a/libs/fleet/sdk-bindings/typescript/src/generated-crd.ts b/libs/fleet/sdk-bindings/typescript/src/generated-crd.ts
new file mode 100644
index 0000000000..cbb61850af
--- /dev/null
+++ b/libs/fleet/sdk-bindings/typescript/src/generated-crd.ts
@@ -0,0 +1,55 @@
+// Code generated from clusters/base/osgym/crd.yaml; DO NOT EDIT.
+export type ClaimSpec = {
+ bindDeadline?: number
+ lifecycle?: ClaimSpecLifecycle
+ sandboxTemplateRef: SandboxTemplateRef
+ warmpool?: string
+}
+export type ClaimSpecLifecycle = {
+ autoRenew?: boolean
+ shutdownPolicy?: string
+ shutdownTime?: string
+}
+export type PoolSpec = {
+ autoscaling?: PoolSpecAutoscaling
+ replicas: number
+ services?: PoolSpecService[]
+ template: PoolTemplate
+}
+export type PoolSpecAutoscaling = {
+ initialPoolSize?: number
+ maxPoolSize?: number
+ minPoolSize?: number
+}
+export type PoolSpecService = {
+ name: string
+ protocol?: PoolSpecServiceProtocol
+ targetPort: number
+}
+export type PoolSpecServiceProtocol = "TCP" | "UDP"
+export type PoolTemplate = {
+ command?: string[]
+ containerDiskImage: string
+ cpuCores?: number
+ firmware?: PoolTemplateFirmware
+ imagePullSecret?: string
+ memory?: string
+ nodeSelector?: Record<string, string>
+ oidc?: PoolTemplateOidc
+ probes?: unknown
+ runtime?: PoolTemplateRuntime
+ runtimeClassName?: string
+ tolerations?: unknown[]
+}
+export type PoolTemplateFirmware = "bios" | "efi"
+export type PoolTemplateOidc = {
+ awsRegion?: string
+ awsRoleArn?: string
+ credentialsSecret: string
+ refreshIntervalSeconds?: number
+ tokenUrl: string
+}
+export type PoolTemplateRuntime = "kubevirt" | "macos" | "gvisor"
+export type SandboxTemplateRef = {
+ name: string
+}
diff --git a/libs/fleet/sdk-bindings/typescript/src/index.ts b/libs/fleet/sdk-bindings/typescript/src/index.ts
new file mode 100644
index 0000000000..bcd71dead0
--- /dev/null
+++ b/libs/fleet/sdk-bindings/typescript/src/index.ts
@@ -0,0 +1,148 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process"
+import type { ClaimSpec, PoolSpec } from "./generated-crd.js"
+
+export * from "./generated-crd.js"
+
+export type OAuthConfiguration = { tokenUrl: string; clientId: string; clientSecret: string }
+export type Configuration = { baseUrl: string; oauth: OAuthConfiguration }
+export type ResourceMetadata = { namespace: string; name: string; labels?: Record<string, string> }
+export type Pool = { apiVersion: "cua.ai/v1"; kind: "OSGymWorkspacePool"; metadata: ResourceMetadata; spec: Record<string, unknown>; status?: Record<string, unknown> }
+export type Claim = { apiVersion: "osgym.cua.ai/v1alpha1"; kind: "OSGymSandboxClaim"; metadata: ResourceMetadata; spec: Record<string, unknown>; status?: Record<string, unknown> }
+export type Sandbox = { namespace: string; claim: string; sandbox: string; services: string[] }
+export type CreatePoolRequest = { namespace: string; spec: PoolSpec }
+export type CreateClaimRequest = { pool: Pool; spec?: ClaimSpec }
+type ServiceHttpResponse = { status: number; body: string }
+export type ServiceFetch = (path: string, init?: RequestInit) => Promise<Response>
+
+export class UnknownServiceError extends Error {
+ readonly requested: string
+ readonly available: readonly string[]
+
+ constructor(requested: string, available: readonly string[]) {
+ super(`unknown sandbox service ${JSON.stringify(requested)}; available services: ${JSON.stringify(available)}`)
+ this.name = "UnknownServiceError"
+ this.requested = requested
+ this.available = [...available]
+ }
+}
+
+type HostCall =
+ | { kind: "http"; request: { method: string; url: string; headers: [string, string][]; body?: string } }
+ | { kind: "sleep"; milliseconds: number }
+ | { kind: "now_ms" }
+ | { kind: "acquire_oauth_credentials" }
+ | { kind: "load_access_token" }
+ | { kind: "store_access_token"; token: { value: string; expires_at_ms: number } }
+
+type Reply<T> = { ok: boolean; value?: T; error?: string }
+
+export class SDK {
+ readonly #configuration: Configuration
+ readonly #process: ChildProcessWithoutNullStreams
+ #buffer = ""
+ #token?: { value: string; expires_at_ms: number }
+ #pending: { resolve: (value: unknown) => void; reject: (error: Error) => void }[] = []
+
+ private constructor(configuration: Configuration) {
+ this.#configuration = configuration
+ this.#process = spawn(process.env.CYCLOPS_CORE_RUNNER ?? "cyclops-core-runner", [], { stdio: "pipe" })
+ this.#process.stdout.setEncoding("utf8")
+ this.#process.stdout.on("data", chunk => this.#read(String(chunk)))
+ this.#process.on("error", error => this.#fail(error))
+ this.#process.on("exit", code => this.#fail(new Error(`core runner exited with ${code ?? "unknown"}`)))
+ }
+
+ static async connect(configuration: Configuration): Promise<SDK> {
+ const sdk = new SDK(configuration)
+ try {
+ await sdk.#call({ op: "configure", configuration: { protocol_version: 7, base_url: configuration.baseUrl } })
+ return sdk
+ } catch (error) {
+ sdk.close()
+ throw error
+ }
+ }
+
+ createPool(request: CreatePoolRequest): Promise<Pool> { return this.#call({ op: "create_pool", request }) }
+ listPools(namespace: string): Promise<Pool[]> { return this.#call({ op: "list_pools", namespace }) }
+ getPool(pool: Pool): Promise<Pool> { return this.#call({ op: "get_pool", pool }) }
+ updatePool(pool: Pool): Promise<Pool> { return this.#call({ op: "update_pool", pool }) }
+ deletePool(pool: Pool): Promise<void> { return this.#call({ op: "delete_pool", pool }) }
+ createClaim(request: CreateClaimRequest): Promise<Claim> { return this.#call({ op: "create_claim", request }) }
+ listClaims(namespace: string): Promise<Claim[]> { return this.#call({ op: "list_claims", namespace }) }
+ getClaim(claim: Claim): Promise<Claim> { return this.#call({ op: "get_claim", claim }) }
+ updateClaim(claim: Claim): Promise<Claim> { return this.#call({ op: "update_claim", claim }) }
+ deleteClaim(claim: Claim): Promise<void> { return this.#call({ op: "delete_claim", claim }) }
+ waitClaim(claim: Claim): Promise<Sandbox> { return this.#call({ op: "wait_claim", claim }) }
+ serviceFetch(sandbox: Sandbox, service: string): ServiceFetch {
+ const available = [...new Set(sandbox.services)].sort()
+ if (!available.includes(service)) throw new UnknownServiceError(service, available)
+ return async (path, init = {}) => {
+ if (!path.startsWith("/") || path.startsWith("//") || path.includes("#")) {
+ throw new TypeError(`service request path must be relative and start with '/': ${path}`)
+ }
+ const request = new Request(`https://cyclops.invalid${path}`, init)
+ const body = init.body === undefined || init.body === null ? undefined : await request.text()
+ const response = await this.#call<ServiceHttpResponse>({
+ op: "service_request",
+ sandbox,
+ service,
+ request: {
+ method: request.method,
+ path,
+ headers: Array.from(request.headers.entries()),
+ body,
+ },
+ })
+ const responseBody = [204, 205, 304].includes(response.status) ? null : response.body
+ return new Response(responseBody, { status: response.status })
+ }
+ }
+ close(): void { this.#process.stdin.end(); this.#process.kill("SIGTERM") }
+
+ #call<T>(request: unknown): Promise<T> {
+ return new Promise<T>((resolve, reject) => {
+ this.#pending.push({ resolve: value => resolve(value as T), reject })
+ this.#process.stdin.write(`${JSON.stringify(request)}\n`)
+ })
+ }
+
+ async #read(chunk: string): Promise<void> {
+ this.#buffer += chunk
+ while (this.#buffer.includes("\n")) {
+ const newline = this.#buffer.indexOf("\n")
+ const line = this.#buffer.slice(0, newline)
+ this.#buffer = this.#buffer.slice(newline + 1)
+ if (!line) continue
+ const message = JSON.parse(line) as Reply<unknown> | HostCall
+ if ("kind" in message) {
+ try { this.#process.stdin.write(`${JSON.stringify({ ok: true, value: await this.#dispatch(message) })}\n`) }
+ catch (error) { this.#process.stdin.write(`${JSON.stringify({ ok: false, error: { transport: String(error) } })}\n`) }
+ continue
+ }
+ const pending = this.#pending.shift()
+ if (!pending) continue
+ if (message.ok) pending.resolve(message.value)
+ else pending.reject(new Error(message.error ?? "core operation failed"))
+ }
+ }
+
+ async #dispatch(message: HostCall): Promise<unknown> {
+ if (message.kind === "http") {
+ const response = await fetch(message.request.url, { method: message.request.method, headers: Object.fromEntries(message.request.headers), body: message.request.body, redirect: "manual" })
+ return { status: response.status, body: await response.text() }
+ }
+ if (message.kind === "sleep") { await new Promise(resolve => setTimeout(resolve, message.milliseconds)); return null }
+ if (message.kind === "now_ms") return Date.now()
+ if (message.kind === "acquire_oauth_credentials") return { token_url: this.#configuration.oauth.tokenUrl, client_id: this.#configuration.oauth.clientId, client_secret: this.#configuration.oauth.clientSecret }
+ if (message.kind === "load_access_token") return this.#token ?? null
+ this.#token = message.token
+ return null
+ }
+
+ #fail(error: Error): void {
+ for (const pending of this.#pending.splice(0)) pending.reject(error)
+ }
+}
+
+export function connect(configuration: Configuration): Promise<SDK> { return SDK.connect(configuration) }
diff --git a/libs/fleet/sdk-bindings/typescript/test/connect-failure.test.js b/libs/fleet/sdk-bindings/typescript/test/connect-failure.test.js
new file mode 100644
index 0000000000..169ffa2dc5
--- /dev/null
+++ b/libs/fleet/sdk-bindings/typescript/test/connect-failure.test.js
@@ -0,0 +1,51 @@
+import assert from "node:assert/strict"
+import { chmod, mkdtemp, readFile, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { test } from "node:test"
+import { setTimeout as delay } from "node:timers/promises"
+
+import { connect } from "../dist/index.js"
+
+test("connect terminates the core runner when configuration fails", async () => {
+ const directory = await mkdtemp(join(tmpdir(), "cyclops-sdk-connect-"))
+ const runner = join(directory, "runner.mjs")
+ const pidFile = join(directory, "pid")
+ const terminatedFile = join(directory, "terminated")
+ await writeFile(runner, `#!/usr/bin/env node
+import { writeFileSync } from "node:fs"
+import { createInterface } from "node:readline"
+writeFileSync(${JSON.stringify(pidFile)}, String(process.pid))
+process.on("SIGTERM", () => { writeFileSync(${JSON.stringify(terminatedFile)}, "yes"); process.exit(0) })
+createInterface({ input: process.stdin }).once("line", () => process.stdout.write('{"ok":false,"error":"invalid configuration"}\\n'))
+`)
+ await chmod(runner, 0o755)
+ const previousRunner = process.env.CYCLOPS_CORE_RUNNER
+ process.env.CYCLOPS_CORE_RUNNER = runner
+ let pid
+ try {
+ await assert.rejects(
+ connect({
+ baseUrl: "invalid",
+ oauth: { tokenUrl: "https://auth.example/token", clientId: "id", clientSecret: "secret" },
+ }),
+ /invalid configuration/,
+ )
+ pid = Number(await readFile(pidFile, "utf8"))
+ for (let attempt = 0; attempt < 20; attempt++) {
+ try {
+ assert.equal(await readFile(terminatedFile, "utf8"), "yes")
+ return
+ } catch {
+ await delay(25)
+ }
+ }
+ assert.fail("core runner was not terminated")
+ } finally {
+ if (previousRunner === undefined) delete process.env.CYCLOPS_CORE_RUNNER
+ else process.env.CYCLOPS_CORE_RUNNER = previousRunner
+ if (pid) {
+ try { process.kill(pid, "SIGKILL") } catch {}
+ }
+ }
+})
diff --git a/libs/fleet/sdk-bindings/typescript/test/public-api.ts b/libs/fleet/sdk-bindings/typescript/test/public-api.ts
new file mode 100644
index 0000000000..e7dc4db27b
--- /dev/null
+++ b/libs/fleet/sdk-bindings/typescript/test/public-api.ts
@@ -0,0 +1,57 @@
+import {
+ connect,
+ type Claim,
+ type CreateClaimRequest,
+ type CreatePoolRequest,
+ type Configuration,
+ type Pool,
+ type PoolSpec,
+ type Sandbox,
+ type ServiceFetch,
+} from "../src/index.js"
+
+const configuration: Configuration = {
+ baseUrl: "https://run.example",
+ oauth: { tokenUrl: "https://auth.example/token", clientId: "id", clientSecret: "secret" },
+}
+const poolSpec: PoolSpec = {
+ replicas: 1,
+ template: { containerDiskImage: "example/workspace:latest", cpuCores: 4, memory: "4Gi" },
+}
+const pool: Pool = {
+ apiVersion: "cua.ai/v1",
+ kind: "OSGymWorkspacePool",
+ metadata: { namespace: "pool-one", name: "pool-one" },
+ spec: { replicas: 1, template: { containerDiskImage: "example/workspace:latest", cpuCores: 4, memory: "4Gi" } },
+}
+const claim: Claim = {
+ apiVersion: "osgym.cua.ai/v1alpha1",
+ kind: "OSGymSandboxClaim",
+ metadata: { namespace: "pool-one", name: "claim-one" },
+ spec: { sandboxTemplateRef: { name: "pool-one-template" } },
+}
+
+async function contract(): Promise<Sandbox> {
+ const sdk = await connect(configuration)
+ const poolRequest: CreatePoolRequest = { namespace: "pool-one", spec: poolSpec }
+ const createdPool = await sdk.createPool(poolRequest)
+ await sdk.listPools(createdPool.metadata.namespace)
+ await sdk.getPool(pool)
+ await sdk.updatePool(pool)
+ const claimRequest: CreateClaimRequest = { pool: createdPool }
+ const createdClaim = await sdk.createClaim(claimRequest)
+ await sdk.listClaims(createdClaim.metadata.namespace)
+ await sdk.getClaim(claim)
+ await sdk.updateClaim(claim)
+ const sandbox = await sdk.waitClaim(claim)
+ const service: ServiceFetch = sdk.serviceFetch(sandbox, "mcp")
+ const response: Response = await service("/mcp", { method: "POST", body: "{}" })
+ void response
+ // @ts-expect-error URL-based authenticated clients are intentionally not public.
+ void sdk.rawClient
+ await sdk.deleteClaim(claim)
+ await sdk.deletePool(pool)
+ sdk.close()
+ return sandbox
+}
+void contract
diff --git a/libs/fleet/sdk-bindings/typescript/test/service-client.test.js b/libs/fleet/sdk-bindings/typescript/test/service-client.test.js
new file mode 100644
index 0000000000..53da8ad862
--- /dev/null
+++ b/libs/fleet/sdk-bindings/typescript/test/service-client.test.js
@@ -0,0 +1,16 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import { SDK, UnknownServiceError } from "../dist/index.js"
+
+test("serviceFetch rejects unknown services with sorted available names", () => {
+ const sdk = Object.create(SDK.prototype)
+ assert.throws(
+ () => sdk.serviceFetch({ namespace: "pool-one", claim: "claim-one", sandbox: "sandbox-one", services: ["novnc", "mcp", "mcp"] }, "metrics"),
+ error => {
+ assert.ok(error instanceof UnknownServiceError)
+ assert.equal(error.requested, "metrics")
+ assert.deepEqual(error.available, ["mcp", "novnc"])
+ return true
+ },
+ )
+})
diff --git a/libs/fleet/sdk-bindings/typescript/tsconfig.contract.json b/libs/fleet/sdk-bindings/typescript/tsconfig.contract.json
new file mode 100644
index 0000000000..8e3c56a096
--- /dev/null
+++ b/libs/fleet/sdk-bindings/typescript/tsconfig.contract.json
@@ -0,0 +1,10 @@
+{
+ "extends": "./tsconfig.json",
+ "compilerOptions": {
+ "rootDir": ".",
+ "outDir": "/tmp/cyclops-sdk-typescript-contract",
+ "declaration": false,
+ "noEmit": true
+ },
+ "include": ["src/**/*.ts", "test/**/*.ts"]
+}
diff --git a/libs/fleet/sdk-bindings/typescript/tsconfig.examples.json b/libs/fleet/sdk-bindings/typescript/tsconfig.examples.json
new file mode 100644
index 0000000000..3910c6ab42
--- /dev/null
+++ b/libs/fleet/sdk-bindings/typescript/tsconfig.examples.json
@@ -0,0 +1,11 @@
+{
+ "extends": "./tsconfig.json",
+ "compilerOptions": {
+ "rootDir": "../examples/typescript",
+ "outDir": "dist-examples",
+ "declaration": false
+ },
+ "include": [
+ "../examples/typescript/**/*.ts"
+ ]
+}
diff --git a/libs/fleet/sdk-bindings/typescript/tsconfig.json b/libs/fleet/sdk-bindings/typescript/tsconfig.json
new file mode 100644
index 0000000000..4d96503645
--- /dev/null
+++ b/libs/fleet/sdk-bindings/typescript/tsconfig.json
@@ -0,0 +1,14 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "outDir": "dist",
+ "rootDir": "src",
+ "strict": true,
+ "declaration": true,
+ "skipLibCheck": true,
+ "types": ["node"]
+ },
+ "include": ["src/**/*.ts"]
+}
diff --git a/libs/fleet/sdk-core/Cargo.lock b/libs/fleet/sdk-core/Cargo.lock
new file mode 100644
index 0000000000..a07a870163
--- /dev/null
+++ b/libs/fleet/sdk-core/Cargo.lock
@@ -0,0 +1,759 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "anyhow"
+version = "1.0.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a4385e2e34eb35d6b3efe798b9eb88096925d87726c0798709bf56d9ed84af3"
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "cyclops-sdk-core"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "serde_json",
+ "thiserror",
+ "url",
+ "wit-bindgen",
+]
+
+[[package]]
+name = "displaydoc"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+
+[[package]]
+name = "futures"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b147ee9d1f6d097cef9ce628cd2ee62288d963e16fb287bd9286455b241382d"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-executor",
+ "futures-io",
+ "futures-sink",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-channel"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d"
+dependencies = [
+ "futures-core",
+ "futures-sink",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
+
+[[package]]
+name = "futures-executor"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "baf29c38818342a3b26b5b923639e7b1f4a61fc5e76102d4b1981c6dc7a7579d"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-io"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cecba35d7ad927e23624b22ad55235f2239cfa44fd10428eecbeba6d6a717718"
+
+[[package]]
+name = "futures-macro"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e835b70203e41293343137df5c0664546da5745f82ec9b84d40be8336958447b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "futures-sink"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c39754e157331b013978ec91992bde1ac089843443c49cbc7f46150b0fad0893"
+
+[[package]]
+name = "futures-task"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
+
+[[package]]
+name = "futures-util"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-io",
+ "futures-macro",
+ "futures-sink",
+ "futures-task",
+ "memchr",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "icu_collections"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "utf8_iter",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38"
+
+[[package]]
+name = "icu_properties"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de"
+dependencies = [
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14"
+
+[[package]]
+name = "icu_provider"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "id-arena"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954"
+
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown 0.17.1",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "leb128fmt"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
+
+[[package]]
+name = "litemap"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
+
+[[package]]
+name = "log"
+version = "0.4.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "potential_utf"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
+dependencies = [
+ "zerovec",
+]
+
+[[package]]
+name = "prettyplease"
+version = "0.2.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
+dependencies = [
+ "proc-macro2",
+ "syn",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+
+[[package]]
+name = "spdx"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3e17e880bafaeb362a7b751ec46bdc5b61445a188f80e0606e68167cd540fa3"
+dependencies = [
+ "smallvec",
+]
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "synstructure"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tinystr"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-xid"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
+
+[[package]]
+name = "url"
+version = "2.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+]
+
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
+[[package]]
+name = "wasm-encoder"
+version = "0.225.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f7eac0445cac73bcf09e6a97f83248d64356dccf9f2b100199769b6b42464e5"
+dependencies = [
+ "leb128fmt",
+ "wasmparser",
+]
+
+[[package]]
+name = "wasm-metadata"
+version = "0.225.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1d20d0bf2c73c32a5114cf35a5c10ccf9f9aa37a3a2c0114b3e11cbf6faac12"
+dependencies = [
+ "anyhow",
+ "indexmap",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "spdx",
+ "url",
+ "wasm-encoder",
+ "wasmparser",
+]
+
+[[package]]
+name = "wasmparser"
+version = "0.225.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36e5456165f81e64cb9908a0fe9b9d852c2c74582aa3fe2be3c2da57f937d3ae"
+dependencies = [
+ "bitflags",
+ "hashbrown 0.15.5",
+ "indexmap",
+ "semver",
+]
+
+[[package]]
+name = "wit-bindgen"
+version = "0.39.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4dd9a372b25d6f35456b0a730d2adabeb0c4878066ba8f8089800349be6ecb5"
+dependencies = [
+ "wit-bindgen-rt",
+ "wit-bindgen-rust-macro",
+]
+
+[[package]]
+name = "wit-bindgen-core"
+version = "0.39.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f108fa9b77a346372858b30c11ea903680e7e2b9d820b1a5883e9d530bf51c7e"
+dependencies = [
+ "anyhow",
+ "heck",
+ "wit-parser",
+]
+
+[[package]]
+name = "wit-bindgen-rt"
+version = "0.39.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f42320e61fe2cfd34354ecb597f86f413484a798ba44a8ca1165c58d42da6c1"
+dependencies = [
+ "bitflags",
+ "futures",
+ "once_cell",
+]
+
+[[package]]
+name = "wit-bindgen-rust"
+version = "0.39.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5ba5b852e976d35dbf6cb745746bf1bd4fc26782bab1e0c615fc71a7d8aac05"
+dependencies = [
+ "anyhow",
+ "heck",
+ "indexmap",
+ "prettyplease",
+ "syn",
+ "wasm-metadata",
+ "wit-bindgen-core",
+ "wit-component",
+]
+
+[[package]]
+name = "wit-bindgen-rust-macro"
+version = "0.39.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "401529c9af9304a20ed99fa01799e467b7d37727126f0c9a958895471268ad7a"
+dependencies = [
+ "anyhow",
+ "prettyplease",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wit-bindgen-core",
+ "wit-bindgen-rust",
+]
+
+[[package]]
+name = "wit-component"
+version = "0.225.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2505c917564c1d74774563bbcd3e4f8c216a6508050862fd5f449ee56e3c5125"
+dependencies = [
+ "anyhow",
+ "bitflags",
+ "indexmap",
+ "log",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "wasm-encoder",
+ "wasm-metadata",
+ "wasmparser",
+ "wit-parser",
+]
+
+[[package]]
+name = "wit-parser"
+version = "0.225.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebefaa234e47224f10ce60480c5bfdece7497d0f3b87a12b41ff39e5c8377a78"
+dependencies = [
+ "anyhow",
+ "id-arena",
+ "indexmap",
+ "log",
+ "semver",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "unicode-xid",
+ "wasmparser",
+]
+
+[[package]]
+name = "writeable"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
+
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "synstructure",
+]
+
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "synstructure",
+]
+
+[[package]]
+name = "zerotrie"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
diff --git a/libs/fleet/sdk-core/Cargo.toml b/libs/fleet/sdk-core/Cargo.toml
new file mode 100644
index 0000000000..4ab17c1e69
--- /dev/null
+++ b/libs/fleet/sdk-core/Cargo.toml
@@ -0,0 +1,19 @@
+[package]
+name = "cyclops-sdk-core"
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[[bin]]
+name = "cyclops-core-runner"
+path = "src/core_runner.rs"
+
+[dependencies]
+serde = { version = "1.0.217", features = ["derive"] }
+serde_json = "1.0.138"
+thiserror = "2.0.11"
+url = "2.5.8"
+wit-bindgen = "0.39.0"
diff --git a/libs/fleet/sdk-core/README.md b/libs/fleet/sdk-core/README.md
new file mode 100644
index 0000000000..c033b23a88
--- /dev/null
+++ b/libs/fleet/sdk-core/README.md
@@ -0,0 +1,9 @@
+# Cyclops SDK core
+
+The Rust core owns typed pool and claim CRUD, porcelain defaults, claim polling, service endpoint resolution, OAuth token caching and refresh, authenticated HTTP execution, and one retry after `401`. Bindings never receive bearer tokens or service endpoint URLs.
+
+Pool creation accepts `namespace + PoolSpec`, ensures the caller-owned namespace, and rolls the namespace back if pool creation fails. Pool deletion removes the pool before deleting its namespace. For nonzero replica pools, claim creation waits for an available sandbox before creating the claim. Zero-replica pools remain demand-driven. Claim creation accepts an optional generated `ClaimSpec`; otherwise, the core derives `<pool-name>-template`.
+
+`wait_claim` returns sandbox identity and the service names declared by its pool. `service_request` accepts that sandbox, one declared service name, and an HTTP request with a relative path. The core validates every route component, resolves the private control-plane route, applies managed authorization, performs the request, and refreshes the token once after `401`. Unknown-service errors include the requested name and sorted available names. No exported operation accepts an application-constructed URL.
+
+The native JSON-lines runner and WASM component expose the same typed resource and service HTTP operations. Language bindings provide transport adapters and idiomatic request surfaces only.
diff --git a/libs/fleet/sdk-core/rust-toolchain.toml b/libs/fleet/sdk-core/rust-toolchain.toml
new file mode 100644
index 0000000000..75ee9179c2
--- /dev/null
+++ b/libs/fleet/sdk-core/rust-toolchain.toml
@@ -0,0 +1,4 @@
+[toolchain]
+channel = "1.97.0"
+targets = ["wasm32-wasip2"]
+profile = "minimal"
diff --git a/libs/fleet/sdk-core/src/client.rs b/libs/fleet/sdk-core/src/client.rs
new file mode 100644
index 0000000000..a08af33b14
--- /dev/null
+++ b/libs/fleet/sdk-core/src/client.rs
@@ -0,0 +1,752 @@
+use crate::{
+ validate_configuration, validate_name, Claim, ClaimSpec, Configuration, CreateClaimRequest,
+ CreatePoolRequest, Pool, ResourceList, ResourceMetadata, Sandbox, SandboxTemplateRef,
+};
+use serde::{de::DeserializeOwned, Deserialize, Serialize};
+use serde_json::Value;
+use std::collections::BTreeMap;
+use thiserror::Error;
+use url::{form_urlencoded, Url as ParsedUrl};
+
+const TOKEN_EXPIRY_SKEW_MS: u64 = 30_000;
+const POOL_POLL_INTERVAL_MS: u64 = 5_000;
+const POOL_MAX_POLL_ATTEMPTS: u32 = 180;
+const CLAIM_POLL_INTERVAL_MS: u64 = 5_000;
+const CLAIM_MAX_POLL_ATTEMPTS: u32 = 180;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct HttpRequest {
+ pub method: String,
+ pub url: String,
+ pub headers: Vec<(String, String)>,
+ pub body: Option<String>,
+}
+
+impl HttpRequest {
+ pub fn get(url: impl Into<String>) -> Self {
+ Self::new("GET", url, None)
+ }
+ pub fn post(url: impl Into<String>, body: impl Into<String>) -> Self {
+ Self::new("POST", url, Some(body.into()))
+ }
+ pub fn put(url: impl Into<String>, body: impl Into<String>) -> Self {
+ Self::new("PUT", url, Some(body.into()))
+ }
+ pub fn delete(url: impl Into<String>) -> Self {
+ Self::new("DELETE", url, None)
+ }
+ pub fn new(method: impl Into<String>, url: impl Into<String>, body: Option<String>) -> Self {
+ Self {
+ method: method.into(),
+ url: url.into(),
+ headers: vec![
+ ("accept".into(), "application/json".into()),
+ ("content-type".into(), "application/json".into()),
+ ],
+ body,
+ }
+ }
+ fn with_bearer(mut self, token: &str) -> Self {
+ self.headers
+ .retain(|(name, _)| !name.eq_ignore_ascii_case("authorization"));
+ self.headers
+ .push(("authorization".into(), format!("Bearer {token}")));
+ self
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct HttpResponse {
+ pub status: u16,
+ pub body: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ServiceHttpRequest {
+ pub method: String,
+ pub path: String,
+ pub headers: Vec<(String, String)>,
+ pub body: Option<String>,
+}
+
+impl ServiceHttpRequest {
+ pub fn get(path: impl Into<String>) -> Self {
+ Self::new("GET", path, None)
+ }
+ pub fn post(path: impl Into<String>, body: impl Into<String>) -> Self {
+ Self::new("POST", path, Some(body.into()))
+ }
+ pub fn new(method: impl Into<String>, path: impl Into<String>, body: Option<String>) -> Self {
+ Self {
+ method: method.into(),
+ path: path.into(),
+ headers: Vec::new(),
+ body,
+ }
+ }
+}
+
+pub type ServiceHttpResponse = HttpResponse;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct OAuthCredentials {
+ pub token_url: String,
+ pub client_id: String,
+ pub client_secret: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct AccessToken {
+ pub value: String,
+ pub expires_at_ms: u64,
+}
+
+#[derive(Debug, Clone, Error, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum PlatformError {
+ #[error("transport error: {0}")]
+ Transport(String),
+ #[error("clock error: {0}")]
+ Clock(String),
+ #[error("credential error: {0}")]
+ Credentials(String),
+ #[error("token storage error: {0}")]
+ TokenStorage(String),
+}
+
+pub trait Platform {
+ fn http(&mut self, request: HttpRequest) -> Result<HttpResponse, PlatformError>;
+ fn sleep(&mut self, milliseconds: u64) -> Result<(), PlatformError>;
+ fn now_ms(&mut self) -> u64;
+ fn acquire_oauth_credentials(&mut self) -> Result<OAuthCredentials, PlatformError>;
+ fn load_access_token(&mut self) -> Result<Option<AccessToken>, PlatformError>;
+ fn store_access_token(&mut self, token: &AccessToken) -> Result<(), PlatformError>;
+}
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum SdkError {
+ #[error("invalid configuration: {0}")]
+ Configuration(String),
+ #[error("transport error: {0}")]
+ Transport(String),
+ #[error("token error: {0}")]
+ Token(String),
+ #[error("response body error: {0}")]
+ Body(String),
+ #[error("{operation} returned HTTP {status}: {body}")]
+ Status {
+ operation: String,
+ status: u16,
+ body: String,
+ },
+ #[error("pool entered terminal phase {phase}: {status}")]
+ PoolFailed { phase: String, status: String },
+ #[error("pool did not become available before the polling limit")]
+ PoolTimeout,
+ #[error("claim entered terminal phase {phase}: {status}")]
+ ClaimFailed { phase: String, status: String },
+ #[error("claim did not bind before the polling limit")]
+ ClaimTimeout,
+ #[error("unknown sandbox service {requested:?}; available services: {available:?}")]
+ UnknownService {
+ requested: String,
+ available: Vec<String>,
+ },
+ #[error("service request path must be relative and start with '/': {0}")]
+ InvalidServicePath(String),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Url(String);
+impl Url {
+ pub fn as_str(&self) -> &str {
+ &self.0
+ }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PoolUrl {
+ collection: Url,
+ item: Url,
+}
+impl PoolUrl {
+ pub fn new(base: &str, namespace: &str, name: &str) -> Result<Self, SdkError> {
+ validate_url_parts(base, namespace, name)?;
+ let collection = format!(
+ "{}/api/k8s/apis/cua.ai/v1/namespaces/{namespace}/osgymworkspacepools",
+ base.trim_end_matches('/')
+ );
+ Ok(Self {
+ item: Url(format!("{collection}/{name}")),
+ collection: Url(collection),
+ })
+ }
+ pub fn collection(&self) -> &Url {
+ &self.collection
+ }
+ pub fn item(&self) -> &Url {
+ &self.item
+ }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClaimUrl {
+ collection: Url,
+ item: Url,
+}
+impl ClaimUrl {
+ pub fn new(base: &str, namespace: &str, name: &str) -> Result<Self, SdkError> {
+ validate_url_parts(base, namespace, name)?;
+ let collection = format!(
+ "{}/api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxclaims",
+ base.trim_end_matches('/')
+ );
+ Ok(Self {
+ item: Url(format!("{collection}/{name}")),
+ collection: Url(collection),
+ })
+ }
+ pub fn collection(&self) -> &Url {
+ &self.collection
+ }
+ pub fn item(&self) -> &Url {
+ &self.item
+ }
+}
+
+pub struct Sdk<P> {
+ platform: P,
+ configuration: Configuration,
+ next_claim_id: u64,
+ claim_services: BTreeMap<String, Vec<String>>,
+}
+
+impl<P: Platform> Sdk<P> {
+ pub fn connect(platform: P, configuration: Configuration) -> Result<Self, SdkError> {
+ validate_configuration(&configuration)
+ .map_err(|error| SdkError::Configuration(error.to_string()))?;
+ Ok(Self {
+ platform,
+ configuration,
+ next_claim_id: 0,
+ claim_services: BTreeMap::new(),
+ })
+ }
+ pub fn platform(&self) -> &P {
+ &self.platform
+ }
+ pub fn platform_mut(&mut self) -> &mut P {
+ &mut self.platform
+ }
+ pub fn into_platform(self) -> P {
+ self.platform
+ }
+ pub fn service_request(
+ &mut self,
+ sandbox: &Sandbox,
+ service: &str,
+ request: ServiceHttpRequest,
+ ) -> Result<ServiceHttpResponse, SdkError> {
+ validate_service(sandbox, service)?;
+ let url = service_url(
+ &self.configuration.base_url,
+ sandbox,
+ service,
+ &request.path,
+ )?;
+ let mut headers = request.headers;
+ headers.retain(|(name, _)| !is_transport_owned_header(name));
+ self.send_raw(HttpRequest {
+ method: request.method,
+ url,
+ headers,
+ body: request.body,
+ })
+ }
+
+ pub fn create_pool(&mut self, request: CreatePoolRequest) -> Result<Pool, SdkError> {
+ validate_name(&request.namespace)
+ .map_err(|error| SdkError::Configuration(error.to_string()))?;
+ let namespace = request.namespace.clone();
+ let namespace_created = self.ensure_namespace(&namespace)?;
+ let pool = Pool {
+ api_version: "cua.ai/v1".into(),
+ kind: "OSGymWorkspacePool".into(),
+ metadata: ResourceMetadata {
+ namespace: namespace.clone(),
+ name: request.namespace,
+ labels: None,
+ },
+ spec: serde_json::to_value(request.spec)
+ .map_err(|error| SdkError::Body(error.to_string()))?,
+ status: None,
+ };
+ let url = self.pool_url(&pool)?;
+ let result = self.send_json(
+ "create pool",
+ HttpRequest::post(url.collection().as_str(), to_json(&pool)?),
+ &[200, 201, 202],
+ );
+ if result.is_err() && namespace_created {
+ let _ = self.delete_namespace(&namespace);
+ }
+ result
+ }
+ pub fn list_pools(&mut self, namespace: &str) -> Result<Vec<Pool>, SdkError> {
+ let url = PoolUrl::new(&self.configuration.base_url, namespace, "list")?;
+ let list: ResourceList<Pool> = self.send_json(
+ "list pools",
+ HttpRequest::get(url.collection().as_str()),
+ &[200],
+ )?;
+ Ok(list.items)
+ }
+ pub fn get_pool(&mut self, pool: Pool) -> Result<Pool, SdkError> {
+ let url = self.pool_url(&pool)?;
+ self.send_json("get pool", HttpRequest::get(url.item().as_str()), &[200])
+ }
+ pub fn update_pool(&mut self, pool: Pool) -> Result<Pool, SdkError> {
+ let url = self.pool_url(&pool)?;
+ self.send_json(
+ "update pool",
+ HttpRequest::put(url.item().as_str(), to_json(&pool)?),
+ &[200],
+ )
+ }
+ pub fn delete_pool(&mut self, pool: Pool) -> Result<(), SdkError> {
+ let namespace = pool.metadata.namespace.clone();
+ let url = self.pool_url(&pool)?;
+ self.send_unit(
+ "delete pool",
+ HttpRequest::delete(url.item().as_str()),
+ &[200, 202, 204, 404],
+ )?;
+ self.delete_namespace(&namespace)
+ }
+ pub fn create_claim(&mut self, request: CreateClaimRequest) -> Result<Claim, SdkError> {
+ let CreateClaimRequest { pool, spec } = request;
+ let requested_replicas = pool
+ .spec
+ .get("replicas")
+ .and_then(Value::as_u64)
+ .unwrap_or(0);
+ let pool = if requested_replicas > 0 {
+ self.wait_pool_ready(pool)?
+ } else {
+ pool
+ };
+ let services = service_names(&pool);
+ let namespace = pool.metadata.namespace;
+ let pool_name = pool.metadata.name;
+ validate_name(&namespace).map_err(|error| SdkError::Configuration(error.to_string()))?;
+ validate_name(&pool_name).map_err(|error| SdkError::Configuration(error.to_string()))?;
+ let spec = match spec {
+ Some(spec) => spec,
+ None => ClaimSpec::builder()
+ .sandbox_template_ref(
+ SandboxTemplateRef::builder()
+ .name(format!("{pool_name}-template"))
+ .build()
+ .map_err(SdkError::Configuration)?,
+ )
+ .build()
+ .map_err(SdkError::Configuration)?,
+ };
+ validate_name(&spec.sandbox_template_ref.name)
+ .map_err(|error| SdkError::Configuration(error.to_string()))?;
+ let claim_id = self.next_claim_id;
+ self.next_claim_id = self.next_claim_id.wrapping_add(1);
+ let claim = Claim {
+ api_version: "osgym.cua.ai/v1alpha1".into(),
+ kind: "OSGymSandboxClaim".into(),
+ metadata: ResourceMetadata {
+ namespace,
+ name: format!("claim-{:x}-{claim_id:x}", self.platform.now_ms()),
+ labels: None,
+ },
+ spec: serde_json::to_value(spec).map_err(|error| SdkError::Body(error.to_string()))?,
+ status: None,
+ };
+ let url = self.claim_url(&claim)?;
+ let created = self.send_json(
+ "create claim",
+ HttpRequest::post(url.collection().as_str(), to_json(&claim)?),
+ &[200, 201, 202],
+ )?;
+ self.claim_services.insert(claim_key(&created), services);
+ Ok(created)
+ }
+ pub fn list_claims(&mut self, namespace: &str) -> Result<Vec<Claim>, SdkError> {
+ let url = ClaimUrl::new(&self.configuration.base_url, namespace, "list")?;
+ let list: ResourceList<Claim> = self.send_json(
+ "list claims",
+ HttpRequest::get(url.collection().as_str()),
+ &[200],
+ )?;
+ Ok(list.items)
+ }
+ pub fn get_claim(&mut self, claim: Claim) -> Result<Claim, SdkError> {
+ let url = self.claim_url(&claim)?;
+ self.send_json("get claim", HttpRequest::get(url.item().as_str()), &[200])
+ }
+ pub fn update_claim(&mut self, claim: Claim) -> Result<Claim, SdkError> {
+ let url = self.claim_url(&claim)?;
+ self.send_json(
+ "update claim",
+ HttpRequest::put(url.item().as_str(), to_json(&claim)?),
+ &[200],
+ )
+ }
+ pub fn delete_claim(&mut self, claim: Claim) -> Result<(), SdkError> {
+ let key = claim_key(&claim);
+ let url = self.claim_url(&claim)?;
+ self.send_unit(
+ "delete claim",
+ HttpRequest::delete(url.item().as_str()),
+ &[200, 202, 204, 404],
+ )?;
+ self.claim_services.remove(&key);
+ Ok(())
+ }
+ pub fn wait_claim(&mut self, claim: Claim) -> Result<Sandbox, SdkError> {
+ let services = self.services_for_claim(&claim)?;
+ for _ in 0..CLAIM_MAX_POLL_ATTEMPTS {
+ let current = self.get_claim(claim.clone())?;
+ let phase = current
+ .status
+ .as_ref()
+ .and_then(|status| status.get("phase"))
+ .and_then(Value::as_str)
+ .unwrap_or("Pending");
+ if phase == "Bound" {
+ return sandbox_from_claim(&current, services.clone());
+ }
+ if matches!(phase, "Failed" | "Error" | "Expired") {
+ return Err(SdkError::ClaimFailed {
+ phase: phase.into(),
+ status: current
+ .status
+ .as_ref()
+ .map(Value::to_string)
+ .unwrap_or_else(|| "null".into()),
+ });
+ }
+ self.platform
+ .sleep(CLAIM_POLL_INTERVAL_MS)
+ .map_err(map_platform_error)?;
+ }
+ Err(SdkError::ClaimTimeout)
+ }
+
+ fn services_for_claim(&mut self, claim: &Claim) -> Result<Vec<String>, SdkError> {
+ if let Some(services) = self.claim_services.get(&claim_key(claim)) {
+ return Ok(services.clone());
+ }
+ let template = claim
+ .spec
+ .get("sandboxTemplateRef")
+ .and_then(|value| value.get("name"))
+ .and_then(Value::as_str)
+ .ok_or_else(|| SdkError::Body("claim omitted spec.sandboxTemplateRef.name".into()))?;
+ let pool_name = template.strip_suffix("-template").ok_or_else(|| {
+ SdkError::Body(format!("cannot resolve pool from template {template:?}"))
+ })?;
+ let url = PoolUrl::new(
+ &self.configuration.base_url,
+ &claim.metadata.namespace,
+ pool_name,
+ )?;
+ let pool: Pool = self.send_json(
+ "get pool services",
+ HttpRequest::get(url.item().as_str()),
+ &[200],
+ )?;
+ Ok(service_names(&pool))
+ }
+
+ fn wait_pool_ready(&mut self, pool: Pool) -> Result<Pool, SdkError> {
+ for _ in 0..POOL_MAX_POLL_ATTEMPTS {
+ let current = self.get_pool(pool.clone())?;
+ let status = current.status.as_ref();
+ let available = status
+ .and_then(|value| value.get("availableCount"))
+ .and_then(Value::as_u64)
+ .unwrap_or(0);
+ if available > 0 {
+ return Ok(current);
+ }
+ let phase = status
+ .and_then(|value| value.get("phase"))
+ .and_then(Value::as_str)
+ .unwrap_or("Provisioning");
+ if matches!(phase, "Failed" | "Error") {
+ return Err(SdkError::PoolFailed {
+ phase: phase.into(),
+ status: status
+ .map(Value::to_string)
+ .unwrap_or_else(|| "null".into()),
+ });
+ }
+ self.platform
+ .sleep(POOL_POLL_INTERVAL_MS)
+ .map_err(map_platform_error)?;
+ }
+ Err(SdkError::PoolTimeout)
+ }
+
+ fn ensure_namespace(&mut self, name: &str) -> Result<bool, SdkError> {
+ validate_name(name).map_err(|error| SdkError::Configuration(error.to_string()))?;
+ let url = format!(
+ "{}/api/namespaces",
+ self.configuration.base_url.trim_end_matches('/')
+ );
+ let response = self.send_allowed(
+ "create namespace",
+ HttpRequest::post(url, to_json(&serde_json::json!({ "name": name }))?),
+ &[200, 201, 202, 409],
+ )?;
+ Ok(response.status != 409)
+ }
+ fn delete_namespace(&mut self, name: &str) -> Result<(), SdkError> {
+ validate_name(name).map_err(|error| SdkError::Configuration(error.to_string()))?;
+ let url = format!(
+ "{}/api/namespaces/{name}",
+ self.configuration.base_url.trim_end_matches('/')
+ );
+ self.send_unit(
+ "delete namespace",
+ HttpRequest::delete(url),
+ &[200, 202, 204, 404],
+ )
+ }
+
+ fn pool_url(&self, pool: &Pool) -> Result<PoolUrl, SdkError> {
+ PoolUrl::new(
+ &self.configuration.base_url,
+ &pool.metadata.namespace,
+ &pool.metadata.name,
+ )
+ }
+ fn claim_url(&self, claim: &Claim) -> Result<ClaimUrl, SdkError> {
+ ClaimUrl::new(
+ &self.configuration.base_url,
+ &claim.metadata.namespace,
+ &claim.metadata.name,
+ )
+ }
+ fn send_json<T: DeserializeOwned>(
+ &mut self,
+ operation: &str,
+ request: HttpRequest,
+ allowed: &[u16],
+ ) -> Result<T, SdkError> {
+ let response = self.send_allowed(operation, request, allowed)?;
+ serde_json::from_str(&response.body).map_err(|error| SdkError::Body(error.to_string()))
+ }
+ fn send_unit(
+ &mut self,
+ operation: &str,
+ request: HttpRequest,
+ allowed: &[u16],
+ ) -> Result<(), SdkError> {
+ self.send_allowed(operation, request, allowed).map(|_| ())
+ }
+ fn send_allowed(
+ &mut self,
+ operation: &str,
+ request: HttpRequest,
+ allowed: &[u16],
+ ) -> Result<HttpResponse, SdkError> {
+ let response = self.send_raw(request)?;
+ if allowed.contains(&response.status) {
+ Ok(response)
+ } else {
+ Err(status_error(operation, response))
+ }
+ }
+ fn send_raw(&mut self, request: HttpRequest) -> Result<HttpResponse, SdkError> {
+ if !same_origin(&self.configuration.base_url, &request.url) {
+ return self.platform.http(request).map_err(map_platform_error);
+ }
+ let token = self.access_token(false)?;
+ let response = self
+ .platform
+ .http(request.clone().with_bearer(&token.value))
+ .map_err(map_platform_error)?;
+ if response.status != 401 {
+ return Ok(response);
+ }
+ let refreshed = self.access_token(true)?;
+ self.platform
+ .http(request.with_bearer(&refreshed.value))
+ .map_err(map_platform_error)
+ }
+ fn access_token(&mut self, force_refresh: bool) -> Result<AccessToken, SdkError> {
+ let now = self.platform.now_ms();
+ if !force_refresh {
+ if let Some(token) = self
+ .platform
+ .load_access_token()
+ .map_err(map_platform_error)?
+ {
+ if token.expires_at_ms > now.saturating_add(TOKEN_EXPIRY_SKEW_MS) {
+ return Ok(token);
+ }
+ }
+ }
+ let credentials = self
+ .platform
+ .acquire_oauth_credentials()
+ .map_err(map_platform_error)?;
+ let body = form_urlencoded::Serializer::new(String::new())
+ .append_pair("grant_type", "client_credentials")
+ .append_pair("client_id", &credentials.client_id)
+ .append_pair("client_secret", &credentials.client_secret)
+ .finish();
+ let mut request = HttpRequest::post(credentials.token_url, body);
+ request.headers = vec![
+ ("accept".into(), "application/json".into()),
+ (
+ "content-type".into(),
+ "application/x-www-form-urlencoded".into(),
+ ),
+ ];
+ let response = self.platform.http(request).map_err(map_platform_error)?;
+ if !(200..300).contains(&response.status) {
+ return Err(status_error("acquire OAuth token", response));
+ }
+ #[derive(Deserialize)]
+ struct TokenResponse {
+ access_token: String,
+ expires_in: u64,
+ }
+ let body: TokenResponse = serde_json::from_str(&response.body)
+ .map_err(|error| SdkError::Token(error.to_string()))?;
+ let token = AccessToken {
+ value: body.access_token,
+ expires_at_ms: now.saturating_add(body.expires_in.saturating_mul(1_000)),
+ };
+ self.platform
+ .store_access_token(&token)
+ .map_err(map_platform_error)?;
+ Ok(token)
+ }
+}
+
+fn same_origin(base: &str, request: &str) -> bool {
+ match (ParsedUrl::parse(base), ParsedUrl::parse(request)) {
+ (Ok(base), Ok(request)) => base.origin() == request.origin(),
+ _ => false,
+ }
+}
+fn validate_url_parts(base: &str, namespace: &str, name: &str) -> Result<(), SdkError> {
+ if !(base.starts_with("http://") || base.starts_with("https://")) {
+ return Err(SdkError::Configuration(
+ "base_url must use http or https".into(),
+ ));
+ }
+ validate_name(namespace).map_err(|error| SdkError::Configuration(error.to_string()))?;
+ validate_name(name).map_err(|error| SdkError::Configuration(error.to_string()))
+}
+fn to_json<T: Serialize>(value: &T) -> Result<String, SdkError> {
+ serde_json::to_string(value).map_err(|error| SdkError::Body(error.to_string()))
+}
+fn status_error(operation: &str, response: HttpResponse) -> SdkError {
+ SdkError::Status {
+ operation: operation.into(),
+ status: response.status,
+ body: response.body,
+ }
+}
+fn map_platform_error(error: PlatformError) -> SdkError {
+ SdkError::Transport(error.to_string())
+}
+fn claim_key(claim: &Claim) -> String {
+ format!("{}/{}", claim.metadata.namespace, claim.metadata.name)
+}
+
+fn service_names(pool: &Pool) -> Vec<String> {
+ let mut services = pool
+ .spec
+ .get("services")
+ .and_then(Value::as_array)
+ .into_iter()
+ .flatten()
+ .filter_map(|service| service.get("name").and_then(Value::as_str))
+ .map(str::to_owned)
+ .collect::<Vec<_>>();
+ services.sort();
+ services.dedup();
+ services
+}
+
+fn validate_service(sandbox: &Sandbox, service: &str) -> Result<(), SdkError> {
+ if sandbox
+ .services
+ .iter()
+ .any(|available| available == service)
+ {
+ return Ok(());
+ }
+ let mut available = sandbox.services.clone();
+ available.sort();
+ available.dedup();
+ Err(SdkError::UnknownService {
+ requested: service.into(),
+ available,
+ })
+}
+
+fn is_transport_owned_header(name: &str) -> bool {
+ matches!(
+ name.to_ascii_lowercase().as_str(),
+ "host"
+ | "connection"
+ | "proxy-authorization"
+ | "proxy-connection"
+ | "te"
+ | "trailer"
+ | "transfer-encoding"
+ | "upgrade"
+ )
+}
+
+fn service_url(
+ base_url: &str,
+ sandbox: &Sandbox,
+ service: &str,
+ path: &str,
+) -> Result<String, SdkError> {
+ validate_url_parts(base_url, &sandbox.namespace, &sandbox.sandbox)?;
+ validate_name(service).map_err(|error| SdkError::Configuration(error.to_string()))?;
+ if !path.starts_with('/') || path.starts_with("//") || path.contains('#') {
+ return Err(SdkError::InvalidServicePath(path.into()));
+ }
+ Ok(format!(
+ "{}/api/svc/{}/{}-{}{}",
+ base_url.trim_end_matches('/'),
+ sandbox.namespace,
+ sandbox.sandbox,
+ service,
+ path
+ ))
+}
+
+fn sandbox_from_claim(claim: &Claim, services: Vec<String>) -> Result<Sandbox, SdkError> {
+ let status = claim
+ .status
+ .as_ref()
+ .ok_or_else(|| SdkError::Body("bound claim omitted status".into()))?;
+ let sandbox = status
+ .get("sandbox")
+ .and_then(|value| value.get("name"))
+ .and_then(Value::as_str)
+ .ok_or_else(|| SdkError::Body("bound claim omitted status.sandbox.name".into()))?
+ .to_string();
+ Ok(Sandbox {
+ namespace: claim.metadata.namespace.clone(),
+ claim: claim.metadata.name.clone(),
+ sandbox,
+ services,
+ })
+}
diff --git a/libs/fleet/sdk-core/src/core_runner.rs b/libs/fleet/sdk-core/src/core_runner.rs
new file mode 100644
index 0000000000..ce5ad10ccb
--- /dev/null
+++ b/libs/fleet/sdk-core/src/core_runner.rs
@@ -0,0 +1,232 @@
+use cyclops_sdk_core::{
+ AccessToken, Claim, Configuration, CreateClaimRequest, CreatePoolRequest, HttpRequest,
+ HttpResponse, OAuthCredentials, Platform, PlatformError, Pool, Sandbox, Sdk,
+ ServiceHttpRequest,
+};
+use serde::{de::DeserializeOwned, Deserialize, Serialize};
+use std::io::{self, BufRead, Write};
+
+#[derive(Deserialize)]
+#[serde(tag = "op", rename_all = "snake_case")]
+enum Request {
+ Configure {
+ configuration: Configuration,
+ },
+ CreatePool {
+ request: Box<CreatePoolRequest>,
+ },
+ ListPools {
+ namespace: String,
+ },
+ GetPool {
+ pool: Pool,
+ },
+ UpdatePool {
+ pool: Pool,
+ },
+ DeletePool {
+ pool: Pool,
+ },
+ CreateClaim {
+ request: Box<CreateClaimRequest>,
+ },
+ ListClaims {
+ namespace: String,
+ },
+ GetClaim {
+ claim: Claim,
+ },
+ UpdateClaim {
+ claim: Claim,
+ },
+ DeleteClaim {
+ claim: Claim,
+ },
+ WaitClaim {
+ claim: Claim,
+ },
+ #[serde(rename = "service_request")]
+ ServiceHttp {
+ sandbox: Sandbox,
+ service: String,
+ request: ServiceHttpRequest,
+ },
+}
+
+#[derive(Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+enum HostCall<'a> {
+ Http { request: HttpRequest },
+ Sleep { milliseconds: u64 },
+ NowMs,
+ AcquireOauthCredentials,
+ LoadAccessToken,
+ StoreAccessToken { token: &'a AccessToken },
+}
+
+#[derive(Deserialize)]
+struct HostReply {
+ ok: bool,
+ value: serde_json::Value,
+ error: Option<PlatformError>,
+}
+#[derive(Serialize)]
+struct Reply<T> {
+ ok: bool,
+ value: Option<T>,
+ error: Option<String>,
+}
+struct RpcPlatform<R, W> {
+ input: R,
+ output: W,
+}
+
+impl<R: BufRead, W: Write> RpcPlatform<R, W> {
+ fn read_request(&mut self) -> Result<Option<Request>, String> {
+ let mut line = String::new();
+ if self
+ .input
+ .read_line(&mut line)
+ .map_err(|error| error.to_string())?
+ == 0
+ {
+ return Ok(None);
+ }
+ serde_json::from_str(&line)
+ .map(Some)
+ .map_err(|error| error.to_string())
+ }
+ fn write_reply<T: Serialize>(&mut self, reply: &Reply<T>) -> Result<(), String> {
+ serde_json::to_writer(&mut self.output, reply).map_err(|error| error.to_string())?;
+ writeln!(self.output).map_err(|error| error.to_string())?;
+ self.output.flush().map_err(|error| error.to_string())
+ }
+ fn call<T: DeserializeOwned>(&mut self, call: HostCall<'_>) -> Result<T, PlatformError> {
+ serde_json::to_writer(&mut self.output, &call)
+ .map_err(|error| PlatformError::Transport(error.to_string()))?;
+ writeln!(self.output).map_err(|error| PlatformError::Transport(error.to_string()))?;
+ self.output
+ .flush()
+ .map_err(|error| PlatformError::Transport(error.to_string()))?;
+ let mut line = String::new();
+ self.input
+ .read_line(&mut line)
+ .map_err(|error| PlatformError::Transport(error.to_string()))?;
+ if line.is_empty() {
+ return Err(PlatformError::Transport("host adapter exited".into()));
+ }
+ let reply: HostReply = serde_json::from_str(&line)
+ .map_err(|error| PlatformError::Transport(format!("invalid host reply: {error}")))?;
+ if reply.ok {
+ serde_json::from_value(reply.value).map_err(|error| {
+ PlatformError::Transport(format!("invalid host reply value: {error}"))
+ })
+ } else {
+ Err(reply
+ .error
+ .unwrap_or_else(|| PlatformError::Transport("host reply omitted error".into())))
+ }
+ }
+ fn call_unit(&mut self, call: HostCall<'_>) -> Result<(), PlatformError> {
+ let _: serde_json::Value = self.call(call)?;
+ Ok(())
+ }
+}
+
+impl<R: BufRead, W: Write> Platform for RpcPlatform<R, W> {
+ fn http(&mut self, request: HttpRequest) -> Result<HttpResponse, PlatformError> {
+ self.call(HostCall::Http { request })
+ }
+ fn sleep(&mut self, milliseconds: u64) -> Result<(), PlatformError> {
+ self.call_unit(HostCall::Sleep { milliseconds })
+ }
+ fn now_ms(&mut self) -> u64 {
+ self.call(HostCall::NowMs).unwrap_or(0)
+ }
+ fn acquire_oauth_credentials(&mut self) -> Result<OAuthCredentials, PlatformError> {
+ self.call(HostCall::AcquireOauthCredentials)
+ }
+ fn load_access_token(&mut self) -> Result<Option<AccessToken>, PlatformError> {
+ self.call(HostCall::LoadAccessToken)
+ }
+ fn store_access_token(&mut self, token: &AccessToken) -> Result<(), PlatformError> {
+ self.call_unit(HostCall::StoreAccessToken { token })
+ }
+}
+
+fn reply<T: Serialize>(result: Result<T, cyclops_sdk_core::SdkError>) -> Reply<T> {
+ match result {
+ Ok(value) => Reply {
+ ok: true,
+ value: Some(value),
+ error: None,
+ },
+ Err(error) => Reply {
+ ok: false,
+ value: None,
+ error: Some(error.to_string()),
+ },
+ }
+}
+
+fn main() -> Result<(), String> {
+ let stdin = io::stdin();
+ let stdout = io::stdout();
+ let mut platform = RpcPlatform {
+ input: stdin.lock(),
+ output: stdout.lock(),
+ };
+ let configuration = match platform.read_request()? {
+ Some(Request::Configure { configuration }) => configuration,
+ Some(_) => return Err("first request must configure the SDK".into()),
+ None => return Ok(()),
+ };
+ let mut sdk = Sdk::connect(platform, configuration).map_err(|error| error.to_string())?;
+ sdk.platform_mut().write_reply(&Reply {
+ ok: true,
+ value: Some(()),
+ error: None,
+ })?;
+ while let Some(request) = sdk.platform_mut().read_request()? {
+ let response = match request {
+ Request::Configure { .. } => serde_json::to_value(Reply::<()> {
+ ok: false,
+ value: None,
+ error: Some("SDK is already configured".into()),
+ }),
+ Request::CreatePool { request } => {
+ serde_json::to_value(reply(sdk.create_pool(*request)))
+ }
+ Request::ListPools { namespace } => {
+ serde_json::to_value(reply(sdk.list_pools(&namespace)))
+ }
+ Request::GetPool { pool } => serde_json::to_value(reply(sdk.get_pool(pool))),
+ Request::UpdatePool { pool } => serde_json::to_value(reply(sdk.update_pool(pool))),
+ Request::DeletePool { pool } => serde_json::to_value(reply(sdk.delete_pool(pool))),
+ Request::CreateClaim { request } => {
+ serde_json::to_value(reply(sdk.create_claim(*request)))
+ }
+ Request::ListClaims { namespace } => {
+ serde_json::to_value(reply(sdk.list_claims(&namespace)))
+ }
+ Request::GetClaim { claim } => serde_json::to_value(reply(sdk.get_claim(claim))),
+ Request::UpdateClaim { claim } => serde_json::to_value(reply(sdk.update_claim(claim))),
+ Request::DeleteClaim { claim } => serde_json::to_value(reply(sdk.delete_claim(claim))),
+ Request::WaitClaim { claim } => serde_json::to_value(reply(sdk.wait_claim(claim))),
+ Request::ServiceHttp {
+ sandbox,
+ service,
+ request,
+ } => serde_json::to_value(reply(sdk.service_request(&sandbox, &service, request))),
+ }
+ .map_err(|error| error.to_string())?;
+ serde_json::to_writer(&mut sdk.platform_mut().output, &response)
+ .map_err(|error| error.to_string())?;
+ writeln!(sdk.platform_mut().output).map_err(|error| error.to_string())?;
+ sdk.platform_mut()
+ .output
+ .flush()
+ .map_err(|error| error.to_string())?;
+ }
+ Ok(())
+}
diff --git a/libs/fleet/sdk-core/src/generated_crd.rs b/libs/fleet/sdk-core/src/generated_crd.rs
new file mode 100644
index 0000000000..7f56e45f2c
--- /dev/null
+++ b/libs/fleet/sdk-core/src/generated_crd.rs
@@ -0,0 +1,516 @@
+// Code generated from clusters/base/osgym/crd.yaml; DO NOT EDIT.
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct ClaimSpec {
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "bindDeadline")]
+ pub bind_deadline: Option<u32>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "lifecycle")]
+ pub lifecycle: Option<ClaimSpecLifecycle>,
+ #[serde(rename = "sandboxTemplateRef")]
+ pub sandbox_template_ref: SandboxTemplateRef,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "warmpool")]
+ pub warmpool: Option<String>,
+}
+
+impl ClaimSpec {
+ pub fn builder() -> ClaimSpecBuilder {
+ ClaimSpecBuilder::default()
+ }
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct ClaimSpecBuilder {
+ bind_deadline: Option<u32>,
+ lifecycle: Option<ClaimSpecLifecycle>,
+ sandbox_template_ref: Option<SandboxTemplateRef>,
+ warmpool: Option<String>,
+}
+
+impl ClaimSpecBuilder {
+ pub fn bind_deadline(mut self, value: u32) -> Self {
+ self.bind_deadline = Some(value);
+ self
+ }
+ pub fn lifecycle(mut self, value: ClaimSpecLifecycle) -> Self {
+ self.lifecycle = Some(value);
+ self
+ }
+ pub fn sandbox_template_ref(mut self, value: SandboxTemplateRef) -> Self {
+ self.sandbox_template_ref = Some(value);
+ self
+ }
+ pub fn warmpool(mut self, value: String) -> Self {
+ self.warmpool = Some(value);
+ self
+ }
+ pub fn build(self) -> Result<ClaimSpec, String> {
+ Ok(ClaimSpec {
+ bind_deadline: self.bind_deadline,
+ lifecycle: self.lifecycle,
+ sandbox_template_ref: self
+ .sandbox_template_ref
+ .ok_or_else(|| "sandboxTemplateRef is required".to_string())?,
+ warmpool: self.warmpool,
+ })
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct ClaimSpecLifecycle {
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "autoRenew")]
+ pub auto_renew: Option<bool>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "shutdownPolicy")]
+ pub shutdown_policy: Option<String>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "shutdownTime")]
+ pub shutdown_time: Option<String>,
+}
+
+impl ClaimSpecLifecycle {
+ pub fn builder() -> ClaimSpecLifecycleBuilder {
+ ClaimSpecLifecycleBuilder::default()
+ }
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct ClaimSpecLifecycleBuilder {
+ auto_renew: Option<bool>,
+ shutdown_policy: Option<String>,
+ shutdown_time: Option<String>,
+}
+
+impl ClaimSpecLifecycleBuilder {
+ pub fn auto_renew(mut self, value: bool) -> Self {
+ self.auto_renew = Some(value);
+ self
+ }
+ pub fn shutdown_policy(mut self, value: String) -> Self {
+ self.shutdown_policy = Some(value);
+ self
+ }
+ pub fn shutdown_time(mut self, value: String) -> Self {
+ self.shutdown_time = Some(value);
+ self
+ }
+ pub fn build(self) -> Result<ClaimSpecLifecycle, String> {
+ Ok(ClaimSpecLifecycle {
+ auto_renew: self.auto_renew,
+ shutdown_policy: self.shutdown_policy,
+ shutdown_time: self.shutdown_time,
+ })
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct PoolSpec {
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "autoscaling")]
+ pub autoscaling: Option<PoolSpecAutoscaling>,
+ #[serde(rename = "replicas")]
+ pub replicas: u32,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "services")]
+ pub services: Option<Vec<PoolSpecService>>,
+ #[serde(rename = "template")]
+ pub template: PoolTemplate,
+}
+
+impl PoolSpec {
+ pub fn builder() -> PoolSpecBuilder {
+ PoolSpecBuilder::default()
+ }
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct PoolSpecBuilder {
+ autoscaling: Option<PoolSpecAutoscaling>,
+ replicas: Option<u32>,
+ services: Option<Vec<PoolSpecService>>,
+ template: Option<PoolTemplate>,
+}
+
+impl PoolSpecBuilder {
+ pub fn autoscaling(mut self, value: PoolSpecAutoscaling) -> Self {
+ self.autoscaling = Some(value);
+ self
+ }
+ pub fn replicas(mut self, value: u32) -> Self {
+ self.replicas = Some(value);
+ self
+ }
+ pub fn services(mut self, value: Vec<PoolSpecService>) -> Self {
+ self.services = Some(value);
+ self
+ }
+ pub fn template(mut self, value: PoolTemplate) -> Self {
+ self.template = Some(value);
+ self
+ }
+ pub fn build(self) -> Result<PoolSpec, String> {
+ Ok(PoolSpec {
+ autoscaling: self.autoscaling,
+ replicas: self
+ .replicas
+ .ok_or_else(|| "replicas is required".to_string())?,
+ services: self.services,
+ template: self
+ .template
+ .ok_or_else(|| "template is required".to_string())?,
+ })
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct PoolSpecAutoscaling {
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "initialPoolSize")]
+ pub initial_pool_size: Option<u32>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "maxPoolSize")]
+ pub max_pool_size: Option<u32>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "minPoolSize")]
+ pub min_pool_size: Option<u32>,
+}
+
+impl PoolSpecAutoscaling {
+ pub fn builder() -> PoolSpecAutoscalingBuilder {
+ PoolSpecAutoscalingBuilder::default()
+ }
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct PoolSpecAutoscalingBuilder {
+ initial_pool_size: Option<u32>,
+ max_pool_size: Option<u32>,
+ min_pool_size: Option<u32>,
+}
+
+impl PoolSpecAutoscalingBuilder {
+ pub fn initial_pool_size(mut self, value: u32) -> Self {
+ self.initial_pool_size = Some(value);
+ self
+ }
+ pub fn max_pool_size(mut self, value: u32) -> Self {
+ self.max_pool_size = Some(value);
+ self
+ }
+ pub fn min_pool_size(mut self, value: u32) -> Self {
+ self.min_pool_size = Some(value);
+ self
+ }
+ pub fn build(self) -> Result<PoolSpecAutoscaling, String> {
+ Ok(PoolSpecAutoscaling {
+ initial_pool_size: self.initial_pool_size,
+ max_pool_size: self.max_pool_size,
+ min_pool_size: self.min_pool_size,
+ })
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct PoolSpecService {
+ #[serde(rename = "name")]
+ pub name: String,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "protocol")]
+ pub protocol: Option<PoolSpecServiceProtocol>,
+ #[serde(rename = "targetPort")]
+ pub target_port: u32,
+}
+
+impl PoolSpecService {
+ pub fn builder() -> PoolSpecServiceBuilder {
+ PoolSpecServiceBuilder::default()
+ }
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct PoolSpecServiceBuilder {
+ name: Option<String>,
+ protocol: Option<PoolSpecServiceProtocol>,
+ target_port: Option<u32>,
+}
+
+impl PoolSpecServiceBuilder {
+ pub fn name(mut self, value: String) -> Self {
+ self.name = Some(value);
+ self
+ }
+ pub fn protocol(mut self, value: PoolSpecServiceProtocol) -> Self {
+ self.protocol = Some(value);
+ self
+ }
+ pub fn target_port(mut self, value: u32) -> Self {
+ self.target_port = Some(value);
+ self
+ }
+ pub fn build(self) -> Result<PoolSpecService, String> {
+ Ok(PoolSpecService {
+ name: self.name.ok_or_else(|| "name is required".to_string())?,
+ protocol: self.protocol,
+ target_port: self
+ .target_port
+ .ok_or_else(|| "targetPort is required".to_string())?,
+ })
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub enum PoolSpecServiceProtocol {
+ #[serde(rename = "TCP")]
+ TCP,
+ #[serde(rename = "UDP")]
+ UDP,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct PoolTemplate {
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "command")]
+ pub command: Option<Vec<String>>,
+ #[serde(rename = "containerDiskImage")]
+ pub container_disk_image: String,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "cpuCores")]
+ pub cpu_cores: Option<u32>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "firmware")]
+ pub firmware: Option<PoolTemplateFirmware>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "imagePullSecret")]
+ pub image_pull_secret: Option<String>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "memory")]
+ pub memory: Option<String>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "nodeSelector")]
+ pub node_selector: Option<std::collections::BTreeMap<String, String>>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "oidc")]
+ pub oidc: Option<PoolTemplateOidc>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "probes")]
+ pub probes: Option<serde_json::Value>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "runtime")]
+ pub runtime: Option<PoolTemplateRuntime>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "runtimeClassName")]
+ pub runtime_class_name: Option<String>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "tolerations")]
+ pub tolerations: Option<Vec<serde_json::Value>>,
+}
+
+impl PoolTemplate {
+ pub fn builder() -> PoolTemplateBuilder {
+ PoolTemplateBuilder::default()
+ }
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct PoolTemplateBuilder {
+ command: Option<Vec<String>>,
+ container_disk_image: Option<String>,
+ cpu_cores: Option<u32>,
+ firmware: Option<PoolTemplateFirmware>,
+ image_pull_secret: Option<String>,
+ memory: Option<String>,
+ node_selector: Option<std::collections::BTreeMap<String, String>>,
+ oidc: Option<PoolTemplateOidc>,
+ probes: Option<serde_json::Value>,
+ runtime: Option<PoolTemplateRuntime>,
+ runtime_class_name: Option<String>,
+ tolerations: Option<Vec<serde_json::Value>>,
+}
+
+impl PoolTemplateBuilder {
+ pub fn command(mut self, value: Vec<String>) -> Self {
+ self.command = Some(value);
+ self
+ }
+ pub fn container_disk_image(mut self, value: String) -> Self {
+ self.container_disk_image = Some(value);
+ self
+ }
+ pub fn cpu_cores(mut self, value: u32) -> Self {
+ self.cpu_cores = Some(value);
+ self
+ }
+ pub fn firmware(mut self, value: PoolTemplateFirmware) -> Self {
+ self.firmware = Some(value);
+ self
+ }
+ pub fn image_pull_secret(mut self, value: String) -> Self {
+ self.image_pull_secret = Some(value);
+ self
+ }
+ pub fn memory(mut self, value: String) -> Self {
+ self.memory = Some(value);
+ self
+ }
+ pub fn node_selector(mut self, value: std::collections::BTreeMap<String, String>) -> Self {
+ self.node_selector = Some(value);
+ self
+ }
+ pub fn oidc(mut self, value: PoolTemplateOidc) -> Self {
+ self.oidc = Some(value);
+ self
+ }
+ pub fn probes(mut self, value: serde_json::Value) -> Self {
+ self.probes = Some(value);
+ self
+ }
+ pub fn runtime(mut self, value: PoolTemplateRuntime) -> Self {
+ self.runtime = Some(value);
+ self
+ }
+ pub fn runtime_class_name(mut self, value: String) -> Self {
+ self.runtime_class_name = Some(value);
+ self
+ }
+ pub fn tolerations(mut self, value: Vec<serde_json::Value>) -> Self {
+ self.tolerations = Some(value);
+ self
+ }
+ pub fn build(self) -> Result<PoolTemplate, String> {
+ Ok(PoolTemplate {
+ command: self.command,
+ container_disk_image: self
+ .container_disk_image
+ .ok_or_else(|| "containerDiskImage is required".to_string())?,
+ cpu_cores: self.cpu_cores,
+ firmware: self.firmware,
+ image_pull_secret: self.image_pull_secret,
+ memory: self.memory,
+ node_selector: self.node_selector,
+ oidc: self.oidc,
+ probes: self.probes,
+ runtime: self.runtime,
+ runtime_class_name: self.runtime_class_name,
+ tolerations: self.tolerations,
+ })
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub enum PoolTemplateFirmware {
+ #[serde(rename = "bios")]
+ Bios,
+ #[serde(rename = "efi")]
+ Efi,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct PoolTemplateOidc {
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "awsRegion")]
+ pub aws_region: Option<String>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "awsRoleArn")]
+ pub aws_role_arn: Option<String>,
+ #[serde(rename = "credentialsSecret")]
+ pub credentials_secret: String,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[serde(rename = "refreshIntervalSeconds")]
+ pub refresh_interval_seconds: Option<u32>,
+ #[serde(rename = "tokenUrl")]
+ pub token_url: String,
+}
+
+impl PoolTemplateOidc {
+ pub fn builder() -> PoolTemplateOidcBuilder {
+ PoolTemplateOidcBuilder::default()
+ }
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct PoolTemplateOidcBuilder {
+ aws_region: Option<String>,
+ aws_role_arn: Option<String>,
+ credentials_secret: Option<String>,
+ refresh_interval_seconds: Option<u32>,
+ token_url: Option<String>,
+}
+
+impl PoolTemplateOidcBuilder {
+ pub fn aws_region(mut self, value: String) -> Self {
+ self.aws_region = Some(value);
+ self
+ }
+ pub fn aws_role_arn(mut self, value: String) -> Self {
+ self.aws_role_arn = Some(value);
+ self
+ }
+ pub fn credentials_secret(mut self, value: String) -> Self {
+ self.credentials_secret = Some(value);
+ self
+ }
+ pub fn refresh_interval_seconds(mut self, value: u32) -> Self {
+ self.refresh_interval_seconds = Some(value);
+ self
+ }
+ pub fn token_url(mut self, value: String) -> Self {
+ self.token_url = Some(value);
+ self
+ }
+ pub fn build(self) -> Result<PoolTemplateOidc, String> {
+ Ok(PoolTemplateOidc {
+ aws_region: self.aws_region,
+ aws_role_arn: self.aws_role_arn,
+ credentials_secret: self
+ .credentials_secret
+ .ok_or_else(|| "credentialsSecret is required".to_string())?,
+ refresh_interval_seconds: self.refresh_interval_seconds,
+ token_url: self
+ .token_url
+ .ok_or_else(|| "tokenUrl is required".to_string())?,
+ })
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub enum PoolTemplateRuntime {
+ #[serde(rename = "kubevirt")]
+ Kubevirt,
+ #[serde(rename = "macos")]
+ Macos,
+ #[serde(rename = "gvisor")]
+ Gvisor,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct SandboxTemplateRef {
+ #[serde(rename = "name")]
+ pub name: String,
+}
+
+impl SandboxTemplateRef {
+ pub fn builder() -> SandboxTemplateRefBuilder {
+ SandboxTemplateRefBuilder::default()
+ }
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct SandboxTemplateRefBuilder {
+ name: Option<String>,
+}
+
+impl SandboxTemplateRefBuilder {
+ pub fn name(mut self, value: String) -> Self {
+ self.name = Some(value);
+ self
+ }
+ pub fn build(self) -> Result<SandboxTemplateRef, String> {
+ Ok(SandboxTemplateRef {
+ name: self.name.ok_or_else(|| "name is required".to_string())?,
+ })
+ }
+}
diff --git a/libs/fleet/sdk-core/src/generated_crd_component.rs b/libs/fleet/sdk-core/src/generated_crd_component.rs
new file mode 100644
index 0000000000..60de4de551
--- /dev/null
+++ b/libs/fleet/sdk-core/src/generated_crd_component.rs
@@ -0,0 +1,224 @@
+// Code generated from clusters/base/osgym/crd.yaml; DO NOT EDIT.
+fn claim_spec_json(value: crd_types::ClaimSpec) -> Result<serde_json::Value, String> {
+ let mut object = serde_json::Map::new();
+ if let Some(value) = value.bind_deadline {
+ object.insert("bindDeadline".into(), serde_json::Value::from(value));
+ }
+ if let Some(value) = value.lifecycle {
+ object.insert("lifecycle".into(), claim_spec_lifecycle_json(value)?);
+ }
+ object.insert(
+ "sandboxTemplateRef".into(),
+ sandbox_template_ref_json(value.sandbox_template_ref)?,
+ );
+ if let Some(value) = value.warmpool {
+ object.insert("warmpool".into(), serde_json::Value::from(value));
+ }
+ Ok(serde_json::Value::Object(object))
+}
+
+fn claim_spec_lifecycle_json(
+ value: crd_types::ClaimSpecLifecycle,
+) -> Result<serde_json::Value, String> {
+ let mut object = serde_json::Map::new();
+ if let Some(value) = value.auto_renew {
+ object.insert("autoRenew".into(), serde_json::Value::from(value));
+ }
+ if let Some(value) = value.shutdown_policy {
+ object.insert("shutdownPolicy".into(), serde_json::Value::from(value));
+ }
+ if let Some(value) = value.shutdown_time {
+ object.insert("shutdownTime".into(), serde_json::Value::from(value));
+ }
+ Ok(serde_json::Value::Object(object))
+}
+
+fn pool_spec_json(value: crd_types::PoolSpec) -> Result<serde_json::Value, String> {
+ let mut object = serde_json::Map::new();
+ if let Some(value) = value.autoscaling {
+ object.insert("autoscaling".into(), pool_spec_autoscaling_json(value)?);
+ }
+ object.insert("replicas".into(), serde_json::Value::from(value.replicas));
+ if let Some(value) = value.services {
+ object.insert(
+ "services".into(),
+ serde_json::Value::Array(
+ value
+ .into_iter()
+ .map(|item| Ok(pool_spec_service_json(item)?))
+ .collect::<Result<Vec<_>, String>>()?,
+ ),
+ );
+ }
+ object.insert("template".into(), pool_template_json(value.template)?);
+ Ok(serde_json::Value::Object(object))
+}
+
+fn pool_spec_autoscaling_json(
+ value: crd_types::PoolSpecAutoscaling,
+) -> Result<serde_json::Value, String> {
+ let mut object = serde_json::Map::new();
+ if let Some(value) = value.initial_pool_size {
+ object.insert("initialPoolSize".into(), serde_json::Value::from(value));
+ }
+ if let Some(value) = value.max_pool_size {
+ object.insert("maxPoolSize".into(), serde_json::Value::from(value));
+ }
+ if let Some(value) = value.min_pool_size {
+ object.insert("minPoolSize".into(), serde_json::Value::from(value));
+ }
+ Ok(serde_json::Value::Object(object))
+}
+
+fn pool_spec_service_json(value: crd_types::PoolSpecService) -> Result<serde_json::Value, String> {
+ let mut object = serde_json::Map::new();
+ object.insert("name".into(), serde_json::Value::from(value.name));
+ if let Some(value) = value.protocol {
+ object.insert("protocol".into(), pool_spec_service_protocol_json(value));
+ }
+ object.insert(
+ "targetPort".into(),
+ serde_json::Value::from(value.target_port),
+ );
+ Ok(serde_json::Value::Object(object))
+}
+
+fn pool_spec_service_protocol_json(value: crd_types::PoolSpecServiceProtocol) -> serde_json::Value {
+ serde_json::Value::String(
+ match value {
+ crd_types::PoolSpecServiceProtocol::Tcp => "TCP",
+ crd_types::PoolSpecServiceProtocol::Udp => "UDP",
+ }
+ .into(),
+ )
+}
+
+fn pool_template_json(value: crd_types::PoolTemplate) -> Result<serde_json::Value, String> {
+ let mut object = serde_json::Map::new();
+ if let Some(value) = value.command {
+ object.insert(
+ "command".into(),
+ serde_json::Value::Array(
+ value
+ .into_iter()
+ .map(|item| serde_json::Value::from(item))
+ .collect(),
+ ),
+ );
+ }
+ object.insert(
+ "containerDiskImage".into(),
+ serde_json::Value::from(value.container_disk_image),
+ );
+ if let Some(value) = value.cpu_cores {
+ object.insert("cpuCores".into(), serde_json::Value::from(value));
+ }
+ if let Some(value) = value.firmware {
+ object.insert("firmware".into(), pool_template_firmware_json(value));
+ }
+ if let Some(value) = value.image_pull_secret {
+ object.insert("imagePullSecret".into(), serde_json::Value::from(value));
+ }
+ if let Some(value) = value.memory {
+ object.insert("memory".into(), serde_json::Value::from(value));
+ }
+ if let Some(value) = value.node_selector {
+ object.insert(
+ "nodeSelector".into(),
+ serde_json::Value::Object(
+ value
+ .into_iter()
+ .map(|entry| (entry.key, serde_json::Value::from(entry.value)))
+ .collect(),
+ ),
+ );
+ }
+ if let Some(value) = value.oidc {
+ object.insert("oidc".into(), pool_template_oidc_json(value)?);
+ }
+ if let Some(value) = value.probes {
+ object.insert(
+ "probes".into(),
+ serde_json::from_str(&value).map_err(|error| error.to_string())?,
+ );
+ }
+ if let Some(value) = value.runtime {
+ object.insert("runtime".into(), pool_template_runtime_json(value));
+ }
+ if let Some(value) = value.runtime_class_name {
+ object.insert("runtimeClassName".into(), serde_json::Value::from(value));
+ }
+ if let Some(value) = value.tolerations {
+ object.insert(
+ "tolerations".into(),
+ serde_json::Value::Array(
+ value
+ .into_iter()
+ .map(|item| Ok(serde_json::from_str(&item).map_err(|error| error.to_string())?))
+ .collect::<Result<Vec<_>, String>>()?,
+ ),
+ );
+ }
+ Ok(serde_json::Value::Object(object))
+}
+
+fn pool_template_firmware_json(value: crd_types::PoolTemplateFirmware) -> serde_json::Value {
+ serde_json::Value::String(
+ match value {
+ crd_types::PoolTemplateFirmware::Bios => "bios",
+ crd_types::PoolTemplateFirmware::Efi => "efi",
+ }
+ .into(),
+ )
+}
+
+fn pool_template_oidc_json(
+ value: crd_types::PoolTemplateOidc,
+) -> Result<serde_json::Value, String> {
+ let mut object = serde_json::Map::new();
+ if let Some(value) = value.aws_region {
+ object.insert("awsRegion".into(), serde_json::Value::from(value));
+ }
+ if let Some(value) = value.aws_role_arn {
+ object.insert("awsRoleArn".into(), serde_json::Value::from(value));
+ }
+ object.insert(
+ "credentialsSecret".into(),
+ serde_json::Value::from(value.credentials_secret),
+ );
+ if let Some(value) = value.refresh_interval_seconds {
+ object.insert(
+ "refreshIntervalSeconds".into(),
+ serde_json::Value::from(value),
+ );
+ }
+ object.insert("tokenUrl".into(), serde_json::Value::from(value.token_url));
+ Ok(serde_json::Value::Object(object))
+}
+
+fn pool_template_runtime_json(value: crd_types::PoolTemplateRuntime) -> serde_json::Value {
+ serde_json::Value::String(
+ match value {
+ crd_types::PoolTemplateRuntime::Kubevirt => "kubevirt",
+ crd_types::PoolTemplateRuntime::Macos => "macos",
+ crd_types::PoolTemplateRuntime::Gvisor => "gvisor",
+ }
+ .into(),
+ )
+}
+
+fn sandbox_template_ref_json(
+ value: crd_types::SandboxTemplateRef,
+) -> Result<serde_json::Value, String> {
+ let mut object = serde_json::Map::new();
+ object.insert("name".into(), serde_json::Value::from(value.name));
+ Ok(serde_json::Value::Object(object))
+}
+
+fn pool_spec_from_wit(value: crd_types::PoolSpec) -> Result<super::PoolSpec, String> {
+ serde_json::from_value(pool_spec_json(value)?).map_err(|error| error.to_string())
+}
+
+fn claim_spec_from_wit(value: crd_types::ClaimSpec) -> Result<super::ClaimSpec, String> {
+ serde_json::from_value(claim_spec_json(value)?).map_err(|error| error.to_string())
+}
diff --git a/libs/fleet/sdk-core/src/lib.rs b/libs/fleet/sdk-core/src/lib.rs
new file mode 100644
index 0000000000..53d9ef6a0a
--- /dev/null
+++ b/libs/fleet/sdk-core/src/lib.rs
@@ -0,0 +1,423 @@
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use thiserror::Error;
+
+mod client;
+pub mod generated_crd;
+pub use client::{
+ AccessToken, ClaimUrl, HttpRequest, HttpResponse, OAuthCredentials, Platform, PlatformError,
+ PoolUrl, Sdk, SdkError, ServiceHttpRequest, ServiceHttpResponse,
+};
+pub use generated_crd::*;
+
+pub const PROTOCOL_VERSION: u32 = 7;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct Configuration {
+ pub protocol_version: u32,
+ pub base_url: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ResourceMetadata {
+ pub namespace: String,
+ pub name: String,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub labels: Option<std::collections::BTreeMap<String, String>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct Pool {
+ pub api_version: String,
+ pub kind: String,
+ pub metadata: ResourceMetadata,
+ pub spec: Value,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub status: Option<Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct Claim {
+ pub api_version: String,
+ pub kind: String,
+ pub metadata: ResourceMetadata,
+ pub spec: Value,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub status: Option<Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(bound(deserialize = "T: Deserialize<'de>"))]
+pub struct ResourceList<T> {
+ #[serde(default)]
+ pub items: Vec<T>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct Sandbox {
+ pub namespace: String,
+ pub claim: String,
+ pub sandbox: String,
+ pub services: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct CreatePoolRequest {
+ pub namespace: String,
+ pub spec: PoolSpec,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct CreateClaimRequest {
+ pub pool: Pool,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub spec: Option<ClaimSpec>,
+}
+
+#[derive(Debug, Error)]
+pub enum CoreError {
+ #[error("protocol version {0} is unsupported; expected {PROTOCOL_VERSION}")]
+ Protocol(u32),
+ #[error("resource names must be DNS-1123 labels")]
+ InvalidName,
+ #[error("base_url must use http or https")]
+ InvalidBaseUrl,
+}
+
+pub(crate) fn validate_configuration(configuration: &Configuration) -> Result<(), CoreError> {
+ if configuration.protocol_version != PROTOCOL_VERSION {
+ return Err(CoreError::Protocol(configuration.protocol_version));
+ }
+ if !(configuration.base_url.starts_with("http://")
+ || configuration.base_url.starts_with("https://"))
+ {
+ return Err(CoreError::InvalidBaseUrl);
+ }
+ Ok(())
+}
+pub(crate) fn validate_name(value: &str) -> Result<(), CoreError> {
+ if is_dns_label(value) {
+ Ok(())
+ } else {
+ Err(CoreError::InvalidName)
+ }
+}
+fn is_dns_label(value: &str) -> bool {
+ !value.is_empty()
+ && value.len() <= 63
+ && value
+ .bytes()
+ .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
+ && !value.starts_with('-')
+ && !value.ends_with('-')
+}
+
+#[cfg(target_arch = "wasm32")]
+mod component {
+ wit_bindgen::generate!({ path: "wit", world: "cyclops-sdk" });
+ use super::{
+ AccessToken, HttpRequest, HttpResponse, OAuthCredentials, Platform, PlatformError, Sdk,
+ ServiceHttpRequest as CoreServiceHttpRequest,
+ };
+ use std::cell::RefCell;
+ use trycua::cyclops_sdk::{crd_types, platform, requests, resources, service_http};
+ include!("generated_crd_component.rs");
+
+ struct ComponentPlatform;
+ impl Platform for ComponentPlatform {
+ fn http(&mut self, request: HttpRequest) -> Result<HttpResponse, PlatformError> {
+ platform::http(&platform::HttpRequest {
+ method: request.method,
+ url: request.url,
+ headers: request
+ .headers
+ .into_iter()
+ .map(|(name, value)| platform::Header { name, value })
+ .collect(),
+ body: request.body,
+ })
+ .map(|response| HttpResponse {
+ status: response.status,
+ body: response.body,
+ })
+ .map_err(PlatformError::Transport)
+ }
+ fn sleep(&mut self, milliseconds: u64) -> Result<(), PlatformError> {
+ platform::sleep(milliseconds).map_err(PlatformError::Clock)
+ }
+ fn now_ms(&mut self) -> u64 {
+ platform::now_ms()
+ }
+ fn acquire_oauth_credentials(&mut self) -> Result<OAuthCredentials, PlatformError> {
+ platform::acquire_oauth_credentials()
+ .map(|value| OAuthCredentials {
+ token_url: value.token_url,
+ client_id: value.client_id,
+ client_secret: value.client_secret,
+ })
+ .map_err(PlatformError::Credentials)
+ }
+ fn load_access_token(&mut self) -> Result<Option<AccessToken>, PlatformError> {
+ platform::load_access_token()
+ .map(|value| {
+ value.map(|token| AccessToken {
+ value: token.value,
+ expires_at_ms: token.expires_at_ms,
+ })
+ })
+ .map_err(PlatformError::TokenStorage)
+ }
+ fn store_access_token(&mut self, token: &AccessToken) -> Result<(), PlatformError> {
+ platform::store_access_token(&platform::AccessToken {
+ value: token.value.clone(),
+ expires_at_ms: token.expires_at_ms,
+ })
+ .map_err(PlatformError::TokenStorage)
+ }
+ }
+ thread_local! { static SDK: RefCell<Option<Sdk<ComponentPlatform>>> = const { RefCell::new(None) }; }
+ fn with_sdk<T>(
+ operation: impl FnOnce(&mut Sdk<ComponentPlatform>) -> Result<T, String>,
+ ) -> Result<T, String> {
+ SDK.with(|slot| {
+ operation(
+ slot.borrow_mut()
+ .as_mut()
+ .ok_or_else(|| "SDK is not configured".to_string())?,
+ )
+ })
+ }
+ fn pool_from_wit(value: resources::Pool) -> Result<super::Pool, String> {
+ Ok(super::Pool {
+ api_version: value.api_version,
+ kind: value.kind,
+ metadata: super::ResourceMetadata {
+ namespace: value.metadata.namespace,
+ name: value.metadata.name,
+ labels: value
+ .metadata
+ .labels_json
+ .map(|labels| serde_json::from_str(&labels).map_err(|error| error.to_string()))
+ .transpose()?,
+ },
+ spec: serde_json::from_str(&value.spec_json).map_err(|error| error.to_string())?,
+ status: value
+ .status_json
+ .map(|status| serde_json::from_str(&status).map_err(|error| error.to_string()))
+ .transpose()?,
+ })
+ }
+ fn pool_to_wit(value: super::Pool) -> Result<resources::Pool, String> {
+ Ok(resources::Pool {
+ api_version: value.api_version,
+ kind: value.kind,
+ metadata: resources::ResourceMetadata {
+ namespace: value.metadata.namespace,
+ name: value.metadata.name,
+ labels_json: value
+ .metadata
+ .labels
+ .map(|labels| serde_json::to_string(&labels).map_err(|error| error.to_string()))
+ .transpose()?,
+ },
+ spec_json: serde_json::to_string(&value.spec).map_err(|error| error.to_string())?,
+ status_json: value
+ .status
+ .map(|status| serde_json::to_string(&status).map_err(|error| error.to_string()))
+ .transpose()?,
+ })
+ }
+ fn claim_from_wit(value: resources::Claim) -> Result<super::Claim, String> {
+ Ok(super::Claim {
+ api_version: value.api_version,
+ kind: value.kind,
+ metadata: super::ResourceMetadata {
+ namespace: value.metadata.namespace,
+ name: value.metadata.name,
+ labels: value
+ .metadata
+ .labels_json
+ .map(|labels| serde_json::from_str(&labels).map_err(|error| error.to_string()))
+ .transpose()?,
+ },
+ spec: serde_json::from_str(&value.spec_json).map_err(|error| error.to_string())?,
+ status: value
+ .status_json
+ .map(|status| serde_json::from_str(&status).map_err(|error| error.to_string()))
+ .transpose()?,
+ })
+ }
+ fn claim_to_wit(value: super::Claim) -> Result<resources::Claim, String> {
+ Ok(resources::Claim {
+ api_version: value.api_version,
+ kind: value.kind,
+ metadata: resources::ResourceMetadata {
+ namespace: value.metadata.namespace,
+ name: value.metadata.name,
+ labels_json: value
+ .metadata
+ .labels
+ .map(|labels| serde_json::to_string(&labels).map_err(|error| error.to_string()))
+ .transpose()?,
+ },
+ spec_json: serde_json::to_string(&value.spec).map_err(|error| error.to_string())?,
+ status_json: value
+ .status
+ .map(|status| serde_json::to_string(&status).map_err(|error| error.to_string()))
+ .transpose()?,
+ })
+ }
+ fn sandbox_to_wit(value: super::Sandbox) -> resources::Sandbox {
+ resources::Sandbox {
+ namespace: value.namespace,
+ claim: value.claim,
+ sandbox: value.sandbox,
+ services: value.services,
+ }
+ }
+ fn sandbox_from_wit(value: resources::Sandbox) -> super::Sandbox {
+ super::Sandbox {
+ namespace: value.namespace,
+ claim: value.claim,
+ sandbox: value.sandbox,
+ services: value.services,
+ }
+ }
+
+ struct CyclopsComponent;
+ impl Guest for CyclopsComponent {
+ fn protocol_version() -> u32 {
+ super::PROTOCOL_VERSION
+ }
+ fn configure(configuration_json: String) -> Result<(), String> {
+ let configuration =
+ serde_json::from_str(&configuration_json).map_err(|error| error.to_string())?;
+ let sdk = Sdk::connect(ComponentPlatform, configuration)
+ .map_err(|error| error.to_string())?;
+ SDK.with(|slot| *slot.borrow_mut() = Some(sdk));
+ Ok(())
+ }
+ fn create_pool(request: requests::CreatePoolRequest) -> Result<resources::Pool, String> {
+ with_sdk(|sdk| {
+ pool_to_wit(
+ sdk.create_pool(super::CreatePoolRequest {
+ namespace: request.namespace,
+ spec: pool_spec_from_wit(request.spec)?,
+ })
+ .map_err(|error| error.to_string())?,
+ )
+ })
+ }
+ fn list_pools(namespace: String) -> Result<Vec<resources::Pool>, String> {
+ with_sdk(|sdk| {
+ sdk.list_pools(&namespace)
+ .map_err(|error| error.to_string())?
+ .into_iter()
+ .map(pool_to_wit)
+ .collect()
+ })
+ }
+ fn get_pool(value: resources::Pool) -> Result<resources::Pool, String> {
+ with_sdk(|sdk| {
+ pool_to_wit(
+ sdk.get_pool(pool_from_wit(value)?)
+ .map_err(|error| error.to_string())?,
+ )
+ })
+ }
+ fn update_pool(value: resources::Pool) -> Result<resources::Pool, String> {
+ with_sdk(|sdk| {
+ pool_to_wit(
+ sdk.update_pool(pool_from_wit(value)?)
+ .map_err(|error| error.to_string())?,
+ )
+ })
+ }
+ fn delete_pool(value: resources::Pool) -> Result<(), String> {
+ with_sdk(|sdk| {
+ sdk.delete_pool(pool_from_wit(value)?)
+ .map_err(|error| error.to_string())
+ })
+ }
+ fn create_claim(request: requests::CreateClaimRequest) -> Result<resources::Claim, String> {
+ with_sdk(|sdk| {
+ claim_to_wit(
+ sdk.create_claim(super::CreateClaimRequest {
+ pool: pool_from_wit(request.pool)?,
+ spec: request.spec.map(claim_spec_from_wit).transpose()?,
+ })
+ .map_err(|error| error.to_string())?,
+ )
+ })
+ }
+ fn list_claims(namespace: String) -> Result<Vec<resources::Claim>, String> {
+ with_sdk(|sdk| {
+ sdk.list_claims(&namespace)
+ .map_err(|error| error.to_string())?
+ .into_iter()
+ .map(claim_to_wit)
+ .collect()
+ })
+ }
+ fn get_claim(value: resources::Claim) -> Result<resources::Claim, String> {
+ with_sdk(|sdk| {
+ claim_to_wit(
+ sdk.get_claim(claim_from_wit(value)?)
+ .map_err(|error| error.to_string())?,
+ )
+ })
+ }
+ fn update_claim(value: resources::Claim) -> Result<resources::Claim, String> {
+ with_sdk(|sdk| {
+ claim_to_wit(
+ sdk.update_claim(claim_from_wit(value)?)
+ .map_err(|error| error.to_string())?,
+ )
+ })
+ }
+ fn delete_claim(value: resources::Claim) -> Result<(), String> {
+ with_sdk(|sdk| {
+ sdk.delete_claim(claim_from_wit(value)?)
+ .map_err(|error| error.to_string())
+ })
+ }
+ fn wait_claim(value: resources::Claim) -> Result<resources::Sandbox, String> {
+ with_sdk(|sdk| {
+ Ok(sandbox_to_wit(
+ sdk.wait_claim(claim_from_wit(value)?)
+ .map_err(|error| error.to_string())?,
+ ))
+ })
+ }
+ fn service_request(
+ value: resources::Sandbox,
+ service: String,
+ request: service_http::ServiceHttpRequest,
+ ) -> Result<service_http::ServiceHttpResponse, String> {
+ with_sdk(|sdk| {
+ sdk.service_request(
+ &sandbox_from_wit(value),
+ &service,
+ CoreServiceHttpRequest {
+ method: request.method,
+ path: request.path,
+ headers: request
+ .headers
+ .into_iter()
+ .map(|header| (header.name, header.value))
+ .collect(),
+ body: request.body,
+ },
+ )
+ .map(|response| service_http::ServiceHttpResponse {
+ status: response.status,
+ body: response.body,
+ })
+ .map_err(|error| error.to_string())
+ })
+ }
+ }
+ export!(CyclopsComponent);
+}
diff --git a/libs/fleet/sdk-core/tests/client_flow.rs b/libs/fleet/sdk-core/tests/client_flow.rs
new file mode 100644
index 0000000000..a01cd2895e
--- /dev/null
+++ b/libs/fleet/sdk-core/tests/client_flow.rs
@@ -0,0 +1,502 @@
+use cyclops_sdk_core::{
+ AccessToken, Claim, ClaimUrl, Configuration, CreateClaimRequest, CreatePoolRequest,
+ HttpRequest, HttpResponse, OAuthCredentials, Platform, PlatformError, PoolSpec, PoolTemplate,
+ PoolUrl, Sandbox, Sdk, SdkError, ServiceHttpRequest,
+};
+use serde_json::json;
+use std::collections::VecDeque;
+
+#[derive(Default)]
+struct FakePlatform {
+ responses: VecDeque<HttpResponse>,
+ requests: Vec<HttpRequest>,
+ sleeps: Vec<u64>,
+ token: Option<AccessToken>,
+ oauth: Option<OAuthCredentials>,
+ credential_requests: usize,
+}
+
+impl Platform for FakePlatform {
+ fn http(&mut self, request: HttpRequest) -> Result<HttpResponse, PlatformError> {
+ self.requests.push(request);
+ self.responses
+ .pop_front()
+ .ok_or_else(|| PlatformError::Transport("missing response".into()))
+ }
+ fn sleep(&mut self, milliseconds: u64) -> Result<(), PlatformError> {
+ self.sleeps.push(milliseconds);
+ Ok(())
+ }
+ fn now_ms(&mut self) -> u64 {
+ 1_000
+ }
+ fn acquire_oauth_credentials(&mut self) -> Result<OAuthCredentials, PlatformError> {
+ self.credential_requests += 1;
+ Ok(self.oauth.clone().unwrap_or_else(|| OAuthCredentials {
+ token_url: "https://auth.example/token".into(),
+ client_id: "id".into(),
+ client_secret: "secret".into(),
+ }))
+ }
+ fn load_access_token(&mut self) -> Result<Option<AccessToken>, PlatformError> {
+ Ok(self.token.clone())
+ }
+ fn store_access_token(&mut self, token: &AccessToken) -> Result<(), PlatformError> {
+ self.token = Some(token.clone());
+ Ok(())
+ }
+}
+
+fn claim() -> Claim {
+ serde_json::from_value(json!({
+ "apiVersion":"osgym.cua.ai/v1alpha1", "kind":"OSGymSandboxClaim",
+ "metadata":{"namespace":"pool-a","name":"claim-a"},
+ "spec":{"sandboxTemplateRef":{"name":"pool-a-template"}}
+ }))
+ .unwrap()
+}
+
+fn connected(responses: Vec<HttpResponse>) -> Sdk<FakePlatform> {
+ let platform = FakePlatform {
+ responses: responses.into(),
+ token: Some(AccessToken {
+ value: "cached".into(),
+ expires_at_ms: 301_001,
+ }),
+ ..FakePlatform::default()
+ };
+ Sdk::connect(
+ platform,
+ Configuration {
+ protocol_version: cyclops_sdk_core::PROTOCOL_VERSION,
+ base_url: "https://run.example".into(),
+ },
+ )
+ .unwrap()
+}
+
+#[test]
+fn canonical_resource_urls_are_namespaced() {
+ let pool = PoolUrl::new("https://run.example/", "pool-a", "pool-a").unwrap();
+ assert_eq!(
+ pool.collection().as_str(),
+ "https://run.example/api/k8s/apis/cua.ai/v1/namespaces/pool-a/osgymworkspacepools"
+ );
+ assert_eq!(
+ pool.item().as_str(),
+ "https://run.example/api/k8s/apis/cua.ai/v1/namespaces/pool-a/osgymworkspacepools/pool-a"
+ );
+ let claim = ClaimUrl::new("https://run.example", "pool-a", "claim-a").unwrap();
+ assert_eq!(claim.collection().as_str(), "https://run.example/api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/pool-a/osgymsandboxclaims");
+ assert_eq!(claim.item().as_str(), "https://run.example/api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/pool-a/osgymsandboxclaims/claim-a");
+}
+
+fn sandbox_with_services() -> Sandbox {
+ Sandbox {
+ namespace: "pool-a".into(),
+ claim: "claim-a".into(),
+ sandbox: "sandbox-a".into(),
+ services: vec!["mcp".into(), "novnc".into()],
+ }
+}
+
+#[test]
+fn service_request_resolves_relative_path_and_reuses_auth_retry() {
+ let mut sdk = connected(vec![
+ HttpResponse {
+ status: 401,
+ body: "expired".into(),
+ },
+ HttpResponse {
+ status: 200,
+ body: r#"{"access_token":"fresh","expires_in":300}"#.into(),
+ },
+ HttpResponse {
+ status: 200,
+ body: "initialized".into(),
+ },
+ ]);
+ let response = sdk
+ .service_request(
+ &sandbox_with_services(),
+ "mcp",
+ ServiceHttpRequest {
+ method: "POST".into(),
+ path: "/mcp?session=one".into(),
+ headers: vec![
+ ("content-type".into(), "application/json".into()),
+ ("authorization".into(), "Caller token".into()),
+ ("host".into(), "cyclops.invalid".into()),
+ ("connection".into(), "keep-alive".into()),
+ ],
+ body: Some("{}".into()),
+ },
+ )
+ .unwrap();
+ assert_eq!(response.status, 200);
+ assert_eq!(response.body, "initialized");
+ assert_eq!(sdk.platform().requests.len(), 3);
+ assert_eq!(
+ sdk.platform().requests[0].url,
+ "https://run.example/api/svc/pool-a/sandbox-a-mcp/mcp?session=one"
+ );
+ assert_eq!(
+ sdk.platform().requests[2].url,
+ sdk.platform().requests[0].url
+ );
+ assert!(sdk.platform().requests[0]
+ .headers
+ .contains(&("authorization".into(), "Bearer cached".into())));
+ assert!(!sdk.platform().requests[0]
+ .headers
+ .iter()
+ .any(|(name, _)| name.eq_ignore_ascii_case("host")
+ || name.eq_ignore_ascii_case("connection")));
+ assert!(sdk.platform().requests[2]
+ .headers
+ .contains(&("authorization".into(), "Bearer fresh".into())));
+}
+
+#[test]
+fn service_request_rejects_unknown_service_with_available_names() {
+ let mut sdk = connected(vec![]);
+ let error = sdk
+ .service_request(
+ &sandbox_with_services(),
+ "metrics",
+ ServiceHttpRequest::get("/health"),
+ )
+ .unwrap_err();
+ assert_eq!(
+ error,
+ SdkError::UnknownService {
+ requested: "metrics".into(),
+ available: vec!["mcp".into(), "novnc".into()],
+ }
+ );
+ assert!(sdk.platform().requests.is_empty());
+}
+
+#[test]
+fn service_request_rejects_absolute_urls() {
+ let mut sdk = connected(vec![]);
+ let error = sdk
+ .service_request(
+ &sandbox_with_services(),
+ "mcp",
+ ServiceHttpRequest::get("https://attacker.example/mcp"),
+ )
+ .unwrap_err();
+ assert_eq!(
+ error,
+ SdkError::InvalidServicePath("https://attacker.example/mcp".into())
+ );
+ assert!(sdk.platform().requests.is_empty());
+}
+
+#[test]
+fn service_request_rejects_forged_route_parts() {
+ let mut sdk = connected(vec![]);
+ let mut sandbox = sandbox_with_services();
+ sandbox.sandbox = "../other".into();
+ let error = sdk
+ .service_request(&sandbox, "mcp", ServiceHttpRequest::get("/mcp"))
+ .unwrap_err();
+ assert!(matches!(error, SdkError::Configuration(_)));
+ assert!(sdk.platform().requests.is_empty());
+}
+
+#[test]
+fn wait_claim_reuses_get_claim_until_bound() {
+ let pending = json!({
+ "apiVersion":"osgym.cua.ai/v1alpha1", "kind":"OSGymSandboxClaim",
+ "metadata":{"namespace":"pool-a","name":"claim-a"},
+ "spec":{"sandboxTemplateRef":{"name":"pool-a-template"}},
+ "status":{"phase":"Pending"}
+ })
+ .to_string();
+ let bound = json!({
+ "apiVersion":"osgym.cua.ai/v1alpha1", "kind":"OSGymSandboxClaim",
+ "metadata":{"namespace":"pool-a","name":"claim-a"},
+ "spec":{"sandboxTemplateRef":{"name":"pool-a-template"}},
+ "status":{"phase":"Bound","sandbox":{"name":"sandbox-a"}}
+ })
+ .to_string();
+ let pool = json!({
+ "apiVersion":"cua.ai/v1", "kind":"OSGymWorkspacePool",
+ "metadata":{"namespace":"pool-a","name":"pool-a"},
+ "spec":{"replicas":1,"services":[{"name":"mcp","targetPort":3000}],"template":{"containerDiskImage":"example/workspace:latest","cpuCores":4,"memory":"4Gi"}}
+ })
+ .to_string();
+ let mut sdk = connected(vec![
+ HttpResponse {
+ status: 200,
+ body: pool,
+ },
+ HttpResponse {
+ status: 200,
+ body: pending,
+ },
+ HttpResponse {
+ status: 200,
+ body: bound,
+ },
+ ]);
+ let sandbox = sdk.wait_claim(claim()).unwrap();
+ assert_eq!(sandbox.sandbox, "sandbox-a");
+ assert_eq!(sdk.platform().requests.len(), 3);
+ assert_eq!(sandbox.services, ["mcp"]);
+ assert!(sdk
+ .platform()
+ .requests
+ .iter()
+ .all(|request| request.method == "GET"));
+ assert_eq!(sdk.platform().sleeps, [5_000]);
+}
+
+#[test]
+fn oauth_credentials_are_form_encoded() {
+ let platform = FakePlatform {
+ responses: vec![
+ HttpResponse {
+ status: 200,
+ body: r#"{"access_token":"fresh","expires_in":300}"#.into(),
+ },
+ HttpResponse {
+ status: 200,
+ body: "ok".into(),
+ },
+ ]
+ .into(),
+ oauth: Some(OAuthCredentials {
+ token_url: "https://auth.example/token".into(),
+ client_id: "id&+= %".into(),
+ client_secret: "s/e?c#r&et=+ %".into(),
+ }),
+ ..FakePlatform::default()
+ };
+ let mut sdk = Sdk::connect(
+ platform,
+ Configuration {
+ protocol_version: cyclops_sdk_core::PROTOCOL_VERSION,
+ base_url: "https://run.example".into(),
+ },
+ )
+ .unwrap();
+ sdk.service_request(
+ &sandbox_with_services(),
+ "mcp",
+ ServiceHttpRequest::get("/mcp"),
+ )
+ .unwrap();
+ assert_eq!(
+ sdk.platform().requests[0].body.as_deref(),
+ Some("grant_type=client_credentials&client_id=id%26%2B%3D+%25&client_secret=s%2Fe%3Fc%23r%26et%3D%2B+%25")
+ );
+}
+
+#[test]
+fn compact_specs_are_expanded_into_canonical_resources() {
+ let pool_body = r#"{"apiVersion":"cua.ai/v1","kind":"OSGymWorkspacePool","metadata":{"namespace":"pool-one","name":"pool-one"},"spec":{"replicas":1,"template":{"containerDiskImage":"example/workspace:latest","cpuCores":4,"memory":"4Gi"}}}"#;
+ let pool_response = pool_body.to_string();
+ let claim_response = serde_json::to_string(&claim()).unwrap();
+ let claim_body = r#"{"apiVersion":"osgym.cua.ai/v1alpha1","kind":"OSGymSandboxClaim","metadata":{"namespace":"pool-one","name":"claim-3e8-0"},"spec":{"sandboxTemplateRef":{"name":"pool-one-template"}}}"#;
+ let mut sdk = connected(vec![
+ HttpResponse {
+ status: 201,
+ body: r#"{"name":"pool-one","status":"Active"}"#.into(),
+ },
+ HttpResponse {
+ status: 201,
+ body: pool_response.clone(),
+ },
+ HttpResponse {
+ status: 200,
+ body: ready_pool_body(),
+ },
+ HttpResponse {
+ status: 201,
+ body: claim_response,
+ },
+ ]);
+ let created_pool = sdk
+ .create_pool(CreatePoolRequest {
+ namespace: "pool-one".into(),
+ spec: PoolSpec::builder()
+ .replicas(1)
+ .template(
+ PoolTemplate::builder()
+ .container_disk_image("example/workspace:latest".into())
+ .cpu_cores(4)
+ .memory("4Gi".into())
+ .build()
+ .unwrap(),
+ )
+ .build()
+ .unwrap(),
+ })
+ .unwrap();
+ sdk.create_claim(CreateClaimRequest {
+ pool: created_pool,
+ spec: None,
+ })
+ .unwrap();
+ assert_eq!(sdk.platform().requests.len(), 4);
+ assert_eq!(
+ sdk.platform().requests[0].url,
+ "https://run.example/api/namespaces"
+ );
+ assert_eq!(
+ sdk.platform().requests[0].body.as_deref(),
+ Some(r#"{"name":"pool-one"}"#)
+ );
+ assert_eq!(sdk.platform().requests[1].body.as_deref(), Some(pool_body));
+ assert_eq!(sdk.platform().requests[2].method, "GET");
+ assert_eq!(sdk.platform().requests[3].body.as_deref(), Some(claim_body));
+}
+
+#[test]
+fn create_claim_waits_for_a_requested_pool_replica_to_become_available() {
+ let pending = serde_json::from_str::<cyclops_sdk_core::Pool>(
+ r#"{"apiVersion":"cua.ai/v1","kind":"OSGymWorkspacePool","metadata":{"namespace":"pool-one","name":"pool-one"},"spec":{"replicas":1,"template":{"containerDiskImage":"example/workspace:latest","cpuCores":4,"memory":"4Gi"}},"status":{"phase":"Provisioning","availableCount":0,"totalCount":1}}"#,
+ )
+ .unwrap();
+ let pool = pool_resource();
+ let claim_response = serde_json::to_string(&claim()).unwrap();
+ let mut sdk = connected(vec![
+ HttpResponse {
+ status: 200,
+ body: serde_json::to_string(&pending).unwrap(),
+ },
+ HttpResponse {
+ status: 200,
+ body: ready_pool_body(),
+ },
+ HttpResponse {
+ status: 201,
+ body: claim_response,
+ },
+ ]);
+ sdk.create_claim(CreateClaimRequest { pool, spec: None })
+ .unwrap();
+ assert_eq!(sdk.platform().requests.len(), 3);
+ assert_eq!(
+ sdk.platform()
+ .requests
+ .iter()
+ .map(|request| request.method.as_str())
+ .collect::<Vec<_>>(),
+ ["GET", "GET", "POST"]
+ );
+ assert_eq!(sdk.platform().sleeps, [5_000]);
+}
+
+#[test]
+fn create_claim_does_not_wait_for_a_zero_replica_pool() {
+ let mut pool = pool_resource();
+ pool.spec["replicas"] = serde_json::Value::from(0);
+ let mut sdk = connected(vec![HttpResponse {
+ status: 201,
+ body: serde_json::to_string(&claim()).unwrap(),
+ }]);
+ sdk.create_claim(CreateClaimRequest { pool, spec: None })
+ .unwrap();
+ assert_eq!(sdk.platform().requests.len(), 1);
+ assert_eq!(sdk.platform().requests[0].method, "POST");
+}
+
+#[test]
+fn create_pool_reuses_an_existing_namespace() {
+ let pool_body = r#"{"apiVersion":"cua.ai/v1","kind":"OSGymWorkspacePool","metadata":{"namespace":"pool-one","name":"pool-one"},"spec":{"replicas":1,"template":{"containerDiskImage":"example/workspace:latest","cpuCores":4,"memory":"4Gi"}}}"#;
+ let mut sdk = connected(vec![
+ HttpResponse {
+ status: 409,
+ body: "namespace already exists".into(),
+ },
+ HttpResponse {
+ status: 201,
+ body: pool_body.into(),
+ },
+ ]);
+ sdk.create_pool(pool_request()).unwrap();
+ assert_eq!(sdk.platform().requests.len(), 2);
+}
+
+#[test]
+fn create_pool_rolls_back_a_new_namespace_when_pool_creation_fails() {
+ let mut sdk = connected(vec![
+ HttpResponse {
+ status: 201,
+ body: r#"{"name":"pool-one","status":"Active"}"#.into(),
+ },
+ HttpResponse {
+ status: 403,
+ body: "forbidden".into(),
+ },
+ HttpResponse {
+ status: 202,
+ body: String::new(),
+ },
+ ]);
+ let error = sdk.create_pool(pool_request()).unwrap_err();
+ assert!(error.to_string().contains("create pool returned HTTP 403"));
+ assert_eq!(sdk.platform().requests.len(), 3);
+ assert_eq!(sdk.platform().requests[2].method, "DELETE");
+ assert_eq!(
+ sdk.platform().requests[2].url,
+ "https://run.example/api/namespaces/pool-one"
+ );
+}
+
+#[test]
+fn delete_pool_deletes_the_pool_before_its_namespace() {
+ let mut sdk = connected(vec![
+ HttpResponse {
+ status: 202,
+ body: String::new(),
+ },
+ HttpResponse {
+ status: 202,
+ body: String::new(),
+ },
+ ]);
+ let pool = pool_resource();
+ sdk.delete_pool(pool).unwrap();
+ assert_eq!(sdk.platform().requests.len(), 2);
+ assert!(sdk.platform().requests[0]
+ .url
+ .ends_with("/osgymworkspacepools/pool-one"));
+ assert_eq!(
+ sdk.platform().requests[1].url,
+ "https://run.example/api/namespaces/pool-one"
+ );
+}
+
+fn pool_resource() -> cyclops_sdk_core::Pool {
+ serde_json::from_str(
+ r#"{"apiVersion":"cua.ai/v1","kind":"OSGymWorkspacePool","metadata":{"namespace":"pool-one","name":"pool-one"},"spec":{"replicas":1,"template":{"containerDiskImage":"example/workspace:latest","cpuCores":4,"memory":"4Gi"}}}"#,
+ )
+ .unwrap()
+}
+
+fn ready_pool_body() -> String {
+ r#"{"apiVersion":"cua.ai/v1","kind":"OSGymWorkspacePool","metadata":{"namespace":"pool-one","name":"pool-one"},"spec":{"replicas":1,"template":{"containerDiskImage":"example/workspace:latest","cpuCores":4,"memory":"4Gi"}},"status":{"phase":"Ready","availableCount":1,"totalCount":1}}"#.into()
+}
+
+fn pool_request() -> CreatePoolRequest {
+ CreatePoolRequest {
+ namespace: "pool-one".into(),
+ spec: PoolSpec::builder()
+ .replicas(1)
+ .template(
+ PoolTemplate::builder()
+ .container_disk_image("example/workspace:latest".into())
+ .cpu_cores(4)
+ .memory("4Gi".into())
+ .build()
+ .unwrap(),
+ )
+ .build()
+ .unwrap(),
+ }
+}
diff --git a/libs/fleet/sdk-core/tests/public_api.rs b/libs/fleet/sdk-core/tests/public_api.rs
new file mode 100644
index 0000000000..32037acd18
--- /dev/null
+++ b/libs/fleet/sdk-core/tests/public_api.rs
@@ -0,0 +1,195 @@
+use cyclops_sdk_core::{
+ AccessToken, Claim, Configuration, CreateClaimRequest, CreatePoolRequest, HttpRequest,
+ HttpResponse, OAuthCredentials, Platform, PlatformError, Pool, PoolSpec, PoolTemplate, Sandbox,
+ Sdk,
+};
+use std::collections::VecDeque;
+
+#[derive(Default)]
+struct FakePlatform {
+ responses: VecDeque<HttpResponse>,
+ requests: Vec<HttpRequest>,
+ token: Option<AccessToken>,
+}
+
+impl Platform for FakePlatform {
+ fn http(&mut self, request: HttpRequest) -> Result<HttpResponse, PlatformError> {
+ self.requests.push(request);
+ self.responses
+ .pop_front()
+ .ok_or_else(|| PlatformError::Transport("missing response".into()))
+ }
+ fn sleep(&mut self, _milliseconds: u64) -> Result<(), PlatformError> {
+ Ok(())
+ }
+ fn now_ms(&mut self) -> u64 {
+ 1_000
+ }
+ fn acquire_oauth_credentials(&mut self) -> Result<OAuthCredentials, PlatformError> {
+ unreachable!()
+ }
+ fn load_access_token(&mut self) -> Result<Option<AccessToken>, PlatformError> {
+ Ok(self.token.clone())
+ }
+ fn store_access_token(&mut self, token: &AccessToken) -> Result<(), PlatformError> {
+ self.token = Some(token.clone());
+ Ok(())
+ }
+}
+
+fn connected(responses: impl IntoIterator<Item = (u16, String)>) -> Sdk<FakePlatform> {
+ Sdk::connect(
+ FakePlatform {
+ responses: responses
+ .into_iter()
+ .map(|(status, body)| HttpResponse { status, body })
+ .collect(),
+ token: Some(AccessToken {
+ value: "cached".into(),
+ expires_at_ms: 301_001,
+ }),
+ ..FakePlatform::default()
+ },
+ Configuration {
+ protocol_version: cyclops_sdk_core::PROTOCOL_VERSION,
+ base_url: "https://run.example".into(),
+ },
+ )
+ .unwrap()
+}
+
+fn pool() -> Pool {
+ serde_json::from_str(r#"{"apiVersion":"cua.ai/v1","kind":"OSGymWorkspacePool","metadata":{"namespace":"pool-one","name":"pool-one"},"spec":{"replicas":1,"template":{"containerDiskImage":"example/workspace:latest","cpuCores":4,"memory":"4Gi"}}}"#).unwrap()
+}
+
+fn claim() -> Claim {
+ serde_json::from_str(r#"{"apiVersion":"osgym.cua.ai/v1alpha1","kind":"OSGymSandboxClaim","metadata":{"namespace":"pool-one","name":"claim-one"},"spec":{"sandboxTemplateRef":{"name":"pool-one-template"}}}"#).unwrap()
+}
+
+#[test]
+fn canonical_pool_and_claim_crud_uses_typed_resources() {
+ let pool_json = serde_json::to_string(&pool()).unwrap();
+ let claim_json = serde_json::to_string(&claim()).unwrap();
+ let list_pools = format!(r#"{{"items":[{pool_json}]}}"#);
+ let list_claims = format!(r#"{{"items":[{claim_json}]}}"#);
+ let bound_claim = r#"{"apiVersion":"osgym.cua.ai/v1alpha1","kind":"OSGymSandboxClaim","metadata":{"namespace":"pool-one","name":"claim-one"},"spec":{"sandboxTemplateRef":{"name":"pool-one-template"}},"status":{"phase":"Bound","sandbox":{"name":"sandbox-one"}}}"#;
+ let mut sdk = connected([
+ (201, r#"{"name":"pool-one","status":"Active"}"#.into()),
+ (201, pool_json.clone()),
+ (200, list_pools),
+ (200, pool_json.clone()),
+ (200, pool_json),
+ (
+ 200,
+ r#"{"apiVersion":"cua.ai/v1","kind":"OSGymWorkspacePool","metadata":{"namespace":"pool-one","name":"pool-one"},"spec":{"replicas":1,"template":{"containerDiskImage":"example/workspace:latest","cpuCores":4,"memory":"4Gi"}},"status":{"phase":"Ready","availableCount":1,"totalCount":1}}"#.into(),
+ ),
+ (201, claim_json.clone()),
+ (200, list_claims),
+ (200, claim_json.clone()),
+ (200, claim_json),
+ (200, bound_claim.into()),
+ (204, String::new()),
+ (204, String::new()),
+ (204, String::new()),
+ ]);
+
+ let pool = sdk
+ .create_pool(CreatePoolRequest {
+ namespace: "pool-one".into(),
+ spec: PoolSpec::builder()
+ .replicas(1)
+ .template(
+ PoolTemplate::builder()
+ .container_disk_image("example/workspace:latest".into())
+ .cpu_cores(4)
+ .memory("4Gi".into())
+ .build()
+ .unwrap(),
+ )
+ .build()
+ .unwrap(),
+ })
+ .unwrap();
+ sdk.list_pools("pool-one").unwrap();
+ sdk.get_pool(pool.clone()).unwrap();
+ sdk.update_pool(pool.clone()).unwrap();
+ let claim = sdk
+ .create_claim(CreateClaimRequest {
+ pool: pool.clone(),
+ spec: None,
+ })
+ .unwrap();
+ sdk.list_claims("pool-one").unwrap();
+ sdk.get_claim(claim.clone()).unwrap();
+ sdk.update_claim(claim.clone()).unwrap();
+ let Sandbox { sandbox, .. } = sdk.wait_claim(claim.clone()).unwrap();
+ sdk.delete_claim(claim).unwrap();
+ sdk.delete_pool(pool).unwrap();
+ assert_eq!(sandbox, "sandbox-one");
+
+ let methods = sdk
+ .platform()
+ .requests
+ .iter()
+ .map(|request| request.method.as_str())
+ .collect::<Vec<_>>();
+ assert_eq!(
+ methods,
+ [
+ "POST", "POST", "GET", "GET", "PUT", "GET", "POST", "GET", "GET", "PUT", "GET",
+ "DELETE", "DELETE", "DELETE"
+ ]
+ );
+}
+
+#[test]
+fn wit_exports_typed_resources_and_service_http() {
+ let wit = format!(
+ "{}\n{}",
+ include_str!("../wit/cyclops-sdk.wit"),
+ include_str!("../wit/generated-crd.wit")
+ );
+ for resource in [
+ "record pool",
+ "record pool-spec",
+ "record claim",
+ "record claim-spec",
+ "record sandbox",
+ ] {
+ assert!(wit.contains(resource), "missing typed {resource}");
+ }
+ assert!(!wit.contains("pool-json"));
+ assert!(!wit.contains("claim-json"));
+ for operation in [
+ "create-pool",
+ "list-pools",
+ "get-pool",
+ "update-pool",
+ "delete-pool",
+ "create-claim",
+ "list-claims",
+ "get-claim",
+ "update-claim",
+ "delete-claim",
+ "wait-claim",
+ "service-request",
+ ] {
+ assert!(wit.contains(operation), "missing {operation}");
+ }
+ assert!(!wit.contains("raw-request"));
+ assert!(wit.contains("record service-http-request"));
+ assert!(wit.contains("record service-http-response"));
+ for leaked_url in ["server-url", "mcp-url", "novnc-url"] {
+ assert!(!wit.contains(leaked_url), "leaked {leaked_url}");
+ }
+ for prohibited in [
+ concat!("create", "-namespace"),
+ concat!("release", "-claim"),
+ concat!("claim", "-status"),
+ concat!("claimed", "-sandbox"),
+ concat!("run", "-task"),
+ concat!("run", "-call", "back"),
+ ] {
+ assert!(!wit.contains(prohibited), "prohibited {prohibited}");
+ }
+}
diff --git a/libs/fleet/sdk-core/wit/cyclops-sdk.wit b/libs/fleet/sdk-core/wit/cyclops-sdk.wit
new file mode 100644
index 0000000000..9d3f67c1a0
--- /dev/null
+++ b/libs/fleet/sdk-core/wit/cyclops-sdk.wit
@@ -0,0 +1,56 @@
+package trycua:[email protected];
+
+interface platform {
+ record header { name: string, value: string }
+ record http-request { method: string, url: string, headers: list<header>, body: option<string> }
+ record http-response { status: u16, body: string }
+ record oauth-credentials { token-url: string, client-id: string, client-secret: string }
+ record access-token { value: string, expires-at-ms: u64 }
+ http: func(request: http-request) -> result<http-response, string>;
+ sleep: func(milliseconds: u64) -> result<_, string>;
+ now-ms: func() -> u64;
+ acquire-oauth-credentials: func() -> result<oauth-credentials, string>;
+ load-access-token: func() -> result<option<access-token>, string>;
+ store-access-token: func(token: access-token) -> result<_, string>;
+}
+
+interface resources {
+ record resource-metadata { namespace: string, name: string, labels-json: option<string> }
+ record pool { api-version: string, kind: string, metadata: resource-metadata, spec-json: string, status-json: option<string> }
+ record claim { api-version: string, kind: string, metadata: resource-metadata, spec-json: string, status-json: option<string> }
+ record sandbox { namespace: string, claim: string, sandbox: string, services: list<string> }
+}
+
+interface requests {
+ use resources.{pool};
+ use crd-types.{pool-spec, claim-spec};
+ record create-pool-request { namespace: string, spec: pool-spec }
+ record create-claim-request { pool: pool, spec: option<claim-spec> }
+}
+
+interface service-http {
+ record header { name: string, value: string }
+ record service-http-request { method: string, path: string, headers: list<header>, body: option<string> }
+ record service-http-response { status: u16, body: string }
+}
+
+world cyclops-sdk {
+ import platform;
+ use resources.{pool, claim, sandbox};
+ use requests.{create-pool-request, create-claim-request};
+ use service-http.{service-http-request, service-http-response};
+ export protocol-version: func() -> u32;
+ export configure: func(configuration-json: string) -> result<_, string>;
+ export create-pool: func(request: create-pool-request) -> result<pool, string>;
+ export list-pools: func(namespace: string) -> result<list<pool>, string>;
+ export get-pool: func(value: pool) -> result<pool, string>;
+ export update-pool: func(value: pool) -> result<pool, string>;
+ export delete-pool: func(value: pool) -> result<_, string>;
+ export create-claim: func(request: create-claim-request) -> result<claim, string>;
+ export list-claims: func(namespace: string) -> result<list<claim>, string>;
+ export get-claim: func(value: claim) -> result<claim, string>;
+ export update-claim: func(value: claim) -> result<claim, string>;
+ export delete-claim: func(value: claim) -> result<_, string>;
+ export wait-claim: func(value: claim) -> result<sandbox, string>;
+ export service-request: func(value: sandbox, service: string, request: service-http-request) -> result<service-http-response, string>;
+}
diff --git a/libs/fleet/sdk-core/wit/generated-crd.wit b/libs/fleet/sdk-core/wit/generated-crd.wit
new file mode 100644
index 0000000000..0a7816fc41
--- /dev/null
+++ b/libs/fleet/sdk-core/wit/generated-crd.wit
@@ -0,0 +1,60 @@
+// Code generated from clusters/base/osgym/crd.yaml; DO NOT EDIT.
+package trycua:[email protected];
+
+interface crd-types {
+ record string-map-entry { key: string, value: string }
+ record claim-spec {
+ bind-deadline: option<u32>,
+ lifecycle: option<claim-spec-lifecycle>,
+ sandbox-template-ref: sandbox-template-ref,
+ warmpool: option<string>,
+ }
+ record claim-spec-lifecycle {
+ auto-renew: option<bool>,
+ shutdown-policy: option<string>,
+ shutdown-time: option<string>,
+ }
+ record pool-spec {
+ autoscaling: option<pool-spec-autoscaling>,
+ replicas: u32,
+ services: option<list<pool-spec-service>>,
+ template: pool-template,
+ }
+ record pool-spec-autoscaling {
+ initial-pool-size: option<u32>,
+ max-pool-size: option<u32>,
+ min-pool-size: option<u32>,
+ }
+ record pool-spec-service {
+ name: string,
+ protocol: option<pool-spec-service-protocol>,
+ target-port: u32,
+ }
+ enum pool-spec-service-protocol { tcp, udp }
+ record pool-template {
+ command: option<list<string>>,
+ container-disk-image: string,
+ cpu-cores: option<u32>,
+ firmware: option<pool-template-firmware>,
+ image-pull-secret: option<string>,
+ memory: option<string>,
+ node-selector: option<list<string-map-entry>>,
+ oidc: option<pool-template-oidc>,
+ probes: option<string>,
+ runtime: option<pool-template-runtime>,
+ runtime-class-name: option<string>,
+ tolerations: option<list<string>>,
+ }
+ enum pool-template-firmware { bios, efi }
+ record pool-template-oidc {
+ aws-region: option<string>,
+ aws-role-arn: option<string>,
+ credentials-secret: string,
+ refresh-interval-seconds: option<u32>,
+ token-url: string,
+ }
+ enum pool-template-runtime { kubevirt, macos, gvisor }
+ record sandbox-template-ref {
+ name: string,
+ }
+}
diff --git a/libs/fleet/sdk-schema-generator/go.mod b/libs/fleet/sdk-schema-generator/go.mod
new file mode 100644
index 0000000000..7eeec79710
--- /dev/null
+++ b/libs/fleet/sdk-schema-generator/go.mod
@@ -0,0 +1,5 @@
+module github.com/trycua/cloud/cyclops-cs/sdk-schema-generator
+
+go 1.23.0
+
+require gopkg.in/yaml.v3 v3.0.1
diff --git a/libs/fleet/sdk-schema-generator/go.sum b/libs/fleet/sdk-schema-generator/go.sum
new file mode 100644
index 0000000000..a62c313c5b
--- /dev/null
+++ b/libs/fleet/sdk-schema-generator/go.sum
@@ -0,0 +1,4 @@
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/libs/fleet/sdk-schema-generator/main.go b/libs/fleet/sdk-schema-generator/main.go
new file mode 100644
index 0000000000..faf44e5aba
--- /dev/null
+++ b/libs/fleet/sdk-schema-generator/main.go
@@ -0,0 +1,686 @@
+package main
+
+import (
+ "bytes"
+ "flag"
+ "fmt"
+ goformat "go/format"
+ "io"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "sort"
+ "strings"
+ "unicode"
+
+ yamlv3 "gopkg.in/yaml.v3"
+)
+
+type node struct {
+ Name string
+ JSONName string
+ Type string
+ Required bool
+ Enum []string
+ Properties []*node
+ Items *node
+ MapValues *node
+ Opaque bool
+}
+
+type rootType struct {
+ CRDName string
+ Version string
+ Name string
+ Node *node
+}
+
+type output struct {
+ Path string
+ Data []byte
+}
+
+func main() {
+ root := flag.String("root", ".", "repository root")
+ check := flag.Bool("check", false, "fail if generated files differ")
+ flag.Parse()
+
+ crdPath := filepath.Join(*root, "clusters/base/osgym/crd.yaml")
+ roots := []*rootType{
+ {CRDName: "osgymworkspacepools.cua.ai", Version: "v1", Name: "PoolSpec"},
+ {CRDName: "osgymsandboxclaims.osgym.cua.ai", Version: "v1alpha1", Name: "ClaimSpec"},
+ }
+ loadRoots(crdPath, roots)
+
+ outputs := []output{
+ {filepath.Join(*root, "cyclops-cs/sdk-core/wit/generated-crd.wit"), renderWIT(roots)},
+ {filepath.Join(*root, "cyclops-cs/sdk-core/src/generated_crd.rs"), formatRust(renderRust(roots))},
+ {filepath.Join(*root, "cyclops-cs/sdk-core/src/generated_crd_component.rs"), formatRust(renderComponent(roots))},
+ {filepath.Join(*root, "cyclops-cs/sdk-bindings/typescript/src/generated-crd.ts"), renderTypeScript(roots)},
+ {filepath.Join(*root, "cyclops-cs/sdk-bindings/python/cyclops_sdk/generated_crd.py"), renderPython(roots)},
+ {filepath.Join(*root, "cyclops-cs/sdk-bindings/go/generated_crd.go"), formatGo(renderGo(roots))},
+ }
+
+ failed := false
+ for _, item := range outputs {
+ current, err := os.ReadFile(item.Path)
+ if *check {
+ if err != nil || !bytes.Equal(current, item.Data) {
+ fmt.Fprintf(os.Stderr, "generated file is stale: %s\n", item.Path)
+ failed = true
+ }
+ continue
+ }
+ if err := os.MkdirAll(filepath.Dir(item.Path), 0o755); err != nil {
+ fatalf("create output directory: %v", err)
+ }
+ if err := os.WriteFile(item.Path, item.Data, 0o644); err != nil {
+ fatalf("write %s: %v", item.Path, err)
+ }
+ }
+ if failed {
+ os.Exit(1)
+ }
+}
+
+func formatRust(source []byte) []byte {
+ command := exec.Command("rustfmt", "--emit", "stdout")
+ command.Stdin = bytes.NewReader(source)
+ formatted, err := command.Output()
+ if err != nil {
+ fatalf("rustfmt generated source: %v", err)
+ }
+ return formatted
+}
+
+func formatGo(source []byte) []byte {
+ formatted, err := goformat.Source(source)
+ if err != nil {
+ fatalf("gofmt generated source: %v", err)
+ }
+ return formatted
+}
+
+func loadRoots(path string, roots []*rootType) {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ fatalf("read CRDs: %v", err)
+ }
+ wanted := map[string]*rootType{}
+ for _, root := range roots {
+ wanted[root.CRDName] = root
+ }
+ decoder := yamlv3.NewDecoder(bytes.NewReader(data))
+ for {
+ var document map[string]any
+ if err := decoder.Decode(&document); err != nil {
+ if err == io.EOF {
+ break
+ }
+ fatalf("decode CRDs: %v", err)
+ }
+ metadata, _ := document["metadata"].(map[string]any)
+ root := wanted[fmt.Sprint(metadata["name"])]
+ if root == nil {
+ continue
+ }
+ versions := mustSlice(mustMap(document["spec"], "spec")["versions"], "spec.versions")
+ for _, raw := range versions {
+ version := mustMap(raw, "version")
+ if fmt.Sprint(version["name"]) != root.Version {
+ continue
+ }
+ schema := mustMap(mustMap(version["schema"], "schema")["openAPIV3Schema"], "openAPIV3Schema")
+ spec := property(schema, "spec")
+ root.Node = parseNode(root.Name, "spec", spec, true)
+ }
+ }
+ for _, root := range roots {
+ if root.Node == nil {
+ fatalf("missing %s %s schema", root.CRDName, root.Version)
+ }
+ }
+}
+
+func parseNode(name, jsonName string, schema map[string]any, required bool) *node {
+ result := &node{Name: name, JSONName: jsonName, Type: fmt.Sprint(schema["type"]), Required: required}
+ if values, ok := schema["enum"].([]any); ok {
+ for _, value := range values {
+ result.Enum = append(result.Enum, fmt.Sprint(value))
+ }
+ }
+ if schema["x-kubernetes-preserve-unknown-fields"] == true {
+ result.Opaque = true
+ return result
+ }
+ switch result.Type {
+ case "object":
+ if additional, ok := schema["additionalProperties"].(map[string]any); ok {
+ result.MapValues = parseNode(name+"Value", "value", additional, true)
+ return result
+ }
+ properties, _ := schema["properties"].(map[string]any)
+ requiredSet := stringSet(schema["required"])
+ keys := sortedKeys(properties)
+ for _, key := range keys {
+ childName := name + exportedName(key)
+ if key == "template" && strings.HasSuffix(name, "Spec") {
+ childName = strings.TrimSuffix(name, "Spec") + "Template"
+ }
+ if key == "sandboxTemplateRef" {
+ childName = "SandboxTemplateRef"
+ }
+ result.Properties = append(result.Properties, parseNode(childName, key, mustMap(properties[key], key), requiredSet[key]))
+ }
+ case "array":
+ result.Items = parseNode(strings.TrimSuffix(name, "s"), "item", mustMap(schema["items"], name+".items"), true)
+ }
+ return result
+}
+
+func renderWIT(roots []*rootType) []byte {
+ var out bytes.Buffer
+ out.WriteString("// Code generated from clusters/base/osgym/crd.yaml; DO NOT EDIT.\n")
+ out.WriteString("package trycua:[email protected];\n\ninterface crd-types {\n")
+ nodes := collectNamed(roots)
+ if hasMap(nodes) {
+ out.WriteString(" record string-map-entry { key: string, value: string }\n")
+ }
+ for _, item := range nodes {
+ if len(item.Enum) > 0 {
+ fmt.Fprintf(&out, " enum %s { %s }\n", witName(item.Name), strings.Join(enumWIT(item.Enum), ", "))
+ continue
+ }
+ if item.Type != "object" || item.MapValues != nil || item.Opaque {
+ continue
+ }
+ fmt.Fprintf(&out, " record %s {\n", witName(item.Name))
+ for _, field := range item.Properties {
+ fieldType := witType(field)
+ if !field.Required {
+ fieldType = "option<" + fieldType + ">"
+ }
+ fmt.Fprintf(&out, " %s: %s,\n", witName(field.JSONName), fieldType)
+ }
+ out.WriteString(" }\n")
+ }
+ out.WriteString("}\n")
+ return out.Bytes()
+}
+
+func renderRust(roots []*rootType) []byte {
+ var out bytes.Buffer
+ out.WriteString("// Code generated from clusters/base/osgym/crd.yaml; DO NOT EDIT.\n")
+ out.WriteString("use serde::{Deserialize, Serialize};\n\n")
+ for _, item := range collectNamed(roots) {
+ if len(item.Enum) > 0 {
+ out.WriteString("#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\n")
+ fmt.Fprintf(&out, "pub enum %s {\n", item.Name)
+ for _, value := range item.Enum {
+ fmt.Fprintf(&out, " #[serde(rename = %q)]\n %s,\n", value, exportedName(value))
+ }
+ out.WriteString("}\n\n")
+ continue
+ }
+ if item.Type != "object" || item.MapValues != nil || item.Opaque {
+ continue
+ }
+ out.WriteString("#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]\n")
+ fmt.Fprintf(&out, "pub struct %s {\n", item.Name)
+ for _, field := range item.Properties {
+ fieldType := rustType(field)
+ if !field.Required {
+ fieldType = "Option<" + fieldType + ">"
+ out.WriteString(" #[serde(default, skip_serializing_if = \"Option::is_none\")]\n")
+ }
+ fmt.Fprintf(&out, " #[serde(rename = %q)]\n pub %s: %s,\n", field.JSONName, rustField(field.JSONName), fieldType)
+ }
+ out.WriteString("}\n\n")
+ renderRustBuilder(&out, item)
+ }
+ return out.Bytes()
+}
+
+func renderRustBuilder(out *bytes.Buffer, item *node) {
+ fmt.Fprintf(out, "impl %s {\n", item.Name)
+ fmt.Fprintf(out, " pub fn builder() -> %sBuilder { %sBuilder::default() }\n", item.Name, item.Name)
+ out.WriteString("}\n\n")
+ fmt.Fprintf(out, "#[derive(Debug, Clone, Default)]\npub struct %sBuilder {\n", item.Name)
+ for _, field := range item.Properties {
+ fmt.Fprintf(out, " %s: Option<%s>,\n", rustField(field.JSONName), rustType(field))
+ }
+ out.WriteString("}\n\n")
+ fmt.Fprintf(out, "impl %sBuilder {\n", item.Name)
+ for _, field := range item.Properties {
+ fieldName := rustField(field.JSONName)
+ fieldType := rustType(field)
+ fmt.Fprintf(out, " pub fn %s(mut self, value: %s) -> Self {\n", fieldName, fieldType)
+ fmt.Fprintf(out, " self.%s = Some(value);\n self\n }\n", fieldName)
+ }
+ fmt.Fprintf(out, " pub fn build(self) -> Result<%s, String> {\n", item.Name)
+ fmt.Fprintf(out, " Ok(%s {\n", item.Name)
+ for _, field := range item.Properties {
+ fieldName := rustField(field.JSONName)
+ if field.Required {
+ fmt.Fprintf(out, " %s: self.%s.ok_or_else(|| %q.to_string())?,\n", fieldName, fieldName, field.JSONName+" is required")
+ } else {
+ fmt.Fprintf(out, " %s: self.%s,\n", fieldName, fieldName)
+ }
+ }
+ out.WriteString(" })\n }\n}\n\n")
+}
+
+func renderComponent(roots []*rootType) []byte {
+ var out bytes.Buffer
+ out.WriteString("// Code generated from clusters/base/osgym/crd.yaml; DO NOT EDIT.\n")
+ for _, item := range collectNamed(roots) {
+ if len(item.Enum) > 0 {
+ fmt.Fprintf(&out, "fn %s_json(value: crd_types::%s) -> serde_json::Value {\n", snake(item.Name), item.Name)
+ out.WriteString(" serde_json::Value::String(match value {\n")
+ for _, value := range item.Enum {
+ fmt.Fprintf(&out, " crd_types::%s::%s => %q,\n", item.Name, exportedName(strings.ToLower(value)), value)
+ }
+ out.WriteString(" }.into())\n}\n\n")
+ continue
+ }
+ if item.Type != "object" || item.MapValues != nil || item.Opaque {
+ continue
+ }
+ fmt.Fprintf(&out, "fn %s_json(value: crd_types::%s) -> Result<serde_json::Value, String> {\n", snake(item.Name), item.Name)
+ out.WriteString(" let mut object = serde_json::Map::new();\n")
+ for _, field := range item.Properties {
+ fieldAccess := "value." + rustField(field.JSONName)
+ if field.Required {
+ fmt.Fprintf(&out, " object.insert(%q.into(), %s);\n", field.JSONName, componentValue(field, fieldAccess))
+ } else {
+ fmt.Fprintf(&out, " if let Some(value) = %s { object.insert(%q.into(), %s); }\n", fieldAccess, field.JSONName, componentValue(field, "value"))
+ }
+ }
+ out.WriteString(" Ok(serde_json::Value::Object(object))\n}\n\n")
+ }
+ for _, root := range roots {
+ fmt.Fprintf(&out, "fn %s_from_wit(value: crd_types::%s) -> Result<super::%s, String> {\n", snake(root.Name), root.Name, root.Name)
+ fmt.Fprintf(&out, " serde_json::from_value(%s_json(value)?).map_err(|error| error.to_string())\n}\n\n", snake(root.Name))
+ }
+ return out.Bytes()
+}
+
+func renderTypeScript(roots []*rootType) []byte {
+ var out bytes.Buffer
+ out.WriteString("// Code generated from clusters/base/osgym/crd.yaml; DO NOT EDIT.\n")
+ for _, item := range collectNamed(roots) {
+ if len(item.Enum) > 0 {
+ fmt.Fprintf(&out, "export type %s = %s\n", item.Name, quoteUnion(item.Enum))
+ continue
+ }
+ if item.Type != "object" || item.MapValues != nil || item.Opaque {
+ continue
+ }
+ fmt.Fprintf(&out, "export type %s = {\n", item.Name)
+ for _, field := range item.Properties {
+ optional := ""
+ if !field.Required {
+ optional = "?"
+ }
+ fmt.Fprintf(&out, " %s%s: %s\n", field.JSONName, optional, tsType(field))
+ }
+ out.WriteString("}\n")
+ }
+ return out.Bytes()
+}
+
+func renderPython(roots []*rootType) []byte {
+ var out bytes.Buffer
+ out.WriteString("# Code generated from clusters/base/osgym/crd.yaml; DO NOT EDIT.\n")
+ out.WriteString("from __future__ import annotations\n\n")
+ out.WriteString("from typing import Any, Literal, NotRequired, TypedDict\n\n")
+ for _, item := range collectNamed(roots) {
+ if len(item.Enum) > 0 {
+ fmt.Fprintf(&out, "%s = Literal[%s]\n\n", item.Name, quotedCSV(item.Enum))
+ continue
+ }
+ if item.Type != "object" || item.MapValues != nil || item.Opaque {
+ continue
+ }
+ fmt.Fprintf(&out, "class %s(TypedDict):\n", item.Name)
+ if len(item.Properties) == 0 {
+ out.WriteString(" pass\n")
+ }
+ for _, field := range item.Properties {
+ fieldType := pyType(field)
+ if !field.Required {
+ fieldType = "NotRequired[" + fieldType + "]"
+ }
+ fmt.Fprintf(&out, " %s: %s\n", field.JSONName, fieldType)
+ }
+ out.WriteString("\n")
+ }
+ return out.Bytes()
+}
+
+func renderGo(roots []*rootType) []byte {
+ var out bytes.Buffer
+ out.WriteString("// Code generated from clusters/base/osgym/crd.yaml; DO NOT EDIT.\n")
+ out.WriteString("package cyclopssdk\n\n")
+ for _, item := range collectNamed(roots) {
+ if len(item.Enum) > 0 {
+ fmt.Fprintf(&out, "type %s string\n\nconst (\n", item.Name)
+ for _, value := range item.Enum {
+ fmt.Fprintf(&out, "\t%s%s %s = %q\n", item.Name, exportedName(value), item.Name, value)
+ }
+ out.WriteString(")\n\n")
+ continue
+ }
+ if item.Type != "object" || item.MapValues != nil || item.Opaque {
+ continue
+ }
+ fmt.Fprintf(&out, "type %s struct {\n", item.Name)
+ for _, field := range item.Properties {
+ fieldType := goType(field)
+ tag := field.JSONName
+ if !field.Required {
+ if goNeedsPointer(field) {
+ fieldType = "*" + fieldType
+ }
+ tag += ",omitempty"
+ }
+ fmt.Fprintf(&out, "\t%s %s `json:%q`\n", exportedName(field.JSONName), fieldType, tag)
+ }
+ out.WriteString("}\n\n")
+ }
+ return out.Bytes()
+}
+
+func collectNamed(roots []*rootType) []*node {
+ seen := map[string]*node{}
+ var visit func(*node)
+ visit = func(item *node) {
+ if item == nil {
+ return
+ }
+ if (item.Type == "object" && item.MapValues == nil && !item.Opaque) || len(item.Enum) > 0 {
+ seen[item.Name] = item
+ }
+ for _, child := range item.Properties {
+ visit(child)
+ }
+ visit(item.Items)
+ visit(item.MapValues)
+ }
+ for _, root := range roots {
+ visit(root.Node)
+ }
+ keys := make([]string, 0, len(seen))
+ for key := range seen {
+ keys = append(keys, key)
+ }
+ sort.Strings(keys)
+ result := make([]*node, 0, len(keys))
+ for _, key := range keys {
+ result = append(result, seen[key])
+ }
+ return result
+}
+
+func witType(item *node) string {
+ if len(item.Enum) > 0 || (item.Type == "object" && item.MapValues == nil && !item.Opaque) {
+ return witName(item.Name)
+ }
+ if item.Opaque {
+ return "string"
+ }
+ switch item.Type {
+ case "string":
+ return "string"
+ case "integer":
+ return "u32"
+ case "boolean":
+ return "bool"
+ case "array":
+ return "list<" + witType(item.Items) + ">"
+ case "object":
+ return "list<string-map-entry>"
+ default:
+ fatalf("unsupported WIT schema type %q for %s", item.Type, item.Name)
+ return ""
+ }
+}
+
+func rustType(item *node) string {
+ if len(item.Enum) > 0 || (item.Type == "object" && item.MapValues == nil && !item.Opaque) {
+ return item.Name
+ }
+ if item.Opaque {
+ return "serde_json::Value"
+ }
+ switch item.Type {
+ case "string":
+ return "String"
+ case "integer":
+ return "u32"
+ case "boolean":
+ return "bool"
+ case "array":
+ return "Vec<" + rustType(item.Items) + ">"
+ case "object":
+ return "std::collections::BTreeMap<String, " + rustType(item.MapValues) + ">"
+ default:
+ fatalf("unsupported Rust schema type %q for %s", item.Type, item.Name)
+ return ""
+ }
+}
+
+func tsType(item *node) string {
+ if len(item.Enum) > 0 || (item.Type == "object" && item.MapValues == nil && !item.Opaque) {
+ return item.Name
+ }
+ if item.Opaque {
+ return "unknown"
+ }
+ switch item.Type {
+ case "string":
+ return "string"
+ case "integer":
+ return "number"
+ case "boolean":
+ return "boolean"
+ case "array":
+ return tsType(item.Items) + "[]"
+ case "object":
+ return "Record<string, " + tsType(item.MapValues) + ">"
+ default:
+ fatalf("unsupported TypeScript schema type %q", item.Type)
+ return "never"
+ }
+}
+
+func pyType(item *node) string {
+ if len(item.Enum) > 0 || (item.Type == "object" && item.MapValues == nil && !item.Opaque) {
+ return item.Name
+ }
+ if item.Opaque {
+ return "Any"
+ }
+ switch item.Type {
+ case "string":
+ return "str"
+ case "integer":
+ return "int"
+ case "boolean":
+ return "bool"
+ case "array":
+ return "list[" + pyType(item.Items) + "]"
+ case "object":
+ return "dict[str, " + pyType(item.MapValues) + "]"
+ default:
+ fatalf("unsupported Python schema type %q", item.Type)
+ return "Any"
+ }
+}
+
+func goType(item *node) string {
+ if len(item.Enum) > 0 || (item.Type == "object" && item.MapValues == nil && !item.Opaque) {
+ return item.Name
+ }
+ if item.Opaque {
+ return "any"
+ }
+ switch item.Type {
+ case "string":
+ return "string"
+ case "integer":
+ return "uint32"
+ case "boolean":
+ return "bool"
+ case "array":
+ return "[]" + goType(item.Items)
+ case "object":
+ return "map[string]" + goType(item.MapValues)
+ default:
+ fatalf("unsupported Go schema type %q", item.Type)
+ return "any"
+ }
+}
+
+func componentValue(item *node, expression string) string {
+ if len(item.Enum) > 0 {
+ return snake(item.Name) + "_json(" + expression + ")"
+ }
+ if item.Opaque {
+ return "serde_json::from_str(&" + expression + ").map_err(|error| error.to_string())?"
+ }
+ if item.Type == "object" && item.MapValues == nil {
+ return snake(item.Name) + "_json(" + expression + ")?"
+ }
+ switch item.Type {
+ case "string", "integer", "boolean":
+ return "serde_json::Value::from(" + expression + ")"
+ case "array":
+ inner := componentValue(item.Items, "item")
+ if strings.Contains(inner, "?") {
+ return "serde_json::Value::Array(" + expression + ".into_iter().map(|item| Ok(" + inner + ")).collect::<Result<Vec<_>, String>>()?)"
+ }
+ return "serde_json::Value::Array(" + expression + ".into_iter().map(|item| " + inner + ").collect())"
+ case "object":
+ return "serde_json::Value::Object(" + expression + ".into_iter().map(|entry| (entry.key, serde_json::Value::from(entry.value))).collect())"
+ default:
+ fatalf("unsupported component type %q", item.Type)
+ return ""
+ }
+}
+
+func property(schema map[string]any, name string) map[string]any {
+ return mustMap(mustMap(schema["properties"], "properties")[name], name)
+}
+func stringSet(value any) map[string]bool {
+ result := map[string]bool{}
+ for _, item := range mustSliceDefault(value) {
+ result[fmt.Sprint(item)] = true
+ }
+ return result
+}
+func mustSliceDefault(value any) []any {
+ if value == nil {
+ return nil
+ }
+ return mustSlice(value, "array")
+}
+func sortedKeys(values map[string]any) []string {
+ keys := make([]string, 0, len(values))
+ for key := range values {
+ keys = append(keys, key)
+ }
+ sort.Strings(keys)
+ return keys
+}
+func hasMap(nodes []*node) bool {
+ for _, item := range nodes {
+ for _, field := range item.Properties {
+ if field.Type == "object" && field.MapValues != nil {
+ return true
+ }
+ }
+ }
+ return false
+}
+func goNeedsPointer(item *node) bool {
+ return item.Type == "string" || item.Type == "integer" || item.Type == "boolean" || len(item.Enum) > 0 || (item.Type == "object" && item.MapValues == nil && !item.Opaque)
+}
+func exportedName(value string) string {
+ parts := splitWords(value)
+ var out strings.Builder
+ for _, part := range parts {
+ if part == "" {
+ continue
+ }
+ runes := []rune(part)
+ runes[0] = unicode.ToUpper(runes[0])
+ out.WriteString(string(runes))
+ }
+ return out.String()
+}
+func splitWords(value string) []string {
+ value = strings.ReplaceAll(value, "-", "_")
+ var out []string
+ start := 0
+ runes := []rune(value)
+ for i := 1; i < len(runes); i++ {
+ if unicode.IsUpper(runes[i]) && (unicode.IsLower(runes[i-1]) || unicode.IsDigit(runes[i-1])) {
+ out = append(out, string(runes[start:i]))
+ start = i
+ }
+ }
+ out = append(out, string(runes[start:]))
+ return strings.FieldsFunc(strings.Join(out, "_"), func(r rune) bool { return r == '_' })
+}
+func snake(value string) string {
+ parts := splitWords(value)
+ for i := range parts {
+ parts[i] = strings.ToLower(parts[i])
+ }
+ return strings.Join(parts, "_")
+}
+func witName(value string) string { return strings.ReplaceAll(snake(value), "_", "-") }
+func rustField(value string) string {
+ result := snake(value)
+ if result == "type" {
+ return "type_"
+ }
+ return result
+}
+func enumWIT(values []string) []string {
+ result := make([]string, len(values))
+ for i, value := range values {
+ result[i] = witName(value)
+ }
+ return result
+}
+func quoteUnion(values []string) string {
+ quoted := make([]string, len(values))
+ for i, value := range values {
+ quoted[i] = fmt.Sprintf("%q", value)
+ }
+ return strings.Join(quoted, " | ")
+}
+func quotedCSV(values []string) string {
+ quoted := make([]string, len(values))
+ for i, value := range values {
+ quoted[i] = fmt.Sprintf("%q", value)
+ }
+ return strings.Join(quoted, ", ")
+}
+func mustMap(value any, name string) map[string]any {
+ result, ok := value.(map[string]any)
+ if !ok {
+ fatalf("%s is not an object", name)
+ }
+ return result
+}
+func mustSlice(value any, name string) []any {
+ result, ok := value.([]any)
+ if !ok {
+ fatalf("%s is not an array", name)
+ }
+ return result
+}
+func fatalf(format string, args ...any) { fmt.Fprintf(os.Stderr, format+"\n", args...); os.Exit(1) }
diff --git a/libs/fleet/sdk-schema-generator/main_test.go b/libs/fleet/sdk-schema-generator/main_test.go
new file mode 100644
index 0000000000..47f68c063f
--- /dev/null
+++ b/libs/fleet/sdk-schema-generator/main_test.go
@@ -0,0 +1,36 @@
+package main
+
+import (
+ "strings"
+ "testing"
+)
+
+func TestRenderRustGeneratesBuilders(t *testing.T) {
+ roots := []*rootType{{
+ Name: "ExampleSpec",
+ Node: &node{
+ Name: "ExampleSpec",
+ Type: "object",
+ Properties: []*node{
+ {Name: "ExampleSpecName", JSONName: "name", Type: "string", Required: true},
+ {Name: "ExampleSpecCount", JSONName: "count", Type: "integer", Required: false},
+ },
+ },
+ }}
+
+ source := string(renderRust(roots))
+ for _, expected := range []string{
+ "pub fn builder() -> ExampleSpecBuilder",
+ "pub struct ExampleSpecBuilder",
+ "name: Option<String>",
+ "count: Option<u32>",
+ "pub fn name(mut self, value: String) -> Self",
+ "pub fn count(mut self, value: u32) -> Self",
+ `ok_or_else(|| "name is required".to_string())?`,
+ "count: self.count",
+ } {
+ if !strings.Contains(source, expected) {
+ t.Fatalf("generated Rust missing %q:\n%s", expected, source)
+ }
+ }
+}