Protocolosmedia-object

DeliveryTransport

Spec canónica de protocols/media-object/DELIVERY_TRANSPORT.md, copiada sin reescribir.

ImplementadoSin versión del tren todavía· generada desde protocols/media-object/DELIVERY_TRANSPORT.md

Página generada desde protocols/media-object/DELIVERY_TRANSPORT.md. No se edita a mano: bun run docs:gen la regenera y bun run docs:check falla si difiere.

DeliveryTransport

Interface

interface DeliveryTransport {
  /** Retorna el tamaño total del recurso en bytes. */
  getSize(): Promise<number>;

  /**
   * Lee un rango de bytes [start, end) del recurso.
   * Retorna un stream asíncrono de chunks Uint8Array.
   * Lanza si el rango es inválido o el recurso no está disponible.
   */
  readRange(start: number, end: number, requestId: string): AsyncIterable<Uint8Array>;

  /**
   * Cancela una request de lectura en vuelo (r20 §3.6).
   * cancel(requestId) es por request, no global.
   * Si la request ya completó, es no-op.
   */
  cancel(requestId: string): void;

  /** Libera todos los recursos del transporte. */
  close(): Promise<void>;
}

Relación con ISeekableMediaSource

AspectoDeliveryTransportISeekableMediaSource
PlanoDelivery (servidor → cliente)Storage (servidor ↔ storage)
DirecciónServidor → ClienteServidor → Storage
AbstracciónRecurso remoto accesible por rangoCualquier fuente (local, HTTP, S3, torrent)
Método clavereadRange(start, end)readAt(offset, size)
Cancelacióncancel(requestId) por requestcancel(requestId) por request
PropósitoEntregar bytes al clienteObtener bytes del storage

DeliveryTransport puede implementarse envolviendo un ISeekableMediaSource (el delivery lee del source y sirve al cliente), pero no son el mismo contrato.

Consideraciones

  • requestId en readRange y cancel debe ser único por request dentro de una sesión.
  • cancel no debe lanzar si el requestId no existe (no-op seguro).
  • close debe ser idempotente.
  • Los chunks en readRange pueden ser de cualquier tamaño; el consumidor no debe asumir tamaños fijos.