client

func (*Client) AnnounceIntermediateTrust ¶

func (c *Client) AnnounceIntermediateTrust(ctx context.Context, epoch uint64, trust reputation.PeerToPeerTrust, prm PrmAnnounceIntermediateTrust) error

AnnounceIntermediateTrust sends global trust values calculated for the specified NeoFS network participants at some stage of client's calculation algorithm.

Any errors (local or remote, including returned status codes) are returned as Go errors, see apistatus package for NeoFS-specific error types.

Context is required and must not be nil. It is used for network communication.

Return errors:

• ErrZeroEpoch

Parameter epoch must not be zero.

func (*Client) AnnounceLocalTrust ¶

func (c *Client) AnnounceLocalTrust(ctx context.Context, epoch uint64, trusts []reputation.Trust, prm PrmAnnounceLocalTrust) error

AnnounceLocalTrust sends client's trust values to the NeoFS network participants.

Any errors (local or remote, including returned status codes) are returned as Go errors, see apistatus package for NeoFS-specific error types.

Context is required and must not be nil. It is used for network communication.

Return errors:

• ErrZeroEpoch
• ErrMissingTrusts

Parameter epoch must not be zero. Parameter trusts must not be empty.

func (*Client) BalanceGet ¶

func (c *Client) BalanceGet(ctx context.Context, prm PrmBalanceGet) (accounting.Decimal, error)

BalanceGet requests current balance of the NeoFS account.

Any errors (local or remote, including returned status codes) are returned as Go errors, see apistatus package for NeoFS-specific error types.

Context is required and must not be nil. It is used for network communication.

Return errors:

• ErrMissingAccount

func (*Client) Close ¶

func (c *Client) Close() error

Close closes underlying connection to the NeoFS server. Implements io.Closer. Can be called concurrently to server operations in other goroutines: in this case they are likely to fail due to a connection error.

One-time method call during application shutdown stage (after Client.Dial) is expected. Calling multiple times leads to undefined behavior.

See also Client.Dial.

func (*Client) Conn ¶

func (c *Client) Conn() *grpc.ClientConn

Conn returns underlying gRPC connection to the configured endpoint. Must not be called before successful Client.Dial. Conn is not intended for normal use, but may be required to use services not supported by the Client.

func (*Client) ContainerDelete ¶

func (c *Client) ContainerDelete(ctx context.Context, id cid.ID, signer neofscrypto.Signer, prm PrmContainerDelete) error

ContainerDelete sends request to remove the NeoFS container.

Any errors (local or remote, including returned status codes) are returned as Go errors, see apistatus package for NeoFS-specific error types.

Operation is async/await. Deadline is determined from ctx. If ctx has no deadline, server waits 15s after submitting the transaction. On timeout, apistatus.ErrContainerAwaitTimeout is returned. This error indicates a delay in transaction execution, meaning the operation may still succeed. If necessary, caller can continue the wait via Client.ContainerGet. It is recommended to always use context with timeout. Note that the context includes all processing stages incl. network delays.

Success can be verified by reading by identifier (see GetContainer).

Context is required and must not be nil. It is used for network communication.

Signer is required and must not be nil. The account corresponding to the specified Signer will be charged for the operation. Signer's scheme MUST be neofscrypto.ECDSA_DETERMINISTIC_SHA256. For example, you can use neofsecdsa.SignerRFC6979. If signature already exists, use PrmContainerDelete.AttachSignature: then signer will not be used.

Reflects all internal errors in second return value (transport problems, response processing, etc.). Return errors:

• ErrMissingSigner
• apistatus.ErrContainerLocked
• apistatus.ErrContainerAwaitTimeout

func (*Client) ContainerEACL ¶

func (c *Client) ContainerEACL(ctx context.Context, id cid.ID, prm PrmContainerEACL) (eacl.Table, error)

ContainerEACL reads eACL table of the NeoFS container.

Any errors (local or remote, including returned status codes) are returned as Go errors, see apistatus package for NeoFS-specific error types.

Context is required and must not be nil. It is used for network communication.

func (*Client) ContainerGet ¶

func (c *Client) ContainerGet(ctx context.Context, id cid.ID, prm PrmContainerGet) (container.Container, error)

ContainerGet reads NeoFS container by ID. The ID must not be zero.

Any errors (local or remote, including returned status codes) are returned as Go errors, see apistatus package for NeoFS-specific error types.

Context is required and must not be nil. It is used for network communication.

func (*Client) ContainerList ¶

func (c *Client) ContainerList(ctx context.Context, ownerID user.ID, prm PrmContainerList) ([]cid.ID, error)

ContainerList requests identifiers of the account-owned containers.

Any errors (local or remote, including returned status codes) are returned as Go errors, see apistatus package for NeoFS-specific error types.

Context is required and must not be nil. It is used for network communication.

func (*Client) ContainerPut ¶

func (c *Client) ContainerPut(ctx context.Context, cont container.Container, signer neofscrypto.Signer, prm PrmContainerPut) (cid.ID, error)

ContainerPut sends request to save container in NeoFS.

Storage policy is required and limited by:

• 256 replica descriptors;
• 8 objects in each one;
• 64 nodes in any set, i.e. BF * selector count;
• 512 total nodes.

Any errors (local or remote, including returned status codes) are returned as Go errors, see apistatus package for NeoFS-specific error types.

Operation is async/await. Deadline is determined from ctx. If ctx has no deadline, server waits 15s after submitting the transaction. On timeout, apistatus.ErrContainerAwaitTimeout is returned. This error indicates a delay in transaction execution, meaning the operation may still succeed. If necessary, caller can continue the wait via Client.ContainerGet with returned ID. It is recommended to always use context with timeout. Note that the context includes all processing stages incl. network delays.

Success can be verified by reading Client.ContainerGet using the returned identifier (notice that it needs some time to succeed).

Context is required and must not be nil. It is used for network communication.

Signer is required and must not be nil. The account corresponding to the specified Signer will be charged for the operation. Signer's scheme MUST be neofscrypto.ECDSA_DETERMINISTIC_SHA256. For example, you can use neofsecdsa.SignerRFC6979. If signature already exists, use PrmContainerPut.AttachSignature: then signer will not be used.

Return errors:

• ErrMissingSigner
• apistatus.ErrContainerAwaitTimeout

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/nspcc-dev/neo-go/pkg/crypto/keys"
	"github.com/nspcc-dev/neofs-sdk-go/client"
	"github.com/nspcc-dev/neofs-sdk-go/container"
	"github.com/nspcc-dev/neofs-sdk-go/container/acl"

	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"
	"github.com/nspcc-dev/neofs-sdk-go/netmap"
	"github.com/nspcc-dev/neofs-sdk-go/user"
)

