ultravisor-beacon-capability 1.0.0

package/docs/examples/rest-endpoint-sync.md

@@ -0,0 +1,240 @@
+# Example: REST Endpoint Sync
+
+A capability that fetches data from one REST API and pushes it to another. Common use case: syncing records between services, pulling data from a vendor API into an internal system, or replicating configuration between environments.
+
+## Full Source
+
+```javascript
+const libFable = require('fable');
+const libBeaconCapability = require('ultravisor-beacon-capability');
+const libHTTPS = require('https');
+const libHTTP = require('http');
+const libURL = require('url');
+
+class RESTSync extends libBeaconCapability
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.serviceType = 'RESTSync';
+		this.capabilityName = 'RESTSync';
+	}
+
+	/**
+	 * Internal helper: make an HTTP request and return parsed JSON.
+	 */
+	_request(pURL, pMethod, pHeaders, pBody, fCallback)
+	{
+		let tmpParsed = libURL.parse(pURL);
+		let tmpLib = (tmpParsed.protocol === 'https:') ? libHTTPS : libHTTP;
+
+		let tmpHeaders = Object.assign({ 'Content-Type': 'application/json' }, pHeaders || {});
+
+		let tmpOptions = {
+			hostname: tmpParsed.hostname,
+			port: tmpParsed.port,
+			path: tmpParsed.path,
+			method: pMethod,
+			headers: tmpHeaders,
+			timeout: 30000
+		};
+
+		let tmpReq = tmpLib.request(tmpOptions, (pRes) =>
+		{
+			let tmpData = '';
+			pRes.on('data', (pChunk) => { tmpData += pChunk; });
+			pRes.on('end', () =>
+			{
+				let tmpParsedBody = null;
+				try { tmpParsedBody = JSON.parse(tmpData); }
+				catch (pParseError) { tmpParsedBody = tmpData; }
+
+				if (pRes.statusCode >= 400)
+				{
+					return fCallback(new Error(`HTTP ${pRes.statusCode}: ${tmpData.substring(0, 500)}`));
+				}
+				return fCallback(null, { StatusCode: pRes.statusCode, Body: tmpParsedBody });
+			});
+		});
+
+		tmpReq.on('error', (pError) => fCallback(pError));
+		tmpReq.on('timeout', () => { tmpReq.destroy(); fCallback(new Error('Request timed out')); });
+
+		if (pBody)
+		{
+			tmpReq.write(typeof pBody === 'string' ? pBody : JSON.stringify(pBody));
+		}
+		tmpReq.end();
+	}
+
+	// --- Action: FetchAndPost ---
+
+	get actionFetchAndPost_Description()
+	{
+		return 'Fetch records from a source API and POST each to a destination API';
+	}
+
+	get actionFetchAndPost_Schema()
+	{
+		return [
+			{ Name: 'SourceURL', DataType: 'String', Required: true, Description: 'GET endpoint that returns an array of records' },
+			{ Name: 'SourceHeaders', DataType: 'Object', Required: false },
+			{ Name: 'DestinationURL', DataType: 'String', Required: true, Description: 'POST endpoint for each record' },
+			{ Name: 'DestinationHeaders', DataType: 'Object', Required: false },
+			{ Name: 'RecordsPath', DataType: 'String', Required: false, Description: 'Dot-path to the array in the source response (e.g. "data.items")' },
+			{ Name: 'DryRun', DataType: 'Boolean', Required: false, Default: false }
+		];
+	}
+
+	actionFetchAndPost(pSettings, pWorkItem, fCallback, fReportProgress)
+	{
+		fReportProgress({ Percent: 5, Message: 'Fetching from source...' });
+
+		this._request(pSettings.SourceURL, 'GET', pSettings.SourceHeaders, null, (pFetchError, pFetchResult) =>
+		{
+			if (pFetchError)
+			{
+				return fCallback(pFetchError);
+			}
+
+			// Extract records array
+			let tmpRecords = pFetchResult.Body;
+			if (pSettings.RecordsPath)
+			{
+				let tmpParts = pSettings.RecordsPath.split('.');
+				for (let i = 0; i < tmpParts.length; i++)
+				{
+					tmpRecords = tmpRecords ? tmpRecords[tmpParts[i]] : undefined;
+				}
+			}
+
+			if (!Array.isArray(tmpRecords))
+			{
+				return fCallback(new Error(`Source did not return an array at path "${pSettings.RecordsPath || '(root)'}"`));
+			}
+
+			fReportProgress({ Percent: 20, Message: `Fetched ${tmpRecords.length} records` });
+
+			if (pSettings.DryRun)
+			{
+				return fCallback(null, {
+					Outputs: { DryRun: true, RecordCount: tmpRecords.length, SampleRecord: tmpRecords[0] || null },
+					Log: [`DRY RUN: Would POST ${tmpRecords.length} records to ${pSettings.DestinationURL}`]
+				});
+			}
+
+			// POST each record sequentially
+			let tmpIndex = 0;
+			let tmpSuccessCount = 0;
+			let tmpErrors = [];
+
+			let fnPostNext = () =>
+			{
+				if (tmpIndex >= tmpRecords.length)
+				{
+					return fCallback(null, {
+						Outputs: {
+							TotalRecords: tmpRecords.length,
+							SuccessCount: tmpSuccessCount,
+							ErrorCount: tmpErrors.length,
+							Errors: tmpErrors.slice(0, 20)
+						},
+						Log: [`Synced ${tmpSuccessCount}/${tmpRecords.length} records to ${pSettings.DestinationURL}`]
+					});
+				}
+
+				let tmpRecord = tmpRecords[tmpIndex];
+				tmpIndex++;
+
+				this._request(pSettings.DestinationURL, 'POST', pSettings.DestinationHeaders, tmpRecord, (pPostError) =>
+				{
+					if (pPostError)
+					{
+						tmpErrors.push({ Index: tmpIndex - 1, Error: pPostError.message });
+					}
+					else
+					{
+						tmpSuccessCount++;
+					}
+
+					let tmpPercent = 20 + Math.round((tmpIndex / tmpRecords.length) * 75);
+					fReportProgress({ Percent: tmpPercent, Message: `Posted ${tmpIndex} / ${tmpRecords.length}` });
+
+					setImmediate(fnPostNext);
+				});
+			};
+
+			fnPostNext();
+		});
+	}
+
+	// --- Action: MirrorEndpoint ---
+
+	get actionMirrorEndpoint_Description()
+	{
+		return 'GET from source and PUT the entire response body to a destination';
+	}
+
+	get actionMirrorEndpoint_Schema()
+	{
+		return [
+			{ Name: 'SourceURL', DataType: 'String', Required: true },
+			{ Name: 'SourceHeaders', DataType: 'Object', Required: false },
+			{ Name: 'DestinationURL', DataType: 'String', Required: true },
+			{ Name: 'DestinationHeaders', DataType: 'Object', Required: false }
+		];
+	}
+
+	actionMirrorEndpoint(pSettings, pWorkItem, fCallback)
+	{
+		this._request(pSettings.SourceURL, 'GET', pSettings.SourceHeaders, null, (pFetchError, pFetchResult) =>
+		{
+			if (pFetchError) return fCallback(pFetchError);
+
+			this._request(pSettings.DestinationURL, 'PUT', pSettings.DestinationHeaders, pFetchResult.Body, (pPutError, pPutResult) =>
+			{
+				if (pPutError) return fCallback(pPutError);
+				return fCallback(null, {
+					Outputs: {
+						SourceStatus: pFetchResult.StatusCode,
+						DestinationStatus: pPutResult.StatusCode
+					},
+					Log: [`Mirrored ${pSettings.SourceURL} -> ${pSettings.DestinationURL}`]
+				});
+			});
+		});
+	}
+}
+
+// --- Startup ---
+
+let tmpFable = new libFable({ Product: 'RESTSync', ProductVersion: '1.0.0' });
+tmpFable.addServiceType('RESTSync', RESTSync);
+let tmpCap = tmpFable.instantiateServiceProvider('RESTSync');
+
+tmpCap.connect(
+	{
+		ServerURL: process.env.ULTRAVISOR_URL || 'http://localhost:54321',
+		Name: 'rest-sync-worker'
+	},
+	(pError) =>
+	{
+		if (pError) throw pError;
+		console.log('REST sync beacon online');
+	});
+
+process.on('SIGTERM', () => { tmpCap.disconnect(() => process.exit(0)); });
+```
+
+## Registered Task Types
+
+- `beacon-restsync-fetchandpost`
+- `beacon-restsync-mirrorendpoint`
+
+## Key Points
+
+- **No external HTTP library** -- uses Node.js built-in modules
+- **RecordsPath** supports dot-notation for extracting arrays from nested JSON (e.g. `data.results`)
+- **Sequential POSTs** avoid overwhelming the destination API; use `MaxConcurrent` on the beacon config for parallelism at the work item level
+- **DryRun** fetches from source but skips destination writes
+- **Error collection** is capped at 20 entries to avoid massive outputs

