client: Improve docs of object GET operation (#473)

implementation has changed, documentation has not

client/container_statistic_test.go

@@ -701,8 +701,8 @@ func TestClientStatistic_ObjectGet(t *testing.T) {
 	require.NoError(t, err)
 
 	buff := make([]byte, 32)
-	_, isOk := reader.ReadChunk(buff)
-	require.True(t, isOk)
+	_, err = reader.Read(buff)
+	require.NoError(t, err)
 
 	require.Equal(t, 2, collector.methods[stat.MethodObjectGet].requests)
 }
@@ -771,8 +771,8 @@ func TestClientStatistic_ObjectRange(t *testing.T) {
 	require.NoError(t, err)
 
 	buff := make([]byte, 32)
-	_, isOk := reader.ReadChunk(buff)
-	require.True(t, isOk)
+	_, err = reader.Read(buff)
+	require.NoError(t, err)
 
 	require.Equal(t, 2, collector.methods[stat.MethodObjectRange].requests)
 }

client/object_get.go

@@ -67,11 +67,12 @@ type PrmObjectGet struct {
 	prmObjectRead
 }
 
-// ObjectReader is designed to read one object from NeoFS system.
+// PayloadReader is a data stream of the particular NeoFS object. Implements
+// [io.ReadCloser].
 //
 // Must be initialized using Client.ObjectGetInit, any other
 // usage is unsafe.
-type ObjectReader struct {
+type PayloadReader struct {
 	cancelCtxStream context.CancelFunc
 
 	client *Client
@@ -90,7 +91,7 @@ type ObjectReader struct {
 
 // readHeader reads header of the object. Result means success.
 // Failure reason can be received via Close.
-func (x *ObjectReader) readHeader(dst *object.Object) bool {
+func (x *PayloadReader) readHeader(dst *object.Object) bool {
 	if x.statisticCallback != nil {
 		defer func() {
 			x.statisticCallback(x.err)
@@ -134,7 +135,7 @@ func (x *ObjectReader) readHeader(dst *object.Object) bool {
 	return true
 }
 
-func (x *ObjectReader) readChunk(buf []byte) (int, bool) {
+func (x *PayloadReader) readChunk(buf []byte) (int, bool) {
 	if x.statisticCallback != nil {
 		defer func() {
 			x.statisticCallback(x.err)
@@ -194,15 +195,7 @@ func (x *ObjectReader) readChunk(buf []byte) (int, bool) {
 	}
 }
 
-// ReadChunk reads another chunk of the object payload. Works similar to
-// io.Reader.Read but returns success flag instead of error.
-//
-// Failure reason can be received via Close.
-func (x *ObjectReader) ReadChunk(buf []byte) (int, bool) {
-	return x.readChunk(buf)
-}
-
-func (x *ObjectReader) close(ignoreEOF bool) error {
+func (x *PayloadReader) close(ignoreEOF bool) error {
 	var err error
 	if x.statisticCallback != nil {
 		defer func() {
@@ -230,27 +223,14 @@ func (x *ObjectReader) close(ignoreEOF bool) error {
 	return nil
 }
 
-// Close ends reading the object and returns the result of the operation
-// along with the final results. Must be called after using the ObjectReader.
-//
-// Any client's internal or transport errors are returned as Go built-in error.
-// If Client is tuned to resolve NeoFS API statuses, then NeoFS failures
-// codes are returned as error.
-//
-// Return errors:
-//   - global (see Client docs)
-//   - *[object.SplitInfoError] (returned on virtual objects with PrmObjectGet.MakeRaw)
-//   - [apistatus.ErrContainerNotFound]
-//   - [apistatus.ErrObjectNotFound]
-//   - [apistatus.ErrObjectAccessDenied]
-//   - [apistatus.ErrObjectAlreadyRemoved]
-//   - [apistatus.ErrSessionTokenExpired]
-func (x *ObjectReader) Close() error {
+// Close ends reading the object payload. Must be called after using the
+// PayloadReader.
+func (x *PayloadReader) Close() error {
 	return x.close(true)
 }
 
 // Read implements io.Reader of the object payload.
-func (x *ObjectReader) Read(p []byte) (int, error) {
+func (x *PayloadReader) Read(p []byte) (int, error) {
 	n, ok := x.readChunk(p)
 
 	x.remainingPayloadLen -= n
@@ -271,18 +251,25 @@ func (x *ObjectReader) Read(p []byte) (int, error) {
 }
 
 // ObjectGetInit initiates reading an object through a remote server using NeoFS API protocol.
+// Returns header of the requested object and stream of its payload separately.
 //
-// The call only opens the transmission channel, explicit fetching is done using the ObjectReader.
-// Exactly one return value is non-nil. Resulting reader must be finally closed.
+// Exactly one return value is non-nil. Resulting PayloadReader must be finally closed.
 //
 // Context is required and must not be nil. It is used for network communication.
 //
 // Signer is required and must not be nil. The operation is executed on behalf of the account corresponding to
 // the specified Signer, which is taken into account, in particular, for access control.
 //
 // Return errors:
+//   - global (see Client docs)
 //   - [ErrMissingSigner]
-func (c *Client) ObjectGetInit(ctx context.Context, containerID cid.ID, objectID oid.ID, signer neofscrypto.Signer, prm PrmObjectGet) (object.Object, *ObjectReader, error) {
+//   - *[object.SplitInfoError] (returned on virtual objects with PrmObjectGet.MakeRaw)
+//   - [apistatus.ErrContainerNotFound]
+//   - [apistatus.ErrObjectNotFound]
+//   - [apistatus.ErrObjectAccessDenied]
+//   - [apistatus.ErrObjectAlreadyRemoved]
+//   - [apistatus.ErrSessionTokenExpired]
+func (c *Client) ObjectGetInit(ctx context.Context, containerID cid.ID, objectID oid.ID, signer neofscrypto.Signer, prm PrmObjectGet) (object.Object, *PayloadReader, error) {
 	var (
 		addr  v2refs.Address
 		cidV2 v2refs.ContainerID
@@ -330,7 +317,7 @@ func (c *Client) ObjectGetInit(ctx context.Context, containerID cid.ID, objectID
 		return hdr, nil, err
 	}
 
-	var r ObjectReader
+	var r PayloadReader
 	r.cancelCtxStream = cancel
 	r.stream = stream
 	r.client = c
@@ -469,7 +456,7 @@ type PrmObjectRange struct {
 }
 
 // ObjectRangeReader is designed to read payload range of one object
-// from NeoFS system.
+// from NeoFS system. Implements [io.ReadCloser].
 //
 // Must be initialized using Client.ObjectRangeInit, any other
 // usage is unsafe.
@@ -556,14 +543,6 @@ func (x *ObjectRangeReader) readChunk(buf []byte) (int, bool) {
 	}
 }
 
-// ReadChunk reads another chunk of the object payload range.
-// Works similar to io.Reader.Read but returns success flag instead of error.
-//
-// Failure reason can be received via Close.
-func (x *ObjectRangeReader) ReadChunk(buf []byte) (int, bool) {
-	return x.readChunk(buf)
-}
-
 func (x *ObjectRangeReader) close(ignoreEOF bool) error {
 	var err error
 	if x.statisticCallback != nil {

pool/object.go

@@ -60,7 +60,7 @@ func (p *Pool) ObjectPutInit(ctx context.Context, hdr object.Object, signer neof
 // Operation is executed within a session automatically created by [Pool] unless parameters explicitly override session settings.
 //
 // See details in [client.Client.ObjectGetInit].
-func (p *Pool) ObjectGetInit(ctx context.Context, containerID cid.ID, objectID oid.ID, signer neofscrypto.Signer, prm client.PrmObjectGet) (object.Object, *client.ObjectReader, error) {
+func (p *Pool) ObjectGetInit(ctx context.Context, containerID cid.ID, objectID oid.ID, signer neofscrypto.Signer, prm client.PrmObjectGet) (object.Object, *client.PayloadReader, error) {
 	var hdr object.Object
 	c, err := p.sdkClient()
 	if err != nil {

pool/pool.go

@@ -1866,7 +1866,7 @@ func (p *Pool) RawClient() (*sdkClient.Client, error) {
 }
 
 type objectReadCloser struct {
-	reader *sdkClient.ObjectReader
+	reader *sdkClient.PayloadReader
 }
 
 // Read implements io.Reader of the object payload.