feat: allow setting acl on putObject

[Zegnat]

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

Porting some code from @aws-sdk/client-s3 we have a project that uploads both publicly available resources and private resources to a bucket. In our code this is easily managed by providing a pre-defined ACL value directly:

import { PutObjectCommand } from "@aws-sdk/client-s3";
const uploadParams = new PutObjectCommand({
  ACL: "public-read", // ← this part
  Body: [··· Buffer ···],
  Bucket: "my-mixed-bucket",
  ContentType: "text/plain",
  Key: "my-file.txt",
});

Describe the solution you'd like

Just like with the Server-Side Encryption headers, it would be nice to be able to provide an ACL value directly to S3mini#putObject(). Preferably with the same strings supported as in PutObjectCommand.

The official AWS SDK supports strings they call Canned ACLs, predefined permissions. These seem to have some cross-platform support, as we are actually using Ceph ourselves and not S3. There are 6 possible values:

export declare const ObjectCannedACL: {
    readonly authenticated_read: "authenticated-read";
    readonly aws_exec_read: "aws-exec-read";
    readonly bucket_owner_full_control: "bucket-owner-full-control";
    readonly bucket_owner_read: "bucket-owner-read";
    readonly private: "private";
    readonly public_read: "public-read";
    readonly public_read_write: "public-read-write";
};

And these are described in the Amazon S3 documentation.

It looks like the Canned ACL value can be passed directly as an x-amz-acl header.

Describe alternatives you've considered

An alternative solution would be to allow a much more open-ended / generic “headers” argument on the S3mini#putObject-method. But I like how explicit the current class is with what can and cannot be set.

[good-lly]

This idea seems rational - expanding on headers would be ideal to cover all other necessary use cases.

Would you mind creating/sending a PR? I'm currently very busy for the next few weeks, but I can find some time to test and merge it during my after-hours.

[Zegnat]

I can probably put together a simple PR for this. But I cannot currently test it against all the different object storage providers.

What API would you prefer? Should SSECHeaders be expanded?

s3mini/src/types.ts

Lines 11 to 15 in 61688c8

	export interface SSECHeaders {
	'x-amz-server-side-encryption-customer-algorithm': string;
	'x-amz-server-side-encryption-customer-key': string;
	'x-amz-server-side-encryption-customer-key-md5': string;
	}

Or should it be a completely new argument to the S3mini#putObject method?

[good-lly]

hmmm ... can you test it (at least) against Minio / Ceph or something else from the list?

regarding the argument - I am not 100% sure. Intuitively, I would not mess it with SSECHeaders but at the same time I would keep the args more "abstact"/useful ... is it necessary to add add em inside signature hashing as well?

[Zegnat]

hmmm ... can you test it (at least) against Minio / Ceph or something else from the list?

I should be able to test Minio locally. I will be able to test Ceph once I am back from vacation, as we have OpenStack infrastructure with Ceph as our main object storage there. I just do not have access to that right now.

regarding the argument - I am not 100% sure. Intuitively, I would not mess it with SSECHeaders but at the same time I would keep the args more "abstact"/useful ... is it necessary to add add em inside signature hashing as well?

From how I understand creating signed requests all x-amz-* headers should be included as CanonicalHeaders and SignedHeaders? So it sounds like the answer will be yes.

There are so many possible x-amz-* headers that I do not think add separate arguments for each to S3mini#putObject makes too much sense. But I do understand the preference of keeping SSECHeaders separate as it needs to be provided to other methods besides putObject as well.

Maybe a more generic final argument?

type AwsHeaders = { [k: `x-amz-${string}`]: string };