package/docs/examples/server-metrics-collection.md

@@ -0,0 +1,199 @@
+# Example: Server Metrics Collection
+
+A capability that collects CPU, memory, disk, and process metrics from the host machine. Schedule it to run every few minutes to build a lightweight time series of infrastructure health in Ultravisor.
+
+## Full Source
+
+```javascript
+const libFable = require('fable');
+const libBeaconCapability = require('ultravisor-beacon-capability');
+const libChildProcess = require('child_process');
+const libOS = require('os');
+
+class ServerMetrics extends libBeaconCapability
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.serviceType = 'ServerMetrics';
+		this.capabilityName = 'ServerMetrics';
+	}
+
+	// --- Action: CollectAll ---
+
+	get actionCollectAll_Description()
+	{
+		return 'Collect CPU, memory, disk, and load average metrics from the host';
+	}
+
+	actionCollectAll(pSettings, pWorkItem, fCallback)
+	{
+		let tmpMetrics = {
+			Timestamp: new Date().toISOString(),
+			Hostname: libOS.hostname(),
+			Platform: libOS.platform(),
+			Arch: libOS.arch(),
+			Uptime: libOS.uptime(),
+			LoadAverage: libOS.loadavg(),
+			CPUs: libOS.cpus().length,
+			TotalMemoryMB: Math.round(libOS.totalmem() / (1024 * 1024)),
+			FreeMemoryMB: Math.round(libOS.freemem() / (1024 * 1024)),
+			MemoryUsagePercent: Math.round((1 - libOS.freemem() / libOS.totalmem()) * 100)
+		};
+
+		// Get disk usage
+		libChildProcess.exec("df -h / | tail -1 | awk '{print $2, $3, $4, $5}'", (pError, pStdOut) =>
+		{
+			if (!pError && pStdOut.trim())
+			{
+				let tmpParts = pStdOut.trim().split(/\s+/);
+				tmpMetrics.DiskTotal = tmpParts[0] || 'unknown';
+				tmpMetrics.DiskUsed = tmpParts[1] || 'unknown';
+				tmpMetrics.DiskAvailable = tmpParts[2] || 'unknown';
+				tmpMetrics.DiskUsagePercent = tmpParts[3] || 'unknown';
+			}
+
+			return fCallback(null, {
+				Outputs: tmpMetrics,
+				Log: [
+					`${tmpMetrics.Hostname}: CPU load ${tmpMetrics.LoadAverage[0].toFixed(2)}, ` +
+					`Memory ${tmpMetrics.MemoryUsagePercent}%, ` +
+					`Disk ${tmpMetrics.DiskUsagePercent || 'N/A'}`
+				]
+			});
+		});
+	}
+
+	// --- Action: TopProcesses ---
+
+	get actionTopProcesses_Description()
+	{
+		return 'List the top processes by CPU or memory usage';
+	}
+
+	get actionTopProcesses_Schema()
+	{
+		return [
+			{ Name: 'SortBy', DataType: 'String', Required: false, Default: 'cpu', Description: '"cpu" or "memory"' },
+			{ Name: 'Count', DataType: 'Integer', Required: false, Default: 10 }
+		];
+	}
+
+	actionTopProcesses(pSettings, pWorkItem, fCallback)
+	{
+		let tmpSortFlag = (pSettings.SortBy === 'memory') ? '-m' : '-r';
+		let tmpCount = parseInt(pSettings.Count, 10) || 10;
+
+		// macOS and Linux have different ps flags; use a portable approach
+		let tmpCmd = `ps aux --sort=${(pSettings.SortBy === 'memory') ? '-%mem' : '-%cpu'} | head -${tmpCount + 1}`;
+
+		libChildProcess.exec(tmpCmd, (pError, pStdOut) =>
+		{
+			if (pError)
+			{
+				// Fallback for macOS
+				let tmpFallback = `ps aux | sort -nrk ${(pSettings.SortBy === 'memory') ? '4' : '3'} | head -${tmpCount}`;
+				libChildProcess.exec(tmpFallback, (pFallbackError, pFallbackOut) =>
+				{
+					if (pFallbackError) return fCallback(pFallbackError);
+					return fCallback(null, {
+						Outputs: { Processes: pFallbackOut, SortedBy: pSettings.SortBy || 'cpu' },
+						Log: [`Top ${tmpCount} processes by ${pSettings.SortBy || 'cpu'}`]
+					});
+				});
+				return;
+			}
+
+			return fCallback(null, {
+				Outputs: { Processes: pStdOut, SortedBy: pSettings.SortBy || 'cpu' },
+				Log: [`Top ${tmpCount} processes by ${pSettings.SortBy || 'cpu'}`]
+			});
+		});
+	}
+
+	// --- Action: NetworkConnections ---
+
+	get actionNetworkConnections_Description()
+	{
+		return 'Count active network connections by state';
+	}
+
+	actionNetworkConnections(pSettings, pWorkItem, fCallback)
+	{
+		let tmpCmd = "netstat -an 2>/dev/null | awk '/tcp/ {print $6}' | sort | uniq -c | sort -rn";
+
+		libChildProcess.exec(tmpCmd, (pError, pStdOut) =>
+		{
+			if (pError)
+			{
+				// Fallback: try ss on Linux
+				let tmpFallback = "ss -tan | awk 'NR>1 {print $1}' | sort | uniq -c | sort -rn";
+				libChildProcess.exec(tmpFallback, (pFallbackError, pFallbackOut) =>
+				{
+					if (pFallbackError) return fCallback(pFallbackError);
+					return this._parseConnectionCounts(pFallbackOut, fCallback);
+				});
+				return;
+			}
+
+			this._parseConnectionCounts(pStdOut, fCallback);
+		});
+	}
+
+	_parseConnectionCounts(pOutput, fCallback)
+	{
+		let tmpStates = {};
+		let tmpTotal = 0;
+		let tmpLines = pOutput.trim().split('\n');
+
+		for (let i = 0; i < tmpLines.length; i++)
+		{
+			let tmpMatch = tmpLines[i].trim().match(/(\d+)\s+(.*)/);
+			if (tmpMatch)
+			{
+				let tmpCount = parseInt(tmpMatch[1], 10);
+				tmpStates[tmpMatch[2]] = tmpCount;
+				tmpTotal += tmpCount;
+			}
+		}
+
+		return fCallback(null, {
+			Outputs: { States: tmpStates, TotalConnections: tmpTotal },
+			Log: [`Network connections: ${tmpTotal} total`]
+		});
+	}
+}
+
+// --- Startup ---
+
+let tmpFable = new libFable({ Product: 'ServerMetrics', ProductVersion: '1.0.0' });
+tmpFable.addServiceType('ServerMetrics', ServerMetrics);
+let tmpCap = tmpFable.instantiateServiceProvider('ServerMetrics');
+
+tmpCap.connect(
+	{
+		ServerURL: process.env.ULTRAVISOR_URL || 'http://localhost:54321',
+		Name: `metrics-${libOS.hostname()}`
+	},
+	(pError) =>
+	{
+		if (pError) throw pError;
+		console.log('Server metrics beacon online');
+	});
+
+process.on('SIGTERM', () => { tmpCap.disconnect(() => process.exit(0)); });
+```
+
+## Registered Task Types
+
+- `beacon-servermetrics-collectall`
+- `beacon-servermetrics-topprocesses`
+- `beacon-servermetrics-networkconnections`
+
+## Key Points
+
+- **CollectAll** uses the Node.js `os` module for cross-platform metrics, with `df` for disk info
+- **TopProcesses** includes a macOS fallback when Linux-style `ps --sort` is unavailable
+- **NetworkConnections** tries `netstat` first, then falls back to `ss`
+- Schedule `CollectAll` every 5 minutes in Ultravisor to build a lightweight metrics history
+- The beacon name includes the hostname, so multiple servers can register the same capability

