@autofleet/super-express 2.0.0 → 2.2.0

package/.nvmrc

@@ -0,0 +1 @@
+20.15.0

package/README.md

@@ -0,0 +1,119 @@
+
+# SuperExpress
+
+SuperExpress is an enhanced Express.js server application with built-in middleware for logging, security, health checks, and more. This project aims to provide a ready-to-use Express.js server setup with configurable options.
+
+## Features
+
+- **Logging**: Uses Morgan for HTTP request logging.
+- **Security**: Adds various security headers.
+- **Body Parsing**: Configurable body parser with a high payload limit.
+- **Health Checks**: An endpoint to check if the server is alive.
+- **Stats Endpoint**: Provides server and application statistics.
+- **Tracing**: Supports request tracing.
+
+## Installation
+
+To install the dependencies, run:
+
+```bash
+npm install
+```
+
+## Usage
+
+### Importing and Initializing
+
+To use SuperExpress, you need to import and initialize it in your application:
+
+```javascript
+import createSuperExpressApp from './index.js';
+
+const options = {
+    bodyParser: true,
+    helmet: true,
+    morgan: true,
+    nitur: true,
+    stats: true,
+    packageJsonPath: './package.json',
+    tracing: true,
+    eagerLoadUserPermissions: true,
+    aliveEndpointOptions: { customOption: 'value' }
+};
+
+const app = await createSuperExpressApp(options);
+
+app.listen(3000, () => {
+    console.log('Server is running on port 3000');
+});
+```
+
+### Options
+
+You can customize the behavior of SuperExpress by passing an options object:
+
+- `bodyParser` (boolean): Enables or disables the body parser middleware.
+- `helmet` (boolean): Enables or disables security headers.
+- `morgan` (boolean): Enables or disables HTTP request logging.
+- `nitur` (boolean): Enables or disables the alive endpoint.
+- `stats` (boolean): Enables or disables the stats endpoint.
+- `packageJsonPath` (string): Path to the `package.json` file for the stats endpoint.
+- `tracing` (boolean): Enables or disables request tracing.
+- `eagerLoadUserPermissions` (boolean): Enables or disables eager loading of user permissions for tracing middleware.
+- `aliveEndpointOptions` (object): Options to customize the alive endpoint.
+
+## Endpoints
+
+### Alive Endpoint
+
+- **Path**: `/alive`
+- **Method**: `GET`
+- **Description**: Checks if the server is alive.
+
+### Stats Endpoint
+
+- **Path**: `/`
+- **Method**: `GET`
+- **Description**: Provides server and application statistics.
+
+## Tests
+
+This project uses Node.js's built-in test runner for testing. To run the tests, execute:
+
+```bash
+node --test index.test.js
+```
+
+## Example
+
+Here's an example of how to set up and run the server:
+
+```javascript
+import createSuperExpressApp from './index.js';
+
+const options = {
+    bodyParser: true,
+    helmet: true,
+    morgan: true,
+    nitur: true,
+    stats: true,
+    packageJsonPath: './package.json',
+    tracing: true,
+    eagerLoadUserPermissions: true,
+    aliveEndpointOptions: { customOption: 'value' }
+};
+
+const app = await createSuperExpressApp(options);
+
+app.listen(3000, () => {
+    console.log('Server is running on port 3000');
+});
+```
+
+## Contributing
+
+Feel free to submit issues or pull requests. Contributions are welcome!
+
+## License
+
+This project is licensed under the MIT License.

package/config/default-options.json

@@ -0,0 +1,10 @@
+{
+    "bodyParser": true,
+    "compression": true,
+    "helmet": true,
+    "morgan": true,
+    "nitur": true,
+    "stats": true,
+    "tracing": true,
+    "eagerLoadUserPermissions": true
+}

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "@autofleet/super-express",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "AF Express with built in boilerplate",
-  "main": "index.js",
+  "main": "src/index.js",
   "type": "module",
   "author": "Autofleet",
   "license": "MIT",
   "dependencies": {
+    "@autofleet/nitur": "^1.3.4",
+    "@autofleet/zehut": "^3.0.10",
     "express": "^4.19.2",
-    "helmet": "^3.21.2",
-    "morgan": "^1.9.1"
+    "morgan": "^1.10.0"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test test/index.test.js",
+    "publish": "npm publish"
   },
   "repository": {
     "type": "git",
@@ -24,6 +26,6 @@
   "homepage": "https://github.com/Autofleet/super-express#readme",
   "devDependencies": {
     "@types/express": "^4.17.21",
-    "@types/helmet": "^4.0.0"
+    "supertest": "^7.0.0"
   }
 }

package/src/index.d.ts

