131 | } 132 | } 133 | -------------------------------------------------------------------------------- /examples/README.md: -------------------------------------------------------------------------------- 1 | # Examples 2 | 3 | This folder contains examples on how you could use `wasm-webterm` in your project. 4 | It also includes WebAssembly binaries for Coreutils and OpenSSL. 5 | 6 | Only the [webpack example (3)](./3-react-with-webpack) has enabled HTTPS headers, so it can use web workers. 7 | The examples [1 (directly with http-server)](./1-directly-in-the-browser) and [2 (parcel)](./2-nodejs-with-parcel) have instructions on how you could enable the HTTP headers yourself. 8 | 9 | -------------------------------------------------------------------------------- /examples/binaries/base32.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/base64.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/basename.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/cat.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/coreutils.wasm: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cryptool-org/wasm-webterm/7e6e7c7a32222a3898ace803f46e68352896da30/examples/binaries/coreutils.wasm -------------------------------------------------------------------------------- /examples/binaries/dirname.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/echo.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/env.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/ls.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/mkdir.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/mv.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/openssl.wasm: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cryptool-org/wasm-webterm/7e6e7c7a32222a3898ace803f46e68352896da30/examples/binaries/openssl.wasm -------------------------------------------------------------------------------- /examples/binaries/printf.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/pwd.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/sum.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /examples/binaries/wc.lnk: -------------------------------------------------------------------------------- 1 | coreutils -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "wasm-webterm", 3 | "version": "0.0.11", 4 | "description": "xterm.js addon to run webassembly binaries (emscripten + wasmer)", 5 | "files": [ 6 | "webterm.bundle.js", 7 | "webterm.bundle.js.map" 8 | ], 9 | "main": "webterm.bundle.js", 10 | "scripts": { 11 | "build": "webpack --mode production && rm -rf ./*.LICENSE.*", 12 | "dev": "webpack watch --mode development" 13 | }, 14 | "keywords": [ 15 | "xterm.js", 16 | "emscripten", 17 | "wasmer", 18 | "wasi", 19 | "wasm", 20 | "webassembly", 21 | "js", 22 | "javascript" 23 | ], 24 | "author": "cryptool.org", 25 | "license": "Apache-2.0", 26 | "dependencies": { 27 | "@wasmer/wasi": "^0.12.0", 28 | "@wasmer/wasm-transformer": "^0.12.0", 29 | "@wasmer/wasmfs": "^0.12.0", 30 | "comlink": "^4.4.2", 31 | "js-untar": "^2.0.0", 32 | "local-echo": "github:wavesoft/local-echo", 33 | "pako": "^2.1.0", 34 | "shell-quote": "^1.8.2", 35 | "xterm-addon-fit": "^0.5.0" 36 | }, 37 | "devDependencies": { 38 | "memfs": "^4.17.2", 39 | "prettier": "^3.5.3", 40 | "process": "^0.11.10", 41 | "webpack": "^5.99.9", 42 | "webpack-cli": "^6.0.1" 43 | }, 44 | "peerDependencies": { 45 | "xterm": ">4.9.0 <=4.19.0" 46 | } 47 | } 48 | -------------------------------------------------------------------------------- /src/History.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Shell history controller for `size` most-recent entries. 3 | */ 4 | export default class History { 5 | #size 6 | #entries = [] 7 | #cursor = 0 8 | 9 | constructor(size) { 10 | this.#size = size 11 | } 12 | 13 | get size() { 14 | return this.#size 15 | } 16 | 17 | // push an entry and maintain buffer size (drop oldest entry) 18 | push(entry) { 19 | // skip empty entries 20 | if (entry.trim() === "") return 21 | // skip duplicate entries 22 | const last = this.#entries[this.#entries.length - 1] 23 | if (entry === last) return 24 | 25 | this.#entries.push(entry) 26 | if (this.#entries.length > this.size) { 27 | this.#entries.shift() // drop oldest entry to keep size 28 | } 29 | 30 | this.#cursor = this.#entries.length 31 | } 32 | 33 | // rewind cursor to the latest entry 34 | rewind() { 35 | this.#cursor = this.#entries.length 36 | } 37 | 38 | // move cursor to the previous entry and return it 39 | getPrevious() { 40 | this.#cursor = Math.max(0, this.#cursor - 1) 41 | return this.#entries[this.#cursor] 42 | } 43 | 44 | // move cursor to the next entry and return it 45 | getNext() { 46 | this.#cursor = Math.min(this.#entries.length, this.#cursor + 1) 47 | return this.#entries[this.#cursor] 48 | } 49 | } 50 | -------------------------------------------------------------------------------- /src/LineBuffer.js: -------------------------------------------------------------------------------- 1 | export default class LineBuffer { 2 | #outputFn 3 | #buffer 4 | 5 | constructor(outputFn) { 6 | if (typeof outputFn !== "function") { 7 | throw new ValueError( 8 | `'outputFn' must be a function but is '${typeof outputFn}'!` 9 | ) 10 | } 11 | this.#outputFn = outputFn 12 | this.#buffer = "" 13 | } 14 | 15 | write(value) { 16 | // numbers are interpreted as char codes -> convert to string 17 | if (typeof value == "number") value = String.fromCharCode(value) 18 | 19 | this.#buffer += value 20 | 21 | let idx = this.#buffer.indexOf("\n") 22 | while (idx >= 0) { 23 | this.#outputFn(this.#buffer.slice(0, idx + 1)) 24 | this.#buffer = this.#buffer.slice(idx + 1) 25 | idx = this.#buffer.indexOf("\n") 26 | } 27 | } 28 | 29 | flush() { 30 | if (this.#buffer.length > 0) { 31 | this.#outputFn(this.#buffer) 32 | this.#buffer = "" 33 | } 34 | } 35 | } 36 | -------------------------------------------------------------------------------- /src/WapmFetchUtil.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Script to fetch wasmer binaries from wapm.io -- Code taken from: 3 | * https://github.com/wasmerio/wasmer-js/tree/0.x/packages/wasm-terminal 4 | */ 5 | 6 | // some imports need to be lowered 7 | // import { lowerI64Imports } from "@wasmer/wasm-transformer" 8 | 9 | // packages come as .tar.gz 10 | import pako from "pako" // gunzip 11 | import untar from "js-untar" // untar 12 | 13 | class WapmFetchUtil { 14 | static WAPM_GRAPHQL_QUERY = `query shellGetCommandQuery($command: String!) { 15 | command: getCommand(name: $command) { 16 | command 17 | module { 18 | name 19 | abi 20 | source 21 | } 22 | packageVersion { 23 | version 24 | package { 25 | name 26 | displayName 27 | } 28 | filesystem { 29 | wasm 30 | host 31 | } 32 | distribution { 33 | downloadUrl 34 | } 35 | modules { 36 | name 37 | publicUrl 38 | abi 39 | } 40 | commands { 41 | command 42 | module { 43 | name 44 | abi 45 | source 46 | } 47 | } 48 | } 49 | } 50 | }` 51 | 52 | static getCommandFromWAPM = async (commandName) => { 53 | const fetchResponse = await fetch("https://registry.wapm.io/graphql", { 54 | method: "POST", 55 | mode: "cors", 56 | headers: { 57 | Accept: "application/json", 58 | "Content-Type": "application/json", 59 | }, 60 | body: JSON.stringify({ 61 | operationName: "shellGetCommandQuery", 62 | query: WapmFetchUtil.WAPM_GRAPHQL_QUERY, 63 | variables: { 64 | command: commandName, 65 | }, 66 | }), 67 | }) 68 | 69 | const response = await fetchResponse.json() 70 | 71 | if (response && response.data && response.data.command) 72 | return response.data.command 73 | else throw new Error(`command not found ${commandName}`) 74 | } 75 | 76 | static fetchCommandFromWAPM = async ({ args, env }) => { 77 | const commandName = args[0] 78 | const command = await WapmFetchUtil.getCommandFromWAPM(commandName) 79 | if (command.module.abi !== "wasi") 80 | throw new Error( 81 | `Only WASI modules are supported. The "${commandName}" command is using the "${command.module.abi}" ABI.` 82 | ) 83 | return command 84 | } 85 | 86 | static WAPM_PACKAGE_QUERY = `query shellGetPackageQuery($name: String!, $version: String) { 87 | packageVersion: getPackageVersion(name: $name, version: $version) { 88 | version 89 | package { 90 | name 91 | displayName 92 | } 93 | filesystem { 94 | wasm 95 | host 96 | } 97 | distribution { 98 | downloadUrl 99 | } 100 | modules { 101 | name 102 | publicUrl 103 | abi 104 | } 105 | commands { 106 | command 107 | module { 108 | name 109 | abi 110 | source 111 | } 112 | } 113 | } 114 | }` 115 | 116 | static execWapmQuery = async (query, variables) => { 117 | const fetchResponse = await fetch("https://registry.wapm.io/graphql", { 118 | method: "POST", 119 | mode: "cors", 120 | headers: { 121 | Accept: "application/json", 122 | "Content-Type": "application/json", 123 | }, 124 | body: JSON.stringify({ 125 | query, 126 | variables, 127 | }), 128 | }) 129 | 130 | const response = await fetchResponse.json() 131 | if (response && response.data) return response.data 132 | } 133 | 134 | static getBinaryFromUrl = async (url) => { 135 | const fetched = await fetch(url) 136 | const buffer = await fetched.arrayBuffer() 137 | return new Uint8Array(buffer) 138 | } 139 | 140 | static getWAPMPackageFromPackageName = async (packageName) => { 141 | let version 142 | 143 | if (packageName.indexOf("@") > -1) { 144 | const splitted = packageName.split("@") 145 | packageName = splitted[0] 146 | version = splitted[1] 147 | } 148 | 149 | let data = await WapmFetchUtil.execWapmQuery( 150 | WapmFetchUtil.WAPM_PACKAGE_QUERY, 151 | { name: packageName, version: version } 152 | ) 153 | 154 | if (data && data.packageVersion) return data.packageVersion 155 | else throw new Error(`Package not found in the registry ${packageName}`) 156 | } 157 | 158 | static getWasmBinaryFromUrl = async (url) => { 159 | const fetched = await fetch(url) 160 | const buffer = await fetched.arrayBuffer() 161 | return new Uint8Array(buffer) 162 | } 163 | 164 | static getWasmBinaryFromCommand = async (programName) => { 165 | // fetch command from wapm.io (includes path to binary) 166 | const command = await WapmFetchUtil.fetchCommandFromWAPM({ 167 | args: [programName], 168 | }) 169 | 170 | // fetch binary from wapm and extract wasmer files from .tar.gz 171 | const binary = await WapmFetchUtil.getBinaryFromUrl( 172 | command.packageVersion.distribution.downloadUrl 173 | ) 174 | const inflatedBinary = pako.inflate(binary) 175 | const wapmFiles = await untar(inflatedBinary.buffer) 176 | const wasmerFiles = wapmFiles.filter((wapmFile) => 177 | wapmFile.name.split("/").pop().endsWith(".wasm") 178 | ) 179 | 180 | // console.log("wasmerFiles", wasmerFiles) 181 | 182 | // check if we got exactly one binary and then lower its imports 183 | if (wasmerFiles.length > 1) 184 | throw Error("more than 1 wasm file, don't know what to do :D") 185 | const wasmModule = wasmerFiles[0].buffer // await lowerI64Imports(wasmerFiles[0].buffer) 186 | 187 | // todo: there is a file "wapm.toml" that contains info about which command uses which module/binary 188 | 189 | return wasmModule 190 | } 191 | } 192 | 193 | export default WapmFetchUtil 194 | -------------------------------------------------------------------------------- /src/WasmWebTerm.js: -------------------------------------------------------------------------------- 1 | import { proxy, wrap } from "comlink" 2 | 3 | import { FitAddon } from "xterm-addon-fit" 4 | import XtermEchoAddon from "local-echo" 5 | import parse from "shell-quote/parse" 6 | import { inflate } from "pako" // fallback for DecompressionStream API (free as its used in WapmFetchUtil) 7 | 8 | import LineBuffer from "./LineBuffer" 9 | import History from "./History" 10 | import WasmWorkerRAW from "./runners/WasmWorker" // will be prebuilt using webpack 11 | import { 12 | default as PromptsFallback, 13 | MODULE_ID as WasmRunnerID, // get the id of this module in the final webpack bundle 14 | } from "./runners/WasmRunner" 15 | import WapmFetchUtil from "./WapmFetchUtil" 16 | 17 | class WasmWebTerm { 18 | isRunningCommand 19 | 20 | onActivated 21 | onDisposed 22 | 23 | onFileSystemUpdate 24 | onBeforeCommandRun 25 | onCommandRunFinish 26 | 27 | _xterm 28 | _xtermEcho 29 | _xtermPrompt 30 | 31 | _worker 32 | _wasmRunner // prompts fallback 33 | 34 | _jsCommands 35 | _wasmModules 36 | _wasmFsFiles 37 | 38 | _stdoutBuffer 39 | _stderrBuffer 40 | 41 | _outputBuffer 42 | _lastOutputTime 43 | 44 | constructor(wasmBinaryPath) { 45 | this.wasmBinaryPath = wasmBinaryPath 46 | 47 | this._jsCommands = new Map() // js commands and their callback functions 48 | this.isRunningCommand = false // allow running only 1 command in parallel 49 | 50 | this._worker = false // fallback (do not use worker until it is initialized) 51 | this._wasmModules = [] // [{ name: "abc", type: "emscripten|wasmer", module: WebAssembly.Module, [runtime: Blob] }] 52 | this._wasmFsFiles = [] // files created during wasm execution (will be written to wasm runtime's FS) 53 | 54 | this._outputBuffer = "" // buffers outputs to determine if it ended with line break 55 | this._lastOutputTime = 0 // can be used for guessing if output is complete on stdin calls 56 | 57 | this.onActivated = () => {} // can be overwritten to know when activation is complete 58 | this.onDisposed = () => {} // can be overwritten to know when disposition is complete 59 | 60 | this.onFileSystemUpdate = () => {} // can be overwritten to handle emscr file changes 61 | this.onBeforeCommandRun = () => {} // can be overwritten to show load animation (etc) 62 | this.onCommandRunFinish = () => {} // can be overwritten to hide load animation (etc) 63 | 64 | // check if browser support for web working is available 65 | if ( 66 | ![typeof Worker, typeof SharedArrayBuffer, typeof Atomics].includes( 67 | "undefined" 68 | ) 69 | ) 70 | // if yes, initialize worker 71 | this._initWorker() 72 | // if no support -> use prompts as fallback 73 | else this._wasmRunner = new PromptsFallback() 74 | 75 | this._suppressOutputs = false 76 | window.term = this // todo: debug 77 | } 78 | 79 | /* xterm.js addon life cycle */ 80 | 81 | async activate(xterm) { 82 | this._xterm = xterm 83 | 84 | // create xterm addon to fit size 85 | this._xtermFitAddon = new FitAddon() 86 | this._xtermFitAddon.activate(this._xterm) 87 | 88 | // fit xterm size to container 89 | setTimeout(() => this._xtermFitAddon.fit(), 1) 90 | 91 | // handle container resize 92 | window.addEventListener("resize", () => { 93 | this._xtermFitAddon.fit() 94 | }) 95 | 96 | // handle module drag and drop 97 | setTimeout(() => this._initWasmModuleDragAndDrop(), 1) 98 | 99 | // set xterm prompt 100 | this._xtermPrompt = async () => "$ " 101 | // async to be able to fetch sth here 102 | 103 | // create xterm local echo addon 104 | this._xtermEcho = new XtermEchoAddon(null, { historySize: 1000 }) 105 | this._xtermEcho.activate(this._xterm) 106 | 107 | // patch history controller 108 | this._xtermEcho.history = new History(this._xtermEcho.history.size || 10) 109 | 110 | // register available js commands 111 | this.registerJsCommand("help", async function* (argv) { 112 | yield "todo: show helping things\n" 113 | }) 114 | this.registerJsCommand("about", async (argv) => { 115 | return ( 116 | "Wasm-WebTerm version " + 117 | __VERSION__ + 118 | ".\nBackend: " + 119 | (this._worker ? "WebWorker" : "Prompts Fallback") + 120 | ".\n" 121 | ) 122 | }) 123 | this.registerJsCommand( 124 | "clear", 125 | async (argv) => await this.printWelcomeMessagePlusControlSequences() 126 | ) 127 | 128 | // if using webworker -> wait until initialized 129 | if (this._worker instanceof Promise) await this._worker 130 | 131 | // register xterm data handler for Ctrl+C 132 | this._xterm.onData((data) => this._onXtermData(data)) 133 | 134 | // notify that we're ready 135 | await this.onActivated() 136 | 137 | // write welcome message to terminal 138 | this._xterm.writeln( 139 | await this.printWelcomeMessagePlusControlSequences(), 140 | 141 | // callback for when welcome message was printed 142 | () => { 143 | // start REPL 144 | this.repl() 145 | 146 | // focus terminal cursor 147 | setTimeout(() => this._xterm.focus(), 1) 148 | } 149 | ) 150 | } 151 | 152 | async dispose() { 153 | await this._xtermEcho.dispose() 154 | await this._xtermFitAddon.dispose() 155 | if (this._worker) this._terminateWorker() 156 | await this.onDisposed() 157 | } 158 | 159 | /* js command handling */ 160 | 161 | registerJsCommand(name, callback, autocomplete) { 162 | this._jsCommands.set(name, { name, callback, autocomplete }) 163 | return this // to be able to stack these calls 164 | } 165 | 166 | unregisterJsCommand(name) { 167 | return this._jsCommands.delete(name) 168 | } 169 | 170 | get jsCommands() { 171 | return this._jsCommands 172 | } 173 | 174 | /* read eval print loop */ 175 | 176 | async repl() { 177 | try { 178 | // read 179 | const prompt = await this._xtermPrompt() 180 | const line = await this._xtermEcho.read(prompt) 181 | 182 | // empty input -> prompt again 183 | if (line.trim() == "") return this.repl() 184 | 185 | // give user possibility to exec sth before run 186 | await this.onBeforeCommandRun() 187 | 188 | // print newline before 189 | this._xterm.write("\r\n") 190 | 191 | // eval and print 192 | await this.runLine(line) 193 | 194 | // print extra newline if output does not end with one 195 | if (this._outputBuffer.slice(-1) != "\n") this._xterm.write("\u23CE\r\n") 196 | 197 | // print newline after 198 | this._xterm.write("\r\n") 199 | 200 | // give user possibility to run sth after exec 201 | await this.onCommandRunFinish() 202 | 203 | // loop 204 | this.repl() 205 | } catch (e) { 206 | /* console.error("Error during REPL:", e) */ 207 | } 208 | } 209 | 210 | /* parse line as commands and handle them */ 211 | _parseCommands(line) { 212 | let usesEnvironmentVars = false 213 | let usesBashFeatures = false 214 | 215 | // parse line into tokens (respect escaped spaces and quotation marks) 216 | const commandLine = parse(line, (_key) => { 217 | usesEnvironmentVars = true 218 | return undefined 219 | }) 220 | 221 | const commands = [] 222 | let cmd = [] 223 | 224 | splitter: { 225 | for (let idx = 0; idx < commandLine.length; ++idx) { 226 | const item = commandLine[idx] 227 | 228 | if (typeof item === "string") { 229 | if (cmd.length === 0 && item.match(/^\w+=.*$/)) { 230 | usesEnvironmentVars = true 231 | continue 232 | } else { 233 | cmd.push(item) 234 | } 235 | } else { 236 | switch (item.op) { 237 | case "|": 238 | commands.push(cmd) 239 | cmd = [] 240 | break 241 | default: 242 | usesBashFeatures = true 243 | console.error("Unsupported shell operator:", item.op) 244 | break splitter 245 | } 246 | } 247 | } 248 | } 249 | commands.push(cmd) 250 | 251 | if (usesEnvironmentVars) { 252 | this._stderr( 253 | "\x1b[1m[\x1b[33mWARN\x1b[39m]\x1b[0m Environment variables are not supported!\n" 254 | ) 255 | } 256 | if (usesBashFeatures) { 257 | this._stderr( 258 | "\x1b[1m[\x1b[33mWARN\x1b[39m]\x1b[0m Advanced bash features are not supported! Only the pipe '|' works for now.\n" 259 | ) 260 | } 261 | 262 | return commands 263 | } 264 | 265 | async runLine(line) { 266 | try { 267 | let stdinPreset = null 268 | this._suppressOutputs = false 269 | 270 | const commandsInLine = this._parseCommands(line) 271 | for (const [index, argv] of commandsInLine.entries()) { 272 | // split into command name and argv 273 | const commandName = argv.shift() 274 | const command = this._jsCommands.get(commandName) 275 | 276 | // try user registered js commands first 277 | if (typeof command?.callback == "function") { 278 | // todo: move this to a method like "runJsCommand"? 279 | 280 | // call registered user function 281 | const result = command.callback(argv, stdinPreset) 282 | let output // where user function outputs are stored 283 | 284 | /** 285 | * user functions are another word for custom js 286 | * commands and can pass outputs in various ways: 287 | * 288 | * 1) return value normally via "return" 289 | * 2) pass value through promise resolve() / async 290 | * 3) yield values via generator functions 291 | */ 292 | 293 | // await promises if any (2) 294 | if (result.then) output = ((await result) || "").toString() 295 | // await yielding generator functions (3) 296 | else if (result.next) 297 | for await (let data of result) 298 | output = output == null ? data : output + data 299 | // default: when functions return "normally" (1) 300 | else output = result.toString() 301 | 302 | // if is last command in pipe -> print output to xterm 303 | if (index == commandsInLine.length - 1) this._stdout(output) 304 | else stdinPreset = output || null // else -> use output as stdinPreset 305 | 306 | // todo: make it possible for user functions to use stdERR. 307 | // exceptions? they end function execution.. 308 | } 309 | 310 | // otherwise try wasm commands 311 | else if (command == undefined) { 312 | // if is not last command in pipe 313 | if (index < commandsInLine.length - 1) { 314 | const output = await this.runWasmCommandHeadless( 315 | commandName, 316 | argv, 317 | stdinPreset 318 | ) 319 | stdinPreset = output.stdout // apply last stdout to next stdin 320 | } 321 | 322 | // if is last command -> run normally and reset stdinPreset 323 | else { 324 | await this.runWasmCommand(commandName, argv, stdinPreset) 325 | stdinPreset = null 326 | } 327 | } 328 | 329 | // command is defined but has no function -> can not handle 330 | else 331 | console.error("command is defined but has no function:", commandName) 332 | } 333 | } catch (e) { 334 | // catch errors (print to terminal and developer console) 335 | if (this._outputBuffer.slice(-1) != "\n") this._stderr("\n") 336 | this._stderr(`\x1b[1m[\x1b[31mERROR\x1b[39m]\x1b[0m ${e.toString()}\n`) 337 | console.error("Error running line:", e) 338 | } 339 | } 340 | 341 | /* running single wasm commands */ 342 | 343 | runWasmCommand(programName, argv, stdinPreset, onFinishCallback) { 344 | console.log("called runWasmCommand:", programName, argv) 345 | 346 | if (this.isRunningCommand) throw "WasmWebTerm is already running a command" 347 | else this.isRunningCommand = true 348 | 349 | // enable outputs if they were suppressed 350 | this._suppressOutputs = false 351 | this._outputBuffer = "" 352 | 353 | // define callback for when command has finished 354 | const onFinish = proxy(async (files) => { 355 | console.log("command finished:", programName, argv) 356 | 357 | // enable commands to run again 358 | this.isRunningCommand = false 359 | 360 | // store created files 361 | this._wasmFsFiles = files 362 | await this.onFileSystemUpdate(this._wasmFsFiles) 363 | 364 | // wait until outputs are rendered 365 | await this._waitForOutputPause() 366 | 367 | // flush out any pending outputs 368 | this._stdoutBuffer.flush() 369 | this._stderrBuffer.flush() 370 | 371 | // wait until the rest is rendered 372 | this._waitForOutputPause().then(() => { 373 | // notify caller that command run is over 374 | if (typeof onFinishCallback == "function") onFinishCallback() 375 | 376 | // resolve await from shell 377 | this._runWasmCommandPromise?.resolve() 378 | }) 379 | }) 380 | 381 | // define callback for when errors occur 382 | const onError = proxy((value) => this._stderr(value + "\n")) 383 | 384 | // get or initialize wasm module 385 | this._stdout("loading web assembly ...") 386 | this._getOrFetchWasmModule(programName) 387 | .then((wasmModule) => { 388 | // clear last line 389 | this._xterm.write("\x1b[2K\r") 390 | 391 | // check if we can run on worker 392 | if (this._worker) 393 | // delegate command execution to worker thread 394 | this._worker.runCommand( 395 | programName, 396 | wasmModule.module, 397 | wasmModule.type, 398 | argv, 399 | this._stdinProxy, 400 | this._stdoutProxy, 401 | this._stderrProxy, 402 | this._wasmFsFiles, 403 | onFinish, 404 | onError, 405 | null, 406 | stdinPreset, 407 | wasmModule.runtime 408 | ) 409 | // if not -> fallback with prompts 410 | // start execution on the MAIN thread (freezes terminal) 411 | else 412 | this._wasmRunner.runCommand( 413 | programName, 414 | wasmModule.module, 415 | wasmModule.type, 416 | argv, 417 | null, 418 | this._stdoutProxy, 419 | this._stderrProxy, 420 | this._wasmFsFiles, 421 | onFinish, 422 | onError, 423 | null, 424 | stdinPreset, 425 | wasmModule.runtime 426 | ) 427 | }) 428 | 429 | // catch errors (command not running anymore + reject (returns to shell)) 430 | .catch((e) => { 431 | this.isRunningCommand = false 432 | this._runWasmCommandPromise?.reject(e) 433 | }) 434 | 435 | // return promise (makes shell await) 436 | return new Promise( 437 | (resolve, reject) => (this._runWasmCommandPromise = { resolve, reject }) 438 | ) 439 | } 440 | 441 | runWasmCommandHeadless(programName, argv, stdinPreset, onFinishCallback) { 442 | if (this.isRunningCommand) throw "WasmWebTerm is already running a command" 443 | else this.isRunningCommand = true 444 | 445 | // promise for resolving / rejecting command execution 446 | let runWasmCommandHeadlessPromise = { resolve: () => {}, reject: () => {} } 447 | 448 | // define callback for when command has finished 449 | const onFinish = proxy((outBuffers) => { 450 | // enable commands to run again 451 | this.isRunningCommand = false 452 | 453 | // flush outputs 454 | this._stdoutBuffer.flush() 455 | this._stderrBuffer.flush() 456 | 457 | // call on finish callback 458 | if (typeof onFinishCallback == "function") onFinishCallback(outBuffers) 459 | 460 | // resolve promise 461 | runWasmCommandHeadlessPromise.resolve(outBuffers) 462 | }) 463 | 464 | // define callback for when errors occur 465 | const onError = proxy((value) => this._stderr(value + "\n")) 466 | 467 | // define callback for onSuccess (contains files) 468 | const onSuccess = proxy(() => {}) // not used currently 469 | 470 | // get or initialize wasm module 471 | this._getOrFetchWasmModule(programName) 472 | .then((wasmModule) => { 473 | if (this._worker) 474 | // check if we can run on worker 475 | 476 | // delegate command execution to worker thread 477 | this._worker.runCommandHeadless( 478 | programName, 479 | wasmModule.module, 480 | wasmModule.type, 481 | argv, 482 | this._wasmFsFiles, 483 | onFinish, 484 | onError, 485 | onSuccess, 486 | stdinPreset, 487 | wasmModule.runtime 488 | ) 489 | // if not -> use fallback 490 | // start execution on the MAIN thread (freezes terminal) 491 | else 492 | this._wasmRunner.runCommandHeadless( 493 | programName, 494 | wasmModule.module, 495 | wasmModule.type, 496 | argv, 497 | this._wasmFsFiles, 498 | onFinish, 499 | onError, 500 | onSuccess, 501 | stdinPreset, 502 | wasmModule.runtime 503 | ) 504 | }) 505 | 506 | // catch errors (command not running anymore + reject promise) 507 | .catch((e) => { 508 | this.isRunningCommand = false 509 | runWasmCommandHeadlessPromise.reject(e) 510 | }) 511 | 512 | // return promise (makes shell await) 513 | return new Promise( 514 | (resolve, reject) => (runWasmCommandHeadlessPromise = { resolve, reject }) 515 | ) 516 | } 517 | 518 | /* wasm module handling */ 519 | 520 | _getOrFetchWasmModule(programName) { 521 | return new Promise(async (resolve, reject) => { 522 | let wasmModule, 523 | wasmBinary, 524 | localBinaryFound = false 525 | 526 | // check if there is an initialized module already 527 | this._wasmModules.forEach((moduleObj) => { 528 | if (moduleObj.name == programName) wasmModule = moduleObj 529 | }) 530 | 531 | // if a module was found -> resolve 532 | if (wasmModule?.module instanceof WebAssembly.Module) resolve(wasmModule) 533 | else 534 | try { 535 | // if none is found -> initialize a new one 536 | 537 | // create wasm module object (to resolve and to store) 538 | wasmModule = { 539 | name: programName, 540 | type: "emscripten", 541 | module: undefined, 542 | } 543 | 544 | // try to find local wasm binary 545 | // (only if wasmBinaryPath is provided, otherwise use wapm directly) 546 | if (this.wasmBinaryPath != undefined) { 547 | // try to fetch local wasm binaries first 548 | const localBinaryResponse = await fetch( 549 | this.wasmBinaryPath + "/" + programName + ".wasm" 550 | ) 551 | wasmBinary = await localBinaryResponse.arrayBuffer() 552 | 553 | // validate if localBinaryResponse contains a wasm binary 554 | if (localBinaryResponse?.ok && WebAssembly.validate(wasmBinary)) { 555 | // try to fetch emscripten js runtime 556 | const jsRuntimeResponse = await fetch( 557 | this.wasmBinaryPath + "/" + programName + ".js" 558 | ) 559 | if (jsRuntimeResponse?.ok) { 560 | // read js runtime from response 561 | const jsRuntimeCode = await jsRuntimeResponse.arrayBuffer() 562 | 563 | // check if the first char of the response is not "<" 564 | // (because dumb parcel does not return http errors but an html page) 565 | const firstChar = String.fromCharCode( 566 | new Uint8Array(jsRuntimeCode).subarray(0, 1).toString() 567 | ) 568 | if (firstChar != "<") 569 | // set this module's runtime 570 | wasmModule.runtime = jsRuntimeCode 571 | } 572 | 573 | // if no valid js runtime was found -> it's considered a wasmer binary 574 | if (!wasmModule.runtime) wasmModule.type = "wasmer" 575 | 576 | // local binary was found -> do not fetch wapm 577 | localBinaryFound = true 578 | } 579 | 580 | // if none was found or it was invalid -> try for a .lnk file 581 | else { 582 | // explanation: .lnk files can contain a different module/runtime name. 583 | // this enables `echo` and `ls` to both use `coreutils.wasm`, for example. 584 | 585 | // try to fetch .lnk file 586 | const linkResponse = await fetch( 587 | this.wasmBinaryPath + "/" + programName + ".lnk" 588 | ) 589 | if (linkResponse?.ok) { 590 | // read new program name from .lnk file 591 | const linkedProgramName = await linkResponse.text() 592 | const linkDestination = 593 | this.wasmBinaryPath + "/" + linkedProgramName + ".wasm" 594 | 595 | // try to fetch the new binary 596 | const linkedBinaryResponse = await fetch(linkDestination) 597 | if (linkedBinaryResponse?.ok) { 598 | // read binary from response 599 | wasmBinary = await linkedBinaryResponse.arrayBuffer() 600 | 601 | // validate if linkedBinaryResponse contains a wasm binary 602 | if (WebAssembly.validate(wasmBinary)) { 603 | // try to fetch emscripten js runtime 604 | const jsRuntimeResponse = await fetch( 605 | this.wasmBinaryPath + "/" + linkedProgramName + ".js" 606 | ) 607 | if (jsRuntimeResponse?.ok) { 608 | // todo: note that this code is redundant, maybe use a function? 609 | 610 | // read js runtime from response 611 | const jsRuntimeCode = 612 | await jsRuntimeResponse.arrayBuffer() 613 | 614 | // check if the first char of the response is not "<" 615 | // (because dumb parcel does not return http errors but an html page) 616 | const firstChar = String.fromCharCode( 617 | new Uint8Array(jsRuntimeCode).subarray(0, 1).toString() 618 | ) 619 | if (firstChar != "<") 620 | // set this module's runtime 621 | wasmModule.runtime = jsRuntimeCode 622 | } 623 | 624 | // if no valid js runtime was found -> it's considered a wasmer binary 625 | if (!wasmModule.runtime) wasmModule.type = "wasmer" 626 | 627 | // local binary was found -> do not fetch wapm 628 | localBinaryFound = true 629 | } 630 | } 631 | } 632 | } 633 | } 634 | 635 | // if no local binary was found -> fetch from wapm.io 636 | if (!localBinaryFound) { 637 | wasmBinary = 638 | await WapmFetchUtil.getWasmBinaryFromCommand(programName) 639 | wasmModule.type = "wasmer" 640 | } 641 | 642 | // compile fetched bytes into wasm module 643 | wasmModule.module = await WebAssembly.compile(wasmBinary) 644 | 645 | // store compiled module 646 | this._wasmModules.push(wasmModule) 647 | 648 | // continue execution 649 | resolve(wasmModule) 650 | } catch (e) { 651 | reject(e) 652 | } 653 | }) 654 | } 655 | 656 | _initWasmModuleDragAndDrop() { 657 | // event handler for when user starts to drag file 658 | this._xterm.element.addEventListener("dragenter", (e) => { 659 | this._xterm.element.style.opacity = "0.8" 660 | }) 661 | 662 | // needed for drop event to be fired on div 663 | this._xterm.element.addEventListener("dragover", (e) => { 664 | e.preventDefault() 665 | this._xterm.element.style.opacity = "0.8" 666 | }) 667 | 668 | // event handler for when user stops to drag file 669 | this._xterm.element.addEventListener("dragleave", (e) => { 670 | this._xterm.element.style.opacity = "" 671 | }) 672 | 673 | // event handler for when the user drops the file 674 | this._xterm.element.addEventListener( 675 | "drop", 676 | async (e) => { 677 | e.preventDefault() 678 | let files = [] 679 | 680 | if (e.dataTransfer.items) 681 | // read files from .items 682 | for (let i = 0; i < e.dataTransfer.items.length; i++) 683 | if (e.dataTransfer.items[i].kind == "file") 684 | files.push(e.dataTransfer.items[i].getAsFile()) 685 | // read files from .files (other browsers) 686 | else 687 | for (let i = 0; i < e.dataTransfer.files.length; i++) 688 | files.push(e.dataTransfer.files[i]) 689 | 690 | // parse dropped files into modules 691 | for (let i = 0; i < files.length; i++) { 692 | const file = files[i] 693 | if (file.name.endsWith(".wasm")) { 694 | // todo: also support dropping .lnk files? 695 | 696 | const programName = file.name.replace(/\.wasm$/, "") 697 | 698 | // remove existing modules with that name 699 | this._wasmModules = this._wasmModules.filter( 700 | (mod) => mod.name != programName 701 | ) 702 | 703 | // if has .js file -> it's an emscripten binary 704 | if (files.some((f) => f.name == programName + ".js")) { 705 | // load emscripten js runtime and compile emscripten wasm binary 706 | const emscrJsRuntime = files.find( 707 | (f) => f.name == programName + ".js" 708 | ) 709 | const emscrWasmModule = await WebAssembly.compile( 710 | await file.arrayBuffer() 711 | ) 712 | 713 | // add compiled emscripten module to this._wasmModules 714 | this._wasmModules.push({ 715 | name: programName, 716 | type: "emscripten", 717 | runtime: await emscrJsRuntime.arrayBuffer(), 718 | module: emscrWasmModule, 719 | }) 720 | 721 | alert("Emscripten Wasm Module added: " + programName) 722 | } else { 723 | // if not -> its considered a wasmer binary 724 | 725 | // compile wasmer module and store in this._wasmModules 726 | const wasmerModule = await WebAssembly.compile( 727 | await file.arrayBuffer() 728 | ) 729 | this._wasmModules.push({ 730 | name: programName, 731 | type: "wasmer", 732 | module: wasmerModule, 733 | }) 734 | 735 | alert("WASI Module added: " + programName) 736 | } 737 | } 738 | } 739 | 740 | this._xterm.element.style.opacity = "" 741 | }, 742 | false 743 | ) 744 | } 745 | 746 | /* worker execution flow */ 747 | 748 | _initWorker() { 749 | this._worker = new Promise(async (resolve) => { 750 | // init buffers for pausing worker and passing stdin values 751 | this._pauseBuffer = new Int32Array( 752 | new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 1) 753 | ) // 1 bit to shift 754 | this._stdinBuffer = new Int32Array( 755 | new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 1000) 756 | ) // 1000 chars buffer 757 | 758 | // create blob including webworker and its dependencies 759 | const workerSource = fetch(WasmWorkerRAW).then((response) => { 760 | if ("DecompressionStream" in self) { 761 | const stream = response.body.pipeThrough( 762 | new DecompressionStream("gzip") 763 | ) 764 | const decompressed = new Response(stream) 765 | return decompressed.text() 766 | } else { 767 | return response.bytes().then((data) => inflate(data)) 768 | } 769 | }) 770 | 771 | // HACK: Forward all modules for the `WasmRunner`(`PromptsFallback`) to the worker 772 | // instead of bundling them directly. This saves about 90 KiB by not serializing 773 | // these dependencies twice. This works fine, since we already use the identical 774 | // module already as a fallback. 775 | const extraModules = {} 776 | try { 777 | const webpackModuleIds = Object.keys(__webpack_modules__) 778 | let dependencies = [WasmRunnerID] // start with the `WasmRunner` module 779 | for ( 780 | let dep = dependencies.shift(); 781 | dep != undefined; 782 | dep = dependencies.shift() 783 | ) { 784 | // put the module into the list of modules to forward 785 | const mod = __webpack_modules__[dep] 786 | extraModules[dep] = mod 787 | 788 | // parse module for imports of other module dependencies (like `r(MODULE_ID)`) 789 | const matches = mod.toString().matchAll(/\br$(\d+)$/g) 790 | for (const match of matches) { 791 | if (webpackModuleIds.includes(match[1])) dependencies.push(match[1]) 792 | } 793 | } 794 | } catch (err) { 795 | // Could not collect the `WasmRunner` module and its dependencies for forwarding 796 | console.error( 797 | `Cannot collect the \`WasmRunner\` module and its dependencies for use in the Worker: ${err}` 798 | ) 799 | console.error( 800 | "Falling back to excuting `WasmRunner` in the PromptsFallback" 801 | ) 802 | 803 | // -> use prompts as fallback 804 | this._wasmRunner = new PromptsFallback() 805 | this._worker = false 806 | resolve(this._worker) 807 | 808 | return 809 | } 810 | 811 | // prepend source of collected modules as well as the ID for the 812 | // `WasmRunner` module to the original worker source 813 | let prelude = "self._modules={" 814 | for (const [id, module] of Object.entries(extraModules)) { 815 | prelude += `${id}:${module.toString()},` 816 | } 817 | prelude += `};self.WasmRunnerID=${WasmRunnerID}\n` 818 | 819 | const blob = new Blob([prelude, await workerSource], { 820 | type: "application/javascript", 821 | }) 822 | 823 | // init webworker from blob (no separate file, no cross-origin problems) 824 | this._workerRAW = new Worker(URL.createObjectURL(blob)) 825 | const WasmWorker = wrap(this._workerRAW) 826 | this._worker = await new WasmWorker(this._pauseBuffer, this._stdinBuffer) 827 | 828 | resolve(this._worker) // webworker is now initialized 829 | }) 830 | } 831 | 832 | _resumeWorker() { 833 | console.log("resuming worker (request)") 834 | Atomics.store(this._pauseBuffer, 0, 0) // mem[0] = 0 (means do not hold) 835 | Atomics.notify(this._pauseBuffer, 0) // awake waiting 836 | } 837 | 838 | _terminateWorker() { 839 | console.log("called terminate worker") 840 | this._workerRAW?.terminate() 841 | } 842 | 843 | _waitForOutputPause(pauseDuration = 80, interval = 20) { 844 | // note: timeout because web worker outputs are not always rendered to 845 | // the term directly. therefore we wait until we guess it's all there. 846 | return new Promise((resolve) => { 847 | const timeout = () => { 848 | setTimeout(() => { 849 | // if there has been output in the last pauseDuration -> run again 850 | if (this._lastOutputTime > Date.now() - pauseDuration) timeout() 851 | // if not -> resolve 852 | else resolve() 853 | }, interval) 854 | } 855 | timeout() 856 | }) 857 | } 858 | 859 | /* input output handling -> web worker */ 860 | 861 | _setStdinBuffer(string) { 862 | for (let i = 0; i < this._stdinBuffer.length; i++) 863 | this._stdinBuffer[i] = string[i] ? string[i].charCodeAt(0) : 0 // 0 = null (empty bits = end of string) 864 | } 865 | 866 | _stdinProxy = proxy((message) => { 867 | this._waitForOutputPause().then(async () => { 868 | console.log("called _stdinProxy", message) 869 | 870 | // flush outputs (to show the prompt) 871 | this._stdoutBuffer.flush() 872 | this._stderrBuffer.flush() 873 | 874 | // read input until RETURN (LF), CTRL+D (EOF), or CTRL+C 875 | const input = await new Promise((resolve, reject) => { 876 | let buffer = "" 877 | const handler = this._xterm.onData((data) => { 878 | // CTRL + C -> return without data 879 | if (data == "\x03") { 880 | this._xterm.write("^C") 881 | handler.dispose() 882 | return resolve("") 883 | } 884 | // CTRL + D -> return input buffer 885 | else if (data == "\x04") { 886 | handler.dispose() 887 | return resolve(buffer) 888 | } 889 | 890 | // map return to '\n' 891 | if (data == "\r") data = "\n" 892 | // map backspace to CTRL+H 893 | else if (data == "\x7f") data = "\x08" 894 | 895 | // add character or delete last one 896 | if (data == "\x08") buffer = buffer.slice(0, -1) 897 | else buffer += data 898 | 899 | // line complete -> return the input buffer 900 | if (data == "\n") { 901 | // only echo the linebreak when there is no prompt (i.e. we assume multi-line input) 902 | if (!message) this._xterm.write("\r\n") 903 | 904 | handler.dispose() 905 | return resolve(buffer) 906 | } 907 | 908 | // echo input back (special handling for backspace and escape sequences) 909 | if (data == "\x08") this._xterm.write("^H") 910 | else if (data.charCodeAt(0) == 0x1b) 911 | this._xterm.write("^[" + data.slice(1)) 912 | else this._xterm.write(data) 913 | }) 914 | }) 915 | 916 | // pass value to webworker 917 | this._setStdinBuffer(input) 918 | this._resumeWorker() 919 | }) 920 | }) 921 | 922 | _stdoutProxy = proxy((value) => { 923 | this._lastOutputTime = Date.now() // keep track of time 924 | this._stdoutBuffer.write(value) 925 | }) 926 | _stderrProxy = proxy((value) => { 927 | this._lastOutputTime = Date.now() // keep track of time 928 | this._stderrBuffer.write(value) 929 | }) 930 | 931 | /* input output handling -> term */ 932 | 933 | _stdoutBuffer = new LineBuffer(this._stdout.bind(this)) 934 | _stderrBuffer = new LineBuffer(this._stderr.bind(this)) 935 | 936 | _stdout(value) { 937 | // string or char code 938 | 939 | if (this._suppressOutputs) return // used for Ctrl+C 940 | 941 | // numbers are interpreted as char codes -> convert to string 942 | if (typeof value == "number") value = String.fromCharCode(value) 943 | 944 | // avoid offsets with line breaks 945 | value = value.replace(/\n/g, "\r\n") 946 | 947 | // write to terminal 948 | this._outputBuffer += value 949 | this._xterm.write(value) 950 | } 951 | 952 | _stderr(value) { 953 | // check if it's a javascript error 954 | if (value instanceof Error) { 955 | // log error to the console 956 | console.error("stderr error:", value) 957 | 958 | // convert error object to string 959 | value = value.toString() + "\n" 960 | } 961 | 962 | // print to terminal 963 | this._stdout(value) 964 | } 965 | 966 | async printWelcomeMessage() { 967 | let message = `\x1b[1;32m 968 | _ _ _ _ _ _ _ _____ \r 969 | | | | |___ ___ _____ | | | |___| |_ |_ _|___ ___ _____ \r 970 | | | | | .'|_ -| | | | | | -_| . | | | | -_| _| |\r 971 | |_____|__,|___|_|_|_| |_____|___|___| |_| |___|_| |_|_|_|\r 972 | \x1b[37m\r\n` 973 | 974 | message += 975 | "Run WebAssembly binaries compiled with Emscripten or Wasmer.\r\n" 976 | message += 977 | "You can also define and run custom JavaScript functions.\r\n\r\n" 978 | 979 | message += "Version: " + __VERSION__ + ". " 980 | message += 981 | "Backend: " + (this._worker ? "WebWorker" : "Prompts Fallback") + ".\r\n" 982 | message += 983 | "Commands: " + 984 | [...this._jsCommands] 985 | .map((commandObj) => commandObj[0]) 986 | .sort() 987 | .join(", ") + 988 | ". " 989 | 990 | return message 991 | } 992 | 993 | // helper function to cleanly print the welcome message 994 | async printWelcomeMessagePlusControlSequences() { 995 | // clear terminal, reset color, print welcome message, reset color, add empty line 996 | return ( 997 | "\x1bc" + 998 | "\x1b[0;37m" + 999 | (await this.printWelcomeMessage()) + 1000 | "\x1b[0;37m\r\n" 1001 | ) 1002 | } 1003 | 1004 | _onXtermData(data) { 1005 | if (data == "\x03") { 1006 | // custom handler for Ctrl+C (webworker only) 1007 | if (this._worker) { 1008 | this._suppressOutputs = true 1009 | this._terminateWorker() 1010 | this._initWorker() // reinit 1011 | this._runWasmCommandPromise?.reject("Ctrl + C") 1012 | this.isRunningCommand = false 1013 | } 1014 | } 1015 | } 1016 | } 1017 | 1018 | export default WasmWebTerm 1019 | -------------------------------------------------------------------------------- /src/WasmWebTerm.md: -------------------------------------------------------------------------------- 1 | # [`WasmWebTerm.js`](./WasmWebTerm.js) Code API 2 | 3 | The main class `WasmWebTerm`, located in `WasmWebTerm.js`, has some attributes and methods that you can use or overwrite to adapt its behaviour to your needs. You can see an [example on how we used it for OpenSSL](https://github.com/cryptool-org/openssl-webterm). 4 | 5 | For example, you can interact with the files in the filesystem, or change the welcome message, or write custom command with JS functions. 6 | 7 | > Private attributes or methods are indicated by an underscore (`_`). For example: [`_jsCommands`](#_jscommands) would be private while [`jsCommands`](#jscommands) would be public. You can of course use these none the less. 8 | 9 | To begin with, initialize a new instance of `WasmWebTerm`. Then overwrite its methods (if you want) and attach it to the xterm.js `Terminal`. Then you can execute methods on it. 10 | 11 | Here's an example for a webterm with custom welcome message and custom prompt. It then executes `cowsay hi` ([cowsay binary](https://wapm.io/syrusakbary/cowsay)) 12 | 13 | ```js 14 | import { Terminal } from "xterm" 15 | import WasmWebTerm from "wasm-webterm" 16 | 17 | let term = new Terminal() 18 | let wasmterm = new WasmWebTerm() 19 | 20 | wasmterm.printWelcomeMessage = () => "Hello world shell \r\n" 21 | wasmterm._xtermPrompt = () => "custom> " 22 | 23 | term.loadAddon(wasmterm) 24 | term.open(document.getElementById("terminal")) 25 | 26 | wasmterm.runWasmCommand("cowsay", ["hi"]) 27 | ``` 28 | 29 | 30 | ### Public Attributes 31 | 32 | * #### `isRunningCommand` 33 | Boolean value if the addon is currently running a command. Both using the `Terminal` or executing headless. This is to make sure, only a single command runs in parallel. 34 | 35 | * #### `jsCommands` 36 | Getter for [`_jsCommands`](#_jscommands), a [`Map()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map) containing JS commands that can be ran on the webterm. 37 | 38 | 39 | ### Public Methods 40 | 41 | * #### async `repl()` 42 | Starts a [Read Eval Print Loop](https://en.wikipedia.org/wiki/Read–eval–print_loop). It reads a line from the terminal, calls `onBeforeCommandRun()`, calls `runLine(line)` (which evaluates the line and runs the contained command), calls `onCommandRunFinish()`, and then recursively calls itself again (loop). 43 | 44 | * #### async `runLine(line)` 45 | Gets a string (line), splits it into single commands (separated by `|`), and iterates over them. It then checks, if there is a JS function defined in [`_jsCommands`](#_jscommands) with the given command name. If there is, it'll execute it. See [defining custom JS commands](#defining-custom-js-commands) for more details. Otherwise, it will interpret the command name as the name of a WebAssembly binary and delegate to `runWasmCommand(..)` and `runWasmCommandHeadless(..)`. 46 | 47 | * #### `runWasmCommand(programName, argv, stdinPreset, onFinishCallback)` 48 | The method for running single wasm commands on the Terminal. Only one command in parallel is allowed. It will call [`_getOrFetchWasmModule(name)`](#_getorfetchwasmmoduleprogramname) to fetch the according WebAssembly Module. It will then delegate the call to the Worker or the WasmRunner (which is the Prompts fallback). It also defines callback functions for when the wasm execution has finished or errored. It also passes (proxies to) `_stdout(val)`, `_stderr(val)`, and `_stdinProxy(msg)` to the WebAssembly binary. `stdinPreset` can be a string (when using pipes) or `null`. After the run (if successfull or on errors), `onFinishCallback()` will be called. This method can also be awaited instead of using the callback. 49 | 50 | * #### `runWasmCommandHeadless(programName, argv, stdinPreset, onFinishCallback)` 51 | Same as `runWasmCommand(..)` but without writing to the Terminal. It does not pass proxies for input/output but buffers outputs and returns them in the callback. Errors will be printed though. This method can also be awaited instead of using the callback. 52 | 53 | * #### `registerJsCommand(name, callback, autocomplete)` 54 | Registers a JS function in `callback` as to be called when the command with the name of `name` is entered into the Terminal. `autocomplete` does not work yet. These JS functions are also refered to as "user functions". 55 | 56 | They're callback functions will receive `argv` (array) and `stdinPreset` (string) as input. `argv` contains the command parameters and `stdinPreset` contains the output of a previous command when using pipes). 57 | 58 | They can pass outputs in 3 ways: 59 | 60 | * Normally return a string via `return` 61 | * Return a promise and use `resolve()` (async functions are fine too) 62 | * Using `yield` in generator functions 63 | 64 | See [defining custom JS commands](#defining-custom-js-commands) for examples. 65 | 66 | * #### `unregisterJsCommand(name)` 67 | Counter part to [`registerJsCommand(..)`](#registerjscommandname-callback-autocomplete). Removes the entry from the Map. 68 | 69 | * #### async `printWelcomeMessage()` 70 | Returns a string which is then printed to the Terminal on startup. This can be overwritten and is async so you could fetch something. 71 | 72 | 73 | ### Event methods 74 | 75 | The following methods are called on specific events. You can overwrite them to customly handle the events. 76 | 77 | * #### async `onActivated()` 78 | Is fired after the addon has been attached to the xterm.js Terminal instance. Usually triggered by including the Terminal into the DOM. It is called in the method `activate`, where the addon is being initialized. 79 | 80 | * #### async `onDisposed()` 81 | The counter part to `onActivated` is called when the addon has been detached from the Terminal. Usually triggered by closing the tab or something. 82 | 83 | * #### async `onFileSystemUpdate(_wasmFsFiles)` 84 | Is called every time the filesystem is being updated. This does not happen immediatly when a file is being written by the wasm binary, but when a command has been ran. Contains the value of `_wasmFsFiles`. 85 | 86 | * #### async `onBeforeCommandRun()` 87 | Is called before every line/command ran via the REPL. Gives the opportunity to show loading animations or something like that. 88 | 89 | * #### async `onCommandRunFinish()` 90 | Is called after a line/command has been ran via the REPL. Gives the opportunity to hide loading animations etc. 91 | 92 | 93 | ### Private Attributes 94 | 95 | * #### `_xterm` 96 | The local instance of xterm.js `Terminal` which the addon is attached to. 97 | 98 | * #### `_xtermEcho` 99 | The local instance of `local-echo`, which provides the possibility to read from the Terminal. 100 | > It also makes sense to look at the underlying [local-echo](https://github.com/wavesoft/local-echo). For example, its API offers the possibility to `.abortRead(reason)`, which exits the REPL. 101 | 102 | * #### `_xtermPrompt` 103 | An async function that returns what is shown as prompt in the Terminal. Default is `$`. 104 | 105 | * #### `_jsCommands` 106 | ES6 [`Map()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map) containing JS commands in the form of `["command" => function(argv, stdin)]` (simplified). There is a getter called [`jsCommands`](#jscommands), so you don't need the underscore. This can be mutated by using [`registerJsCommand(..)`](#registerjscommandname-callback-autocomplete) and [`unregisterJsCommand(..)`]((#unregisterjscommand)). 107 | 108 | * #### `_worker` 109 | Instance of [Comlink](https://github.com/GoogleChromeLabs/comlink) worker if there is support for Workers. Or the boolean value `false` if there is not and the Prompts Fallback is being used. 110 | 111 | * #### `_pauseBuffer` 112 | [SharedArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) (1 bit) for pausing the Worker by using [Atomics](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Atomics). If the value is set to `1`, the worker will hold on its next call of `pauseExecution()` inside of [`WasmWorker`](https://github.com/cryptool-org/wasm-webterm/blob/master/src/runners/WasmWorker.js). It can then be resumed by setting the value to `0` again. 113 | 114 | * #### `_stdinBuffer` 115 | [SharedArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) (1000 bit) for passing strings to the Worker which are then used as Stdin values. Zeros (0) mark the end of the string. 116 | 117 | * #### `_wasmRunner` 118 | Instance of `WasmRunner` (see `WasmRunner.js`) that is being used as fallback, when Workers are not available. Also refered to as "Prompts Fallback", as it uses `window.prompt()` and runs on the main thread. 119 | 120 | * #### `_wasmModules` 121 | Array of objects containing WebAssembly modules. The object structure is as follows. The `runtime` will only be set if it's an Emscripten binary and contain the JS code then. 122 | ```json 123 | [{ name: "", type: "emscripten|wasmer", module: WebAssembly.Module, runtime: [optional] }] 124 | ``` 125 | 126 | * #### `_wasmFsFiles` 127 | Array of objects containing the files from the virtual memory filesystem used for the wasm binaries encoded as binary data. The format is as follows: 128 | ```json 129 | [{ name: "", timestamp: , bytes: Uint8Array }] 130 | ``` 131 | 132 | * #### `_outputBuffer` 133 | String that buffers both outputs (stdout and stderr). It is used to determine if a command's output has ended with a line break or not, thus one should be appended or not. 134 | 135 | * #### `_lastOutputTime` 136 | Unix timestamp updated on every output (stdout and stderr). Worker outputs are not always rendered to the Terminal directly. Therefore we wait for like 80ms before we ask for Stdin or return control to the REPL. 137 | 138 | 139 | ### Internal methods 140 | 141 | * #### async `activate(xterm)` 142 | This is an [xterm.js addon life cycle method](https://xtermjs.org/docs/guides/using-addons/#creating-an-addon) and it's being called when the addon is loaded into the xterm.js Terminal instance. It loads the [xterm.js FitAddon](https://github.com/xtermjs/xterm.js/tree/master/addons/xterm-addon-fit) for dynamic Terminal resizing and the [`local-echo` addon](https://github.com/wavesoft/local-echo) for reading from the Terminal. It also initializes the drag&drop mechanism, registers default JS commands (`help` and `clear`), prints the welcome message, and starts the REPL. 143 | 144 | * #### async `dispose()` 145 | Counter part to `activate(xterm)`. Disposes the FitAddon and `local-echo` and terminates the Worker. 146 | 147 | * #### `_onXtermData(data)` 148 | Handler for data from the xterm.js Terminal. Whenever a user enters something, this method is called. It's currently only used for `Ctrl+C` but could be overwritten and extended. 149 | 150 | * #### `_getOrFetchWasmModule(programName)` 151 | Fetches WebAssembly binaries and compiles them into WebAssembly Modules. Returns Promise to be awaited or handled by using `.then(wasmModule)`. If there already is a compiled module stored in `_wasmModules`, it will be used and nothing will be fetched. If there is none yet, it will fetch `/.wasm` and validate if it's WebAssembly. If so, it will also try to fetch a JS runtime at `/.js`. If it is found, the wasm binary is determined to be an Emscripten binary and the JS runtime is stored. If none is found, the wasm binary is considered a WASI binary. If no `.wasm` binary is found, it will query [wapm.io](https://wapm.io) and try to fetch a WASI binary from there. 152 | 153 | * #### `_initWasmModuleDragAndDrop()` 154 | Registers event handlers for dragging and dropping WebAssembly binaries into the Terminal window. If binaries are dropped, they're compiled and added to `_wasmModules`. 155 | 156 | * #### `_initWorker()` 157 | Creates [SharedArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer)s (`_pauseBuffer` and `_stdinBuffer`) and creates a Comlink instance of the prebuilt `WasmWorker` bundle, which is being initialized as a Worker thread from a Blob. This Blob initialization only works because all dependencies are bundles into `worker.bundle.js` by Webpack. 158 | 159 | * #### `_resumeWorker()` 160 | Sets the [SharedArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) `_pauseBuffer` to `0` which resumes the Worker if its locked in `WasmWorker`'s `pauseExecution()`. 161 | 162 | * #### `_terminateWorker()` 163 | Immediately [terminates](https://developer.mozilla.org/docs/Web/API/Worker/terminate) the Worker thread. "This does not offer the worker an opportunity to finish its operations; it is stopped at once." 164 | 165 | * #### `_waitForOutputPause(pauseDuration = 80, interval = 20)` 166 | Worker outputs are not always rendered to the Terminal directly. Therefore we wait for like 80ms before we ask for Stdin or return control to the REPL. `interval` determines the time between each check. 167 | 168 | * #### `_setStdinBuffer(string)` 169 | Sets the value of `_stdinBuffer` to a given string, which can then be read from the Worker. 170 | 171 | * #### `_stdinProxy(message)` 172 | Comlink Proxy which will be passed to the Worker thread. It will be called when the wasm binary reads from `/dev/stdin` or `/dev/tty`. It then reads a line from the xterm.js Terminal by using `local-echo`, sets the `_stdinBuffer` accordingly, and resumes the Worker. 173 | 174 | * #### `_stdoutProxy(value)` and `_stderrProxy(value)` 175 | Comlink proxies that map to `_stdout(value)` and `_stderr(value)`. They're proxies so that we can pass them to the Worker. But they can also be called directly, so we can also pass them to the `WasmRunner` Prompts fallback. 176 | 177 | * #### `_stdout(value)` 178 | Prints the string `value` to the xterm.js Terminal, stores it in the `_outputBuffer`, and updates `_lastOutputTime`. If `value` is a number, it will be interpreted as an ASCI char code and converted into a string. 179 | 180 | * #### `_stderr(value)` 181 | Just maps to `_stdout(value)` but could be used to handle Stderr separatly. 182 | 183 | 184 | ----- 185 | -------------------------------------------------------------------------------- /src/runnables/EmscriptenRunnable.js: -------------------------------------------------------------------------------- 1 | class EmscrWasmRunnable { 2 | /* method wrapper class for emscr wasm modules. 3 | loads emscripten js runtime and can execute wasm. */ 4 | 5 | programName 6 | wasmModule 7 | 8 | #emscrJsRuntime 9 | 10 | constructor(programName, wasmModule, jsRuntime) { 11 | this.programName = programName 12 | this.wasmModule = wasmModule 13 | this._loadEmscrJsRuntime(jsRuntime) 14 | } 15 | 16 | /** 17 | * Executes given arguments (argv) on wasm module. 18 | * onFinish is called even if there are errors during execution. 19 | * 20 | * if stdinPreset (string) is set, it will be delivered instead of reading stdin 21 | * from terminal (this feature is used for piping and running headless commands) 22 | */ 23 | run( 24 | argv, 25 | stdin, 26 | stdout, 27 | stderr, 28 | files, 29 | onFinish, 30 | onError, 31 | onSuccess, 32 | stdinPreset 33 | ) { 34 | console.log("emscr runnable run:", this.programName, argv) 35 | 36 | // initialize default methods and values 37 | if (typeof stdin != "function") stdin = () => {} 38 | if (typeof stdout != "function") stdout = () => {} 39 | if (typeof stderr != "function") stderr = () => {} 40 | if (!(files instanceof Array)) files = [] 41 | 42 | // initialize default callbacks 43 | if (typeof onFinish != "function") onFinish = () => {} 44 | if (typeof onError != "function") 45 | onError = (e) => { 46 | console.error(e) 47 | } 48 | if (typeof onSuccess != "function") onSuccess = () => {} 49 | 50 | // define emscr module 51 | let emscrModule = { 52 | thisProgramm: this.programName, 53 | instantiateWasm: (imports, callback) => { 54 | WebAssembly.instantiate(this.wasmModule, imports).then((instance) => 55 | callback(instance, this.wasmModule) 56 | ) 57 | return {} 58 | }, 59 | preInit: [ 60 | () => { 61 | emscrModule.TTY.register(emscrModule.FS.makedev(5, 0), { 62 | get_char: (tty) => stdin(tty), 63 | put_char: (tty, val) => { 64 | tty.output.push(val) 65 | stdout(val) 66 | }, 67 | flush: (tty) => (tty.output = []), 68 | fsync: (tty) => 69 | console.log( 70 | "fsynced stdout (EmscriptenRunnable does nothing in this case)" 71 | ), 72 | }) 73 | emscrModule.TTY.register(emscrModule.FS.makedev(6, 0), { 74 | get_char: (tty) => stdin(tty), 75 | put_char: (tty, val) => { 76 | tty.output.push(val) 77 | stderr(val) 78 | }, 79 | flush: (tty) => (tty.output = []), 80 | fsync: (tty) => 81 | console.log( 82 | "fsynced stderr (EmscriptenRunnable does nothing in this case)" 83 | ), 84 | }) 85 | }, 86 | ], 87 | } 88 | 89 | if (stdinPreset) { 90 | // with stdinPreset you can preset a value for stdin 91 | 92 | if (typeof stdinPreset != "string") 93 | stdinPreset = (stdinPreset || "").toString() 94 | 95 | let stdinIndex = 0 96 | emscrModule.stdin = () => { 97 | if (stdinIndex < stdinPreset.length) 98 | return stdinPreset.charCodeAt(stdinIndex++) 99 | return null 100 | } 101 | } 102 | 103 | let filesPostRun // instantiate emscripten module and call main 104 | this.#emscrJsRuntime(emscrModule) 105 | .then((instance) => { 106 | // emscr module instance 107 | 108 | // write submitted files to wasm 109 | this._writeFilesToFS(instance, files) 110 | 111 | // execute command 112 | instance.callMain(argv) 113 | 114 | // read created files from wasm 115 | filesPostRun = this._readFilesFromFS(instance) 116 | 117 | // success callback 118 | onSuccess(filesPostRun) 119 | }) 120 | 121 | .catch((error) => onError(error)) 122 | .finally(() => onFinish(filesPostRun || files)) 123 | } 124 | 125 | /** 126 | * Executes a command without command line input/output. 127 | * It runs the command and returns all outputs in onFinish. 128 | * 129 | * --> only supports commands that do not ask for CLI input 130 | * --> stdin can be preset by passing string as stdinPreset 131 | */ 132 | runHeadless(argv, files, onFinish, onError, onSuccess, stdinPreset) { 133 | console.log("emscr runnable run headless:", this.programName, argv) 134 | 135 | // initialize default callback 136 | if (typeof onFinish != "function") onFinish = () => {} 137 | 138 | // stdin is not needed 139 | const stdin = () => { 140 | console.log("called runHeadless stdin") 141 | } 142 | 143 | // output is redirected into buffer 144 | let outputBuffer = "", 145 | stdoutBuffer = "", 146 | stderrBuffer = "" 147 | const stdout = (val) => { 148 | outputBuffer += String.fromCharCode(val) 149 | stdoutBuffer += String.fromCharCode(val) 150 | } 151 | const stderr = (val) => { 152 | outputBuffer += String.fromCharCode(val) 153 | stderrBuffer += String.fromCharCode(val) 154 | } 155 | 156 | // run command with custom input/output 157 | this.run( 158 | argv, 159 | stdin, 160 | stdout, 161 | stderr, 162 | files, 163 | () => 164 | onFinish({ 165 | output: outputBuffer, 166 | stdout: stdoutBuffer, 167 | stderr: stderrBuffer, 168 | }), 169 | onError, 170 | onSuccess, 171 | stdinPreset 172 | ) 173 | } 174 | 175 | /* file handling */ 176 | 177 | _readFilesFromFS(instance, directory = "/", includeBinary = true) { 178 | const path = instance.FS.lookupPath(directory) 179 | 180 | const getFilesFromNode = (parentNode) => { 181 | let files = [] 182 | Object.values(parentNode.contents).forEach((node) => { 183 | let nodePath = instance.FS.getPath(node) 184 | if (instance.FS.isFile(node.mode)) 185 | files.push({ 186 | name: nodePath, 187 | timestamp: node.timestamp, 188 | bytes: includeBinary 189 | ? instance.FS.readFile(nodePath) 190 | : new Uint8Array(), 191 | }) 192 | if (instance.FS.isDir(node.mode)) 193 | files = [...files, ...getFilesFromNode(node)] 194 | }) 195 | return files 196 | } 197 | 198 | let files = getFilesFromNode(path.node) 199 | return files 200 | } 201 | 202 | _writeFilesToFS(instance, files = []) { 203 | files.forEach((file) => { 204 | try { 205 | if (file.bytes instanceof Uint8Array) { 206 | instance.FS.writeFile(file.name, file.bytes) 207 | 208 | const timestamp = 209 | file.timestamp instanceof Date 210 | ? file.timestamp.getTime() 211 | : file.timestamp 212 | if (typeof timestamp === "number") 213 | instance.FS.utime(file.name, timestamp, timestamp) 214 | } 215 | } catch (e) { 216 | console.error(e.name + ": " + e.message) 217 | } 218 | }) 219 | } 220 | 221 | /* internal methods */ 222 | 223 | _loadEmscrJsRuntime(jsRuntime) { 224 | const emscrJsModuleName = "EmscrJSR_" + this.programName 225 | 226 | // try worker import 227 | if (this._isWorkerScope()) { 228 | // import js runtime 229 | let blob = new Blob([jsRuntime], { type: "application/javascript" }) 230 | importScripts(URL.createObjectURL(blob)) 231 | 232 | console.log(jsRuntime, blob) 233 | 234 | // read emscripten Module from js runtime 235 | this.#emscrJsRuntime = 236 | self[emscrJsModuleName] || self["_createPyodideModule"] 237 | // todo: find better solution for module names 238 | } 239 | 240 | // check if is in normal browser dom 241 | else if (typeof document != "undefined") { 242 | const jsRuntimeElemID = this.programName + "_emscrJSR" 243 | 244 | // inject js runtime if not done before 245 | if (!document.getElementById(jsRuntimeElemID)) { 246 | // create new script element for runtime 247 | let script = document.createElement("script") 248 | script.type = "text/javascript" 249 | script.id = jsRuntimeElemID 250 | 251 | // insert js runtime script into DOM 252 | script.innerHTML = new TextDecoder("utf-8").decode(jsRuntime) 253 | document.head.appendChild(script) 254 | } 255 | 256 | // read emscripten Module from js runtime 257 | this.#emscrJsRuntime = window[emscrJsModuleName] 258 | } else throw new Error("can not load emscr js runtime environment") 259 | } 260 | 261 | _isWorkerScope() { 262 | // checks if script is executed in worker or main thread 263 | return ( 264 | typeof WorkerGlobalScope != "undefined" && 265 | self instanceof WorkerGlobalScope 266 | ) 267 | } 268 | } 269 | 270 | export default EmscrWasmRunnable 271 | -------------------------------------------------------------------------------- /src/runnables/WasmerRunnable.js: -------------------------------------------------------------------------------- 1 | import { WASI } from "@wasmer/wasi" 2 | import browserBindings from "@wasmer/wasi/lib/bindings/browser" 3 | import { WasmFs } from "@wasmer/wasmfs" 4 | 5 | const S_IFCHR = 8192 // magic constant from memFS 6 | 7 | class WasmerRunnable { 8 | /* method wrapper class for wasmer wasm modules. 9 | initializes memory filesystem and can execute wasm. */ 10 | 11 | programName 12 | wasmModule 13 | 14 | constructor(programName, wasmModule) { 15 | this.programName = programName 16 | this.wasmModule = wasmModule 17 | } 18 | 19 | run( 20 | argv, 21 | stdin, 22 | stdout, 23 | stderr, 24 | files, 25 | onFinish, 26 | onError, 27 | onSuccess, 28 | stdinPreset 29 | ) { 30 | console.log("wasmer runnable run:", this.programName, argv) 31 | 32 | // initialize default methods and values 33 | if (typeof stdin != "function") stdin = () => {} 34 | if (typeof stdout != "function") stdout = () => {} 35 | if (typeof stderr != "function") stderr = () => {} 36 | if (!(files instanceof Array)) files = [] 37 | 38 | // initialize default callbacks 39 | if (typeof onFinish != "function") onFinish = () => {} 40 | if (typeof onError != "function") 41 | onError = (e) => { 42 | console.error(e) 43 | } 44 | if (typeof onSuccess != "function") onSuccess = () => {} 45 | 46 | // init new memory filesystem 47 | const wasmFs = new WasmFs() 48 | 49 | // write all files to wasmfs 50 | this._writeFilesToFS(wasmFs, files) 51 | 52 | // set /dev/stdin to stdin function 53 | wasmFs.volume.fds[0].node.read = stdin 54 | 55 | if (stdinPreset) { 56 | // with stdinPreset you can preset a value for stdin 57 | 58 | if (typeof stdinPreset != "string") 59 | stdinPreset = (stdinPreset || "").toString() 60 | 61 | let stdinCallCounter = 0 62 | wasmFs.volume.fds[0].node.read = (stdinBuffer) => { 63 | // second read means end of string 64 | if (stdinCallCounter % 2 !== 0) { 65 | stdinCallCounter++ 66 | return 0 67 | } 68 | 69 | // copy stdin preset to stdinBuffer 70 | for (let i = 0; i < stdinPreset.length; i++) 71 | stdinBuffer[i] = stdinPreset.charCodeAt(i) 72 | 73 | // indicate we've read once 74 | stdinCallCounter++ 75 | 76 | // return how much to read 77 | return stdinPreset.length 78 | } 79 | } 80 | 81 | // set /dev/stdout to stdout function 82 | wasmFs.volume.fds[1].node.write = ( 83 | stdoutBuffer, 84 | offset, 85 | length, 86 | position 87 | ) => { 88 | stdout(new TextDecoder("utf-8").decode(stdoutBuffer)) 89 | return stdoutBuffer.length 90 | } 91 | 92 | // set /dev/stderr to stderr function 93 | wasmFs.volume.fds[2].node.write = ( 94 | stderrBuffer, 95 | offset, 96 | length, 97 | position 98 | ) => { 99 | stderr(new TextDecoder("utf-8").decode(stderrBuffer)) 100 | return stderrBuffer.length 101 | } 102 | 103 | // map /dev/tty to /dev/stdin and /dev/stdout 104 | const ttyFd = wasmFs.volume.openSync("/dev/tty", "w+") 105 | wasmFs.volume.fds[ttyFd].node.read = wasmFs.volume.fds[0].node.read 106 | wasmFs.volume.fds[ttyFd].node.write = wasmFs.volume.fds[1].node.write 107 | 108 | // mark /dev/{stdin,stdout,stderr,tty} as character devices 109 | wasmFs.volume.fds[0].node.setModeProperty(S_IFCHR) 110 | wasmFs.volume.fds[1].node.setModeProperty(S_IFCHR) 111 | wasmFs.volume.fds[2].node.setModeProperty(S_IFCHR) 112 | wasmFs.volume.fds[ttyFd].node.setModeProperty(S_IFCHR) 113 | 114 | // create wasi runtime 115 | let wasi = new WASI({ 116 | args: [this.programName, ...argv], 117 | env: {}, // todo: maybe use environment variables? 118 | bindings: { 119 | ...browserBindings, 120 | fs: wasmFs.fs, 121 | }, 122 | preopens: { 123 | ".": ".", 124 | "/": "/", 125 | }, 126 | }) 127 | 128 | // instantiate wasm module 129 | const imports = wasi.getImports(this.wasmModule) // WebAssembly.Module.imports(this.wasmModule) 130 | WebAssembly.instantiate(this.wasmModule, { ...imports }).then( 131 | (instance) => { 132 | let filesPostRun 133 | try { 134 | // write submitted files to wasm 135 | this._writeFilesToFS(wasmFs, files) 136 | 137 | // execute command 138 | try { 139 | wasi.start(instance) 140 | } catch (e) { 141 | // make browserBindings not throw on code 0 (normal exit) 142 | if (e.code != 0) browserBindings.exit(e.code) 143 | } 144 | 145 | // read created files from wasm 146 | filesPostRun = this._readFilesFromFS(wasmFs) 147 | 148 | // success callback 149 | onSuccess(filesPostRun) 150 | } catch (e) { 151 | onError(e.message) 152 | } finally { 153 | onFinish(filesPostRun || files) 154 | } 155 | } 156 | ) 157 | } 158 | 159 | runHeadless(argv, files, onFinish, onError, onSuccess, stdinPreset) { 160 | console.log("wasmer runnable run headless:", this.programName, argv) 161 | 162 | // initialize default callback 163 | if (typeof onFinish != "function") onFinish = () => {} 164 | 165 | // stdin is not needed 166 | const stdin = () => { 167 | console.log("called runHeadless stdin") 168 | return 0 169 | } 170 | 171 | // output is redirected into buffer 172 | let outputBuffer = "", 173 | stdoutBuffer = "", 174 | stderrBuffer = "" 175 | const stdout = (stdoutVal) => { 176 | outputBuffer += stdoutVal 177 | stdoutBuffer += stdoutVal 178 | return stdoutVal.length 179 | } 180 | const stderr = (stderrVal) => { 181 | outputBuffer += stderrVal 182 | stderrBuffer += stderrVal 183 | return stderrVal.length 184 | } 185 | 186 | // run command with custom input/output 187 | this.run( 188 | argv, 189 | stdin, 190 | stdout, 191 | stderr, 192 | files, 193 | () => 194 | onFinish({ 195 | output: outputBuffer, 196 | stdout: stdoutBuffer, 197 | stderr: stderrBuffer, 198 | }), 199 | onError, 200 | onSuccess, 201 | stdinPreset 202 | ) 203 | } 204 | 205 | /* file handling */ 206 | 207 | _readFilesFromFS(wasmFs, directory = "/", includeBinary = true) { 208 | const rootLink = wasmFs.volume.getLinkAsDirOrThrow(directory) 209 | 210 | const getFilesFromLink = (parentLink) => { 211 | let files = [] 212 | Object.values(parentLink.children).forEach((link) => { 213 | let linkPath = link.getPath() 214 | let node = link.getNode() 215 | if (node.isFile()) 216 | files.push({ 217 | name: linkPath, 218 | timestamp: node.mtime.getTime(), 219 | bytes: includeBinary 220 | ? wasmFs.fs.readFileSync(linkPath) 221 | : new Uint8Array(), 222 | }) 223 | if (node.isDirectory()) files = [...files, ...getFilesFromLink(link)] 224 | }) 225 | return files 226 | } 227 | 228 | let files = getFilesFromLink(rootLink) 229 | return files 230 | } 231 | 232 | _writeFilesToFS(wasmFs, files = []) { 233 | files.forEach((file) => { 234 | try { 235 | if (file.bytes instanceof Uint8Array) { 236 | const path = file.name.split("/").slice(0, -1).join("/") 237 | wasmFs.fs.mkdirSync(path, { recursive: true }) 238 | wasmFs.fs.writeFileSync(file.name, file.bytes) 239 | 240 | if (file.timestamp instanceof Date) 241 | wasmFs.fs.utimesSync(file.name, file.timestamp, file.timestamp) 242 | else if (typeof file.timestamp === "number") 243 | wasmFs.fs.utimesSync( 244 | file.name, 245 | file.timestamp / 1000, 246 | file.timestamp / 1000 247 | ) 248 | } 249 | } catch (e) { 250 | console.error(e.name + ": " + e.message) 251 | } 252 | }) 253 | } 254 | } 255 | 256 | export default WasmerRunnable 257 | -------------------------------------------------------------------------------- /src/runners/ImportInjectedModules.js: -------------------------------------------------------------------------------- 1 | // HACK: Inject all the modules that have been forward from the parent thread into 2 | // our own bundle. This has to be done before importing any of these modules. 3 | const existingModules = Object.keys(__webpack_modules__) 4 | 5 | for (const [id, mod] of Object.entries(global._modules)) { 6 | if (!existingModules.includes(id)) __webpack_modules__[id] = mod 7 | } 8 | 9 | // HACK: Make the lexicographic first export of the `WasmRunner` module available 10 | // as the default export. Webpack does mangle/minify names longer than 2 characters. 11 | const WasmRunnerModule = __webpack_require__(global.WasmRunnerID) 12 | const defaultKey = Object.keys(WasmRunnerModule)[0] 13 | self.WasmRunner = WasmRunnerModule[defaultKey] 14 | -------------------------------------------------------------------------------- /src/runners/WasmRunner.js: -------------------------------------------------------------------------------- 1 | import EmscrWasmRunnable from "../runnables/EmscriptenRunnable" 2 | import WasmerRunnable from "../runnables/WasmerRunnable" 3 | 4 | /* executes wasm on the main thread. asks for stdin by using prompts. 5 | this class will be extented by WasmWorker to run on worker thread. */ 6 | 7 | class WasmRunner { 8 | outputBuffer 9 | 10 | constructor() { 11 | this.outputBuffer = "" 12 | } 13 | 14 | runCommand( 15 | programName, 16 | wasmModule, 17 | wasmModuleType, 18 | argv, 19 | stdinProxy, 20 | stdoutProxy, 21 | stderrProxy, 22 | files, 23 | onFinish, 24 | onError, 25 | onSuccess, 26 | stdinPreset, 27 | emscrJsRuntime 28 | ) { 29 | // initialize default callbacks 30 | if (typeof onFinish != "function") onFinish = () => {} 31 | if (typeof onError != "function") 32 | onError = (e) => { 33 | console.error(e) 34 | } 35 | if (typeof onSuccess != "function") onSuccess = () => {} 36 | 37 | // store outputs of stdout in buffer (for stdin prompts) 38 | const bufferOutputs = (value) => { 39 | this.outputBuffer += 40 | typeof value == "number" ? String.fromCharCode(value) : value 41 | } 42 | const stdoutHandler = (value) => { 43 | bufferOutputs(value) 44 | return stdoutProxy(value) 45 | } 46 | const stderrHandler = (value) => { 47 | bufferOutputs(value) 48 | return stderrProxy(value) 49 | } 50 | 51 | if (wasmModuleType == "emscripten") { 52 | // instantiate new emscr runnable 53 | console.log("wasm runner creates new emscr runnable") 54 | let emscrWasmExe = new EmscrWasmRunnable( 55 | programName, 56 | wasmModule, 57 | emscrJsRuntime 58 | ) 59 | 60 | // pipe stdin calls through stdin handler (which pauses thread) 61 | const stdinHandler = (tty) => 62 | this._onEmscrStdinCall(tty, stdinProxy, stdoutHandler, stderrHandler) 63 | 64 | // run command on it 65 | emscrWasmExe.run( 66 | argv, 67 | stdinHandler, 68 | stdoutHandler, 69 | stderrHandler, 70 | files, 71 | onFinish, 72 | onError, 73 | onSuccess, 74 | stdinPreset 75 | ) 76 | } else if (wasmModuleType == "wasmer") { 77 | // instantiate new wasmer runnable 78 | console.log("wasm runner creates new wasmer runnable") 79 | let wasmerExe = new WasmerRunnable(programName, wasmModule) 80 | 81 | // pipe stdin calls through stdin handler (which pauses thread) 82 | const stdinHandler = (stdinBuffer) => 83 | this._onWasmerStdinCall( 84 | stdinBuffer, 85 | stdinProxy, 86 | stdoutHandler, 87 | stderrHandler 88 | ) 89 | 90 | // run command on it 91 | wasmerExe.run( 92 | argv, 93 | stdinHandler, 94 | stdoutHandler, 95 | stderrHandler, 96 | files, 97 | onFinish, 98 | onError, 99 | onSuccess, 100 | stdinPreset 101 | ) 102 | } else 103 | throw new Error( 104 | "Unknown wasm module type (can only handle emscripten or wasmer)" 105 | ) 106 | } 107 | 108 | runCommandHeadless( 109 | programName, 110 | wasmModule, 111 | wasmModuleType, 112 | argv, 113 | files, 114 | onFinish, 115 | onError, 116 | onSuccess, 117 | stdinPreset, 118 | emscrJsRuntime 119 | ) { 120 | // initialize default callbacks 121 | if (typeof onFinish != "function") onFinish = () => {} 122 | if (typeof onError != "function") 123 | onError = (e) => { 124 | console.error(e) 125 | } 126 | if (typeof onSuccess != "function") onSuccess = () => {} 127 | 128 | if (wasmModuleType == "emscripten") { 129 | // instantiate new emscr runnable 130 | console.log("wasm runner creates new emscr runnable") 131 | let emscrWasmExe = new EmscrWasmRunnable( 132 | programName, 133 | wasmModule, 134 | emscrJsRuntime 135 | ) 136 | 137 | // run command on it 138 | emscrWasmExe.runHeadless( 139 | argv, 140 | files, 141 | onFinish, 142 | onError, 143 | onSuccess, 144 | stdinPreset 145 | ) 146 | } else if (wasmModuleType == "wasmer") { 147 | // instantiate new wasmer runnable 148 | let wasmerExe = new WasmerRunnable(programName, wasmModule) 149 | 150 | // run command on it 151 | wasmerExe.runHeadless( 152 | argv, 153 | files, 154 | onFinish, 155 | onError, 156 | onSuccess, 157 | stdinPreset 158 | ) 159 | } else 160 | throw new Error( 161 | "Unknown wasm module type (can only handle emscripten or wasmer)" 162 | ) 163 | } 164 | 165 | // handles stdin calls from emscr (tty is passed by emscr js runtime) 166 | _onEmscrStdinCall(tty, stdinProxy, stdoutProxy, stderrProxy) { 167 | if (tty.input.length == 0) { 168 | // use last line from output buffer as prompt caption 169 | const promptCaption = this.outputBuffer.split(/\r?\n/g).pop() 170 | 171 | // get input from user via prompt 172 | const input = window.prompt(promptCaption) 173 | 174 | // if aborted -> end 175 | if (input == null) return null 176 | 177 | // print input to terminal 178 | stdoutProxy(input) 179 | if (!promptCaption) stdoutProxy("\r\n") 180 | 181 | // copy input value to tty input 182 | tty.input = (input + "\n").split("").map((char) => char.charCodeAt(0)) 183 | tty.input.push(null) // marks end 184 | } 185 | 186 | // deliver input 187 | return tty.input.shift() 188 | } 189 | 190 | // handles stdin calls from wasmer 191 | _onWasmerStdinCall(stdinBuffer, stdinProxy, stdoutProxy, stderrProxy) { 192 | // use last line from output buffer as prompt caption 193 | const promptCaption = this.outputBuffer.split(/\r?\n/g).pop() 194 | 195 | // get input from user via prompt 196 | const input = window.prompt(promptCaption) 197 | 198 | // if aborted -> end 199 | if (input == null) return 0 200 | 201 | // print input to terminal 202 | stdoutProxy(input) 203 | if (!promptCaption) stdoutProxy("\r\n") 204 | 205 | // copy input value to stdinBuffer 206 | Array.from(input + "\n").forEach( 207 | (char, i) => (stdinBuffer[i] = char.charCodeAt(0)) 208 | ) 209 | 210 | // return how much to read 211 | return input.length + 1 212 | } 213 | } 214 | 215 | export default WasmRunner 216 | export const MODULE_ID = __webpack_module__.id 217 | -------------------------------------------------------------------------------- /src/runners/WasmWorker.js: -------------------------------------------------------------------------------- 1 | import { expose } from "comlink" 2 | // HACK: make `WasmRunner` and its dependecies available from the injected modules by the 3 | // main thread, instead of importing and bundling them directly. 4 | import "./ImportInjectedModules" 5 | import WasmRunner from "./WasmRunner" 6 | 7 | class WasmWorker extends WasmRunner { 8 | #pauseBuffer 9 | #stdinBuffer 10 | 11 | constructor(pauseBuffer, stdinBuffer) { 12 | super() 13 | // buffers can be accessed both from the main thread and the worker 14 | this.#pauseBuffer = pauseBuffer // used to pause/resume worker execution 15 | this.#stdinBuffer = stdinBuffer // used to pass user inputs to worker 16 | } 17 | 18 | // note: running commands is handled by parent class 19 | 20 | /* pausing and resuming */ 21 | 22 | pauseExecution() { 23 | console.log("pausing worker execution") 24 | Atomics.store(this.#pauseBuffer, 0, 1) // mem[0] = 1 (means hold) 25 | Atomics.wait(this.#pauseBuffer, 0, 1) // wait while value is 1 26 | console.log("resuming worker execution") 27 | } 28 | 29 | resumeExecution() { 30 | console.log("resuming worker execution") 31 | Atomics.store(this.#pauseBuffer, 0, 0) // mem[0] = 0 (means do not hold) 32 | // note: this method is just for completeness (the worker will be 33 | // resumed from outside by changing the pause buffer value) 34 | } 35 | 36 | /* input output handling */ 37 | 38 | #readStdinBuffer(index = null) { 39 | // null = read all 40 | if (index != null) return Atomics.load(this.#stdinBuffer, index) 41 | let result = [] 42 | for (let i = 0; i < this.#stdinBuffer.length; i++) { 43 | const value = Atomics.load(this.#stdinBuffer, i) 44 | if (value === 0) break // 0 marks end of input 45 | result.push(value) 46 | } 47 | return result 48 | } 49 | 50 | // handles stdin calls from emscr (pause -> call stdin proxy -> deliver) 51 | _onEmscrStdinCall(tty, stdinProxy, stdoutProxy, stderrProxy) { 52 | if (tty.input.length == 0) { 53 | // read input (will set stdin buffer) 54 | stdinProxy(this.outputBuffer.split(/\r?\n/g).pop()) 55 | this.pauseExecution() // resumes after input 56 | 57 | // copy stdin buffer to tty input 58 | tty.input = this.#readStdinBuffer() 59 | this.outputBuffer += tty.input.map((c) => String.fromCharCode(c)).join("") 60 | 61 | if (tty.input.length == 0) return null 62 | else tty.input.push(null) // marks end 63 | } 64 | 65 | // deliver input 66 | return tty.input.shift() 67 | } 68 | 69 | // handles stdin calls from wasmer 70 | _onWasmerStdinCall(stdinBuffer, stdinProxy, stdoutProxy, stderrProxy) { 71 | // read input (will set stdin buffer) 72 | stdinProxy(this.outputBuffer.split(/\r?\n/g).pop()) 73 | this.pauseExecution() // resumes after input 74 | 75 | // copy stdin buffer to stdinBuffer 76 | const _stdinBuffer = this.#readStdinBuffer() 77 | _stdinBuffer.forEach((char, i) => (stdinBuffer[i] = char)) 78 | this.outputBuffer += _stdinBuffer 79 | .map((c) => String.fromCharCode(c)) 80 | .join("") 81 | 82 | // return how much to read 83 | return _stdinBuffer.length 84 | } 85 | 86 | /* expose (sets up comlink communication) */ 87 | 88 | static expose() { 89 | expose(WasmWorker) 90 | } 91 | 92 | static isWorkerScope() { 93 | // checks if script is executed in worker or main thread 94 | return ( 95 | typeof WorkerGlobalScope != "undefined" && 96 | self instanceof WorkerGlobalScope 97 | ) 98 | } 99 | } 100 | 101 | // if this runs in worker scope -> expose 102 | if (WasmWorker.isWorkerScope()) WasmWorker.expose() 103 | 104 | export default WasmWorker 105 | -------------------------------------------------------------------------------- /webpack.config.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Webpack config to bundle WasmWebTerm 3 | * Generates the files "webterm.bundle.js" and "webterm.bundle.js.map" 4 | */ 5 | 6 | const webpack = require("webpack") 7 | 8 | module.exports = { 9 | entry: { 10 | WasmWebTerm: "./src/WasmWebTerm.js", 11 | }, 12 | output: { 13 | path: __dirname, 14 | filename: "webterm.bundle.js", 15 | library: { type: "umd", name: "[name]" }, 16 | }, 17 | optimization: { 18 | moduleIds: "deterministic", // share deterministic ids with the worker bundle 19 | }, 20 | plugins: [ 21 | new webpack.ProvidePlugin({ 22 | Buffer: ["buffer", "Buffer"], 23 | process: "process/browser", 24 | }), 25 | new webpack.DefinePlugin({ 26 | __VERSION__: JSON.stringify(process.env.npm_package_version), 27 | }), 28 | ], 29 | module: { 30 | rules: [ 31 | { 32 | test: __dirname + "/src/runners/WasmWorker.js", 33 | use: [{ loader: "worker-loader" }], 34 | type: "asset/source", 35 | }, 36 | ], 37 | }, 38 | resolveLoader: { 39 | alias: { "worker-loader": __dirname + "/worker.loader.js" }, 40 | }, 41 | devtool: "source-map", 42 | } 43 | -------------------------------------------------------------------------------- /worker.loader.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Webpack loader to prebundle WasmWorker. 3 | * This eliminates the need of a separate webworker js file. 4 | */ 5 | 6 | const path = require("path") 7 | const webpack = require("webpack") 8 | const memfs = require("memfs") 9 | 10 | function bytesToBase64DataUrl(bytes, type = "application/octet-stream") { 11 | const buffer = Buffer.from(bytes) 12 | const encoded = buffer.toString("base64") 13 | return `data:${type};base64,${encoded}` 14 | } 15 | 16 | async function compress(bytes, method = "gzip") { 17 | const blob = new Blob([bytes]) 18 | const stream = blob.stream().pipeThrough(new CompressionStream(method)) 19 | const response = new Response(stream, { 20 | headers: { "Content-Type": `application/${method}` }, 21 | }) 22 | return response.arrayBuffer() 23 | } 24 | 25 | module.exports = function (source) { 26 | const inputFilename = "./src/runners/WasmWorker.js" 27 | const outputFilename = "worker.compiled.js" 28 | 29 | // create webpack compiler 30 | let compiler = webpack({ 31 | entry: inputFilename, 32 | output: { 33 | path: "/", 34 | filename: outputFilename, 35 | library: { 36 | type: "umd", 37 | name: "[name]", 38 | }, 39 | }, 40 | optimization: { 41 | moduleIds: "deterministic", // share deterministic ids with the main bundle 42 | }, 43 | externals: { 44 | // HACK: Do not bundle the `WasmRunner` module and its dependencies again. 45 | // Instead let the main thread forward it from its bundle when 46 | // instantiating the worker. 47 | "./WasmRunner": "global WasmRunner", 48 | }, 49 | plugins: [ 50 | new webpack.ProvidePlugin({ 51 | Buffer: ["buffer", "Buffer"], 52 | process: "process/browser", 53 | }), 54 | ], 55 | }) 56 | 57 | // make compiler use memfs as *output* file system 58 | compiler.outputFileSystem = memfs.createFsFromVolume(new memfs.Volume()) 59 | compiler.outputFileSystem.join = path.join.bind(path) 60 | 61 | return new Promise((resolve, reject) => { 62 | // compile webworker 63 | compiler.run(async (error, stats) => { 64 | // exit on errors 65 | if (error != null) reject(error) 66 | if (stats?.hasErrors()) reject(stats.compilation.errors) 67 | 68 | // read compiled bundle from file system and resolve 69 | try { 70 | const compiled = compiler.outputFileSystem.readFileSync( 71 | "/" + outputFilename, 72 | "utf-8" 73 | ) 74 | const compressed = await compress(compiled, "gzip") 75 | const encoded = bytesToBase64DataUrl(compressed, "application/gzip") 76 | console.log( 77 | "Worker size:", 78 | Math.ceil((compiled.length / 1024) * 10) / 10, 79 | "KiB,", 80 | Math.ceil((encoded.length / 1024) * 10) / 10, 81 | "KiB compressed" 82 | ) 83 | resolve(encoded) 84 | } catch (e) { 85 | console.error("Errors while compiling with worker.loader.js:", e) 86 | } 87 | }) 88 | }) 89 | } 90 | --------------------------------------------------------------------------------

WebAssembly WebTerm