@amxts/core 0.1.0 → 0.2.0

package/scripts/compile.ts

@@ -1,4 +1,6 @@
 import type { PluginNative } from './plugin-natives';
+import type { Sources } from './project';
+import type { PluginMap } from './source-map';
 import type { System } from './system';
 import { spawnSync } from 'node:child_process';
 
@@ -17,10 +19,13 @@ import * as assemblyscript from '../runtime/deps/assemblyscript/dist/assemblyscr
 // @ts-ignore - its types are beside it, under a path tsconfig does not map
 import binaryen from '../runtime/deps/assemblyscript/node_modules/binaryen/index.js';
 import { ascMain } from './asc';
+import { ABI_SECTION, abiIdentity } from './build-identity';
 import { playerFieldsBuild } from './player-fields';
 import { includeName, nativeContract, nativesTransform, pawnInclude } from './plugin-natives';
 import { ascPath, sourcesFor } from './project';
+import { targetTransforms } from './reapi-events';
 import { sharedModulesBuild } from './shared-modules';
+import { displayName, MAP_SECTION, mapText, pluginMap, withSection } from './source-map';
 import { HOST_SYSTEM, TARGET_ABI } from './system';
 
 export interface Plugin {
@@ -96,6 +101,35 @@ export class HoistImports {
 /** The import a coroutine parks in - the one Asyncify unwinds from. */
 export const SUSPEND_IMPORT = 'env.co_suspend';
 
+/** The import of a plugin that makes a promise: it is compiled again with ASYNC_EXPORTS. */
+const WAKE_IMPORT = 'env.co_wake';
+
+/**
+ * What wamrc keeps for a failed call's stack (scripts/source-map.ts): each
+ * function's frame with its index and the offset of the call it is in, or of
+ * the trap - a store at each call, a push and a pop at each function. No
+ * values: with them WAMR's frames are no longer the small ones. A dev build's
+ * alone (`amxts dev`, a quick build): measured, the frames took a fifth to a
+ * third of a call-heavy plugin's time, so a full build keeps none, and an
+ * error there says its message - and a throw or an abort its place.
+ */
+const STACK_FLAGS = ['--enable-dump-call-stack', '--call-stack-features=bounds-checks,ip,func-idx,trap-ip'];
+
+/**
+ * The map goes into the .aot either way, and so does the ABI the plugin is
+ * compiled against, which the module checks before it loads it
+ * (scripts/build-identity.ts).
+ */
+const SECTIONS = `--emit-custom-sections=${MAP_SECTION},${ABI_SECTION}`;
+
+/**
+ * The CPU the machine code is for: a Pentium 4's, SSE2. LLVM's i386 left
+ * alone does fractions on the x87, where a number made whole - every `%`,
+ * every number given where a cell goes - costs several times as much. Every
+ * CPU a game server runs on has SSE2.
+ */
+const CPU = '--cpu=pentium4';
+
 /**
  * Where compilePlugin writes the Pawn include for a plugin's natives: beside
  * the .aot, named after the plugin - or, for a plugin that implements an
@@ -134,6 +168,9 @@ export function compileToMachineCode(plugin: Plugin, wasm: string, natives: Plug
 		'--target=i386',
 		`--target-abi=${TARGET_ABI[plugin.system ?? HOST_SYSTEM]}`,
 		`--native-signatures=${plugin.signatures}`,
+		...(plugin.quick ? STACK_FLAGS : []),
+		SECTIONS,
+		CPU,
 		...level,
 		'-o',
 		part,
@@ -150,12 +187,13 @@ export function compileToMachineCode(plugin: Plugin, wasm: string, natives: Plug
 
 	if (compile.status !== 0) {
 		rmSync(part, { force: true });
-		return out;
+		// A crash says nothing: still a failure, not an empty problem
+		return out.trim() || `wamrc stopped (${compile.status ?? compile.signal}) without a word`;
 	}
 
 	// A signature that disagrees with its import is not an error to wamrc: it
-	// drops that native to the generic path, 28 ns a call instead of 2, and
-	// says so only in this warning. That means the API and the module have
+	// drops that native to the generic path, many times slower than the direct
+	// call, and says so only in this warning. That means the API and the module have
 	// drifted apart, which is worth refusing rather than running slowly.
 	if (/failed to check signature/.test(out)) {
 		rmSync(part, { force: true });
@@ -182,9 +220,10 @@ export function writeInclude(output: string, natives: PluginNative[]): void {
 
 /**
  * The first half of compilePlugin: the plugin's .ts to `wasm`, ready for
- * wamrc. Tests run the result as it is; with `names` it keeps its function
- * names, so a test can see what Asyncify instrumented. With `natives`, the
- * plugin's `export function`s become natives, listed there.
+ * wamrc, with its map (scripts/source-map.ts). Tests run the result as it is;
+ * with `names` it keeps its function names, so a test can see what Asyncify
+ * instrumented. With `natives`, the plugin's `export function`s become
+ * natives, listed there.
  */
 export async function compileToWasm(
 	plugin: Pick<Plugin, 'source' | 'root' | 'quick'>,
@@ -193,53 +232,93 @@ export async function compileToWasm(
 	natives?: PluginNative[],
 ): Promise<string | null> {
 	// A quick build leaves the optimising to one Binaryen pass afterwards.
-	const flags = [...(plugin.quick ? [] : ['--optimize']), ...(names ? ['--debug'] : [])];
-	const level = plugin.quick ? OPTIMIZE.quick : OPTIMIZE.full;
-	let problem = await compileWasm(plugin, wasm, BASE_EXPORTS, flags, natives);
-	if (problem) return problem;
+	const flags = [...(plugin.quick ? [] : ['--optimize']), ...(names ? ['--debug'] : []), '--sourceMap'];
+	const level = plugin.quick ? OPTIMIZE.quick : null;
+	let made = await compileWasm(plugin, BASE_EXPORTS, flags, level, natives);
 
 	// A plugin that makes a promise - an async function, fetch, sleep - has
 	// the host drive its jobs, so it is compiled again with the scheduler's
-	// exports. Only then, and only when a coroutine can park, does Asyncify
-	// run: a plugin without either is the same wasm it always was.
-	if (importsOf(readFileSync(wasm)).has('env.co_wake')) {
+	// exports.
+	if (typeof made !== 'string' && importsOf(made.binary).has(WAKE_IMPORT)) {
 		if (natives) natives.length = 0;
-		problem = await compileWasm(plugin, wasm, ASYNC_EXPORTS, flags, natives);
-		if (problem) return problem;
+		made = await compileWasm(plugin, ASYNC_EXPORTS, flags, level, natives);
 	}
-	const binary = readFileSync(wasm);
-	if (importsOf(binary).has(SUSPEND_IMPORT)) writeFileSync(wasm, asyncify(binary, names, level));
-	else if (plugin.quick) writeFileSync(wasm, optimized(binary, level));
+	if (typeof made === 'string') return made;
+	mkdirSync(dirname(resolve(wasm)), { recursive: true });
+	writeFileSync(wasm, withSection(withSection(made.binary, MAP_SECTION, mapText(made.map)), ABI_SECTION, abiIdentity()));
 	return null;
 }
 
+/**
+ * The last transform of a compile: Binaryen's work after asc's own, on the
+ * module asc is about to write - a quick build's optimisation at `level`,
+ * and Asyncify for a plugin whose coroutines can park. It runs there rather
+ * than on the written binary so that the source map asc writes beside it is
+ * of the code that runs: Binaryen reads a binary without its map. asc has no
+ * hook after its optimiser, so this wraps the module's emitBinary, which asc
+ * calls once to write the module. `done` gets the functions' names, by wasm
+ * index, as they are written.
+ *
+ * A plugin that makes a promise but was compiled without the scheduler's
+ * exports is compiled again (compileToWasm), so nothing is done for it.
+ */
+export function finishing(hoodExports: string, level: number | null, done: (first: number, names: string[]) => void = () => {}) {
+	return {
+		afterCompile(module: any) {
+			const emit = module.emitBinary.bind(module);
+			module.emitBinary = (url?: string) => {
+				const imports = new Set(functionsOf(module).map(each => each.imported));
+				if (hoodExports === ASYNC_EXPORTS || !imports.has(WAKE_IMPORT)) {
+					if (imports.has(SUSPEND_IMPORT)) asyncify(module, level ?? OPTIMIZE.full);
+					else if (level !== null) optimize(module, level);
+				}
+				const functions = functionsOf(module);
+				const first = functions.filter(each => each.imported).length;
+				done(first, functions.slice(first).map(each => each.name));
+				return emit(url);
+			};
+		},
+	};
+}
+
+/**
+ * The module's functions in the order of their wasm indexes - Binaryen
+ * writes the imported ones first, then the rest, each in its own order -
+ * with each one's name, and `module.name` when it is imported.
+ */
+function functionsOf(module: any): { name: string; imported: string | null }[] {
+	const functions = Array.from({ length: module.getNumFunctions() }, (_, i) => binaryen.getFunctionInfo(module.getFunctionByIndex(i)));
+	const ordered = [...functions.filter(info => info.module), ...functions.filter(info => !info.module)];
+	return ordered.map(info => ({ name: info.name, imported: info.module ? `${info.module}.${info.base}` : null }));
+}
+
 /** Binaryen's optimisation at `level`: what a quick build runs in place of asc's. */
-function optimized(wasm: Uint8Array, level: number): Uint8Array {
-	const module = binaryen.readBinary(wasm);
-	try {
-		module.setFeatures(binaryen.Features.All);
-		binaryen.setOptimizeLevel(level);
-		binaryen.setShrinkLevel(0);
-		module.optimize();
-		return module.emitBinary();
-	} finally {
-		module.dispose();
-	}
+function optimize(module: any, level: number) {
+	binaryen.setOptimizeLevel(level);
+	binaryen.setShrinkLevel(0);
+	module.optimize();
+}
+
+/** What asc made of a plugin: the binary, and its map. */
+interface Compiled {
+	binary: Uint8Array;
+	map: PluginMap;
 }
 
 /**
- * asc, from the plugin's .ts to `wasm`, with `hoodExports` as the second entry.
- * With `natives`, the plugin's `export function`s become its natives and are
- * listed there; without, they stay plain wasm exports - what a test host that
- * calls a fixture's functions by name wants.
+ * asc, from the plugin's .ts to a binary and its map, with `hoodExports` as
+ * the second entry and `level` a quick build's (finishing). With `natives`,
+ * the plugin's `export function`s become its natives and are listed there;
+ * without, they stay plain wasm exports - what a test host that calls a
+ * fixture's functions by name wants. What went wrong, as text.
  */
 async function compileWasm(
 	plugin: Pick<Plugin, 'source' | 'root'>,
-	wasm: string,
 	hoodExports: string,
 	flags: string[],
+	level: number | null,
 	natives?: PluginNative[],
-): Promise<string | null> {
+): Promise<Compiled | string> {
 	// --exportTable is not optional: a handler reaches the module as its index
 	// in the function table, and without this asc emits no table at all, so
 	// every index points at nothing.
@@ -260,6 +339,9 @@ async function compileWasm(
 		return String((problem as Error).message ?? problem);
 	}
 
+	let binary: Uint8Array | null = null;
+	let sourceMap = '';
+	let functions = { first: 0, names: [] as string[] };
 	const { error, stderr } = await ascMain(
 		[
 			entry,
@@ -268,7 +350,7 @@ async function compileWasm(
 			// entry file's exports reach the wasm).
 			HOOD_EXPORTS,
 			'--outFile',
-			wasm,
+			'plugin.wasm',
 			'--exportTable',
 			...flags,
 		],
@@ -282,21 +364,25 @@ async function compileWasm(
 				return text === null ? null : shared.read(path, playerFields.read(relative('.', (sources.real(path) ?? path)), text));
 			},
 
-			writeFile(filename: string, contents: string | Uint8Array): void {
-				// The name asc passes back is the one it was given in --outFile,
-				// so it is already where the caller wants it.
-				const path = resolve(filename);
-				mkdirSync(dirname(path), { recursive: true });
-				writeFileSync(path, contents);
+			// The binary and its source map, for compileToWasm to write as one.
+			writeFile(_: string, contents: string | Uint8Array): void {
+				if (typeof contents === 'string') sourceMap = contents;
+				else binary = contents;
 			},
 
 			listFiles(): string[] {
 				return [];
 			},
 
-			transforms: natives
-				? [HoistImports, nativesTransform(entry, natives, plugin.root), playerFields.transform, shared.transform]
-				: [HoistImports, playerFields.transform, shared.transform],
+			transforms: [
+				HoistImports,
+				...(natives ? [nativesTransform(entry, natives, plugin.root)] : []),
+				playerFields.transform,
+				shared.transform,
+				// A project for plain HLDS listens for no event reapi alone delivers.
+				...targetTransforms(sources.project.config?.target),
+				finishing(hoodExports, level, (first, names) => (functions = { first, names })),
+			],
 		},
 	);
 
@@ -306,7 +392,26 @@ async function compileWasm(
 
 	// A transform's refusal - a native whose signature cannot cross - is an
 	// error with nothing written to stderr.
-	return error ? (stderr.toString() || String(error.message ?? error)) : null;
+	if (error || !binary) return stderr.toString() || String(error?.message ?? error);
+	// A quick build is a dev build (`amxts dev`): its map names the project's
+	// folder, where the module finds the sources to show a failed line. A
+	// build to ship names none - the machine's folders are not the server's.
+	const root = level === null ? '' : sources.project.dir;
+	return { binary, map: pluginMap(sourceMap, file => fileName(sources, plugin.root, file), functions.first, functions.names.map(displayName), root) };
+}
+
+/**
+ * A file of asc's source map as the plugin's map names it: as the project
+ * names it - `plugins/shop.ts`, `node_modules/@amxts/core/as/facade.ts` - or
+ * null for AssemblyScript's standard library, whose lines would double the
+ * map and mean nothing to an author; its functions keep their names.
+ */
+function fileName(sources: Sources, root: string, file: string): string | null {
+	// asc reads `~/` - the plugins folder - as a library of its own
+	const hood = /^~lib\/~\/(.*)$/.exec(file);
+	if (!hood && file.startsWith('~lib/')) return null;
+	const path = hood ? resolve(root, hood[1]) : ascPath(root, file, '');
+	return relative(sources.project.dir, sources.real(path) ?? path).replace(/\\/g, '/');
 }
 
 /**
@@ -319,28 +424,20 @@ async function compileWasm(
  * prologue asks co_spawn to call it - so no `await` is ever reached through
  * a function table, and a listener that is async returns to its caller at its
  * first `await` like any other call. Nothing can be missing from the list,
- * which is the failure that hangs rather than traps.
+ * which is the failure that hangs rather than traps. Then the optimiser at
+ * `level` - asc's own, or a quick build's lower one - so the rest of the
+ * module comes out as it went in.
  */
-export function asyncify(wasm: Uint8Array, names = false, level = OPTIMIZE.full): Uint8Array {
-	const module = binaryen.readBinary(wasm);
+function asyncify(module: any, level: number) {
 	try {
-		module.setFeatures(binaryen.Features.All);
 		binaryen.setPassArgument('asyncify-imports', SUSPEND_IMPORT);
 		binaryen.setPassArgument('asyncify-ignore-indirect', '1');
-		// asc's own --optimize levels (a quick build's lower one), so the rest
-		// of the module comes out as it went in.
-		binaryen.setOptimizeLevel(level);
-		binaryen.setShrinkLevel(0);
-		binaryen.setDebugInfo(names);
 		module.runPasses(['asyncify']);
-		module.optimize();
+		optimize(module, level);
 		if (!module.validate()) throw new Error('Asyncify produced an invalid module');
-		return module.emitBinary();
 	} finally {
 		binaryen.setPassArgument('asyncify-imports', null);
 		binaryen.setPassArgument('asyncify-ignore-indirect', null);
-		binaryen.setDebugInfo(false);
-		module.dispose();
 	}
 }
 

package/scripts/docker-server.ts

@@ -1,15 +1,25 @@
-// The Docker server a project runs on (docker/server, the amxts-server image):
-// which running containers mount the project, and their console.
+// The Docker server a project runs on (docker/server, published as
+// ghcr.io/amxts/server): which running containers mount the project, and
+// their console.
 //
 // `amxts dev --docker` builds into dist/, which such a container reads where
 // it is - its module reloads a plugin whose .aot changed - so nothing is
 // deployed. What is left is showing the developer the server's answer, and
 // that is the container's console: its amxts lines, as they come.
 import { spawn, spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import process from 'node:process';
+import { serverImage } from './system';
 import { c } from './ui';
 
+/**
+ * The server image of this core's version. Its module loads only the .aot of
+ * the same release's wamrc, so a project runs on the image of its own core;
+ * `bun run server:image` builds it from a checkout under the same name.
+ */
+export const SERVER_IMAGE = serverImage(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+
 /** Where the image takes a project from. */
 const PROJECT_MOUNT = '/project';
 
@@ -69,5 +79,5 @@ export function followConsoles(names: string[]): void {
 
 /** The command that starts the server for this project. */
 export function runCommand(projectDir: string): string {
-	return `docker run --rm -it -p 27015:27015/udp -v "${resolve(projectDir)}:${PROJECT_MOUNT}" amxts-server`;
+	return `docker run --rm -it -p 27015:27015/udp -v "${resolve(projectDir)}:${PROJECT_MOUNT}" ${SERVER_IMAGE}`;
 }

package/scripts/docs/as/amxts.ts

@@ -207,4 +207,90 @@ export default {
 		en: `Stops calling a listener added with \`addEventListener\` - the same function and the same field.`,
 		ru: `Перестаёт вызывать обработчик, добавленный через \`addEventListener\`, — ту же функцию с тем же полем.`,
 	},
+	'Server.addCommand': {
+		en: `
+			Adds a command players type, by its usage: the name, then the
+			arguments, \`<name>\` required and \`[name]\` optional. Their types are an
+			interface, the type argument; without it each is text.
+
+			\`\`\`ts
+			interface KickArgs {
+			  target: Player;
+			  reason?: string;
+			}
+
+			server.addCommand<KickArgs>("/kick <target> [reason]", ({ player, target, reason }) => {
+			  target.kick(reason ?? \`Kicked by \${player.name}\`);
+			}, { access: "kick" });
+			server.addCommand("/hp", ({ player }) => print(player, \`\${player.health} HP\`));
+			\`\`\`
+
+			A name with \`/\` is a chat command, one without a console command, and
+			\`"say <phrase>"\` a phrase written in chat. A \`number\` argument is
+			parsed, a \`Player\` found by \`#userid\`, the whole name or a part of it,
+			a \`string\` taken as it is - the last one takes the rest of the line. A
+			word that is not what the command takes answers the player with the
+			usage, and the handler does not run.
+
+			Pawn: \`register_clcmd\`
+		`,
+		ru: `
+			Добавляет команду, которую набирают игроки, по её использованию: имя,
+			затем аргументы, \`<name>\` — обязательный, \`[name]\` — необязательный.
+			Их типы — интерфейс, аргумент типа; без него каждый — текст.
+
+			\`\`\`ts
+			interface KickArgs {
+			  target: Player;
+			  reason?: string;
+			}
+
+			server.addCommand<KickArgs>("/kick <target> [reason]", ({ player, target, reason }) => {
+			  target.kick(reason ?? \`Kicked by \${player.name}\`);
+			}, { access: "kick" });
+			server.addCommand("/hp", ({ player }) => print(player, \`\${player.health} HP\`));
+			\`\`\`
+
+			Имя со \`/\` — команда чата, без него — команда консоли, а
+			\`"say <фраза>"\` — фраза, написанная в чат. Аргумент \`number\`
+			разбирается как число, \`Player\` находится по \`#userid\`, имени целиком
+			или его части, \`string\` берётся как есть — последний забирает остаток
+			строки. На слово, которое команда не принимает, игрок получает её
+			использование, и обработчик не запускается.
+
+			Pawn: \`register_clcmd\`
+		`,
+	},
+	'Server.addServerCommand': {
+		en: `
+			Adds a command of the server console - typed there, sent over rcon or
+			run by another plugin - by its usage, its arguments read as a player's
+			command's are. No player types it.
+
+			\`\`\`ts
+			interface ResetArgs {
+			  what?: "scores" | "all";
+			}
+
+			server.addServerCommand<ResetArgs>("myplugin_reset [what]", ({ what }) => reset(what ?? "all"));
+			\`\`\`
+
+			Pawn: \`register_srvcmd\`
+		`,
+		ru: `
+			Добавляет команду консоли сервера — её набирают там, присылают по rcon
+			или запускает другой плагин — по её использованию; аргументы читаются
+			так же, как у команды игрока. Игрок её не набирает.
+
+			\`\`\`ts
+			interface ResetArgs {
+			  what?: "scores" | "all";
+			}
+
+			server.addServerCommand<ResetArgs>("myplugin_reset [what]", ({ what }) => reset(what ?? "all"));
+			\`\`\`
+
+			Pawn: \`register_srvcmd\`
+		`,
+	},
 };