veewee/ext-wasm

Run webassembly from PHP

ext-wasm's Issues

Investigate: can we provide FFI bindings for people who dont want to install an extension?

Support WebAssembly Memory

See:

• https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/Memory
• https://wasmerio.github.io/wasmer-python/api/wasmer/wasmer.html#MemoryType

$memory = new Wasm\Memory(
    minimumPages: 1 
    maximulPages: null,
    shared: true
);

$instance = Wasm\InstanceBuilder::fromWat($wat)
    ->withImports(['env' => ['someMemory' => $memory]])
    ->build();

$memory = $instance->someMemory();

// settings
$sizeInBytes = $memory->bytes();
$sizeInPages = $memory->pages();
$memory->grow(2);

// views
// TODO: possibly add an ArrayWrapper or Buffer that allows both read and write
$str = pack('C*', ...$memory->view()); // TODO : separate int[n] vs float[n] views

// Buffer Resource
$resource = $memory->buffer();
fseek($resource, 0);
fread($resource, $memory->bytes());
fwrite($resource, $data);

Investigate: can we provide pre-compiled versions of this extension for easier installation?

Introduce instance builder

$instance = Wasm\InstanceBuilder::fromWat(
    <<<'EOWAT'
    (module
      (global $one (export "one") i32 (i32.const 1))
      (global $some (export "some") (mut i32) (i32.const 0))
      (func (export "get_one") (result i32) (global.get $one))
      (func (export "get_some") (result i32) (global.get $some))
      (func (export "set_some") (param i32) (global.set $some (local.get 0))))
    EOWAT
)
    ->withEngine(Wasm\Engine::UNIVERSAL)
    ->withCompiler(Wasm\Compiler::LLVM)
    ->withImports($imports)
    ->withMemory($memory)
    ->build();

// OR

$instance = Wasm\InstanceBuilder::fromWasi(read_file($binaryFile))->build();

// OR

$instance = WasmInstance::fromBuilder($builder);

We can start out small with the most basic Builder::fromWat()->build() so that we extend the with-methods based on the features we add.

❗ WasmInstance::__construct should not be used anymore and should be marked as private.

Segfault PHP 8.2

On PHP 8.2 (on every OS), we get segfaults when running the testsuite:

Run make phpunit
php "-d extension=./target/release/libext_wasm.so" ./tools/phpunit.phar;
PHPUnit 9.6.6 by Sebastian Bergmann and contributors.

Segmentation fault (core dumped)
make: *** [Makefile:28: phpunit] Error 139
Error: Process completed with exit code 2.

See #1

Possibly linked to davidcole1340/ext-php-rs#218

On mac:

make: *** [phpunit] Segmentation fault: 11

The segmentation fault (signal 11) indicates an attempt to write to memory that has not been allocated to the process for writing. A common reason for this is when array bounds are exceeded.

On Windows

mingw32-make: *** [makefile:29: phpunit] Error 2816

Test cases

All features of this extension should be covered by PHPUnit test cases.
At least all examples - and other edge cases - should be in there so that they are tested on the full matrix of PHP versions and operating systems.

Support native dylib engine

See https://wasmerio.github.io/wasmer-python/api/wasmer/wasmer.html#engine

$instance = Wasm\InstanceBuilder::fromWat($wat)
    ->withEngine(Wasm\Engine::DYLIB)
    ->build();

Investigation: can we deliver wasm meta-data for generating autocompletion

See:

• https://github.com/veewee/ext-wasm/blob/main/examples/autocompleting-decorator-not-working-yet.php
• https://github.com/veewee/ext-wasm/blob/main/examples/autocompleting-proxy.php

/**
 * @property int $one
 * @property int $some
 * @method int get_one()
 * @method int get_some()
 * @method int set_some(int $param)
 */
final class MyInstanceDecorator extends Wasm\WasmInstance {
  public function __construct() {
    parent::__construct(
      <<<'EOWAT'
      (module
        (global $one (export "one") i32 (i32.const 1))
        (global $some (export "some") (mut i32) (i32.const 0))
        (func (export "get_one") (result i32) (global.get $one))
        (func (export "get_some") (result i32) (global.get $some))
        (func (export "set_some") (param i32) (global.set $some (local.get 0))))
      EOWAT
    );
  }
}

❗ Currently decorating the WasmInstance like this throws an exception. This probably needs to be fixed in the rs-php-ext project.

It would be nice if we can provide $instance->getMetaData() that gives us all the raw information to build the @method and @property.
That way, we could build a code-generator that gives us autocompletable and staticly analyzer safe PHP code.

The goal of this issue is solely to provide the meta data. Doing something with it seems more appropriate for doing in a separate PHP-based package.

Provide fluent interfaces

Once php-ext-rs supports it, we can make the builder, imports, ... class methods fluent so that it becomes easier to configure the wasm instance.

