querysub 0.2.0

package/src/2-proxy/schema2.ts

@@ -0,0 +1,518 @@
+import { cache } from "socket-function/src/caching";
+import { nextId, recursiveFreeze } from "socket-function/src/misc";
+import { canHaveChildren } from "socket-function/src/types";
+import { isDefined } from "../misc";
+
+function example() {
+    return {
+        value: t.number,
+        valueUnion: t.number.string,
+        valueWithWeirdDefault: t.number(1),
+        obj: t.atomic({ key: "", value: 0 }),
+        objWithUnion: t.atomic<{ key: string; value: number | string; }>({ key: "", value: "" }),
+        users: t.lookup({
+            name: t.string
+        }),
+        userNoGC: t.lookupNoGC({
+            name: t.string
+        }),
+        // atomicOnlyOnWrite makes new reads faster, without breaking old non-atomic data
+        //  (but it means you can't do truthy checks on the value).
+        metadata: t.atomicOnlyOnWrite<{ a: number }>()
+    };
+}
+
+type TypeDefType<T = never, Optional = false> = {
+
+    /** A passthrough to strip the type wrapper for qreact.state,
+     *      or for piecing together schemas.
+     */
+    state<StateT>(typeDef: StateT): TypeDefToT<StateT>;
+
+    // NOTE: BigInt isn't supported well by cbor-x (their documentation says it is stored in 64-bit precision,
+    //  although maybe that is out of date?), so we won't encourage it's use here.
+    // NOTE: Symbol isn't supported by cbor-x, so we definitely won't encourage it's use here.
+    // NOTE: Buffer will probably work fine, but... it is better to not use it directly, as it encourages
+    //      using large buffers, which... while they might work, are not handled efficiently by our framework.
+    //      It is better to offload large Buffers to cloud storage and pass around a hash instead.
+
+    /** Atomic values are read/written atomically, as the value OR undefined (if not value is set). This allows
+     *      objects to be used more naturally, without having to wrap them in atomic() calls.
+     */
+    atomic<NewT>(defaultValue?: T | NewT): TypeDefType<T | NewT>;
+    type<NewT>(defaultValue?: T | NewT): TypeDefType<T | NewT>;
+
+    // NOTE: Defaults aren't that useful, as the type will still require the values on write.
+    //  Defaults are mostly for new fields, so that readers of old types don't have to deal with undefined.
+    //  - And we can't make the fields optional for writers, are this would make readers have to handle
+    //    the field being undefined, and as there are usually more readers than writers, this is even worse.
+    //  - Of course, you can always write `undefined as any` to the field on creation, which won't write to
+    //      it, and will force the default to be used. It's not great, but... it would work, and at least
+    //      if the field is removed entirely you will get a type error (but if the field's default is removed,
+    //      you won't get a type error for the place that writes undefined).
+    number: TypeDefType<T | number> & ((defaultValue: T | number) => TypeDefType<T | number>);
+    string: TypeDefType<T | string> & ((defaultValue: T | string) => TypeDefType<T | string>);
+    boolean: TypeDefType<T | boolean> & ((defaultValue: T | boolean) => TypeDefType<T | boolean>);
+    undefined: TypeDefType<T | undefined> & ((defaultValue: T | undefined) => TypeDefType<T | undefined>);
+    null: TypeDefType<T | null> & ((defaultValue: T | null) => TypeDefType<T | null>);
+
+    // NOTE: By definition, optional values don't have defaults
+    numberOptional: TypeDefType<T | number, true>;
+    stringOptional: TypeDefType<T | string, true>;
+    booleanOptional: TypeDefType<T | boolean, true>;
+    undefinedOptional: TypeDefType<T | undefined, true>;
+    nullOptional: TypeDefType<T | null, true>;
+
+    /** Atomic and optional */
+    optional<NewT>(defaultValue?: T | NewT): TypeDefType<T | NewT, true>;
+
+    /** An object (so not atomic), but optional (so you can delete it).
+     *  NOTE: We automatically create an AliveChecker for optionalObjects when creating a schema. If you don't
+     *      want this, use optionalObjectNoGC.
+     */
+    optionalObject<ObjectT>(object: ObjectT): TypeDefType<TypeDefToT<ObjectT>, true>;
+
+    /** An object (so not atomic), but optional (so you can delete it), without automatic GCing of deleted objects. */
+    optionalObjectNoGC<ObjectT>(object: ObjectT): TypeDefType<TypeDefToT<ObjectT>, true>;
+
+    /** "optionalObject" should usually be used, OR, directly use objects, ex, { a: { value: t.string } }.
+     *      However there are some cases when this is useful.
+     *      - An object (so not atomic)
+     */
+    object<ObjectT>(object: ObjectT): TypeDefType<TypeDefToT<ObjectT>, true>;
+
+    /** IMPORTANT! This allows anyone who passes the allowedToWrite check (as well as normal read permissions
+     *      check), is allow to write arbitrary to ANY values at or under `undoRegion[key]`
+     *      - USED on lookups, as this is what we want to do 99% of the time
+     *      - Makes this an object (so it requires a value otherwise it is undefined). Mostly to simplify
+     *          our implementation, but also... if the user can write any values to it, and so the extra
+     *          safety is a good idea (maybe...)
+    */
+    undoRegion(
+        allowedToWrite: (key: string, path: string[]) => boolean | undefined,
+    ): TypeDefType<T>;
+    /** Same as "undoRegion", but applies to the entire object. For example if you want a user to be
+     *      able to undo a specific object in their state, but nothing else.
+     */
+    undoRegionObject(
+        allowedToWrite: (key: string, path: string[]) => boolean | undefined,
+    ): TypeDefType<T>;
+
+    /** NOTE: GC Delay is extremely useful if deleted keys are stored in another lookup
+     *      with the ability for the user to "see deleted", and then undo deletions.
+     *      If the user adds back the key to the lookup (via undeleteFromLookup),
+     *      the value will no longer be GCed.
+     */
+    gcDelay(gcDelay: number): TypeDefType<T>;
+
+    /** ONLY atomic on write, not on read. Useful for backwards compatibility,
+     *      when we made a type atomic for efficiency, and still have old data that isn't atomic.
+     *      (New writes will be atomic, but reads won't be, so you have to use atomic() on all
+     *      the resulting fields, or check a specific field, etc).
+     */
+    atomicOnlyOnWrite<NewT>(defaultValue?: T | NewT): TypeDefType<T | NewT>;
+    /** Lookups behave as expected with respect to delete, even if the entries are not atomic.
+     *      As in, `delete lookup["a"]` will mean `lookup["a"] === undefined`, even
+     *          if there are nested non-atomic values in the lookup.
+     * 
+     *  NOTE: There is no array. We don't support synchronized arrays. Use an object instead,
+     *      even using numbers as keys if you want (they'll be casted to strings, but at least
+     *      it will add some type safety).
+     *      - Arrays can't work because shifting elements would require updating all keys, which
+     *          is inefficient.
+     *      - You can use Object.keys(), and sorting, with unique keys, to simulate an array.
+     *          - But, this can be slow. If the array is short, just make the entire array atomic instead.
+     * 
+     *  NOTE: We automatically create an AliveChecker for lookups when creating a schema. If you don't
+     *      want this, use lookupNoGC.
+     */
+    lookup<NewT>(
+        schema: NewT,
+    ): TypeDefType<{ [key: string]: TypeDefToT<NewT> }>;
+    lookupNumber<NewT>(
+        schema: NewT,
+    ): TypeDefType<{ [key: number]: TypeDefToT<NewT> }>;
+    lookupEither<NewT>(
+        schema: NewT,
+    ): TypeDefType<{ [key: string | number]: TypeDefToT<NewT> }>;
+
+    /** Hints to the GC system not to collect the nested orphaned values. Required if the key
+     *      is stored somewhere else, giving accessor access to the value.
+     *      - ALSO, skips the special `delete` behavior (as otherwise you couldn't access
+     *          the value), so you have to check if the object is set yourself
+     *          (and the "in" check won't work, as you deleted the value, so... you likely
+     *          need to check a special field, or, just assume it exists?)
+     */
+    lookupNoGC<NewT>(
+        schema: NewT
+    ): TypeDefType<{ [key: string | number]: TypeDefToT<NewT> }>;
+    lookupNumberNoGC<NewT>(
+        schema: NewT
+    ): TypeDefType<{ [key: number]: TypeDefToT<NewT> }>;
+    lookupEitherNoGC<NewT>(
+        schema: NewT
+    ): TypeDefType<{ [key: string | number]: TypeDefToT<NewT> }>;
+
+
+
+    // TODO: Support .union, which just spreads the inputs together, making an object which
+    //      has both values (but the type which still be a union).
+
+    zzz_finalT: T;
+    zzz_optional: Optional;
+};
+
+const typeDefProxyRoot = new Proxy(() => { }, {
+    get(target, prop) {
+        if (typeof prop !== "string") return undefined;
+        if (prop === "state") {
+            return (value: unknown) => value;
+        }
+        let defaultValue: TypeDefValues = {
+            path: [],
+            pathWithCalls: [],
+        };
+        defaultValue.path.push(prop);
+        defaultValue.pathWithCalls.push({ key: prop, callParams: [] });
+        return typeDefProxy(defaultValue);
+    },
+});
+export const t = typeDefProxyRoot as any as TypeDefType;
+
+export type Schema2 = TypeDefObj;
+export type Schema2T<T> = TypeDefToT<T>;
+
+export type SchemaPath = (string | WildCard)[];
+
+const WildCard = Symbol("WildCard");
+type WildCard = typeof WildCard;
+export class Schema2Fncs {
+    public static WildCard = WildCard;
+    public static isAtomic(schema: Schema2, type: "read" | "write", path: string[]): {
+        defaultValue?: unknown;
+    } | undefined {
+        let internalType = typeDefCached(schema);
+        let def = getDefMatch(internalType.defs, path);
+        if (def && !def.isNotAtomic) {
+            if (type === "read" && def.atomicOnlyOnWrite) {
+                return undefined;
+            }
+            return { defaultValue: def.defaultValue, };
+        }
+        return undefined;
+    }
+    public static isObject(schema: Schema2, path: string[]): boolean {
+        let internalType = typeDefCached(schema);
+        let def = getDefMatch(internalType.defs, path);
+        return !!def?.isObject;
+    }
+    public static getKeys(schema: Schema2, path: string[]): string[] | undefined {
+        let internalType = typeDefCached(schema);
+        let childValues = internalType.defs.filter(def => isDefKeyMatch(def.path, path));
+        if (childValues.length > 0) {
+            let keys = childValues.map(x => x.path[path.length]);
+            // If any are a wildcard, it means we have a lookup, so they need to
+            //  synchronize the keys (they aren't constant).
+            if (keys.some(x => x === WildCard)) return undefined;
+            return Array.from(new Set(keys as string[]));
+        }
+
+        return undefined;
+    }
+    public static getPaths(schema: Schema2): SchemaPath[] {
+        return typeDefCached(schema).paths;
+    }
+    public static getGCObjects(schema: Schema2): {
+        path: SchemaPath;
+        gcDelay?: number;
+    }[] {
+        return typeDefCached(schema).gcObjects;
+    }
+
+    public static getAllUndoChecks(schema: Schema2): {
+        path: SchemaPath;
+        undoChecks: ((key: string, path: string[]) => boolean | undefined)[];
+    }[] {
+        let defs = typeDefCached(schema).defs;
+        return defs.map(def => {
+            if (!def.undoChecks) return undefined;
+            return {
+                path: def.path,
+                undoChecks: def.undoChecks,
+            };
+        }).filter(isDefined);
+    }
+}
+
+
+
+// #region Implementation
+
+type EraseEmptyObject<T> = T extends Record<string, never> ? unknown : T;
+
+/*
+    Super annoying type code:
+        Objects with zzz_finalT are treated as leaf nodes and resolved to their final type.
+        Objects with zzz_optional: true are made optional in the resulting type.
+        Other objects are recursively resolved.
+*/
+type TypeDefToT<T> = T extends { zzz_finalT: infer X } ? X : (
+    //{ [K in keyof T]: TypeDefToT<T[K]> }
+    EraseEmptyObject<{ [K in keyof T as T[K] extends { zzz_optional: true } ? never : K]: TypeDefToT<T[K]> }>
+    & EraseEmptyObject<{ [K in keyof T as T[K] extends { zzz_optional: true } ? K : never]?: TypeDefToT<T[K]> }>
+);
+
+type TypeDefValues = {
+    path: string[];
+    pathWithCalls: { key: string; callParams: unknown[] }[];
+};
+const getProxyTypeDefs = Symbol("getProxyTypeDefs");
+function typeDefProxy(typeDef: TypeDefValues) {
+    const proxy = new Proxy(() => { }, {
+        get(target, prop): any {
+            if (prop === getProxyTypeDefs) return typeDef;
+            if (typeof prop !== "string") return undefined;
+            typeDef.path.push(prop);
+            typeDef.pathWithCalls.push({ key: prop, callParams: [] });
+            return proxy;
+        },
+        apply(target, thisArg, args): any {
+            typeDef.pathWithCalls[typeDef.pathWithCalls.length - 1].callParams = args;
+            return proxy;
+        }
+    });
+    return proxy;
+}
+
+
+type InternalTypeDef = {
+    // NOTE: We don't store primitives, because, 1, we don't need to, and 2, because
+    //  they could be added with the .type<number>() call, at which point we can't track them.
+    path: SchemaPath;
+    atomicOnlyOnWrite?: boolean;
+
+    isObject?: boolean;
+    isObjectGC?: boolean;
+
+    isNotAtomic?: boolean;
+
+    gcDelay?: number;
+
+    defaultValue?: unknown;
+
+    undoChecks?: ((key: string, path: string[]) => boolean | undefined)[];
+};
+
+
+type TypeDefObj = TypeDefType<any> | {
+    [key: string]: TypeDefObj;
+}
+function typeDefTypeToInternalType(
+    typeDef: TypeDefValues,
+    path: SchemaPath = [],
+    initialValues?: Partial<InternalTypeDef>
+): InternalTypeDef[] {
+    let rootResult: InternalTypeDef = { path, ...initialValues };
+    // NOTE: By default functions cause atomic behavior ("atomic", "type", etc), and don't need special handler
+    //      Most of the overloads are for purely type behavior, and not runtime behavior (or just
+    //      for nice aliases, so it is more clear what the functions do).
+    if (typeDef.path.includes("atomicOnlyOnWrite")) {
+        rootResult.atomicOnlyOnWrite = true;
+    }
+    let isLookup = false;
+    let isLookupGC = false;
+    if (typeDef.path.includes("lookup") || typeDef.path.includes("lookupNumber") || typeDef.path.includes("lookupEither")) {
+        isLookup = true;
+        isLookupGC = true;
+    }
+    if (typeDef.path.includes("lookupNoGC") || typeDef.path.includes("lookupNumberNoGC") || typeDef.path.includes("lookupEitherNoGC")) {
+        isLookup = true;
+        isLookupGC = false;
+    }
+
+    let isObject = false;
+    let isObjectGC = false;
+    if (typeDef.path.includes("optionalObject")) {
+        isObject = true;
+        isObjectGC = true;
+    }
+    if (typeDef.path.includes("optionalObjectNoGC") || typeDef.path.includes("object")) {
+        isObject = true;
+        isObjectGC = false;
+    }
+
+    let undoRegions = typeDef.pathWithCalls.filter(x => x.key === "undoRegionObject");
+    for (let undoRegion of undoRegions) {
+        let allowedToWrite = undoRegion.callParams[0] as (key: string, path: string[]) => boolean | undefined;
+        rootResult.undoChecks = rootResult.undoChecks || [];
+        rootResult.undoChecks.push(allowedToWrite);
+    }
+
+    let results: InternalTypeDef[] = [rootResult];
+    if (isLookup || isObject) {
+        rootResult.isNotAtomic = true;
+
+        let callArgs: unknown;
+        for (let part of typeDef.pathWithCalls) {
+            if (
+                part.key.startsWith("lookup")
+                || part.key === "optionalObject" || part.key === "optionalObjectNoGC" || part.key === "object"
+            ) {
+                callArgs = part.callParams[0];
+            }
+        }
+
+        let nestedValues: Partial<InternalTypeDef> = {
+        };
+        nestedValues.isObject = isObject;
+        // NOTE: Gets reset if the nestedValues are used with a primitive
+        nestedValues.isNotAtomic = true;
+        nestedValues.isObjectGC = isObjectGC || isLookupGC;
+        nestedValues.gcDelay = Number(typeDef.pathWithCalls.find(x => x.key === "gcDelay")?.callParams?.[0]) || undefined;
+
+        if (isLookup) {
+            let undoRegions = typeDef.pathWithCalls.filter(x => x.key === "undoRegion");
+            for (let undoRegion of undoRegions) {
+                let allowedToWrite = undoRegion.callParams[0] as (key: string, path: string[]) => boolean | undefined;
+                nestedValues.undoChecks = nestedValues.undoChecks || [];
+                nestedValues.undoChecks.push(allowedToWrite);
+            }
+        }
+
+        // Lookups are basically objects, except they end with a wildcard
+        let nestedPath = isLookup ? path.concat(WildCard) : path;
+
+        let directTypeDef = getTypeDefValues(callArgs as any);
+        results.push(...typeDefTypeToInternalType(
+            directTypeDef || { path: [], pathWithCalls: [] },
+            nestedPath,
+            nestedValues
+        ));
+        if (!directTypeDef) {
+            results.push(...typeDefToInternalType(callArgs as any, nestedPath));
+        }
+    } else {
+        if (typeDef.path.length > 0) {
+            rootResult.isNotAtomic = false;
+        }
+        let params = typeDef.pathWithCalls;
+        let baseDefault: unknown = undefined;
+        if (typeDef.path.includes("number")) {
+            baseDefault = 0;
+        } else if (typeDef.path.includes("string")) {
+            baseDefault = "";
+        } else if (typeDef.path.includes("boolean")) {
+            baseDefault = false;
+        }
+        rootResult.defaultValue = recursiveFreeze(params[params.length - 1]?.callParams?.[0] ?? baseDefault);
+    }
+    return results;
+}
+function getTypeDefValues(typeDef: TypeDefObj) {
+    let typeDefType: TypeDefValues | undefined = (typeof typeDef === "function" && typeDef[getProxyTypeDefs] || undefined);
+    return typeDefType;
+}
+function typeDefToInternalType(typeDef: TypeDefObj, path: SchemaPath = []): InternalTypeDef[] {
+    let typeDefType = getTypeDefValues(typeDef);
+    if (typeDefType) {
+        return typeDefTypeToInternalType(typeDefType, path);
+    }
+    if (!canHaveChildren(typeDef)) return [];
+    let results: InternalTypeDef[][] = [];
+    for (let [key, value] of Object.entries(typeDef)) {
+        results.push(typeDefToInternalType(value, path.concat(key)));
+    }
+    return results.flat();
+}
+const typeDefCached = cache((typeDef: TypeDefObj) => {
+    let defs = typeDefToInternalType(typeDef);
+    let gcObjects = defs.filter(def => def.isObjectGC);
+    // NOTE: If the lookup only has primitives, then it doesn't need to be GCed
+    gcObjects = gcObjects.filter(def => {
+        let nonPrimitivePath = def.path.concat(WildCard);
+        return defs.some(x => isMatch(nonPrimitivePath, x.path));
+    });
+    return {
+        defs,
+        paths: defs.map(x => x.path),
+        gcObjects: gcObjects.map(x => ({ path: x.path, gcDelay: x.gcDelay })),
+    };
+});
+function isMatch(defPath: SchemaPath, path: SchemaPath) {
+    if (path.length !== defPath.length) return false;
+    for (let i = 0; i < path.length; i++) {
+        if (defPath[i] === WildCard) continue;
+        if (path[i] === WildCard) continue;
+        if (path[i] === defPath[i]) continue;
+        return false;
+    }
+    return true;
+}
+function getDefMatch(defs: InternalTypeDef[], path: string[]) {
+    for (let def of defs) {
+        if (isMatch(def.path, path)) return def;
+    }
+    return undefined;
+}
+function isDefKeyMatch(defPath: SchemaPath, path: string[]) {
+    if (path.length + 1 > defPath.length) return false;
+    for (let i = 0; i < path.length; i++) {
+        if (defPath[i] === WildCard) continue;
+        if (path[i] === defPath[i]) continue;
+        return false;
+    }
+    return true;
+}
+function isDefParentOrEqualMatch(defPath: SchemaPath, path: string[]) {
+    if (defPath.length > path.length) return false;
+    for (let i = 0; i < defPath.length; i++) {
+        if (defPath[i] === WildCard) continue;
+        if (path[i] === defPath[i]) continue;
+        return false;
+    }
+    return true;
+}
+
+// let x = t.lookup({
+//     name: t.string,
+//     num: t.number,
+//     defaultedNum: t.number(1),
+//     obj: t.atomic<{ key: string; value: number }>(),
+//     objWriteOnly: t.atomicOnlyOnWrite<{ key: string; value: number }>(),
+//     justObj: {
+//         nestedLookup: t.lookupNoGC({
+//             k: t.number,
+//             str: t.string,
+//             and: t.boolean,
+//             more: t.atomic<{ key: string; value: number }>(),
+//             directLookup2: t.lookup(t.number),
+//         }),
+//         directLookup: t.lookup(t.number),
+//         gcedLookup: t.lookup({
+//             key: t.string,
+//             value: t.number,
+//         }),
+//     }
+// });
+// console.log(typeDefCached(x));
+
+// console.log("name", Schema2Fncs.isAtomic(x, "read", ["x", "name"]));
+// console.log("k", Schema2Fncs.isAtomic(x, "read", ["x", "justObj", "nestedLookup", "afsd", "k"]));
+// console.log("j", Schema2Fncs.isAtomic(x, "read", ["x", "justObj", "nestedLookup", "afd", "j"]));
+// console.log("objWriteOnly read", Schema2Fncs.isAtomic(x, "read", ["x", "objWriteOnly"]));
+// console.log("objWriteOnly write", Schema2Fncs.isAtomic(x, "write", ["x", "objWriteOnly"]));
+// console.log("lookup", Schema2Fncs.isAtomic(x, "read", ["x"]));
+
+//console.log("isLookup lookup", Schema2Fncs.isLookup(x, []));
+//console.log("isLookup lookup.obj", Schema2Fncs.isLookup(x, ["x", "obj"]));
+//console.log("isLookup lookup.justObj.directLookup", Schema2Fncs.isLookup(x, ["x", "justObj", "directLookup"]));
+
+// console.log("getKeys root", Schema2Fncs.getKeys(x, []));
+// console.log("getKeys lookup", Schema2Fncs.getKeys(x, ["x"]));
+// console.log("getKeys lookup.justObj.nestedLookup", Schema2Fncs.getKeys(x, ["x", "justObj", "nestedLookup", "x"]));
+// console.log("getKeys lookup.justObj.directLookup", Schema2Fncs.getKeys(x, ["x", "justObj", "directLookup", "x"]));
+// console.log("getKeys lookup.justObj.directLookup", Schema2Fncs.getKeys(x, ["x", "justObj", "directLookup"]));
+
+// console.log("getGCLookups", Schema2Fncs.getGCLookups(x));
+
+// #endregion

