Specify metadata on putObject calls

[apellerano-pw]

I need a way to set metadata on uploaded items. What about an API like this?

s3: {
  accessKeyId: '<your-aws-access-key>',
  secretAccessKey: '<your-aws-secret>',
  bucket: '<your-s3-bucket>',
  region: '<the-region-your-bucket-is-in>',
  metadata: {
    key1: 'foo',
    key2: 'bar',
  },
}

And then _putObject in lib/s3.js can read options.metadata and add to params. Basically a passthru.

var params = {
  ...existingStuff,
  Metadata: metadata
};

It would be up to the end user whether they want to use keyNames that S3 will collapse to x-amz-meta-keynames or key-names to get x-amz-meta-key-names. In other words, this library would have no opinion about how metadata key names should be formatted.

It would also be the end user's responsibility to convert their datatypes to String.

[lukemelia]

I'm open to this idea. One consideration: would we want to support varying the metadata by file? We could make the API something where you provide a function that accepts the file path. e.g.

s3: {
  accessKeyId: '<your-aws-access-key>',
  secretAccessKey: '<your-aws-secret>',
  bucket: '<your-s3-bucket>',
  region: '<the-region-your-bucket-is-in>',
  metadata(path) {
    // conditionally determine metadata based on path, or just return a static hash...
    return {
      key1: 'foo',
      key2: 'bar',
    };
  }
}

[apellerano-pw]

It depends on what use cases there are. You would be able to accomplish that with pipeline aliases, with the filePattern being the conditional branches of the metadata function. But if there was a use case where the metadata is derived from the file path itself, you'd def want the function.

pipeline: {
  alias: {
    s3: { as: ['s3-some-stuff', 's3-other-stuff-with-metadata'] },
},

This alias + filePattern approach works for my needs. I am wanting to smuggle some build-time information (git sha) via metadata onto the release entrypoint that a separate runtime system can read when it promotes that entrypoint. So that promotion moment can be shuttled off to deploy observability tools (and reference the git sha.)

[lukemelia]

Sounds good. We can start with the simpler version then.

[apellerano-pw]

Great, I'll get a PR up!

[apellerano-pw]

@lukemelia #195 is up for review. Also did some light documentation for contributors in #194