func main() {
	ctx := context.Background()
	var accountID user.ID

	// The account was taken from https://github.com/nspcc-dev/neofs-aio
	key, err := keys.NEP2Decrypt("6PYM8VdX2BSm7BSXKzV4Fz6S3R9cDLLWNrD9nMjxW352jEv3fsC8N3wNLY", "one", keys.NEP2ScryptParams())
	if err != nil {
		panic(err)
	}

	signer := user.NewAutoIDSignerRFC6979(key.PrivateKey)
	// take account from user's signer
	accountID = signer.UserID()

	// prepare client
	var prmInit client.PrmInit

	c, err := client.New(prmInit)
	if err != nil {
		panic(fmt.Errorf("New: %w", err))
	}

	// connect to NeoFS gateway
	var prmDial client.PrmDial
	prmDial.SetServerURI("grpc://localhost:8080") // endpoint address
	prmDial.SetTimeout(15 * time.Second)
	prmDial.SetStreamTimeout(15 * time.Second)

	if err = c.Dial(prmDial); err != nil {
		panic(fmt.Errorf("dial %w", err))
	}

	// describe new container
	cont := container.Container{}
	// set version and nonce
	cont.Init()
	cont.SetOwner(accountID)
	cont.SetBasicACL(acl.PublicRW)

	// set reserved attributes
	cont.SetName("name-1")
	cont.SetCreationTime(time.Now().UTC())

	// init placement policy
	var containerID cid.ID

	replica := netmap.ReplicaDescriptor{}
	replica.SetNumberOfObjects(1)

	var placementPolicy netmap.PlacementPolicy
	placementPolicy.SetReplicas([]netmap.ReplicaDescriptor{replica})

	placementPolicy.SetContainerBackupFactor(1)
	cont.SetPlacementPolicy(placementPolicy)

	containerID, err = c.ContainerPut(ctx, cont, signer, client.PrmContainerPut{})
	if err != nil {
		panic(fmt.Errorf("ContainerPut %w", err))
	}

	// containerID already exists
	fmt.Println(containerID)
	// example output: 76wa5UNiT8gk8Q5rdCVCV4pKuZSmYsifh6g84BcL6Hqs

	contRes, err := c.ContainerGet(ctx, containerID, client.PrmContainerGet{})
	if err != nil {
		panic(fmt.Errorf("ContainerGet %w", err))
	}

	jsonData, err := contRes.MarshalJSON()
	if err != nil {
		panic(fmt.Errorf("MarshalJSON %w", err))
	}

	fmt.Println(string(jsonData))
	// example output: {"version":{"major":2,"minor":13},"ownerID":{"value":"Ne6eoiwn40vQFI/EEI4I906PUEiy8ZXKcw=="},"nonce":"rPVd/iw2RW6Q6d66FVnIqg==","basicACL":532660223,"attributes":[{"key":"Name","value":"name-1"},{"key":"Timestamp","value":"1681738627"}],"placementPolicy":{"replicas":[{"count":1,"selector":""}],"containerBackupFactor":1,"selectors":[],"filters":[],"subnetId":{"value":0}}}
}

Output:

func (*Client) ContainerSetEACL ¶

func (c *Client) ContainerSetEACL(ctx context.Context, table eacl.Table, signer user.Signer, prm PrmContainerSetEACL) error

ContainerSetEACL sends request to update eACL table of the NeoFS container.

Any errors (local or remote, including returned status codes) are returned as Go errors, see apistatus package for NeoFS-specific error types.

Operation is async/await. Deadline is determined from ctx. If ctx has no deadline, server waits 15s after submitting the transaction. On timeout, apistatus.ErrContainerAwaitTimeout is returned. This error indicates a delay in transaction execution, meaning the operation may still succeed. If necessary, caller can continue the wait via Client.ContainerEACL. It is recommended to always use context with timeout. Note that the context includes all processing stages incl. network delays.

Success can be verified by reading by identifier (see EACL).

Signer is required and must not be nil. The account corresponding to the specified Signer will be charged for the operation. Signer's scheme MUST be neofscrypto.ECDSA_DETERMINISTIC_SHA256. For example, you can use neofsecdsa.SignerRFC6979. If signature already exists, use PrmContainerSetEACL.AttachSignature: then signer will not be used.

Return errors:

• ErrMissingEACLContainer
• ErrMissingSigner
• apistatus.ErrContainerAwaitTimeout

Context is required and must not be nil. It is used for network communication.

func (*Client) Dial ¶

func (c *Client) Dial(prm PrmDial) error

Dial establishes a connection to the server from the NeoFS network. Returns an error describing failure reason. If failed, the Client SHOULD NOT be used.

Uses the context specified by SetContext if it was called with non-nil argument, otherwise context.Background() is used. Dial returns context errors, see context package docs for details.

Panics if required parameters are set incorrectly, look carefully at the method documentation.

One-time method call during application start-up stage is expected. Calling multiple times leads to undefined behavior.

Return client errors:

• ErrMissingServer
• ErrNonPositiveTimeout

See also Client.Close. nolint:contextcheck

func (*Client) EndpointInfo ¶

func (c *Client) EndpointInfo(ctx context.Context, prm PrmEndpointInfo) (*ResEndpointInfo, error)

EndpointInfo requests information about the storage node served on the remote endpoint.

Method can be used as a health check to see if node is alive and responds to requests.

Any client's internal or transport errors are returned as `error`, see apistatus package for NeoFS-specific error types.

Context is required and must not be nil. It is used for network communication.

Exactly one return value is non-nil. Server status return is returned in ResEndpointInfo. Reflects all internal errors in second return value (transport problems, response processing, etc.).

func (*Client) NetMapSnapshot ¶

func (c *Client) NetMapSnapshot(ctx context.Context, _ PrmNetMapSnapshot) (netmap.NetMap, error)

NetMapSnapshot requests current network view of the remote server.

Any client's internal or transport errors are returned as `error`, see apistatus package for NeoFS-specific error types.

Context is required and MUST NOT be nil. It is used for network communication.

Reflects all internal errors in second return value (transport problems, response processing, etc.).

func (*Client) NetworkInfo ¶

func (c *Client) NetworkInfo(ctx context.Context, prm PrmNetworkInfo) (netmap.NetworkInfo, error)

NetworkInfo requests information about the NeoFS network of which the remote server is a part.

Any client's internal or transport errors are returned as `error`, see apistatus package for NeoFS-specific error types.

Context is required and must not be nil. It is used for network communication.

Reflects all internal errors in second return value (transport problems, response processing, etc.).

func (*Client) ObjectDelete ¶

func (c *Client) ObjectDelete(ctx context.Context, containerID cid.ID, objectID oid.ID, signer user.Signer, prm PrmObjectDelete) (oid.ID, error)

ObjectDelete marks an object for deletion from the container using NeoFS API protocol. As a marker, a special unit called a tombstone is placed in the container. It confirms the user's intent to delete the object, and is itself a container object. Explicit deletion is done asynchronously, and is generally not guaranteed.

Any client's internal or transport errors are returned as `error`, see apistatus package for NeoFS-specific error types.

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. If signer implements neofscrypto.SignerV2, signing is done using it. In this case, neofscrypto.Signer methods are not called. neofscrypto.OverlapSigner may be used to pass neofscrypto.SignerV2 when neofscrypto.Signer is unimplemented.

Return errors:

• global (see Client docs)
• ErrMissingSigner
• apistatus.ErrContainerNotFound
• apistatus.ErrIncomplete
• apistatus.ErrObjectAccessDenied
• apistatus.ErrObjectLocked
• apistatus.ErrSessionTokenExpired

func (*Client) ObjectGetInit ¶

