How is putFile() supposed to work?

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.

The issue names putFile() but no file path or test. Start by locating putFile() and tracing its callback and response handling, then review related issues about res and res.resume(). Done means documenting when the callback fires, how failures are reported, and whether callers must consume the response.

Written by the indexing model from the issue text.