Separate type for object header

[cthulhu-rider]

Is your feature request related to a problem? Please describe.

currently, object provides Object structure type, but no Header one. This type would be helpful for HEAD ops (Client, node storage, etc.). Now such ops return instances of the Object type with unset payload field. I see following drawbacks in this approach:

1. header is always requested by object ID, and the resulting instance has the one. This is redundant now
2. header encoding becomes more tricky. This leads to additions like https://pkg.go.dev/github.com/nspcc-dev/neofs-sdk-go/object#Object.MarshalHeaderJSON, which is not rly bad, but could be provided apriori. For binary encoding, https://pkg.go.dev/github.com/nspcc-dev/neofs-sdk-go/object#Object.CutPayload is used, but it adds ID to the result while these BLOBS are usually stored by ID key itself
3. entity appears in the protocol and in different system parts, it is quite natural for it to have a type
4. in code, the header is not distinguished from the object, although it is a narrower type. Because of this, comments have to be added, which weakens the type system

Describe the solution you'd like

type Header struct { /* container, owner, ... */ }
type Object struct {
	Header
	id        oid.ID
	signature neofscrypto.Signature
	payload   []byte
}
func (*Client) HeadObject(...) (object.Header, neofscrypto.Signature, error)

Additional context

iirc @carpawell had questions why there is no header type. I couldnt find any issue, pls share if smth already exists

[carpawell]

I always did not understand why there is no header while IMO it is a natural understanding for our HEAD operation and objects in general: every object has a header and every object has a payload. Sometimes we need only a header and vice versa. I have not opened any issues about it.

[roman-khimov]

Yeah, we need this type, passing object.Object and doing CutPayload() tricks is very confusing, you never know what you have in code: a complete object or header only. But we need it to follow proto spec as well, signature is a part of the header IIRC.

[cthulhu-rider]

signature is not a part of header itself https://github.com/nspcc-dev/neofs-api/blob/e66b25d4bf2afc4472023e1e2c2467f694f5a0e1/object/types.proto#L226, so it's transmitted beside https://github.com/nspcc-dev/neofs-api/blob/e66b25d4bf2afc4472023e1e2c2467f694f5a0e1/object/service.proto#L462

[roman-khimov]

Header, SignedHeader, Object?

[cthulhu-rider]

Header, SignedHeader, Object?

SignedHeader includes ID here?

[roman-khimov]

It's so tempting for me to make it a method with cached internal value (transaction.Transaction). We need to evaluate real use cases, I know we have a number of uses for SignedHeader (maybe even more so than for Header alone).

[cthulhu-rider]

cached values ​​are often a source of errors. I would stick with simple tuples with open logic

real use cases

https://pkg.go.dev/github.com/nspcc-dev/neofs-sdk-go/object#Object.MarshalHeaderJSON is what i remember. https://github.com/nspcc-dev/neo-go/blob/5f92da21fa43e4fe80fb965c78d5d244b6003ffd/pkg/services/oracle/neofs/neofs.go#L185. The getObjHeader could return object.Header

various tuples can be used:

• API HEAD returns https://github.com/nspcc-dev/neofs-api/blob/e66b25d4bf2afc4472023e1e2c2467f694f5a0e1/object/service.proto#L439-L452, no ID
• metastorages store meta info by ID key, so they expect some kind of HeaderWithSignature too

and i remember no usecase where we need (ID, signature, header) tuple

finally, for now i see Header ∈ HeaderWithSignature ∈ Object type system

[cthulhu-rider]

it must be noted that transition to the heading types must be carried out carefully. For example, CutPayload returns an object. So, https://github.com/nspcc-dev/neofs-node/blob/918307b0739feb086416e667497c676170e0c9ca/pkg/local_object_storage/metabase/put.go#L186 means that metabase stores (ID, signature, header) tuples. Not rly good to store storage key in the value, but it is what it is, updated code must take this into account. Normally, metabase could store HeaderWithSignature

ALSO!!!: do not forget about field numbers. Object and HeaderWithSignature have different ones. Field nums are essential for Marshal and any protobuf functionality