func (c *Client) ObjectGetInit(ctx context.Context, containerID cid.ID, objectID oid.ID, signer user.Signer, prm PrmObjectGet) (object.Object, *PayloadReader, 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. Use PrmObjectGet.SetRange to request a payload range. If PrmObjectGet.MarkPayloadOnly is used, the returned object.Object is empty.

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. If signer implements neofscrypto.SignerV2, signing is done using it. In this case, neofscrypto.Signer methods are not called. neofscrypto.OverlapSigner may be used to pass neofscrypto.SignerV2 when neofscrypto.Signer is unimplemented.

Return errors:

• global (see Client docs)
• ErrMissingSigner
• *object.SplitInfoError (returned on virtual objects with PrmObjectGet.MakeRaw)
• apistatus.ErrContainerNotFound
• apistatus.ErrObjectNotFound
• apistatus.ErrObjectAccessDenied
• apistatus.ErrObjectAlreadyRemoved
• apistatus.ErrSessionTokenExpired

package main

import (
	"context"
	"errors"
	"fmt"
	"io"
	"log"
	"time"

	"github.com/nspcc-dev/neo-go/pkg/wallet"
	"github.com/nspcc-dev/neofs-sdk-go/client"

	apistatus "github.com/nspcc-dev/neofs-sdk-go/client/status"

	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"

	oid "github.com/nspcc-dev/neofs-sdk-go/object/id"
	"github.com/nspcc-dev/neofs-sdk-go/user"
)

func main() {
	const (
		// walletPath is path to your wallet file.
		walletPath = "wallet.json"
		// walletPass is password to decrypt your wallet.
		walletPass = "password"

		// testnetStorageNode is address of NeoFS Testnet storage node.
		// It can be your own node or any public node.
		testnetStorageNode = "st1.t5.fs.neo.org:8080"

		// Example container and object IDs for testing.
		cnrIDStr    = "9wqwAcEU8Vn2tq4T1PVpBT6CbVgFb8WfF8ekSRmcQQjq"
		objectIDStr = "7sTMgE8MzpyvqwLh6EJUXdoPJJyMRRRNHyTx2ErvjgNX"
	)

	ctx := context.Background()

	// Load wallet and decrypt account
	// For public-read containers, this step is not required
	// as no signing is needed to read objects.
	w, err := wallet.NewWalletFromFile(walletPath)
	if err != nil {
		log.Fatal(err)
	}
	addr := w.GetChangeAddress()
	acc := w.GetAccount(addr)
	err = acc.Decrypt(walletPass, w.Scrypt)
	if err != nil {
		log.Fatal(err)
	}
	signer := user.NewAutoIDSigner(acc.PrivateKey().PrivateKey)

	// Create and configure client
	var prmInit client.PrmInit
	c, err := client.New(prmInit)
	if err != nil {
		log.Fatal(fmt.Errorf("client init: %w", err))
	}

	// Connect to NeoFS node
	var prmDial client.PrmDial
	prmDial.SetServerURI(testnetStorageNode)
	// Optional settings
	prmDial.SetTimeout(15 * time.Second)
	prmDial.SetStreamTimeout(15 * time.Second)

	if err = c.Dial(prmDial); err != nil {
		log.Fatal(fmt.Errorf("dial: %w", err))
	}

	// Parse container ID from string
	containerID, err := cid.DecodeString(cnrIDStr)
	if err != nil {
		log.Fatal(fmt.Errorf("parse container ID: %w", err))
	}

	// Parse object ID from string
	objectID, err := oid.DecodeString(objectIDStr)
	if err != nil {
		log.Fatal(fmt.Errorf("parse object ID: %w", err))
	}

	// Configure get parameters
	var prm client.PrmObjectGet

	// Initiate object retrieval
	objHeader, reader, err := c.ObjectGetInit(ctx, containerID, objectID, signer, prm)
	if err != nil {
		switch {
		case errors.Is(err, apistatus.ErrObjectAccessDenied):
			var errAccessDenied apistatus.ObjectAccessDenied
			if errors.As(err, &errAccessDenied) {
				reason := errAccessDenied.Reason()
				if reason != "" {
					log.Fatal(fmt.Errorf("access denied: %s", reason))
				} else {
					log.Fatal(fmt.Errorf("access denied: %w", err))
				}
			}
		case errors.Is(err, apistatus.ErrObjectNotFound):
			log.Fatal(fmt.Errorf("object not found: %w", err))
		default:
			log.Fatal(fmt.Errorf("init object get: %w", err))
		}
	}
	defer reader.Close()

	// Access object header information
	fmt.Printf("Object owner: %s\n", objHeader.Owner())
	fmt.Printf("Payload size: %d bytes\n", objHeader.PayloadSize())
	fmt.Println("Attributes:")
	for _, v := range objHeader.Attributes() {
		fmt.Printf("\t%s: %s\n", v.Key(), v.Value())
	}
	// Example output:
	// Object owner: NfeCA7AuP5zodtJEPsSdkZ2gB3hKdNEhUg
	// Payload size: 1024 bytes
	// Attributes:
	//	FileName: example.txt
	//	ContentType: text/plain

	// Read the payload
	payload, err := io.ReadAll(reader)
	if err != nil {
		log.Fatal(fmt.Errorf("read payload: %w", err))
	}

	fmt.Printf("Successfully read %d bytes\n", len(payload))
	// Example output: Successfully read 1024 bytes
}

Output:

func (*Client) ObjectHead ¶

func (c *Client) ObjectHead(ctx context.Context, containerID cid.ID, objectID oid.ID, signer user.Signer, prm PrmObjectHead) (*object.Object, error)

ObjectHead reads object header through a remote server using NeoFS API protocol.

Exactly one return value is non-nil. By default, server status is returned in res structure. Any client's internal or transport errors are returned as `error`, see apistatus package for NeoFS-specific error types.

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. If signer implements neofscrypto.SignerV2, signing is done using it. In this case, neofscrypto.Signer methods are not called. neofscrypto.OverlapSigner may be used to pass neofscrypto.SignerV2 when neofscrypto.Signer is unimplemented.

Return errors:

• global (see Client docs)
• ErrMissingSigner
• *object.SplitInfoError (returned on virtual objects with PrmObjectHead.MakeRaw)
• apistatus.ErrContainerNotFound
• apistatus.ErrObjectNotFound
• apistatus.ErrObjectAccessDenied
• apistatus.ErrObjectAlreadyRemoved
• apistatus.ErrSessionTokenExpired

func (*Client) ObjectPutInit ¶

func (c *Client) ObjectPutInit(ctx context.Context, hdr object.Object, signer user.Signer, prm PrmObjectPutInit) (ObjectWriter, error)

ObjectPutInit initiates writing an object through a remote server using NeoFS API protocol. Header length is limited to object.MaxHeaderLen.

The call only opens the transmission channel, explicit recording is done using the ObjectWriter. Exactly one return value is non-nil. Resulting writer must be finally closed.

Context is required and must not be nil. It will be used for network communication for the whole object transmission, including put init (this method) and subsequent object payload writes via ObjectWriter.

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. If signer implements neofscrypto.SignerV2, signing is done using it. In this case, neofscrypto.Signer methods are not called. neofscrypto.OverlapSigner may be used to pass neofscrypto.SignerV2 when neofscrypto.Signer is unimplemented.

Returns errors:

• ErrMissingSigner

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/google/uuid"
	"github.com/nspcc-dev/neo-go/pkg/wallet"
	"github.com/nspcc-dev/neofs-sdk-go/client"

	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"

	neofsecdsa "github.com/nspcc-dev/neofs-sdk-go/crypto/ecdsa"
	"github.com/nspcc-dev/neofs-sdk-go/object"
	"github.com/nspcc-dev/neofs-sdk-go/session"
	"github.com/nspcc-dev/neofs-sdk-go/user"
)

