@vctrl/hooks 0.16.2 → 0.17.0

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

@@ -1,292 +0,0 @@
-/* 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

@@ -1,62 +0,0 @@
-/* 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

@@ -1,351 +0,0 @@
-/* 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)
-	}
-}