feat(desktop,trpc): make creating a cloud workspace feel immediate

apps/api/src/app/api/cloud-workspaces/provision/route.ts

@@ -0,0 +1,67 @@
+import { provisionCloudWorkspace } from "@superset/trpc/cloud-workspace-provision";
+import { Receiver } from "@upstash/qstash";
+import { z } from "zod";
+
+import { env } from "@/env";
+
+// Provisioning is a second or two warm, but the first sandboxes after an image
+// rebuild pull the image and take tens of seconds.
+export const maxDuration = 60;
+export const dynamic = "force-dynamic";
+
+const receiver = new Receiver({
+	currentSigningKey: env.QSTASH_CURRENT_SIGNING_KEY,
+	nextSigningKey: env.QSTASH_NEXT_SIGNING_KEY,
+});
+
+const payloadSchema = z
+	.object({
+		cloudWorkspaceId: z.string().uuid(),
+		/** Absent when the user typed a name, which the row already holds. */
+		namingPrompt: z.string().max(20000).optional(),
+	})
+	.strict();
+
+/**
+ * Provisions the sandbox for a `cloud_workspaces` row that `cloudWorkspace.create`
+ * already wrote. The row's status is the only thing the client waits on, so
+ * this job is what turns the provisioning screen into a workspace.
+ */
+export async function POST(request: Request): Promise<Response> {
+	const body = await request.text();
+	const signature = request.headers.get("upstash-signature");
+	if (!signature) {
+		return Response.json({ error: "Missing signature" }, { status: 401 });
+	}
+
+	// `verify` throws rather than returning false on a signature it can't even
+	// parse, so a malformed header answered 500 — reported as a server fault,
+	// noisy in Sentry, and a different answer than a well-formed wrong
+	// signature gets. Both are the same refusal.
+	let valid = false;
+	try {
+		valid = await receiver.verify({
+			body,
+			signature,
+			url: `${env.NEXT_PUBLIC_API_URL}/api/cloud-workspaces/provision`,
+		});
+	} catch {
+		valid = false;
+	}
+	if (!valid) {
+		return Response.json({ error: "Invalid signature" }, { status: 401 });
+	}
+
+	const parsed = payloadSchema.safeParse(JSON.parse(body));
+	if (!parsed.success) {
+		console.error("[cloud-workspaces/provision] invalid payload", parsed.error);
+		return Response.json({ error: "Invalid payload" }, { status: 400 });
+	}
+
+	// A failure here is already recorded on the row and the sandbox already
+	// torn down, so answering 200 is right: a redelivery would repeat work that
+	// deliberately gave up. QStash's retries are for the deliveries that never
+	// reach this line.
+	const outcome = await provisionCloudWorkspace(parsed.data);
+	return Response.json({ ok: true, outcome });
+}

apps/desktop/src/renderer/hooks/host-service/useDestroyWorkspace/useDestroyWorkspace.ts

@@ -4,6 +4,7 @@ import type {
 } from "@superset/host-service";
 import { TRPCClientError } from "@trpc/client";
 import { useCallback } from "react";
+import { useCloudWorkspaces } from "renderer/hooks/useCloudWorkspaces";
 import { apiTrpcClient } from "renderer/lib/api-trpc-client";
 import { cloudTrpc } from "renderer/lib/cloud-trpc";
 import { getHostServiceClientByUrl } from "renderer/lib/host-service-client";