func main() {
	const (
		// walletPath is path to your wallet file.
		walletPath = "wallet.json"
		// walletPass is password to decrypt your wallet.
		walletPass = "password"

		// testnetStorageNode is address of NeoFS Testnet storage node.
		// It can be your own node or any public node.
		testnetStorageNode = "st1.t5.fs.neo.org:8080"

		// Example container ID for testing.
		cnrIDStr = "9wqwAcEU8Vn2tq4T1PVpBT6CbVgFb8WfF8ekSRmcQQjq"
	)

	ctx := context.Background()

	// Load wallet and decrypt account
	// This is required to sign the upload request.
	w, err := wallet.NewWalletFromFile(walletPath)
	if err != nil {
		log.Fatal(err)
	}
	addr := w.GetChangeAddress()
	acc := w.GetAccount(addr)
	err = acc.Decrypt(walletPass, w.Scrypt)
	if err != nil {
		log.Fatal(err)
	}
	signer := user.NewAutoIDSigner(acc.PrivateKey().PrivateKey)

	// Create and configure client
	var prmInit client.PrmInit
	c, err := client.New(prmInit)
	if err != nil {
		log.Fatal(fmt.Errorf("client init: %w", err))
	}

	// Connect to NeoFS node
	var prmDial client.PrmDial
	prmDial.SetServerURI(testnetStorageNode)
	// Optional settings
	prmDial.SetTimeout(15 * time.Second)
	prmDial.SetStreamTimeout(15 * time.Second)

	if err = c.Dial(prmDial); err != nil {
		log.Fatal(fmt.Errorf("dial: %w", err))
	}

	// Parse container ID from string
	containerID, err := cid.DecodeString(cnrIDStr)
	if err != nil {
		log.Fatal(fmt.Errorf("parse container ID: %w", err))
	}

	// Create object header with required fields
	var obj = object.New(containerID, signer.UserID())

	// Optional: set custom attributes
	obj.SetAttributes(
		object.NewAttribute(object.AttributeFileName, "example.txt"),
		object.NewAttribute(object.AttributeFilePath, "path/to/example.txt"),
		object.NewAttribute("ContentType", "text/plain"),
	)

	// We need to create a session to authorize the upload
	// Get current epoch time
	ni, err := c.NetworkInfo(ctx, client.PrmNetworkInfo{})
	if err != nil {
		log.Fatal(fmt.Errorf("get current epoch: %w", err))
	}

	currEpoch := ni.CurrentEpoch()
	expireAt := currEpoch + 10 // session valid for 10 epochs

	// Create session for the upload
	var prmSession client.PrmSessionCreate
	prmSession.SetExp(expireAt)
	res, err := c.SessionCreate(ctx, signer, prmSession)
	if err != nil {
		log.Fatal(fmt.Errorf("create session: %w", err))
	}

	var keySession neofsecdsa.PublicKey
	err = keySession.Decode(res.PublicKey())
	if err != nil {
		log.Fatal(fmt.Errorf("decode public session key: %w", err))
	}

	var idSession uuid.UUID
	err = idSession.UnmarshalBinary(res.ID())
	if err != nil {
		log.Fatal(fmt.Errorf("decode session ID: %w", err))
	}

	// Fill session parameters
	var sessionToken session.Object
	sessionToken.SetID(idSession)
	sessionToken.SetNbf(currEpoch)
	sessionToken.SetIat(currEpoch)
	sessionToken.SetExp(expireAt)
	sessionToken.SetAuthKey(&keySession)

	sessionToken.BindContainer(containerID)
	sessionToken.ForVerb(session.VerbObjectPut)
	// Sign the session token with the user's key
	err = sessionToken.Sign(signer)
	if err != nil {
		log.Fatal(fmt.Errorf("sign session token: %w", err))
	}

	// Configure put parameters
	var prm client.PrmObjectPutInit
	prm.WithinSession(sessionToken)

	// Initiate object upload
	writer, err := c.ObjectPutInit(ctx, *obj, signer, prm)
	if err != nil {
		log.Fatal(fmt.Errorf("init object put: %w", err))
	}

	// Write the payload data
	payload := []byte("Hello, NeoFS!")
	_, err = writer.Write(payload)
	if err != nil {
		_ = writer.Close()
		log.Fatal(fmt.Errorf("write payload: %w", err))
	}

	// Close the writer to finalize the upload
	if err = writer.Close(); err != nil {
		log.Fatal(fmt.Errorf("close writer: %w", err))
	}

	// Get the stored object ID
	objectID := writer.GetResult().StoredObjectID()
	fmt.Printf("Successfully uploaded object with ID: %s\n", objectID)
	// Example output: Successfully uploaded object with ID: 7sTMgE8MzpyvqwLh6EJUXdoPJJyMRRRNHyTx2ErvjgNX
}

Output:

func (*Client) ObjectSearchInit ¶

func (c *Client) ObjectSearchInit(ctx context.Context, containerID cid.ID, signer user.Signer, prm PrmObjectSearch) (*ObjectListReader, error)

ObjectSearchInit initiates object selection through a remote server using NeoFS API protocol.

The call only opens the transmission channel, explicit fetching of matched objects is done using the ObjectListReader. Exactly one return value is non-nil. Resulting reader 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. If signer implements neofscrypto.SignerV2, signing is done using it. In this case, neofscrypto.Signer methods are not called. neofscrypto.OverlapSigner may be used to pass neofscrypto.SignerV2 when neofscrypto.Signer is unimplemented.

Return errors:

• ErrMissingSigner

func (*Client) RemoveContainerAttribute ¶

func (c *Client) RemoveContainerAttribute(ctx context.Context, prm RemoveContainerAttributeParameters, prmSig neofscrypto.Signature, opts RemoveContainerAttributeOptions) error

RemoveContainerAttribute removes container attribute.

If container does not have the attribute, server does nothing and responds without an error.

[RemoveContainerAttributeParameters.ValidUntil] must not yet pass.

[RemoveContainerAttributeParameters.Attribute] must be one of:

• CORS
• __NEOFS__LOCK_UNTIL
• S3_TAGS
• S3_SETTINGS
• S3_NOTIFICATIONS

Attribute-specific requirements:

• __NEOFS__LOCK_UNTIL: current timestamp must have already passed if any

The prmSig must be a signature of prm in either neofscrypto.N3 or neofscrypto.ECDSA_DETERMINISTIC_SHA256 scheme (using SignRemoveContainerAttributeParameters for example). It must be either container owner's or session subject's signature when using RemoveContainerAttributeOptions.AttachSessionToken (RemoveContainerAttributeOptions.AttachSessionTokenV1). If session is used, the token must be issued by the container owner and include [RemoveContainerAttributeParameters.ID] + sessionv2.VerbContainerRemoveAttribute (session.VerbContainerRemoveAttribute) context.

Operation is async/await. Deadline is determined from ctx. If ctx has no deadline, server waits 15s after submitting the transaction. On timeout, apistatus.ErrContainerAwaitTimeout is returned. This error indicates a delay in transaction execution, meaning the operation may still succeed. If necessary, caller can continue the wait via Client.ContainerGet. It is recommended to always use context with timeout. Note that the context includes all processing stages incl. network delays.

func (*Client) ReplicateObject ¶

func (c *Client) ReplicateObject(ctx context.Context, id oid.ID, src io.ReadSeeker, signer neofscrypto.Signer, signedReplication bool) (*neofscrypto.Signature, error)

ReplicateObject copies binary-encoded NeoFS object from the given io.ReadSeeker to remote server for local storage. The signer must authenticate a storage node that matches the object's storage policy. Since this property can change over NeoFS system time, compliance with the policy is checked back to foreseeable moment in the past. The server must be a storage node compliant with the current object's storage policy. ID must be the same as in src.

ReplicateObject is intended for maintaining data storage by NeoFS system nodes only, not for regular use.

If signedReplication, client requests server to sign replicated object information to ensure replication was successful. Signature is returned (nil if not requested).

Object must be encoded in compliance with Protocol Buffers v3 format in ascending order of fields.

Source io.ReadSeeker must point to the start. Note that ReplicateObject does not reset src to start after the call. If it is needed, do not forget to Seek.

See also DemuxReplicatedObject.

Return errors:

• apistatus.ErrServerInternal: internal server error described in the text message;
• apistatus.ErrObjectAccessDenied: the signer does not authenticate any NeoFS storage node matching storage policy of the container referenced by the replicated object;
• apistatus.ErrContainerNotFound: the container to which the replicated object is associated was not found.

func (*Client) SearchObjects ¶

func (c *Client) SearchObjects(ctx context.Context, cnr cid.ID, filters object.SearchFilters, attrs []string, cursor string,
	signer neofscrypto.Signer, opts SearchObjectsOptions) ([]SearchResultItem, string, error)

SearchObjects selects objects from a given container by applying specified filters, collects values of requested attributes, and returns the sorted result. SearchObjects also returns an opaque continuation cursor: when passed to a repeat call, it specifies where to continue the operation from. To start a new search, pass an empty cursor.

The result is sorted lexicographically by the first attribute, then by object ID. When the first filter is an integer, numeric comparison is used. System attributes can be included using special aliases like object.FilterPayloadSize.

The maximum number of filters is 8. The maximum number of attributes is 8. If attributes are specified, the first filter must correspond to the first attribute. Neither filters nor attributes may contain object.FilterContainerID or object.FilterID. Filters using object.FilterRoot and object.FilterPhysical must have zero value and matcher.

If the signer implements neofscrypto.SignerV2, signing is performed using it. In this case, neofscrypto.Signer methods are not invoked. neofscrypto.OverlapSigner can be used to pass neofscrypto.SignerV2 when neofscrypto.Signer is unimplemented.

Note that if a requested attribute is missing in the matching object, the corresponding element in its [SearchResultItem.Attributes] is empty.

func (*Client) SessionCreate ¶

func (c *Client) SessionCreate(ctx context.Context, signer user.Signer, prm PrmSessionCreate) (*ResSessionCreate, error)

SessionCreate opens a session with the node server on the remote endpoint. The session lifetime coincides with the server lifetime. Results can be written to session token which can be later attached to the requests.

