@reboot-dev/reboot 0.23.0 → 0.25.0

package/index.d.ts

@@ -1,8 +1,9 @@
 import { errors_pb, IdempotencyOptions, protobuf_es, ScheduleOptions } from "@reboot-dev/reboot-api";
+import express from "express";
 import * as reboot_native from "./reboot_native.cjs";
 export { reboot_native };
 export * from "./utils/index.js";
-type ApplicationConfig = {
+type ApplicationRevision = {
     applicationId: string;
 };
 export declare class Reboot {
@@ -16,10 +17,9 @@ export declare class Reboot {
     }): ExternalContext;
     start(): Promise<void>;
     stop(): Promise<void>;
-    up(servicers: any, options?: {
-        tokenVerifier?: TokenVerifier;
+    up(application: Application, options?: {
         localEnvoy?: boolean;
-    }): Promise<ApplicationConfig>;
+    }): Promise<ApplicationRevision>;
     down(): Promise<void>;
     url(): string;
 }
@@ -48,8 +48,10 @@ export declare class Context {
     static fromNativeExternal(external: any, kind: string, aborted: Promise<void>): ReaderContext | WriterContext | TransactionContext | WorkflowContext;
     get __external(): any;
     get auth(): Auth | null;
-    get stateId(): any;
-    get iteration(): any;
+    get stateId(): string;
+    get iteration(): number;
+    get cookie(): string;
+    get appInternal(): boolean;
     generateIdempotentStateId(stateType: string, serviceName: string, method: string, idempotency: IdempotencyOptions): Promise<any>;
 }
 export declare class ReaderContext extends Context {
@@ -117,8 +119,8 @@ export declare abstract class TokenVerifier {
      * Returns:
      *   `Auth` information if the token is valid, null otherwise.
      */
-    abstract verifyToken(context: ReaderContext, token: string): Promise<Auth | null>;
-    _verifyToken(context: ReaderContext, token: string): Promise<Uint8Array | null>;
+    abstract verifyToken(context: ReaderContext, token?: string): Promise<Auth | null>;
+    _verifyToken(context: ReaderContext, token?: string): Promise<Uint8Array | null>;
 }
 export type AuthorizerDecision = errors_pb.Unauthenticated | errors_pb.PermissionDenied | errors_pb.Ok;
 /**
@@ -144,12 +146,38 @@ export declare abstract class Authorizer<StateType, RequestTypes> {
     abstract authorize(methodName: string, context: ReaderContext, state?: StateType, request?: RequestTypes): Promise<AuthorizerDecision>;
     _authorize?: (methodName: string, context: ReaderContext, bytesState?: Uint8Array, bytesRequest?: Uint8Array) => Promise<Uint8Array>;
 }
-/**
- * An authorizer that allows all requests, as long as the caller is authenticated.
- */
-export declare class AllowAllIfAuthenticated extends Authorizer<protobuf_es.Message, protobuf_es.Message> {
-    authorize(methodName: string, context: ReaderContext, state?: protobuf_es.Message, request?: protobuf_es.Message): Promise<AuthorizerDecision>;
+export type AuthorizerCallable<StateType, RequestType> = (args: {
+    context: ReaderContext;
+    state?: StateType;
+    request?: RequestType;
+}) => Promise<AuthorizerDecision> | AuthorizerDecision;
+export declare abstract class AuthorizerRule<StateType, RequestType> {
+    abstract execute(args: {
+        context: ReaderContext;
+        state?: StateType;
+        request?: RequestType;
+    }): Promise<AuthorizerDecision>;
 }
+export declare function deny(): AuthorizerRule<protobuf_es.Message, protobuf_es.Message>;
+export declare function allow(): AuthorizerRule<protobuf_es.Message, protobuf_es.Message>;
+export declare function allowIf<StateType, RequestType>(args: {
+    all: AuthorizerCallable<StateType, RequestType>[];
+    any?: never;
+}): AuthorizerRule<StateType, RequestType>;
+export declare function allowIf<StateType, RequestType>(args: {
+    all?: never;
+    any: AuthorizerCallable<StateType, RequestType>[];
+}): AuthorizerRule<StateType, RequestType>;
+export declare function hasVerifiedToken({ context, }: {
+    context: ReaderContext;
+    state?: protobuf_es.Message;
+    request?: protobuf_es.Message;
+}): errors_pb.Unauthenticated | errors_pb.Ok;
+export declare function isAppInternal({ context, }: {
+    context: ReaderContext;
+    state?: protobuf_es.Message;
+    request?: protobuf_es.Message;
+}): errors_pb.Unauthenticated | errors_pb.Ok;
 export declare class Application {
     #private;
     constructor({ servicers, initialize, initializeBearerToken, tokenVerifier, }: {
@@ -158,7 +186,30 @@ export declare class Application {
         initializeBearerToken?: string;
         tokenVerifier?: TokenVerifier;
     });
+    get servicers(): ServicerFactory[];
+    get tokenVerifier(): TokenVerifier;
+    get http(): Application.Http;
     run(): Promise<any>;
+    get __external(): any;
+}
+export declare namespace Application {
+    namespace Http {
+        type Path = string | RegExp | (string | RegExp)[];
+        type ReqResHandler = (context: ExternalContext, req: express.Request, res: express.Response) => any;
+        type ReqResNextHandler = (context: ExternalContext, req: express.Request, res: express.Response, next: express.NextFunction) => any;
+        type ErrReqResNextHandler = (context: ExternalContext, err: any, req: express.Request, res: express.Response, next: express.NextFunction) => any;
+        type Handler = ReqResHandler | ReqResNextHandler | ErrReqResNextHandler;
+    }
+    class Http {
+        #private;
+        constructor(express: express.Application, createExternalContext: (args: {
+            name: string;
+            bearerToken?: string;
+        }) => Promise<ExternalContext>);
+        private add;
+        get(path: Http.Path, ...handlers: Http.Handler[]): void;
+        post(path: Http.Path, ...handlers: Http.Handler[]): void;
+    }
 }
 /**
  * @deprecated testWithReboot is deprecated in favor of the manual start of Reboot in the test setup.
@@ -171,20 +222,44 @@ export declare class Loop {
 export declare function retry_reactively_until(context: WorkflowContext, condition: () => Promise<boolean>): Promise<void>;
 export declare function retry_reactively_until<T>(context: WorkflowContext, condition: () => Promise<false | Exclude<T, boolean>>): Promise<Exclude<T, boolean>>;
 export declare function atMostOnce(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<void>, options?: {
-    parse: undefined;
+    stringify?: undefined;
+    parse?: undefined;
+    validate?: undefined;
 }): Promise<void>;
 export declare function atMostOnce<T>(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<T>, options: {
-    parse: (value: any) => T;
+    stringify?: (result: T) => string;
+    parse: (value: string) => T;
+    validate?: undefined;
+} | {
+    stringify?: (result: T) => string;
+    parse?: undefined;
+    validate: (result: T) => boolean;
 }): Promise<T>;
 export declare function atLeastOnce(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<void>, options?: {
-    parse: undefined;
+    stringify?: undefined;
+    parse?: undefined;
+    validate?: undefined;
 }): Promise<void>;
 export declare function atLeastOnce<T>(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<T>, options: {
-    parse: (value: any) => T;
+    stringify?: (result: T) => string;
+    parse: (value: string) => T;
+    validate?: undefined;
+} | {
+    stringify?: (result: T) => string;
+    parse?: undefined;
+    validate: (result: T) => boolean;
 }): Promise<T>;
 export declare function until(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<boolean>, options?: {
-    parse: undefined;
+    stringify?: undefined;
+    parse?: undefined;
+    validate?: undefined;
 }): Promise<void>;
 export declare function until<T>(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<false | Exclude<T, boolean>>, options: {
-    parse: (value: any) => T;
+    stringify?: (result: T) => string;
+    parse: (value: string) => T;
+    validate?: undefined;
+} | {
+    stringify?: (result: T) => string;
+    parse?: undefined;
+    validate: (result: T) => boolean;
 }): Promise<Exclude<T, boolean>>;

package/index.js

@@ -9,12 +9,13 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _Reboot_external, _ExternalContext_external, _a, _Context_external, _Context_isInternalConstructing, _ReaderContext_kind, _WriterContext_kind, _TransactionContext_kind, _WorkflowContext_kind, _Application_external;
+var _Reboot_external, _ExternalContext_external, _a, _Context_external, _Context_isInternalConstructing, _ReaderContext_kind, _WriterContext_kind, _TransactionContext_kind, _WorkflowContext_kind, _Application_servicers, _Application_tokenVerifier, _Application_express, _Application_http, _Application_servers, _Application_createExternalContext, _Application_external;
 import { auth_pb, errors_pb, protobuf_es, } from "@reboot-dev/reboot-api";
 import { strict as assert } from "assert";
+import express from "express";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { fork } from "node:child_process";
 import { test } from "node:test";
-import { AsyncLocalStorage } from "node:async_hooks";
 import * as reboot_native from "./reboot_native.cjs";
 import { ensurePythonVenv } from "./venv.js";
 export { reboot_native };
@@ -49,6 +50,12 @@ if (process != null) {
         // exits due to a SIGINT will exit with a code of 130.
         checkIfNoOtherListenersAndIfSoExit("SIGINT", 130);
     });
+    process.on("unhandledRejection", (reason, promise) => {
+        // We install a slightly quieter unhandled-rejection handler because the
+        // native portion of Reboot renders useful error messages before raising.
+        console.error("Exiting:", reason);
+        checkIfNoOtherListenersAndIfSoExit("unhandledRejection", 1);
+    });
 }
 export class Reboot {
     constructor() {
@@ -78,10 +85,10 @@ export class Reboot {
             startedInstances.splice(indexOfTimestamp, 1);
         }
     }
-    async up(servicers, options) {
+    async up(application, options) {
         // TODO(benh): determine module and file name so that we can
         // namespace if we have more than one implementation of servicers.
-        return await reboot_native.Reboot_up(__classPrivateFieldGet(this, _Reboot_external, "f"), servicers, options?.tokenVerifier, options?.localEnvoy);
+        return await reboot_native.Reboot_up(__classPrivateFieldGet(this, _Reboot_external, "f"), application.__external, options?.localEnvoy);
     }
     async down() {
         await reboot_native.Reboot_down(__classPrivateFieldGet(this, _Reboot_external, "f"));
@@ -169,6 +176,12 @@ export class Context {
     get iteration() {
         return reboot_native.Context_iteration(__classPrivateFieldGet(this, _Context_external, "f"));
     }
+    get cookie() {
+        return reboot_native.Context_cookie(__classPrivateFieldGet(this, _Context_external, "f"));
+    }
+    get appInternal() {
+        return reboot_native.Context_appInternal(__classPrivateFieldGet(this, _Context_external, "f"));
+    }
     async generateIdempotentStateId(stateType, serviceName, method, idempotency) {
         return reboot_native.Context_generateIdempotentStateId(__classPrivateFieldGet(this, _Context_external, "f"), stateType, serviceName, method, idempotency);
     }
@@ -315,21 +328,173 @@ export class TokenVerifier {
  */
 export class Authorizer {
 }
-/**
- * An authorizer that allows all requests, as long as the caller is authenticated.
- */
-export class AllowAllIfAuthenticated extends Authorizer {
-    async authorize(methodName, context, state, request) {
-        if (!context.auth) {
-            return new errors_pb.Unauthenticated();
+export class AuthorizerRule {
+}
+export function deny() {
+    return new (class extends AuthorizerRule {
+        async execute(args) {
+            return new errors_pb.PermissionDenied();
+        }
+    })();
+}
+export function allow() {
+    return new (class extends AuthorizerRule {
+        async execute(args) {
+            return new errors_pb.Ok();
         }
+    })();
+}
+export function allowIf(args) {
+    const all = args.all;
+    const any = args.any;
+    if ((all === undefined && any === undefined) ||
+        (all !== undefined && any !== undefined)) {
+        throw new Error("Exactly one of `all` or `any` must be passed");
+    }
+    const callables = all ?? any;
+    return new (class extends AuthorizerRule {
+        async execute({ context, state, request }) {
+            // NOTE: we invoke each authorizer callable **one at a time**
+            // instead of concurrently so that:
+            //
+            // (1) We support dependency semantics for `all`, i.e.,
+            //     callable's later can assume earlier callables did not
+            //     return `Unauthenticated` or `PermissionDenied`.
+            //
+            // (2) We support short-circuiting`, i.e., cheaper authorizer
+            //     callables can be listed first so more expensive ones
+            //     aren't executed unless necessary.
+            //
+            // PLEASE KEEP SEMANTICS IN SYNC WITH PYTHON.
+            // Remember if we had any `PermissionDenied` for `any` so that
+            // we return that instead of `Unauthenticated`.
+            let denied = false;
+            for (const callable of callables) {
+                const decision = await callable({ context, state, request });
+                if (decision instanceof errors_pb.Ok) {
+                    if (all !== undefined) {
+                        // All callables must return `Ok`, keep checking.
+                        continue;
+                    }
+                    else {
+                        // Only needed one `Ok` and we got it, short-circuit.
+                        return decision;
+                    }
+                }
+                else if (decision instanceof errors_pb.Unauthenticated) {
+                    if (all !== undefined) {
+                        // All callables must return `Ok`, short-circuit.
+                        return decision;
+                    }
+                    else {
+                        // Just need one `Ok`, keep checking.
+                        continue;
+                    }
+                }
+                else if (decision instanceof errors_pb.PermissionDenied) {
+                    if (all !== undefined) {
+                        // All callables must return `Ok`, short-circuit.
+                        return decision;
+                    }
+                    else {
+                        // Remember that we got at least one `PermissionDenied` so
+                        // we can return it later.
+                        denied = true;
+                        // Only need one `Ok`, keep checking.
+                        continue;
+                    }
+                }
+            }
+            // If this was `all`, then they must have all been `Ok`!
+            if (all !== undefined) {
+                // TODO: assert !denied
+                return new errors_pb.Ok();
+            }
+            // Must be `any`, check if we got a `PermissionDenied` otherwise
+            // return `Unauthenticated`.
+            if (denied) {
+                return new errors_pb.PermissionDenied();
+            }
+            else {
+                return new errors_pb.Unauthenticated();
+            }
+        }
+    })();
+}
+export function hasVerifiedToken({ context, }) {
+    if (!context.auth) {
+        return new errors_pb.Unauthenticated();
+    }
+    return new errors_pb.Ok();
+}
+export function isAppInternal({ context, }) {
+    if (context.appInternal) {
         return new errors_pb.Ok();
     }
+    return new errors_pb.Unauthenticated();
 }
 export class Application {
     constructor({ servicers, initialize, initializeBearerToken, tokenVerifier, }) {
+        _Application_servicers.set(this, void 0);
+        _Application_tokenVerifier.set(this, void 0);
+        _Application_express.set(this, void 0);
+        _Application_http.set(this, void 0);
+        _Application_servers.set(this, void 0);
+        _Application_createExternalContext.set(this, void 0);
         _Application_external.set(this, void 0);
-        __classPrivateFieldSet(this, _Application_external, reboot_native.Application_constructor(ExternalContext.fromNativeExternal, servicers, async (context) => {
+        __classPrivateFieldSet(this, _Application_servicers, servicers, "f");
+        __classPrivateFieldSet(this, _Application_tokenVerifier, tokenVerifier, "f");
+        __classPrivateFieldSet(this, _Application_express, express(), "f");
+        // We assume that our users will want these middleware.
+        // TODO: expose `.use()` to allow users to add their own middleware.
+        __classPrivateFieldGet(this, _Application_express, "f").use(express.json());
+        __classPrivateFieldGet(this, _Application_express, "f").use(express.urlencoded({ extended: true }));
+        __classPrivateFieldSet(this, _Application_http, new Application.Http(__classPrivateFieldGet(this, _Application_express, "f"), async (args) => {
+            return await __classPrivateFieldGet(this, _Application_createExternalContext, "f").call(this, args);
+        }), "f");
+        __classPrivateFieldSet(this, _Application_servers, new Map(), "f");
+        __classPrivateFieldSet(this, _Application_external, reboot_native.Application_constructor(ExternalContext.fromNativeExternal, servicers, {
+            start: async (consensusId, port, createExternalContext) => {
+                // Store `createExternalContext` function before listening
+                // so we don't attempt to serve any traffic and try and use
+                // an `undefined` function.
+                __classPrivateFieldSet(this, _Application_createExternalContext, createExternalContext, "f");
+                let server;
+                [server, port] = await new Promise((resolve, reject) => {
+                    const server = __classPrivateFieldGet(this, _Application_express, "f").listen(port ?? 0, (error) => {
+                        if (error) {
+                            reject(error);
+                        }
+                        else {
+                            // We requested a port so we should have an
+                            // `AddressInfo` not a string representing a file
+                            // descriptor path for a pipe or socket, etc.
+                            const address = server.address();
+                            assert(typeof address !== "string");
+                            resolve([server, address.port]);
+                        }
+                    });
+                });
+                __classPrivateFieldGet(this, _Application_servers, "f").set(consensusId, server);
+                return port;
+            },
+            stop: async (consensusId) => {
+                const server = __classPrivateFieldGet(this, _Application_servers, "f").get(consensusId);
+                if (server !== undefined) {
+                    await new Promise((resolve, reject) => {
+                        server.close((err) => {
+                            if (err) {
+                                reject(err);
+                            }
+                            else {
+                                resolve();
+                            }
+                        });
+                    });
+                    __classPrivateFieldGet(this, _Application_servers, "f").delete(consensusId);
+                }
+            },
+        }, async (context) => {
             if (initialize !== undefined) {
                 try {
                     await initialize(context);
@@ -345,11 +510,98 @@ export class Application {
             }
         }, initializeBearerToken, tokenVerifier), "f");
     }
+    get servicers() {
+        return __classPrivateFieldGet(this, _Application_servicers, "f");
+    }
+    get tokenVerifier() {
+        return __classPrivateFieldGet(this, _Application_tokenVerifier, "f");
+    }
+    get http() {
+        return __classPrivateFieldGet(this, _Application_http, "f");
+    }
     async run() {
         return await reboot_native.Application_run(__classPrivateFieldGet(this, _Application_external, "f"));
     }
+    get __external() {
+        return __classPrivateFieldGet(this, _Application_external, "f");
+    }
 }
-_Application_external = new WeakMap();
+_Application_servicers = new WeakMap(), _Application_tokenVerifier = new WeakMap(), _Application_express = new WeakMap(), _Application_http = new WeakMap(), _Application_servers = new WeakMap(), _Application_createExternalContext = new WeakMap(), _Application_external = new WeakMap();
+(function (Application) {
+    var _Http_express, _Http_createExternalContext;
+    class Http {
+        constructor(express, createExternalContext) {
+            _Http_express.set(this, void 0);
+            _Http_createExternalContext.set(this, void 0);
+            __classPrivateFieldSet(this, _Http_express, express, "f");
+            __classPrivateFieldSet(this, _Http_createExternalContext, createExternalContext, "f");
+        }
+        add(method, path, handlers) {
+            const methods = {
+                GET: (path, ...handlers) => __classPrivateFieldGet(this, _Http_express, "f").get(path, ...handlers),
+                POST: (path, ...handlers) => __classPrivateFieldGet(this, _Http_express, "f").post(path, ...handlers),
+            };
+            const createExternalContext = (name, authorization) => {
+                let bearerToken = undefined;
+                if (authorization !== undefined) {
+                    const parts = authorization.split(" ");
+                    if (parts.length === 2 && parts[0].toLowerCase() === "bearer") {
+                        bearerToken = parts[1];
+                    }
+                }
+                return __classPrivateFieldGet(this, _Http_createExternalContext, "f").call(this, {
+                    name,
+                    bearerToken,
+                });
+            };
+            methods[method](path, ...handlers.map((handler) => {
+                // Express allows for three different kinds of handlers, a
+                // "normal" handler that takes two args, `req` and `res`, a
+                // "middlware" handler that takes three args, `req, `res`,
+                // and `next`, and an "error" handler that takes four args
+                // `err`, `req`, `res`, and `next`. To the best of our
+                // understanding they determine what arguments to pass to
+                // handlers based on how many arguments the handler takes,
+                // and so that is exactly what we do below as well, except
+                // accounting for an extra first arg for the
+                // `ExternalContext`.
+                switch (handler.length) {
+                    // (context, req, res) => ...
+                    case 3:
+                        return async (req, res) => {
+                            const context = await createExternalContext(`HTTP ${method} '${req.path}'`, req.header("Authorization"));
+                            // @ts-ignore
+                            handler(context, req, res);
+                        };
+                    // (context, req, res, next) => ...
+                    case 4:
+                        return async (req, res, next) => {
+                            const context = await createExternalContext(`HTTP ${method} '${req.path}'`, req.header("Authorization"));
+                            // @ts-ignore
+                            handler(context, req, res, next);
+                        };
+                    // (context, err, req, res, next) => ...
+                    case 5:
+                        return async (err, req, res, next) => {
+                            const context = await createExternalContext(`HTTP ${method} '${req.path}'`, req.header("Authorization"));
+                            handler(context, err, req, res, next);
+                        };
+                    default:
+                        throw new Error(`HTTP ${method} handler for '${path}' has unexpected ` +
+                            `number of arguments`);
+                }
+            }));
+        }
+        get(path, ...handlers) {
+            this.add("GET", path, handlers);
+        }
+        post(path, ...handlers) {
+            this.add("POST", path, handlers);
+        }
+    }
+    _Http_express = new WeakMap(), _Http_createExternalContext = new WeakMap();
+    Application.Http = Http;
+})(Application || (Application = {}));
 /**
  * @deprecated testWithReboot is deprecated in favor of the manual start of Reboot in the test setup.
  */
@@ -395,43 +647,55 @@ export async function retry_reactively_until(context, condition) {
     });
     return t;
 }
-async function atLeastOrMostOnce(idempotencyAlias, context, callable, options) {
-    let t = undefined;
+async function atLeastOrMostOnce(idempotencyAlias, context, callable, { stringify = JSON.stringify, parse = JSON.parse, validate, atMostOnce, }) {
+    assert(stringify !== undefined);
+    assert(parse !== undefined);
+    assert(atMostOnce !== undefined);
     const result = await reboot_native.atLeastOrMostOnce(context.__external, idempotencyAlias, async () => {
-        t = await callable();
+        const t = await callable();
         if (t !== undefined) {
-            if (options.parse === undefined) {
-                throw new Error("Required 'parse' property in 'options' is undefined");
-            }
-            // NOTE: we've decided not to stringify and parse `t` using
-            // `options.parse` now to avoid the extra overhead, but it
-            // might catch some bugs _before_ anything gets persisted and
-            // users may prefer that tradeoff.
-            return JSON.stringify(t);
+            // NOTE: to differentiate `callable` returning `void` (or
+            // explicitly `undefined`) from `stringify` returning an empty
+            // string we use `{ value: stringify(t) }`.
+            const result = { value: stringify(t) };
+            return JSON.stringify(result);
+        }
+        // Fail early if the developer thinks that they have some value
+        // that they want to validate but we got `undefined`.
+        if (validate !== undefined) {
+            throw new Error("Not expecting `validate` as you are returning `void` (or explicitly `undefined`); did you mean to return a value (or if you want to explicitly return the absence of a value use `null`)");
         }
         // NOTE: using the empty string to represent a `callable`
-        // returning void or explicitly `undefined`.
+        // returning `void` (or explicitly `undefined`).
         return "";
-    }, options.atMostOnce);
-    if (t !== undefined) {
-        return t;
-    }
+    }, atMostOnce);
+    // NOTE: we parse and validate `value` every time, even the first
+    // time, so as to catch bugs where the `value` returned from
+    // `callable` might not parse or be valid. We will have already
+    // persisted `result`, so in the event of a bug the developer will
+    // have to change the idempotency alias so that `callable` is
+    // re-executed. These semantics are the same as Python (although
+    // Python uses the `type` keyword argument instead of the
+    // `parse` and `validate` properties we use here).
     assert(result !== undefined);
     if (result !== "") {
-        if (options.parse === undefined) {
-            throw new Error("Required 'parse' property in 'options' is undefined");
+        const { value } = JSON.parse(result);
+        const t = parse(value);
+        if (parse !== JSON.parse) {
+            if (validate === undefined) {
+                // TODO: link to docs about why this is required, when those docs exist.
+                throw new Error("Missing `validate` property");
+            }
+            else if (!validate(t)) {
+                throw new Error("Failed to validate memoized result");
+            }
         }
-        return options.parse(JSON.parse(result));
-    }
-    assert(result === "");
-    // Let end user decide what they want to do with `undefined` if
-    // they specify `options.parse`.
-    if (options.parse !== undefined) {
-        return options.parse(undefined);
+        return t;
     }
-    // Otherwise `callable` must return void (undefined), fall through.
+    // Otherwise `callable` must have returned void (or explicitly
+    // `undefined`), fall through.
 }
-export async function atMostOnce(idempotencyAlias, context, callable, options = { parse: undefined }) {
+export async function atMostOnce(idempotencyAlias, context, callable, options = { validate: undefined }) {
     try {
         return await atLeastOrMostOnce(idempotencyAlias, context, callable, {
             ...options,
@@ -445,13 +709,13 @@ export async function atMostOnce(idempotencyAlias, context, callable, options =
         throw e;
     }
 }
-export async function atLeastOnce(idempotencyAlias, context, callable, options = { parse: undefined }) {
+export async function atLeastOnce(idempotencyAlias, context, callable, options = { validate: undefined }) {
     return atLeastOrMostOnce(idempotencyAlias, context, callable, {
         ...options,
         atMostOnce: false,
     });
 }
-export async function until(idempotencyAlias, context, callable, options = { parse: undefined }) {
+export async function until(idempotencyAlias, context, callable, options = { validate: undefined }) {
     // TODO(benh): figure out how to not use `as` type assertions here
     // to appease the TypeScript compiler which otherwise isn't happy
     // with passing on these types.

package/package.json

@@ -3,18 +3,19 @@
     "@bufbuild/protobuf": "1.3.2",
     "@bufbuild/protoplugin": "1.3.2",
     "@bufbuild/protoc-gen-es": "1.3.2",
-    "@reboot-dev/reboot-api": "0.23.0",
+    "@reboot-dev/reboot-api": "0.25.0",
     "chalk": "^4.1.2",
     "node-addon-api": "^7.0.0",
     "node-gyp": ">=10.2.0",
     "uuid": "^9.0.1",
     "which-pm-runs": "^1.1.0",
     "extensionless": "^1.9.9",
-    "esbuild": "^0.24.0"
+    "esbuild": "^0.25.0",
+    "express": "^5.1.0"
   },
   "type": "module",
   "name": "@reboot-dev/reboot",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "npm package for Reboot",
   "scripts": {
     "postinstall": "rbt || exit 0",
@@ -24,7 +25,8 @@
   "devDependencies": {
     "typescript": ">=4.9.5",
     "@types/node": "20.11.5",
-    "@types/uuid": "^9.0.4"
+    "@types/uuid": "^9.0.4",
+    "@types/express": "^5.0.1"
   },
   "bin": {
     "rbt": "./rbt.js",
@@ -54,6 +56,7 @@
     "reboot_native.cc",
     "reboot_native.cjs",
     "reboot_native.d.ts",
+    "secrets",
     "utils",
     "venv.d.ts",
     "venv.js",

package/rbt.js

@@ -27,13 +27,16 @@ function addExtensionlessToNodeOptions() {
     // If we have one of those two versions then we can pre import
     // `extensionless/register` to use the `module.register()` function,
     // otherwise we need to fall back to `--experimental-loader`.
-    if (major > 20 ||
+    if (major >= 21 ||
         (major == 20 && minor >= 6) ||
         (major == 18 && minor >= 19)) {
         process.env.NODE_OPTIONS += "--import=extensionless/register";
     }
     else {
-        process.env.NODE_OPTIONS += "--experimental-loader=extensionless";
+        throw new Error(`The current version of Node.js is not supported.
+       Supported versions are:
+        * greater than or equal to 20.6
+        * greater than or equal to 18.19 but less than 19`);
     }
 }
 async function main() {