retold-remote 0.0.15 → 0.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "retold-remote",
-    "version": "0.0.15",
+    "version": "0.0.17",
     "description": "Retold Remote - NAS media browser with gallery views and keyboard navigation",
     "main": "source/Pict-RetoldRemote-Bundle.js",
     "bin": {
@@ -34,22 +34,22 @@
         "dcraw": "^1.0.3",
         "epubjs": "^0.3.93",
         "exifr": "^7.1.3",
-        "fable": "^3.1.63",
+        "fable": "^3.1.67",
         "fable-serviceproviderbase": "^3.0.19",
         "node-unrar-js": "^2.0.2",
         "orator": "^6.0.4",
         "orator-serviceserver-restify": "^2.0.9",
         "parime": "^1.0.3",
         "pdf-parse": "^1.1.1",
-        "pict": "^1.0.357",
+        "pict": "^1.0.359",
         "pict-application": "^1.0.33",
         "pict-docuserve": "^0.0.32",
         "pict-provider": "^1.0.12",
-        "pict-section-code": "^1.0.3",
+        "pict-section-code": "^1.0.4",
         "pict-section-filebrowser": "^0.0.2",
         "pict-service-commandlineutility": "^1.0.19",
         "pict-view": "^1.0.67",
-        "retold-content-system": "^1.0.8",
+        "retold-content-system": "^1.0.12",
         "yauzl": "^3.2.0"
     },
     "optionalDependencies": {
@@ -58,7 +58,7 @@
     },
     "devDependencies": {
         "puppeteer": "^24.0.0",
-        "quackage": "^1.0.63"
+        "quackage": "^1.0.65"
     },
     "copyFilesSettings": {
         "whenFileExists": "overwrite"

package/source/server/RetoldRemote-ImageService.js

@@ -752,7 +752,11 @@ class RetoldRemoteImageService extends libFableServiceProviderBase
 
 		if (!this._sharp && !this._capabilities.imagemagick)
 		{
-			return fCallback(new Error('Neither sharp nor ImageMagick is available.'));
+			// Neither Sharp nor ImageMagick available locally — check for Ultravisor
+			if (!(this._dispatcher && this._dispatcher.isAvailable()))
+			{
+				return fCallback(new Error('Neither sharp nor ImageMagick is available.'));
+			}
 		}
 
 		let tmpMaxDim = pMaxDimension || this.options.DefaultMaxPreviewDimension;
@@ -826,11 +830,20 @@ class RetoldRemoteImageService extends libFableServiceProviderBase
 		{
 			this._doGeneratePreview(pAbsPath, pAbsPath, pRelPath, tmpMaxDim, tmpCacheKey, tmpOutputFilename, tmpCacheDir, tmpManifestPath, tmpOutputPath, tmpStat, false, fCallback);
 		}
-		else
+		else if (this._capabilities.imagemagick)
 		{
 			// No Sharp available — use ImageMagick for standard images too
 			this._doGeneratePreviewWithImageMagick(pAbsPath, pRelPath, tmpMaxDim, tmpCacheKey, tmpOutputFilename, tmpManifestPath, tmpOutputPath, tmpStat, false, fCallback);
 		}
+		else if (this._dispatcher && this._dispatcher.isAvailable())
+		{
+			// No local tools available — dispatch to Ultravisor beacon
+			this._doGeneratePreviewWithDispatcher(pAbsPath, pRelPath, tmpMaxDim, tmpCacheKey, tmpOutputFilename, tmpCacheDir, tmpManifestPath, tmpOutputPath, tmpStat, tmpIsRaw, fCallback);
+		}
+		else
+		{
+			return fCallback(new Error('No preview tools available.'));
+		}
 	}
 
 	/**
@@ -1087,6 +1100,101 @@ class RetoldRemoteImageService extends libFableServiceProviderBase
 		}
 	}
 
+	/**
+	 * Generate a preview by dispatching to an Ultravisor beacon.
+	 * Uses the MediaConversion capability (ImageResize) with a shell
+	 * convert fallback. The result is written to the cache directory.
+	 *
+	 * @param {string}   pInputPath      - Absolute path to the source image
+	 * @param {string}   pRelPath        - Relative path (for response/logging)
+	 * @param {number}   pMaxDim         - Max dimension
+	 * @param {string}   pCacheKey       - Cache key
+	 * @param {string}   pOutputFilename - Output filename
+	 * @param {string}   pCacheDir       - Cache directory path
+	 * @param {string}   pManifestPath   - Manifest file path
+	 * @param {string}   pOutputPath     - Output file path
+	 * @param {object}   pStat           - Original file stat
+	 * @param {boolean}  pIsRaw          - Whether this is a raw camera format
+	 * @param {Function} fCallback       - Callback(pError, pResult)
+	 */
+	_doGeneratePreviewWithDispatcher(pInputPath, pRelPath, pMaxDim, pCacheKey, pOutputFilename, pCacheDir, pManifestPath, pOutputPath, pStat, pIsRaw, fCallback)
+	{
+		let tmpSelf = this;
+		let tmpRelPath;
+
+		try
+		{
+			tmpRelPath = libPath.relative(this.contentPath, pInputPath);
+		}
+		catch (pErr)
+		{
+			return fCallback(new Error('Could not resolve relative path for dispatch.'));
+		}
+
+		if (!tmpRelPath || tmpRelPath.startsWith('..'))
+		{
+			return fCallback(new Error('File is outside content root.'));
+		}
+
+		this._dispatcher.dispatchConversion(
+		{
+			Action: 'ImageResize',
+			InputPath: tmpRelPath,
+			OutputFilename: pOutputFilename,
+			Width: pMaxDim,
+			Height: pMaxDim,
+			Format: 'jpeg',
+			Quality: this.options.PreviewQuality || 85,
+			AffinityKey: tmpRelPath,
+			TimeoutMs: 120000,
+			FallbackCommand: `convert "{SourcePath}"[0] -auto-orient -resize ${pMaxDim}x${pMaxDim} -quality ${this.options.PreviewQuality || 85} "{OutputPath}"`
+		},
+		(pDispatchError, pResult) =>
+		{
+			if (pDispatchError || !pResult || !pResult.OutputBuffer)
+			{
+				return fCallback(new Error('Ultravisor preview generation failed: ' + (pDispatchError ? pDispatchError.message : 'no output')));
+			}
+
+			try
+			{
+				libFs.writeFileSync(pOutputPath, pResult.OutputBuffer);
+			}
+			catch (pWriteError)
+			{
+				return fCallback(new Error('Failed to write preview output: ' + pWriteError.message));
+			}
+
+			let tmpResult =
+			{
+				Success: true,
+				SourcePath: pRelPath,
+				CacheKey: pCacheKey,
+				OutputFilename: pOutputFilename,
+				Width: pMaxDim,
+				Height: pMaxDim,
+				OrigWidth: 0,
+				OrigHeight: 0,
+				FileSize: pResult.OutputBuffer.length,
+				NeedsPreview: true,
+				IsRawFormat: pIsRaw,
+				GeneratedAt: new Date().toISOString()
+			};
+
+			try
+			{
+				libFs.writeFileSync(pManifestPath, JSON.stringify(tmpResult, null, '\t'));
+			}
+			catch (pWriteError)
+			{
+				tmpSelf.fable.log.warn(`Could not write preview manifest: ${pWriteError.message}`);
+			}
+
+			tmpSelf.fable.log.info(`Generated image preview (Ultravisor): ${pRelPath}`);
+			return fCallback(null, tmpResult);
+		});
+	}
+
 	// ---------------------------------------------------------------
 	// DZI tile generation
 	// ---------------------------------------------------------------