Any errors (local or remote, including returned status codes) are returned as Go errors, see apistatus package for NeoFS-specific error types.

Context is required and must not be nil. It is used for network communication.

Signer is required and must not be nil. The account will be used as owner of new session.

Return errors:

• ErrMissingSigner

package main

import (
	"context"
	"crypto/ecdsa"
	"crypto/elliptic"
	"crypto/rand"

	"github.com/google/uuid"
	"github.com/nspcc-dev/neofs-sdk-go/client"

	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"

	neofsecdsa "github.com/nspcc-dev/neofs-sdk-go/crypto/ecdsa"
	"github.com/nspcc-dev/neofs-sdk-go/session"
	"github.com/nspcc-dev/neofs-sdk-go/user"
)

func main() {
	// import "github.com/google/uuid"

	var prmInit client.PrmInit
	// ...
	c, _ := client.New(prmInit)

	// Epoch when session will expire.
	// Note that expiration starts since exp+1 epoch.
	// For instance, now you have 8 epoch. You set exp=10. The session will be still valid during 10th epoch.
	// Expiration starts since 11 epoch.
	var exp uint64
	var prm client.PrmSessionCreate
	prm.SetExp(exp)

	// The key is generated to simplify the example, in reality it's likely to come from configuration/wallet.
	pk, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
	signer := user.NewAutoIDSignerRFC6979(*pk)

	res, _ := c.SessionCreate(context.Background(), signer, prm)

	var id uuid.UUID
	_ = id.UnmarshalBinary(res.ID())

	// Public key for separate private key, which was created inside node for this session.
	var key neofsecdsa.PublicKey
	_ = key.Decode(res.PublicKey())

	// Fill session parameters
	var sessionObject session.Object
	sessionObject.SetID(id)
	sessionObject.SetAuthKey(&key)
	sessionObject.SetExp(exp)

	// Attach verb and container. Session allows to do just one action by time. In this example it is a VerbObjectPut.
	// If you need Get, Delete, etc you should create another session.
	sessionObject.ForVerb(session.VerbObjectPut)
	// Session works only with one container.
	sessionObject.BindContainer(cid.ID{})

	// Finally, token must be signed by container owner or someone who allowed to do the Verb action. In our example
	// it is VerbObjectPut.
	_ = sessionObject.Sign(signer)

	// ...

	// This token will be used in object put operation
	var prmPut client.PrmObjectPutInit
	prmPut.WithinSession(sessionObject)
	// ...
}

Output:

func (*Client) SetContainerAttribute ¶

func (c *Client) SetContainerAttribute(ctx context.Context, prm SetContainerAttributeParameters, prmSig neofscrypto.Signature, opts SetContainerAttributeOptions) error

SetContainerAttribute sets container attribute.

If container does not have the attribute, it is added. Otherwise, its value is swapped.

[SetContainerAttributeParameters.ValidUntil] must not yet pass.

[SetContainerAttributeParameters.Attribute] must be one of:

• CORS
• __NEOFS__LOCK_UNTIL
• S3_TAGS
• S3_SETTINGS
• S3_NOTIFICATIONS

In general, requirements for [SetContainerAttributeParameters.Value] are the same as for container creation. Attribute-specific requirements:

• __NEOFS__LOCK_UNTIL: new timestamp must be after the current one if any
• S3_TAGS: must be a valid JSON object
• S3_SETTINGS: must be a valid JSON object
• S3_NOTIFICATIONS: must be a valid JSON object

The prmSig must be a signature of prm in either neofscrypto.N3 or neofscrypto.ECDSA_DETERMINISTIC_SHA256 scheme (using SignSetContainerAttributeParameters for example). It must be either container owner's or session subject's signature when using SetContainerAttributeOptions.AttachSessionToken (SetContainerAttributeOptions.AttachSessionTokenV1). If session is used, the token must be issued by the container owner and include [SetContainerAttributeParameters.ID] + sessionv2.VerbContainerSetAttribute (session.VerbContainerSetAttribute) context.

Operation is async/await. Deadline is determined from ctx. If ctx has no deadline, server waits 15s after submitting the transaction. On timeout, apistatus.ErrContainerAwaitTimeout is returned. This error indicates a delay in transaction execution, meaning the operation may still succeed. If necessary, caller can continue the wait via Client.ContainerGet. It is recommended to always use context with timeout. Note that the context includes all processing stages incl. network delays.

func (*DefaultObjectWriter) Close ¶

func (x *DefaultObjectWriter) Close() error

Close ends writing the object and returns the result of the operation along with the final results. Must be called after using the DefaultObjectWriter.

Exactly one return value is non-nil. By default, server status is returned in res structure. 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)
• apistatus.ErrContainerNotFound
• apistatus.ErrIncomplete
• apistatus.ErrObjectAccessDenied
• apistatus.ErrObjectLocked
• apistatus.ErrLockNonRegularObject
• apistatus.ErrQuotaExceeded
• apistatus.ErrSessionTokenNotFound
• apistatus.ErrSessionTokenExpired

func (*DefaultObjectWriter) GetResult ¶

func (x *DefaultObjectWriter) GetResult() ResObjectPut

GetResult returns the put operation result.

func (*DefaultObjectWriter) Write ¶

func (x *DefaultObjectWriter) Write(chunk []byte) (n int, err error)

WritePayloadChunk writes chunk of the object payload. Result means success. Failure reason can be received via DefaultObjectWriter.Close.

func (MissingResponseFieldErr) Error ¶

func (e MissingResponseFieldErr) Error() string

Error implements the error interface.

func (MissingResponseFieldErr) Is ¶

func (e MissingResponseFieldErr) Is(target error) bool

Is implements interface for correct checking current error type with errors.Is.

func (*ObjectListReader) Close ¶

func (x *ObjectListReader) Close() error

Close ends reading list of the matched objects and returns the result of the operation along with the final results. Must be called after using the ObjectListReader.

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)
• apistatus.ErrContainerNotFound
• apistatus.ErrIncomplete
• apistatus.ErrObjectAccessDenied
• apistatus.ErrSessionTokenExpired

func (*ObjectListReader) Iterate ¶

func (x *ObjectListReader) Iterate(f func(oid.ID) bool) error

Iterate iterates over the list of found object identifiers. f can return true to stop iteration earlier.

Returns an error if object can't be read.

func (*ObjectListReader) Read ¶

func (x *ObjectListReader) Read(buf []oid.ID) (int, error)

Read reads another list of the object identifiers. Works similar to io.Reader.Read but copies oid.ID.

Failure reason can be received via Close.

Panics if buf has zero length.

func (*ObjectRangeReader) Close ¶

func (x *ObjectRangeReader) Close() error

Close ends reading the payload range and returns the result of the operation along with the final results. Must be called after using the ObjectRangeReader.

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 PrmObjectRange.MakeRaw)
• apistatus.ErrContainerNotFound
• apistatus.ErrObjectNotFound
• apistatus.ErrObjectAccessDenied
• apistatus.ErrObjectAlreadyRemoved
• apistatus.ErrObjectOutOfRange
• apistatus.ErrSessionTokenExpired

func (*ObjectRangeReader) Read ¶

func (x *ObjectRangeReader) Read(p []byte) (int, error)

Read implements io.Reader of the object payload.

func (*ObjectRangeReader) WriteTo ¶

func (x *ObjectRangeReader) WriteTo(w io.Writer) (int64, error)

WriteTo writes the remaining payload range to w. It implements io.WriterTo and streams chunks without an intermediate read buffer.

func (*PayloadReader) Close ¶

func (x *PayloadReader) Close() error

Close ends reading the object payload. Must be called after using the PayloadReader.

func (*PayloadReader) Read ¶

func (x *PayloadReader) Read(p []byte) (int, error)

Read implements io.Reader of the object payload.

func (*PayloadReader) WriteTo ¶

func (x *PayloadReader) WriteTo(w io.Writer) (int64, error)

WriteTo writes the remaining object payload to w. It implements io.WriterTo and streams chunks without an intermediate read buffer.

func (*PrmAnnounceIntermediateTrust) SetIteration ¶