package/docs/examples/shell-commands.md

@@ -0,0 +1,176 @@
+# Example: Shell Commands
+
+Wrap basic shell commands as beacon actions. This is the simplest possible capability -- each action executes a shell command and returns the output.
+
+## Full Source
+
+```javascript
+const libFable = require('fable');
+const libBeaconCapability = require('ultravisor-beacon-capability');
+const libChildProcess = require('child_process');
+
+class ShellCommands extends libBeaconCapability
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.serviceType = 'ShellCommands';
+		this.capabilityName = 'ShellCommands';
+	}
+
+	// --- Action: Ping ---
+
+	get actionPing_Description()
+	{
+		return 'Ping a host and return the result';
+	}
+
+	get actionPing_Schema()
+	{
+		return [
+			{ Name: 'Host', DataType: 'String', Required: true },
+			{ Name: 'Count', DataType: 'Integer', Required: false, Default: 4 }
+		];
+	}
+
+	actionPing(pSettings, pWorkItem, fCallback)
+	{
+		let tmpCount = pSettings.Count || 4;
+		let tmpCmd = `ping -c ${tmpCount} ${pSettings.Host}`;
+
+		this.log.info(`Pinging ${pSettings.Host} (${tmpCount} packets)...`);
+
+		libChildProcess.exec(tmpCmd, { timeout: 30000 }, (pError, pStdOut, pStdErr) =>
+		{
+			if (pError)
+			{
+				return fCallback(null, {
+					Outputs: { Success: false, StdOut: pStdOut || '', StdErr: pStdErr || '', ExitCode: pError.code },
+					Log: [`Ping failed: ${pError.message}`]
+				});
+			}
+			return fCallback(null, {
+				Outputs: { Success: true, StdOut: pStdOut, ExitCode: 0 },
+				Log: [`Pinged ${pSettings.Host} successfully`]
+			});
+		});
+	}
+
+	// --- Action: Uptime ---
+
+	get actionUptime_Description()
+	{
+		return 'Return the system uptime';
+	}
+
+	actionUptime(pSettings, pWorkItem, fCallback)
+	{
+		libChildProcess.exec('uptime', (pError, pStdOut) =>
+		{
+			if (pError) return fCallback(pError);
+			return fCallback(null, {
+				Outputs: { Uptime: pStdOut.trim() },
+				Log: ['Retrieved system uptime']
+			});
+		});
+	}
+
+	// --- Action: Whoami ---
+
+	get actionWhoami_Description()
+	{
+		return 'Return the current user and hostname';
+	}
+
+	actionWhoami(pSettings, pWorkItem, fCallback)
+	{
+		libChildProcess.exec('whoami && hostname', (pError, pStdOut) =>
+		{
+			if (pError) return fCallback(pError);
+			let tmpLines = pStdOut.trim().split('\n');
+			return fCallback(null, {
+				Outputs: { User: tmpLines[0], Hostname: tmpLines[1] || '' },
+				Log: ['Retrieved user and hostname']
+			});
+		});
+	}
+
+	// --- Action: RunCommand ---
+
+	get actionRunCommand_Description()
+	{
+		return 'Execute an arbitrary shell command with a timeout';
+	}
+
+	get actionRunCommand_Schema()
+	{
+		return [
+			{ Name: 'Command', DataType: 'String', Required: true },
+			{ Name: 'TimeoutSeconds', DataType: 'Integer', Required: false, Default: 60 },
+			{ Name: 'WorkingDirectory', DataType: 'String', Required: false }
+		];
+	}
+
+	actionRunCommand(pSettings, pWorkItem, fCallback)
+	{
+		let tmpOptions = {
+			timeout: (pSettings.TimeoutSeconds || 60) * 1000,
+			maxBuffer: 10 * 1024 * 1024
+		};
+
+		if (pSettings.WorkingDirectory)
+		{
+			tmpOptions.cwd = pSettings.WorkingDirectory;
+		}
+
+		this.log.info(`Executing: ${pSettings.Command}`);
+
+		libChildProcess.exec(pSettings.Command, tmpOptions, (pError, pStdOut, pStdErr) =>
+		{
+			let tmpExitCode = pError ? (pError.code || 1) : 0;
+			return fCallback(null, {
+				Outputs: {
+					StdOut: pStdOut || '',
+					StdErr: pStdErr || '',
+					ExitCode: tmpExitCode,
+					Success: tmpExitCode === 0
+				},
+				Log: [`Command exited with code ${tmpExitCode}`]
+			});
+		});
+	}
+}
+
+// --- Startup ---
+
+let tmpFable = new libFable({ Product: 'ShellCommands', ProductVersion: '1.0.0' });
+tmpFable.addServiceType('ShellCommands', ShellCommands);
+let tmpCap = tmpFable.instantiateServiceProvider('ShellCommands');
+
+tmpCap.connect(
+	{
+		ServerURL: process.env.ULTRAVISOR_URL || 'http://localhost:54321',
+		Name: `shell-${require('os').hostname()}`,
+		MaxConcurrent: 4
+	},
+	(pError, pInfo) =>
+	{
+		if (pError) throw pError;
+		console.log(`Shell commands beacon online: ${pInfo.BeaconID}`);
+	});
+
+process.on('SIGTERM', () => { tmpCap.disconnect(() => process.exit(0)); });
+```
+
+## Registered Task Types
+
+- `beacon-shellcommands-ping`
+- `beacon-shellcommands-uptime`
+- `beacon-shellcommands-whoami`
+- `beacon-shellcommands-runcommand`
+
+## Key Points
+
+- `exec` timeout prevents long-running commands from hanging
+- Failed commands return results with `Success: false` rather than calling `fCallback(pError)` -- this ensures the work item completes (with error data in Outputs) rather than being marked as a hard failure
+- `maxBuffer` is raised to 10MB for commands that produce large output

