source: trip-planner-front/node_modules/cacache/README.md@ 6a3a178

Last change on this file since 6a3a178 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 21.7 KB
LineΒ 
1# cacache [![npm version](https://img.shields.io/npm/v/cacache.svg)](https://npm.im/cacache) [![license](https://img.shields.io/npm/l/cacache.svg)](https://npm.im/cacache) [![Travis](https://img.shields.io/travis/npm/cacache.svg)](https://travis-ci.org/npm/cacache) [![AppVeyor](https://ci.appveyor.com/api/projects/status/github/npm/cacache?svg=true)](https://ci.appveyor.com/project/npm/cacache) [![Coverage Status](https://coveralls.io/repos/github/npm/cacache/badge.svg?branch=latest)](https://coveralls.io/github/npm/cacache?branch=latest)
2
3[`cacache`](https://github.com/npm/cacache) is a Node.js library for managing
4local key and content address caches. It's really fast, really good at
5concurrency, and it will never give you corrupted data, even if cache files
6get corrupted or manipulated.
7
8On systems that support user and group settings on files, cacache will
9match the `uid` and `gid` values to the folder where the cache lives, even
10when running as `root`.
11
12It was written to be used as [npm](https://npm.im)'s local cache, but can
13just as easily be used on its own.
14
15## Install
16
17`$ npm install --save cacache`
18
19## Table of Contents
20
21* [Example](#example)
22* [Features](#features)
23* [Contributing](#contributing)
24* [API](#api)
25 * [Using localized APIs](#localized-api)
26 * Reading
27 * [`ls`](#ls)
28 * [`ls.stream`](#ls-stream)
29 * [`get`](#get-data)
30 * [`get.stream`](#get-stream)
31 * [`get.info`](#get-info)
32 * [`get.hasContent`](#get-hasContent)
33 * Writing
34 * [`put`](#put-data)
35 * [`put.stream`](#put-stream)
36 * [`rm.all`](#rm-all)
37 * [`rm.entry`](#rm-entry)
38 * [`rm.content`](#rm-content)
39 * [`index.compact`](#index-compact)
40 * [`index.insert`](#index-insert)
41 * Utilities
42 * [`clearMemoized`](#clear-memoized)
43 * [`tmp.mkdir`](#tmp-mkdir)
44 * [`tmp.withTmp`](#with-tmp)
45 * Integrity
46 * [Subresource Integrity](#integrity)
47 * [`verify`](#verify)
48 * [`verify.lastRun`](#verify-last-run)
49
50### Example
51
52```javascript
53const cacache = require('cacache')
54const fs = require('fs')
55
56const tarball = '/path/to/mytar.tgz'
57const cachePath = '/tmp/my-toy-cache'
58const key = 'my-unique-key-1234'
59
60// Cache it! Use `cachePath` as the root of the content cache
61cacache.put(cachePath, key, '10293801983029384').then(integrity => {
62 console.log(`Saved content to ${cachePath}.`)
63})
64
65const destination = '/tmp/mytar.tgz'
66
67// Copy the contents out of the cache and into their destination!
68// But this time, use stream instead!
69cacache.get.stream(
70 cachePath, key
71).pipe(
72 fs.createWriteStream(destination)
73).on('finish', () => {
74 console.log('done extracting!')
75})
76
77// The same thing, but skip the key index.
78cacache.get.byDigest(cachePath, integrityHash).then(data => {
79 fs.writeFile(destination, data, err => {
80 console.log('tarball data fetched based on its sha512sum and written out!')
81 })
82})
83```
84
85### Features
86
87* Extraction by key or by content address (shasum, etc)
88* [Subresource Integrity](#integrity) web standard support
89* Multi-hash support - safely host sha1, sha512, etc, in a single cache
90* Automatic content deduplication
91* Fault tolerance (immune to corruption, partial writes, process races, etc)
92* Consistency guarantees on read and write (full data verification)
93* Lockless, high-concurrency cache access
94* Streaming support
95* Promise support
96* Fast -- sub-millisecond reads and writes including verification
97* Arbitrary metadata storage
98* Garbage collection and additional offline verification
99* Thorough test coverage
100* There's probably a bloom filter in there somewhere. Those are cool, right? πŸ€”
101
102### Contributing
103
104The cacache team enthusiastically welcomes contributions and project participation! There's a bunch of things you can do if you want to contribute! The [Contributor Guide](CONTRIBUTING.md) has all the information you need for everything from reporting bugs to contributing entire new features. Please don't hesitate to jump in if you'd like to, or even ask us questions if something isn't clear.
105
106All participants and maintainers in this project are expected to follow [Code of Conduct](CODE_OF_CONDUCT.md), and just generally be excellent to each other.
107
108Please refer to the [Changelog](CHANGELOG.md) for project history details, too.
109
110Happy hacking!
111
112### API
113
114#### <a name="ls"></a> `> cacache.ls(cache) -> Promise<Object>`
115
116Lists info for all entries currently in the cache as a single large object. Each
117entry in the object will be keyed by the unique index key, with corresponding
118[`get.info`](#get-info) objects as the values.
119
120##### Example
121
122```javascript
123cacache.ls(cachePath).then(console.log)
124// Output
125{
126 'my-thing': {
127 key: 'my-thing',
128 integrity: 'sha512-BaSe64/EnCoDED+HAsh=='
129 path: '.testcache/content/deadbeef', // joined with `cachePath`
130 time: 12345698490,
131 size: 4023948,
132 metadata: {
133 name: 'blah',
134 version: '1.2.3',
135 description: 'this was once a package but now it is my-thing'
136 }
137 },
138 'other-thing': {
139 key: 'other-thing',
140 integrity: 'sha1-ANothER+hasH=',
141 path: '.testcache/content/bada55',
142 time: 11992309289,
143 size: 111112
144 }
145}
146```
147
148#### <a name="ls-stream"></a> `> cacache.ls.stream(cache) -> Readable`
149
150Lists info for all entries currently in the cache as a single large object.
151
152This works just like [`ls`](#ls), except [`get.info`](#get-info) entries are
153returned as `'data'` events on the returned stream.
154
155##### Example
156
157```javascript
158cacache.ls.stream(cachePath).on('data', console.log)
159// Output
160{
161 key: 'my-thing',
162 integrity: 'sha512-BaSe64HaSh',
163 path: '.testcache/content/deadbeef', // joined with `cachePath`
164 time: 12345698490,
165 size: 13423,
166 metadata: {
167 name: 'blah',
168 version: '1.2.3',
169 description: 'this was once a package but now it is my-thing'
170 }
171}
172
173{
174 key: 'other-thing',
175 integrity: 'whirlpool-WoWSoMuchSupport',
176 path: '.testcache/content/bada55',
177 time: 11992309289,
178 size: 498023984029
179}
180
181{
182 ...
183}
184```
185
186#### <a name="get-data"></a> `> cacache.get(cache, key, [opts]) -> Promise({data, metadata, integrity})`
187
188Returns an object with the cached data, digest, and metadata identified by
189`key`. The `data` property of this object will be a `Buffer` instance that
190presumably holds some data that means something to you. I'm sure you know what
191to do with it! cacache just won't care.
192
193`integrity` is a [Subresource
194Integrity](#integrity)
195string. That is, a string that can be used to verify `data`, which looks like
196`<hash-algorithm>-<base64-integrity-hash>`.
197
198If there is no content identified by `key`, or if the locally-stored data does
199not pass the validity checksum, the promise will be rejected.
200
201A sub-function, `get.byDigest` may be used for identical behavior, except lookup
202will happen by integrity hash, bypassing the index entirely. This version of the
203function *only* returns `data` itself, without any wrapper.
204
205See: [options](#get-options)
206
207##### Note
208
209This function loads the entire cache entry into memory before returning it. If
210you're dealing with Very Large data, consider using [`get.stream`](#get-stream)
211instead.
212
213##### Example
214
215```javascript
216// Look up by key
217cache.get(cachePath, 'my-thing').then(console.log)
218// Output:
219{
220 metadata: {
221 thingName: 'my'
222 },
223 integrity: 'sha512-BaSe64HaSh',
224 data: Buffer#<deadbeef>,
225 size: 9320
226}
227
228// Look up by digest
229cache.get.byDigest(cachePath, 'sha512-BaSe64HaSh').then(console.log)
230// Output:
231Buffer#<deadbeef>
232```
233
234#### <a name="get-stream"></a> `> cacache.get.stream(cache, key, [opts]) -> Readable`
235
236Returns a [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams) of the cached data identified by `key`.
237
238If there is no content identified by `key`, or if the locally-stored data does
239not pass the validity checksum, an error will be emitted.
240
241`metadata` and `integrity` events will be emitted before the stream closes, if
242you need to collect that extra data about the cached entry.
243
244A sub-function, `get.stream.byDigest` may be used for identical behavior,
245except lookup will happen by integrity hash, bypassing the index entirely. This
246version does not emit the `metadata` and `integrity` events at all.
247
248See: [options](#get-options)
249
250##### Example
251
252```javascript
253// Look up by key
254cache.get.stream(
255 cachePath, 'my-thing'
256).on('metadata', metadata => {
257 console.log('metadata:', metadata)
258}).on('integrity', integrity => {
259 console.log('integrity:', integrity)
260}).pipe(
261 fs.createWriteStream('./x.tgz')
262)
263// Outputs:
264metadata: { ... }
265integrity: 'sha512-SoMeDIGest+64=='
266
267// Look up by digest
268cache.get.stream.byDigest(
269 cachePath, 'sha512-SoMeDIGest+64=='
270).pipe(
271 fs.createWriteStream('./x.tgz')
272)
273```
274
275#### <a name="get-info"></a> `> cacache.get.info(cache, key) -> Promise`
276
277Looks up `key` in the cache index, returning information about the entry if
278one exists.
279
280##### Fields
281
282* `key` - Key the entry was looked up under. Matches the `key` argument.
283* `integrity` - [Subresource Integrity hash](#integrity) for the content this entry refers to.
284* `path` - Filesystem path where content is stored, joined with `cache` argument.
285* `time` - Timestamp the entry was first added on.
286* `metadata` - User-assigned metadata associated with the entry/content.
287
288##### Example
289
290```javascript
291cacache.get.info(cachePath, 'my-thing').then(console.log)
292
293// Output
294{
295 key: 'my-thing',
296 integrity: 'sha256-MUSTVERIFY+ALL/THINGS=='
297 path: '.testcache/content/deadbeef',
298 time: 12345698490,
299 size: 849234,
300 metadata: {
301 name: 'blah',
302 version: '1.2.3',
303 description: 'this was once a package but now it is my-thing'
304 }
305}
306```
307
308#### <a name="get-hasContent"></a> `> cacache.get.hasContent(cache, integrity) -> Promise`
309
310Looks up a [Subresource Integrity hash](#integrity) in the cache. If content
311exists for this `integrity`, it will return an object, with the specific single integrity hash
312that was found in `sri` key, and the size of the found content as `size`. If no content exists for this integrity, it will return `false`.
313
314##### Example
315
316```javascript
317cacache.get.hasContent(cachePath, 'sha256-MUSTVERIFY+ALL/THINGS==').then(console.log)
318
319// Output
320{
321 sri: {
322 source: 'sha256-MUSTVERIFY+ALL/THINGS==',
323 algorithm: 'sha256',
324 digest: 'MUSTVERIFY+ALL/THINGS==',
325 options: []
326 },
327 size: 9001
328}
329
330cacache.get.hasContent(cachePath, 'sha521-NOT+IN/CACHE==').then(console.log)
331
332// Output
333false
334```
335
336##### <a name="get-options"></a> Options
337
338##### `opts.integrity`
339If present, the pre-calculated digest for the inserted content. If this option
340is provided and does not match the post-insertion digest, insertion will fail
341with an `EINTEGRITY` error.
342
343##### `opts.memoize`
344
345Default: null
346
347If explicitly truthy, cacache will read from memory and memoize data on bulk read. If `false`, cacache will read from disk data. Reader functions by default read from in-memory cache.
348
349##### `opts.size`
350If provided, the data stream will be verified to check that enough data was
351passed through. If there's more or less data than expected, insertion will fail
352with an `EBADSIZE` error.
353
354
355#### <a name="put-data"></a> `> cacache.put(cache, key, data, [opts]) -> Promise`
356
357Inserts data passed to it into the cache. The returned Promise resolves with a
358digest (generated according to [`opts.algorithms`](#optsalgorithms)) after the
359cache entry has been successfully written.
360
361See: [options](#put-options)
362
363##### Example
364
365```javascript
366fetch(
367 'https://registry.npmjs.org/cacache/-/cacache-1.0.0.tgz'
368).then(data => {
369 return cacache.put(cachePath, 'registry.npmjs.org|cacache@1.0.0', data)
370}).then(integrity => {
371 console.log('integrity hash is', integrity)
372})
373```
374
375#### <a name="put-stream"></a> `> cacache.put.stream(cache, key, [opts]) -> Writable`
376
377Returns a [Writable
378Stream](https://nodejs.org/api/stream.html#stream_writable_streams) that inserts
379data written to it into the cache. Emits an `integrity` event with the digest of
380written contents when it succeeds.
381
382See: [options](#put-options)
383
384##### Example
385
386```javascript
387request.get(
388 'https://registry.npmjs.org/cacache/-/cacache-1.0.0.tgz'
389).pipe(
390 cacache.put.stream(
391 cachePath, 'registry.npmjs.org|cacache@1.0.0'
392 ).on('integrity', d => console.log(`integrity digest is ${d}`))
393)
394```
395
396##### <a name="put-options"></a> Options
397
398##### `opts.metadata`
399
400Arbitrary metadata to be attached to the inserted key.
401
402##### `opts.size`
403
404If provided, the data stream will be verified to check that enough data was
405passed through. If there's more or less data than expected, insertion will fail
406with an `EBADSIZE` error.
407
408##### `opts.integrity`
409
410If present, the pre-calculated digest for the inserted content. If this option
411is provided and does not match the post-insertion digest, insertion will fail
412with an `EINTEGRITY` error.
413
414`algorithms` has no effect if this option is present.
415
416##### `opts.algorithms`
417
418Default: ['sha512']
419
420Hashing algorithms to use when calculating the [subresource integrity
421digest](#integrity)
422for inserted data. Can use any algorithm listed in `crypto.getHashes()` or
423`'omakase'`/`'γŠδ»»γ›γ—γΎγ™'` to pick a random hash algorithm on each insertion. You
424may also use any anagram of `'modnar'` to use this feature.
425
426Currently only supports one algorithm at a time (i.e., an array length of
427exactly `1`). Has no effect if `opts.integrity` is present.
428
429##### `opts.memoize`
430
431Default: null
432
433If provided, cacache will memoize the given cache insertion in memory, bypassing
434any filesystem checks for that key or digest in future cache fetches. Nothing
435will be written to the in-memory cache unless this option is explicitly truthy.
436
437If `opts.memoize` is an object or a `Map`-like (that is, an object with `get`
438and `set` methods), it will be written to instead of the global memoization
439cache.
440
441Reading from disk data can be forced by explicitly passing `memoize: false` to
442the reader functions, but their default will be to read from memory.
443
444##### `opts.tmpPrefix`
445Default: null
446
447Prefix to append on the temporary directory name inside the cache's tmp dir.
448
449#### <a name="rm-all"></a> `> cacache.rm.all(cache) -> Promise`
450
451Clears the entire cache. Mainly by blowing away the cache directory itself.
452
453##### Example
454
455```javascript
456cacache.rm.all(cachePath).then(() => {
457 console.log('THE APOCALYPSE IS UPON US 😱')
458})
459```
460
461#### <a name="rm-entry"></a> `> cacache.rm.entry(cache, key, [opts]) -> Promise`
462
463Alias: `cacache.rm`
464
465Removes the index entry for `key`. Content will still be accessible if
466requested directly by content address ([`get.stream.byDigest`](#get-stream)).
467
468By default, this appends a new entry to the index with an integrity of `null`.
469If `opts.removeFully` is set to `true` then the index file itself will be
470physically deleted rather than appending a `null`.
471
472To remove the content itself (which might still be used by other entries), use
473[`rm.content`](#rm-content). Or, to safely vacuum any unused content, use
474[`verify`](#verify).
475
476##### Example
477
478```javascript
479cacache.rm.entry(cachePath, 'my-thing').then(() => {
480 console.log('I did not like it anyway')
481})
482```
483
484#### <a name="rm-content"></a> `> cacache.rm.content(cache, integrity) -> Promise`
485
486Removes the content identified by `integrity`. Any index entries referring to it
487will not be usable again until the content is re-added to the cache with an
488identical digest.
489
490##### Example
491
492```javascript
493cacache.rm.content(cachePath, 'sha512-SoMeDIGest/IN+BaSE64==').then(() => {
494 console.log('data for my-thing is gone!')
495})
496```
497
498#### <a name="index-compact"></a> `> cacache.index.compact(cache, key, matchFn, [opts]) -> Promise`
499
500Uses `matchFn`, which must be a synchronous function that accepts two entries
501and returns a boolean indicating whether or not the two entries match, to
502deduplicate all entries in the cache for the given `key`.
503
504If `opts.validateEntry` is provided, it will be called as a function with the
505only parameter being a single index entry. The function must return a Boolean,
506if it returns `true` the entry is considered valid and will be kept in the index,
507if it returns `false` the entry will be removed from the index.
508
509If `opts.validateEntry` is not provided, however, every entry in the index will
510be deduplicated and kept until the first `null` integrity is reached, removing
511all entries that were written before the `null`.
512
513The deduplicated list of entries is both written to the index, replacing the
514existing content, and returned in the Promise.
515
516#### <a name="index-insert"></a> `> cacache.index.insert(cache, key, integrity, opts) -> Promise`
517
518Writes an index entry to the cache for the given `key` without writing content.
519
520It is assumed if you are using this method, you have already stored the content
521some other way and you only wish to add a new index to that content. The `metadata`
522and `size` properties are read from `opts` and used as part of the index entry.
523
524Returns a Promise resolving to the newly added entry.
525
526#### <a name="clear-memoized"></a> `> cacache.clearMemoized()`
527
528Completely resets the in-memory entry cache.
529
530#### <a name="tmp-mkdir"></a> `> tmp.mkdir(cache, opts) -> Promise<Path>`
531
532Returns a unique temporary directory inside the cache's `tmp` dir. This
533directory will use the same safe user assignment that all the other stuff use.
534
535Once the directory is made, it's the user's responsibility that all files
536within are given the appropriate `gid`/`uid` ownership settings to match
537the rest of the cache. If not, you can ask cacache to do it for you by
538calling [`tmp.fix()`](#tmp-fix), which will fix all tmp directory
539permissions.
540
541If you want automatic cleanup of this directory, use
542[`tmp.withTmp()`](#with-tpm)
543
544See: [options](#tmp-options)
545
546##### Example
547
548```javascript
549cacache.tmp.mkdir(cache).then(dir => {
550 fs.writeFile(path.join(dir, 'blablabla'), Buffer#<1234>, ...)
551})
552```
553
554#### <a name="tmp-fix"></a> `> tmp.fix(cache) -> Promise`
555
556Sets the `uid` and `gid` properties on all files and folders within the tmp
557folder to match the rest of the cache.
558
559Use this after manually writing files into [`tmp.mkdir`](#tmp-mkdir) or
560[`tmp.withTmp`](#with-tmp).
561
562##### Example
563
564```javascript
565cacache.tmp.mkdir(cache).then(dir => {
566 writeFile(path.join(dir, 'file'), someData).then(() => {
567 // make sure we didn't just put a root-owned file in the cache
568 cacache.tmp.fix().then(() => {
569 // all uids and gids match now
570 })
571 })
572})
573```
574
575#### <a name="with-tmp"></a> `> tmp.withTmp(cache, opts, cb) -> Promise`
576
577Creates a temporary directory with [`tmp.mkdir()`](#tmp-mkdir) and calls `cb`
578with it. The created temporary directory will be removed when the return value
579of `cb()` resolves, the tmp directory will be automatically deleted once that
580promise completes.
581
582The same caveats apply when it comes to managing permissions for the tmp dir's
583contents.
584
585See: [options](#tmp-options)
586
587##### Example
588
589```javascript
590cacache.tmp.withTmp(cache, dir => {
591 return fs.writeFileAsync(path.join(dir, 'blablabla'), Buffer#<1234>, ...)
592}).then(() => {
593 // `dir` no longer exists
594})
595```
596
597##### <a name="tmp-options"></a> Options
598
599##### `opts.tmpPrefix`
600Default: null
601
602Prefix to append on the temporary directory name inside the cache's tmp dir.
603
604#### <a name="integrity"></a> Subresource Integrity Digests
605
606For content verification and addressing, cacache uses strings following the
607[Subresource
608Integrity spec](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).
609That is, any time cacache expects an `integrity` argument or option, it
610should be in the format `<hashAlgorithm>-<base64-hash>`.
611
612One deviation from the current spec is that cacache will support any hash
613algorithms supported by the underlying Node.js process. You can use
614`crypto.getHashes()` to see which ones you can use.
615
616##### Generating Digests Yourself
617
618If you have an existing content shasum, they are generally formatted as a
619hexadecimal string (that is, a sha1 would look like:
620`5f5513f8822fdbe5145af33b64d8d970dcf95c6e`). In order to be compatible with
621cacache, you'll need to convert this to an equivalent subresource integrity
622string. For this example, the corresponding hash would be:
623`sha1-X1UT+IIv2+UUWvM7ZNjZcNz5XG4=`.
624
625If you want to generate an integrity string yourself for existing data, you can
626use something like this:
627
628```javascript
629const crypto = require('crypto')
630const hashAlgorithm = 'sha512'
631const data = 'foobarbaz'
632
633const integrity = (
634 hashAlgorithm +
635 '-' +
636 crypto.createHash(hashAlgorithm).update(data).digest('base64')
637)
638```
639
640You can also use [`ssri`](https://npm.im/ssri) to have a richer set of functionality
641around SRI strings, including generation, parsing, and translating from existing
642hex-formatted strings.
643
644#### <a name="verify"></a> `> cacache.verify(cache, opts) -> Promise`
645
646Checks out and fixes up your cache:
647
648* Cleans up corrupted or invalid index entries.
649* Custom entry filtering options.
650* Garbage collects any content entries not referenced by the index.
651* Checks integrity for all content entries and removes invalid content.
652* Fixes cache ownership.
653* Removes the `tmp` directory in the cache and all its contents.
654
655When it's done, it'll return an object with various stats about the verification
656process, including amount of storage reclaimed, number of valid entries, number
657of entries removed, etc.
658
659##### <a name="verify-options"></a> Options
660
661##### `opts.concurrency`
662
663Default: 20
664
665Number of concurrently read files in the filesystem while doing clean up.
666
667##### `opts.filter`
668Receives a formatted entry. Return false to remove it.
669Note: might be called more than once on the same entry.
670
671##### `opts.log`
672Custom logger function:
673```
674 log: { silly () {} }
675 log.silly('verify', 'verifying cache at', cache)
676```
677
678##### Example
679
680```sh
681echo somegarbage >> $CACHEPATH/content/deadbeef
682```
683
684```javascript
685cacache.verify(cachePath).then(stats => {
686 // deadbeef collected, because of invalid checksum.
687 console.log('cache is much nicer now! stats:', stats)
688})
689```
690
691#### <a name="verify-last-run"></a> `> cacache.verify.lastRun(cache) -> Promise`
692
693Returns a `Date` representing the last time `cacache.verify` was run on `cache`.
694
695##### Example
696
697```javascript
698cacache.verify(cachePath).then(() => {
699 cacache.verify.lastRun(cachePath).then(lastTime => {
700 console.log('cacache.verify was last called on' + lastTime)
701 })
702})
703```
Note: See TracBrowser for help on using the repository browser.