Logo

Apéndice: Estructuras de datos mínimas (Manifiesto/Parte/Estado)

Este apéndice proporciona recomendaciones mínimas de estructura de datos para "fragmentación paralela + transferencia reanudable + reintentos idempotentes". El objetivo es permitir una simultaneidad de alto rendimiento y una recuperación confiable después de fallas, sin transacciones complejas.

Principios generales

  • Objetos grandes frente a estados pequeños: fragmentos/manifiesto son objetos grandes almacenados en el almacenamiento de objetos; El estado es pequeño y se almacena en una tienda estatal.
  • Claves únicas e idempotencia: un fragmento DEBE ser direccionable de forma única por (transferId, fileId, chunkIndex) para retransmisiones idempotentes.
  • Recoverability: El estado DEBE expresar el “conjunto completo” para que la recuperación pueda omitir las partes completas.
  • Sin fugas sensibles: Las claves y el estado de los objetos DEBEN evitar incrustar campos confidenciales como el correo electrónico o los nombres de archivos originales (si están cifrados depende de su política de privacidad).

A.1 Campos mínimos manifiestos

El manifiesto es el "punto de entrada único" del receptor para su descarga y reensamblaje. Recomendaciones mínimas:

  • manifestVersion: DEBE. Se utiliza para actualizaciones de compatibilidad (p. ej., 1).
  • transferId: DEBE. Identificador único de sesión de transferencia.
  • creado en / expira en: DEBE. Para manejo del ciclo de vida y sugerencias de UI.
  • policy: DEBE. Un resumen de la política (límites de recuento de descargas, requisito de contraseña, si se permite compartir antes de completar, etc.).
  • archivos[]: DEBE. Descripción de la lista de archivos (con tamaños de archivo mínimos y rangos de fragmentos).
  • chunking: DEBE. Incluye ChunkSize y cómo se calcula ChunkCount, o ChunkCount por archivo.
  • objectKeyRule: DEBE. Derive claves de objeto de (transferId, fileId, chunkIndex) o proporcione una tabla de mapeo explícita.

A.1.1 Campos mínimos de archivos[]

  • fileId: DEBE. Identificador de archivo único (no utilice el nombre de archivo como clave única).
  • size: DEBE. Tamaño en bytes.
  • mime: MAYO. Para sugerencias de visualización y descarga.
  • name: MAYO. Si desea un conocimiento cero estricto/fugas mínimas, omita name o almacenar un nombre cifrado.
  • chunkCount: DEBE. Recuento de fragmentos para este archivo.
  • chunkOffset: MAYO. Si varios archivos comparten un global chunkIndex, se necesita una compensación; de lo contrario se puede omitir.

A.1.2 Campos de integridad y verificación (opcional pero recomendado)

  • trozos de hashes[]: DEBE. Verificación por fragmento (uno o una combinación de hash/longitud/etag).
  • fileHash: MAYO. Suma de comprobación de todo el archivo (verificar después de la descarga).
  • ciphertextLength: MAYO. Comprobaciones de coherencia de la longitud a nivel de texto cifrado (no se necesita texto sin formato).

A.2 Objetos fragmentados: restricciones mínimas

  • Direccionamiento único: un fragmento DEBE ser direccionable de forma exclusiva por (transferId, fileId, chunkIndex).
  • Carga idempotente: volver a cargar el mismo fragmento NO DEBE alterar el estado final (puede sobrescribirse o rechazarse, pero el comportamiento debe ser coherente).
  • Metadatos mínimos: el servidor PUEDE registrar solo la longitud del texto cifrado, el tiempo de escritura, la etiqueta electrónica/versión, etc., para fines de observación y resolución de problemas.

A.2.1 Regla clave de objeto (ejemplo)

  • /transfers/{transferId}/chunks/{fileId}/{chunkIndex}
  • /transfers/{transferId}/manifest

Restricción: las claves de objeto DEBEN admitir la limpieza masiva mediante transferId prefijo; Las claves de objeto DEBEN evitar llevar información comercial confidencial.

A.3 Registros estatales: campos mínimos

El estado responde “carga/descarga de progreso y recuperación”. Debe ser pequeño y rápido de leer/escribir.

  • transferId:DEBE。
  • status: DEBE. Valores sugeridos: UPLOADING / READY / DELETED / EXPIRED.
  • uploadedSet: DEBE. Conjunto de trozos completo; DEBE comprimirse con un mapa de bits/conjunto de rangos.
  • uploadedBytes: DEBE. Para visualización del progreso y verificación de cuotas (se puede derivar de fragmentos, pero mantenerlo es más rápido).
  • downloadCount: MAYO. Si aplica límites de recuento de descargas, debe registrarlos y actualizarlos atómicamente (los detalles dependen de su almacenamiento).
  • expiresAt: DEBE. Para cumplimiento de caducidad y limpieza de antecedentes.

A.3.1 Salida mínima para una API de recuperación

Para transferencias reanudables, el servidor DEBE poder devolver:

  • Estado de la transferencia (CARGANDO/LISTO/ELIMINADO/EXPIRADO)
  • uploadedSet (conjunto de fragmentos completo)
  • Resumen de la política (por ejemplo, por encima de la cuota, vencida, si se permite la carga continua)

Nota: límites frente al documento técnico de seguridad y privacidad

  • Este apéndice sólo describe las “estructuras y restricciones” necesarias para la transferencia/almacenamiento.
  • Para conocer los campos de cifrado, cómo se transporta/deriva el material clave y el comportamiento de cierre fallido en caso de fallas de autenticación, consulte el documento técnico de seguridad y privacidad.