search

Automattic / knox

S3 Lib
MIT License
1.74k stars 285 forks source link

How is putFile() supposed to work? #313

Open spazmodius opened 8 years ago

spazmodius commented 8 years ago

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 commented 7 years ago

Some more documentation will be very useful!

SinisaG commented 7 years ago

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!