faroshq
diff --git a/‎docs/app-studio-runtime-decoupling.md‎
Lines changed: 7 additions & 6 deletions b/‎docs/app-studio-runtime-decoupling.md‎
Lines changed: 7 additions & 6 deletions
diff --git a/‎providers/infrastructure/dataplane/contract.go‎
Lines changed: 109 additions & 0 deletions b/‎providers/infrastructure/dataplane/contract.go‎
Lines changed: 109 additions & 0 deletions
diff --git a/‎providers/infrastructure/dataplane/handler.go‎
Lines changed: 186 additions & 0 deletions b/‎providers/infrastructure/dataplane/handler.go‎
Lines changed: 186 additions & 0 deletions
@@ -110,14 +110,14 @@ A generic resolver turns `(instance, endpointName) → {serviceNamespace, servic
 ### 4.1 Request shape
 
 ```
-GET  /services/providers/infrastructure/vw/clusters/{ws}/
-       apis/infrastructure.kedge.faros.sh/v1alpha1/sandboxrunners/{name}/log
+GET  /services/providers/infrastructure/dataplane/clusters/{ws}/sandboxrunners/{name}/log
 GET  …/sandboxrunners/{name}/proxy/{path...}
 POST …/sandboxrunners/{name}/sync
 POST …/sandboxrunners/{name}/restart