package/docs/index.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<meta http-equiv="X-UA-Compatible" content="IE=edge">
+		<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+		<meta name="description" content="Ultravisor Beacon Capability v0.0.1 Documentation — Convention-based base class for building Ultravisor beacon capabilities with minimal boilerplate">
+
+		<title>Ultravisor Beacon Capability v0.0.1 Documentation</title>
+
+		<!-- Application Stylesheet -->
+		<link href="css/docuserve.css" rel="stylesheet">
+		<!-- KaTeX stylesheet for LaTeX equation rendering -->
+		<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css">
+		<!-- PICT Dynamic View CSS Container -->
+		<style id="PICT-CSS"></style>
+
+		<!-- Load the PICT library from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict@1/dist/pict.min.js" type="text/javascript"></script>
+		<!-- Bootstrap the Application -->
+		<script type="text/javascript">
+//<![CDATA[
+		Pict.safeOnDocumentReady(() => { Pict.safeLoadPictApplication(PictDocuserve, 2)});
+//]]>
+		</script>
+	</head>
+	<body>
+		<!-- The root container for the Pict application -->
+		<div id="Docuserve-Application-Container"></div>
+
+		<!-- Mermaid diagram rendering -->
+		<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+		<script>mermaid.initialize({ startOnLoad: false, theme: 'default' });</script>
+		<!-- KaTeX for LaTeX equation rendering -->
+		<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js"></script>
+		<!-- Load the Docuserve PICT Application Bundle from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict-docuserve@0/dist/pict-docuserve.min.js" type="text/javascript"></script>
+	</body>
+</html>