balena-io-modules
file-disk
Handles reads / writes on disk image files.
API
Warning: The API exposed by this library is still forming and can change at any time!
FileDisk
new FileDisk(fd, readOnly, recordWrites, recordReads, discardIsZero=true)
fdis a file descriptor returned byfs.openreadOnlya boolean (defaultfalse)recordWrites, a boolean (defaultfalse); if you usereadOnlywithoutrecordWrites, all write requests will be lost.recordReads, a boolean (defaultfalse): cache reads in memorydiscardIsZero, a boolean (defaulttrue): don't read discarded regions, return zero filled buffers instead.
FileDisk.getCapacity(): Promise<Number>
FileDisk.read(buffer, bufferOffset, length, fileOffset): Promise<{ bytesRead: Number, buffer: Buffer }>
- behaves like fs.read
FileDisk.write(buffer, bufferOffset, length, fileOffset): Promise<{ bytesWritten: Number, buffer: Buffer }>
- behaves like fs.write
FileDisk.flush(): Promise<void>
- behaves like fs.fdatasync
FileDisk.discard(offset, length): Promise<void>
FileDisk.getStream([position, [length, [highWaterMark]]]): Promise<stream.Readable>
positionstart reading from this offset (defaults to 0)lengthread that amount of bytes (defaults to (disk capacity - position))highWaterMark(defaults to 16384, minimum 16) is the size of chunks that will be read
FileDisk.getDiscardedChunks() returns the list of discarded chunks. Each chunk
has a start and end properties. end position is inclusive.
FileDisk.getRanges(blockSize): Promise<Range[]>
- using the disk's discarded chunks and the given blockSize, it returns a Promise
of an array of
Ranges:{ offset: number, length: number }.
S3Disk
S3Disk has been moved to a separate repository.
Examples
Read 1024 first bytes, write them starting at position 1024 then flush.
const filedisk = require('file-disk');
await filedisk.withOpenFile('/path/to/some/file', 'r+', async (handle) => {
const disk = new filedisk.FileDisk(handle)
// get file size
const size = await disk.getCapacity();
console.log("size:", size);
const buf = Buffer.alloc(1024);
// read `buf.length` bytes starting at 0 from the file into `buf`
const { bytesRead, buffer } = await disk.read(buf, 0, buf.length, 0);
// write `buffer` into file starting at `buffer.length` (in the file)
await disk.write(buf, 0, buf.length, buf.length);
// flush
await disk.flush();
});
Open a file readOnly, use the recordWrites mode, then stream the contents somewhere.
const filedisk = require('file-disk');
const BUF = Buffer.alloc(1024);
await filedisk.withOpenFile('/path/to/some/file', 'r', async (handle) => {
const disk = new filedisk.FileDisk(handle, true, true);
let bytesRead, bytesWritten, buffer;
// read `BUF.length` bytes starting at 0 from the file into `BUF`
{ bytesRead, buffer } = await disk.read(BUF, 0, BUF.length, 0);
// write `buffer` into file starting at `buffer.length` (in the file)
{ bytesWritten, buffer } = await disk.write(buffer, 0, buffer.length, buffer.length);
const buf2 = Buffer.alloc(1024);
// read what we've just written
{ bytesRead, buffer } = await disk.read(buf2, 0, buffer.length, 0);
// writes are stored in memory
assert(BUF.equals(buffer));
const stream = await disk.getStream();
// pipe the stream somewhere
await new Promise((resolve, reject) => {
stream.pipe(someWritableStream)
.on('close', resolve)
.on('error', reject);
});
});