JSCore Runtime - Execute JavaScript and WebAssembly natively with JavaScriptCore - A step towards compiled C extension modules for Pythonista

[M4nw3l]

I’m honestly thrilled to have reached a good point to share this new project I’ve been working on. It radically blurs the lines of what is possible in Pythonista 3, by implementing JavaScript and WebAssembly as closely integrated, independent execution runtimes with full Python interoperability support. It is an extensive Python mapping of the JavaScriptCore iOS API and implementation with just objc_util and standard libraries. Python scripts, programs and apps can now directly import and use JavaScript and WebAssembly functionality with close to native performance, a Python-like interface and seamless standard Python values conversions, including for Python callables such as functions and lambdas.

https://github.com/M4nw3l/pythonista-jscore-runtime

A couple of quick examples before some further discussion:
JavaScript runtime:

from jscore_runtime import *

runtime = jscore.runtime()
context = runtime.context()

# define values / objects from python
context.js.my_object = {“hello”:”world”, “array”:[1,2,3] }
print(context.eval(“my_object;”).value) # access from javascript 
# prints:  {‘hello’:’world’, ‘array’:[1,2,3] }

# use python functions as javascript functions 
context.js.python_print = lambda *args: print(*args)
context.eval(‘python_print(“hello python”);’)
# prints: hello python

context.destroy()
runtime.destroy()

WebAssembly runtime:

# based on Mozilla’s simple.wasm module loading example from
# https://developer.mozilla.org/en-US/docs/WebAssembly/Guides/Using_the_JavaScript_API#loading_wasm_modules_in_javascript

from jscore_runtime import *

runtime = jscore.runtime(wasm_runtime)
context = runtime.context()

# download simple.wasm from the link above and import to same folder as the script in Pythonista beforehand
# load simple.wasm
module = wasm_module.from_file('./simple.wasm')
# define imports
module.imports.my_namespace.imported_func = lambda v: print(v)
# load module into context
context.load_module(module)
# once loaded, a modules exports become available and may be invoked
module.exports.exported_func()
 # prints: 42

context.destroy()
runtime.destroy()

OK, so although they’re somewhat trivial there’s a fair bit going on in these, and they are aiming to illustrate briefly what the interfaces look like for using JavaScript and WebAssembly from Python programs, with working examples. Note: to run the WebAssembly example the simple.wasm file needs to be downloaded and copied into Pythonista with the “Run Pythonista Script->Import File” share sheet option.

Now to address the main question, how is this a step towards compiled C extension modules in Pythonista, isn’t this impossible?
The short answer is, well it’s not impossible anymore… Although really it has been technically possible for a little while apparently, since JavaScriptCore with working WebAssembly support has been available as an iOS API. However this support isn’t out of the box, there are a number of challenges to overcome in cross-compiling C or another compiled language to WebAssembly and then executing it, from entirely within Pythonista. Currently this project addresses the execution of WebAssembly with Pythonista, that has been compiled already from a source. It does not compile any WebAssembly currently, it just runs it. While JavaScript execution support also comes as the natural first step because it is part of WebAssembly’s integration model and JavaScriptCore is primarily a standalone JavaScript engine. Like V8 is the standalone JavaScript engine to Chrome, JavaScriptCore is the same equivalent component to WebKit/Safari.

Some effort to prepare/compile a WebAssembly module, load and use it from Pythonista is still required as well as some knowledge of a compiler capable of generating WebAssembly is needed currently. WebAssembly System Interface (WASI) is not implemented as of yet either. A long-term goal is to support a full compilation tool-chain, that also integrates with setuptools / pip ultimately from just Pythonista. Which is potentially achievable with WebAssembly ports of the appropriate tools such as cc/gcc/clang and LLVM etc and some suitable code generation. Though some parts of integrating Wasm modules as Python compiled extension modules may still unavoidably require more explicit implementation. Its aim is the rather lofty goal of Pythonista having at least the same equivalent of Pyto’s capability to cross-compile Python extension modules to WebAssembly. Except with this support being provided purely as installable python modules/pip packages for Pythonista as-is, without requiring any changes or updates to Pythonista itself.

For now I hope you enjoy experimenting with executing JavaScript and pre-compiled WebAssembly in your programs! Some more details and usage examples are given in the README. I would enjoy to hear how you get on if you try out the project, if you build something with it, or even if you encounter problems or just have any thoughts, feedback or suggestions for improvements as well?

[jackatttack]

This is genius, I've been working on web assembly bridges using the webview in ui but this is a way cleaner approach.

I'll give this some experimenting and see what I think.

