@deepnote/cloud-mock 0.0.0-stage → 0.1.0

package/dist/server-CcG0_Okb.js

@@ -0,0 +1,528 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { buffer, text } from "node:stream/consumers";
+import { deserializeDeepnoteFile, serializeDeepnoteFile } from "@deepnote/blocks";
+import { unzipSync, zipSync } from "fflate";
+import { z } from "zod";
+import { once } from "node:events";
+import { createServer } from "node:http";
+import os from "node:os";
+//#region src/http.ts
+/** Thrown from a route, `onRequest` or `onNotFound`, answers the request with `status` and an `ErrorResponse` body. */
+var HttpError = class extends Error {
+	status;
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+	}
+};
+/** Answers with `body` as JSON. */
+function sendJson(res, status, body) {
+	const text = JSON.stringify(body);
+	res.writeHead(status, { "Content-Type": "application/json" }).end(text);
+}
+/** Answers with `status` and the `ErrorResponse` body `{ message }`. */
+function sendError(res, status, message) {
+	sendJson(res, status, { message });
+}
+/** Answers with a 200 of `bytes` as `contentType`. */
+function sendBytes(res, contentType, bytes) {
+	res.writeHead(200, { "Content-Type": contentType }).end(bytes);
+}
+//#endregion
+//#region src/utils.ts
+const EPOCH = (/* @__PURE__ */ new Date(0)).toISOString();
+const decoder = new TextDecoder();
+function parseDocument(content) {
+	return deserializeDeepnoteFile(decoder.decode(content));
+}
+function sha256(data) {
+	return createHash("sha256").update(data).digest("hex");
+}
+/** The content hash from `packages/cloud/docs/project-import-contract.md`. */
+function canonicalHash(files) {
+	return sha256(files.map(({ filename, content }) => `${filename}\n${sha256(content)}`).sort().join("\n"));
+}
+function projectModifiedAt(files) {
+	const first = files.at(0);
+	return first ? parseDocument(first.content).metadata.modifiedAt ?? EPOCH : EPOCH;
+}
+function importedNotebooks(document, action) {
+	return document.project.notebooks.map(({ id, name }) => ({
+		id,
+		name,
+		action
+	}));
+}
+function dataAppSettings({ url, publishedDataApps }, { id, projectType }) {
+	return projectType === "data_app" ? {
+		published: publishedDataApps.has(id),
+		url: `${url}/apps/${id}/`
+	} : null;
+}
+//#endregion
+//#region src/file-utils.ts
+const NOTEBOOK_FILE = /^[^/\\]+\.deepnote$/;
+const FILES_DIR = ".files";
+const DATA_APP_MARKER = ".data-app";
+async function statIfExists(target) {
+	try {
+		return await fs.stat(target);
+	} catch (error) {
+		const { code } = error;
+		if (code === "ENOENT" || code === "ENOTDIR") return;
+		throw error;
+	}
+}
+/** Sorted the way `@deepnote/cloud`'s `exportProject` sorts them, so the first one is the one
+* sync reads `modifiedAt` from. */
+async function readNotebookFiles(projectDir) {
+	const filenames = (await fs.readdir(projectDir, { withFileTypes: true })).filter((entry) => entry.isFile() && NOTEBOOK_FILE.test(entry.name)).map(({ name }) => name).sort((a, b) => a.localeCompare(b));
+	return Promise.all(filenames.map(async (filename) => ({
+		filename,
+		content: await fs.readFile(path.join(projectDir, filename))
+	})));
+}
+async function projectDir(rootDir, projectId) {
+	const dir = path.join(rootDir, projectId);
+	if (!(await statIfExists(dir))?.isDirectory()) throw new HttpError(404, "Project not found");
+	return dir;
+}
+function normalizeFilePath(rawPath) {
+	const trimmedPath = rawPath.trim();
+	if (!trimmedPath) throw new HttpError(400, "path is required");
+	if (trimmedPath.includes("\0")) throw new HttpError(400, "path must not contain null bytes");
+	if (trimmedPath.split("/").filter((segment) => segment.length > 0).includes("..")) throw new HttpError(400, "path must not contain directory traversal");
+	if (trimmedPath.endsWith("/")) throw new HttpError(400, "path must reference a file, not a directory");
+	const normalizedPath = path.posix.normalize(trimmedPath).replace(/^\/+/, "");
+	if (!normalizedPath || normalizedPath === ".") throw new HttpError(400, "path is required");
+	return normalizedPath;
+}
+function workingFile(filesDir, value) {
+	const target = path.resolve(filesDir, normalizeFilePath(value));
+	if (!target.startsWith(filesDir + path.sep)) throw new HttpError(400, "Invalid path");
+	return target;
+}
+async function freeWorkingFile(target) {
+	const { dir, name, ext } = path.parse(target);
+	for (let n = 1;; n++) {
+		const candidate = path.join(dir, `${name} (${n})${ext}`);
+		if (!await statIfExists(candidate)) return candidate;
+	}
+}
+async function listWorkingFiles(filesDir) {
+	if (!(await statIfExists(filesDir))?.isDirectory()) return [];
+	const filePaths = (await fs.readdir(filesDir, {
+		recursive: true,
+		withFileTypes: true
+	})).filter((entry) => entry.isFile()).map((entry) => path.relative(filesDir, path.join(entry.parentPath, entry.name)).split(path.sep).join("/")).sort();
+	return Promise.all(filePaths.map(async (filePath) => {
+		const { size, mtime } = await fs.stat(path.join(filesDir, filePath));
+		return {
+			name: path.posix.basename(filePath),
+			path: filePath,
+			type: "file",
+			size,
+			updatedAt: mtime.toISOString()
+		};
+	}));
+}
+async function projectSummary(dir) {
+	const id = path.basename(dir);
+	const first = (await readNotebookFiles(dir)).at(0);
+	const { birthtime, mtime } = await fs.stat(dir);
+	return {
+		id,
+		name: first ? parseDocument(first.content).project.name : id,
+		projectType: (await statIfExists(path.join(dir, ".data-app")))?.isFile() ? "data_app" : "standard",
+		createdAt: birthtime.toISOString(),
+		updatedAt: mtime.toISOString(),
+		folder: null
+	};
+}
+//#endregion
+//#region src/schemas.ts
+const BooleanQueryParamSchema = z.enum(["true", "false"]).transform((value) => value === "true");
+const ProjectIdSchema = z.uuid().brand();
+const ProjectIdParamSchema = z.object({ projectId: ProjectIdSchema });
+const FileReferenceQuerySchema = z.strictObject({
+	projectId: ProjectIdSchema,
+	path: z.string().min(1)
+});
+const CreateFileMultipartFieldsSchema = z.strictObject({
+	projectId: ProjectIdSchema,
+	path: z.string().min(1),
+	overwrite: BooleanQueryParamSchema.optional().default(false)
+});
+const CreateProjectBodySchema = z.strictObject({
+	name: z.string().min(1),
+	folderId: z.uuid().optional(),
+	projectType: z.enum([
+		"standard",
+		"notebook",
+		"agent",
+		"data_app",
+		"streamlit_app"
+	]).optional(),
+	environmentId: z.uuid().optional()
+});
+const UpdateProjectBodySchema = z.strictObject({
+	dataApp: z.strictObject({ published: z.boolean() }).optional(),
+	environmentId: z.uuid().optional(),
+	folderId: z.uuid().nullable().optional()
+}).refine((update) => update.dataApp !== void 0 || update.environmentId !== void 0 || update.folderId !== void 0, { message: "At least one project setting must be provided." });
+const ImportProjectQuerySchema = z.strictObject({
+	baseModifiedAt: z.iso.datetime().optional(),
+	baseContentHash: z.string().regex(/^[0-9a-f]{64}$/, "Must be a 64-character lowercase SHA-256 hex digest.").optional(),
+	deleteMissingNotebooks: BooleanQueryParamSchema.optional().default(false),
+	force: BooleanQueryParamSchema.optional().default(false)
+});
+/** Parses `input`, throwing a 400 {@link HttpError} that names each invalid field. */
+function parseRequestInput(schema, input) {
+	const result = schema.safeParse(input, { error: (issue) => issue.code === "invalid_type" && issue.input === void 0 ? "is required" : void 0 });
+	if (!result.success) throw new HttpError(400, readableErrors(result.error));
+	return result.data;
+}
+function readableErrors(error) {
+	return error.issues.map((issue) => {
+		const field = issue.path.map(String).join(".");
+		return field ? `${field} ${issue.message.toLowerCase()}` : issue.message;
+	}).join("; ");
+}
+//#endregion
+//#region src/mock-deepnote-cloud.ts
+const MOCK_WORKSPACE_NAME = "Mock Workspace";
+const DATA_APP_PLACEHOLDER_HTML = "<!doctype html>\n<title>Untitled data app</title>\n";
+const ME = {
+	apiKey: {
+		id: "3a9e5c1d-7f2b-4d6e-8c0a-1b4f6d8e2a5c",
+		name: "Mock API key",
+		type: "public-api",
+		createdAt: "2026-01-01T00:00:00.000Z",
+		lastUsedAt: null,
+		expiresAt: null
+	},
+	user: {
+		id: "0b3c6f1e-2d4a-4e8b-9c7d-5a1f3e2b8c4d",
+		email: null,
+		name: null
+	},
+	workspace: {
+		id: "7e2d9a4c-1b5f-4c3e-8a6d-9f0b2c4e6a8d",
+		name: MOCK_WORKSPACE_NAME,
+		slug: "mock-workspace"
+	},
+	accessLevel: "admin"
+};
+async function readJsonBody(req) {
+	if (req.headers["content-type"]?.split(";")[0]?.trim().toLowerCase() !== "application/json") return {};
+	const body = await text(req);
+	if (body === "") return {};
+	const value = JSON.parse(body);
+	if (typeof value !== "object" || value === null) throw new SyntaxError("The JSON body is not an object or array");
+	return value;
+}
+async function listProjects({ rootDir, res }) {
+	const ids = (await fs.readdir(rootDir, { withFileTypes: true })).filter((entry) => entry.isDirectory() && ProjectIdSchema.safeParse(entry.name).success).map(({ name }) => name).sort();
+	const projects = await Promise.all(ids.map(async (id) => ({
+		...await projectSummary(path.join(rootDir, id)),
+		notebooks: []
+	})));
+	sendJson(res, 200, {
+		projects,
+		pagination: {
+			pageSize: projects.length,
+			nextPageToken: null,
+			hasMore: false
+		}
+	});
+}
+async function createProject({ rootDir, req, res }) {
+	const { name, folderId, projectType, environmentId } = parseRequestInput(CreateProjectBodySchema, await readJsonBody(req));
+	if (projectType !== void 0 && projectType !== "standard" && projectType !== "data_app") throw new HttpError(400, "The mock creates only standard and data_app projects");
+	if (folderId !== void 0) throw new HttpError(404, "Folder not found");
+	if (environmentId !== void 0) throw new HttpError(404, "Environment not found");
+	const projectId = randomUUID();
+	const dir = path.join(rootDir, projectId);
+	await fs.mkdir(dir);
+	if (projectType === "data_app") {
+		await fs.writeFile(path.join(dir, DATA_APP_MARKER), "");
+		await fs.mkdir(path.join(dir, FILES_DIR, "_deepnote_static"), { recursive: true });
+		await fs.writeFile(path.join(dir, FILES_DIR, "_deepnote_static/index.html"), DATA_APP_PLACEHOLDER_HTML);
+	}
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const notebook = {
+		id: randomUUID(),
+		name: "Notebook 1",
+		blocks: []
+	};
+	await fs.writeFile(path.join(dir, "notebook.deepnote"), serializeDeepnoteFile({
+		version: "1.0.0",
+		metadata: {
+			createdAt: now,
+			modifiedAt: now
+		},
+		project: {
+			id: projectId,
+			name,
+			notebooks: [notebook]
+		}
+	}));
+	const summary = await projectSummary(dir);
+	sendJson(res, 201, { project: {
+		...summary,
+		notebooks: [{
+			id: notebook.id,
+			projectId,
+			name: notebook.name,
+			createdAt: summary.createdAt,
+			isInit: false,
+			isScheduled: false,
+			lastRunAt: null
+		}],
+		environment: null
+	} });
+}
+async function getProject(request) {
+	const { projectId } = parseRequestInput(ProjectIdParamSchema, { projectId: request.pathProjectId });
+	const dir = await projectDir(request.rootDir, projectId);
+	const summary = await projectSummary(dir);
+	const body = { project: {
+		...summary,
+		notebooks: [],
+		integrations: [],
+		files: await listWorkingFiles(path.join(dir, FILES_DIR)),
+		dataApp: dataAppSettings(request, summary),
+		environment: null
+	} };
+	sendJson(request.res, 200, body);
+}
+async function updateProject(request) {
+	const { projectId } = parseRequestInput(ProjectIdParamSchema, { projectId: request.pathProjectId });
+	const { dataApp: update } = parseRequestInput(UpdateProjectBodySchema, await readJsonBody(request.req));
+	const summary = await projectSummary(await projectDir(request.rootDir, projectId));
+	if (update) {
+		if (summary.projectType !== "data_app") throw new HttpError(400, "Only data apps can be published.");
+		if (update.published) request.publishedDataApps.add(summary.id);
+		else request.publishedDataApps.delete(summary.id);
+	}
+	const body = { project: {
+		...summary,
+		dataApp: dataAppSettings(request, summary),
+		environment: null
+	} };
+	sendJson(request.res, 200, body);
+}
+async function exportProject({ rootDir, res, pathProjectId }) {
+	const { projectId } = parseRequestInput(ProjectIdParamSchema, { projectId: pathProjectId });
+	const files = await readNotebookFiles(await projectDir(rootDir, projectId));
+	sendBytes(res, "application/zip", zipSync(Object.fromEntries(files.map((file) => [file.filename, file.content]))));
+}
+async function importProject({ rootDir, req, res, requestUrl, pathProjectId }) {
+	const { projectId } = parseRequestInput(ProjectIdParamSchema, { projectId: pathProjectId });
+	const options = parseRequestInput(ImportProjectQuerySchema, Object.fromEntries(requestUrl.searchParams));
+	if (req.headers["content-type"]?.split(";")[0]?.trim().toLowerCase() !== "application/zip") throw new HttpError(400, "Content-Type must be application/zip");
+	const dir = await projectDir(rootDir, projectId);
+	const body = await buffer(req);
+	const archive = Object.entries(unzipSync(body)).map(([filename, content]) => ({
+		filename,
+		content
+	}));
+	if (!archive.every(({ filename }) => NOTEBOOK_FILE.test(filename))) throw new HttpError(422, "The archive may contain only .deepnote files");
+	const documents = archive.map((file) => ({
+		...file,
+		document: parseDocument(file.content)
+	}));
+	const projects = documents.map(({ document }) => document.project);
+	if (projects.some((project) => project.id !== projectId)) throw new HttpError(422, "A document belongs to another project");
+	if (projects.some((project) => project.notebooks.length !== 1)) throw new HttpError(422, "A document must contain exactly one notebook");
+	const current = await readNotebookFiles(dir);
+	if (!options.force) {
+		const { baseModifiedAt, baseContentHash } = options;
+		if (baseModifiedAt && new Date(baseModifiedAt).getTime() !== new Date(projectModifiedAt(current)).getTime()) throw new HttpError(409, "Project structure changed since it was exported.");
+		if (baseContentHash && baseContentHash !== canonicalHash(current)) throw new HttpError(409, "Project content changed since it was exported.");
+	}
+	const imported = new Set(archive.map(({ filename }) => filename));
+	const missing = options.deleteMissingNotebooks ? current.filter(({ filename }) => !imported.has(filename)) : [];
+	const deletedNotebooks = missing.flatMap(({ content }) => importedNotebooks(parseDocument(content), "deleted"));
+	const existing = new Set(current.map(({ filename }) => filename));
+	const notebooks = [];
+	for (const { filename, content, document } of documents) {
+		await fs.writeFile(path.join(dir, filename), content);
+		notebooks.push(...importedNotebooks(document, existing.has(filename) ? "overwritten" : "created"));
+	}
+	for (const { filename } of missing) await fs.rm(path.join(dir, filename));
+	notebooks.push(...deletedNotebooks);
+	const after = await readNotebookFiles(dir);
+	sendJson(res, 200, {
+		project: {
+			id: projectId,
+			modifiedAt: projectModifiedAt(after),
+			contentHash: canonicalHash(after)
+		},
+		notebooks
+	});
+}
+async function downloadFile({ rootDir, res, requestUrl }) {
+	const { projectId, path: filePath } = parseRequestInput(FileReferenceQuerySchema, Object.fromEntries(requestUrl.searchParams));
+	const target = workingFile(path.join(rootDir, projectId, FILES_DIR), filePath);
+	const stats = await statIfExists(target);
+	if (!stats) throw new HttpError(404, "File not found");
+	if (!stats.isFile()) throw new HttpError(400, "Path is not a file");
+	sendBytes(res, "application/octet-stream", await fs.readFile(target));
+}
+async function uploadFile({ rootDir, req, res, requestUrl }) {
+	const body = await buffer(req);
+	let form;
+	try {
+		form = await new Request(requestUrl, {
+			method: "POST",
+			headers: { "Content-Type": req.headers["content-type"] ?? "" },
+			body
+		}).formData();
+	} catch {
+		throw new HttpError(400, "Expected a multipart upload");
+	}
+	const { projectId, path: requestedPath, overwrite } = parseRequestInput(CreateFileMultipartFieldsSchema, Object.fromEntries([...form].filter(([, value]) => typeof value === "string")));
+	const file = form.get("file");
+	if (file === null || typeof file === "string") throw new HttpError(400, "file is required");
+	const filesDir = path.join(rootDir, projectId, FILES_DIR);
+	const requested = workingFile(filesDir, requestedPath);
+	await projectDir(rootDir, projectId);
+	const stored = !overwrite && await statIfExists(requested) ? await freeWorkingFile(requested) : requested;
+	await fs.mkdir(path.dirname(stored), { recursive: true });
+	await fs.writeFile(stored, new Uint8Array(await file.arrayBuffer()));
+	const { size, mtime } = await fs.stat(stored);
+	sendJson(res, 201, { file: {
+		projectId,
+		path: path.relative(filesDir, stored).split(path.sep).join("/"),
+		size,
+		updatedAt: mtime.toISOString()
+	} });
+}
+async function deleteFile({ rootDir, res, requestUrl }) {
+	const { projectId, path: filePath } = parseRequestInput(FileReferenceQuerySchema, Object.fromEntries(requestUrl.searchParams));
+	const target = workingFile(path.join(rootDir, projectId, FILES_DIR), filePath);
+	const stats = await statIfExists(target);
+	if (!stats) throw new HttpError(404, "File not found");
+	if (!stats.isFile()) throw new HttpError(400, "Path is not a file");
+	await fs.rm(target);
+	res.writeHead(204).end();
+}
+const ROUTES = [
+	{
+		method: "GET",
+		pattern: /^\/v2\/me$/,
+		handle: async ({ res }) => sendJson(res, 200, ME)
+	},
+	{
+		method: "GET",
+		pattern: /^\/v2\/projects$/,
+		handle: listProjects
+	},
+	{
+		method: "POST",
+		pattern: /^\/v2\/projects$/,
+		handle: createProject
+	},
+	{
+		method: "GET",
+		pattern: /^\/v2\/projects\/([^/]+)$/,
+		handle: getProject
+	},
+	{
+		method: "PATCH",
+		pattern: /^\/v2\/projects\/([^/]+)$/,
+		handle: updateProject
+	},
+	{
+		method: "GET",
+		pattern: /^\/v2\/projects\/([^/]+)\/export$/,
+		handle: exportProject
+	},
+	{
+		method: "POST",
+		pattern: /^\/v2\/projects\/([^/]+)\/import$/,
+		handle: importProject
+	},
+	{
+		method: "GET",
+		pattern: /^\/v2\/files\/download$/,
+		handle: downloadFile
+	},
+	{
+		method: "POST",
+		pattern: /^\/v2\/files$/,
+		handle: uploadFile
+	},
+	{
+		method: "DELETE",
+		pattern: /^\/v2\/files$/,
+		handle: deleteFile
+	}
+];
+//#endregion
+//#region src/server.ts
+async function handleRequest(context, { onRequest, onNotFound }, req, res) {
+	if (!req.headers.authorization?.startsWith("Bearer ")) throw new HttpError(401, "Missing API token");
+	const method = req.method ?? "GET";
+	const requestUrl = new URL(req.url ?? "/", context.url);
+	await onRequest?.({
+		method,
+		url: requestUrl
+	});
+	for (const route of ROUTES) {
+		const match = route.method === method ? route.pattern.exec(requestUrl.pathname) : null;
+		if (match) {
+			await route.handle({
+				...context,
+				req,
+				res,
+				requestUrl,
+				pathProjectId: match[1]
+			});
+			return;
+		}
+	}
+	await onNotFound?.(req, res);
+	if (!res.headersSent) throw new HttpError(404, "Not found");
+}
+/** Starts a mock of the Deepnote Cloud API v2 on a free port of `127.0.0.1`. Any Bearer token is accepted. */
+async function startMockDeepnoteCloud(options = {}) {
+	const rootDir = options.rootDir === void 0 ? await fs.mkdtemp(path.join(os.tmpdir(), "deepnote-cloud-")) : path.resolve(options.rootDir);
+	await fs.mkdir(rootDir, { recursive: true });
+	const server = createServer();
+	server.listen(0, "127.0.0.1");
+	await once(server, "listening");
+	const url = `http://127.0.0.1:${server.address().port}`;
+	const context = {
+		rootDir,
+		url,
+		publishedDataApps: /* @__PURE__ */ new Set()
+	};
+	const handling = /* @__PURE__ */ new Set();
+	server.on("request", (req, res) => {
+		res.setHeader("Connection", "close");
+		const handled = handleRequest(context, options, req, res);
+		handling.add(handled);
+		handled.catch((error) => {
+			if (res.headersSent) throw error;
+			sendError(res, error instanceof HttpError ? error.status : 500, error instanceof Error ? error.message : String(error));
+		}).finally(() => handling.delete(handled));
+	});
+	return {
+		rootDir,
+		url,
+		stop: async () => {
+			await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+			await Promise.allSettled(handling);
+			if (options.rootDir === void 0) await fs.rm(rootDir, {
+				recursive: true,
+				force: true
+			});
+		}
+	};
+}
+//#endregion
+export { sendError as a, sendBytes as i, MOCK_WORKSPACE_NAME as n, sendJson as o, HttpError as r, startMockDeepnoteCloud as t };

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@deepnote/cloud-mock",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Local mock of the Deepnote Cloud Public API v2 for testing",
+  "keywords": [
+    "deepnote",
+    "cloud",
+    "mock",
+    "testing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deepnote/deepnote.git",
+    "directory": "packages/cloud-mock"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "deepnote-cloud-mock": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "dependencies": {
+    "fflate": "^0.8.3",
+    "zod": "^4.6.7",
+    "@deepnote/blocks": "5.0.0"
+  },
+  "devDependencies": {
+    "@deepnote/cloud": "0.4.0"
+  },
+  "engines": {
+    "node": ">=22.14.0",
+    "pnpm": ">=10.17.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest",
+    "watch": "tsdown --watch",
+    "generate:api-types": "pnpm dlx openapi-typescript@7.13.0 https://api.deepnote.com/v2/openapi.json -o src/deepnote-cloud-api.generated.d.ts"
+  }
 }