wain-validate
=============
[![crates.io][crates-io-badge]][crates-io]
[![CI][ci-badge]][ci]

[`wain-validate`][gh] is a crate to validate a parsed WebAssembly abstract syntax tree.
Validation logic is defined in [spec][wasm-spec-validation]

This crate is part of larger [wain][proj] project.


## Installation

```toml
[dependencies]
wain-validate = "0"
```


## Usage

It takes a reference to `wain_ast::Root` value and validates it. The value can be generated by
`wain-syntax-binary` and `wain-syntax-text` parsers:

- [wain-ast](https://crates.io/crates/wain-ast)
- [wain-syntax-text](https://crates.io/crates/wain-syntax-text)
- [wain-syntax-binary](https://crates.io/crates/wain-syntax-binary)

Using `wain_validate::validate()` is the easiest way.

```rust
extern crate wain_syntax_binary;
extern crate wain_validate;

use std::fs;
use wain_syntax_binary::parse;
use wain_validate::validate;

let source = fs::read("foo.wasm").unwrap();
let tree = parse(&source).unwrap();

if let Err(err) = validate(&tree) {
    eprintln!("This .wasm file is invalid!: {}", err);
}
```

Working examples can be seen at [examples/api/ directory][examples]

Please read documentation (not yet) for details.


## Implementation

Conforming [spec][wasm-spec-validation], following things are validated:

- In Wasm, every reference is an index. It validates all indices are not out of bounds
- Wasm is designed to check stack operations statically. It validates instructions sequences with
  emulating stack state
- Type check is best-effort due to polymorphic instruction `select`. Since almost all instructions
  are not polymorphic, almost all type checks can be done in validation

Conforming the spec, wain validates instructions after `unreachable` instruction. For example,

```wat
(unreachable) (i64.const 0) (i32.add)
```

`i32.add` is invalid because it should take two `i32` values from stack but at least one `i64` value
is in the stack.


## License

[the MIT license](./LICENSE.txt)

[ci-badge]: https://github.com/rhysd/wain/workflows/CI/badge.svg?branch=master&event=push
[ci]: https://github.com/rhysd/wain/actions?query=workflow%3ACI+branch%3Amaster+event%3Apush
[crates-io-badge]: https://img.shields.io/crates/v/wain-validate.svg
[crates-io]: https://crates.io/crates/wain-validate
[wasm-spec-validation]: https://webassembly.github.io/spec/core/valid/index.html
[gh]: https://github.com/rhysd/wain/tree/master/wain-validate
[proj]: https://github.com/rhysd/wain
[examples]: https://github.com/rhysd/wain/tree/master/examples/api