Handling callbacks between Components regardless of loading mode

[andy-haynes]

TL;DR - how can we always call methods on props the same way when they may be asynchronous based on how the Component was loaded?

This has some wide implications for the Viewer, in particular how it will treat the concept of trust. For background, there are two modes for loading a Component tree:

• Sandboxed: Each Component gets its own iframe and communicates indirectly with other Components via window.postMessage. This is more secure but incurs heavy performance overhead for nested Components.
• Trusted: Child Components are defined inline within the parent Component. The Component takes longer to load but the components and props callbacks are defined in the same iframe context.

For these to be effectively utilized, I'm of the opinion that trust should be decided at render/run time, e.g. a potential implementation might look like:

// load this Component inline
// props methods are defined in the parent Component's iframe
<Widget src"trusted.near/widget/Trusted" isTrusted={true} />

// load this Component component in a separate iframe
// props methods are invoked from that iframe and passed to the parent Component
<Widget src"untrusted.near/widget/Sandboxed" isTrusted={false} />

The consequence of this approach is that the behavior between the two should be as seamless as possible; a Component loaded as sandboxed should be as close as possible to functionally identical with that same Component loaded in a trusted context. One fundamental difference between the approaches is that callbacks between sandboxed Components (i.e. methods passed on props from parent to child) are inherently asynchronous because of their reliance on window.postMessage. Trusted Components do not have this issue, as the callback would be defined within the same iframe context.

The current implementation for sandboxed Components solves this by treating props methods as being async, which has the side effect of enabling top-level await within Component definitions (which is really more of an anti-pattern). This is pretty awkward for trusted Components, which would now need to await every method invocation on props in order to function the same when it is loaded as sandboxed.

One solution I've been thinking about involves emulating the behavior of the Near and Social methods making RPC requests:

1. return undefined on the first invocation
2. kick off a promise to fetch the value from RPC
3. cache the value for the next props method invocation to return
4. trigger re-render of the Component

Effectively the only change for Component developers is to account for the case in which the result of a props method invocation is undefined, i.e.

before:

return (<div>value is {props.getDataSynchronously().value}</div>);

after:

const data = props.getDataSynchronously();
if (data === undefined) {
  return (<>loading...</>);
}

return (<div>value is {data.value}</div>);

Curious to hear what others think. Is this a viable solution? Is there a better way to abstract this away from the mode of Component loading?

[mpeterdev]

I think our goal should be to make things look and feel as much like vanilla React as possible. In this situation, I would lean towards imposing constraints instead of inventing new patterns.

This is pretty awkward for trusted Components, which would now need to await every method invocation on props in order to function the same when it is loaded as sandboxed.

While slightly awkward, this is very predictable and it's an easy to remember rule that when passing functions as props in BOS they must always be written (explicitly) as async functions and handled as such.

One solution I've been thinking about involves emulating the behavior of the Near and Social methods making RPC requests

I am not a big fan of this because it's like a hook but not a hook, and will be unfamiliar to developers. If we implemented it in such a way that it was written and felt like a hook then I would be more open to it.

The current implementation for sandboxed Components solves this by treating props methods as being async, which has the side effect of enabling top-level await within Component definitions (which is really more of an anti-pattern).

Agreed, we should not allow top-level await. I'm not clear on why making props functions async affects function components in a way that enables this. If it is not trivial to disallow, let's work through an example.

[andy-haynes]

Top-level await was the shortcut to clean handling of asynchronous props methods. It's basically a workaround for not having hooks.

It's been a while since I've looked into bringing in Preact hooks, but that's probably the sanest approach here. Then we can look at implementing a hook on top of that specifically for working with props methods to make this constraint less cumbersome. Not sure exactly what that looks like yet but it's better than rolling our own or doing it implicitly.

[mpeterdev]

related to #11 and #14

[andy-haynes]

I revisited adding Preact hooks but there are some challenges with how Preact core and hooks packages work together. It's going to take some more work to get them supported within Components.

I am not a big fan of this because it's like a hook but not a hook, and will be unfamiliar to developers. If we implemented it in such a way that it was written and felt like a hook then I would be more open to it.

In the interim, I'm leaning more towards something like this - a useComponentCallback pseudo-hook for Component callbacks until hooks are supported. It would work just as I outlined but could be implemented with useState and useEffect, e.g.:

function useComponentCallback(cb: Function, args: any) {
  const [value, setValue] = useState<any>(undefined);
  useEffect(() => {
    (async () => {
      setValue(await cb(args));
    })();
  }, []);

  return () => value;
}

The big advantage here being that we'd be adhering to React conventions. There are a few constraints though:

1. Callbacks are invoked eagerly. This isn't a problem for simple use cases, but it would mean unnecessary calls for branching logic (e.g. props.a() is invoked when props.x === true and props.b() otherwise) since the hook would need to be invoked unconditionally. This could be addressed by restructuring the component.
2. The function returned from the hook is bound to the initial parameters. This precludes the use of dynamic arguments, making this hook only suitable for props methods to be invoked at render time.
3. The props callbacks would need to be deterministic. The first value returned for a given props method invocation will always be the value associated with the provided arguments. E.g. props.getBlockHeight() would return undefined on the initial invocation, with every invocation (after the promise has resolved) returning the returned value.

For a simple Component:

// legacy VM
return <>{props.renderItems(items)}</>;

// current `async` implementation
return <>{await props.renderItems(items)}</>;

// proposed hook
const placeholder = "loading..."; // this is an option now since the render isn't blocking
const renderItems = useComponentCallback(props.renderItems, items);
return <>{renderItems() || placeholder}</>;

For a more complex Component:

// legacy VM
return <>{items.map((i) => <Item item={props.getItem(i)} />}</>;

// current `async` implementation
return <>{await Promise.all(items.map(async (i) => <Item item={await props.getItem(i)} />))}</>;

// proposed hook
const placeholder = "loading..."; // this is an option now since the render isn't blocking
// no `args` passed into useComponentCallback since it encapsulates a set of invocations with different parameters
const renderItems = useComponentCallback(() => Promise.all(items.map(async (i) => <Item item={await props.getItem(i)} />)));
return <>{renderItems() || placeholder}</>;

[mpeterdev]

I think a pseudo-hook is a good approach at this time 👍