gristlabs_grist-core/app/common/ActionBundle.ts
Alex Hall 9fffb491f9 (core) External requests
Summary:
Adds a Python function `REQUEST` which makes an HTTP GET request. Behind the scenes it:

- Raises a special exception to stop trying to evaluate the current cell and just keep the existing value.
- Notes the request arguments which will be returned by `apply_user_actions`.
- Makes the actual request in NodeJS, which sends back the raw response data in a new action `RespondToRequests` which reevaluates the cell(s) that made the request.
- Wraps the response data in a class which mimics the `Response` class of the `requests` library.

In certain cases, this asynchronous flow doesn't work and the sandbox will instead synchronously call an exported JS method:

- When reevaluating a single cell to get a formula error, the request is made synchronously.
- When a formula makes multiple requests, the earlier responses are retrieved synchronously from files which store responses as long as needed to complete evaluating formulas. See https://grist.slack.com/archives/CL1LQ8AT0/p1653399747810139

Test Plan: Added Python and nbrowser tests.

Reviewers: georgegevoian

Reviewed By: georgegevoian

Subscribers: paulfitz, dsagal

Differential Revision: https://phab.getgrist.com/D3429
2022-06-17 21:53:20 +02:00

87 lines
3.6 KiB
TypeScript

/**
* Basic definitions of types needed for ActionBundles.
* See also EncActionBundle for how these are packaged for encryption.
*/
import {DocAction, UserAction} from 'app/common/DocActions';
// Metadata about the action.
export interface ActionInfo {
time: number; // Milliseconds since epoch.
user: string;
inst: string;
desc?: string;
otherId: number;
linkId: number;
}
// Envelope contains information about recipients. In EncActionBundle, it's augmented with
// information about the symmetric key that encrypts this envelope's contents.
export interface Envelope {
recipients: string[]; // sorted array of recipient instanceIds
}
// EnvContent packages arbitrary content with the index of the envelope to which it belongs.
export type EnvContent<Content> = [number, Content];
// ActionBundle contains actions arranged into envelopes, i.e. split up by sets of recipients.
// Note that different Envelopes contain different sets of recipients (which may overlap however).
// ActionBundle is what gets encrypted/decrypted and then sent between hub and instance.
export interface ActionBundle {
actionNum: number;
actionHash: string|null; // a checksum of bundle, (not including actionHash and other parts).
parentActionHash: string|null; // a checksum of the parent action bundle, if there is one.
envelopes: Envelope[];
info: EnvContent<ActionInfo>; // Should be in the envelope addressed to all peers.
stored: Array<EnvContent<DocAction>>;
calc: Array<EnvContent<DocAction>>;
}
export function getEnvContent<Content>(items: Array<EnvContent<Content>>): Content[] {
return items.map((item) => item[1]);
}
// ======================================================================
// Types for ActionBundles used locally inside an instance.
// Local action received from the browser, that is not yet applied. It is usually one UserAction,
// but when multiple actions are sent by the browser in one call, they will form one bundle.
export interface UserActionBundle {
info: ActionInfo;
userActions: UserAction[];
}
// ActionBundle as received from the sandbox. It does not have some action metadata, but does have
// undo information and a retValue for each input UserAction. Note that it is satisfied by the
// ActionBundle structure defined in sandbox/grist/action_obj.py.
export interface SandboxActionBundle {
envelopes: Envelope[];
stored: Array<EnvContent<DocAction>>;
direct: Array<EnvContent<boolean>>;
calc: Array<EnvContent<DocAction>>;
undo: Array<EnvContent<DocAction>>; // Inverse actions for all 'stored' actions.
retValues: any[]; // Contains retValue for each of userActions.
rowCount: number;
// Mapping of keys (hashes of request args) to all unique requests made in a round of calculation
requests?: Record<string, SandboxRequest>;
}
// Represents a unique call to the Python REQUEST function
export interface SandboxRequest {
url: string;
params: Record<string, string> | null;
headers: Record<string, string> | null;
deps: unknown; // pass back to the sandbox unchanged in the response
}
// Local action that's been applied. It now has an actionNum, and includes doc actions packaged
// into envelopes, as well as undo, and userActions, which allow rebasing.
export interface LocalActionBundle extends ActionBundle {
userActions: UserAction[];
// Inverse actions for all 'stored' actions. These aren't shared and not split by envelope.
// Applying 'undo' is governed by EDIT rather than READ permissions, so we always apply all undo
// actions. (It is the result of applying 'undo' that may be addressed to different recipients).
undo: DocAction[];
}