@quantum-hub/qhub-api 1.0.4

package/src/api/platform/core/fetcher/getErrorResponseBody.ts

@@ -0,0 +1,33 @@
+import { fromJson } from "../json.js";
+import { getResponseBody } from "./getResponseBody.js";
+
+export async function getErrorResponseBody(response: Response): Promise<unknown> {
+    let contentType = response.headers.get("Content-Type")?.toLowerCase();
+    if (contentType == null || contentType.length === 0) {
+        return getResponseBody(response);
+    }
+
+    if (contentType.indexOf(";") !== -1) {
+        contentType = contentType.split(";")[0]?.trim() ?? "";
+    }
+    switch (contentType) {
+        case "application/hal+json":
+        case "application/json":
+        case "application/ld+json":
+        case "application/problem+json":
+        case "application/vnd.api+json":
+        case "text/json": {
+            const text = await response.text();
+            return text.length > 0 ? fromJson(text) : undefined;
+        }
+        default:
+            if (contentType.startsWith("application/vnd.") && contentType.endsWith("+json")) {
+                const text = await response.text();
+                return text.length > 0 ? fromJson(text) : undefined;
+            }
+
+            // Fallback to plain text if content type is not recognized
+            // Even if no body is present, the response will be an empty string
+            return await response.text();
+    }
+}

package/src/api/platform/core/fetcher/getFetchFn.ts

@@ -0,0 +1,3 @@
+export async function getFetchFn(): Promise<typeof fetch> {
+    return fetch;
+}

package/src/api/platform/core/fetcher/getHeader.ts

@@ -0,0 +1,8 @@
+export function getHeader(headers: Record<string, any>, header: string): string | undefined {
+    for (const [headerKey, headerValue] of Object.entries(headers)) {
+        if (headerKey.toLowerCase() === header.toLowerCase()) {
+            return headerValue;
+        }
+    }
+    return undefined;
+}

package/src/api/platform/core/fetcher/getRequestBody.ts

@@ -0,0 +1,20 @@
+import { toJson } from "../json.js";
+import { toQueryString } from "../url/qs.js";
+
+export declare namespace GetRequestBody {
+    interface Args {
+        body: unknown;
+        type: "json" | "file" | "bytes" | "form" | "other";
+    }
+}
+
+export async function getRequestBody({ body, type }: GetRequestBody.Args): Promise<BodyInit | undefined> {
+    if (type === "form") {
+        return toQueryString(body, { arrayFormat: "repeat", encode: true });
+    }
+    if (type.includes("json")) {
+        return toJson(body);
+    } else {
+        return body as BodyInit;
+    }
+}

package/src/api/platform/core/fetcher/getResponseBody.ts

@@ -0,0 +1,58 @@
+import { fromJson } from "../json.js";
+import { getBinaryResponse } from "./BinaryResponse.js";
+
+export async function getResponseBody(response: Response, responseType?: string): Promise<unknown> {
+    switch (responseType) {
+        case "binary-response":
+            return getBinaryResponse(response);
+        case "blob":
+            return await response.blob();
+        case "arrayBuffer":
+            return await response.arrayBuffer();
+        case "sse":
+            if (response.body == null) {
+                return {
+                    ok: false,
+                    error: {
+                        reason: "body-is-null",
+                        statusCode: response.status,
+                    },
+                };
+            }
+            return response.body;
+        case "streaming":
+            if (response.body == null) {
+                return {
+                    ok: false,
+                    error: {
+                        reason: "body-is-null",
+                        statusCode: response.status,
+                    },
+                };
+            }
+
+            return response.body;
+
+        case "text":
+            return await response.text();
+    }
+
+    // if responseType is "json" or not specified, try to parse as JSON
+    const text = await response.text();
+    if (text.length > 0) {
+        try {
+            const responseBody = fromJson(text);
+            return responseBody;
+        } catch (_err) {
+            return {
+                ok: false,
+                error: {
+                    reason: "non-json",
+                    statusCode: response.status,
+                    rawBody: text,
+                },
+            };
+        }
+    }
+    return undefined;
+}

