Git-Mirrors/veilid
1
0
Fork 0
mirror of https://gitlab.com/veilid/veilid.git synced 2024-10-01 01:26:08 -04:00
Code Issues Packages Projects Releases Wiki Activity
8cb5b4b85a
veilid/veilid-wasm/README.md

42 lines
2.8 KiB
Markdown
Raw Normal View History

Add new VeilidTable and VeilidClient to WASM API These new interfaces have been reworked (compared to the original API) to emit (mostly) proper TypeScript types.
2023-08-18 18:32:04 -04:00
# veilid-wasm
(wasm) webdriver-based tests for JS/TS apis, update README
2023-09-06 22:13:05 -04:00
This package is a Rust cargo crate the generates WebAssembly (WASM) bindings for `veilid-core::VeilidAPI`, and outputs JavaScript and TypeScript interfaces for calling the WASM module.
Add new VeilidTable and VeilidClient to WASM API These new interfaces have been reworked (compared to the original API) to emit (mostly) proper TypeScript types.
2023-08-18 18:32:04 -04:00
(wasm) webdriver-based tests for JS/TS apis, update README
2023-09-06 22:13:05 -04:00
## Limitations
Running Veilid in the browser via WebAssembly has some limitations:
Clarify that WASM bootstrap uses ws, not wss or DNS This fixes the logic error of "bootstrapping via TXT record also will work." This also adds a clarification that, because DNS is unavailable, the only option today is ws:// (Veilid currently does not allow wss:// with an IP address. Specifically, try_wss will fail with apibail_parse_error! and then RPCError::map_protocol.) This clarification saves time for any users who would otherwise be tempted to get a certificate for an IP address (at least one free Certificate Authority supports this, and the resulting certificate can be added to a veilid-server configuration.) try_wss failure: https://gitlab.com/veilid/veilid/-/blob/bd4b4233bfed5bdca4da3cacda3ad960e28daab5/veilid-core/src/network_manager/types/dial_info/mod.rs#L199-L202 https://gitlab.com/veilid/veilid/-/blob/bd4b4233bfed5bdca4da3cacda3ad960e28daab5/veilid-core/src/rpc_processor/coders/dial_info.rs#L52-L56 see also: https://gitlab.com/veilid/veilid/-/blob/bd4b4233bfed5bdca4da3cacda3ad960e28daab5/veilid-core/src/network_manager/types/dial_info/mod.rs#L58-L59 In addition, several spelling errors are fixed.
2023-09-27 01:46:22 -04:00
### Browser-based limitations
(wasm) webdriver-based tests for JS/TS apis, update README
2023-09-06 22:13:05 -04:00
Clarify that WASM bootstrap uses ws, not wss or DNS This fixes the logic error of "bootstrapping via TXT record also will work." This also adds a clarification that, because DNS is unavailable, the only option today is ws:// (Veilid currently does not allow wss:// with an IP address. Specifically, try_wss will fail with apibail_parse_error! and then RPCError::map_protocol.) This clarification saves time for any users who would otherwise be tempted to get a certificate for an IP address (at least one free Certificate Authority supports this, and the resulting certificate can be added to a veilid-server configuration.) try_wss failure: https://gitlab.com/veilid/veilid/-/blob/bd4b4233bfed5bdca4da3cacda3ad960e28daab5/veilid-core/src/network_manager/types/dial_info/mod.rs#L199-L202 https://gitlab.com/veilid/veilid/-/blob/bd4b4233bfed5bdca4da3cacda3ad960e28daab5/veilid-core/src/rpc_processor/coders/dial_info.rs#L52-L56 see also: https://gitlab.com/veilid/veilid/-/blob/bd4b4233bfed5bdca4da3cacda3ad960e28daab5/veilid-core/src/network_manager/types/dial_info/mod.rs#L58-L59 In addition, several spelling errors are fixed.
2023-09-27 01:46:22 -04:00
1. TCP/UDP sockets are unavailable in the browser. This limits WASM nodes to communicating using WebSockets.
1. Lookup of DNS records is unavailable in the browser, which means bootstrapping via TXT record also will not work. WASM nodes will need to connect to the bootstrap server directly via WebSockets, using this URL format: `ws://bootstrap.veilid.net:5150/ws` in the `network.routing_table.bootstrap[]` section of the veilid config.
1. Do not set up any nodes with a core.network.protocol.wss.url IP address such as wss://12.34.56.78:5150/ws to support SSL. Even though a Certificate Authority (trusted by browsers) will give you an SSL certificate for an IP address, this is unsupported by Veilid as of v0.2.3. Any wss:// URL containing an IP address causes an RPC error in veilid-core and your node will lose communication with other nodes.
1. Since a WASM node running in the browser can't open ports, WASM nodes select another node to act as its Inbound Relay, so other nodes can react out to it and open a WS connection.
(wasm) webdriver-based tests for JS/TS apis, update README
2023-09-06 22:13:05 -04:00
1. Because of browser security policy regarding WebSockets:
1. `ws://` only works on `http://` sites
1. `wss://` only works on `https://` site with SSL certificates.
### Running WASM on HTTPS sites [Not currently implemented]
Clarify that WASM bootstrap uses ws, not wss or DNS This fixes the logic error of "bootstrapping via TXT record also will work." This also adds a clarification that, because DNS is unavailable, the only option today is ws:// (Veilid currently does not allow wss:// with an IP address. Specifically, try_wss will fail with apibail_parse_error! and then RPCError::map_protocol.) This clarification saves time for any users who would otherwise be tempted to get a certificate for an IP address (at least one free Certificate Authority supports this, and the resulting certificate can be added to a veilid-server configuration.) try_wss failure: https://gitlab.com/veilid/veilid/-/blob/bd4b4233bfed5bdca4da3cacda3ad960e28daab5/veilid-core/src/network_manager/types/dial_info/mod.rs#L199-L202 https://gitlab.com/veilid/veilid/-/blob/bd4b4233bfed5bdca4da3cacda3ad960e28daab5/veilid-core/src/rpc_processor/coders/dial_info.rs#L52-L56 see also: https://gitlab.com/veilid/veilid/-/blob/bd4b4233bfed5bdca4da3cacda3ad960e28daab5/veilid-core/src/network_manager/types/dial_info/mod.rs#L58-L59 In addition, several spelling errors are fixed.
2023-09-27 01:46:22 -04:00
Since WSS connections require WSS peers with valid SSL certificates, `veilid-core` plans to implement a feature called Outbound Relays. Outbound Relays will likely be hosted by the same host of the WASM web-app, and must run have valid SSL certificates that are signed by a Certificate Authority that's trusted by browsers. Outbound Relays will allow WASM nodes to communicate to other nodes over TCP/UDP/WS/WSS through the Outbound Relay's connection.
(wasm) webdriver-based tests for JS/TS apis, update README
2023-09-06 22:13:05 -04:00
## Running unit tests
Clarify that WASM bootstrap uses ws, not wss or DNS This fixes the logic error of "bootstrapping via TXT record also will work." This also adds a clarification that, because DNS is unavailable, the only option today is ws:// (Veilid currently does not allow wss:// with an IP address. Specifically, try_wss will fail with apibail_parse_error! and then RPCError::map_protocol.) This clarification saves time for any users who would otherwise be tempted to get a certificate for an IP address (at least one free Certificate Authority supports this, and the resulting certificate can be added to a veilid-server configuration.) try_wss failure: https://gitlab.com/veilid/veilid/-/blob/bd4b4233bfed5bdca4da3cacda3ad960e28daab5/veilid-core/src/network_manager/types/dial_info/mod.rs#L199-L202 https://gitlab.com/veilid/veilid/-/blob/bd4b4233bfed5bdca4da3cacda3ad960e28daab5/veilid-core/src/rpc_processor/coders/dial_info.rs#L52-L56 see also: https://gitlab.com/veilid/veilid/-/blob/bd4b4233bfed5bdca4da3cacda3ad960e28daab5/veilid-core/src/network_manager/types/dial_info/mod.rs#L58-L59 In addition, several spelling errors are fixed.
2023-09-27 01:46:22 -04:00
Prerequisites:
(wasm) webdriver-based tests for JS/TS apis, update README
2023-09-06 22:13:05 -04:00
- NodeJS - ensure `node` and `npm` are installed.
- Firefox browser installed, and available as `firefox`.
Run the test script:
- `./wasm_test.sh` to test with debug symbols.
- `./wasm_test.sh release` to test against a release build.
## Development notes
### Important cargo crates and their functions
- [`wasm-bindgen`](https://rustwasm.github.io/wasm-bindgen/) is used to generate interop code between JavaScript and Rust, as well as basic TypeScript types.
- [`tsify`](https://github.com/madonoharu/tsify) is used to export TypeScript types in places where `wasm-bindgen` runs into limitations, or in places where you don't need the mappings that `wasm-bindgen` generates.
- [`serde-wasm-bindgen`](https://github.com/cloudflare/serde-wasm-bindgen) enables serialization/deserialization.
Reference in New Issue Copy Permalink