@vctrl/hooks 0.9.4 → 0.11.1

package/src/use-optimize-model/utils/texture-optimization.ts

@@ -0,0 +1,292 @@
+/* vectreal-core | vctrl/hooks
+Copyright (C) 2024 Moritz Becker
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>. */
+
+import { validateServerResponse } from './validation'
+import { ServerCommunicationService } from '../../utils/server-communication'
+
+import type {
+	ModelOptimizer,
+	TextureCompressOptions,
+	TextureDescriptor
+} from '@vctrl/core/model-optimizer'
+
+const DEFAULT_TIMEOUT_MS = 20_000
+const DEFAULT_MAX_RETRIES = 2
+const DEFAULT_MAX_TEXTURE_UPLOAD_BYTES = 50 * 1024 * 1024
+const DEFAULT_MAX_CONCURRENT_REQUESTS = 4
+const TRANSIENT_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504])
+
+const wait = async (ms: number): Promise<void> => {
+	await new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+const resolveTextureMimeType = (response: Response): string => {
+	const contentType = response.headers.get('content-type')
+	if (!contentType) {
+		return 'application/octet-stream'
+	}
+
+	return contentType.split(';')[0]?.trim() || 'application/octet-stream'
+}
+
+const resolveCanonicalTextureFileName = (response: Response): string => {
+	const responseFileName =
+		response.headers.get('X-Texture-File-Name') ||
+		response.headers.get('X-Texture-Name')
+
+	if (!responseFileName || responseFileName.trim().length === 0) {
+		throw new Error(
+			'Optimized texture response is missing a canonical file name'
+		)
+	}
+
+	return responseFileName.trim()
+}
+
+const requestSingleTextureOptimization = async (
+	endpoint: string,
+	headers: HeadersInit,
+	body: ArrayBuffer,
+	requestTimeoutMs: number,
+	maxRetries: number
+): Promise<Response> => {
+	let attempt = 0
+
+	while (true) {
+		const controller = new AbortController()
+		const timeoutId = setTimeout(() => controller.abort(), requestTimeoutMs)
+
+		try {
+			const response = await fetch(endpoint, {
+				method: 'POST',
+				headers,
+				body,
+				signal: controller.signal
+			})
+
+			if (
+				!response.ok &&
+				TRANSIENT_STATUS_CODES.has(response.status) &&
+				attempt < maxRetries
+			) {
+				attempt += 1
+				await wait(200 * attempt + Math.floor(Math.random() * 120))
+				continue
+			}
+
+			return response
+		} catch (error) {
+			if (attempt >= maxRetries) {
+				throw error
+			}
+
+			attempt += 1
+			await wait(200 * attempt + Math.floor(Math.random() * 120))
+		} finally {
+			clearTimeout(timeoutId)
+		}
+	}
+}
+
+const optimizeTexture = async (
+	optimizer: ModelOptimizer,
+	texture: TextureDescriptor,
+	options: TextureCompressOptions,
+	serverOptions: ReturnType<
+		typeof ServerCommunicationService.createDefaultServerOptions
+	>
+): Promise<void> => {
+	const payload = optimizer.getTexturePayload(texture.index)
+	const maxTextureUploadBytes =
+		options.maxTextureUploadBytes ?? DEFAULT_MAX_TEXTURE_UPLOAD_BYTES
+
+	if (payload.image.byteLength > maxTextureUploadBytes) {
+		throw new Error(
+			`Texture ${texture.index} payload (${payload.image.byteLength} bytes) exceeds maxTextureUploadBytes (${maxTextureUploadBytes} bytes). Increase maxTextureUploadBytes to allow optimizing larger source textures.`
+		)
+	}
+
+	const requestBytes = new Uint8Array(payload.image.byteLength)
+	requestBytes.set(payload.image)
+	const requestBody = requestBytes.buffer
+	const { serverOptions: _, ...restOptions } = options
+	const headers = ServerCommunicationService.createRequestHeaders(
+		serverOptions,
+		{
+			'Content-Type': 'application/octet-stream',
+			'X-Texture-Index': String(texture.index),
+			'X-Texture-Name': payload.fileName,
+			'X-Texture-File-Name': payload.fileName,
+			'X-Texture-Mime-Type': payload.mimeType,
+			'X-Optimize-Options': JSON.stringify(restOptions)
+		}
+	)
+
+	const response = await requestSingleTextureOptimization(
+		serverOptions.endpoint,
+		headers,
+		requestBody,
+		options.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS,
+		options.maxRetries ?? DEFAULT_MAX_RETRIES
+	)
+
+	if (!response.ok) {
+		await ServerCommunicationService.handleServerResponseError(response)
+	}
+
+	await validateServerResponse(response)
+
+	const responseTextureIndex = Number.parseInt(
+		response.headers.get('X-Texture-Index') || '',
+		10
+	)
+
+	if (
+		!Number.isFinite(responseTextureIndex) ||
+		responseTextureIndex !== texture.index
+	) {
+		throw new Error(
+			`Texture identity mismatch. Expected ${texture.index}, received ${response.headers.get('X-Texture-Index')}`
+		)
+	}
+
+	const optimizedTextureBytes = new Uint8Array(await response.arrayBuffer())
+	if (optimizedTextureBytes.byteLength === 0) {
+		throw new Error(`Empty optimized payload for texture ${texture.index}`)
+	}
+
+	const canonicalFileName = resolveCanonicalTextureFileName(response)
+
+	optimizer.replaceTexturePayload(
+		texture.index,
+		optimizedTextureBytes,
+		resolveTextureMimeType(response),
+		canonicalFileName
+	)
+}
+
+/**
+ * Performs server-side texture optimization.
+ */
+export const performServerSideTextureOptimization = async (
+	optimizer: ModelOptimizer,
+	options: TextureCompressOptions
+): Promise<void> => {
+	const serverOptions = ServerCommunicationService.createDefaultServerOptions(
+		options.serverOptions
+	)
+	const textures = optimizer.listTextureDescriptors()
+	const failures: Array<{ index: number; reason: string }> = []
+	let successCount = 0
+	const maxConcurrentRequests =
+		options.maxConcurrentRequests ?? DEFAULT_MAX_CONCURRENT_REQUESTS
+
+	try {
+		for (
+			let start = 0;
+			start < textures.length;
+			start += maxConcurrentRequests
+		) {
+			const chunk = textures.slice(start, start + maxConcurrentRequests)
+			const settled = await Promise.allSettled(
+				chunk.map(async (texture) => {
+					await optimizeTexture(optimizer, texture, options, serverOptions)
+					return texture.index
+				})
+			)
+
+			for (const [index, outcome] of settled.entries()) {
+				if (outcome.status === 'fulfilled') {
+					successCount += 1
+					continue
+				}
+
+				failures.push({
+					index: chunk[index].index,
+					reason:
+						outcome.reason instanceof Error
+							? outcome.reason.message
+							: String(outcome.reason)
+				})
+			}
+		}
+
+		if (successCount > 0) {
+			optimizer.addAppliedOptimization('texture compression')
+		}
+
+		if (failures.length > 0) {
+			const failureSummary = failures
+				.map((failure) => `#${failure.index}: ${failure.reason}`)
+				.join('; ')
+			const prefix =
+				successCount === 0
+					? 'Texture optimization failed for all textures.'
+					: `Texture optimization failed for ${failures.length} of ${textures.length} textures.`
+
+			throw new Error(`${prefix} ${failureSummary}`)
+		}
+	} catch (err) {
+		console.error('Server-side texture compression failed:', err)
+		throw new Error(
+			`Server-side texture compression failed: ${err}. Client-side texture compression is not supported in browser environments.`,
+			{ cause: err }
+		)
+	}
+}
+
+/**
+ * Handles client-side texture optimization (throws error as not supported in browser).
+ */
+export const performClientSideTextureOptimization = (): never => {
+	console.warn(
+		'Client-side texture compression is not supported in browser environments. ' +
+			'Please enable server-side compression by setting serverOptions.enabled = true.'
+	)
+
+	throw new Error(
+		'Texture compression requires server-side processing. Enable serverOptions.enabled = true in your options.'
+	)
+}
+
+/**
+ * Determines if server-side optimization should be used.
+ */
+export const shouldUseServerOptimization = (
+	options?: TextureCompressOptions
+): boolean => {
+	return options?.serverOptions?.enabled ?? false
+}
+
+/**
+ * Main texture optimization function that orchestrates the process.
+ */
+export const optimizeTextures = async (
+	optimizer: ModelOptimizer,
+	options?: TextureCompressOptions
+): Promise<void> => {
+	if (!optimizer.hasModel()) {
+		return
+	}
+
+	const useServer = shouldUseServerOptimization(options)
+
+	if (useServer && options) {
+		await performServerSideTextureOptimization(optimizer, options)
+	} else {
+		performClientSideTextureOptimization()
+	}
+}

package/src/use-optimize-model/utils/validation.ts

@@ -0,0 +1,62 @@
+/* vectreal-core | vctrl/hooks
+Copyright (C) 2024 Moritz Becker
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>. */
+
+/**
+ * Validates that the response contains the expected content type.
+ */
+export const validateResponseContentType = (response: Response): void => {
+	const contentType = response.headers.get('content-type')
+
+	if (!contentType) {
+		throw new Error('Missing content type from server response')
+	}
+
+	if (contentType.includes('application/json')) {
+		throw new Error('Unexpected JSON success response from texture optimizer')
+	}
+
+	if (
+		!contentType.startsWith('image/') &&
+		!contentType.includes('application/octet-stream')
+	) {
+		throw new Error(`Unexpected content type from server: ${contentType}`)
+	}
+}
+
+/**
+ * Validates a server response and throws appropriate errors.
+ */
+export const validateServerResponse = async (
+	response: Response
+): Promise<void> => {
+	// First check if the response was successful
+	if (!response.ok) {
+		return // Error handling is done elsewhere
+	}
+
+	// Check content type for successful responses
+	const contentType = response.headers.get('content-type')
+
+	if (contentType?.includes('application/json')) {
+		// Server returned JSON error despite 200 status
+		const errorData = await response.json()
+		throw new Error(
+			errorData.error || errorData.details || 'Server returned error'
+		)
+	}
+
+	validateResponseContentType(response)
+}

package/src/utils/server-communication.ts

@@ -0,0 +1,351 @@
+/* vectreal-core | vctrl/hooks
+Copyright (C) 2024 Moritz Becker
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>. */
+
+import type {
+	ApiEnvelope,
+	ServerOptions,
+	TextureBinaryPayload,
+	TextureCompressOptions
+} from '@vctrl/core'
+
+/**
+ * Configuration for a server request.
+ */
+export interface ServerRequestConfig {
+	/** Server endpoint URL or path */
+	endpoint: string
+	/** HTTP method (GET, POST, etc.) */
+	method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+	/** Request body (FormData, JSON, or other) */
+	body?: FormData | Record<string, unknown> | string
+	/** Optional server options (headers, auth, etc.) */
+	serverOptions?: ServerOptions
+	/** Content type for JSON bodies (default: 'application/json') */
+	contentType?: string
+}
+
+/**
+ * Unified server communication service for handling HTTP requests.
+ * Provides a consistent interface for API calls with built-in error handling,
+ * authentication, and response parsing.
+ *
+ * @example
+ * ```typescript
+ * // Simple GET request
+ * const data = await ServerCommunicationService.request<SceneData>({
+ *   endpoint: '/api/load-scene',
+ *   method: 'GET'
+ * })
+ *
+ * // POST with FormData
+ * const formData = new FormData()
+ * formData.append('model', file)
+ * const result = await ServerCommunicationService.request({
+ *   endpoint: '/api/optimize',
+ *   method: 'POST',
+ *   body: formData,
+ *   serverOptions: { apiKey: 'secret' }
+ * })
+ *
+ * // POST with JSON
+ * const response = await ServerCommunicationService.request({
+ *   endpoint: '/api/save',
+ *   method: 'POST',
+ *   body: { sceneId: '123', settings: {...} },
+ *   serverOptions: { headers: { 'X-Custom': 'value' } }
+ * })
+ * ```
+ */
+export class ServerCommunicationService {
+	private static extractApiData<T>(response: ApiEnvelope<T> | T): T {
+		if (!response || typeof response !== 'object') {
+			return response as T
+		}
+
+		const envelope = response as ApiEnvelope<T>
+
+		if (envelope.error) {
+			throw new Error(envelope.error)
+		}
+
+		if (envelope.success === false) {
+			throw new Error('Request failed')
+		}
+
+		if ('data' in envelope) {
+			if (typeof envelope.data === 'undefined') {
+				throw new Error('Server response did not include data payload')
+			}
+
+			return envelope.data
+		}
+
+		return response as T
+	}
+
+	/**
+	 * Creates default server options with required endpoint.
+	 * Merges provided options with defaults.
+	 */
+	static createDefaultServerOptions(
+		serverOptions?: ServerOptions
+	): ServerOptions & Required<Pick<ServerOptions, 'endpoint'>> {
+		return {
+			endpoint: '/api/optimize-textures',
+			...serverOptions
+		}
+	}
+
+	/**
+	 * Creates request headers for server communication.
+	 * Includes authentication token if apiKey is provided.
+	 */
+	static createRequestHeaders(
+		serverOptions?: ServerOptions,
+		additionalHeaders?: HeadersInit
+	): HeadersInit {
+		const headers: HeadersInit = {
+			...(serverOptions?.apiKey
+				? { Authorization: `Bearer ${serverOptions.apiKey}` }
+				: {}),
+			...serverOptions?.headers,
+			...additionalHeaders
+		}
+
+		return headers
+	}
+
+	/**
+	 * Extracts error message from a failed response.
+	 * Attempts to parse JSON error data, falls back to text.
+	 */
+	static async extractErrorMessage(response: Response): Promise<string> {
+		let errorMessage = `Server responded with ${response.status}: ${response.statusText}`
+
+		try {
+			const contentType = response.headers.get('content-type')
+			if (contentType?.includes('application/json')) {
+				const errorData = await response.json()
+				errorMessage = errorData.error || errorData.details || errorMessage
+			} else {
+				const errorText = await response.text()
+				if (errorText) errorMessage += ` - ${errorText}`
+			}
+		} catch {
+			// Fallback to basic error message if can't parse response
+		}
+
+		return errorMessage
+	}
+
+	/**
+	 * Handles server response errors and throws appropriate errors.
+	 */
+	static async handleServerResponseError(response: Response): Promise<never> {
+		const errorMessage =
+			await ServerCommunicationService.extractErrorMessage(response)
+		throw new Error(errorMessage)
+	}
+
+	/**
+	 * Prepares FormData for a single texture optimization request.
+	 */
+	static prepareTextureOptimizationFormData(
+		texture: TextureBinaryPayload,
+		options?: TextureCompressOptions
+	): FormData {
+		const requestData = new FormData()
+
+		requestData.append(
+			'texture',
+			new Blob([new Uint8Array(texture.image)], {
+				type: texture.mimeType || 'application/octet-stream'
+			}),
+			`${texture.name || `texture-${texture.index}`}`
+		)
+		requestData.append('textureIndex', String(texture.index))
+		requestData.append('textureName', texture.name)
+		requestData.append('textureMimeType', texture.mimeType)
+
+		if (options) {
+			const { serverOptions: _, ...restOptions } = options
+			requestData.append('options', JSON.stringify(restOptions))
+		}
+
+		return requestData
+	}
+
+	/**
+	 * Performs a generic HTTP request with error handling.
+	 * Returns parsed response data.
+	 *
+	 * @template T - Expected response data type
+	 * @param config - Request configuration
+	 * @returns Promise resolving to parsed response data
+	 * @throws Error if request fails or response is not ok
+	 */
+	static async request<T = unknown>(config: ServerRequestConfig): Promise<T> {
+		const {
+			endpoint,
+			method = 'GET',
+			body,
+			serverOptions,
+			contentType = 'application/json'
+		} = config
+
+		// Prepare headers
+		const headers: HeadersInit =
+			ServerCommunicationService.createRequestHeaders(serverOptions)
+
+		// Prepare request body
+		let requestBody: FormData | string | undefined
+
+		if (body instanceof FormData) {
+			// Don't set Content-Type for FormData - browser will set it with boundary
+			requestBody = body
+		} else if (typeof body === 'object' && body !== null) {
+			// JSON body
+			;(headers as Record<string, string>)['Content-Type'] = contentType
+			requestBody = JSON.stringify(body)
+		} else if (typeof body === 'string') {
+			requestBody = body
+		}
+
+		// Perform request
+		const response = await fetch(endpoint, {
+			method,
+			headers,
+			body: requestBody
+		})
+
+		// Handle errors
+		if (!response.ok) {
+			await ServerCommunicationService.handleServerResponseError(response)
+		}
+
+		// Parse response
+		const responseContentType = response.headers.get('content-type')
+
+		if (responseContentType?.includes('application/json')) {
+			return (await response.json()) as T
+		}
+
+		// For binary responses (e.g., model files)
+		if (
+			responseContentType?.includes('model/') ||
+			responseContentType?.includes('application/octet-stream')
+		) {
+			const arrayBuffer = await response.arrayBuffer()
+			return new Uint8Array(arrayBuffer) as T
+		}
+
+		// Default to text
+		return (await response.text()) as T
+	}
+
+	/**
+	 * Performs a GET request.
+	 * Convenience method for common GET operations.
+	 */
+	static async get<T = unknown>(
+		endpoint: string,
+		serverOptions?: ServerOptions
+	): Promise<T> {
+		return ServerCommunicationService.request<T>({
+			endpoint,
+			method: 'GET',
+			serverOptions
+		})
+	}
+
+	/**
+	 * Performs a POST request with JSON body.
+	 * Convenience method for common POST operations.
+	 */
+	static async post<T = unknown>(
+		endpoint: string,
+		body: Record<string, unknown>,
+		serverOptions?: ServerOptions
+	): Promise<T> {
+		return ServerCommunicationService.request<T>({
+			endpoint,
+			method: 'POST',
+			body,
+			serverOptions
+		})
+	}
+
+	/**
+	 * Performs a POST request with FormData body.
+	 * Convenience method for file uploads.
+	 */
+	static async postFormData<T = unknown>(
+		endpoint: string,
+		formData: FormData,
+		serverOptions?: ServerOptions
+	): Promise<T> {
+		return ServerCommunicationService.request<T>({
+			endpoint,
+			method: 'POST',
+			body: formData,
+			serverOptions
+		})
+	}
+
+	/**
+	 * Fetches scene data from the server.
+	 * Specialized method for loading 3D scenes with their associated settings.
+	 *
+	 * This method handles the vectreal-platform API format which uses:
+	 * - FormData with 'action' and 'sceneId' parameters
+	 * - POST request to the scene-settings endpoint
+	 * - Returns scene data including GLTF JSON and asset data
+	 *
+	 * @param sceneId - The unique identifier of the scene to load
+	 * @param serverOptions - Optional server configuration (endpoint, auth, headers)
+	 * @returns Promise resolving to the scene data
+	 * @throws Error if the request fails or scene doesn't exist
+	 *
+	 * @example
+	 * ```typescript
+	 * const sceneData = await ServerCommunicationService.loadScene('abc-123', {
+	 *   endpoint: '/api/scenes/abc-123',
+	 *   apiKey: 'optional-auth-token'
+	 * })
+	 * ```
+	 */
+	static async loadScene<T = unknown>(
+		sceneId: string,
+		serverOptions?: ServerOptions
+	): Promise<T> {
+		const formData = new FormData()
+		formData.append('action', 'get-scene-settings')
+		formData.append('sceneId', sceneId)
+
+		const endpoint = serverOptions?.endpoint || `/api/scenes/${sceneId}`
+
+		const response = await ServerCommunicationService.request<
+			ApiEnvelope<T> | T
+		>({
+			endpoint,
+			method: 'POST',
+			body: formData,
+			serverOptions
+		})
+
+		return ServerCommunicationService.extractApiData(response)
+	}
+}