Git-Mirrors/veilid
1
0
Fork 0
mirror of https://gitlab.com/veilid/veilid.git synced 2024-12-28 00:39:25 -05:00
Code Issues Packages Projects Releases Wiki Activity
d38f3cb42f
veilid/veilid-wasm
History
Δ ǀ Ξ ȼ d38f3cb42f
Refactored Earthfile to improve caching 
Targets have been parallelized so that initial push of the container cache should build the whole build a little quicker, plus the container should now use the cache for more of the build and so speed up normal builds to just the compilation and test of the code that has changed

The `build_cache` target now builds a `build-cache:latest` container that is stored in the GitLab project Container Registry, and then used (if it exists) by the `test_build` target.  The `build_cache` task runs under 3 conditions, 1. the container does not exist, 2. if scheduled, 3. if run manually from the Pipelines page in the GitLab interface.

It is recommended that the build is set up to run on a weekly schedule via the `Pipeline schedules` page in GitLab with the schedule of `0 2 * * 6`.
2023-10-31 11:17:13 +00:00
..
.cargo Add VeilidRoutingContext class for WASM 2023-09-03 23:27:20 -04:00
src (wasm) re-export helpful length constants 2023-09-24 14:47:22 -04:00
tests (wasm) re-export helpful length constants 2023-09-24 14:47:22 -04:00
.gitignore ffi work 2022-02-06 21:18:42 -05:00
Cargo.toml Refactored Earthfile to improve caching 2023-10-31 11:17:13 +00:00
LICENSE.md licensing 2023-07-19 12:48:44 -04:00
README.md Clarify that WASM bootstrap uses ws, not wss or DNS 2023-09-27 05:46:22 +00:00
wasm_build.sh The wasm_build.sh script is now more resilient to failures in finding llvm-dwarfdump 2023-10-01 15:57:58 -04:00
wasm_setup_check.sh (wasm) webdriver-based tests for JS/TS apis, update README 2023-09-17 18:17:24 -04:00
wasm_test.sh allow testing with Firefox snap 2023-09-29 10:33:04 +02:00
wasm-sourcemap.py WASM work 2022-03-15 09:33:34 -04:00

README.md

veilid-wasm

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.

Limitations

Running Veilid in the browser via WebAssembly has some limitations:

Browser-based limitations

  1. TCP/UDP sockets are unavailable in the browser. This limits WASM nodes to communicating using WebSockets.
  2. 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.
  3. 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.
  4. 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.
  5. Because of browser security policy regarding WebSockets:
    1. ws:// only works on http:// sites
    2. wss:// only works on https:// site with SSL certificates.

Running WASM on HTTPS sites [Not currently implemented]

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.

Running unit tests

Prerequisites:

  • 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 is used to generate interop code between JavaScript and Rust, as well as basic TypeScript types.
  • 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 enables serialization/deserialization.