ultravisor-beacon 0.0.2 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultravisor-beacon",
-	"version": "0.0.2",
+	"version": "0.0.4",
 	"description": "Ultravisor Beacon: lightweight beacon client and Fable service for remote task execution",
 	"main": "source/Ultravisor-Beacon-Service.cjs",
 	"scripts": {
@@ -22,7 +22,8 @@
 	"author": "Steven Velozo <steven@velozo.com>",
 	"license": "MIT",
 	"dependencies": {
-		"fable-serviceproviderbase": "^3.0.19"
+		"fable-serviceproviderbase": "^3.0.19",
+		"ws": "^8.20.0"
 	},
 	"devDependencies": {
 		"quackage": "^1.0.65"

package/source/Ultravisor-Beacon-AddressResolver.cjs

@@ -0,0 +1,367 @@
+/**
+ * Ultravisor Beacon Address Resolver
+ *
+ * Parses and resolves Universal Data Addresses — a URI scheme for
+ * referencing resources across a federated beacon mesh.
+ *
+ * Address format:
+ *   >BeaconID/Context/Path...
+ *
+ * Components:
+ *   >           — Prefix indicating a beacon-scoped resource
+ *   BeaconID    — The registered beacon's name or ID
+ *                  Special values: '*' (any beacon with required capability),
+ *                                  'ULTRAVISOR' (the orchestrator itself)
+ *   Context     — The namespace within the beacon:
+ *                  'File'       — Filesystem access (content root)
+ *                  'Staging'    — Work item staging area
+ *                  'Cache'      — Cache storage (thumbnails, previews, etc.)
+ *                  'Projection' — Data query endpoint (e.g. retold-facto)
+ *                  'Operation'  — Operation state/artifacts on the orchestrator
+ *   Path        — The resource path within that context
+ *
+ * Examples:
+ *   >RR-BCN-001/File/volume3/Sort/SomeSong.mp3
+ *   >ULTRAVISOR/Operation/0x732490df0/Stage/Transcoded.avi
+ *   >RF-BCN-001/Projection/Countries/*
+ *   >RF-BCN-001/Projection/Countries/FilteredTo/FBV~Name~LK~Col%25
+ *   >WILDCARD/MediaConversion/Staging/input.jpg  (use * for any beacon)
+ *
+ * This module is Fable-free — usable from both beacon clients and
+ * the Ultravisor server.
+ */
+
+class UltravisorBeaconAddressResolver
+{
+	constructor(pOptions)
+	{
+		let tmpOptions = pOptions || {};
+
+		// Registry of known beacons and their contexts
+		// Map of BeaconID → { Contexts: { ContextName: { BasePath, BaseURL, Writable } } }
+		this._BeaconRegistry = {};
+
+		// Local beacon ID (set when running on a beacon)
+		this._LocalBeaconID = tmpOptions.LocalBeaconID || null;
+
+		// Local context mappings (set when running on a beacon)
+		// Map of ContextName → absolute filesystem path
+		this._LocalContextPaths = {};
+	}
+
+	// ================================================================
+	// Address Parsing
+	// ================================================================
+
+	/**
+	 * Parse a universal data address string into its components.
+	 *
+	 * @param {string} pAddress - The address string (e.g. '>RR-BCN-001/File/photos/img.jpg')
+	 * @returns {object|null} Parsed address: { BeaconID, Context, Path, Raw }
+	 *                        Returns null if the address is not a valid universal address.
+	 */
+	parse(pAddress)
+	{
+		if (!pAddress || typeof pAddress !== 'string')
+		{
+			return null;
+		}
+
+		// Must start with >
+		if (pAddress.charAt(0) !== '>')
+		{
+			return null;
+		}
+
+		// Strip the prefix
+		let tmpBody = pAddress.substring(1);
+
+		// Split into segments: BeaconID / Context / Path...
+		let tmpFirstSlash = tmpBody.indexOf('/');
+		if (tmpFirstSlash < 0)
+		{
+			// Just a beacon ID with no context or path
+			return {
+				BeaconID: tmpBody,
+				Context: '',
+				Path: '',
+				Raw: pAddress
+			};
+		}
+
+		let tmpBeaconID = tmpBody.substring(0, tmpFirstSlash);
+		let tmpRemainder = tmpBody.substring(tmpFirstSlash + 1);
+
+		let tmpSecondSlash = tmpRemainder.indexOf('/');
+		if (tmpSecondSlash < 0)
+		{
+			// BeaconID and Context, no path
+			return {
+				BeaconID: tmpBeaconID,
+				Context: tmpRemainder,
+				Path: '',
+				Raw: pAddress
+			};
+		}
+
+		let tmpContext = tmpRemainder.substring(0, tmpSecondSlash);
+		let tmpPath = tmpRemainder.substring(tmpSecondSlash + 1);
+
+		return {
+			BeaconID: tmpBeaconID,
+			Context: tmpContext,
+			Path: tmpPath,
+			Raw: pAddress
+		};
+	}
+
+	/**
+	 * Check if a string is a universal data address.
+	 *
+	 * @param {string} pAddress - The string to check.
+	 * @returns {boolean} True if the string starts with '>'.
+	 */
+	isUniversalAddress(pAddress)
+	{
+		return (typeof pAddress === 'string' && pAddress.length > 1 && pAddress.charAt(0) === '>');
+	}
+
+	/**
+	 * Compose a universal data address from components.
+	 *
+	 * @param {string} pBeaconID - The beacon identifier.
+	 * @param {string} pContext - The context namespace.
+	 * @param {string} pPath - The resource path.
+	 * @returns {string} The composed address.
+	 */
+	compose(pBeaconID, pContext, pPath)
+	{
+		let tmpParts = ['>', pBeaconID];
+		if (pContext)
+		{
+			tmpParts.push('/', pContext);
+			if (pPath)
+			{
+				tmpParts.push('/', pPath);
+			}
+		}
+		return tmpParts.join('');
+	}
+
+	// ================================================================
+	// Beacon Registry
+	// ================================================================
+
+	/**
+	 * Register a beacon and its available contexts.
+	 *
+	 * @param {string} pBeaconID - The beacon identifier.
+	 * @param {object} pContexts - Map of ContextName → { BasePath, BaseURL, Writable, Description }
+	 */
+	registerBeacon(pBeaconID, pContexts)
+	{
+		this._BeaconRegistry[pBeaconID] = {
+			Contexts: pContexts || {}
+		};
+	}
+
+	/**
+	 * Deregister a beacon.
+	 *
+	 * @param {string} pBeaconID - The beacon identifier to remove.
+	 */
+	deregisterBeacon(pBeaconID)
+	{
+		delete this._BeaconRegistry[pBeaconID];
+	}
+
+	/**
+	 * Get the context definition for a beacon.
+	 *
+	 * @param {string} pBeaconID - The beacon identifier.
+	 * @param {string} pContext - The context name.
+	 * @returns {object|null} The context definition, or null if not found.
+	 */
+	getBeaconContext(pBeaconID, pContext)
+	{
+		let tmpBeacon = this._BeaconRegistry[pBeaconID];
+		if (!tmpBeacon || !tmpBeacon.Contexts)
+		{
+			return null;
+		}
+		return tmpBeacon.Contexts[pContext] || null;
+	}
+
+	/**
+	 * List all registered beacons and their contexts.
+	 *
+	 * @returns {object} Map of BeaconID → { Contexts }
+	 */
+	listBeacons()
+	{
+		return JSON.parse(JSON.stringify(this._BeaconRegistry));
+	}
+
+	// ================================================================
+	// Local Context Configuration
+	// ================================================================
+
+	/**
+	 * Set the local beacon identity (for resolving self-references).
+	 *
+	 * @param {string} pBeaconID - This beacon's ID.
+	 */
+	setLocalBeaconID(pBeaconID)
+	{
+		this._LocalBeaconID = pBeaconID;
+	}
+
+	/**
+	 * Register a local context path mapping.
+	 *
+	 * @param {string} pContext - The context name (e.g. 'File', 'Staging', 'Cache').
+	 * @param {string} pBasePath - The absolute filesystem path for this context.
+	 */
+	setLocalContextPath(pContext, pBasePath)
+	{
+		this._LocalContextPaths[pContext] = pBasePath;
+	}
+
+	// ================================================================
+	// Address Resolution
+	// ================================================================
+
+	/**
+	 * Resolve a universal data address to a local filesystem path.
+	 *
+	 * Only works for addresses targeting the local beacon or addresses
+	 * with explicit local context mappings. Returns null for remote addresses.
+	 *
+	 * @param {string} pAddress - The universal address string.
+	 * @returns {object} Resolution result:
+	 *   { Local: true, Path: '/absolute/path/to/file' }
+	 *   or { Local: false, BeaconID: '...', Context: '...', Path: '...' }
+	 *   or { Error: 'description' }
+	 */
+	resolve(pAddress)
+	{
+		let tmpParsed = this.parse(pAddress);
+		if (!tmpParsed)
+		{
+			return { Error: `Invalid universal address: ${pAddress}` };
+		}
+
+		// Check if this targets the local beacon
+		let tmpIsLocal = false;
+		if (tmpParsed.BeaconID === this._LocalBeaconID)
+		{
+			tmpIsLocal = true;
+		}
+
+		if (tmpIsLocal)
+		{
+			let tmpBasePath = this._LocalContextPaths[tmpParsed.Context];
+			if (!tmpBasePath)
+			{
+				return { Error: `Unknown local context: ${tmpParsed.Context}` };
+			}
+
+			let tmpResolvedPath = tmpParsed.Path
+				? require('path').join(tmpBasePath, tmpParsed.Path)
+				: tmpBasePath;
+
+			return {
+				Local: true,
+				Path: tmpResolvedPath,
+				BeaconID: tmpParsed.BeaconID,
+				Context: tmpParsed.Context
+			};
+		}
+
+		// Remote address — return the parsed components for the caller to handle
+		return {
+			Local: false,
+			BeaconID: tmpParsed.BeaconID,
+			Context: tmpParsed.Context,
+			Path: tmpParsed.Path
+		};
+	}
+
+	/**
+	 * Build a URL for accessing a resource on a remote beacon.
+	 *
+	 * Uses the beacon's registered BaseURL for the context.
+	 *
+	 * @param {string} pAddress - The universal address string.
+	 * @returns {string|null} The full URL, or null if the beacon/context is unknown.
+	 */
+	resolveToURL(pAddress)
+	{
+		let tmpParsed = this.parse(pAddress);
+		if (!tmpParsed)
+		{
+			return null;
+		}
+
+		let tmpContextDef = this.getBeaconContext(tmpParsed.BeaconID, tmpParsed.Context);
+		if (!tmpContextDef || !tmpContextDef.BaseURL)
+		{
+			return null;
+		}
+
+		let tmpBaseURL = tmpContextDef.BaseURL;
+		// Ensure trailing slash on base
+		if (tmpBaseURL.charAt(tmpBaseURL.length - 1) !== '/')
+		{
+			tmpBaseURL += '/';
+		}
+
+		return tmpBaseURL + (tmpParsed.Path || '');
+	}
+
+	/**
+	 * Scan an object's values for universal addresses and return
+	 * a list of all addresses found. Useful for pre-processing
+	 * operation settings to identify file transfer requirements.
+	 *
+	 * @param {object} pObject - The object to scan (e.g. work item Settings).
+	 * @returns {Array<{ Key: string, Address: object }>} List of found addresses.
+	 */
+	scanForAddresses(pObject)
+	{
+		let tmpResults = [];
+
+		if (!pObject || typeof pObject !== 'object')
+		{
+			return tmpResults;
+		}
+
+		let tmpKeys = Object.keys(pObject);
+		for (let i = 0; i < tmpKeys.length; i++)
+		{
+			let tmpValue = pObject[tmpKeys[i]];
+			if (typeof tmpValue === 'string' && this.isUniversalAddress(tmpValue))
+			{
+				let tmpParsed = this.parse(tmpValue);
+				if (tmpParsed)
+				{
+					tmpResults.push({ Key: tmpKeys[i], Address: tmpParsed });
+				}
+			}
+			else if (typeof tmpValue === 'object' && tmpValue !== null)
+			{
+				// Recurse into nested objects
+				let tmpNested = this.scanForAddresses(tmpValue);
+				for (let j = 0; j < tmpNested.length; j++)
+				{
+					tmpNested[j].Key = tmpKeys[i] + '.' + tmpNested[j].Key;
+					tmpResults.push(tmpNested[j]);
+				}
+			}
+		}
+
+		return tmpResults;
+	}
+}
+
+module.exports = UltravisorBeaconAddressResolver;

package/source/Ultravisor-Beacon-CapabilityAdapter.cjs

@@ -70,20 +70,35 @@ class UltravisorBeaconCapabilityAdapter extends libCapabilityProvider
 		let tmpDescriptorActions = (this._Descriptor && this._Descriptor.actions) ? this._Descriptor.actions : {};
 		let tmpActionDef = tmpDescriptorActions[pAction];
 
-		if (!tmpActionDef || typeof tmpActionDef.Handler !== 'function')
+		// Per-action Handler takes priority
+		if (tmpActionDef && typeof tmpActionDef.Handler === 'function')
 		{
-			return fCallback(new Error(
-				`CapabilityAdapter "${this.Name}" has no Handler for action "${pAction}".`));
+			try
+			{
+				return tmpActionDef.Handler(pWorkItem, pContext, fCallback, fReportProgress);
+			}
+			catch (pError)
+			{
+				return fCallback(pError);
+			}
 		}
 
-		try
+		// Fall back to descriptor-level execute method (Provider pattern —
+		// a single execute() that routes actions internally)
+		if (typeof this._Descriptor.execute === 'function')
 		{
-			tmpActionDef.Handler(pWorkItem, pContext, fCallback, fReportProgress);
-		}
-		catch (pError)
-		{
-			return fCallback(pError);
+			try
+			{
+				return this._Descriptor.execute(pAction, pWorkItem, pContext, fCallback, fReportProgress);
+			}
+			catch (pError)
+			{
+				return fCallback(pError);
+			}
 		}
+
+		return fCallback(new Error(
+			`CapabilityAdapter "${this.Name}" has no Handler for action "${pAction}".`));
 	}
 
 	/**

package/source/Ultravisor-Beacon-Client.cjs

@@ -397,10 +397,23 @@ class UltravisorBeaconClient
 		let tmpBody = {
 			Name: this._Config.Name,
 			Capabilities: this._Executor.providerRegistry.getCapabilities(),
+			ActionSchemas: this._Executor.providerRegistry.getActionSchemas(),
 			MaxConcurrent: this._Config.MaxConcurrent,
 			Tags: this._Config.Tags
 		};
 
+		// Include contexts if any are defined
+		if (this._Config.Contexts && Object.keys(this._Config.Contexts).length > 0)
+		{
+			tmpBody.Contexts = this._Config.Contexts;
+		}
+
+		// Include operations if any are defined
+		if (Array.isArray(this._Config.Operations) && this._Config.Operations.length > 0)
+		{
+			tmpBody.Operations = this._Config.Operations;
+		}
+
 		this._httpRequest('POST', '/Beacon/Register', tmpBody, fCallback);
 	}
 
@@ -685,13 +698,23 @@ class UltravisorBeaconClient
 			console.log(`[Beacon] WebSocket connected to ${tmpWSURL}`);
 
 			// Register over WebSocket
-			this._wsSend({
+			let tmpWSRegPayload = {
 				Action: 'BeaconRegister',
 				Name: this._Config.Name,
 				Capabilities: this._Executor.providerRegistry.getCapabilities(),
+				ActionSchemas: this._Executor.providerRegistry.getActionSchemas(),
 				MaxConcurrent: this._Config.MaxConcurrent,
 				Tags: this._Config.Tags
-			});
+			};
+			if (this._Config.Contexts && Object.keys(this._Config.Contexts).length > 0)
+			{
+				tmpWSRegPayload.Contexts = this._Config.Contexts;
+			}
+			if (Array.isArray(this._Config.Operations) && this._Config.Operations.length > 0)
+			{
+				tmpWSRegPayload.Operations = this._Config.Operations;
+			}
+			this._wsSend(tmpWSRegPayload);
 		});
 
 		this._WebSocket.on('message', (pMessage) =>

package/source/Ultravisor-Beacon-ProviderRegistry.cjs

@@ -129,6 +129,42 @@ class UltravisorBeaconProviderRegistry
 		return this._Capabilities.slice();
 	}
 
+	/**
+	 * Get serializable action schemas from all loaded providers.
+	 *
+	 * Collects action metadata (Description, SettingsSchema) from every
+	 * registered provider.  Handler functions are NOT included — the
+	 * CapabilityAdapter's `actions` getter already strips them.
+	 *
+	 * @returns {Array<{ Capability: string, Action: string, Description: string, SettingsSchema: Array }>}
+	 */
+	getActionSchemas()
+	{
+		let tmpSchemas = [];
+		let tmpProviderNames = Object.keys(this._Providers);
+
+		for (let i = 0; i < tmpProviderNames.length; i++)
+		{
+			let tmpProvider = this._Providers[tmpProviderNames[i]];
+			let tmpActions = tmpProvider.actions || {};
+			let tmpActionNames = Object.keys(tmpActions);
+
+			for (let j = 0; j < tmpActionNames.length; j++)
+			{
+				let tmpActionDef = tmpActions[tmpActionNames[j]];
+
+				tmpSchemas.push({
+					Capability: tmpProvider.Capability,
+					Action: tmpActionNames[j],
+					Description: tmpActionDef.Description || '',
+					SettingsSchema: tmpActionDef.SettingsSchema || []
+				});
+			}
+		}
+
+		return tmpSchemas;
+	}
+
 	/**
 	 * Get all loaded providers.
 	 *

package/source/Ultravisor-Beacon-Service.cjs

@@ -30,6 +30,7 @@ const libBeaconClient = require('./Ultravisor-Beacon-Client.cjs');
 const libCapabilityManager = require('./Ultravisor-Beacon-CapabilityManager.cjs');
 const libConnectivityHTTP = require('./Ultravisor-Beacon-ConnectivityHTTP.cjs');
 const libConnectivityWebSocket = require('./Ultravisor-Beacon-ConnectivityWebSocket.cjs');
+const libAddressResolver = require('./Ultravisor-Beacon-AddressResolver.cjs');
 
 class UltravisorBeaconService extends libFableServiceBase
 {
@@ -49,14 +50,19 @@ class UltravisorBeaconService extends libFableServiceBase
 			PollIntervalMs: 5000,
 			HeartbeatIntervalMs: 30000,
 			StagingPath: '',
-			Tags: {}
+			Tags: {},
+			Contexts: {}
 		}, this.options || {});
 
 		// Internal components
 		this._CapabilityManager = new libCapabilityManager();
 		this._ConnectivityService = new libConnectivityHTTP(this.options);
+		this._AddressResolver = new libAddressResolver();
 		this._ThinClient = null;
 		this._Enabled = false;
+
+		// Operation definitions to register with the coordinator on connect
+		this._Operations = [];
 	}
 
 	// ================================================================
@@ -94,6 +100,43 @@ class UltravisorBeaconService extends libFableServiceBase
 		return this;
 	}
 
+	/**
+	 * Register an operation definition to push to the coordinator on connect.
+	 *
+	 * Operation definitions use the same graph structure as HypervisorState
+	 * operations (Hash, Name, Description, Graph with Nodes and Connections).
+	 * These are sent during beacon registration and stored by the coordinator.
+	 *
+	 * @param {object} pOperationDef - Operation definition:
+	 *   {
+	 *     Hash: 'video-ingest',
+	 *     Name: 'Video Ingest Pipeline',
+	 *     Description: '...',
+	 *     Graph: { Nodes: [...], Connections: [...] }
+	 *   }
+	 * @returns {object} this (for chaining)
+	 */
+	registerOperation(pOperationDef)
+	{
+		if (!pOperationDef || typeof(pOperationDef) !== 'object')
+		{
+			if (this.log)
+			{
+				this.log.warn('UltravisorBeacon: registerOperation requires a valid object.');
+			}
+			return this;
+		}
+
+		this._Operations.push(pOperationDef);
+
+		if (this.log)
+		{
+			this.log.info(`UltravisorBeacon: registered operation [${pOperationDef.Hash || 'auto'}] "${pOperationDef.Name || ''}"`);
+		}
+
+		return this;
+	}
+
 	/**
 	 * Remove a previously registered capability.
 	 *
@@ -116,6 +159,51 @@ class UltravisorBeaconService extends libFableServiceBase
 		return this._CapabilityManager.getCapabilityNames();
 	}
 
+	/**
+	 * Register a data context that this beacon exposes.
+	 *
+	 * Contexts define namespaces for the Universal Data Addressing scheme.
+	 * For example, a retold-remote beacon might expose a 'File' context
+	 * (content root) and a 'Cache' context (thumbnail cache).
+	 *
+	 * @param {string} pContextName - The context name (e.g. 'File', 'Cache', 'Staging').
+	 * @param {object} pContextDef - Context definition:
+	 *   {
+	 *     BasePath: '/absolute/path',     // Local filesystem path
+	 *     BaseURL: '/content/',           // URL prefix for remote access
+	 *     Writable: true,                 // Whether remote writes are allowed
+	 *     Description: 'Content root'     // Human-readable description
+	 *   }
+	 * @returns {object} this (for chaining)
+	 */
+	registerContext(pContextName, pContextDef)
+	{
+		this.options.Contexts[pContextName] = pContextDef;
+
+		// Also register with the address resolver for local resolution
+		if (pContextDef.BasePath)
+		{
+			this._AddressResolver.setLocalContextPath(pContextName, pContextDef.BasePath);
+		}
+
+		if (this.log)
+		{
+			this.log.info(`UltravisorBeacon: registered context [${pContextName}]`);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Get the address resolver instance.
+	 *
+	 * @returns {UltravisorBeaconAddressResolver}
+	 */
+	getAddressResolver()
+	{
+		return this._AddressResolver;
+	}
+
 	/**
 	 * Enable beacon mode: build providers, create thin client, connect.
 	 *
@@ -163,6 +251,8 @@ class UltravisorBeaconService extends libFableServiceBase
 			MaxConcurrent: this.options.MaxConcurrent || 1,
 			StagingPath: this.options.StagingPath || process.cwd(),
 			Tags: this.options.Tags || {},
+			Contexts: this.options.Contexts || {},
+			Operations: this._Operations.length > 0 ? this._Operations : undefined,
 			// Pass empty Providers array — we'll register adapters directly
 			Providers: []
 		});
@@ -196,6 +286,7 @@ class UltravisorBeaconService extends libFableServiceBase
 			}
 
 			this._Enabled = true;
+			this._AddressResolver.setLocalBeaconID(pBeacon.BeaconID);
 
 			if (this.log)
 			{
@@ -285,5 +376,6 @@ module.exports.CapabilityManager = libCapabilityManager;
 module.exports.CapabilityAdapter = require('./Ultravisor-Beacon-CapabilityAdapter.cjs');
 module.exports.CapabilityProvider = require('./Ultravisor-Beacon-CapabilityProvider.cjs');
 module.exports.ProviderRegistry = require('./Ultravisor-Beacon-ProviderRegistry.cjs');
+module.exports.AddressResolver = libAddressResolver;
 module.exports.ConnectivityHTTP = libConnectivityHTTP;
 module.exports.ConnectivityWebSocket = libConnectivityWebSocket;