/examples/basic.js at 8080245c2696cc6404b0628e5c3eb363cb80014f

// Copyright 2025 Shota FUJI
//
// Licensed under the Zero-Clause BSD License or the Apache License, Version 2.0, at your option.
// You may not use, copy, modify, or distribute this file except according to those terms. You can
// find a copy of the Zero-Clause BSD License at LICENSES/0BSD.txt, and a copy of the Apache License,
// Version 2.0 at LICENSES/Apache-2.0.txt. You may also obtain a copy of the Zero-Clause BSD License
// at <https://opensource.org/license/0bsd> and a copy of the Apache License, Version 2.0 at
// <https://www.apache.org/licenses/LICENSE-2.0>
//
// SPDX-License-Identifier: 0BSD OR Apache-2.0
//
// ===
//
// This example searches Roon Core on computer's subnet then print found one's information on
// stdout. (Bun does not have simply write to stderr. console.error forces text color to be red)
//
// You can run this example by running "bun ./examples/basic.js" from repository root.
// You need Bun (JavaScript runtime) and built ".wasm" file generated by "zig build wasm".
//
// While this works, you should use the official roon-node-api. This is only for demonstration
// purpose.
//
// Unlike basic.zig and basic.c, this example does not retry.

import dgram from "node:dgram";

const wasm = Bun.file(new URL("../zig-out/bin/sood.wasm", import.meta.url));

const { instance } = await WebAssembly.instantiate(await wasm.arrayBuffer());

// Using short alias for brevity.
const x = instance.exports;

const sock = dgram.createSocket({ type: "udp4" });

sock.on("error", err => {
	console.error(err);
});

// As there is no standard for "string" type, every WASM module have to come up with
// their own definition. This module represents strings in "address to UTF8 string
// and its byte size." Every string getters consists of two functions suffixed with
// "_ptr" and "_len". For example, getters for getting "bar" field from "foo" struct
// will be "get_foo_bar_ptr(foo_ptr)" and "get_foo_bar_len(foo_ptr)".
//
//  MEMORY: |   |'b'|'a'|'z'|   |   |
//              ^           ^
//      get_foo_bar_ptr   (end)
//  get_foo_bar_len = (end) - get_foo_bar_ptr
//
// After you know the address and length on the WASM linear memory, converts the byte
// array to UTF-8 string with your platform API/programming language. In this JavaScript
// example, we're using the standard "TextDecoder" web API for parsing the byte array
// (Uint8Array) to JavaScript string (UTF-16).
const utf8Decoder = new TextDecoder();