See
davidcole1340/ext-php-rs#236

Support multiple compilers

Currently the system uses the default encoder.
We should add support for:

• singlepass
• cranelift
• llvm

$instance = Wasm\InstanceBuilder::fromWat($wat)
    ->withCompiler(Wasm\Compiler::LLVM)
    ->build();

https://wasmerio.github.io/wasmer-python/api/wasmer/wasmer.html#engine

Support all wasmer value types

See https://github.com/veewee/ext-wasm/blob/main/src/types.rs#L4

• ExternRef(Option<ExternRef>)
• FuncRef(Option<Function>)
• V128(u128)

❗ To investigate : do we need to split Values from Types?

• https://wasmerio.github.io/wasmer-python/api/wasmer/wasmer.html#Value
• https://wasmerio.github.io/wasmer-python/api/wasmer/wasmer.html#Type

Custom exceptions

Currently this repo throws a default PHP \Exception.
It should be better if we at-least provided a Wasm\Exception

Other possible exceptions:

• https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/Exception
• https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/CompileError
• https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/LinkError
• https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/RuntimeError

Do note that currently we'll need to work around these limitations:

• davidcole1340/ext-php-rs#214
• davidcole1340/ext-php-rs#203

static mut WASM_EXCEPTION: Option<&'static ClassEntry> = None;

#[php_startup]
pub fn startup() {
    let ce_wasm_exception = ClassBuilder::new("Wasm\\Exception\\Exception")
        .extends(ce::exception())
        .build()
        .expect("Invalid check");
    unsafe { WASM_EXCEPTION.replace(ce_wasm_exception) };
}

//--> Return
PhpException::new(e.to_string(), 0, unsafe {
    WASM_EXCEPTION.expect("did not set exception ce")
})

Support returning multiple results in function calls

Example:
https://github.com/veewee/ext-wasm/blob/main/examples/function-multiple_arguments.php

<?php

$instance = new Wasm\WasmInstance(
  <<<'EOWAT'
    (module
      (func $swap (export "swap") (param i32 i32) (result i32 i32)
        (local.get 1) (local.get 0)
      )
    )
    EOWAT
);

var_dump($instance->swap(1, 2));

This should return [2, 1]

Currently this returns null

See

ext-wasm/src/lib.rs

Line 44 in a6d650d

_ => None // Todo support: Some(result), "Copy" solution for Value might not be best for case "1" either

Bug : stub generation fails

To investigate:

make stubs                                                                                                                                                                                              

cargo php stubs;
Finished dev [unoptimized + debuginfo] target(s) in 0.17s
Error: Failed to load extension library

Caused by:
dlopen(/Projects/github/veewee/ext-wasm/target/debug/libext_wasm.dylib, 0x0005): symbol not found in flat > namespace '_zend_array_count'
make: *** [stubs] Error 1

(probably an issue in ext-php-rs when the array implementation got improved in https://github.com/davidcole1340/ext-php-rs/releases/tag/v0.10.1)

Investigate: Can we make this package available on pear/pecl?

Support WebAssembly Tables

See:

• https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/Table
• https://wasmerio.github.io/wasmer-python/api/wasmer/wasmer.html#TableType

$table = new Wasm\Table(minimum: 2, maximum: null, type: 'i32', init: $initValue);

$instance = Wasm\InstanceBuilder::fromWat($wat)
    ->withImports(['env' => ['someTable' => $table]])
    ->build();


$table = $instance->getTable();
$table->set(0, 1);
$table->get(0);
$table->count(); // implements \Countable
$table->grow(2, $initValue);

// possibly:
[...$table] // implements Iterator | IteratorAggregate

Compile errors on Windows

error[E0554]: #![feature] may not be used on the stable release channel
--> C:\Users\runneradmin.cargo\registry\src\github.com-1ecc6299db9ec823\ext-php-rs-0.10.0\src\lib.rs:7:22
|
7 | #![cfg_attr(windows, feature(abi_vectorcall))]
| ^^^^^^^^^^^^^^^^^^^^^^^

For more information about this error, try rustc --explain E0554.
error: could not compile ext-php-rs due to previous error
mingw32-make[1]: *** [makefile:8: compile] Error 101
mingw32-make[1]: Leaving directory 'D:/a/ext-wasm/ext-wasm'
mingw32-make: *** [makefile:14: setup-ci] Error 2

See See #1

Support WASI

https://wasmerio.github.io/wasmer-python/api/wasmer/wasmer.html#wasi

$instance = Wasm\InstanceBuilder::fromWasi(read_file($binaryFile))->build();

Support WebAssembly imports

See:

• https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/Module/imports
• https://wasmerio.github.io/wasmer-python/api/wasmer/wasmer.html#ImportType

$instance = Wasm\InstanceBuilder::fromWat($wat)
    ->withImports($imports)
    ->build();

TODO:

• Figure out the best way to define imports