package/src/api/platform/core/fetcher/index.ts

@@ -0,0 +1,11 @@
+export type { APIResponse } from "./APIResponse.js";
+export type { BinaryResponse } from "./BinaryResponse.js";
+export type { EndpointMetadata } from "./EndpointMetadata.js";
+export { EndpointSupplier } from "./EndpointSupplier.js";
+export type { Fetcher, FetchFunction } from "./Fetcher.js";
+export { fetcher } from "./Fetcher.js";
+export { getHeader } from "./getHeader.js";
+export { HttpResponsePromise } from "./HttpResponsePromise.js";
+export type { RawResponse, WithRawResponse } from "./RawResponse.js";
+export { abortRawResponse, toRawResponse, unknownRawResponse } from "./RawResponse.js";
+export { Supplier } from "./Supplier.js";

package/src/api/platform/core/fetcher/makeRequest.ts

@@ -0,0 +1,42 @@
+import { anySignal, getTimeoutSignal } from "./signals.js";
+
+export const makeRequest = async (
+    fetchFn: (url: string, init: RequestInit) => Promise<Response>,
+    url: string,
+    method: string,
+    headers: Headers | Record<string, string>,
+    requestBody: BodyInit | undefined,
+    timeoutMs?: number,
+    abortSignal?: AbortSignal,
+    withCredentials?: boolean,
+    duplex?: "half",
+): Promise<Response> => {
+    const signals: AbortSignal[] = [];
+
+    let timeoutAbortId: ReturnType<typeof setTimeout> | undefined;
+    if (timeoutMs != null) {
+        const { signal, abortId } = getTimeoutSignal(timeoutMs);
+        timeoutAbortId = abortId;
+        signals.push(signal);
+    }
+
+    if (abortSignal != null) {
+        signals.push(abortSignal);
+    }
+    const newSignals = anySignal(signals);
+    const response = await fetchFn(url, {
+        method: method,
+        headers,
+        body: requestBody,
+        signal: newSignals,
+        credentials: withCredentials ? "include" : undefined,
+        // @ts-ignore
+        duplex,
+    });
+
+    if (timeoutAbortId != null) {
+        clearTimeout(timeoutAbortId);
+    }
+
+    return response;
+};

package/src/api/platform/core/fetcher/requestWithRetries.ts

@@ -0,0 +1,64 @@
+const INITIAL_RETRY_DELAY = 1000; // in milliseconds
+const MAX_RETRY_DELAY = 60000; // in milliseconds
+const DEFAULT_MAX_RETRIES = 2;
+const JITTER_FACTOR = 0.2; // 20% random jitter
+
+function addPositiveJitter(delay: number): number {
+    const jitterMultiplier = 1 + Math.random() * JITTER_FACTOR;
+    return delay * jitterMultiplier;
+}
+
+function addSymmetricJitter(delay: number): number {
+    const jitterMultiplier = 1 + (Math.random() - 0.5) * JITTER_FACTOR;
+    return delay * jitterMultiplier;
+}
+
+function getRetryDelayFromHeaders(response: Response, retryAttempt: number): number {
+    const retryAfter = response.headers.get("Retry-After");
+    if (retryAfter) {
+        const retryAfterSeconds = parseInt(retryAfter, 10);
+        if (!Number.isNaN(retryAfterSeconds) && retryAfterSeconds > 0) {
+            return Math.min(retryAfterSeconds * 1000, MAX_RETRY_DELAY);
+        }
+
+        const retryAfterDate = new Date(retryAfter);
+        if (!Number.isNaN(retryAfterDate.getTime())) {
+            const delay = retryAfterDate.getTime() - Date.now();
+            if (delay > 0) {
+                return Math.min(Math.max(delay, 0), MAX_RETRY_DELAY);
+            }
+        }
+    }
+
+    const rateLimitReset = response.headers.get("X-RateLimit-Reset");
+    if (rateLimitReset) {
+        const resetTime = parseInt(rateLimitReset, 10);
+        if (!Number.isNaN(resetTime)) {
+            const delay = resetTime * 1000 - Date.now();
+            if (delay > 0) {
+                return addPositiveJitter(Math.min(delay, MAX_RETRY_DELAY));
+            }
+        }
+    }
+
+    return addSymmetricJitter(Math.min(INITIAL_RETRY_DELAY * 2 ** retryAttempt, MAX_RETRY_DELAY));
+}
+
+export async function requestWithRetries(
+    requestFn: () => Promise<Response>,
+    maxRetries: number = DEFAULT_MAX_RETRIES,
+): Promise<Response> {
+    let response: Response = await requestFn();
+
+    for (let i = 0; i < maxRetries; ++i) {
+        if ([408, 429].includes(response.status) || response.status >= 500) {
+            const delay = getRetryDelayFromHeaders(response, i);
+
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            response = await requestFn();
+        } else {
+            break;
+        }
+    }
+    return response!;
+}