@@ -128,8 +129,12 @@ export function useDestroyWorkspace(workspaceId: string): UseDestroyWorkspace {
 		? "ready"
 		: hostTarget.status;
 
-	const isSandbox =
-		hostTarget.status === "ready" && hostTarget.kind === "sandbox";
+	// The cloud row decides this, not whether we currently hold an address for
+	// it: a workspace still provisioning, or one whose sandbox stopped
+	// answering, is no less a cloud workspace — and deleting it anywhere but at
+	// the API would leave the sandbox running.
+	const { workspaces: cloudWorkspaces } = useCloudWorkspaces();
+	const isSandbox = cloudWorkspaces.some((row) => row.id === workspaceId);
 	const utils = cloudTrpc.useUtils();
 
 	const destroy = useCallback(

apps/desktop/src/renderer/hooks/host-service/useWorkspaceHostUrl/useWorkspaceHostUrl.ts

@@ -50,8 +50,12 @@ export function useWorkspaceHostTarget(
 	const cloudWorkspaces = cloudQuery.data ?? [];
 	const cloudPending =
 		Boolean(organizationId) && !match && !cloudQuery.isFetched;
+	// Only a `ready` row has an address to broker: the list carries workspaces
+	// that are still provisioning, and `access` refuses those.
 	const cloudMatch = workspaceId
-		? (cloudWorkspaces.find((w) => w.id === workspaceId) ?? null)
+		? (cloudWorkspaces.find(
+				(w) => w.id === workspaceId && w.status === "ready",
+			) ?? null)
 		: null;
 	const access = cloudTrpc.cloudWorkspace.access.useMutation();
 	const [sandboxUrl, setSandboxUrl] = useState<string | null>(null);

apps/desktop/src/renderer/hooks/useCloudWorkspaces/index.ts

@@ -0,0 +1,5 @@
+export {
+	type CloudWorkspaceRow,
+	type CloudWorkspacesValue,
+	useCloudWorkspaces,
+} from "./useCloudWorkspaces";

apps/desktop/src/renderer/hooks/useCloudWorkspaces/useCloudWorkspaces.ts

@@ -0,0 +1,50 @@
+import { FEATURE_FLAGS } from "@superset/shared/constants";
+import type { RouterOutputs } from "@superset/trpc";
+import { useFeatureFlagEnabled } from "posthog-js/react";
+import { authClient } from "renderer/lib/auth-client";
+import { cloudTrpc } from "renderer/lib/cloud-trpc";
+
+export type CloudWorkspaceRow = RouterOutputs["cloudWorkspace"]["list"][number];
+
+/**
+ * Someone is watching a provisioning row, so poll like it: a warm sandbox is
+ * up in about a second, and this poll is now the longest part of the wait
+ * between pressing create and the workspace opening.
+ */
+const PROVISIONING_POLL_MS = 1_000;
+const IDLE_POLL_MS = 30_000;
+
+export interface CloudWorkspacesValue {
+	workspaces: CloudWorkspaceRow[];
+	organizationId: string | null;
+}
+
+/**
+ * Every cloud workspace in the active organization, including the ones still
+ * provisioning and the ones that failed. The row exists from the moment create
+ * returns, and both the sidebar and the workspace route render it long before
+ * a sandbox is behind it.
+ *
+ * Shared rather than queried per consumer so the polling cadence is one
+ * decision: while anything is provisioning there is a screen waiting on the
+ * flip to `ready`, and a 30s poll would leave it spinning for half a minute
+ * after the sandbox came up.
+ */
+export function useCloudWorkspaces(): CloudWorkspacesValue {
+	const enabled = useFeatureFlagEnabled(FEATURE_FLAGS.CLOUD_WORKSPACES);
+	const { data: session } = authClient.useSession();
+	const organizationId = session?.session?.activeOrganizationId ?? null;
+
+	const query = cloudTrpc.cloudWorkspace.list.useQuery(
+		{ organizationId: organizationId ?? "" },
+		{
+			enabled: Boolean(enabled && organizationId),
+			refetchInterval: (current) =>
+				current.state.data?.some((row) => row.status === "provisioning")
+					? PROVISIONING_POLL_MS
+					: IDLE_POLL_MS,
+		},
+	);
+
+	return { workspaces: query.data ?? [], organizationId };
+}

apps/desktop/src/renderer/routes/_authenticated/_dashboard/components/DashboardSidebar/components/DashboardSidebarCloudSection/DashboardSidebarCloudSection.tsx

@@ -1,9 +1,6 @@
-import { FEATURE_FLAGS } from "@superset/shared/constants";
 import { useLiveQuery } from "@tanstack/react-db";
-import { useFeatureFlagEnabled } from "posthog-js/react";
 import { useMemo } from "react";
-import { authClient } from "renderer/lib/auth-client";
-import { cloudTrpc } from "renderer/lib/cloud-trpc";
+import { useCloudWorkspaces } from "renderer/hooks/useCloudWorkspaces";
 import { useCollections } from "renderer/routes/_authenticated/providers/CollectionsProvider";
 import { useHostWorkspaces } from "renderer/routes/_authenticated/providers/HostWorkspacesProvider";
 import type { DashboardSidebarWorkspace } from "../../types";
@@ -30,14 +27,7 @@ export function DashboardSidebarCloudSection({
 	isCollapsed?: boolean;
 	onWorkspaceHover?: (workspaceId: string) => void | Promise<void>;
 }) {
-	const enabled = useFeatureFlagEnabled(FEATURE_FLAGS.CLOUD_WORKSPACES);
-	const { data: session } = authClient.useSession();
-	const organizationId = session?.session?.activeOrganizationId ?? null;
-
-	const { data: cloudWorkspaces = [] } = cloudTrpc.cloudWorkspace.list.useQuery(
-		{ organizationId: organizationId ?? "" },
-		{ enabled: Boolean(enabled && organizationId), refetchInterval: 30_000 },
-	);
+	const { workspaces: cloudWorkspaces } = useCloudWorkspaces();
 	const { workspaces: hostWorkspaces } = useHostWorkspaces();
 
 	// Row visibility, pinning and order all live in the same local-state
@@ -102,12 +92,25 @@ export function DashboardSidebarCloudSection({
 					updatedAt: cloud.updatedAt,
 					taskId: null,
 					isPinned: false,
-					pendingTransaction: null,
+					// Same row treatment a local create gets while it is in flight —
+					// a spinner instead of a status dot, and no rename/delete menu
+					// on a workspace whose sandbox doesn't exist yet.
+					pendingTransaction:
+						cloud.status === "provisioning"
+							? {
+									id: cloud.id,
+									workspaceId: cloud.id,
+									type: "insert",
+									state: "pending",
+									createdAt: cloud.createdAt,
+									updatedAt: cloud.updatedAt,
+								}
+							: null,
 				};
 			});
 	}, [cloudWorkspaces, hostWorkspaces, localStateRows]);
 
-	if (!enabled || rows.length === 0) return null;
+	if (rows.length === 0) return null;
 
 	if (isCollapsed) {
 		return (

apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/layout.tsx → apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/$workspaceId/layout.tsx

@@ -1,36 +1,37 @@
 import { eq } from "@tanstack/db";
 import { useLiveQuery } from "@tanstack/react-db";
-import { createFileRoute, Outlet, useMatchRoute } from "@tanstack/react-router";
+import { createFileRoute, Outlet } from "@tanstack/react-router";
 import { useEffect, useMemo, useRef } from "react";
+import { useCloudWorkspaces } from "renderer/hooks/useCloudWorkspaces";
 import { useV2UserPreferences } from "renderer/hooks/useV2UserPreferences";
 import { electronTrpc } from "renderer/lib/electron-trpc";
 import { useDashboardSidebarState } from "renderer/routes/_authenticated/hooks/useDashboardSidebarState";
 import { useCollections } from "renderer/routes/_authenticated/providers/CollectionsProvider";
 import { useHostWorkspaces } from "renderer/routes/_authenticated/providers/HostWorkspacesProvider";
 import { useSandboxAccess } from "renderer/routes/_authenticated/providers/SandboxAccessProvider";
 import { useWorkspaceTransactionsStore } from "renderer/stores/workspace-creates";
-import { StateScreenShell } from "./components/StateScreenShell";
-import { WorkspaceCreateErrorState } from "./components/WorkspaceCreateErrorState";
-import { WorkspaceCreatingState } from "./components/WorkspaceCreatingState";
-import { WorkspaceHostIncompatibleState } from "./components/WorkspaceHostIncompatibleState";
-import { WorkspaceNotFoundState } from "./components/WorkspaceNotFoundState";
-import { useRemoteHostStatus } from "./hooks/useRemoteHostStatus";
-import { useWorkspaceMissVerdict } from "./hooks/useWorkspaceMissVerdict";
-import { WorkspaceProvider } from "./providers/WorkspaceProvider";
+import { CloudWorkspaceProvisioningState } from "../components/CloudWorkspaceProvisioningState";
+import { StateScreenShell } from "../components/StateScreenShell";
+import { WorkspaceCreateErrorState } from "../components/WorkspaceCreateErrorState";
+import { WorkspaceCreatingState } from "../components/WorkspaceCreatingState";
+import { WorkspaceHostIncompatibleState } from "../components/WorkspaceHostIncompatibleState";
+import { WorkspaceNotFoundState } from "../components/WorkspaceNotFoundState";
+import { useRemoteHostStatus } from "../hooks/useRemoteHostStatus";
+import { useWorkspaceMissVerdict } from "../hooks/useWorkspaceMissVerdict";
+import { WorkspaceProvider } from "../providers/WorkspaceProvider";
 
-export const Route = createFileRoute("/_authenticated/_dashboard/v2-workspace")(
-	{
-		component: V2WorkspaceLayout,
-	},
-);
+export const Route = createFileRoute(
+	"/_authenticated/_dashboard/v2-workspace/$workspaceId",
+)({
+	component: V2WorkspaceLayout,
+});
 
 function V2WorkspaceLayout() {
-	const matchRoute = useMatchRoute();
-	const workspaceMatch = matchRoute({
-		to: "/v2-workspace/$workspaceId",
-	});
-	const workspaceId =
-		workspaceMatch !== false ? workspaceMatch.workspaceId : null;
+	// Owned by this segment, so the param is available by definition. This used
+	// to live on the parent route, which had to match its own child to recover
+	// the id and then render an empty shell for the "no id" case that route
+	// could always reach and this one cannot.
+	const { workspaceId } = Route.useParams();
 	const collections = useCollections();
 	const { ensureWorkspaceInSidebar } = useDashboardSidebarState();
 	const pendingTransaction = useWorkspaceTransactionsStore((state) =>
@@ -71,6 +72,11 @@ function V2WorkspaceLayout() {
 	const isCloud = sandboxes.some(
 		(sandbox) => sandbox.workspaceId === workspaceId,
 	);
+	// The cloud row exists from the moment the workspace is created, which is
+	// well before there is a sandbox to serve it.
+	const { workspaces: cloudWorkspaces } = useCloudWorkspaces();
+	const cloudWorkspace =
+		cloudWorkspaces.find((row) => row.id === workspaceId) ?? null;
 	const { data: failedEntries } = useLiveQuery(
 		(q) =>
 			q
@@ -108,8 +114,23 @@ function V2WorkspaceLayout() {
 		cache.refetchAll,
 	);
 
-	if (!workspaceId) {
-		return <StateScreenShell>{null}</StateScreenShell>;
+	// Before "not found": a cloud workspace is navigated to as soon as its row
+	// exists, so for the first seconds of its life there is nothing in the
+	// fan-out to find. The same screen covers a ready sandbox that hasn't been
+	// addressed yet (access minting, host-service booting) — that gap used to
+	// be a blank frame, and letting it reach the host-unreachable takeover
+	// would tell the user their machine is down while it is simply starting.
+	if (!workspace && cloudWorkspace) {
+		return (
+			<StateScreenShell>
+				<CloudWorkspaceProvisioningState
+					workspaceId={cloudWorkspace.id}
+					name={cloudWorkspace.name}
+					branch={cloudWorkspace.branch}
+					status={cloudWorkspace.status}
+				/>
+			</StateScreenShell>
+		);
 	}
 
 	if (!workspace) {