package/source/server/RetoldRemote-MediaService.js

@@ -496,7 +496,9 @@ class RetoldRemoteMediaService extends libFableServiceProviderBase
 			}
 		}
 
-		// Try Ultravisor dispatch as last resort for image thumbnails
+		// Try Ultravisor dispatch as last resort for image thumbnails.
+		// Uses structured MediaConversion capability (orator-conversion beacon)
+		// with shell convert fallback if MediaConversion is not available.
 		if (this._dispatcher && this._dispatcher.isAvailable())
 		{
 			let tmpRelPath;
@@ -513,15 +515,19 @@ class RetoldRemoteMediaService extends libFableServiceProviderBase
 			{
 				let tmpOutputFormat = pFormat === 'webp' ? 'webp' : 'jpeg';
 				let tmpOutputFilename = `thumbnail.${pFormat === 'webp' ? 'webp' : 'jpg'}`;
-				let tmpCommand = `convert "{SourcePath}" -thumbnail ${pWidth}x${pHeight} -auto-orient ${tmpOutputFormat}:"{OutputPath}"`;
 
-				this._dispatcher.dispatchMediaCommand(
+				this._dispatcher.dispatchConversion(
 				{
-					Command: tmpCommand,
+					Action: 'ImageResize',
 					InputPath: tmpRelPath,
 					OutputFilename: tmpOutputFilename,
+					Width: pWidth,
+					Height: pHeight,
+					Format: tmpOutputFormat,
+					Quality: 80,
 					AffinityKey: tmpRelPath,
-					TimeoutMs: 30000
+					TimeoutMs: 30000,
+					FallbackCommand: `convert "{SourcePath}" -thumbnail ${pWidth}x${pHeight} -auto-orient ${tmpOutputFormat}:"{OutputPath}"`
 				},
 				(pDispatchError, pResult) =>
 				{
@@ -677,10 +683,11 @@ class RetoldRemoteMediaService extends libFableServiceProviderBase
 	}
 
 	/**
-	 * Fallback raw thumbnail generation: ImageMagick → exifr embedded preview.
+	 * Fallback raw thumbnail generation: ImageMagick → Ultravisor MediaConversion → exifr embedded preview.
 	 */
 	_generateRawThumbnailFallback(pFullPath, pWidth, pHeight, pFormat, fCallback)
 	{
+		let tmpSelf = this;
 		let tmpOutputFormat = pFormat === 'webp' ? 'webp' : 'jpeg';
 
 		// Strategy 2: ImageMagick (may have dcraw delegate)
@@ -694,11 +701,67 @@ class RetoldRemoteMediaService extends libFableServiceProviderBase
 			}
 			catch (pError)
 			{
-				// Fall through to exifr
+				// Fall through to Ultravisor
+			}
+		}
+
+		// Strategy 2.5: Try Ultravisor MediaConversion (beacon may have Sharp
+		// even if local machine does not have ImageMagick)
+		if (this._dispatcher && this._dispatcher.isAvailable())
+		{
+			let tmpRelPath;
+			try
+			{
+				tmpRelPath = libPath.relative(this.contentPath, pFullPath);
+			}
+			catch (pErr)
+			{
+				tmpRelPath = null;
+			}
+
+			if (tmpRelPath && !tmpRelPath.startsWith('..'))
+			{
+				let tmpOutputFilename = `thumbnail.${pFormat === 'webp' ? 'webp' : 'jpg'}`;
+
+				this._dispatcher.dispatchConversion(
+				{
+					Action: 'ImageResize',
+					InputPath: tmpRelPath,
+					OutputFilename: tmpOutputFilename,
+					Width: pWidth,
+					Height: pHeight,
+					Format: tmpOutputFormat,
+					Quality: 80,
+					AffinityKey: tmpRelPath,
+					TimeoutMs: 60000,
+					FallbackCommand: `convert "{SourcePath}" -thumbnail ${pWidth}x${pHeight} -auto-orient ${tmpOutputFormat}:"{OutputPath}"`
+				},
+				(pDispatchError, pResult) =>
+				{
+					if (!pDispatchError && pResult && pResult.OutputBuffer)
+					{
+						tmpSelf.fable.log.info(`Raw thumbnail generated via Ultravisor for ${tmpRelPath}`);
+						return fCallback(null, pResult.OutputBuffer);
+					}
+
+					// Fall through to exifr embedded preview
+					tmpSelf._generateRawThumbnailExifr(pFullPath, pWidth, pHeight, pFormat, fCallback);
+				});
+				return;
 			}
 		}
 
-		// Strategy 3: Extract embedded JPEG preview via exifr, resize with sharp
+		return this._generateRawThumbnailExifr(pFullPath, pWidth, pHeight, pFormat, fCallback);
+	}
+
+	/**
+	 * Strategy 3 for raw thumbnails: extract embedded JPEG preview via exifr,
+	 * resize with sharp. Most cameras embed a full-size JPEG preview in the raw file.
+	 */
+	_generateRawThumbnailExifr(pFullPath, pWidth, pHeight, pFormat, fCallback)
+	{
+		let tmpOutputFormat = pFormat === 'webp' ? 'webp' : 'jpeg';
+
 		if (this.capabilities.sharp)
 		{
 			let tmpSharp = this.capabilities.sharpModule;

package/source/server/RetoldRemote-UltravisorDispatcher.js

@@ -198,6 +198,317 @@ class RetoldRemoteUltravisorDispatcher extends libFableServiceProviderBase
 			});
 	}
 
+	/**
+	 * Check if a specific capability is available on any connected beacon.
+	 *
+	 * @param {string} pCapability - The capability name (e.g. 'MediaConversion', 'Shell')
+	 * @returns {boolean} True if at least one beacon has this capability
+	 */
+	hasCapability(pCapability)
+	{
+		return this._Available && this._Capabilities.indexOf(pCapability) >= 0;
+	}
+
+	/**
+	 * Dispatch a structured media conversion to Ultravisor using the
+	 * MediaConversion capability (orator-conversion beacon provider).
+	 *
+	 * Falls back to dispatchMediaCommand() (Shell) if MediaConversion
+	 * is not available.
+	 *
+	 * @param {object} pOptions - Conversion options
+	 * @param {string} pOptions.Action - Conversion action (e.g. 'ImageResize', 'PdfPageToPng')
+	 * @param {string} [pOptions.InputPath] - Relative path to source file (from content root)
+	 * @param {string} [pOptions.InputFilename] - Filename for the downloaded source
+	 * @param {string} [pOptions.OutputFilename] - Name of the output file
+	 * @param {number} [pOptions.Width] - Width for ImageResize
+	 * @param {number} [pOptions.Height] - Height for ImageResize
+	 * @param {string} [pOptions.Format] - Output format for ImageResize
+	 * @param {number} [pOptions.Quality] - Quality for lossy formats
+	 * @param {number} [pOptions.Page] - PDF page number (1-based)
+	 * @param {number} [pOptions.LongSidePixels] - Max dimension for sized PDF renders
+	 * @param {string} [pOptions.AffinityKey] - Affinity routing key
+	 * @param {number} [pOptions.TimeoutMs] - Timeout in ms (default 300000)
+	 * @param {function} fCallback - function(pError, pResult)
+	 */
+	dispatchConversion(pOptions, fCallback)
+	{
+		if (!this.hasCapability('MediaConversion'))
+		{
+			// Fall back to shell dispatch if caller provides a Command
+			if (pOptions.FallbackCommand)
+			{
+				return this.dispatchMediaCommand({
+					Command: pOptions.FallbackCommand,
+					InputPath: pOptions.InputPath,
+					InputFilename: pOptions.InputFilename,
+					OutputFilename: pOptions.OutputFilename,
+					AffinityKey: pOptions.AffinityKey,
+					TimeoutMs: pOptions.TimeoutMs
+				}, fCallback);
+			}
+			return fCallback(new Error('MediaConversion capability not available and no fallback command provided'));
+		}
+
+		let tmpSettings = {
+			InputFile: pOptions.InputFilename ||
+				(pOptions.InputPath ? pOptions.InputPath.split('/').pop() : 'source_file'),
+			OutputFile: pOptions.OutputFilename || 'output'
+		};
+
+		// Pass through action-specific settings
+		if (pOptions.Width) tmpSettings.Width = pOptions.Width;
+		if (pOptions.Height) tmpSettings.Height = pOptions.Height;
+		if (pOptions.Format) tmpSettings.Format = pOptions.Format;
+		if (pOptions.Quality) tmpSettings.Quality = pOptions.Quality;
+		if (pOptions.Page) tmpSettings.Page = pOptions.Page;
+		if (pOptions.LongSidePixels) tmpSettings.LongSidePixels = pOptions.LongSidePixels;
+
+		// Set up source file download
+		if (pOptions.InputPath && this._ContentAPIURL)
+		{
+			let tmpEncodedPath = pOptions.InputPath.split('/').map(encodeURIComponent).join('/');
+			tmpSettings.SourceURL = this._ContentAPIURL + '/content/' + tmpEncodedPath;
+			tmpSettings.SourceFilename = tmpSettings.InputFile;
+		}
+
+		// Set up output file collection
+		if (pOptions.OutputFilename)
+		{
+			tmpSettings.ReturnOutputAsBase64 = true;
+		}
+
+		let tmpWorkItem = {
+			Capability: 'MediaConversion',
+			Action: pOptions.Action || 'ImageResize',
+			Settings: tmpSettings,
+			AffinityKey: pOptions.AffinityKey || '',
+			TimeoutMs: pOptions.TimeoutMs || 300000
+		};
+
+		this.dispatch(tmpWorkItem,
+			(pError, pResult) =>
+			{
+				if (pError)
+				{
+					return fCallback(pError);
+				}
+
+				// If we have base64 output data, decode it to a Buffer
+				if (pResult.Outputs && pResult.Outputs.OutputData)
+				{
+					try
+					{
+						pResult.OutputBuffer = Buffer.from(pResult.Outputs.OutputData, 'base64');
+					}
+					catch (pDecodeError)
+					{
+						return fCallback(new Error('Failed to decode output data: ' + pDecodeError.message));
+					}
+				}
+
+				return fCallback(null, pResult);
+			});
+	}
+
+	// ================================================================
+	// Streaming Dispatch (binary-framed)
+	// ================================================================
+
+	/**
+	 * Dispatch a work item with binary-framed streaming.
+	 *
+	 * Uses the /Beacon/Work/DispatchStream endpoint which returns a
+	 * binary frame stream instead of a single JSON response. This
+	 * enables real-time progress updates and efficient binary output
+	 * transfer without base64 re-encoding overhead.
+	 *
+	 * Frame protocol (binary-frames-v1):
+	 *   [1 byte type][4 bytes payload length (uint32 big-endian)][payload]
+	 *   Type 0x01: Progress      (JSON: { Percent, Message, Step, TotalSteps })
+	 *   Type 0x02: Intermediate  (raw binary: e.g. thumbnail preview)
+	 *   Type 0x03: Final output  (raw binary: completed file)
+	 *   Type 0x04: Result        (JSON: { Success, Outputs, Log })
+	 *   Type 0x05: Error         (JSON: { Error })
+	 *
+	 * @param {object} pWorkItem - Work item details (same as dispatch())
+	 * @param {object} pCallbacks - Event callbacks:
+	 *   {
+	 *     onProgress: function({ Percent, Message, Step, TotalSteps }) — optional
+	 *     onBinaryData: function(Buffer) — optional, intermediate binary data
+	 *     onError: function({ Error }) — optional, non-fatal error notification
+	 *   }
+	 * @param {function} fCallback - function(pError, pResult) called on completion.
+	 *   pResult includes OutputBuffer (Buffer) if final binary output was streamed.
+	 */
+	dispatchStream(pWorkItem, pCallbacks, fCallback)
+	{
+		if (!this._UltravisorURL)
+		{
+			return fCallback(new Error('Ultravisor Dispatcher: not configured'));
+		}
+
+		let tmpParsedURL;
+		try
+		{
+			tmpParsedURL = new URL(this._UltravisorURL);
+		}
+		catch (pError)
+		{
+			return fCallback(new Error('Invalid UltravisorURL: ' + this._UltravisorURL));
+		}
+
+		let tmpLib = tmpParsedURL.protocol === 'https:' ? libHTTPS : libHTTP;
+
+		let tmpOptions = {
+			hostname: tmpParsedURL.hostname,
+			port: tmpParsedURL.port || (tmpParsedURL.protocol === 'https:' ? 443 : 80),
+			path: '/Beacon/Work/DispatchStream',
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+				'Connection': 'keep-alive'
+			}
+		};
+
+		let tmpCallbackFired = false;
+		let tmpComplete = (pError, pResult) =>
+		{
+			if (tmpCallbackFired) { return; }
+			tmpCallbackFired = true;
+			fCallback(pError, pResult);
+		};
+
+		let tmpReq = tmpLib.request(tmpOptions, (pResponse) =>
+		{
+			// Non-streaming error response (4xx/5xx before stream starts)
+			if (pResponse.statusCode >= 400)
+			{
+				let tmpData = '';
+				pResponse.on('data', (pChunk) => { tmpData += pChunk; });
+				pResponse.on('end', () =>
+				{
+					try
+					{
+						let tmpParsed = JSON.parse(tmpData);
+						tmpComplete(new Error(tmpParsed.Error || `HTTP ${pResponse.statusCode}`));
+					}
+					catch (pParseError)
+					{
+						tmpComplete(new Error(`HTTP ${pResponse.statusCode}: ${tmpData.substring(0, 200)}`));
+					}
+				});
+				pResponse.on('error', tmpComplete);
+				return;
+			}
+
+			// Binary frame stream parser
+			let tmpBuffer = Buffer.alloc(0);
+			let tmpLastResult = null;
+			let tmpBinaryChunks = [];
+
+			pResponse.on('data', (pChunk) =>
+			{
+				tmpBuffer = Buffer.concat([tmpBuffer, pChunk]);
+
+				// Parse complete frames from the buffer
+				while (tmpBuffer.length >= 5)
+				{
+					let tmpPayloadLen = tmpBuffer.readUInt32BE(1);
+
+					if (tmpBuffer.length < 5 + tmpPayloadLen)
+					{
+						break; // Need more data for this frame
+					}
+
+					let tmpType = tmpBuffer.readUInt8(0);
+					let tmpPayload = tmpBuffer.slice(5, 5 + tmpPayloadLen);
+					tmpBuffer = tmpBuffer.slice(5 + tmpPayloadLen);
+
+					switch (tmpType)
+					{
+						case 0x01: // Progress
+							if (pCallbacks && pCallbacks.onProgress)
+							{
+								try
+								{
+									pCallbacks.onProgress(JSON.parse(tmpPayload.toString()));
+								}
+								catch (pParseError)
+								{
+									// Ignore malformed progress frames
+								}
+							}
+							break;
+
+						case 0x02: // Intermediate binary data
+							if (pCallbacks && pCallbacks.onBinaryData)
+							{
+								pCallbacks.onBinaryData(Buffer.from(tmpPayload));
+							}
+							break;
+
+						case 0x03: // Final binary output
+							tmpBinaryChunks.push(Buffer.from(tmpPayload));
+							break;
+
+						case 0x04: // Result metadata
+							try
+							{
+								tmpLastResult = JSON.parse(tmpPayload.toString());
+							}
+							catch (pParseError)
+							{
+								// Ignore malformed result frames
+							}
+							break;
+
+						case 0x05: // Error
+							if (pCallbacks && pCallbacks.onError)
+							{
+								try
+								{
+									pCallbacks.onError(JSON.parse(tmpPayload.toString()));
+								}
+								catch (pParseError)
+								{
+									// Ignore malformed error frames
+								}
+							}
+							break;
+					}
+				}
+			});
+
+			pResponse.on('end', () =>
+			{
+				if (tmpLastResult)
+				{
+					// Attach final binary output as a Buffer
+					if (tmpBinaryChunks.length > 0)
+					{
+						tmpLastResult.OutputBuffer = Buffer.concat(tmpBinaryChunks);
+					}
+					tmpComplete(null, tmpLastResult);
+				}
+				else
+				{
+					tmpComplete(new Error('Stream ended without result frame'));
+				}
+			});
+
+			pResponse.on('error', tmpComplete);
+		});
+
+		tmpReq.on('error', tmpComplete);
+
+		// Disable socket timeout for long-running streaming dispatch
+		tmpReq.setTimeout(0);
+
+		tmpReq.write(JSON.stringify(pWorkItem));
+		tmpReq.end();
+	}
+
 	// ================================================================
 	// HTTP Transport
 	// ================================================================