I've already been really impressed with the speeds of running this.

Great work

[M4nw3l]

@jackatttack Thank you so much, I really appreciate the feedback and your kind comments. I have also tried the running Wasm in a WebView approach too in my other project, which works pretty well, but yes it is much heavier as you observe. The bridging approach here conceptually can be applied similarly to just evaluating JavaScript in a WebView, except type handling is a bit different as you don’t get access to JSValue objects or JavaScriptCore at the same level through a WebView.

Some things are fairly similar in both like loading modules / files but the thread models are different and web views almost can’t avoid a local http server to work as well. If the application is heavier and has a UI anyway then this isn’t necessarily a problem, or might even be a better choice depending on how the application works. However it’s also not really suitable running a WebView at the time you’d want to for Python modules importing. The thread model and communication mechanisms with a WebView make it much more impractical and has more overhead.

I haven’t had much chance to do some more formal analysis yet like putting some numbers to performance etc. So I would be interested in any findings that you have and would love to see the experiments you might come up with too!

There’s still some rough edges and things which are limited or needing improvements like promises, certain other JavaScript data types handling like typed arrays that are not bytes etc, Python objects / class types mapping support potentially. Which for the more use cases I can understand the better really, although some things are closer to being realised than others. I’m experimenting with implementing fully wrapped bridged promises from Python in my working version at the moment.

[mdarrint]

Just saw this comment...love it! 👏🏼👏🏼👏🏼

[M4nw3l]

@mdarrint Thank you! I’m fairly close to a full implementation of WASI snapshot preview 1 now too. Although I’m still working on a few aspects and improvements with it before making it a tagged release. The current version on GitHub is passing most of the WASI test suite for preview 1.

Most of what’s left revolves around efficiently and correctly handling WebAssembly.Memory. As well as support for application binary interface(s) described in the WASI spec. Which is quite dense and fiddly, but getting there!

[M4nw3l]

jscore-runtime v0.0.8

As I have just updated the release version of jscore-runtime adding partial support for WebAssembly System Interface (WASI) snapshot preview 1. I thought now might also be a good time to post an update here too, including some more details and commentary for anyone that might be interested.

First things first, let’s explain a little bit more about what WASI is and how it fits into the picture of executing compiled WASM programs in Pythonista 3 with JavaScriptCore. A system interface is an abstraction layer and protocols representing a means of accessing the device / environment / platform it is running within. It specifies delegated components/functions that must fulfil specific requirements on a given target platform for code requiring this to function correctly. Without having to implement exactly how it is done because it is typically a system or platform specific implementation. This is like having a driver for an operating system/platform and the hardware potentially depending on what is specified. One side is acting like a slot of a particular shape, the other side is adapted to fit into this shape and so an executable can interact with the system, without necessarily needing to know exactly which platform it is running or have to be compiled or have provide code for each possible platform.

Web Assembly .wasm executables are an interesting type of program / executable format, especially when it comes to sandboxed environments like iOS apps such as Pythonista. As partly it is intended to be able to repurpose existing code in a platform independent way as it was designed primarily to run inside browsers. Historically apps like Pythonista have had to work around code compilation, downloading, executable loading and sharing related app store policy restrictions. That while generally not entirely unreasoned from a security perspective and without going into too much detail, have on the other hand tended to hinder certain aspects of a development experience on iOS. For Pythonista for example this has meant obtaining Python modules with pip from pypi, was not built in due to ensuring compliance with this and compilation into an iOS native executable formats being restricted additionally imposes the limitation to installing pure Python modules only currently.

This update bridges the gap significantly As it is now possible to attempt run a compiled .wasm executable with a C style _start entry point with a jscore-runtime wasm_context. Passing program arguments, environment variables, directory mounts and exposing standard stdin, stdout, stderr streams. Making it at least somewhat possible to run platform independent compiled .wasm executables in Pythonista. Which can be executed on a thread as if they are a subprocess by providing interface compatibility for the simulation of an isolated process environment.

context = jscore.wasm()
process = context.run_async(‘./program.wasm’, ‘arg0’, ‘argv’, env = {‘envVar’:’envValue’}, dirs=[‘./preopen_dir’])
stdin = process.stdin
stdout = process.stdout
stderr = process.stderr
# …
process.communicate()
# …

To be clear, this update definitely doesn’t fix or address the installation restriction as of yet. But it does bring the project much closer towards having enough support to be able to consider it further. Ultimately with further implementation in the system interface it should be possible to run both an actual shell / terminal, install common Linux C tools, compilers etc all in an isolated environment inside Pythonista. You can find some examples of this being applied on sites which host terminals running in browser windows and frameworks like Pyodide which runs Python cross-compiled into WebAssembly entirely in a browser window.