package/src/3-path-functions/PathFunctionHelpers.ts

@@ -0,0 +1,129 @@
+import { getOwnMachineId } from "../-a-auth/certs";
+import { atomicObjectWrite, proxyWatcher } from "../2-proxy/PathValueProxyWatcher";
+import { pathValueCommitter } from "../0-path-value-core/PathValueController";
+import { getNextTime } from "../0-path-value-core/pathValueCore";
+import { FunctionSpec, functionSchema, CallSpec } from "./PathFunctionRunner";
+import { logErrors } from "../errors";
+import { FunctionMetadata } from "./syncSchema";
+import debugbreak from "debugbreak";
+import cborx from "cbor-x";
+import { lazy } from "socket-function/src/caching";
+import { secureRandom } from "../misc/random";
+import { onCallPredict } from "../4-querysub/QuerysubController";
+const cborxInstance = lazy(() => new cborx.Encoder({ structuredClone: true }));
+
+export async function deployFunction(spec: FunctionSpec) {
+    const { DomainName, ModuleId, FunctionId } = spec;
+    await proxyWatcher.commitFunction({
+        canWrite: true,
+        watchFunction: function writeTest() {
+            functionSchema()[DomainName].PathFunctionRunner[ModuleId].Sources[FunctionId] = atomicObjectWrite(spec);
+        },
+    });
+}
+export async function undeployFunction(spec: FunctionSpec) {
+    const { DomainName, ModuleId, FunctionId } = spec;
+    await proxyWatcher.commitFunction({
+        canWrite: true,
+        watchFunction: function writeTest() {
+            functionSchema()[DomainName].PathFunctionRunner[ModuleId].Sources[FunctionId] = undefined;
+        },
+    });
+}
+
+export const writeCall = {
+    value: async (callSpec: CallSpec, metadata: FunctionMetadata) => {
+        let domainName = callSpec.DomainName;
+        let moduleId = callSpec.ModuleId;
+        let callId = callSpec.CallId;
+        proxyWatcher.writeOnly({
+            canWrite: true,
+            eventWrite: true,
+            doNotStoreWritesAsPredictions: true,
+            // NOTE: We write the call in the present, it is callSpec.runAtTime that is in the past. No one cares
+            //  when the call was added, only when it wants to run at.
+            watchFunction: function writeCall() {
+                functionSchema()[domainName].PathFunctionRunner[moduleId].Calls[callId] = atomicObjectWrite(callSpec);
+            },
+        });
+        await pathValueCommitter.waitForValuesToCommit();
+    }
+};
+
+export async function runCall(call: CallSpec, metadata: FunctionMetadata) {
+    return await writeCall.value(call, metadata);
+}
+
+interface CallInterceptor<T> {
+    onCall: (call: CallSpec, metadata: FunctionMetadata) => void;
+    code: () => T;
+}
+
+let curInterceptor: CallInterceptor<unknown> | undefined = undefined;
+export function interceptCalls<T>(
+    interceptor: CallInterceptor<T>
+) {
+    let prev = curInterceptor;
+    curInterceptor = interceptor;
+    try {
+        return interceptor.code();
+    } finally {
+        curInterceptor = prev;
+    }
+}
+
+export function writeFunctionCall(config: {
+    domainName: string;
+    moduleId: string;
+    functionId: string;
+    args: unknown[];
+    metadata: FunctionMetadata,
+}) {
+    let { domainName, moduleId, functionId, args, metadata } = config;
+
+    let now = Date.now();
+    // IMPORTANT! CallId MUST be secure, otherwise other users can guess it, and read our calls
+    //  (which could contain secret data).
+    //  secureRandom() is pretty good... combined with date it should be hard enough to guess
+    //      - date adds about 10 bits of randomness (an attacker might be able to guess within a second
+    //          the time a specific call was made)
+    //      - secureRandom adds at more 64 bits of randomess, but in reality it is probably less
+    //      - ALSO, if they don't guess the call within the event remove window... it will be be deleted,
+    //          which gives them about a minute to guess it...
+    let callId = now + "_" + secureRandom();
+    let argsEncoded = encodeArgs(args);
+    let callSpec: CallSpec = {
+        argsEncoded,
+        ModuleId: moduleId,
+        CallId: callId,
+        DomainName: domainName,
+        FunctionId: functionId,
+        runAtTime: getNextTime(),
+        callerMachineId: getOwnMachineId(),
+        // Will be updated by Querysub to be correct (unless we are directly writing, then...
+        //  this is fine).
+        callerIP: "127.0.0.1",
+    };
+
+    if (curInterceptor) {
+        curInterceptor.onCall(callSpec, metadata);
+    } else {
+        logErrors(writeCall.value(callSpec, metadata));
+    }
+
+    return callSpec;
+}
+
+export function parseArgs(call: CallSpec) {
+    return cborxInstance().decode(Buffer.from(call.argsEncoded, "base64"));
+}
+
+export function encodeArgs(args: unknown[]) {
+    // NOTE: This will throw if we try to encode a function. This is probably okay.
+    //  - We use this to prevent accidentally encoding VirtualDOM to the database / objects
+    //      with functions.
+    //  - If this becomes an issue, we might catch the error, and strip functions if we
+    //      have found them.
+    //      - Or... is there are a way to tell cborx to strip the functions?
+    return cborxInstance().encode(args).toString("base64");
+}