@@ -0,0 +1,77 @@
+import express from 'express';
+
+/**
+ * Options to customize the behavior of the SuperExpress application.
+ */
+export type DefaultOptions = {
+    /**
+     * Enables or disables body parser middleware.
+     */
+    bodyParser?: boolean;
+    /**
+     * Enables or disables security headers middleware.
+     */
+    helmet?: boolean;
+    /**
+     * Enables or disables HTTP request logging middleware.
+     */
+    morgan?: boolean;
+    /**
+     * Enables or disables the alive endpoint middleware.
+     */
+    nitur?: boolean;
+    /**
+     * Enables or disables the stats endpoint middleware.
+     */
+    stats?: boolean;
+    /**
+     * Path to the package.json file for the stats endpoint.
+     */
+    packageJsonPath?: string;
+    /**
+     * Enables or disables request tracing middleware.
+     */
+    tracing?: boolean;
+    /**
+     * Enables or disables eager loading of user permissions for tracing middleware.
+     */
+    eagerLoadUserPermissions?: boolean;
+    /**
+     * Options to customize the alive endpoint middleware.
+     */
+    aliveEndpointOptions?: Record<string, unknown>;
+    // Add other options from config/default-options.json as needed
+};
+
+/**
+ * Type for the callback function used in the listen method.
+ */
+type ListenCallback = () => void;
+
+type Listen = express.Application['listen'];
+type Server = Listen extends (port: any, cb: any) => infer R ? R : never;
+/**
+ * Extends the express.Application interface to include nativeListen and the overridden listen method.
+ */
+export interface SuperExpressApp extends express.Application {
+    /**
+     * Original express listen method.
+     */
+    nativeListen: Listen;
+
+    /**
+     * Overridden listen method to add custom behavior.
+     * @param port - The port number to listen on.
+     * @param cb - Optional callback function to execute after the server starts listening.
+     */
+    listen(port: number, cb?: ListenCallback): Server;
+}
+
+/**
+ * Creates a new SuperExpress application with the given options.
+ * @param options - Optional settings to customize the application.
+ * @returns A SuperExpress application instance.
+ */
+export default function createSuperExpressApp(
+    options?: Partial<DefaultOptions & express.ApplicationOptions>
+): SuperExpressApp;

package/src/index.js

@@ -0,0 +1,87 @@
+import express from 'express';
+import morgan from 'morgan';
+import { aliveEndpoint } from '@autofleet/nitur';
+import zehut, { enableTracing } from '@autofleet/zehut';
+
+import defaultOptions from '../config/default-options.json' assert { type: "json" };
+
+export default function (options = {}) {
+    const app = express(options);
+    const mergedOptions = Object.assign({}, defaultOptions, options);
+    /** Formatting */
+    if (mergedOptions.morgan) {
+        app.use(morgan(':method :url :status :res[content-length] - :response-time ms'));
+    }
+    /** Security */
+    if (mergedOptions.helmet) {
+        // this is what helmet does by default. https://helmetjs.github.io/faq/you-might-not-need-helmet/
+        const HEADERS = {
+            "Content-Security-Policy":
+                "default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests",
+            "Cross-Origin-Opener-Policy": "same-origin",
+            "Cross-Origin-Resource-Policy": "same-origin",
+            "Origin-Agent-Cluster": "?1",
+            "Referrer-Policy": "no-referrer",
+            "Strict-Transport-Security": "max-age=15552000; includeSubDomains",
+            "X-Content-Type-Options": "nosniff",
+            "X-DNS-Prefetch-Control": "off",
+            "X-Download-Options": "noopen",
+            "X-Frame-Options": "SAMEORIGIN",
+            "X-Permitted-Cross-Domain-Policies": "none",
+            "X-XSS-Protection": "0",
+        };
+        app.use((req, res, next) => {
+            res.set(HEADERS);
+            next();
+        });
+        app.disable('x-powered-by');
+    }
+    /** Body Parser */
+    if (mergedOptions.bodyParser) {
+        app.use(express.json({ limit: '1000mb' }))
+    } else {
+        console.log('[SuperExpress] Body parser is disabled');
+    }
+    /** Alive Endpoint */
+    if (mergedOptions.nitur) {
+        app.get('/alive', aliveEndpoint(mergedOptions.aliveEndpointOptions || {}));
+    }
+    /** Stats Endpoint */
+    if (mergedOptions.stats && mergedOptions.packageJsonPath) {
+        const serverRunningSince = new Date();
+        import(mergedOptions.packageJsonPath, { assert: { type: 'json' } })
+            .then(module => {
+                const packageJson = module.default;
+                app.get('/', (req, res) => {
+                    res.json({
+                        name: packageJson.name,
+                        version: packageJson.version,
+                        commit: packageJson.commit,
+                        serverRunningSince,
+                    });
+                });
+            });
+    }
+    /** Tracing */
+    if (mergedOptions.tracing) {
+        enableTracing({
+            outbreakOptions: {
+                headersPrefix: 'x-af',
+            },
+        });
+
+        app.use(zehut.middleware({
+            eagerLoadUserPermissions: mergedOptions.eagerLoadUserPermissions,
+        }));
+    }
+
+    app.nativeListen = app.listen
+    app.listen = function (port, cb) {
+        const isProd = process.env.NODE_ENV === 'production';
+        console.log(`[SuperExpress] will listen on port ${port}`);
+        console.log(`[SuperExpress] Production mode: ${isProd}`);
+        return app.nativeListen(port, cb)
+    }
+
+    return app
+};