sock.on("message", (msg, { address }) => {
	// This "dgram" module is of Node.js, hence type of "msg" is non-standard Buffer type.
	// For compability, we're converting it to the standard Uint8Array.
	const messageBuffer = new Uint8Array(msg);

	let responsePtr = null;
	let bytesPtr = null;

	try {
		// In order to pass non-primitive data between WASM host and guest, we need to allocate
		// space at WASM linear memory then fill-in the data to the allocated space.
		// Our "sood.wasm" exports[0] internal memory via "exports.memory".
		// This line calls our allocator and returns the address of the space.
		// [0] ... Actually LLVM automatically exports the memory object.
		bytesPtr = x.allocate_bytes(messageBuffer.length);

		// Once allocated, copy the data byte-to-byte to the WASM linear memory.
		// This procedure differs by your platform/programming language.
		const bytesBuffer = new Uint8Array(x.memory.buffer, bytesPtr, messageBuffer.length);
		bytesBuffer.set(messageBuffer);

		// Allocate a struct to hold parsed result. Since "sood.wasm" knows how many bytes required
		// for the struct, we don't have to specify a size.
		responsePtr = x.allocate_discovery_response();

		// Parse "bytesBuffer", which is copy of "messageBuffer" ("msg"), then fill-in data
		// onto the previously allocated discovery response struct ("allocate_discovery_response").
		// If "result" is non-zero (= error), the discovery response struct remains empty.
		const result = x.parse_discovery_response_into(
			responsePtr,
			bytesPtr,
			messageBuffer.length,
		);

		// "sood.wasm" is not designed to use for reusing allocated space:
		// don't use pointer returned by allocator functions more than once.
		//
		// [DON'T]
		//   const ptr = allocate_discovery_response();
		//   x.parse_discovery_response_into(ptr, bytes1Ptr, bytes1Len);
		//   x.parse_discovery_response_into(ptr, bytes2Ptr, bytes2Len);
		//
		// [DO]
		//   const ptr1 = allocate_discovery_response();
		//   x.parse_discovery_response_into(ptr1, bytes1Ptr, bytes1Len);
		//   const ptr2 = allocate_discovery_response();
		//   x.parse_discovery_response_into(ptr2, bytes2Ptr, bytes2Len);

		// See definition for "WasmResultCode" in "wasm.zig" for each result codes.
		// Like most of the program, 0 means success.
		if (result !== 0) {
			console.log("Non 0 result received:");

			// If you don't have dedicated handlings for individual errors, use
			// "result_code_string_ptr/len" function to get the human readable name for
			// the error code.
			console.log(utf8Decoder.decode(
				new Uint8Array(
					x.memory.buffer,
					x.result_code_string_ptr(result),
					x.result_code_string_len(result),
				),
			));
			return;
		}

		// "get_discovery_response_*" functions retrieve corresponding fields.
		const name = utf8Decoder.decode(
			new Uint8Array(
				x.memory.buffer,
				x.get_discovery_response_name_ptr(responsePtr),
				x.get_discovery_response_name_len(responsePtr),
			),
		);

		const displayVersion = utf8Decoder.decode(
			new Uint8Array(
				x.memory.buffer,
				x.get_discovery_response_display_version_ptr(responsePtr),
				x.get_discovery_response_display_version_len(responsePtr),
			),
		);

		const uniqueId = utf8Decoder.decode(
			new Uint8Array(
				x.memory.buffer,
				x.get_discovery_response_unique_id_ptr(responsePtr),
				x.get_discovery_response_unique_id_len(responsePtr),
			),
		);

		console.log(`Name: \t\t${name}`);
		console.log(`Version: \t${displayVersion}`);
		console.log(`Unique ID: \t${uniqueId}`);

		// SOOD message does not include IP address of the Roon Server. You have to use
		// UDP message's sender IP address.
		console.log(`Address: \t${address}`);

		// HTTP port is unsigned 16-bit integer, therefore simply use the returned value.
		console.log(`HTTP Port: \t${x.get_discovery_response_http_port(responsePtr)}`);

		sock.close();
	} catch (err) {
		console.error(err);
	} finally {
		// Each strings in a parsed data refers to the source bytes, in this example, "bytesBuffer".
		// Because of this, use should free parsed data (discovery response, message, iterator) first
		// then the source bytes.
		if (typeof responsePtr === "number") {
			x.free_discovery_response(responsePtr);
		}

		// Size of bytes are not known in compile time. You have to pass the size.
		if (typeof bytesPtr === "number") {
			x.free_bytes(bytesPtr, messageBuffer.length);
		}
	}
});

const prebuilt = new Uint8Array(
	x.memory.buffer,
	x.prebuilt_discovery_query_ptr(),
	x.prebuilt_discovery_query_len(),
);

// Node.js dgram module takes IP address in string form.
// If you're using API that takes network byte order 32-bit IP address, just reads
// from the address as Uint32 Big Endian.
//
//   const view = new DataView(x.memory.buffer);
//   const multicastAddr = view.getUint32(x.get_discovery_multicast_ipv4_address(), false);
const multicastIpAddr = Array.from(
	new Uint8Array(x.memory.buffer, x.get_discovery_multicast_ipv4_address(), 4),
).map(n => n.toString(10)).join(".");

sock.bind({ port: 0 }, () => {
	// This is what the official roon-node-api. I don't know how important this is.
	sock.setMulticastTTL(1);

	sock.send(prebuilt, 0, prebuilt.length, x.get_discovery_server_udp_port(), multicastIpAddr);
});