objectstore{,/packed}: Document lifetime and integrity behavior

1 files changed, 18 insertions, 1 deletions

diff --git a/objectstore/packed/read_reader.go b/objectstore/packed/read_reader.go
index cbecaf2c..5c9ac8f4 100644
--- a/objectstore/packed/read_reader.go
+++ b/objectstore/packed/read_reader.go
@@ -12,9 +12,18 @@ import (
 	packfmt "codeberg.org/lindenii/furgit/packfile"
 )
 
-// ReadReaderContent reads an object's type, declared content size, and content stream.
+// ReadReaderContent reads an object's type, declared content size, and content
+// stream.
 //
 // The caller must close the returned reader.
+//
+// For base pack entries, the returned reader borrows store-owned mapped pack
+// data and is only valid until the store is closed.
+//
+// Close releases reader-local resources only. It does not drain unread data for
+// additional validation. In particular, malformed trailing compressed data,
+// trailing bytes past the declared object size, and the zlib Adler-32 trailer
+// may go unverified unless the caller reads to io.EOF.
 func (store *Store) ReadReaderContent(id objectid.ObjectID) (objecttype.Type, int64, io.ReadCloser, error) {
 	loc, err := store.lookup(id)
 	if err != nil {
@@ -49,6 +58,14 @@ func (store *Store) ReadReaderContent(id objectid.ObjectID) (objecttype.Type, in
 // ReadReaderFull reads a full serialized object stream as "type size\0content".
 //
 // The caller must close the returned reader.
+//
+// For base pack entries, the returned reader borrows store-owned mapped pack
+// data and is only valid until the store is closed.
+//
+// Close releases reader-local resources only. It does not drain unread data for
+// additional validation. In particular, malformed trailing compressed data,
+// trailing bytes past the declared object size, and the zlib Adler-32 trailer
+// may go unverified unless the caller reads to io.EOF.
 func (store *Store) ReadReaderFull(id objectid.ObjectID) (io.ReadCloser, error) {
 	loc, err := store.lookup(id)
 	if err != nil {