added accepted options for etag

[hrvolapeter]

This PR adds funcionality for setting etags, 'weak' 'strong' custom function, without breaking back compatibility.

Needed for expressjs/express#2936

[dougwilson]

You cannot send back a strong ETag without being able to guarantee the bytes will be identical, i.e. you need to at least take a hash of the file contents.

In order for strong Etags to be an option in this module, you need to add this functionality. Please also ensure that it does not buffer the entire file contents into memory, as the files can be quite large.

[dougwilson]

It is not clear what the "data" argument is in the documentation. Please elaborate in the document what this is and what it contains.

[hrvolapeter]

I thought strong etags are properly generated in etag package, but as I see they are not, wouldn't it be better to add it there ?

[dougwilson]

You're only giving the etag package a stat object, which does not contain enough information to generate a strong ETag.

If you want to add strong ETag support, here are the requirements:

1. The ETag must guarantee byte identical responses for the same ETag.
2. Do not read the entire file contents into memory at ant time.
3. Do not read the file contents from disk more than once.

[dougwilson]

Needed for expressjs/express#2936

I think you misunderstand the requirements for that change, because the change does not require any changes to be made to any dependencies.

[hrvolapeter]

Yes, I saw your comment on it. Anyway I think strong etags should be added. So I will first finish expressjs/express#2936 and then take a look at this.

[dougwilson]

Anyway I think strong etags should be added.

I don't agree that it is even worth it. Not even nginx of Apache give you this for files, because a file can be 800MB, and computing a hash can take significant time and resources, providing a very simple path to DoS a server from many repeated file requests.

I'm going to close the pull request, on the grounds for the highlighted issues above. If you are interested in adding strong ETags here, please keep the requirements I highlighted above, and you may want to research pitfalls and the reasons other servers don't do strong ETags for files so you can't take into account all the prior research and implementations that have already been done.