package/src/api/platform/core/fetcher/signals.ts

@@ -0,0 +1,26 @@
+const TIMEOUT = "timeout";
+
+export function getTimeoutSignal(timeoutMs: number): { signal: AbortSignal; abortId: ReturnType<typeof setTimeout> } {
+    const controller = new AbortController();
+    const abortId = setTimeout(() => controller.abort(TIMEOUT), timeoutMs);
+    return { signal: controller.signal, abortId };
+}
+
+export function anySignal(...args: AbortSignal[] | [AbortSignal[]]): AbortSignal {
+    const signals = (args.length === 1 && Array.isArray(args[0]) ? args[0] : args) as AbortSignal[];
+
+    const controller = new AbortController();
+
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort((signal as any)?.reason);
+            break;
+        }
+
+        signal.addEventListener("abort", () => controller.abort((signal as any)?.reason), {
+            signal: controller.signal,
+        });
+    }
+
+    return controller.signal;
+}

package/src/api/platform/core/file/exports.ts

@@ -0,0 +1 @@
+export type { Uploadable } from "./types.js";

package/src/api/platform/core/file/file.ts

@@ -0,0 +1,217 @@
+import type { Uploadable } from "./types.js";
+
+export async function toBinaryUploadRequest(
+    file: Uploadable,
+): Promise<{ body: Uploadable.FileLike; headers?: Record<string, string> }> {
+    const { data, filename, contentLength, contentType } = await getFileWithMetadata(file);
+    const request = {
+        body: data,
+        headers: {} as Record<string, string>,
+    };
+    if (filename) {
+        request.headers["Content-Disposition"] = `attachment; filename="${filename}"`;
+    }
+    if (contentType) {
+        request.headers["Content-Type"] = contentType;
+    }
+    if (contentLength != null) {
+        request.headers["Content-Length"] = contentLength.toString();
+    }
+    return request;
+}
+
+export async function toMultipartDataPart(
+    file: Uploadable,
+): Promise<{ data: Uploadable.FileLike; filename?: string; contentType?: string }> {
+    const { data, filename, contentType } = await getFileWithMetadata(file, {
+        noSniffFileSize: true,
+    });
+    return {
+        data,
+        filename,
+        contentType,
+    };
+}
+
+async function getFileWithMetadata(
+    file: Uploadable,
+    { noSniffFileSize }: { noSniffFileSize?: boolean } = {},
+): Promise<Uploadable.WithMetadata> {
+    if (isFileLike(file)) {
+        return getFileWithMetadata(
+            {
+                data: file,
+            },
+            { noSniffFileSize },
+        );
+    }
+
+    if ("path" in file) {
+        const fs = await import("fs");
+        if (!fs || !fs.createReadStream) {
+            throw new Error("File path uploads are not supported in this environment.");
+        }
+        const data = fs.createReadStream(file.path);
+        const contentLength =
+            file.contentLength ?? (noSniffFileSize === true ? undefined : await tryGetFileSizeFromPath(file.path));
+        const filename = file.filename ?? getNameFromPath(file.path);
+        return {
+            data,
+            filename,
+            contentType: file.contentType,
+            contentLength,
+        };
+    }
+    if ("data" in file) {
+        const data = file.data;
+        const contentLength =
+            file.contentLength ??
+            (await tryGetContentLengthFromFileLike(data, {
+                noSniffFileSize,
+            }));
+        const filename = file.filename ?? tryGetNameFromFileLike(data);
+        return {
+            data,
+            filename,
+            contentType: file.contentType ?? tryGetContentTypeFromFileLike(data),
+            contentLength,
+        };
+    }
+
+    throw new Error(`Invalid FileUpload of type ${typeof file}: ${JSON.stringify(file)}`);
+}
+
+function isFileLike(value: unknown): value is Uploadable.FileLike {
+    return (
+        isBuffer(value) ||
+        isArrayBufferView(value) ||
+        isArrayBuffer(value) ||
+        isUint8Array(value) ||
+        isBlob(value) ||
+        isFile(value) ||
+        isStreamLike(value) ||
+        isReadableStream(value)
+    );
+}
+
+async function tryGetFileSizeFromPath(path: string): Promise<number | undefined> {
+    try {
+        const fs = await import("fs");
+        if (!fs || !fs.promises || !fs.promises.stat) {
+            return undefined;
+        }
+        const fileStat = await fs.promises.stat(path);
+        return fileStat.size;
+    } catch (_fallbackError) {
+        return undefined;
+    }
+}
+
+function tryGetNameFromFileLike(data: Uploadable.FileLike): string | undefined {
+    if (isNamedValue(data)) {
+        return data.name;
+    }
+    if (isPathedValue(data)) {
+        return getNameFromPath(data.path.toString());
+    }
+    return undefined;
+}
+
+async function tryGetContentLengthFromFileLike(
+    data: Uploadable.FileLike,
+    { noSniffFileSize }: { noSniffFileSize?: boolean } = {},
+): Promise<number | undefined> {
+    if (isBuffer(data)) {
+        return data.length;
+    }
+    if (isArrayBufferView(data)) {
+        return data.byteLength;
+    }
+    if (isArrayBuffer(data)) {
+        return data.byteLength;
+    }
+    if (isBlob(data)) {
+        return data.size;
+    }
+    if (isFile(data)) {
+        return data.size;
+    }
+    if (noSniffFileSize === true) {
+        return undefined;
+    }
+    if (isPathedValue(data)) {
+        return await tryGetFileSizeFromPath(data.path.toString());
+    }
+    return undefined;
+}
+
+function tryGetContentTypeFromFileLike(data: Uploadable.FileLike): string | undefined {
+    if (isBlob(data)) {
+        return data.type;
+    }
+    if (isFile(data)) {
+        return data.type;
+    }
+
+    return undefined;
+}
+
+function getNameFromPath(path: string): string | undefined {
+    const lastForwardSlash = path.lastIndexOf("/");
+    const lastBackSlash = path.lastIndexOf("\\");
+    const lastSlashIndex = Math.max(lastForwardSlash, lastBackSlash);
+    return lastSlashIndex >= 0 ? path.substring(lastSlashIndex + 1) : path;
+}
+
+type NamedValue = {
+    name: string;
+} & unknown;
+
+type PathedValue = {
+    path: string | { toString(): string };
+} & unknown;
+
+type StreamLike = {
+    read?: () => unknown;
+    pipe?: (dest: unknown) => unknown;
+} & unknown;
+
+function isNamedValue(value: unknown): value is NamedValue {
+    return typeof value === "object" && value != null && "name" in value;
+}
+
+function isPathedValue(value: unknown): value is PathedValue {
+    return typeof value === "object" && value != null && "path" in value;
+}
+
+function isStreamLike(value: unknown): value is StreamLike {
+    return typeof value === "object" && value != null && ("read" in value || "pipe" in value);
+}
+
+function isReadableStream(value: unknown): value is ReadableStream {
+    return typeof value === "object" && value != null && "getReader" in value;
+}
+
+function isBuffer(value: unknown): value is Buffer {
+    return typeof Buffer !== "undefined" && Buffer.isBuffer && Buffer.isBuffer(value);
+}
+
+function isArrayBufferView(value: unknown): value is ArrayBufferView {
+    return typeof ArrayBuffer !== "undefined" && ArrayBuffer.isView(value);
+}
+
+function isArrayBuffer(value: unknown): value is ArrayBuffer {
+    return typeof ArrayBuffer !== "undefined" && value instanceof ArrayBuffer;
+}
+
+function isUint8Array(value: unknown): value is Uint8Array {
+    return typeof Uint8Array !== "undefined" && value instanceof Uint8Array;
+}
+
+function isBlob(value: unknown): value is Blob {
+    return typeof Blob !== "undefined" && value instanceof Blob;
+}
+
+function isFile(value: unknown): value is File {
+    return typeof File !== "undefined" && value instanceof File;
+}