package/test/index.test.js

@@ -0,0 +1,94 @@
+// index.test.js
+import { strict as assert } from 'assert';
+import { test } from 'node:test';
+import supertest from 'supertest';
+import createSuperExpressApp from '../src/index.js';
+import fs from 'fs';
+import path, { dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Mock the package.json file content
+const mockPackageJson = {
+    name: 'test-package',
+    version: '1.0.0',
+    commit: 'abcdef123456'
+};
+
+// Mock the default-options.json file content
+const defaultOptions = {
+    bodyParser: true,
+    helmet: true,
+    morgan: true,
+    nitur: true,
+    stats: true,
+    packageJsonPath: '../test/mock-package.json',
+    tracing: true,
+    eagerLoadUserPermissions: true,
+    aliveEndpointOptions: { customOption: 'value' }
+};
+
+// Write the mock package.json file to disk
+fs.writeFileSync(path.resolve(__dirname, './mock-package.json'), JSON.stringify(mockPackageJson));
+
+// Test for the existence of default middleware
+test('should create an app with default middleware', async () => {
+    const app = createSuperExpressApp();
+
+    // Test for the existence of bodyParser middleware
+    await supertest(app)
+        .post('/')
+        .send({ key: 'value' })
+        .expect(404); // Expect 404 because no routes are defined
+
+    // Test for the overridden listen method
+    const originalConsoleLog = console.log;
+    let logOutput = [];
+    console.log = (...args) => logOutput.push(...args);
+    const server = app.listen(3000, () => {});
+    assert(logOutput.includes('[SuperExpress] will listen on port 3000'));
+
+    console.log = originalConsoleLog;
+    server.close();
+});
+
+// Test for custom options
+test('should create an app with custom options', async () => {
+    const app = createSuperExpressApp(defaultOptions);
+
+    // Test for the alive endpoint
+    await supertest(app)
+        .get('/alive')
+        .expect(200);
+
+    // Test for the stats endpoint
+    await supertest(app)
+        .get('/')
+        .expect(200)
+        .expect((res) => {
+            assert(res.body.name);
+            assert(res.body.version);
+            assert(res.body.serverRunningSince);
+        });
+});
+
+// Test for disabled body parser
+test('should disable body parser when option is set to false', async () => {
+    const originalConsoleLog = console.log;
+    let logOutput = [];
+    console.log = (...args) => logOutput.push(...args);
+
+    const app = createSuperExpressApp({ bodyParser: false });
+
+
+    await supertest(app)
+        .post('/')
+        .send({ key: 'value' })
+        .expect(404);
+
+    assert(logOutput.includes('[SuperExpress] Body parser is disabled'));
+
+    console.log = originalConsoleLog;
+});

package/test/mock-package.json

@@ -0,0 +1 @@
+{"name":"test-package","version":"1.0.0","commit":"abcdef123456"}

package/default-options.json

@@ -1,5 +0,0 @@
-{
-    "bodyParser": true,
-    "compression": true,
-    "helmet": true
-}

package/index.js

@@ -1,28 +0,0 @@
-import express from 'express';
-import helmet from 'helmet';
-import morgan from 'morgan';
-
-import defaultOptions from './default-options.json';
-
-export default function(options = {}) {
-    const app = express(options);
-    const isProd = process.env.NODE_ENV === 'production';
-    const mergedOptions = Object.assign({}, defaultOptions, options);
-
-    app.use(morgan(':method :url :status :res[content-length] - :response-time ms'));
-    app.use(helmet());
-    if (mergedOptions.bodyParser) {
-        app.use(express.json({ limit: '1000mb' }))
-    } else {
-        console.log('[SuperExpress] Body parser is disabled');
-    }
-
-    app.nativeListen = app.listen
-    app.listen = function (port, cb) {
-        console.log(`[SuperExpress] will listen on port ${port}`);
-        console.log(`[SuperExpress] Production mode: ${isProd}`);
-        app.nativeListen(port, cb)
-    }
-
-    return app
-};