@struktoai/mirage-core/dist/core/dropbox/read.js

A Unified Virtual Filesystem For AI Agents

// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
import { fileEntry } from "../hierarchy/probe.js";
import { publishRead, writesConditioned } from "../../cache/context.js";
import { record, recordStream, startOp } from "../../observe/context.js";
import {} from "../../types.js";
import { DropboxApiError, dropboxDownload, dropboxDownloadStream } from "./client.js";
import { MISS_SUMMARIES, NOT_FILE_SUMMARY, RESULT_HEADER } from "./constants.js";
import { resultOf, resultToken } from "./fingerprint.js";
import { checkPath, dropboxPathOf } from "./paths.js";
import { eisdir, enoent } from "../../errors/fs.js";
import { windowFor } from "../../utils/ranges.js";
/**
 * What a download Dropbox refused means, or null. Only a miss is ENOENT (a
 * file the listing named that is gone) and a folder's path EISDIR; any other
 * refusal (restricted_content, a 5xx) names a file that may exist, and is
 * thrown as Dropbox sent it. Mirrors Python's `_refusal`.
 */
function refusal(path, err) {
    if (!(err instanceof DropboxApiError) || err.status !== 409)
        return null;
    if (MISS_SUMMARIES.some((miss) => err.summary.startsWith(miss)))
        return enoent(path.virtual);
    if (err.summary.startsWith(NOT_FILE_SUMMARY))
        return eisdir(path.virtual);
    return null;
}
/**
 * Read a file, optionally only a byte range of it.
 *
 * Args:
 *   accessor: Dropbox accessor.
 *   path: the path to read.
 *   options: `{offset, size}`, the byte window, or absent for the whole file.
 *   entry: what is at the path.
 */
export async function read(accessor, path, options, entry) {
    fileEntry(path, entry);
    return readByPath(accessor, path, options);
}
/**
 * Read an exactly spelled path without requiring a listing entry. Rewrites
 * use the same spelling guard as uploads, so an absent alias cannot turn
 * a truncate into an overwrite of another name. Mirrors Python's `read_by_path`.
 */
export async function readByPath(accessor, path, options) {
    await checkPath(accessor, path);
    const window = windowFor(options?.offset ?? 0, options?.size ?? null);
    const timer = startOp();
    let download;
    try {
        download = await dropboxDownload(accessor.tokenManager, dropboxPathOf(accessor, path), window);
    }
    catch (err) {
        throw refusal(path, err) ?? err;
    }
    const [data, result] = download;
    const token = resultToken(resultOf(result));
    record('read', path.virtual, 'dropbox', data.byteLength, timer, { fingerprint: token });
    if (window === undefined && writesConditioned(path))
        publishRead(path.virtual, data, token);
    return data;
}
/** Stream a file, stamped with its content_hash. Mirrors Python's `read_stream`. */
export async function* readStream(accessor, path, entry) {
    await checkPath(accessor, path);
    fileEntry(path, entry);
    const rec = recordStream('read', path.virtual, 'dropbox');
    const stamp = (headers) => {
        if (rec !== null) {
            rec.fingerprint = resultToken(resultOf(headers[RESULT_HEADER.toLowerCase()]));
        }
    };
    try {
        for await (const chunk of dropboxDownloadStream(accessor.tokenManager, dropboxPathOf(accessor, path), stamp)) {
            if (rec !== null)
                rec.bytes += chunk.byteLength;
            yield chunk;
        }
    }
    catch (err) {
        throw refusal(path, err) ?? err;
    }
    if (rec !== null)
        rec.complete = true;
}
//# sourceMappingURL=read.js.map