package/src/api/platform/core/file/index.ts

@@ -0,0 +1,2 @@
+export * from "./file.js";
+export * from "./types.js";

package/src/api/platform/core/file/types.ts

@@ -0,0 +1,81 @@
+/**
+ * A file that can be uploaded. Can be a file-like object (stream, buffer, blob, etc.),
+ * a path to a file, or an object with a file-like object and metadata.
+ */
+export type Uploadable = Uploadable.FileLike | Uploadable.FromPath | Uploadable.WithMetadata;
+
+export namespace Uploadable {
+    /**
+     * Various file-like objects that can be used to upload a file.
+     */
+    export type FileLike =
+        | ArrayBuffer
+        | ArrayBufferLike
+        | ArrayBufferView
+        | Uint8Array
+        | import("buffer").Buffer
+        | import("buffer").Blob
+        | import("buffer").File
+        | import("stream").Readable
+        | import("stream/web").ReadableStream
+        | globalThis.Blob
+        | globalThis.File
+        | ReadableStream;
+
+    /**
+     * A file path with optional metadata, used for uploading a file from the file system.
+     */
+    export type FromPath = {
+        /** The path to the file to upload */
+        path: string;
+        /**
+         * Optional override for the file name (defaults to basename of path).
+         * This is used to set the `Content-Disposition` header in upload requests.
+         */
+        filename?: string;
+        /**
+         * Optional MIME type of the file (e.g., 'image/jpeg', 'text/plain').
+         * This is used to set the `Content-Type` header in upload requests.
+         */
+        contentType?: string;
+        /**
+         * Optional file size in bytes.
+         * If not provided, the file size will be determined from the file system.
+         * The content length is used to set the `Content-Length` header in upload requests.
+         */
+        contentLength?: number;
+    };
+
+    /**
+     * A file-like object with metadata, used for uploading files.
+     */
+    export type WithMetadata = {
+        /** The file data */
+        data: FileLike;
+        /**
+         * Optional override for the file name (defaults to basename of path).
+         * This is used to set the `Content-Disposition` header in upload requests.
+         */
+        filename?: string;
+        /**
+         * Optional MIME type of the file (e.g., 'image/jpeg', 'text/plain').
+         * This is used to set the `Content-Type` header in upload requests.
+         *
+         * If not provided, the content type may be determined from the data itself.
+         * * If the data is a `File`, `Blob`, or similar, the content type will be determined from the file itself, if the type is set.
+         * * Any other data type will not have a content type set, and the upload request will use `Content-Type: application/octet-stream` instead.
+         */
+        contentType?: string;
+        /**
+         * Optional file size in bytes.
+         * The content length is used to set the `Content-Length` header in upload requests.
+         * If the content length is not provided and cannot be determined, the upload request will not include the `Content-Length` header, but will use `Transfer-Encoding: chunked` instead.
+         *
+         * If not provided, the file size will be determined depending on the data type.
+         * * If the data is of type `fs.ReadStream` (`createReadStream`), the size will be determined from the file system.
+         * * If the data is a `Buffer`, `ArrayBuffer`, `Uint8Array`, `Blob`, `File`, or similar, the size will be determined from the data itself.
+         * * If the data is a `Readable` or `ReadableStream`, the size will not be determined.
+         */
+        contentLength?: number;
+    };
+}