Although in our case we have Python 3.10 in Pythonista, but what we are missing is not just that of a shell, which has been solved before. Nor the ability to actually execute Cython like code as Pythonista is a Cython implementation. The difficulty with ‘impure’ Python or Python with C extensions in Pythonista is that they can’t be built or even if can be built then they cannot be loaded without a valid AppStore or Apple OS signature. As unapproved/unsigned C / Objective C / Swift compiled executable loading is restricted on devices which don’t also have a jailbreak. There is no build-essential type package available and the standard library setuptools is not aware of Pythonista as a platform. A somewhat work around has been setting the os to appear as darwin as in macOS however this isn’t quite correct either because although the operating systems have common origin. iOS is more heavily restricted than Macs, so this only helps for Python packages which don’t ship the code with ‘python3-any’ or in os independent packages. But can still work, although perhaps with some adjustments.

As restrictions doesn’t apply in the same way for WebAssembly executables however, as they have to be loaded to work in browsers like Safari. We can use it to make more packages work, especially where they may simply use C extensions for offloading performance concerns that aren’t necessarily platform specific. More just have used C or another compiled to implement some code that Python is less suited for or is better suited to assembly operations such as an optimised matrix multiply. Ideally with no adjustments or at least comparatively less adjustments than just cutting out or simulating / reimplementing the functionality entirely.

The a-shell app is a fairly good example of being able to compile and repurpose existing programs into WebAssembly and then run them in a terminal in practice on iOS. Including compiling from source directly with a compiler and linker also running in web assembly in the app. Pythonista with JavaScriptCore can follow a similar process, which jscore-runtime now provides a partial level of support for with this update.

There are still outstanding and missing features not making it complete enough to consider stable yet, however I felt on balance much of the underlying support added also improved quite a bit upon the core runtime as well since the last release of v0.0.7. Fixing problems such as BigInt crashing Pythonista and typed arrays not being particularly well supported. This update has fixed this among the more significant extensions for WASI support, while it has also had a focus on efficiency in memory handling particularly in WebAssembly. This also helped shake out a few flaws in JSValues handling that needed to be fixed.

A particularly notable feature is WebAssembly memory can be manipulated completely arbitrarily in a single call for getting and setting Uint8Array typed arrays of bytes using a representation of a DataView which jscore-runtime calls wasm_memory_view. This is important to avoid multiple cross-boundary JavaScript calls when WASM code is calling back into Python itself through a javascript_callback. This both simplifies reading and writing struct c-structure type data.

def getBytes(self, offset, length):
    return self._allocator.memory_get_bytes(self.memory, offset, length)
		
def setBytes(self, offset, data, length = None):
    if length is None:
	length = len(data)
    data = bytes(data[:length])
    self._allocator.memory_set_bytes(self.memory, offset, data)
    return offset + length

The _allocator object is a small interface representing the other sides of the functions implementations in JavaScript which are provided by wasm_context.

 function memory_get_bytes(wasm_memory, offset, length) {
    const buffer = new Uint8Array(wasm_memory.buffer, offset, length);
    return new Uint8Array(buffer);
}
function memory_set_bytes(wasm_memory, offset, data) {
    const buffer = new Uint8Array(wasm_memory.buffer, offset);
    buffer.set(data);
}

This also demonstrates one of the most powerful features of jscore-runtime allowing Python, JavaScript and WebAssembly to be used almost interchangeably of one another. JavaScript was an easy choice to implement this functionality as it was much more convenient, simpler and briefer than the same equivalent in Python. TypedArrays are returned in a special wrapper holding the JSValue reference which allows direct access in Python and it to be passed back to JavaScriptCore. This is also newer functionality as until this point most type marshalling was primarily conversion rather than more complete proxies for values. I anticipate this functionality can be expanded further to improve handling objects and shared / custom object prototypes/classes and instances in time, which are synchronised more manually currently. Although a mechanism does exist for this currently via the main JSValue wrapper’s javascript_value.jsobject property. It currently requires a more manual wire up for a given object prototype / instance shape.

While I could probably cover more of the fine grained detail, I’ll conclude here as this post is getting quite long. Finally will leave you with saying that there will be further updates to come. Alongside also a screenshot showing some output from this version of jscore-runtime executing and passing some of the official WASI testsuite tests for snapshot preview 1. Note the error messages are expected as the tests generating them are deliberately attempting to access invalid file descriptors.