AOS-38: Service Pair Naming Style

[Xuanwo]

Signed-off-by: Xuanwo github@xuanwo.io

[xxchan]

Why this rfc is numbered 38?

[xxchan]

BTW, I am wondering why SSE pairs are considered service pairs, since they are supported by most services (although look different).

So, what kind of feature can be considered global?

[xxchan]

What do you mean by 'language related details'? Do you mean SDKs in different languages? (And so we should follow API, but not SDK)

Regarding this, I also came up with another question about the pair's type. Say, the customer key will be Base-64 encoded string in the header, but gcs's go SDK provides func (*gs.ObjectHandle).Key(encryptionKey []byte) *gs.ObjectHandle. In the header, it's x-goog-encryption-key (base-64 string). Does the more 'API-native' way mean that we should let the user give us base-64 string, and decode it to pass to SDK? But []byte is more convenient, and calculating MD5/SHA-256 also requires the original bytes.

So API Native Style only restricts naming, but not the type/content? Will this cause confusion? (I think it won't. The inconsistent situation won't appear many times, and with type signature and description, the user can easily know what to do... Just like the gcs SDK's choice)

[Xuanwo]

Why this RFC is numbered 38?

Use the PR number as ID as golang and matrix do.

BTW, I am wondering why SSE pairs are considered service pairs since they are supported by most services (although look different).

Because different services may have different behavior on it.

For example, Behavior for Read global pair size and offset are the same for every service, but Write pair StorageClass is different: Depends on service type, the user needs to use different values.

According to SSE supports, the behavior is also very different. S3 supports three types and SSE-KMS requires a KMS key id, other services could not support this pair.

In general, If a pair could be used with no service type check, we can consider adding it into global service, otherwise, we need to keep it as service pair.

// size & offset can be used in any service
_, err = store.Read("abc", pairs.WithSize(1024), pairs.Offset(4096))
// But s3 storage class can only be used in s3's store

var pairs []types.Pair
switch tp {
    case s3.Type:
        pairs = append(pairs, s3.WithStorageClass("STANDARD_IA"))
}
_, err = store.Read(“abc”, pairs...)

What do you mean by 'language-related details'? Do you mean SDKs in different languages? (And so we should follow API, but not SDK)

Yes.

So API Native Style only restricts naming, but not the type/content? Will this cause confusion?

From my point of view, []byte is the real type of this API. Because HTTP headers only allow string, so we have to encode it to base64 like boolean True / False should be "true"/"false". But it doesn't mean we have to set all header-related pairs type to string, this makes it much less easy to use.

So we use the []byte and boolean for pairs type based on their real type.