func (x *PrmAnnounceIntermediateTrust) SetIteration(iter uint32)

SetIteration sets current sequence number of the client's calculation algorithm. By default, corresponds to initial (zero) iteration.

func (*PrmAnnounceIntermediateTrust) WithXHeaders ¶

func (x *PrmAnnounceIntermediateTrust) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmAnnounceLocalTrust) WithXHeaders ¶

func (x *PrmAnnounceLocalTrust) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmBalanceGet) SetAccount ¶

func (x *PrmBalanceGet) SetAccount(id user.ID)

SetAccount sets identifier of the NeoFS account for which the balance is requested. Required parameter.

func (*PrmBalanceGet) WithXHeaders ¶

func (x *PrmBalanceGet) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmContainerDelete) AttachSignature ¶

func (x *PrmContainerDelete) AttachSignature(sig neofscrypto.Signature)

AttachSignature allows to attach pre-calculated container ID signature and free Client.ContainerDelete from the calculation. The sig must have neofscrypto.ECDSA_DETERMINISTIC_SHA256 scheme.

func (*PrmContainerDelete) WithXHeaders ¶

func (x *PrmContainerDelete) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmContainerDelete) WithinSession ¶

func (x *PrmContainerDelete) WithinSession(tok session.Container)

WithinSession specifies session within which container should be removed.

Creator of the session acquires the authorship of the request. This may affect the execution of an operation (e.g. access control).

Must be signed. MUST NOT be used together with WithinSessionV2.

func (*PrmContainerDelete) WithinSessionV2 ¶

func (x *PrmContainerDelete) WithinSessionV2(tok sessionv2.Token)

WithinSessionV2 specifies session token V2 within which container should be removed.

Creator of the session acquires the authorship of the request. This may affect the execution of an operation (e.g. access control).

V2 tokens support multiple subjects, delegation chains, and unified contexts.

Must be signed. MUST NOT be used together with WithinSession.

func (*PrmContainerEACL) WithXHeaders ¶

func (x *PrmContainerEACL) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmContainerGet) WithXHeaders ¶

func (x *PrmContainerGet) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmContainerList) WithXHeaders ¶

func (x *PrmContainerList) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmContainerPut) AttachSignature ¶

func (x *PrmContainerPut) AttachSignature(sig neofscrypto.Signature)

AttachSignature allows to attach pre-calculated container signature and free Client.ContainerPut from the calculation. The sig must have neofscrypto.ECDSA_DETERMINISTIC_SHA256 scheme.

func (*PrmContainerPut) WithXHeaders ¶

func (x *PrmContainerPut) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmContainerPut) WithinSession ¶

func (x *PrmContainerPut) WithinSession(s session.Container)

WithinSession specifies session within which container should be saved.

Creator of the session acquires the authorship of the request. This affects the execution of an operation (e.g. access control).

Session is optional, if set the following requirements apply:

• session operation MUST be session.VerbContainerPut (ForVerb)
• token MUST be signed using private signer of the owner of the container to be saved
• MUST NOT be used together with WithinSessionV2

func (*PrmContainerPut) WithinSessionV2 ¶

func (x *PrmContainerPut) WithinSessionV2(s sessionv2.Token)

WithinSessionV2 specifies session token V2 within which container should be saved.

Creator of the session acquires the authorship of the request. This affects the execution of an operation (e.g. access control).

V2 tokens support multiple subjects, delegation chains, and unified contexts.

Must be signed. MUST NOT be used together with WithinSession.

func (*PrmContainerSetEACL) AttachSignature ¶

func (x *PrmContainerSetEACL) AttachSignature(sig neofscrypto.Signature)

AttachSignature allows to attach pre-calculated eACL signature and free Client.ContainerSetEACL from the calculation. The sig must have neofscrypto.ECDSA_DETERMINISTIC_SHA256 scheme.

func (*PrmContainerSetEACL) WithXHeaders ¶

func (x *PrmContainerSetEACL) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmContainerSetEACL) WithinSession ¶

func (x *PrmContainerSetEACL) WithinSession(s session.Container)

WithinSession specifies session within which extended ACL of the container should be saved.

Creator of the session acquires the authorship of the request. This affects the execution of an operation (e.g. access control).

Session is optional, if set the following requirements apply:

• if particular container is specified (ApplyOnlyTo), it MUST equal the container for which extended ACL is going to be set
• session operation MUST be session.VerbContainerSetEACL (ForVerb)
• token MUST be signed using private signer of the owner of the container to be saved
• MUST NOT be used together with WithinSessionV2

func (*PrmContainerSetEACL) WithinSessionV2 ¶

func (x *PrmContainerSetEACL) WithinSessionV2(s sessionv2.Token)

WithinSessionV2 specifies session token V2 within which extended ACL of the container should be saved. Creator of the session acquires the authorship of the request. This affects the execution of an operation (e.g. access control).

V2 tokens support multiple subjects, delegation chains, and unified contexts.

Must be signed. MUST NOT be used together with WithinSession.

func (*PrmDial) SetContext ¶

func (x *PrmDial) SetContext(ctx context.Context)

SetContext allows to specify optional base context within which connection should be established.

Context SHOULD NOT be nil.

func (*PrmDial) SetServerURI ¶

func (x *PrmDial) SetServerURI(endpoint string)

SetServerURI sets server URI in the NeoFS network. Required parameter.

Format of the URI:

[scheme://]host:port

Supported schemes:

grpc
grpcs

See also SetTLSConfig.

func (*PrmDial) SetStreamTimeout ¶

func (x *PrmDial) SetStreamTimeout(timeout time.Duration)

SetStreamTimeout sets the timeout for individual operations in streaming RPC. MUST BE positive. If not called, 10s timeout will be used by default.

func (*PrmDial) SetTLSConfig ¶

func (x *PrmDial) SetTLSConfig(tlsConfig *tls.Config)

SetTLSConfig sets tls.Config to open TLS client connection to the NeoFS server. Nil (default) means insecure connection.

See also SetServerURI.

func (*PrmDial) SetTimeout ¶

func (x *PrmDial) SetTimeout(timeout time.Duration)

SetTimeout sets the timeout for connection to be established. MUST BE positive. If not called, 5s timeout will be used by default.

func (*PrmEndpointInfo) WithXHeaders ¶

func (x *PrmEndpointInfo) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmInit) SetResponseInfoCallback ¶

func (x *PrmInit) SetResponseInfoCallback(f func(ResponseMetaInfo) error)

SetResponseInfoCallback makes the Client to pass ResponseMetaInfo from each NeoFS server response to f. Nil (default) means ignore response meta info.

func (*PrmInit) SetSignMessageBufferSizes ¶

func (x *PrmInit) SetSignMessageBufferSizes(size uint64)

SetSignMessageBufferSizes sets single buffer size to the buffers pool inside client. This pool are using in GRPC message signing process and helps to reduce memory allocations.

func (*PrmInit) SetSignMessageBuffers ¶

func (x *PrmInit) SetSignMessageBuffers(buffers *sync.Pool)

SetSignMessageBuffers sets buffers which are using in GRPC message signing process and helps to reduce memory allocations.

func (*PrmInit) SetStatisticCallback ¶

func (x *PrmInit) SetStatisticCallback(statisticCallback stat.OperationCallback)

SetStatisticCallback makes the Client to pass stat.OperationCallback for the external statistic.

func (*PrmNetworkInfo) WithXHeaders ¶

func (x *PrmNetworkInfo) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmObjectDelete) GetSession ¶

func (x *PrmObjectDelete) GetSession() (*session.Object, error)

GetSession returns session object.

Returns:

• ErrNoSession err if session wasn't set.
• ErrNoSessionExplicitly if IgnoreSession was used.

func (*PrmObjectDelete) GetSessionV2 ¶

func (x *PrmObjectDelete) GetSessionV2() (*sessionv2.Token, error)

GetSessionV2 returns session token V2.

Returns:

• ErrNoSession err if session wasn't set.
• ErrNoSessionExplicitly if IgnoreSession was used.

func (*PrmObjectDelete) IgnoreSession ¶

