API design notes

[chrisdickinson]

@bhelx asked me to take a quick look at the API to see how it maps to JS idioms. This is the result of a quick look – so there's probably stuff I've misunderstood about the implementation, apologies! I'd be happy to talk about any of these items more (or pitch in myself!)

• add async createPlugin(plugin, options): Plugin as the default export
  • I found the static await ExtismPlugin.new() construction workable, but a little surprising! Usually there's a free-standing top-level export for asynchronous object creation alongside a constructor that can be used when you have all of the required info available synchronously. (Compare fs.Stats to fs.stat(file, cb) in Node.)
  • Also, IIUC, we're duck-typing inputs based on {path: string} | {url: string}.
    • We might wish to check if the input is a string, then pass it to new URL (which accepts file:///-style URLs), then pass the resulting URL to fetch – unifying the path/url case
    • That might even give us content-type info we can use to decide whether the response is a manifest or a core module.
  • We probably want to stream incoming wasm plugin data if possible, especially if we're in the browser
• Add example & basic API reference to README so it displays on npm website
  • this follows the rough NPM package convention -- useful since a lot of folks use npm.im/<package name> to quickly get an idea of how to use a package
• We should also publish to npm.im/extism, since that name is available
  • speaking of -- extism is available, so we should grab that package name as well
  • at the very least it prevents a malicious typosquat
  • I grabbed the package for now, we can share it with an extism bot user for publishing purposes.
• that synchronous httpRequest is a killer for prod use; we should think about running the plugin in a Worker so we avoid gumming up the main thread
  • this is probably a bigger refactor: I'd have to spend a bit more time with the sdk to think about how best to accomplish it!
  • Essentially, the sync httpRequest is a good argument for running the plugin inside a worker and adding faux "blocking" to extism_http_request. We could make extism_http_request look "blocking" by sending a SharedArrayBuffer from the worker to the main thread and using that to communicate response data back to the worker.

[mhmd-azeez]

@chrisdickinson thank you very much for the thorough review

that synchronous httpRequest is a killer for prod use; we should think about running the plugin in a Worker so we avoid gumming up the main thread

Yup, I agree. Unfortunately, I wasn't able to find any non-blocking ways. Your help would be greatly appreciated.

[chrisdickinson]

Great work on this – I'm closing this as complete, with work to continue in #7!