Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ Run `Deepnote: Preview App` from the Command Palette, or right-click a folder in
- Like a run in Deepnote, it is not read-only: what its code writes, such as files or stored dataframes, is written.
- A run keeps going until its notebook finishes, even after you close the preview. Reloading or closing the VS Code window stops it.
- For a legacy `.deepnote` file that holds several notebooks, the first run shows the prompt to split the file, as opening the file does.
- The page's other calls to Deepnote reach a local stand-in that does not support them yet: `appData()` rejects with a message saying so, and VS Code shows a warning the first time the app calls it.
- `appData()` answers from that notebook's newest successful `run()` in the preview: the first JSON object the run displayed (an `application/json` output), the first agent block's answer, and when the run started. Until a run succeeds, it rejects with Deepnote's message. The preview keeps run results in memory, so reloading or closing the VS Code window clears them.
- Previewing needs a trusted workspace and the desktop app.

### Database integrations
Expand Down
102 changes: 95 additions & 7 deletions src/notebooks/deepnote/appPreview/appPreviewApi.node.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,27 @@ import { getInputBlockValueOverrideValidationError, isInputBlock } from '@deepno
// TODO: Import from `@deepnote/cloud` once it exports the API's generated types. The mock package is only a
// devDependency, which is fine for a type-only import because the build erases it.
import type { operations } from '@deepnote/cloud-mock';
import type { IOutput, IStream } from '@deepnote/runtime-core';
import { timingSafeEqual } from 'crypto';
import express, { type NextFunction, type Request, type Response, type Router } from 'express';
import { CancellationTokenSource } from 'vscode';
import { z } from 'zod';

import { concatMultilineString } from '../../../platform/common/utils';
import { isObject } from '../../../platform/common/utils/sysTypes';
import { generateUuid } from '../../../platform/common/uuid';
import type { DeepnoteNotebook } from '../../../platform/deepnote/deepnoteTypes';
import { logger } from '../../../platform/logging';
import { blocksInNotebookOrder, toNotebookInputs, type WorkspaceNotebook } from './appPreviewWorkspace.node';
import type { AppPreviewInputValue, AppPreviewRunOutcome, AppPreviewRunRequest, IAppPreviewRunner } from './types';
import type {
AppPreviewInputValue,
AppPreviewRunOutcome,
AppPreviewRunRequest,
IAppPreviewRunner,
SnapshotBlock
} from './types';

export type AppPreviewOperation = 'appData()' | 'dataframe()';
export type AppPreviewOperation = 'dataframe()';