func (x *PrmObjectDelete) IgnoreSession()

IgnoreSession disables auto-session creation.

See also WithinSession.

func (*PrmObjectDelete) WithBearerToken ¶

func (x *PrmObjectDelete) WithBearerToken(t bearer.Token)

WithBearerToken attaches bearer token to be used for the operation.

If set, underlying eACL rules will be used in access control.

Must be signed.

func (*PrmObjectDelete) WithXHeaders ¶

func (x *PrmObjectDelete) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmObjectDelete) WithinSession ¶

func (x *PrmObjectDelete) WithinSession(t session.Object)

WithinSession specifies session within which the query must be executed.

Creator of the session acquires the authorship of the request. This may affect the execution of an operation (e.g. access control).

See also IgnoreSession.

Must be signed. MUST NOT be used together with WithinSessionV2.

func (*PrmObjectDelete) WithinSessionV2 ¶

func (x *PrmObjectDelete) WithinSessionV2(t sessionv2.Token)

WithinSessionV2 specifies session token V2 within which the query must be executed.

Creator of the session acquires the authorship of the request. This may affect the execution of an operation (e.g. access control).

V2 tokens support multiple subjects, delegation chains, and unified contexts.

See also WithinSession, IgnoreSession.

Must be signed. MUST NOT be used together with WithinSession.

func (*PrmObjectGet) MarkLocal ¶

func (x *PrmObjectGet) MarkLocal()

MarkLocal tells the server to execute the operation locally.

func (*PrmObjectGet) MarkPayloadOnly ¶

func (x *PrmObjectGet) MarkPayloadOnly()

MarkPayloadOnly requests payload without an object header.

func (*PrmObjectGet) MarkRaw ¶

func (x *PrmObjectGet) MarkRaw()

MarkRaw marks an intent to read physically stored object.

func (*PrmObjectGet) SetRange ¶

func (x *PrmObjectGet) SetRange(offset, length uint64)

SetRange requests only a byte range of the payload.

To request the full payload, leave the range unset or pass both offset and length as zero. Otherwise, length must not be zero.

func (*PrmObjectGet) SkipChecksumVerification ¶

func (x *PrmObjectGet) SkipChecksumVerification()

SkipChecksumVerification allows to skip verification of received header against object ID and payload against its in-header checksum.

func (*PrmObjectGet) WithBearerToken ¶

func (x *PrmObjectGet) WithBearerToken(t bearer.Token)

WithBearerToken attaches bearer token to be used for the operation.

If set, underlying eACL rules will be used in access control.

Must be signed.

func (*PrmObjectHash) GetSession ¶

func (x *PrmObjectHash) GetSession() (*session.Object, error)

GetSession returns session object.

Returns:

• ErrNoSession err if session wasn't set.
• ErrNoSessionExplicitly if IgnoreSession was used.

func (*PrmObjectHash) GetSessionV2 ¶

func (x *PrmObjectHash) GetSessionV2() (*sessionv2.Token, error)

GetSessionV2 returns session token V2.

Returns:

• ErrNoSession err if session wasn't set.
• ErrNoSessionExplicitly if IgnoreSession was used.

func (*PrmObjectHash) IgnoreSession ¶

func (x *PrmObjectHash) IgnoreSession()

IgnoreSession disables auto-session creation.

See also WithinSession.

func (*PrmObjectHash) MarkLocal ¶

func (x *PrmObjectHash) MarkLocal()

MarkLocal tells the server to execute the operation locally.

func (*PrmObjectHash) SetRangeList ¶

func (x *PrmObjectHash) SetRangeList(r ...uint64)

SetRangeList sets list of ranges in (offset, length) pair format. Required parameter.

If passed as slice, then it must not be mutated before the operation completes.

func (*PrmObjectHash) UseSalt ¶

func (x *PrmObjectHash) UseSalt(salt []byte)

UseSalt sets the salt to XOR the data range before hashing.

Must not be mutated before the operation completes.

func (*PrmObjectHash) WithBearerToken ¶

func (x *PrmObjectHash) WithBearerToken(t bearer.Token)

WithBearerToken attaches bearer token to be used for the operation.

If set, underlying eACL rules will be used in access control.

Must be signed.

func (*PrmObjectHash) WithXHeaders ¶

func (x *PrmObjectHash) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmObjectHash) WithinSession ¶

func (x *PrmObjectHash) WithinSession(t session.Object)

WithinSession specifies session within which the query must be executed.

Creator of the session acquires the authorship of the request. This may affect the execution of an operation (e.g. access control).

See also IgnoreSession.

Must be signed. MUST NOT be used together with WithinSessionV2.

func (*PrmObjectHash) WithinSessionV2 ¶

func (x *PrmObjectHash) WithinSessionV2(t sessionv2.Token)

WithinSessionV2 specifies session token V2 within which the query must be executed.

Creator of the session acquires the authorship of the request. This may affect the execution of an operation (e.g. access control).

V2 tokens support multiple subjects, delegation chains, and unified contexts.

See also WithinSession, IgnoreSession.

Must be signed. MUST NOT be used together with WithinSession.

func (*PrmObjectHead) MarkLocal ¶

func (x *PrmObjectHead) MarkLocal()

MarkLocal tells the server to execute the operation locally.

func (*PrmObjectHead) MarkRaw ¶

func (x *PrmObjectHead) MarkRaw()

MarkRaw marks an intent to read physically stored object.

func (*PrmObjectHead) SkipChecksumVerification ¶

func (x *PrmObjectHead) SkipChecksumVerification()

SkipChecksumVerification allows to skip verification of received header against object ID.

func (*PrmObjectHead) WithBearerToken ¶

func (x *PrmObjectHead) WithBearerToken(t bearer.Token)

WithBearerToken attaches bearer token to be used for the operation.

If set, underlying eACL rules will be used in access control.

Must be signed.

func (*PrmObjectPutInit) GetSession ¶

func (x *PrmObjectPutInit) GetSession() (*session.Object, error)

GetSession returns session object.

Returns:

• ErrNoSession err if session wasn't set.
• ErrNoSessionExplicitly if IgnoreSession was used.

func (*PrmObjectPutInit) GetSessionV2 ¶

func (x *PrmObjectPutInit) GetSessionV2() (*sessionv2.Token, error)

GetSessionV2 returns session token V2.

Returns:

• ErrNoSession err if session wasn't set.
• ErrNoSessionExplicitly if IgnoreSession was used.

func (*PrmObjectPutInit) IgnoreSession ¶

func (x *PrmObjectPutInit) IgnoreSession()

IgnoreSession disables auto-session creation.

See also WithinSession.

func (*PrmObjectPutInit) MarkLocal ¶

func (x *PrmObjectPutInit) MarkLocal()

MarkLocal tells the server to execute the operation locally.

func (*PrmObjectPutInit) WithBearerToken ¶

func (x *PrmObjectPutInit) WithBearerToken(t bearer.Token)

WithBearerToken attaches bearer token to be used for the operation. Should be called once before any writing steps.

func (*PrmObjectPutInit) WithXHeaders ¶

func (x *PrmObjectPutInit) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmObjectPutInit) WithinSession ¶

func (x *PrmObjectPutInit) WithinSession(t session.Object)

WithinSession specifies session within which the query must be executed.

Creator of the session acquires the authorship of the request. This may affect the execution of an operation (e.g. access control).

See also IgnoreSession.

Must be signed. MUST NOT be used together with WithinSessionV2.

func (*PrmObjectPutInit) WithinSessionV2 ¶

func (x *PrmObjectPutInit) WithinSessionV2(t sessionv2.Token)

WithinSessionV2 specifies session token V2 within which the query must be executed.

Creator of the session acquires the authorship of the request. This may affect the execution of an operation (e.g. access control).

V2 tokens support multiple subjects, delegation chains, and unified contexts.

See also WithinSession, IgnoreSession.

Must be signed. MUST NOT be used together with WithinSession.

func (*PrmObjectRange) MarkLocal ¶

func (x *PrmObjectRange) MarkLocal()

MarkLocal tells the server to execute the operation locally.

