@uploadista/client-core 0.0.3

package/src/upload/upload-strategy.ts

@@ -0,0 +1,296 @@
+import type { DataStoreCapabilities } from "@uploadista/core/types";
+import {
+  type NegotiatedStrategy,
+  UploadStrategyNegotiator,
+  type UploadStrategyOptions,
+} from "@uploadista/core/upload";
+import { UploadistaError } from "../error";
+import type { Logger } from "../logger";
+import {
+  defaultClientCapabilities,
+  MockClientDataStore,
+} from "../mock-data-store";
+import type { HttpClient } from "../services/http-client";
+
+export type UploadStrategyConfig = {
+  preferredStrategy?: "single" | "parallel" | "auto";
+  minFileSizeForParallel?: number;
+  enableCapabilityNegotiation?: boolean;
+  onStrategySelected?: (strategy: {
+    chosen: "single" | "parallel";
+    chunkSize: number;
+    parallelUploads: number;
+    reasoning: string[];
+    warnings: string[];
+  }) => void;
+};
+
+export type UploadClientOptions = {
+  baseUrl: string;
+  uploadBasePath?: string;
+  storageId: string;
+  retryDelays?: number[];
+  chunkSize: number;
+  parallelUploads?: number;
+  parallelChunkSize?: number;
+  uploadStrategy?: UploadStrategyConfig;
+};
+
+export function createUploadStrategyNegotiator(
+  dataStore: MockClientDataStore,
+): UploadStrategyNegotiator {
+  return new UploadStrategyNegotiator(dataStore.getCapabilities(), (strategy) =>
+    dataStore.validateUploadStrategy(strategy),
+  );
+}
+
+/**
+ * Fetch capabilities from server
+ */
+export async function fetchServerCapabilities(
+  baseUrl: string,
+  uploadBasePath: string,
+  storageId: string,
+  httpClient: HttpClient,
+): Promise<DataStoreCapabilities> {
+  const capabilitiesUrl = `${baseUrl}/${uploadBasePath}/capabilities?storageId=${encodeURIComponent(storageId)}`;
+
+  try {
+    const response = await httpClient.request(capabilitiesUrl, {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch capabilities: ${response.status} ${response.statusText}`,
+      );
+    }
+
+    const data = await response.json();
+    return (data as { capabilities: DataStoreCapabilities }).capabilities;
+  } catch (_error) {
+    // Fall back to default capabilities if server fetch fails
+    return defaultClientCapabilities;
+  }
+}
+
+/**
+ * Negotiate upload strategy based on capabilities and options
+ */
+export function negotiateUploadStrategy({
+  capabilities,
+  fileSize,
+  chunkSize,
+  parallelUploads,
+  uploadLengthDeferred,
+  strategyConfig,
+  logger,
+}: {
+  capabilities: DataStoreCapabilities;
+  fileSize: number | null;
+  chunkSize: number;
+  parallelUploads: number;
+  uploadLengthDeferred?: boolean;
+  strategyConfig?: UploadStrategyConfig;
+  logger: Logger;
+}): NegotiatedStrategy {
+  if (strategyConfig?.enableCapabilityNegotiation !== false) {
+    // Use capability negotiation with server-fetched capabilities
+    const mockDataStore = new MockClientDataStore(capabilities);
+    const negotiator = createUploadStrategyNegotiator(mockDataStore);
+
+    const negotiationOptions: UploadStrategyOptions = {
+      fileSize: fileSize || 0,
+      preferredStrategy:
+        strategyConfig?.preferredStrategy === "auto"
+          ? undefined
+          : strategyConfig?.preferredStrategy,
+      preferredChunkSize: chunkSize,
+      parallelUploads,
+      minChunkSizeForParallel:
+        strategyConfig?.minFileSizeForParallel || 10 * 1024 * 1024,
+    };
+
+    const negotiatedStrategy = negotiator.negotiateStrategy(negotiationOptions);
+
+    // Log negotiation results
+    logger.log(`Upload strategy negotiated: ${negotiatedStrategy.strategy}`);
+    for (const reason of negotiatedStrategy.reasoning) {
+      logger.log(`  - ${reason}`);
+    }
+    for (const warning of negotiatedStrategy.warnings) {
+      logger.log(`  Warning: ${warning}`);
+    }
+
+    // Notify client of strategy selection if callback provided
+    strategyConfig?.onStrategySelected?.({
+      chosen: negotiatedStrategy.strategy,
+      chunkSize: negotiatedStrategy.chunkSize,
+      parallelUploads: negotiatedStrategy.parallelUploads,
+      reasoning: negotiatedStrategy.reasoning,
+      warnings: negotiatedStrategy.warnings,
+    });
+
+    return negotiatedStrategy;
+  } else {
+    // Fallback to legacy logic
+    const shouldUseParallelUpload =
+      parallelUploads > 1 &&
+      fileSize &&
+      fileSize > (strategyConfig?.minFileSizeForParallel || 10 * 1024 * 1024) &&
+      !uploadLengthDeferred;
+
+    return {
+      strategy: shouldUseParallelUpload ? "parallel" : "single",
+      chunkSize,
+      parallelUploads: shouldUseParallelUpload ? parallelUploads : 1,
+      reasoning: [
+        `Legacy strategy selection: ${shouldUseParallelUpload ? "parallel" : "single"}`,
+      ],
+      warnings: [],
+    };
+  }
+}
+
+/**
+ * Validate upload client configuration against data store capabilities
+ */
+export function validateConfiguration(
+  options: UploadClientOptions,
+  capabilities: DataStoreCapabilities = defaultClientCapabilities,
+  logger: Logger,
+): {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+} {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Validate against capabilities
+  const mockDataStore = new MockClientDataStore(capabilities);
+  const negotiator = createUploadStrategyNegotiator(mockDataStore);
+
+  const validation = negotiator.validateConfiguration({
+    fileSize: 0, // Placeholder for validation
+    preferredStrategy:
+      options.uploadStrategy?.preferredStrategy === "auto"
+        ? undefined
+        : options.uploadStrategy?.preferredStrategy,
+    preferredChunkSize: options.chunkSize,
+    parallelUploads: options.parallelUploads,
+  });
+
+  if (!validation.valid) {
+    errors.push(...validation.errors);
+  }
+
+  // Additional client-specific validations
+  if (options.parallelUploads && options.parallelUploads < 1) {
+    errors.push("parallelUploads must be at least 1");
+  }
+
+  if (options.chunkSize && options.chunkSize < 1024) {
+    warnings.push("Chunk size below 1KB may impact performance");
+  }
+
+  if (
+    options.uploadStrategy?.preferredStrategy === "parallel" &&
+    !options.parallelUploads
+  ) {
+    warnings.push(
+      "Parallel strategy requested but parallelUploads not configured",
+    );
+  }
+
+  // Log validation results
+  if (errors.length > 0) {
+    logger.log("Configuration validation errors:");
+    for (const error of errors) {
+      logger.log(`  Error: ${error}`);
+    }
+  }
+
+  if (warnings.length > 0) {
+    logger.log("Configuration validation warnings:");
+    for (const warning of warnings) {
+      logger.log(`  Warning: ${warning}`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Async configuration validation with server capabilities
+ */
+export async function validateConfigurationAsync(
+  options: UploadClientOptions,
+  httpClient: HttpClient,
+  logger: Logger,
+): Promise<{
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  capabilities: DataStoreCapabilities;
+}> {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  let capabilities: DataStoreCapabilities;
+  try {
+    capabilities = await fetchServerCapabilities(
+      options.baseUrl,
+      options.uploadBasePath || "api/upload",
+      options.storageId,
+      httpClient,
+    );
+  } catch (error) {
+    logger.log(`Failed to fetch server capabilities for validation: ${error}`);
+    capabilities = defaultClientCapabilities;
+    warnings.push(
+      "Using default capabilities for validation - server unavailable",
+    );
+  }
+
+  const validation = validateConfiguration(options, capabilities, logger);
+  errors.push(...validation.errors);
+  warnings.push(...validation.warnings);
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    capabilities,
+  };
+}
+
+/**
+ * Validate options and throw if invalid
+ */
+export function validateAndThrow(
+  options: UploadClientOptions,
+  logger: Logger,
+): void {
+  const validationResult = validateConfiguration(
+    options,
+    defaultClientCapabilities,
+    logger,
+  );
+
+  if (!validationResult.valid) {
+    const errorMessage = `Upload client configuration validation failed: ${validationResult.errors.join(", ")}`;
+    logger.log(errorMessage);
+    throw new UploadistaError({
+      name: "UPLOAD_SIZE_NOT_SPECIFIED", // Reusing existing error type
+      message: errorMessage,
+    });
+  }
+}

package/src/upload/upload-utils.ts

@@ -0,0 +1,114 @@
+import { Base64 } from "js-base64";
+import { UploadistaError } from "../error";
+
+/**
+ * Encodes metadata for upload headers
+ */
+export function encodeMetadata(
+  metadata: Record<string, string | null>,
+): string {
+  return Object.entries(metadata)
+    .map(([key, value]) => `${key} ${Base64.encode(String(value))}`)
+    .join(",");
+}
+
+/**
+ * Checks whether a given status is in the range of the expected category.
+ * For example, only a status between 200 and 299 will satisfy the category 200.
+ */
+export function inStatusCategory(
+  status: number,
+  category: 100 | 200 | 300 | 400 | 500,
+): boolean {
+  return status >= category && status < category + 100;
+}
+
+export type CalculateFileSizeOptions = {
+  uploadLengthDeferred?: boolean;
+  uploadSize?: number;
+};
+
+/**
+ * Calculate the final file size for upload based on options
+ */
+export function calculateFileSize(
+  originalSize: number | null,
+  { uploadLengthDeferred, uploadSize }: CalculateFileSizeOptions,
+): number | null {
+  // First, we look at the uploadLengthDeferred option.
+  // Next, we check if the caller has supplied a manual upload size.
+  // Finally, we try to use the calculated size from the source object.
+  if (uploadLengthDeferred) {
+    return null;
+  }
+
+  if (uploadSize != null) {
+    return uploadSize;
+  }
+
+  const size = originalSize;
+  if (size == null) {
+    throw new UploadistaError({
+      name: "UPLOAD_SIZE_NOT_SPECIFIED",
+      message:
+        "cannot automatically derive upload's size from input. Specify it manually using the `uploadSize` option or use the `uploadLengthDeferred` option",
+    });
+  }
+
+  return size;
+}
+
+/**
+ * Calculate segments for parallel upload
+ */
+export function calculateSegments(
+  fileSize: number,
+  parallelUploads: number,
+  parallelChunkSize?: number,
+): { startByte: number; endByte: number; segmentIndex: number }[] {
+  if (parallelUploads <= 1) {
+    return [{ startByte: 0, endByte: fileSize, segmentIndex: 0 }];
+  }
+
+  // Use parallelChunkSize if provided, otherwise divide file equally
+  const segments: {
+    startByte: number;
+    endByte: number;
+    segmentIndex: number;
+  }[] = [];
+
+  if (parallelChunkSize) {
+    // Fixed segment size approach
+    let currentByte = 0;
+    let segmentIndex = 0;
+
+    while (currentByte < fileSize) {
+      const endByte = Math.min(currentByte + parallelChunkSize, fileSize);
+      segments.push({
+        startByte: currentByte,
+        endByte,
+        segmentIndex,
+      });
+      currentByte = endByte;
+      segmentIndex++;
+    }
+  } else {
+    // Equal division approach
+    const segmentSize = Math.ceil(fileSize / parallelUploads);
+
+    for (let i = 0; i < parallelUploads; i++) {
+      const startByte = i * segmentSize;
+      const endByte = Math.min(startByte + segmentSize, fileSize);
+
+      if (startByte < fileSize) {
+        segments.push({
+          startByte,
+          endByte,
+          segmentIndex: i,
+        });
+      }
+    }
+  }
+
+  return segments;
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "extends": "@uploadista/typescript-config/base.json",
+  "compilerOptions": {
+    "baseUrl": "./",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "lib": ["ES2020"],
+    "target": "ES2020",
+    "typeRoots": ["../../node_modules/@types"],
+    "types": [],
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/__tests__/**",
+    "**/*.test.ts",
+    "**/*.spec.ts"
+  ]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/chunk-buffer.ts","./src/error.ts","./src/index.ts","./src/logger.ts","./src/mock-data-store.ts","./src/network-monitor.ts","./src/smart-chunker.ts","./src/auth/auth-http-client.ts","./src/auth/direct-auth.ts","./src/auth/index.ts","./src/auth/no-auth.ts","./src/auth/saas-auth.ts","./src/auth/types.ts","./src/client/create-uploadista-client.ts","./src/client/index.ts","./src/client/uploadista-api.ts","./src/client/uploadista-websocket-manager.ts","./src/services/abort-controller-service.ts","./src/services/checksum-service.ts","./src/services/file-reader-service.ts","./src/services/fingerprint-service.ts","./src/services/http-client.ts","./src/services/id-generation-service.ts","./src/services/index.ts","./src/services/platform-service.ts","./src/services/service-container.ts","./src/services/storage-service.ts","./src/services/websocket-service.ts","./src/storage/client-storage.ts","./src/storage/in-memory-storage-service.ts","./src/storage/index.ts","./src/types/buffered-chunk.ts","./src/types/chunk-metrics.ts","./src/types/flow-result.ts","./src/types/flow-upload-config.ts","./src/types/flow-upload-item.ts","./src/types/flow-upload-options.ts","./src/types/index.ts","./src/types/multi-flow-upload-options.ts","./src/types/multi-flow-upload-state.ts","./src/types/performance-insights.ts","./src/types/previous-upload.ts","./src/types/upload-options.ts","./src/types/upload-response.ts","./src/types/upload-result.ts","./src/types/upload-session-metrics.ts","./src/upload/chunk-upload.ts","./src/upload/flow-upload.ts","./src/upload/index.ts","./src/upload/parallel-upload.ts","./src/upload/single-upload.ts","./src/upload/upload-manager.ts","./src/upload/upload-metrics.ts","./src/upload/upload-storage.ts","./src/upload/upload-strategy.ts","./src/upload/upload-utils.ts"],"version":"5.9.3"}