@struktoai/mirage-core/dist/utils/ranges.d.ts

A Unified Virtual Filesystem For AI Agents

/**
 * A byte window, as every HTTP-backed reader takes one.
 *
 * The pair travels together because a store that sends a `Range` has to
 * check the answer against the same two numbers, so a helper handed only
 * the rendered header cannot finish the job.
 */
export interface ByteWindow {
    offset: number;
    size: number | null;
}
/**
 * The window a reader was asked for, or undefined when it wants all of it.
 *
 * @param offset first byte to read
 * @param size how many bytes, or null for the rest
 */
export declare function windowFor(offset: number, size: number | null): ByteWindow | undefined;
/**
 * An HTTP `Range` value for a byte window, or null for the whole file.
 *
 * Every HTTP-backed store spells a partial read the same way, so the spelling
 * lives here rather than once per backend. `null` means the caller wants
 * everything and should send no header at all.
 *
 * A zero-length window has no HTTP spelling: `bytes=N--1` is malformed and an
 * absent header means the opposite of what was asked. It is refused here so a
 * caller that forgot to short-circuit finds out rather than silently
 * downloading the whole object.
 *
 * @param offset first byte to read
 * @param size how many bytes, or null for the rest of the file
 */
export declare function rangeHeader(offset: number, size: number | null): string | null;
/**
 * The requested window out of bytes already in hand.
 *
 * The answer when nothing remote can serve a range: a store that renders its
 * content, or one whose reader has no range support.
 *
 * @param data the whole content
 * @param offset first byte to keep
 * @param size how many bytes, or null for the rest
 */
export declare function sliceWindow(data: Uint8Array, offset: number, size: number | null): Uint8Array;
/**
 * Bytes in hand with `payload` written at `offset`, as pwrite(2) leaves a
 * file. The answer when nothing remote can write a range: what lies before
 * and after the window stays, and a gap past the end reads as zeros.
 * Writing nothing changes nothing, even past the end.
 *
 * @param data the whole content
 * @param offset first byte the payload replaces
 * @param payload the bytes written there
 */
export declare function spliceWindow(data: Uint8Array, offset: number, payload: Uint8Array): Uint8Array;
/**
 * Whether an error means "that window runs past the end of the object".
 *
 * OpenDAL's node binding takes an exact byte range and refuses to return
 * fewer bytes than asked for, where a POSIX read simply comes back short.
 * Python is not affected: its binding opens a file object, and `f.read(n)`
 * stops at EOF like any file. The two OpenDAL-backed node backends (hf and
 * nextcloud) therefore retry the read unbounded and take the window
 * themselves; the predicate lives here beside the 416 one rather than in
 * both of them.
 *
 * @param err whatever the reader threw
 */
export declare function isShortRangeRefusal(err: unknown): boolean;
/**
 * Whether an error means "that byte window starts past the end of the object".
 *
 * A POSIX read at or past EOF returns zero bytes; an HTTP store answers 416
 * instead, and every backend spells the refusal differently. The predicate
 * lives here so the ops factory can turn all of them into the empty read the
 * caller expects, rather than each backend re-deciding.
 *
 * @param err whatever the backend reader threw
 */
export declare function isUnsatisfiableRange(err: unknown): boolean;
//# sourceMappingURL=ranges.d.ts.map