func (*PrmObjectRange) MarkRaw ¶

func (x *PrmObjectRange) MarkRaw()

MarkRaw marks an intent to read physically stored object.

func (*PrmObjectRange) WithBearerToken ¶

func (x *PrmObjectRange) WithBearerToken(t bearer.Token)

WithBearerToken attaches bearer token to be used for the operation.

If set, underlying eACL rules will be used in access control.

Must be signed.

func (*PrmObjectSearch) GetSession ¶

func (x *PrmObjectSearch) GetSession() (*session.Object, error)

GetSession returns session object.

Returns:

• ErrNoSession err if session wasn't set.
• ErrNoSessionExplicitly if IgnoreSession was used.

func (*PrmObjectSearch) GetSessionV2 ¶

func (x *PrmObjectSearch) GetSessionV2() (*sessionv2.Token, error)

GetSessionV2 returns session token V2.

Returns:

• ErrNoSession err if session wasn't set.
• ErrNoSessionExplicitly if IgnoreSession was used.

func (*PrmObjectSearch) IgnoreSession ¶

func (x *PrmObjectSearch) IgnoreSession()

IgnoreSession disables auto-session creation.

See also WithinSession.

func (*PrmObjectSearch) MarkLocal ¶

func (x *PrmObjectSearch) MarkLocal()

MarkLocal tells the server to execute the operation locally.

func (*PrmObjectSearch) SetFilters ¶

func (x *PrmObjectSearch) SetFilters(filters object.SearchFilters)

SetFilters sets filters by which to select objects. All container objects match unset/empty filters.

func (*PrmObjectSearch) WithBearerToken ¶

func (x *PrmObjectSearch) WithBearerToken(t bearer.Token)

WithBearerToken attaches bearer token to be used for the operation.

If set, underlying eACL rules will be used in access control.

Must be signed.

func (*PrmObjectSearch) WithXHeaders ¶

func (x *PrmObjectSearch) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*PrmObjectSearch) WithinSession ¶

func (x *PrmObjectSearch) WithinSession(t session.Object)

WithinSession specifies session within which the query must be executed.

Creator of the session acquires the authorship of the request. This may affect the execution of an operation (e.g. access control).

See also IgnoreSession.

Must be signed. MUST NOT be used together with WithinSessionV2.

func (*PrmObjectSearch) WithinSessionV2 ¶

func (x *PrmObjectSearch) WithinSessionV2(t sessionv2.Token)

WithinSessionV2 specifies session token V2 within which the query must be executed.

Creator of the session acquires the authorship of the request. This may affect the execution of an operation (e.g. access control).

V2 tokens support multiple subjects, delegation chains, and unified contexts.

See also WithinSession, IgnoreSession.

Must be signed. MUST NOT be used together with WithinSession.

func (*PrmSessionCreate) SetExp ¶

func (x *PrmSessionCreate) SetExp(exp uint64)

SetExp sets number of the last NepFS epoch in the lifetime of the session after which it will be expired.

func (*PrmSessionCreate) WithXHeaders ¶

func (x *PrmSessionCreate) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*RemoveContainerAttributeOptions) AttachSessionToken ¶

func (x *RemoveContainerAttributeOptions) AttachSessionToken(tok sessionv2.Token)

AttachSessionToken makes client to attach specified session token to the request.

func (*RemoveContainerAttributeOptions) AttachSessionTokenV1 ¶

func (x *RemoveContainerAttributeOptions) AttachSessionTokenV1(tok session.Container)

AttachSessionTokenV1 makes client to attach specified session token V1 to the request. AttachSessionTokenV1 must not be set together with RemoveContainerAttributeOptions.AttachSessionToken that is highly recommended to be used instead.

func (ResEndpointInfo) LatestVersion ¶

func (x ResEndpointInfo) LatestVersion() version.Version

LatestVersion returns latest NeoFS API protocol's version in use.

func (ResEndpointInfo) NodeInfo ¶

func (x ResEndpointInfo) NodeInfo() netmap.NodeInfo

NodeInfo returns information about the NeoFS node served on the remote endpoint.

func (ResObjectPut) StoredObjectID ¶

func (x ResObjectPut) StoredObjectID() oid.ID

StoredObjectID returns identifier of the saved object.

func (ResSessionCreate) ID ¶

func (x ResSessionCreate) ID() []byte

ID returns identifier of the opened session in a binary NeoFS API protocol format.

Client doesn't retain value so modification is safe.

func (ResSessionCreate) PublicKey ¶

func (x ResSessionCreate) PublicKey() []byte

PublicKey returns public key of the opened session in a binary NeoFS API protocol format.

The resulting slice of bytes is a serialized compressed public key. See [elliptic.MarshalCompressed]. Use neofsecdsa.PublicKey.Decode to decode it into a type-specific structure.

The value returned shares memory with the structure itself, so changing it can lead to data corruption. Make a copy if you need to change it.

func (ResponseMetaInfo) Epoch ¶

func (x ResponseMetaInfo) Epoch() uint64

Epoch returns local NeoFS epoch of the server.

func (ResponseMetaInfo) ResponderKey ¶

func (x ResponseMetaInfo) ResponderKey() []byte

ResponderKey returns responder's public key in a binary format.

The resulting slice of bytes is a serialized compressed public key. See [elliptic.MarshalCompressed]. Use neofsecdsa.PublicKey.Decode to decode it into a type-specific structure.

The value returned shares memory with the structure itself, so changing it can lead to data corruption. Make a copy if you need to change it.

func (SearchObjectsOptions) Count ¶

func (x SearchObjectsOptions) Count() uint32

Count returns limit for the search result.

func (*SearchObjectsOptions) DisableForwarding ¶

func (x *SearchObjectsOptions) DisableForwarding()

DisableForwarding disables request forwarding by the server and limits execution to its local storage. Mostly used for system purposes.

func (*SearchObjectsOptions) SetCount ¶

func (x *SearchObjectsOptions) SetCount(count uint32)

SetCount limits the search result to a given number. Must be in [1, client.MaxSearchObjectsCount] range. Defaults to client.MaxSearchObjectsCount.

func (*SearchObjectsOptions) WithBearerToken ¶

func (x *SearchObjectsOptions) WithBearerToken(bt bearer.Token)

WithBearerToken specifies bearer token to attach to the request. The token must be issued by the container owner for the request signer.

func (*SearchObjectsOptions) WithSessionToken ¶

func (x *SearchObjectsOptions) WithSessionToken(st session.Object)

WithSessionToken specifies session token to attach to the request. The token must be issued for the request signer and target the requested container and operation.

func (*SearchObjectsOptions) WithSessionTokenV2 ¶

func (x *SearchObjectsOptions) WithSessionTokenV2(st sessionv2.Token)

WithSessionTokenV2 specifies session token V2 to attach to the request. The token must be issued for the request signer and target the requested container and operation. V2 tokens support multiple subjects, delegation chains, and unified contexts.

func (*SearchObjectsOptions) WithXHeaders ¶

func (x *SearchObjectsOptions) WithXHeaders(hs ...string)

WithXHeaders specifies list of extended headers (string key-value pairs) to be attached to the request. Must have an even length.

Slice must not be mutated until the operation completes.

func (*SetContainerAttributeOptions) AttachSessionToken ¶

func (x *SetContainerAttributeOptions) AttachSessionToken(tok sessionv2.Token)

AttachSessionToken makes client to attach specified session token to the request.

func (*SetContainerAttributeOptions) AttachSessionTokenV1 ¶

func (x *SetContainerAttributeOptions) AttachSessionTokenV1(tok session.Container)

AttachSessionTokenV1 makes client to attach specified session token V1 to the request. AttachSessionTokenV1 must not be set together with SetContainerAttributeOptions.AttachSessionToken that is highly recommended to be used instead.

func (SignError) Error ¶

func (e SignError) Error() string

Error implements the error interface.

func (SignError) Is ¶

func (e SignError) Is(target error) bool

Is implements interface for correct checking current error type with errors.Is.

func (SignError) Unwrap ¶

func (e SignError) Unwrap() error

Unwrap implements the error interface.