@eik/sink-file-system 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# 1.0.0 (2024-07-29)
+
+
+### Features
+
+* initial release ([1c00ec5](https://github.com/eik-lib/sink-file-system/commit/1c00ec533dbec7d08a05ef1b7f9a3575a34db01a))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Eik
+
+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.

package/README.md

@@ -0,0 +1,136 @@
+# @eik/sink-file-system
+
+Sink implementation that persists files on the local file system.
+
+## Usage
+
+```sh
+npm install @eik/sink-file-system
+```
+
+```js
+import path from 'node:path';
+import { pipeline } from 'node:stream';
+import Sink from '@eik/sink-file-system';
+import express from 'express';
+
+const app = express();
+const sink = new Sink({
+    sinkFsRootPath: path.join(process.cwd(), 'eik-files'),
+});
+
+app.get('/file.js', async (req, res, next) => {
+    try {
+        const file = await sink.read('/path/to/file/file.js');
+        pipeline(file.stream, res, (error) => {
+            if (error) return next(error);
+        });
+    } catch (error) {
+        next(error);
+    }
+});
+
+app.listen(8000);
+```
+
+## API
+
+The sink instance has the following API:
+
+### .write(filePath, contentType)
+
+Method for writing a file to storage.
+
+This method takes the following arguments:
+
+-   `filePath` - String - Path to the file to be stored - Required.
+-   `contentType` - String - The content type of the file - Required.
+
+Resolves with a writable stream.
+
+```js
+import { pipeline } from 'node:stream';
+
+const fromStream = new SomeReadableStream();
+const sink = new Sink({ ... });
+
+try {
+    const file = await sink.write('/path/to/file/file.js', 'application/javascript');
+    pipeline(fromStream, file.stream, (error) => {
+        if (error) console.log(error);
+    });
+} catch (error) {
+    console.log(error);
+}
+```
+
+### .read(filePath)
+
+Method for reading a file from storage.
+
+This method takes the following arguments:
+
+-   `filePath` - String - Path to the file to be read - Required.
+
+Resolves with a [ReadFile][read-file] object which holds metadata about
+the file and a readable stream with the byte stream of the file on the
+`.stream` property.
+
+```js
+import { pipeline } from 'node:stream';
+
+const toStream = new SomeWritableStream();
+const sink = new Sink({ ... });
+
+try {
+    const file = await sink.read('/path/to/file/file.js');
+    pipeline(file.stream, toStream, (error) => {
+        if (error) console.log(error);
+    });
+} catch (error) {
+    console.log(error);
+}
+```
+
+### .delete(filePath)
+
+Method for deleting a file in storage.
+
+This method takes the following arguments:
+
+-   `filePath` - String - Path to the file to be deleted - Required.
+
+Resolves if file is deleted and rejects if file could not be deleted.
+
+```js
+const sink = new Sink({ ... });
+
+try {
+    await sink.delete('/path/to/file/file.js');
+} catch (error) {
+    console.log(error);
+}
+```
+
+### .exist(filePath)
+
+Method for checking if a file exist in the storage.
+
+This method takes the following arguments:
+
+-   `filePath` - String - Path to the file to be checked for existence - Required.
+
+Resolves if file exists and rejects if file does not exist.
+
+```js
+const sink = new Sink({ ... });
+
+try {
+    await sink.exist('/path/to/file/file.js');
+} catch (error) {
+    console.log(error);
+}
+```
+
+[eik]: https://github.com/eik-lib
+[read-file]: https://github.com/eik-lib/common/blob/master/lib/classes/read-file.js

package/lib/main.js

@@ -0,0 +1,337 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ReadFile } from '@eik/common';
+import Sink from '@eik/sink';
+import Metrics from '@metrics/client';
+import mime from 'mime';
+import { rimraf } from 'rimraf';
+
+/**
+ * @param {import('node:fs').Stats} stat
+ * @returns {string} As etag
+ */
+const etagFromFsStat = (stat) => {
+    const mtime = stat.mtime.getTime().toString(16);
+    const size = stat.size.toString(16);
+    return `W/"${size}-${mtime}"`;
+};
+
+/**
+ * @typedef {object} SinkFileSystemOptions
+ * @property {string} [sinkFsRootPath] Default: gets a temporary directory from the OS
+ */
+
+/**
+ * A sink for persisting files to local file system. By default
+ * files are stored in a temporary folder on the OS. To ensure
+ * the files are persisted over time, provide a `sinkFsRootPath`.
+ *
+ * @example
+ * ```js
+ * import path from "node:path";
+ * import Sink from "@eik/sink-file-system";
+ *
+ * const sink = new Sink({
+ *   sinkFsRootPath: path.join(process.cwd(), "eik-files"),
+ * });
+ * ```
+ */
+export default class SinkFileSystem extends Sink {
+    /**
+     * @type {Required<SinkFileSystemOptions>}
+     */
+    _config;
+
+    /** @type {import('@metrics/client')} */
+    _metrics;
+
+    /**
+     * @param {SinkFileSystemOptions} options
+     */
+    constructor(options = {}) {
+        super();
+        this._config = {
+            sinkFsRootPath: path.join(os.tmpdir(), '/eik-files'),
+            ...options,
+        };
+        this._metrics = new Metrics();
+        this._counter = this._metrics.counter({
+            name: 'eik_core_sink_fs',
+            description:
+                'Counter measuring access to the file system storage sink',
+            labels: {
+                operation: 'n/a',
+                success: false,
+                access: false,
+            },
+        });
+    }
+
+    get metrics() {
+        return this._metrics;
+    }
+
+    /**
+     * @param {string} filePath
+     * @param {string} contentType
+     * @returns {Promise<import('node:stream').Writable>}
+     */
+    write(filePath, contentType) {
+        return new Promise((resolve, reject) => {
+            const operation = 'write';
+
+            try {
+                Sink.validateFilePath(filePath);
+                Sink.validateContentType(contentType);
+            } catch (error) {
+                this._counter.inc({ labels: { operation } });
+                reject(error);
+                return;
+            }
+
+            const pathname = path.join(this._config.sinkFsRootPath, filePath);
+
+            if (pathname.indexOf(this._config.sinkFsRootPath) !== 0) {
+                this._counter.inc({ labels: { operation } });
+                reject(new Error(`Directory traversal - ${filePath}`));
+                return;
+            }
+
+            const dir = path.dirname(pathname);
+
+            fs.mkdir(
+                dir,
+                {
+                    recursive: true,
+                },
+                (error) => {
+                    if (error) {
+                        this._counter.inc({
+                            labels: { access: true, operation },
+                        });
+                        reject(
+                            new Error(`Could not create directory - ${dir}`),
+                        );
+                        return;
+                    }
+
+                    const stream = fs.createWriteStream(pathname, {
+                        autoClose: true,
+                        emitClose: true,
+                    });
+
+                    this._counter.inc({
+                        labels: {
+                            success: true,
+                            access: true,
+                            operation,
+                        },
+                    });
+
+                    resolve(stream);
+                },
+            );
+        });
+    }
+
+    /**
+     * @param {string} filePath
+     * @throws {Error} if the file does not exist
+     * @returns {Promise<import('@eik/common').ReadFile>}
+     */
+    read(filePath) {
+        return new Promise((resolve, reject) => {
+            const operation = 'read';
+
+            try {
+                Sink.validateFilePath(filePath);
+            } catch (error) {
+                this._counter.inc({ labels: { operation } });
+                reject(error);
+                return;
+            }
+
+            const pathname = path.join(this._config.sinkFsRootPath, filePath);
+
+            if (pathname.indexOf(this._config.sinkFsRootPath) !== 0) {
+                this._counter.inc({ labels: { operation } });
+                reject(new Error(`Directory traversal - ${filePath}`));
+                return;
+            }
+
+            const closeFd = (fd) => {
+                fs.close(fd, (error) => {
+                    if (error) {
+                        this._counter.inc({
+                            labels: {
+                                access: true,
+                                operation,
+                            },
+                        });
+                        return;
+                    }
+                    this._counter.inc({
+                        labels: {
+                            success: true,
+                            access: true,
+                            operation,
+                        },
+                    });
+                });
+            };
+
+            fs.open(pathname, 'r', (error, fd) => {
+                if (error) {
+                    this._counter.inc({
+                        labels: {
+                            access: true,
+                            operation,
+                        },
+                    });
+                    reject(error);
+                    return;
+                }
+
+                fs.fstat(fd, (err, stat) => {
+                    if (err) {
+                        closeFd(fd);
+                        reject(err);
+                        return;
+                    }
+
+                    if (!stat.isFile()) {
+                        closeFd(fd);
+                        reject(new Error(`Not a file - ${pathname}`));
+                        return;
+                    }
+
+                    const mimeType =
+                        mime.getType(pathname) || 'application/octet-stream';
+                    const etag = etagFromFsStat(stat);
+
+                    const obj = new ReadFile({
+                        mimeType,
+                        etag,
+                    });
+
+                    obj.stream = fs.createReadStream(pathname, {
+                        autoClose: true,
+                        fd,
+                    });
+
+                    obj.stream.on('error', () => {
+                        this._counter.inc({
+                            labels: {
+                                access: true,
+                                operation,
+                            },
+                        });
+                    });
+
+                    obj.stream.on('end', () => {
+                        this._counter.inc({
+                            labels: {
+                                success: true,
+                                access: true,
+                                operation,
+                            },
+                        });
+                    });
+
+                    resolve(obj);
+                });
+            });
+        });
+    }
+
+    /**
+     * @param {string} filePath
+     * @returns {Promise<void>}
+     */
+    delete(filePath) {
+        return new Promise((resolve, reject) => {
+            const operation = 'delete';
+
+            try {
+                Sink.validateFilePath(filePath);
+            } catch (error) {
+                this._counter.inc({ labels: { operation } });
+                reject(error);
+                return;
+            }
+
+            const pathname = path.join(this._config.sinkFsRootPath, filePath);
+
+            if (pathname.indexOf(this._config.sinkFsRootPath) !== 0) {
+                this._counter.inc({ labels: { operation } });
+                reject(new Error(`Directory traversal - ${filePath}`));
+                return;
+            }
+
+            rimraf(pathname)
+                .then(() => {
+                    this._counter.inc({
+                        labels: {
+                            success: true,
+                            access: true,
+                            operation,
+                        },
+                    });
+                    resolve();
+                })
+                .catch((error) => {
+                    this._counter.inc({ labels: { access: true, operation } });
+                    reject(error);
+                });
+        });
+    }
+
+    /**
+     * @param {string} filePath
+     * @throws {Error} if the file does not exist
+     * @returns {Promise<void>}
+     */
+    exist(filePath) {
+        return new Promise((resolve, reject) => {
+            const operation = 'exist';
+
+            try {
+                Sink.validateFilePath(filePath);
+            } catch (error) {
+                this._counter.inc({ labels: { operation } });
+                reject(error);
+                return;
+            }
+
+            const pathname = path.join(this._config.sinkFsRootPath, filePath);
+
+            if (pathname.indexOf(this._config.sinkFsRootPath) !== 0) {
+                this._counter.inc({ labels: { operation } });
+                reject(new Error(`Directory traversal - ${filePath}`));
+                return;
+            }
+
+            fs.stat(pathname, (error, stat) => {
+                this._counter.inc({
+                    labels: { success: true, access: true, operation },
+                });
+
+                if (stat && stat.isFile()) {
+                    resolve();
+                    return;
+                }
+
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                reject();
+            });
+        });
+    }
+
+    get [Symbol.toStringTag]() {
+        return 'SinkFileSystem';
+    }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@eik/sink-file-system",
+  "version": "1.0.0",
+  "description": "Sink implementation that persists files on the local file system.",
+  "main": "lib/main.js",
+  "type": "module",
+  "files": [
+    "CHANGELOG.md",
+    "package.json",
+    "README.md",
+    "lib"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "test": "run-s test:*",
+    "test:unit": "tap --disable-coverage --allow-empty-coverage tests/**/*.js",
+    "test:types": "tsc --project tsconfig.test.json",
+    "types": "tsc --declaration --emitDeclarationOnly"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/eik-lib/sink-file-system.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Trygve Lie",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/eik-lib/sink-file-system/issues"
+  },
+  "homepage": "https://github.com/eik-lib/sink-file-system#readme",
+  "dependencies": {
+    "@eik/common": "3.0.1",
+    "@eik/sink": "1.2.5",
+    "@metrics/client": "2.5.3",
+    "mime": "3.0.0",
+    "rimraf": "5.0.8"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/git": "10.0.1",
+    "@types/mime": "3.0.4",
+    "@types/readable-stream": "4.0.15",
+    "eslint": "9.1.1",
+    "eslint-config-prettier": "9.1.0",
+    "eslint-plugin-prettier": "5.1.3",
+    "globals": "15.0.0",
+    "npm-run-all": "4.1.5",
+    "prettier": "3.3.2",
+    "semantic-release": "24.0.0",
+    "tap": "18.8.0"
+  }
+}