endo program behaviour

[michaelfig]

Here are some ideas inspired by generalizing agoric deploy --target=....

endo [...options] <script> ...args

It would import <script> as JS code, just as an Agoric deploy script would, and support the same programming API.

• endo reads $ENDO_OPTIONS for options to add implicitly before the command-line options.
• endo directly passes script and ...args through to the script as an array of strings: powers.args = [script, ...args].
• agoric deploy has an enforced leading --plugin=ag-solo://HOSTPORT where HOSTPORT is the value of the --hostport option, defaulting to localhost:8000. agoric run has default plugins of ['home:$HOME/.agoric'] but
• agoric deploy --home defaults to $HOME/.agoric
• endo --home can specify a URL (interpreted relative to current working directory file: URL, may be remote URLs for databases, etc) and override the OS default config file and program state locations.

#! /usr/bin/env endo
/**
 * @template T
 * @callback EndoScript
 * @params {ERef<Home>} home
 * @params {Record<string, any>} powers
 * @returns {ERef<T>}
 */

/** @template T @type {EndoScript<T>} */
export default async (home, powers) => {
  // Do stuff.
};

/** @typedef {EndoScript<Parameters<EndoScript>>} EndoPluginScript */

• --plugin=NAME:aeditsehai is implemented by @endo/NAME-plugin or endo-NAME-plugin
  • whose module specifier's default export is an EndoPluginScript
  • powers.args is ['--target=NAME:aeditsehai', ...remaining args]
  • powers.priorTarget is [priorHomeP, priorPowers]
  • returns ERef<[nextHomeP, nextPowers]>.

@endo/options-plugin is the implicit target that runs before any other (given no home or powers), and @endo/args-plugin is the implicit target that runs before the non-optional arguments (i.e. to invoke the script).

[michaelfig]

@kriskowal here's something I'd like to discuss in the open.

[kriskowal]

I’ve been mulling on this and maybe we can take an middleware / adapter-pattern approach to plugins. Perhaps the first entry in the chain just receives a bag of powers, and one of those powers is to get the namespace of the next plugin in the chain. A deploy script would be the final link in a particular chain of plugins, so the penultimate plugin would presume the ultimate plugin had the exact signature of a deploy script, providing exactly its particular home object and powers. Each intermediate plugin would embellish the vat powers it passes to the next plugin.

[michaelfig]

That's interesting to me! Please see #1225 for the endo-exec script launcher we could use as the basis for such a plugin system.

[michaelfig]

I have a much more lightweight, policy-agnostic Endo executor: #1225

That can be used as the basis for this kind of plugin system layered on top.

[kriskowal]

So, #1225 imports a program in Node.js but under lockdown. That’s a great place to start. Maybe we could tuck it under the guise of endo unsafe x.js and build atop that.

I can see how this could be the bottom of a stack of plugins. The next step would be to pass an endoExec function down, such that a plugin @endo/plugin could chain to x.js with endo unsafe plugin x.js.

/** @type {import('@endo/exec').Main} */ 
export const main = async ([script, ...args], {exec}) => {
  const plugin = makePlugin(); // Introduce a new power.
  return exec(args, {exec, plugin});
};

[kriskowal]

The idea being that at some point, one of those plugins might be @endo/safe that takes those plugins and threads them into a compartmentalized application, which would effectively be endo safe.