export interface AppPreviewApiOptions {
token: string;
Expand Down Expand Up @@ -49,6 +58,8 @@ export interface AppPreviewApi {
const UNAUTHORIZED_MESSAGE = 'Unauthorized';
const NOT_AVAILABLE_MESSAGE = 'This endpoint is not available to app viewer tokens';
const NOTEBOOK_NOT_FOUND_MESSAGE = 'Notebook not found';
const NO_RUN_RESULTS_MESSAGE = 'You have no run results for this notebook yet. Run the notebook to load them.';
const NO_JSON_OUTPUT_MESSAGE = 'Your latest run has no JSON output.';
const RUN_NOT_FOUND_MESSAGE = 'Run not found';
const INTERNAL_ERROR_MESSAGE = 'Internal server error';

Expand Down Expand Up @@ -97,6 +108,35 @@ function evictFinishedRuns(runs: Map<string, PreviewRun>): void {
removable.slice(0, Math.max(0, removable.length - MAX_FINISHED_RUNS)).forEach((run) => runs.delete(run.runId));
}

/**
* Deepnote's `agentBlockSummary`: the first agent block's first markdown output. runtime-core emits an agent's answer
* as stream output instead, so without markdown it is the block's stream text.
*/
function firstAgentBlockSummary(blocks: SnapshotBlock[]): string | null {
const agent = blocks.find((block) => block.type === 'agent');
if (!agent) {
return null;
}

const markdown = agent.outputs
.map((output) => mimeData(output, 'text/markdown'))
.find((data): data is string => typeof data === 'string');
if (markdown !== undefined) {
return markdown;
}
const streams = agent.outputs.filter((output): output is IStream => output.output_type === 'stream');

return streams.length > 0 ? streams.map((output) => concatMultilineString(output.text)).join('') : null;
}

/** Deepnote's `appData`: the first `application/json` output that is an object, not an array or `null`. */
function firstJsonObject(blocks: SnapshotBlock[]): Record<string, unknown> | undefined {
return blocks
.flatMap((block) => block.outputs)
.map((output) => mimeData(output, 'application/json'))
.find(isJsonObject);
}

/** The input check Deepnote's `POST /v2/runs` makes before it accepts a run. */
function inputsError(notebook: DeepnoteNotebook, inputs: Record<string, AppPreviewInputValue>): string | undefined {
const inputBlocks = notebook.blocks.filter(isInputBlock);
Expand Down Expand Up @@ -127,6 +167,32 @@ function isAuthorized(authorizationHeader: string | undefined, token: string): b
return actual.length === expected.length && timingSafeEqual(actual, expected);
}

// isObject's own guard is `obj is any`, which would switch off type checking where it narrows.
function isJsonObject(value: unknown): value is Record<string, unknown> {
return isObject(value);
}

function mimeData(output: IOutput, mimeType: string): unknown {
const data: unknown = output.data;

return isJsonObject(data) ? data[mimeType] : undefined;
}

function newestSuccessfulRun(runs: Map<string, PreviewRun>, notebookId: string): PreviewRun | undefined {
let newest: PreviewRun | undefined;
for (const run of runs.values()) {
if (
run.notebookId === notebookId &&
run.status === 'success' &&
(!newest || run.createdAt >= newest.createdAt)
) {
newest = run;
}
}

return newest;
}

/** Deepnote's 400 message for a body that fails its schema. */
function readableErrors(error: z.ZodError): string {
return error.issues
Expand Down Expand Up @@ -160,10 +226,11 @@ function toAppViewerNotebook({ file, notebook }: WorkspaceNotebook): AppViewerNo
/**
* The local stand-in for Deepnote's app viewer API, mounted at `/v2` on the preview server.
* Requests without the preview's bearer token get 401. `GET /notebooks/:notebookId` answers from the workspace's
* notebooks, and `POST /runs` runs one with `runner`, which `GET /runs/:runId` then reports on. The other routes
* Deepnote's client calls or is about to call get 501, and every other route gets 403, as Deepnote answers app viewer
* tokens. A body that cannot be read, such as malformed JSON, gets its 4xx; any other failure is logged and gets a JSON
* 500.
* notebooks, and `POST /runs` runs one with `runner`, which `GET /runs/:runId` then reports on.
* `GET /notebooks/:notebookId/app-data` answers from the notebook's newest successful run. The dataframe route, which
* the version of Deepnote's client that adds `dataframe()` calls, gets 501, and every other route gets 403, as Deepnote
* answers app viewer tokens. A body that cannot be read, such as malformed JSON, gets its 4xx; any other failure is
* logged and gets a JSON 500.
*/
export function createAppPreviewApi(options: AppPreviewApiOptions): AppPreviewApi {
const router = express.Router();
Expand Down Expand Up @@ -220,7 +287,28 @@ export function createAppPreviewApi(options: AppPreviewApiOptions): AppPreviewAp
}
res.json({ notebook: toAppViewerNotebook(found) });
});
router.get('/notebooks/:notebookId/app-data', unsupported('appData()'));
router.get('/notebooks/:notebookId/app-data', async (req: Request<{ notebookId: string }>, res: Response) => {
const { notebookId } = req.params;
if (!(await options.findNotebook(notebookId))) {
res.status(404).json({ message: NOTEBOOK_NOT_FOUND_MESSAGE });

return;
}
const run = newestSuccessfulRun(runs, notebookId);
if (!run) {
res.status(404).json({ message: NO_RUN_RESULTS_MESSAGE });

return;
}
const blocks = run.snapshotBlocks ?? [];
const appData = firstJsonObject(blocks);
if (!appData) {
res.status(404).json({ message: NO_JSON_OUTPUT_MESSAGE });

return;
}
res.json({ appData, agentBlockSummary: firstAgentBlockSummary(blocks), runCreatedAt: run.createdAt });
});
router.post('/runs', express.json(), async (req: Request, res: Response) => {
const parsed = createRunBodySchema.safeParse(req.body, {
// Deepnote's error map, so a missing field reads `is required`.
Expand Down
Loading
Loading