@deenruv/asset-server-plugin 1.0.0

package/lib/src/plugin.js

@@ -0,0 +1,394 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var AssetServerPlugin_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssetServerPlugin = void 0;
+const core_1 = require("@deenruv/core");
+const crypto_1 = require("crypto");
+const express_1 = __importDefault(require("express"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const common_1 = require("./common");
+const constants_1 = require("./constants");
+const default_asset_storage_strategy_factory_1 = require("./default-asset-storage-strategy-factory");
+const hashed_asset_naming_strategy_1 = require("./hashed-asset-naming-strategy");
+const sharp_asset_preview_strategy_1 = require("./sharp-asset-preview-strategy");
+const transform_image_1 = require("./transform-image");
+async function getFileType(buffer) {
+    const { fileTypeFromBuffer } = await import("file-type");
+    return fileTypeFromBuffer(buffer);
+}
+/**
+ * @description
+ * The `AssetServerPlugin` serves assets (images and other files) from the local file system, and can also be configured to use
+ * other storage strategies (e.g. {@link S3AssetStorageStrategy}. It can also perform on-the-fly image transformations
+ * and caches the results for subsequent calls.
+ *
+ * ## Installation
+ *
+ * `yarn add \@deenruv/asset-server-plugin`
+ *
+ * or
+ *
+ * `npm install \@deenruv/asset-server-plugin`
+ *
+ * @example
+ * ```ts
+ * import { AssetServerPlugin } from '\@deenruv/asset-server-plugin';
+ *
+ * const config: DeenruvConfig = {
+ *   // Add an instance of the plugin to the plugins array
+ *   plugins: [
+ *     AssetServerPlugin.init({
+ *       route: 'assets',
+ *       assetUploadDir: path.join(__dirname, 'assets'),
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * The full configuration is documented at [AssetServerOptions](/reference/core-plugins/asset-server-plugin/asset-server-options)
+ *
+ * ## Image transformation
+ *
+ * Asset preview images can be transformed (resized & cropped) on the fly by appending query parameters to the url:
+ *
+ * `http://localhost:3000/assets/some-asset.jpg?w=500&h=300&mode=resize`
+ *
+ * The above URL will return `some-asset.jpg`, resized to fit in the bounds of a 500px x 300px rectangle.
+ *
+ * ### Preview mode
+ *
+ * The `mode` parameter can be either `crop` or `resize`. See the [ImageTransformMode](/reference/core-plugins/asset-server-plugin/image-transform-mode) docs for details.
+ *
+ * ### Focal point
+ *
+ * When cropping an image (`mode=crop`), Deenruv will attempt to keep the most "interesting" area of the image in the cropped frame. It does this
+ * by finding the area of the image with highest entropy (the busiest area of the image). However, sometimes this does not yield a satisfactory
+ * result - part or all of the main subject may still be cropped out.
+ *
+ * This is where specifying the focal point can help. The focal point of the image may be specified by passing the `fpx` and `fpy` query parameters.
+ * These are normalized coordinates (i.e. a number between 0 and 1), so the `fpx=0&fpy=0` corresponds to the top left of the image.
+ *
+ * For example, let's say there is a very wide landscape image which we want to crop to be square. The main subject is a house to the far left of the
+ * image. The following query would crop it to a square with the house centered:
+ *
+ * `http://localhost:3000/assets/landscape.jpg?w=150&h=150&mode=crop&fpx=0.2&fpy=0.7`
+ *
+ * ### Format
+ *
+ * Since v1.7.0, the image format can be specified by adding the `format` query parameter:
+ *
+ * `http://localhost:3000/assets/some-asset.jpg?format=webp`
+ *
+ * This means that, no matter the format of your original asset files, you can use more modern formats in your storefront if the browser
+ * supports them. Supported values for `format` are:
+ *
+ * * `jpeg` or `jpg`
+ * * `png`
+ * * `webp`
+ * * `avif`
+ *
+ * The `format` parameter can also be combined with presets (see below).
+ *
+ * ### Quality
+ *
+ * Since v2.2.0, the image quality can be specified by adding the `q` query parameter:
+ *
+ * `http://localhost:3000/assets/some-asset.jpg?q=75`
+ *
+ * This applies to the `jpg`, `webp` and `avif` formats. The default quality value for `jpg` and `webp` is 80, and for `avif` is 50.
+ *
+ * The `q` parameter can also be combined with presets (see below).
+ *
+ * ### Transform presets
+ *
+ * Presets can be defined which allow a single preset name to be used instead of specifying the width, height and mode. Presets are
+ * configured via the AssetServerOptions [presets property](/reference/core-plugins/asset-server-plugin/asset-server-options/#presets).
+ *
+ * For example, defining the following preset:
+ *
+ * ```ts
+ * AssetServerPlugin.init({
+ *   // ...
+ *   presets: [
+ *     { name: 'my-preset', width: 85, height: 85, mode: 'crop' },
+ *   ],
+ * }),
+ * ```
+ *
+ * means that a request to:
+ *
+ * `http://localhost:3000/assets/some-asset.jpg?preset=my-preset`
+ *
+ * is equivalent to:
+ *
+ * `http://localhost:3000/assets/some-asset.jpg?w=85&h=85&mode=crop`
+ *
+ * The AssetServerPlugin comes pre-configured with the following presets:
+ *
+ * name | width | height | mode
+ * -----|-------|--------|-----
+ * tiny | 50px | 50px | crop
+ * thumb | 150px | 150px | crop
+ * small | 300px | 300px | resize
+ * medium | 500px | 500px | resize
+ * large | 800px | 800px | resize
+ *
+ * ### Caching
+ * By default, the AssetServerPlugin will cache every transformed image, so that the transformation only needs to be performed a single time for
+ * a given configuration. Caching can be disabled per-request by setting the `?cache=false` query parameter.
+ *
+ * @docsCategory core plugins/AssetServerPlugin
+ */
+let AssetServerPlugin = AssetServerPlugin_1 = class AssetServerPlugin {
+    /**
+     * @description
+     * Set the plugin options.
+     */
+    static init(options) {
+        AssetServerPlugin_1.options = options;
+        return this;
+    }
+    /** @internal */
+    static async configure(config) {
+        var _a;
+        const storageStrategyFactory = this.options.storageStrategyFactory || default_asset_storage_strategy_factory_1.defaultAssetStorageStrategyFactory;
+        this.assetStorage = await storageStrategyFactory(this.options);
+        config.assetOptions.assetPreviewStrategy =
+            (_a = this.options.previewStrategy) !== null && _a !== void 0 ? _a : new sharp_asset_preview_strategy_1.SharpAssetPreviewStrategy({
+                maxWidth: this.options.previewMaxWidth,
+                maxHeight: this.options.previewMaxHeight,
+            });
+        config.assetOptions.assetStorageStrategy = this.assetStorage;
+        config.assetOptions.assetNamingStrategy =
+            this.options.namingStrategy || new hashed_asset_naming_strategy_1.HashedAssetNamingStrategy();
+        return config;
+    }
+    constructor(processContext) {
+        this.processContext = processContext;
+        this.cacheDir = "cache";
+        this.presets = [
+            { name: "tiny", width: 50, height: 50, mode: "crop" },
+            { name: "thumb", width: 150, height: 150, mode: "crop" },
+            { name: "small", width: 300, height: 300, mode: "resize" },
+            { name: "medium", width: 500, height: 500, mode: "resize" },
+            { name: "large", width: 800, height: 800, mode: "resize" },
+        ];
+    }
+    /** @internal */
+    onApplicationBootstrap() {
+        if (this.processContext.isWorker) {
+            return;
+        }
+        if (AssetServerPlugin_1.options.presets) {
+            for (const preset of AssetServerPlugin_1.options.presets) {
+                const existingIndex = this.presets.findIndex((p) => p.name === preset.name);
+                if (-1 < existingIndex) {
+                    this.presets.splice(existingIndex, 1, preset);
+                }
+                else {
+                    this.presets.push(preset);
+                }
+            }
+        }
+        // Configure Cache-Control header
+        const { cacheHeader } = AssetServerPlugin_1.options;
+        if (!cacheHeader) {
+            this.cacheHeader = constants_1.DEFAULT_CACHE_HEADER;
+        }
+        else {
+            if (typeof cacheHeader === "string") {
+                this.cacheHeader = cacheHeader;
+            }
+            else {
+                this.cacheHeader = [
+                    cacheHeader.restriction,
+                    `max-age: ${cacheHeader.maxAge}`,
+                ]
+                    .filter((value) => !!value)
+                    .join(", ");
+            }
+        }
+        const cachePath = path_1.default.join(AssetServerPlugin_1.options.assetUploadDir, this.cacheDir);
+        fs_extra_1.default.ensureDirSync(cachePath);
+    }
+    configure(consumer) {
+        if (this.processContext.isWorker) {
+            return;
+        }
+        core_1.Logger.info("Creating asset server middleware", constants_1.loggerCtx);
+        consumer
+            .apply(this.createAssetServer())
+            .forRoutes(AssetServerPlugin_1.options.route);
+        (0, core_1.registerPluginStartupMessage)("Asset server", AssetServerPlugin_1.options.route);
+    }
+    /**
+     * Creates the image server instance
+     */
+    createAssetServer() {
+        const assetServer = express_1.default.Router();
+        assetServer.use(this.sendAsset(), this.generateTransformedImage());
+        return assetServer;
+    }
+    /**
+     * Reads the file requested and send the response to the browser.
+     */
+    sendAsset() {
+        return async (req, res, next) => {
+            var _a;
+            const key = this.getFileNameFromRequest(req);
+            try {
+                const file = await AssetServerPlugin_1.assetStorage.readFileToBuffer(key);
+                let mimeType = this.getMimeType(key);
+                if (!mimeType) {
+                    mimeType =
+                        ((_a = (await getFileType(file))) === null || _a === void 0 ? void 0 : _a.mime) || "application/octet-stream";
+                }
+                res.contentType(mimeType);
+                res.setHeader("content-security-policy", "default-src 'self'");
+                res.setHeader("Cache-Control", this.cacheHeader);
+                res.send(file);
+            }
+            catch (e) {
+                const err = new Error("File not found");
+                err.status = 404;
+                return next(err);
+            }
+        };
+    }
+    /**
+     * If an exception was thrown by the first handler, then it may be because a transformed image
+     * is being requested which does not yet exist. In this case, this handler will generate the
+     * transformed image, save it to cache, and serve the result as a response.
+     */
+    generateTransformedImage() {
+        return async (err, req, res, next) => {
+            var _a;
+            if (err && (err.status === 404 || err.statusCode === 404)) {
+                if (req.query) {
+                    const decodedReqPath = decodeURIComponent(req.path);
+                    core_1.Logger.debug(`Pre-cached Asset not found: ${decodedReqPath}`, constants_1.loggerCtx);
+                    let file;
+                    try {
+                        file =
+                            await AssetServerPlugin_1.assetStorage.readFileToBuffer(decodedReqPath);
+                    }
+                    catch (_err) {
+                        res.status(404).send("Resource not found");
+                        return;
+                    }
+                    const image = await (0, transform_image_1.transformImage)(file, req.query, this.presets || []);
+                    try {
+                        const imageBuffer = await image.toBuffer();
+                        const cachedFileName = this.getFileNameFromRequest(req);
+                        if (!req.query.cache || req.query.cache === "true") {
+                            await AssetServerPlugin_1.assetStorage.writeFileFromBuffer(cachedFileName, imageBuffer);
+                            core_1.Logger.debug(`Saved cached asset: ${cachedFileName}`, constants_1.loggerCtx);
+                        }
+                        let mimeType = this.getMimeType(cachedFileName);
+                        if (!mimeType) {
+                            mimeType = ((_a = (await getFileType(imageBuffer))) === null || _a === void 0 ? void 0 : _a.mime) || "image/jpeg";
+                        }
+                        res.set("Content-Type", mimeType);
+                        res.setHeader("content-security-policy", "default-src 'self'");
+                        res.send(imageBuffer);
+                        return;
+                    }
+                    catch (e) {
+                        core_1.Logger.error(e, constants_1.loggerCtx, e.stack);
+                        res.status(500).send(e.message);
+                        return;
+                    }
+                }
+            }
+            next();
+        };
+    }
+    getFileNameFromRequest(req) {
+        const { w, h, mode, preset, fpx, fpy, format, q } = req.query;
+        const focalPoint = fpx && fpy ? `_fpx${fpx}_fpy${fpy}` : "";
+        const quality = q ? `_q${q}` : "";
+        const imageFormat = (0, common_1.getValidFormat)(format);
+        let imageParamsString = "";
+        if (w || h) {
+            const width = w || "";
+            const height = h || "";
+            imageParamsString = `_transform_w${width}_h${height}_m${mode}`;
+        }
+        else if (preset) {
+            if (this.presets && !!this.presets.find((p) => p.name === preset)) {
+                imageParamsString = `_transform_pre_${preset}`;
+            }
+        }
+        if (focalPoint) {
+            imageParamsString += focalPoint;
+        }
+        if (imageFormat) {
+            imageParamsString += imageFormat;
+        }
+        if (quality) {
+            imageParamsString += quality;
+        }
+        const decodedReqPath = decodeURIComponent(req.path);
+        if (imageParamsString !== "") {
+            const imageParamHash = this.md5(imageParamsString);
+            return path_1.default.join(this.cacheDir, this.addSuffix(decodedReqPath, imageParamHash, imageFormat));
+        }
+        else {
+            return decodedReqPath;
+        }
+    }
+    md5(input) {
+        return (0, crypto_1.createHash)("md5").update(input).digest("hex");
+    }
+    addSuffix(fileName, suffix, ext) {
+        const originalExt = path_1.default.extname(fileName);
+        const effectiveExt = ext ? `.${ext}` : originalExt;
+        const baseName = path_1.default.basename(fileName, originalExt);
+        const dirName = path_1.default.dirname(fileName);
+        return path_1.default.join(dirName, `${baseName}${suffix}${effectiveExt}`);
+    }
+    /**
+     * Attempt to get the mime type from the file name.
+     */
+    getMimeType(fileName) {
+        const ext = path_1.default.extname(fileName);
+        switch (ext) {
+            case ".jpg":
+            case ".jpeg":
+                return "image/jpeg";
+            case ".png":
+                return "image/png";
+            case ".gif":
+                return "image/gif";
+            case ".svg":
+                return "image/svg+xml";
+            case ".tiff":
+                return "image/tiff";
+            case ".webp":
+                return "image/webp";
+        }
+    }
+};
+exports.AssetServerPlugin = AssetServerPlugin;
+exports.AssetServerPlugin = AssetServerPlugin = AssetServerPlugin_1 = __decorate([
+    (0, core_1.DeenruvPlugin)({
+        imports: [core_1.PluginCommonModule],
+        configuration: (config) => AssetServerPlugin.configure(config),
+        compatibility: "^0.0.0",
+    }),
+    __metadata("design:paramtypes", [core_1.ProcessContext])
+], AssetServerPlugin);
+//# sourceMappingURL=plugin.js.map

package/lib/src/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/plugin.ts"],"names":[],"mappings":"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"}

package/lib/src/s3-asset-storage-strategy.d.ts

@@ -0,0 +1,159 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import { AwsCredentialIdentity, AwsCredentialIdentityProvider } from "@aws-sdk/types";
+import { AssetStorageStrategy } from "@deenruv/core";
+import { Request } from "express";
+import { Readable } from "node:stream";
+import { AssetServerOptions } from "./types";
+/**
+ * @description
+ * Configuration for connecting to AWS S3.
+ *
+ * @docsCategory core plugins/AssetServerPlugin
+ * @docsPage S3AssetStorageStrategy
+ */
+export interface S3Config {
+    /**
+     * @description
+     * The credentials used to access your s3 account. You can supply either the access key ID & secret, or you can make use of a
+     * [shared credentials file](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-shared.html)
+     * To use a shared credentials file, import the `fromIni()` function from the "@aws-sdk/credential-provider-ini" or "@aws-sdk/credential-providers" package and supply
+     * the profile name (e.g. `{ profile: 'default' }`) as its argument.
+     */
+    credentials: AwsCredentialIdentity | AwsCredentialIdentityProvider;
+    /**
+     * @description
+     * The S3 bucket in which to store the assets. If it does not exist, it will be created on startup.
+     */
+    bucket: string;
+    /**
+     * @description
+     * Configuration object passed directly to the AWS SDK.
+     * S3.Types.ClientConfiguration can be used after importing aws-sdk.
+     * Using type `any` in order to avoid the need to include `aws-sdk` dependency in general.
+     */
+    nativeS3Configuration?: any;
+    /**
+     * @description
+     * Configuration object passed directly to the AWS SDK.
+     * ManagedUpload.ManagedUploadOptions can be used after importing aws-sdk.
+     * Using type `any` in order to avoid the need to include `aws-sdk` dependency in general.
+     */
+    nativeS3UploadConfiguration?: any;
+}
+/**
+ * @description
+ * Returns a configured instance of the {@link S3AssetStorageStrategy} which can then be passed to the {@link AssetServerOptions}
+ * `storageStrategyFactory` property.
+ *
+ * Before using this strategy, make sure you have the `@aws-sdk/client-s3` and `@aws-sdk/lib-storage` package installed:
+ *
+ * ```sh
+ * npm install \@aws-sdk/client-s3 \@aws-sdk/lib-storage
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { AssetServerPlugin, configureS3AssetStorage } from '\@deenruv/asset-server-plugin';
+ * import { DefaultAssetNamingStrategy } from '\@deenruv/core';
+ * import { fromEnv } from '\@aws-sdk/credential-providers';
+ *
+ * // ...
+ *
+ * plugins: [
+ *   AssetServerPlugin.init({
+ *     route: 'assets',
+ *     assetUploadDir: path.join(__dirname, 'assets'),
+ *     namingStrategy: new DefaultAssetNamingStrategy(),
+ *     storageStrategyFactory: configureS3AssetStorage({
+ *       bucket: 'my-s3-bucket',
+ *       credentials: fromEnv(), // or any other credential provider
+ *       nativeS3Configuration: {
+ *         region: process.env.AWS_REGION,
+ *       },
+ *     }),
+ * }),
+ * ```
+ *
+ * ## Usage with MinIO
+ *
+ * Reference: [How to use AWS SDK for Javascript with MinIO Server](https://docs.min.io/docs/how-to-use-aws-sdk-for-javascript-with-minio-server.html)
+ *
+ * @example
+ * ```ts
+ * import { AssetServerPlugin, configureS3AssetStorage } from '\@deenruv/asset-server-plugin';
+ * import { DefaultAssetNamingStrategy } from '\@deenruv/core';
+ *
+ * // ...
+ *
+ * plugins: [
+ *   AssetServerPlugin.init({
+ *     route: 'assets',
+ *     assetUploadDir: path.join(__dirname, 'assets'),
+ *     namingStrategy: new DefaultAssetNamingStrategy(),
+ *     storageStrategyFactory: configureS3AssetStorage({
+ *       bucket: 'my-minio-bucket',
+ *       credentials: {
+ *         accessKeyId: process.env.MINIO_ACCESS_KEY_ID,
+ *         secretAccessKey: process.env.MINIO_SECRET_ACCESS_KEY,
+ *       },
+ *       nativeS3Configuration: {
+ *         endpoint: process.env.MINIO_ENDPOINT ?? 'http://localhost:9000',
+ *         forcePathStyle: true,
+ *         signatureVersion: 'v4',
+ *         // The `region` is required by the AWS SDK even when using MinIO,
+ *         // so we just use a dummy value here.
+ *         region: 'eu-west-1',
+ *       },
+ *     }),
+ * }),
+ * ```
+ * @docsCategory core plugins/AssetServerPlugin
+ * @docsPage S3AssetStorageStrategy
+ */
+export declare function configureS3AssetStorage(s3Config: S3Config): (options: AssetServerOptions) => S3AssetStorageStrategy;
+/**
+ * @description
+ * An {@link AssetStorageStrategy} which uses [Amazon S3](https://aws.amazon.com/s3/) object storage service.
+ * To us this strategy you must first have access to an AWS account.
+ * See their [getting started guide](https://aws.amazon.com/s3/getting-started/) for how to get set up.
+ *
+ * Before using this strategy, make sure you have the `@aws-sdk/client-s3` and `@aws-sdk/lib-storage` package installed:
+ *
+ * ```sh
+ * npm install \@aws-sdk/client-s3 \@aws-sdk/lib-storage
+ * ```
+ *
+ * **Note:** Rather than instantiating this manually, use the {@link configureS3AssetStorage} function.
+ *
+ * ## Use with S3-compatible services (MinIO)
+ * This strategy will also work with any S3-compatible object storage solutions, such as [MinIO](https://min.io/).
+ * See the {@link configureS3AssetStorage} for an example with MinIO.
+ *
+ * @docsCategory asset-server-plugin
+ * @docsPage S3AssetStorageStrategy
+ * @docsWeight 0
+ */
+export declare class S3AssetStorageStrategy implements AssetStorageStrategy {
+    private s3Config;
+    readonly toAbsoluteUrl: (request: Request, identifier: string) => string;
+    private AWS;
+    private libStorage;
+    private s3Client;
+    constructor(s3Config: S3Config, toAbsoluteUrl: (request: Request, identifier: string) => string);
+    init(): Promise<void>;
+    destroy?: (() => void | Promise<void>) | undefined;
+    writeFileFromBuffer(fileName: string, data: Buffer): Promise<string>;
+    writeFileFromStream(fileName: string, data: Readable): Promise<string>;
+    readFileToBuffer(identifier: string): Promise<Buffer>;
+    readFileToStream(identifier: string): Promise<Readable>;
+    private readFile;
+    private writeFile;
+    deleteFile(identifier: string): Promise<void>;
+    fileExists(fileName: string): Promise<boolean>;
+    private getObjectParams;
+    private ensureBucket;
+    private getCredentials;
+    private isCredentialsProfile;
+}