@lossless.org/client 1.14.0 → 1.16.0

package/ts/objectstorage/classes.bucket.ts

@@ -18,7 +18,8 @@ import {
   purgeExactPath as purgeExactPathOperation,
 } from './internal.exactpathpurge.operations.js';
 import { beginBasicBucketOperation } from './internal.exactupload.capability.js';
-import { headBucketExists, runAccountRequest } from './internal.bucketrequests.js';
+import { getProviderStatus, headBucketExists, runAccountRequest } from './internal.bucketrequests.js';
+import { ObjectRangeError } from './classes.objectrangeerror.js';
 
 export interface IListObjectKeysPageOptions {
   prefix?: string;
@@ -196,6 +197,58 @@ const toObjectListingEntry = (
   };
 };
 
+const assertByteRangeOptions = (
+  optionsArg: interfaces.IFastGetRangeStreamOptions,
+): interfaces.IObjectByteRange => {
+  const refuse = (messageArg: string): never => {
+    throw new ObjectRangeError('invalid_argument', messageArg);
+  };
+  if (!optionsArg || typeof optionsArg !== 'object' || Array.isArray(optionsArg)) {
+    return refuse('fastGetRangeStream options must be a plain object.');
+  }
+  const range: unknown = optionsArg.range;
+  if (!range || typeof range !== 'object' || Array.isArray(range)) {
+    return refuse('range must be an object with a start and an optional end.');
+  }
+  const { start, end } = range as { start?: unknown; end?: unknown };
+  if (typeof start !== 'number' || !Number.isSafeInteger(start) || start < 0) {
+    return refuse('range.start must be a non-negative safe integer.');
+  }
+  if (end === undefined) {
+    return { start };
+  }
+  if (typeof end !== 'number' || !Number.isSafeInteger(end) || end < start) {
+    return refuse('range.end must be a safe integer that is not below range.start.');
+  }
+  return { start, end };
+};
+
+/**
+ * Reads the served range and the object size from `Content-Range`, and
+ * refuses a response that does not serve exactly the requested range, so a
+ * provider that ignored the Range header never hands out the whole object.
+ */
+const readServedByteRange = (
+  responseArg: plugins.s3.GetObjectCommandOutput,
+  requestedArg: interfaces.IObjectByteRange,
+): { range: { start: number; end: number }; size: number } => {
+  const match = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(responseArg.ContentRange ?? '');
+  const [start, end, size] = match ? match.slice(1).map(Number) : [];
+  if (
+    start === undefined || end === undefined || size === undefined
+    || ![start, end, size].every(Number.isSafeInteger)
+    || start !== requestedArg.start
+    || end !== Math.min(requestedArg.end ?? Number.MAX_SAFE_INTEGER, size - 1)
+    || (responseArg.ContentLength !== undefined && responseArg.ContentLength !== end - start + 1)
+  ) {
+    throw new ObjectRangeError(
+      'invalid_response',
+      'The provider did not answer the byte-range request with a matching Content-Range.',
+    );
+  }
+  return { range: { start, end }, size };
+};
+
 const destroyReadableAndWaitForSettlement = async (
   readableArg: plugins.stream.Readable,
 ): Promise<void> => {
@@ -460,6 +513,64 @@ export class Bucket {
     optionsArg: interfaces.IFastGetStreamOptions,
     typeArg: 'webstream' | 'nodestream' = 'nodestream'
   ): Promise<ReadableStream | plugins.stream.Readable> {
+    const { stream } = await this.openObjectReadStream(optionsArg, typeArg, undefined, () => undefined);
+    return stream;
+  }
+
+  /**
+   * Streams one inclusive byte range of an object with a single GetObject
+   * request and reports the range served and the object's total size from the
+   * provider's `Content-Range`, so an HTTP 206 answer needs no extra HEAD.
+   * An invalid range is refused with `ObjectRangeError` code
+   * `invalid_argument` before any request; a range that starts at or beyond
+   * the end of the object rejects with `range_not_satisfiable`.
+   */
+  public fastGetRangeStream(
+    optionsArg: interfaces.IFastGetRangeStreamOptions,
+    typeArg: 'webstream'
+  ): Promise<interfaces.IFastGetRangeStreamResult<ReadableStream>>;
+  public async fastGetRangeStream(
+    optionsArg: interfaces.IFastGetRangeStreamOptions,
+    typeArg?: 'nodestream'
+  ): Promise<interfaces.IFastGetRangeStreamResult<plugins.stream.Readable>>;
+
+  public async fastGetRangeStream(
+    optionsArg: interfaces.IFastGetRangeStreamOptions,
+    typeArg: 'webstream' | 'nodestream' = 'nodestream'
+  ): Promise<interfaces.IFastGetRangeStreamResult<ReadableStream | plugins.stream.Readable>> {
+    const requested = assertByteRangeOptions(optionsArg);
+    try {
+      const { stream, info } = await this.openObjectReadStream(
+        optionsArg,
+        typeArg,
+        `bytes=${requested.start}-${requested.end ?? ''}`,
+        (responseArg) => readServedByteRange(responseArg, requested),
+      );
+      return { stream, range: info.range, size: info.size };
+    } catch (error) {
+      const { name, httpStatusCode } = getProviderStatus(error);
+      if (httpStatusCode === 416 || name === 'InvalidRange') {
+        throw new ObjectRangeError(
+          'range_not_satisfiable',
+          `The byte range starting at ${requested.start} is not satisfiable for '${optionsArg.path}'.`,
+          { cause: error },
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Sends one GetObject, reads the response headers through `readResponseArg`
+   * before any byte is handed out, and returns the body as a stream that
+   * `optionsArg.signal` and `SmartBucket.close()` cancel.
+   */
+  private async openObjectReadStream<TInfo>(
+    optionsArg: interfaces.IFastGetStreamOptions,
+    typeArg: 'webstream' | 'nodestream',
+    rangeHeaderArg: string | undefined,
+    readResponseArg: (responseArg: plugins.s3.GetObjectCommandOutput) => TInfo,
+  ): Promise<{ stream: ReadableStream | plugins.stream.Readable; info: TInfo }> {
     const operation = beginBasicBucketOperation(this, optionsArg.signal);
     const disposeBody = async (responseBodyArg: unknown): Promise<void> => {
       try {
@@ -494,6 +605,7 @@ export class Bucket {
           new plugins.s3.GetObjectCommand({
             Bucket: operation.bucketName,
             Key: optionsArg.path,
+            ...(rangeHeaderArg === undefined ? {} : { Range: rangeHeaderArg }),
           }),
           { abortSignal: operation.signal },
         ),
@@ -511,6 +623,14 @@ export class Bucket {
     const disposeResponseBody = async (): Promise<void> => {
       await disposeBody(responseBody);
     };
+    let info: TInfo;
+    try {
+      info = readResponseArg(response);
+    } catch (error) {
+      await disposeResponseBody();
+      operation.finish();
+      throw error;
+    }
     let sourceStream: plugins.stream.Readable | null = null;
     try {
       sourceStream = responseBody instanceof plugins.stream.Readable
@@ -644,7 +764,7 @@ export class Bucket {
       operation.finish();
       throw error;
     }
-    return result;
+    return { stream: result, info };
   }
 
   /**

package/ts/objectstorage/classes.objectrangeerror.ts

@@ -0,0 +1,11 @@
+import type { TObjectRangeErrorCode } from './interfaces.js';
+
+export class ObjectRangeError extends Error {
+  public readonly code: TObjectRangeErrorCode;
+
+  constructor(codeArg: TObjectRangeErrorCode, messageArg: string, optionsArg?: ErrorOptions) {
+    super(messageArg, optionsArg);
+    this.name = 'ObjectRangeError';
+    this.code = codeArg;
+  }
+}

package/ts/objectstorage/index.ts

@@ -2,6 +2,7 @@ export * from './classes.smartbucket.js';
 export * from './classes.bucket.js';
 export * from './classes.exactuploaderror.js';
 export * from './classes.exactpathpurgeerror.js';
+export * from './classes.objectrangeerror.js';
 export * from './classes.directory.js';
 export * from './classes.file.js';
 export * from './classes.listcursor.js';

package/ts/objectstorage/interfaces.ts

@@ -13,6 +13,43 @@ export interface IFastGetStreamOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * A byte range of an object, with HTTP semantics: `start` and `end` are
+ * zero-based and inclusive. Without `end` the range runs to the last byte.
+ */
+export interface IObjectByteRange {
+  start: number;
+  end?: number;
+}
+
+export interface IFastGetRangeStreamOptions extends IFastGetStreamOptions {
+  range: IObjectByteRange;
+}
+
+/**
+ * One ranged download: the stream carries exactly the bytes of `range`.
+ * - `range`: the inclusive byte range the provider served, from its
+ *   `Content-Range`; `end` is clamped to the last byte of the object.
+ * - `size`: the byte length of the whole object, from the same header.
+ */
+export interface IFastGetRangeStreamResult<TStream> {
+  stream: TStream;
+  range: { start: number; end: number };
+  size: number;
+}
+
+/**
+ * - `invalid_argument`: the request was refused before it was sent.
+ * - `range_not_satisfiable`: the provider answered HTTP 416; the range starts
+ *   at or beyond the end of the object.
+ * - `invalid_response`: the provider answered without a `Content-Range` that
+ *   matches the requested range, so its bytes were not handed out.
+ */
+export type TObjectRangeErrorCode =
+  | 'invalid_argument'
+  | 'range_not_satisfiable'
+  | 'invalid_response';
+
 export interface IFastPutStreamOptions {
   path: string;
   readableStream: Readable | ReadableStream;

package/ts/objectstorage/internal.bucketrequests.ts

@@ -19,7 +19,7 @@ export const runAccountRequest = async <T>(
   }
 };
 
-const getProviderStatus = (errorArg: unknown): { name?: string; httpStatusCode?: number } => {
+export const getProviderStatus = (errorArg: unknown): { name?: string; httpStatusCode?: number } => {
   if (typeof errorArg !== 'object' || errorArg === null) {
     return {};
   }