How is putFile() supposed to work?

[spazmodius]

OK, the more I read about issues with .putFile(), and documentation or lack thereof, and "do something with res or at least call res.resume()", the less sure I become that I actually know what this method does.

Let me describe what I thought I thought, and you who know better please correct me...

I believed that calling client.putFile(localFilename, s3Filename, cb) would go through the motions of POSTing (streaming) the contents of my file to S3 using their protocol. When this is done, or has failed, it will call my cb. If the underlying mechanisms fail, or S3 denies the request, or responds with something other than success, then my cb receives an appropriate err argument. Otherwise, the file is up there, everything is cleaned up, and the res argument is purely informative if I care.

Significantly, putFile can be promisified.

However, I see many (some old) issues that make me question this mental model. Maybe cb is called earlier than when it's all done? Maybe I need to parse Amazon response bodies? Switch on statuscode? I'm really not sure.

[bmustata]

Some more documentation will be very useful!

[SinisaG]

Is not really like that. It looks like you'll get an error, that is before the request to s3 is issued. After you have to check the response for the error.

e.g.:

if (res.statusCode !== 200) {
   throw new Error("Something was not quite write");
}

I am struggling with this myself currently also and better documentation would for sure be more useful. In any case, thanks to the creators for their work!