IReadable.read should document out-of-range errors

[daira]

In interfaces.py, document error behaviour when offset and/or size are outside the bounds of the file.

[zooko]

I think the behavior ought to be to return a short result, i.e. return as many bytes as *do* exist and fall within the requested range, and return the 0-length string if none do. That way clients can issue range read requests without knowing for sure whether the request will start past the end or cross the end, which can allow them to do fewer round trips, maybe, in some cases.

[daira]

Replying to zooko:

I think the behavior ought to be to return a short result, i.e. return as many bytes as *do* exist and fall within the requested range, and return the 0-length string if none do. That way clients can issue range read requests without knowing for sure whether the request will start past the end or cross the end, which can allow them to do fewer round trips, maybe, in some cases.

That's a self-consistent design, but it is not the current design (which is for the web-API to truncate the request as necessary to satisfy HTTP semantics). No extra round trips are ever needed, because the file length is known at the time the web-API makes the read call. Also the design change you suggest is not needed to fix #2459, the bug that motivated this ticket. I am skeptical about doing anything more than necessary to fix that bug in a point release.

[warner]

I'll update it to express the current behavior: reject out-of-range reads, permit zero-length reads.

The webapi continues to allow arbitrary oversized Range: headers, since web/filenode.py clips these to the filesize before calling read(). It's just internal callers who must meet the no-overrun requirement (and they can always read the whole file, offset=0 size=None, without paying attention to get_size() ahead of time).

[warner]

Fixed in [6252a72]

[daira]

Reviewed, +1.