+     …/sandboxrunners/{name}/status     (served from the instance status; no runtime hop)
 ```
 
-(The exact prefix depends on the transport vehicle chosen in §6; the handler logic is identical either way.)
+The `/services/providers/infrastructure` prefix is the hub backend proxy; the provider's serve mux sees `/dataplane/clusters/{ws}/{resource}/{name}/{verb}[/{tail}]` (§6.1). The `{ws}` segment carries colons (`root:kedge:orgs:acme`) and is a single path segment.
 
 ### 4.2 Per-request flow
 
@@ -148,16 +148,17 @@ After this, App Studio's `SandboxRunner` values shrink to roughly `{projectRef}`
 
 ## 6. Open decisions
 
-### 6.1 VW transport vehicle — **spike in Phase 1**
+### 6.1 VW transport vehicle — **decided in Phase 1**
 
 The "subresource on the instance" semantics can be realized two ways:
 
 | Vehicle | Pros | Cons |
 |---|---|---|
 | **kcp APIExport subresource** on the instance kind | Purest model; reachable via the normal bound-resource API path App Studio already uses; no per-workspace URL mapping | Unproven that kcp APIExport supports arbitrary custom subresources on CRD-backed resources |
-| **Dedicated VW builder** (`spec.virtualWorkspace` → `/services/providers/infrastructure/vw/…`) | **Proven in-repo** by `edges_proxy_builder.go` (proxy + upgrades + WebSocket through the hub) | Hub must map workspace → provider (the binding supplies this); slightly more wiring |
+| **Provider serve mux behind the hub backend proxy** (`/services/providers/infrastructure/dataplane/…`, workspace in the path) | **Proven in-repo** — the provider already serves `/mcp` this way, and `edges_proxy_builder.go` shows proxy + upgrades + WebSocket through the hub; no kcp-VW machinery | Workspace addressed explicitly in the URL rather than implied by the bound resource; the handler re-authorizes against the instance itself |
 
-Recommendation: budget for the **dedicated VW builder**; it is the de-risked path and the handler logic is identical. Confirm the APIExport-subresource option early — if kcp supports it, prefer it.
+**Decision (Phase 1):** the **provider serve mux** vehicle. The handler mounts at `dataplane.PathPrefix` (`/dataplane/`) on the provider's existing HTTP server and is reached through the hub backend proxy with the caller's bearer token forwarded as-is. The URL carries the workspace explicitly —
+`/dataplane/clusters/<ws>/<resource>/<name>/<verb>[/<tail>]` — and the handler authorizes by fetching the instance **as the caller** (a tenant-scoped GET; 403/404 is the gate). This keeps the k8s-native subresource *semantics* while avoiding the unproven kcp-APIExport-subresource path. BYO compute still falls out of the binding: App Studio resolves which provider backs a workspace and routes there; a future migration to a true APIExport subresource can swap the transport without touching the resolver or the handler logic.
 
 ### 6.2 Move runner config ownership to infra
 
 
@@ -0,0 +1,109 @@
+/*
+Copyright 2026 The Faros Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package dataplane
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"k8s.io/client-go/dynamic"
+
+	infrav1alpha1 "github.com/faroshq/provider-infrastructure/apis/v1alpha1"
+)
+
+// ContractGetter returns the data-plane contract for an instance resource
+// (the lowercase plural, e.g. "sandboxrunners"). Returns a nil contract with no
+// error when the template declares no data plane, and an error when no template
+// owns the resource.
+type ContractGetter interface {
+	For(ctx context.Context, resource string) (*infrav1alpha1.TemplateDataPlane, error)
+}
+
+var templateGVR = schema.GroupVersionResource{
+	Group:    "infrastructure.kedge.faros.sh",
+	Version:  "v1alpha1",
+	Resource: "templates",
+}
+
+// TemplateContractGetter resolves a resource's data-plane contract by reading
+// Templates from the provider workspace with the provider's own (platform)
+// kcp client. Templates are platform-owned and cluster-scoped, so reading them
+// with the provider credential is correct — the caller's RBAC is enforced
+// separately, on the instance (see handler.go).
+type TemplateContractGetter struct {
+	templates dynamic.NamespaceableResourceInterface
+}
+
+// NewTemplateContractGetter builds a getter over the provider's dynamic client.
+// Returns nil when client is nil (REST-only/dev serve), which the handler
+// surfaces as "data plane unavailable".
+func NewTemplateContractGetter(client dynamic.Interface) *TemplateContractGetter {
+	if client == nil {
+		return nil
+	}
+	return &TemplateContractGetter{templates: client.Resource(templateGVR)}
+}
+
+// For lists Templates and returns the dataPlane of the one whose
+// spec.instanceCRD.resource matches. Not cached: the Template set is tiny and a
+// stale contract would silently mis-route a proxy, so we always read fresh.
+func (g *TemplateContractGetter) For(ctx context.Context, resource string) (*infrav1alpha1.TemplateDataPlane, error) {
+	resource = strings.TrimSpace(resource)
+	if resource == "" {
+		return nil, fmt.Errorf("empty instance resource")
+	}
+	list, err := g.templates.List(ctx, metav1.ListOptions{})
+	if err != nil {
+		return nil, fmt.Errorf("listing templates: %w", err)
+	}
+	for i := range list.Items {
+		tmpl := &list.Items[i]
+		got, _, _ := unstructured.NestedString(tmpl.Object, "spec", "instanceCRD", "resource")
+		if strings.TrimSpace(got) != resource {
+			continue
+		}
+		return dataPlaneFromTemplate(tmpl)
+	}
+	return nil, fmt.Errorf("no template owns resource %q", resource)
+}
+
+// dataPlaneFromTemplate extracts and decodes spec.dataPlane from a Template's
+// unstructured form. Returns (nil, nil) when the template declares no data
+// plane.
+func dataPlaneFromTemplate(tmpl *unstructured.Unstructured) (*infrav1alpha1.TemplateDataPlane, error) {
+	raw, found, err := unstructured.NestedMap(tmpl.Object, "spec", "dataPlane")
+	if err != nil {
+		return nil, fmt.Errorf("template %q spec.dataPlane is malformed: %w", tmpl.GetName(), err)
+	}
+	if !found || len(raw) == 0 {
+		return nil, nil
+	}
+	encoded, err := json.Marshal(raw)
+	if err != nil {
+		return nil, fmt.Errorf("template %q spec.dataPlane re-encode: %w", tmpl.GetName(), err)
+	}
+	var contract infrav1alpha1.TemplateDataPlane
+	if err := json.Unmarshal(encoded, &contract); err != nil {
+		return nil, fmt.Errorf("template %q spec.dataPlane decode: %w", tmpl.GetName(), err)
+	}
+	return &contract, nil
+}
@@ -0,0 +1,186 @@
+/*
+Copyright 2026 The Faros Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package dataplane
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
+)
+
+// PathPrefix is where the handler is mounted on the provider's serve mux. It is
+// reached through the hub backend proxy at
+// /services/providers/infrastructure/dataplane/... with the caller's bearer
+// token forwarded as-is and X-Kedge-* identity headers injected.
+const PathPrefix = "/dataplane/"
+
+// InstanceGetter authorizes and fetches a workload instance AS THE CALLER. The
+// implementation builds a tenant-scoped client from (workspace, token) and does
+// a GET — so a 403/404 from the caller's RBAC is the access gate for the whole
+// data plane. No provider-wide credential is consulted here.
+type InstanceGetter interface {
+	Get(ctx context.Context, workspace, token, resource, name string) (*unstructured.Unstructured, error)
+}
+
+// Handler serves a template's declared data-plane verbs as subresources on a
+// workload instance:
+//
+//	/dataplane/clusters/<ws>/<resource>/<name>/<verb>[/<caller-path...>]
+//
+// e.g. /dataplane/clusters/root:kedge:orgs:acme/sandboxrunners/kedge-sandbox-…/log
+//
+// It authorizes the caller against the instance, resolves the verb to a runtime
+// target via the template contract, and reverse-proxies to the runtime cluster
+// the provider owns. Consumers therefore never hold a runtime credential.
+type Handler struct {
+	instances InstanceGetter
+	contracts ContractGetter
+	runtime   Runtime
+}
+
+// NewHandler wires the handler. Any nil dependency makes the data plane report
+// 503 (the serve process runs without a runtime/kcp config in dev).
+func NewHandler(instances InstanceGetter, contracts ContractGetter, runtime Runtime) *Handler {
+	return &Handler{instances: instances, contracts: contracts, runtime: runtime}
+}
+
+// request is the parsed addressing of a data-plane call.
+type request struct {
+	workspace  string
+	resource   string
+	name       string
+	verb       string
+	callerPath string // remaining path beyond the verb (open-proxy tail)
+}
+
+func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	if h == nil || h.instances == nil || h.contracts == nil || h.runtime == nil {
+		http.Error(w, "data plane unavailable on this provider", http.StatusServiceUnavailable)
+		return
+	}
+
+	id := identityFromRequest(r)
+	if id.token == "" {
+		http.Error(w, "no bearer token — cannot act on the caller's behalf", http.StatusUnauthorized)
+		return
+	}
+
+	req, ok := parsePath(r.URL.Path)
+	if !ok {
+		http.Error(w, "bad data-plane path; want /dataplane/clusters/<ws>/<resource>/<name>/<verb>", http.StatusBadRequest)
+		return
+	}
+
+	// 1. Authorize + fetch the instance as the caller. RBAC is the gate.
+	instance, err := h.instances.Get(r.Context(), req.workspace, id.token, req.resource, req.name)
+	if err != nil {
+		writeKubeError(w, err)
+		return
+	}
+
+	// 2. Resolve the template's data-plane contract for this resource.
+	contract, err := h.contracts.For(r.Context(), req.resource)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusNotFound)
+		return
+	}
+	if contract == nil {
+		http.Error(w, "resource "+req.resource+" exposes no data plane", http.StatusNotFound)
+		return
+	}
+
+	// 3. Method allowlist for the verb.
+	if !MethodAllowed(contract, req.verb, r.Method) {
+		http.Error(w, "method "+r.Method+" not allowed for verb "+req.verb, http.StatusMethodNotAllowed)
+		return
+	}
+
+	// 4. Resolve the verb to a concrete runtime target (namespace-confined).
+	target, err := Resolve(contract, instance, req.verb)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusConflict)
+		return
+	}
+
+	// 5a. A status verb is served straight from the instance status — no hop.
+	if target.FromStatus {
+		writeInstanceStatus(w, instance)
+		return
+	}
+
+	// 5b. Reverse-proxy to the runtime Service the provider owns.
+	serveProxy(w, r, h.runtime, target, req.callerPath)
+}
+
+// parsePath parses /dataplane/clusters/<ws>/<resource>/<name>/<verb>[/<tail...>].
+// The workspace segment may itself contain colons (root:kedge:orgs:acme); it is
+// a single path segment, so no escaping is needed.
+func parsePath(p string) (request, bool) {
+	rest := strings.TrimPrefix(p, PathPrefix)
+	if rest == p {
+		return request{}, false
+	}
+	rest = strings.TrimPrefix(rest, "clusters/")
+	parts := strings.SplitN(rest, "/", 5)
+	// parts: [ws, resource, name, verb, tail?]
+	if len(parts) < 4 {
+		return request{}, false
+	}
+	req := request{
+		workspace: strings.TrimSpace(parts[0]),
+		resource:  strings.TrimSpace(parts[1]),
+		name:      strings.TrimSpace(parts[2]),
+		verb:      strings.TrimSpace(parts[3]),
+	}
+	if req.workspace == "" || req.resource == "" || req.name == "" || req.verb == "" {
+		return request{}, false
+	}
+	if len(parts) == 5 {
+		req.callerPath = "/" + parts[4]
+	}
+	return req, true
+}
+
+// writeInstanceStatus returns the instance's status subobject as JSON.
+func writeInstanceStatus(w http.ResponseWriter, instance *unstructured.Unstructured) {
+	status, _, _ := unstructured.NestedMap(instance.Object, "status")
+	if status == nil {
+		status = map[string]any{}
+	}
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(status)
+}
+
+// writeKubeError maps a Kubernetes API error from the authorize/fetch step to
+// an HTTP status, so a caller's 403/404 surfaces faithfully rather than as 500.
+func writeKubeError(w http.ResponseWriter, err error) {
+	var statusErr *apierrors.StatusError
+	if errors.As(err, &statusErr) {
+		code := int(statusErr.ErrStatus.Code)
+		if code == 0 {
+			code = http.StatusBadGateway
+		}
+		http.Error(w, statusErr.ErrStatus.Message, code)
+		return
+	}
+	http.Error(w, err.Error(), http.StatusBadGateway)
+}