Resolves to EXACTLY length bytes starting at offset, or rejects with
an FcbError. Never returns a short buffer, and never clamps a range
that crosses the end of the resource. The returned array MAY be a view
into a buffer the reader reuses on its next call, so a caller that needs
the bytes to outlive the next read must copy them.
Optionalopts: ReadOptsThe resource's total byte length. Synchronous by contract: every source
learns its size when it opens (a stat, blob.size, or a
Content-Range at open time), so the reader's layout arithmetic never
has to await.
Caching decorator: over-fetches to
minRequestSizeand serves subsequent reads inside the cached window without touching the inner reader. This is what makes traversal over a chatty transport (HTTP) cheap while leaving a local source's behaviour effectively unchanged.Buffering policy (exact, so request patterns are predictable from it): the reader holds one window
[bufOffset, bufOffset + buf.length). A request is a HIT iffoffset >= bufOffsetandoffset + length <= bufOffset + buf.length; anything else is a MISS. On a MISS it issues exactly one inner read ofmin(max(length, minRequestSize), size() - offset)bytes starting atoffset-- i.e. over-fetch to minRequestSize but never past size() -- and that read replaces the window. A HIT never touches the inner reader.setMinRequestSizeonly changes the over-fetch size used by future misses; it does not invalidate or resize the current window.The buffer returned by
readis asubarrayof the decorator's own buffer, not a copy: callers that need bytes to survive past the nextreadcall must copy them out (Task 8 does this for features).