pax_global_header00006660000000000000000000000064124076164100014513gustar00rootroot0000000000000052 comment=6b701773b06a102947cc063286e7e3f3bceae27b etag-1.4.0/000077500000000000000000000000001240761641000124355ustar00rootroot00000000000000etag-1.4.0/.gitignore000066400000000000000000000000461240761641000144250ustar00rootroot00000000000000coverage/ node_modules/ npm-debug.log etag-1.4.0/.travis.yml000066400000000000000000000006071240761641000145510ustar00rootroot00000000000000language: node_js node_js: - "0.6" - "0.8" - "0.10" - "0.11" matrix: allow_failures: - node_js: "0.11" fast_finish: true script: - "test $TRAVIS_NODE_VERSION != '0.6' || npm test" - "test $TRAVIS_NODE_VERSION = '0.6' || npm run-script test-travis" after_script: - "test $TRAVIS_NODE_VERSION = '0.10' && npm install coveralls@2 && cat ./coverage/lcov.info | coveralls" etag-1.4.0/HISTORY.md000066400000000000000000000013631240761641000141230ustar00rootroot000000000000001.4.0 / 2014-09-21 ================== * Support "fake" stats objects * Support Node.js 0.6 1.3.1 / 2014-09-14 ================== * Use the (new and improved) `crc` for crc32 1.3.0 / 2014-08-29 ================== * Default strings to strong ETags * Improve speed for weak ETags over 1KB 1.2.1 / 2014-08-29 ================== * Use the (much faster) `buffer-crc32` for crc32 1.2.0 / 2014-08-24 ================== * Add support for file stat objects 1.1.0 / 2014-08-24 ================== * Add fast-path for empty entity * Add weak ETag generation * Shrink size of generated ETags 1.0.1 / 2014-08-24 ================== * Fix behavior of string containing Unicode 1.0.0 / 2014-05-18 ================== * Initial release etag-1.4.0/LICENSE000066400000000000000000000021011240761641000134340ustar00rootroot00000000000000(The MIT License) Copyright (c) 2014 Douglas Christopher Wilson Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. etag-1.4.0/README.md000066400000000000000000000070221240761641000137150ustar00rootroot00000000000000# etag [![NPM Version][npm-image]][npm-url] [![NPM Downloads][downloads-image]][downloads-url] [![Node.js Version][node-version-image]][node-version-url] [![Build Status][travis-image]][travis-url] [![Test Coverage][coveralls-image]][coveralls-url] Create simple ETags ## Installation ```sh $ npm install etag ``` ## API ```js var etag = require('etag') ``` ### etag(entity, [options]) Generate a strong ETag for the given entity. This should be the complete body of the entity. Strings, `Buffer`s, and `fs.Stats` are accepted. By default, a strong ETag is generated except for `fs.Stats`, which will generate a weak ETag (this can be overwritten by `options.weak`). ```js res.setHeader('ETag', etag(body)) ``` #### Options `etag` accepts these properties in the options object. ##### weak Specifies if a "strong" or a "weak" ETag will be generated. The ETag can only really be a strong as the given input. ## Testing ```sh $ npm test ``` ## Benchmark ```bash $ npm run-script bench > etag@1.2.0 bench nodejs-etag > node benchmark/index.js > node benchmark/body0-100b.js 100B body 1 test completed. 2 tests completed. 3 tests completed. 4 tests completed. buffer - strong x 518,895 ops/sec ±1.71% (185 runs sampled) * buffer - weak x 1,917,975 ops/sec ±0.34% (195 runs sampled) string - strong x 245,251 ops/sec ±0.90% (190 runs sampled) string - weak x 442,232 ops/sec ±0.21% (196 runs sampled) > node benchmark/body1-1kb.js 1KB body 1 test completed. 2 tests completed. 3 tests completed. 4 tests completed. buffer - strong x 309,748 ops/sec ±0.99% (191 runs sampled) * buffer - weak x 352,402 ops/sec ±0.20% (198 runs sampled) string - strong x 159,058 ops/sec ±1.83% (191 runs sampled) string - weak x 184,052 ops/sec ±1.30% (189 runs sampled) > node benchmark/body2-5kb.js 5KB body 1 test completed. 2 tests completed. 3 tests completed. 4 tests completed. * buffer - strong x 110,157 ops/sec ±0.60% (194 runs sampled) * buffer - weak x 111,333 ops/sec ±0.67% (194 runs sampled) string - strong x 62,091 ops/sec ±3.92% (186 runs sampled) string - weak x 60,681 ops/sec ±3.98% (186 runs sampled) > node benchmark/body3-10kb.js 10KB body 1 test completed. 2 tests completed. 3 tests completed. 4 tests completed. * buffer - strong x 61,843 ops/sec ±0.44% (197 runs sampled) * buffer - weak x 61,687 ops/sec ±0.52% (197 runs sampled) string - strong x 41,377 ops/sec ±3.33% (189 runs sampled) string - weak x 41,368 ops/sec ±3.29% (190 runs sampled) > node benchmark/body4-100kb.js 100KB body 1 test completed. 2 tests completed. 3 tests completed. 4 tests completed. * buffer - strong x 6,874 ops/sec ±0.17% (198 runs sampled) * buffer - weak x 6,880 ops/sec ±0.15% (198 runs sampled) string - strong x 5,382 ops/sec ±2.17% (192 runs sampled) string - weak x 5,361 ops/sec ±2.23% (192 runs sampled) ``` ## License [MIT](LICENSE) [npm-image]: https://img.shields.io/npm/v/etag.svg?style=flat [npm-url]: https://npmjs.org/package/etag [node-version-image]: https://img.shields.io/node/v/etag.svg?style=flat [node-version-url]: http://nodejs.org/download/ [travis-image]: https://img.shields.io/travis/jshttp/etag.svg?style=flat [travis-url]: https://travis-ci.org/jshttp/etag [coveralls-image]: https://img.shields.io/coveralls/jshttp/etag.svg?style=flat [coveralls-url]: https://coveralls.io/r/jshttp/etag?branch=master [downloads-image]: https://img.shields.io/npm/dm/etag.svg?style=flat [downloads-url]: https://npmjs.org/package/etag etag-1.4.0/benchmark/000077500000000000000000000000001240761641000143675ustar00rootroot00000000000000etag-1.4.0/benchmark/body0-100b.js000066400000000000000000000023121240761641000164000ustar00rootroot00000000000000 /** * Module dependencies. */ var benchmark = require('benchmark') var benchmarks = require('beautify-benchmark') var seedrandom = require('seedrandom') /** * Globals for benchmark.js */ global.buffer = getbuffer(100) global.etag = require('..') global.string = getbuffer(100).toString() var suite = new benchmark.Suite suite.add({ name: 'buffer - strong', minSamples: 100, fn: 'var val = etag(buffer, {weak: false})' }) suite.add({ name: 'buffer - weak', minSamples: 100, fn: 'var val = etag(buffer, {weak: true})' }) suite.add({ name: 'string - strong', minSamples: 100, fn: 'var val = etag(string, {weak: false})' }) suite.add({ name: 'string - weak', minSamples: 100, fn: 'var val = etag(string, {weak: true})' }) suite.on('start', function onCycle(event) { process.stdout.write(' 100B body\n\n') }) suite.on('cycle', function onCycle(event) { benchmarks.add(event.target); }) suite.on('complete', function onComplete() { benchmarks.log(); }) suite.run({async: false}) function getbuffer(size) { var buffer = new Buffer(size) var rng = seedrandom('body ' + size) for (var i = 0; i < buffer.length; i++) { buffer[i] = (rng() * 94 + 32) | 0 } return buffer } etag-1.4.0/benchmark/body1-1kb.js000066400000000000000000000023231240761641000164160ustar00rootroot00000000000000 /** * Module dependencies. */ var benchmark = require('benchmark') var benchmarks = require('beautify-benchmark') var seedrandom = require('seedrandom') /** * Globals for benchmark.js */ global.buffer = getbuffer(1 * 1000) global.etag = require('..') global.string = getbuffer(1 * 1000).toString() var suite = new benchmark.Suite suite.add({ name: 'buffer - strong', minSamples: 100, fn: 'var val = etag(buffer, {weak: false})' }) suite.add({ name: 'buffer - weak', minSamples: 100, fn: 'var val = etag(buffer, {weak: true})' }) suite.add({ name: 'string - strong', minSamples: 100, fn: 'var val = etag(string, {weak: false})' }) suite.add({ name: 'string - weak', minSamples: 100, fn: 'var val = etag(string, {weak: true})' }) suite.on('start', function onCycle(event) { process.stdout.write(' 1KB body\n\n') }) suite.on('cycle', function onCycle(event) { benchmarks.add(event.target); }) suite.on('complete', function onComplete() { benchmarks.log(); }) suite.run({async: false}) function getbuffer(size) { var buffer = new Buffer(size) var rng = seedrandom('body ' + size) for (var i = 0; i < buffer.length; i++) { buffer[i] = (rng() * 94 + 32) | 0 } return buffer } etag-1.4.0/benchmark/body2-5kb.js000066400000000000000000000023231240761641000164230ustar00rootroot00000000000000 /** * Module dependencies. */ var benchmark = require('benchmark') var benchmarks = require('beautify-benchmark') var seedrandom = require('seedrandom') /** * Globals for benchmark.js */ global.buffer = getbuffer(5 * 1000) global.etag = require('..') global.string = getbuffer(5 * 1000).toString() var suite = new benchmark.Suite suite.add({ name: 'buffer - strong', minSamples: 100, fn: 'var val = etag(buffer, {weak: false})' }) suite.add({ name: 'buffer - weak', minSamples: 100, fn: 'var val = etag(buffer, {weak: true})' }) suite.add({ name: 'string - strong', minSamples: 100, fn: 'var val = etag(string, {weak: false})' }) suite.add({ name: 'string - weak', minSamples: 100, fn: 'var val = etag(string, {weak: true})' }) suite.on('start', function onCycle(event) { process.stdout.write(' 5KB body\n\n') }) suite.on('cycle', function onCycle(event) { benchmarks.add(event.target); }) suite.on('complete', function onComplete() { benchmarks.log(); }) suite.run({async: false}) function getbuffer(size) { var buffer = new Buffer(size) var rng = seedrandom('body ' + size) for (var i = 0; i < buffer.length; i++) { buffer[i] = (rng() * 94 + 32) | 0 } return buffer } etag-1.4.0/benchmark/body3-10kb.js000066400000000000000000000023261240761641000165030ustar00rootroot00000000000000 /** * Module dependencies. */ var benchmark = require('benchmark') var benchmarks = require('beautify-benchmark') var seedrandom = require('seedrandom') /** * Globals for benchmark.js */ global.buffer = getbuffer(10 * 1000) global.etag = require('..') global.string = getbuffer(10 * 1000).toString() var suite = new benchmark.Suite suite.add({ name: 'buffer - strong', minSamples: 100, fn: 'var val = etag(buffer, {weak: false})' }) suite.add({ name: 'buffer - weak', minSamples: 100, fn: 'var val = etag(buffer, {weak: true})' }) suite.add({ name: 'string - strong', minSamples: 100, fn: 'var val = etag(string, {weak: false})' }) suite.add({ name: 'string - weak', minSamples: 100, fn: 'var val = etag(string, {weak: true})' }) suite.on('start', function onCycle(event) { process.stdout.write(' 10KB body\n\n') }) suite.on('cycle', function onCycle(event) { benchmarks.add(event.target); }) suite.on('complete', function onComplete() { benchmarks.log(); }) suite.run({async: false}) function getbuffer(size) { var buffer = new Buffer(size) var rng = seedrandom('body ' + size) for (var i = 0; i < buffer.length; i++) { buffer[i] = (rng() * 94 + 32) | 0 } return buffer } etag-1.4.0/benchmark/body4-100kb.js000066400000000000000000000023311240761641000165600ustar00rootroot00000000000000 /** * Module dependencies. */ var benchmark = require('benchmark') var benchmarks = require('beautify-benchmark') var seedrandom = require('seedrandom') /** * Globals for benchmark.js */ global.buffer = getbuffer(100 * 1000) global.etag = require('..') global.string = getbuffer(100 * 1000).toString() var suite = new benchmark.Suite suite.add({ name: 'buffer - strong', minSamples: 100, fn: 'var val = etag(buffer, {weak: false})' }) suite.add({ name: 'buffer - weak', minSamples: 100, fn: 'var val = etag(buffer, {weak: true})' }) suite.add({ name: 'string - strong', minSamples: 100, fn: 'var val = etag(string, {weak: false})' }) suite.add({ name: 'string - weak', minSamples: 100, fn: 'var val = etag(string, {weak: true})' }) suite.on('start', function onCycle(event) { process.stdout.write(' 100KB body\n\n') }) suite.on('cycle', function onCycle(event) { benchmarks.add(event.target); }) suite.on('complete', function onComplete() { benchmarks.log(); }) suite.run({async: false}) function getbuffer(size) { var buffer = new Buffer(size) var rng = seedrandom('body ' + size) for (var i = 0; i < buffer.length; i++) { buffer[i] = (rng() * 94 + 32) | 0 } return buffer } etag-1.4.0/benchmark/index.js000066400000000000000000000012361240761641000160360ustar00rootroot00000000000000var fs = require('fs'); var path = require('path'); var spawn = require('child_process').spawn; var exe = process.argv[0]; var cwd = process.cwd(); runScripts(fs.readdirSync(__dirname)); function runScripts(fileNames) { var fileName = fileNames.shift(); if (!fileName) return; if (!/\.js$/i.test(fileName)) return runScripts(fileNames); if (fileName.toLowerCase() === 'index.js') return runScripts(fileNames); var fullPath = path.join(__dirname, fileName); console.log('> %s %s', exe, path.relative(cwd, fullPath)); var proc = spawn(exe, [fullPath], { 'stdio': 'inherit' }); proc.on('exit', function () { runScripts(fileNames); }); } etag-1.4.0/index.js000066400000000000000000000056521240761641000141120ustar00rootroot00000000000000/*! * etag * Copyright(c) 2014 Douglas Christopher Wilson * MIT Licensed */ /** * Module exports. */ module.exports = etag /** * Module dependencies. */ var crc = require('crc').crc32 var crypto = require('crypto') var Stats = require('fs').Stats /** * Module variables. */ var crc32threshold = 1000 // 1KB var NULL = new Buffer([0]) var toString = Object.prototype.toString /** * Create a simple ETag. * * @param {string|Buffer|Stats} entity * @param {object} [options] * @param {boolean} [options.weak] * @return {String} * @api public */ function etag(entity, options) { if (entity == null) { throw new TypeError('argument entity is required') } var isBuffer = Buffer.isBuffer(entity) var isStats = isstats(entity) var weak = options && typeof options.weak === 'boolean' ? options.weak : isStats // support fs.Stats object if (isStats) { return stattag(entity, weak) } if (!isBuffer && typeof entity !== 'string') { throw new TypeError('argument entity must be string, Buffer, or fs.Stats') } var buf = !isBuffer ? new Buffer(entity, 'utf8') : entity var hash = weak && buf.length <= crc32threshold ? weakhash(buf) : stronghash(buf) return weak ? 'W/"' + hash + '"' : '"' + hash + '"' } /** * Determine if object is a Stats object. * * @param {object} obj * @return {boolean} * @api private */ function isstats(obj) { // not even an object if (obj === null || typeof obj !== 'object') { return false } // genuine fs.Stats if (obj instanceof Stats) { return true } // quack quack return 'atime' in obj && toString.call(obj.atime) === '[object Date]' && 'ctime' in obj && toString.call(obj.ctime) === '[object Date]' && 'mtime' in obj && toString.call(obj.mtime) === '[object Date]' && 'ino' in obj && typeof obj.ino === 'number' && 'size' in obj && typeof obj.size === 'number' } /** * Generate a tag for a stat. * * @param {Buffer} entity * @return {String} * @api private */ function stattag(stat, weak) { var mtime = stat.mtime.toISOString() var size = stat.size.toString(16) if (weak) { return 'W/"' + size + '-' + crc(mtime) + '"' } var hash = crypto .createHash('md5') .update('file', 'utf8') .update(NULL) .update(size, 'utf8') .update(NULL) .update(mtime, 'utf8') .digest('base64') return '"' + hash + '"' } /** * Generate a strong hash. * * @param {Buffer} entity * @return {String} * @api private */ function stronghash(buf) { if (buf.length === 0) { // fast-path empty return '1B2M2Y8AsgTpgAmY7PhCfg==' } return crypto .createHash('md5') .update(buf) .digest('base64') } /** * Generate a weak hash. * * @param {Buffer} entity * @return {String} * @api private */ function weakhash(buf) { if (buf.length === 0) { // fast-path empty return '0-0' } return buf.length.toString(16) + '-' + crc(buf).toString(16) } etag-1.4.0/package.json000066400000000000000000000017351240761641000147310ustar00rootroot00000000000000{ "name": "etag", "description": "Create simple ETags", "version": "1.4.0", "contributors": [ "Douglas Christopher Wilson ", "David Björklund " ], "license": "MIT", "keywords": [ "etag", "http", "res" ], "repository": "jshttp/etag", "dependencies": { "crc": "3.0.0" }, "devDependencies": { "benchmark": "1.0.0", "beautify-benchmark": "0.2.4", "istanbul": "0.3.2", "mocha": "~1.21.4", "seedrandom": "~2.3.6" }, "files": [ "LICENSE", "HISTORY.md", "index.js" ], "engines": { "node": ">= 0.6" }, "scripts": { "bench": "node benchmark/index.js", "test": "mocha --reporter spec --bail --check-leaks test/", "test-cov": "istanbul cover node_modules/mocha/bin/_mocha -- --reporter dot --check-leaks test/", "test-travis": "istanbul cover node_modules/mocha/bin/_mocha --report lcovonly -- --reporter spec --check-leaks test/" } } etag-1.4.0/test/000077500000000000000000000000001240761641000134145ustar00rootroot00000000000000etag-1.4.0/test/test.js000066400000000000000000000065061240761641000147400ustar00rootroot00000000000000 var assert = require('assert') var etag = require('..') var fs = require('fs') describe('etag(entity)', function () { it('should require an entity', function () { assert.throws(etag.bind(), /argument entity is required/) }) it('should reject number entities', function () { assert.throws(etag.bind(null, 4), /argument entity must be/) }) describe('when "entity" is a string', function () { it('should generate a strong ETag', function () { assert.equal(etag('beep boop'), '"Z34SGyQ2IB7YzB7HMkCjrQ=="') }) it('should work containing Unicode', function () { assert.equal(etag('论'), '"aW9HeLTk2Yt6lf7zJYElgw=="') }) it('should work for empty string', function () { assert.equal(etag(''), '"1B2M2Y8AsgTpgAmY7PhCfg=="') }) }) describe('when "entity" is a Buffer', function () { it('should generate a strong ETag', function () { assert.equal(etag(new Buffer([1, 2, 3])), '"Uonfc331cyb83SJZevsfrA=="') }) it('should work for empty Buffer', function () { assert.equal(etag(new Buffer(0)), '"1B2M2Y8AsgTpgAmY7PhCfg=="') }) }) describe('when "entity" is a fs.Stats', function () { it('should generate a weak ETag', function () { assert.ok(isweak(etag(fs.statSync(__filename)))) }) it('should generate consistently', function () { assert.equal(etag(fs.statSync(__filename)), etag(fs.statSync(__filename))) }) }) describe('when "entity" looks like a stats object', function () { it('should generate a weak ETag', function () { var fakeStat = { atime: new Date('2014-09-01T14:52:07Z'), ctime: new Date('2014-09-01T14:52:07Z'), mtime: new Date('2014-09-01T14:52:07Z'), ino: 0, size: 3027 } assert.equal(etag(fakeStat), 'W/"bd3-1182194534"') }) }) describe('with "weak" option', function () { describe('when "false"', function () { it('should generate a strong ETag for a string', function () { assert.equal(etag('', {weak: false}), '"1B2M2Y8AsgTpgAmY7PhCfg=="') assert.equal(etag('beep boop', {weak: false}), '"Z34SGyQ2IB7YzB7HMkCjrQ=="') }) it('should generate a strong ETag for a Buffer', function () { assert.equal(etag(new Buffer(0), {weak: false}), '"1B2M2Y8AsgTpgAmY7PhCfg=="') assert.equal(etag(new Buffer([1, 2, 3]), {weak: false}), '"Uonfc331cyb83SJZevsfrA=="') }) it('should generate a strong ETag for fs.Stats', function () { assert.ok(!isweak(etag(fs.statSync(__filename), {weak: false}))) }) }) describe('when "true"', function () { it('should generate a weak ETag for a string', function () { assert.equal(etag('', {weak: true}), 'W/"0-0"') assert.equal(etag('beep boop', {weak: true}), 'W/"9-7f3ee715"') }) it('should generate a weak ETag for a Buffer', function () { assert.equal(etag(new Buffer(0), {weak: true}), 'W/"0-0"') assert.equal(etag(new Buffer([1, 2, 3]), {weak: true}), 'W/"3-55bc801d"') }) it('should generate a weak ETag for fs.Stats', function () { assert.ok(isweak(etag(fs.statSync(__filename), {weak: true}))) }) }) }) }) function isweak(etag) { var weak = /^(W\/|)"([^"]+)"/.exec(etag) if (weak === null) { throw new Error('invalid ETag: ' + etag) } return weak[1] === 'W/' }