@unito/integration-sdk 0.1.7 → 0.1.8

package/src/httpErrors.ts

@@ -31,20 +31,20 @@ export class TimeoutError extends HttpError {
   }
 }
 
-export class UnprocessableEntityError extends HttpError {
+export class ResourceGoneError extends HttpError {
   constructor(message?: string) {
-    super(message || 'Unprocessable Entity', 422);
+    super(message || 'Resource gone or unavailable', 410);
   }
 }
 
-export class RateLimitExceededError extends HttpError {
+export class UnprocessableEntityError extends HttpError {
   constructor(message?: string) {
-    super(message || 'Rate Limit Exceeded', 429);
+    super(message || 'Unprocessable Entity', 422);
   }
 }
 
-export class WouldExceedLimitError extends HttpError {
+export class RateLimitExceededError extends HttpError {
   constructor(message?: string) {
-    super(message || 'Would Exceed Limit', 429);
+    super(message || 'Rate Limit Exceeded', 429);
   }
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 /* c8 ignore start */
 export * as Api from '@unito/integration-api';
+export { Cache } from './resources/cache.js';
 export { default as Integration } from './integration.js';
 export * from './handler.js';
 export {

package/src/integration.ts

@@ -9,7 +9,7 @@ import selectsMiddleware from './middlewares/selects.js';
 import errorsMiddleware from './middlewares/errors.js';
 import finishMiddleware from './middlewares/finish.js';
 import notFoundMiddleware from './middlewares/notFound.js';
-import { initializeCache, Cache } from './resources/cache.js';
+import { shutdownCaches } from './resources/cache.js';
 import { HandlersInput, Handler } from './handler.js';
 
 function printErrorMessage(message: string) {
@@ -27,8 +27,6 @@ export default class Integration {
 
   private instance: Server<typeof IncomingMessage, typeof ServerResponse> | undefined = undefined;
 
-  private cache: Cache | undefined = undefined;
-
   private port: number;
 
   constructor(options: Options = {}) {
@@ -69,9 +67,6 @@ export default class Integration {
   }
 
   public start() {
-    // Initialize the cache.
-    this.cache = initializeCache();
-
     // Express Server initialization
     const app: express.Application = express();
 
@@ -121,9 +116,7 @@ export default class Integration {
             this.instance.close();
           }
 
-          if (this.cache) {
-            await this.cache.quit();
-          }
+          await shutdownCaches();
         } catch (e) {
           console.error('Failed to gracefully exit', e);
         }

package/src/middlewares/errors.ts

@@ -1,30 +1,55 @@
 import { Request, Response, NextFunction } from 'express';
-import { Error as APIError } from '@unito/integration-api';
+import { Error as ApiError } from '@unito/integration-api';
+
 import { HttpError } from '../httpErrors.js';
 
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Locals {
+      error?: ApiError;
+    }
+  }
+}
+
 const middleware = (err: Error, _req: Request, res: Response, next: NextFunction) => {
   if (res.headersSent) {
     return next(err);
   }
 
-  if (process.env.NODE_ENV !== 'production') {
-    res.locals.logger.error(err);
-  }
+  let error: ApiError;
 
   if (err instanceof HttpError) {
-    return res.status(err.status).json(err.message);
+    error = {
+      code: err.status.toString(),
+      message: err.message,
+      details: {
+        stack: err.stack,
+      },
+    };
+  } else {
+    error = {
+      code: '500',
+      message: 'Oops! Something went wrong',
+      originalError: {
+        code: err.name,
+        message: err.message,
+        details: {
+          stack: err.stack,
+        },
+      },
+    };
   }
 
-  const originalError: APIError = {
-    code: err.name,
-    message: err.message,
-  };
+  res.locals.error = structuredClone(error);
+
+  // Keep the stack details in development for the Debugger
+  if (process.env.NODE_ENV !== 'development') {
+    delete error.details;
+    delete error.originalError?.details;
+  }
 
-  res.status(500).json({
-    code: '500',
-    message: 'Oops! Something went wrong',
-    originalError,
-  } as APIError);
+  res.status(Number(error.code)).json(error);
 };
 
 export default middleware;

package/src/middlewares/finish.ts

@@ -1,11 +1,13 @@
 import { Request, Response, NextFunction } from 'express';
-import Logger from '../resources/logger.js';
+import { Error as ApiError } from '@unito/integration-api';
+import { default as Logger, Metadata } from '../resources/logger.js';
 
 declare global {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace Express {
     interface Locals {
       logger: Logger;
+      error?: ApiError;
     }
   }
 }
@@ -13,8 +15,31 @@ declare global {
 const middleware = (req: Request, res: Response, next: NextFunction) => {
   if (req.originalUrl !== '/health') {
     res.on('finish', function () {
-      const loggerLevel = res.statusCode >= 500 ? 'error' : 'info';
-      res.locals.logger[loggerLevel](`${req.method} ${req.originalUrl} ${res.statusCode}`);
+      const error = res.locals.error;
+
+      const message = `${req.method} ${req.originalUrl} ${res.statusCode}`;
+      const metadata: Metadata = {
+        // Use reserved and standard attributes of Datadog
+        // https://app.datadoghq.com/logs/pipelines/standard-attributes
+        http: { method: req.method, status_code: res.statusCode, url_details: { path: req.originalUrl } },
+        ...(error
+          ? {
+              error: {
+                kind: error.message,
+                stack: (error.originalError?.details?.stack ?? error.details?.stack) as string,
+                message: error.originalError?.message ?? error.message,
+              },
+            }
+          : {}),
+      };
+
+      if ([404, 429].includes(res.statusCode)) {
+        res.locals.logger.warn(message, metadata);
+      } else if (res.statusCode >= 400) {
+        res.locals.logger.error(message, metadata);
+      } else {
+        res.locals.logger.info(message, metadata);
+      }
     });
   }
 

package/src/resources/cache.ts

@@ -1,34 +1,77 @@
-import { WriteThroughCache, LocalCache, CacheInstance } from 'cachette';
-import { createHash } from 'node:crypto';
+import { WriteThroughCache, LocalCache, CacheInstance, FetchingFunction, CachableValue } from 'cachette';
 import * as uuid from 'uuid';
 import Logger from './logger.js';
 
-export type Cache = CacheInstance;
+/**
+ * Array of created caches kept to allow for graceful shutdown on exit signals.
+ */
+const caches: CacheInstance[] = [];
 
-export function initializeCache(): Cache {
-  const cacheInstance: Cache = process.env.REDIS_URL ? new WriteThroughCache(process.env.REDIS_URL) : new LocalCache();
+export const shutdownCaches = async () => {
+  return Promise.allSettled(caches.map(cache => cache.quit()));
+};
 
-  // Intended: the correlation id will be the same for all logs of Cachette.
-  const correlationId = uuid.v4();
+export class Cache {
+  private cacheInstance: CacheInstance;
 
-  const logger = new Logger({ correlation_id: correlationId });
+  private constructor(cacheInstance: CacheInstance) {
+    this.cacheInstance = cacheInstance;
+  }
 
-  cacheInstance
-    .on('info', message => {
-      logger.info(message);
-    })
-    .on('warn', message => {
-      logger.warn(message);
-    })
-    .on('error', message => {
-      logger.error(message);
-    });
+  public getOrFetchValue<F extends FetchingFunction = FetchingFunction>(
+    key: string,
+    ttl: number,
+    fetcher: F,
+    lockTtl?: number,
+    shouldCacheError?: (err: Error) => boolean,
+  ): Promise<ReturnType<F>> {
+    return this.cacheInstance.getOrFetchValue(key, ttl, fetcher, lockTtl, shouldCacheError);
+  }
 
-  return cacheInstance;
-}
+  public getValue(key: string): Promise<CachableValue> {
+    return this.cacheInstance.getValue(key);
+  }
+
+  public setValue(key: string, value: CachableValue, ttl?: number): Promise<boolean> {
+    return this.cacheInstance.setValue(key, value, ttl);
+  }
+
+  public delValue(key: string): Promise<void> {
+    return this.cacheInstance.delValue(key);
+  }
+
+  public getTtl(key: string): Promise<number | undefined> {
+    return this.cacheInstance.getTtl(key);
+  }
+
+  /**
+   * Initializes a WriteThroughCache instance with the provided redis url if present, or a LocalCache otherwise.
+   *
+   * @param redisUrl - The redis url to connect to (optional).
+   * @returns A cache instance.
+   */
+  public static create(redisUrl?: string): Cache {
+    const cacheInstance: CacheInstance = redisUrl ? new WriteThroughCache(redisUrl) : new LocalCache();
+
+    // Push to the array of caches for graceful shutdown on exit signals.
+    caches.push(cacheInstance);
+
+    // Intended: the correlation id will be the same for all logs of Cachette.
+    const correlationId = uuid.v4();
+
+    const logger = new Logger({ correlation_id: correlationId });
 
-const shake256 = createHash('shake256');
+    cacheInstance
+      .on('info', message => {
+        logger.info(message);
+      })
+      .on('warn', message => {
+        logger.warn(message);
+      })
+      .on('error', message => {
+        logger.error(message);
+      });
 
-export function generateCacheKey(value: string): string {
-  return shake256.update(value).digest('hex');
+    return new Cache(cacheInstance);
+  }
 }

package/src/resources/logger.ts

@@ -1,4 +1,4 @@
-enum LogLevel {
+const enum LogLevel {
   ERROR = 'error',
   WARN = 'warn',
   INFO = 'info',
@@ -6,52 +6,112 @@ enum LogLevel {
   DEBUG = 'debug',
 }
 
-export default class Logger {
-  private metadata: Record<string, unknown> = {};
+type PrimitiveValue = undefined | null | string | string[] | number | number[] | boolean | boolean[];
+type Value = {
+  [key: string]: PrimitiveValue | Value;
+};
 
-  constructor(metadata?: Record<string, unknown>) {
-    if (metadata) {
-      this.metadata = structuredClone(metadata);
-    }
-  }
+export type Metadata = Value & { message?: never };
+type ForbidenMetadataKey = 'message';
 
-  private send(logLevel: LogLevel, message: unknown) {
-    console[logLevel](JSON.stringify({ message, ...this.metadata }));
+export default class Logger {
+  private metadata: Metadata;
+
+  constructor(metadata: Metadata = {}) {
+    this.metadata = structuredClone(metadata);
   }
 
-  public log(data: unknown) {
-    this.send(LogLevel.LOG, data);
+  /**
+   * Logs a message with the 'log' log level.
+   * @param message The message to be logged.
+   * @param metadata Optional metadata to be associated with the log message.
+   */
+  public log(message: string, metadata?: Metadata): void {
+    this.send(LogLevel.LOG, message, metadata);
   }
 
-  public error(data: unknown) {
-    this.send(LogLevel.ERROR, data);
+  /**
+   * Logs an error message with the 'error' log level.
+   * @param message The error message to be logged.
+   * @param metadata Optional metadata to be associated with the log message.
+   */
+  public error(message: string, metadata?: Metadata): void {
+    this.send(LogLevel.ERROR, message, metadata);
   }
 
-  public warn(data: unknown) {
-    this.send(LogLevel.WARN, data);
+  /**
+   * Logs a warning message with the 'warn' log level.
+   * @param message The warning message to be logged.
+   * @param metadata Optional metadata to be associated with the log message.
+   */
+  public warn(message: string, metadata?: Metadata): void {
+    this.send(LogLevel.WARN, message, metadata);
   }
 
-  public info(data: unknown) {
-    this.send(LogLevel.INFO, data);
+  /**
+   * Logs an informational message with the 'info' log level.
+   * @param message The informational message to be logged.
+   * @param metadata Optional metadata to be associated with the log message.
+   */
+  public info(message: string, metadata?: Metadata): void {
+    this.send(LogLevel.INFO, message, metadata);
   }
 
-  public debug(data: unknown) {
-    this.send(LogLevel.DEBUG, data);
+  /**
+   * Logs a debug message with the 'debug' log level.
+   * @param message The debug message to be logged.
+   * @param metadata Optional metadata to be associated with the log message.
+   */
+  public debug(message: string, metadata?: Metadata): void {
+    this.send(LogLevel.DEBUG, message, metadata);
   }
 
-  public decorate(metadata: Record<string, unknown>) {
+  /**
+   * Decorates the logger with additional metadata.
+   * @param metadata Additional metadata to be added to the logger.
+   */
+  public decorate(metadata: Metadata): void {
     this.metadata = { ...this.metadata, ...metadata };
   }
 
-  public getMetadata() {
+  public getMetadata(): Metadata {
     return structuredClone(this.metadata);
   }
 
-  public setMetadata(key: string, value: unknown) {
+  public setMetadata<Key extends string>(
+    key: Key extends ForbidenMetadataKey ? never : Key,
+    value: PrimitiveValue | Value,
+  ): void {
     this.metadata[key] = value;
   }
 
-  public clearMetadata() {
+  public clearMetadata(): void {
     this.metadata = {};
   }
+
+  private send(logLevel: LogLevel, message: string, metadata?: Metadata): void {
+    const processedMessage = this.snakifyKeys({
+      ...this.metadata,
+      ...metadata,
+      message,
+    });
+
+    if (process.env.NODE_ENV === 'development') {
+      console[logLevel](JSON.stringify(processedMessage, null, 2));
+    } else {
+      console[logLevel](JSON.stringify(processedMessage));
+    }
+  }
+
+  private snakifyKeys<T extends Value>(value: T): T {
+    const result: Value = {};
+
+    for (const key in value) {
+      const deepValue = typeof value[key] === 'object' ? this.snakifyKeys(value[key] as Value) : value[key];
+      const snakifiedKey = key.replace(/[\w](?<!_)([A-Z])/g, k => `${k[0]}_${k[1]}`).toLowerCase();
+      result[snakifiedKey] = deepValue;
+    }
+
+    return result as T;
+  }
 }

package/test/errors.test.ts

@@ -9,6 +9,7 @@ describe('handleErrorResponse', () => {
     assert.ok(errors.buildHttpError(403, 'forbidden') instanceof httpErrors.UnauthorizedError);
     assert.ok(errors.buildHttpError(404, 'not found') instanceof httpErrors.NotFoundError);
     assert.ok(errors.buildHttpError(408, 'timeout') instanceof httpErrors.TimeoutError);
+    assert.ok(errors.buildHttpError(410, 'resource gone') instanceof httpErrors.ResourceGoneError);
     assert.ok(errors.buildHttpError(422, 'unprocessable entity') instanceof httpErrors.UnprocessableEntityError);
     assert.ok(errors.buildHttpError(429, 'rate limit exceeded') instanceof httpErrors.RateLimitExceededError);
     assert.ok(errors.buildHttpError(500, 'internal server error') instanceof httpErrors.HttpError);

package/test/middlewares/errors.test.ts

@@ -49,7 +49,7 @@ describe('errors middleware', () => {
     middleware(new HttpError('httpError', 429), {} as express.Request, response, () => {});
 
     assert.strictEqual(actualStatus, 429);
-    assert.strictEqual(actualJson, 'httpError');
+    assert.deepEqual(actualJson, { code: '429', message: 'httpError' });
   });
 
   it('handles other error', () => {

package/test/resources/cache.test.ts

@@ -1,31 +1,21 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import { LocalCache } from 'cachette';
-import { generateCacheKey, initializeCache } from '../../src/resources/cache.js';
+import { Cache, shutdownCaches } from '../../src/resources/cache.js';
 
 describe('Cache', () => {
   describe('initializeCache', () => {
-    it('no redis url returns LocalCache', () => {
-      const cache = initializeCache();
+    it('no redis url returns Cache with a inner LocalCache', async () => {
+      const cache = Cache.create();
 
-      assert.equal(cache instanceof LocalCache, true);
+      assert.ok(cache instanceof Cache);
+      assert.ok(cache['cacheInstance'] instanceof LocalCache);
 
-      cache.quit();
+      await shutdownCaches();
     });
 
     it('redis url returns (tries) WriteThroughCache', () => {
-      process.env.REDIS_URL = 'fakeredis'; //'redis://localhost:6379';
-      assert.throws(() => initializeCache(), Error, 'Invalid redis url fakereis.');
-    });
-  });
-
-  describe('generateCacheKey', () => {
-    it('hashes string and returns hex value', () => {
-      const value = 'test';
-      const hash = generateCacheKey(value);
-
-      assert.equal(typeof hash, 'string');
-      assert.equal(hash.length, 64);
+      assert.throws(() => Cache.create('fakeredis'), Error, 'Invalid redis url fakereis.');
     });
   });
 });

package/test/resources/logger.test.ts

@@ -1,10 +1,10 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
-import Logger from '../../src/resources/logger.js';
+import { default as Logger, Metadata } from '../../src/resources/logger.js';
 
 describe('Logger', () => {
   it('metadata', () => {
-    let metadata: Record<string, unknown> = { correlation_id: 'test' };
+    let metadata: Metadata = { correlation_id: 'test' };
     const logger = new Logger(metadata);
 
     // Changing initial object should not affect the logger
@@ -42,7 +42,7 @@ describe('Logger', () => {
     logger.log('test');
     assert.strictEqual(logSpy.mock.calls.length, 1);
     assert.deepEqual(logSpy.mock.calls[0]?.arguments, [
-      JSON.stringify({ message: 'test', correlation_id: '123456789' }),
+      JSON.stringify({ correlation_id: '123456789', message: 'test' }),
     ]);
 
     const errorSpy = testContext.mock.method(global.console, 'error', () => {});
@@ -50,7 +50,7 @@ describe('Logger', () => {
     logger.error('test');
     assert.strictEqual(errorSpy.mock.calls.length, 1);
     assert.deepEqual(errorSpy.mock.calls[0]?.arguments, [
-      JSON.stringify({ message: 'test', correlation_id: '123456789' }),
+      JSON.stringify({ correlation_id: '123456789', message: 'test' }),
     ]);
 
     const warnSpy = testContext.mock.method(global.console, 'warn', () => {});
@@ -58,7 +58,7 @@ describe('Logger', () => {
     logger.warn('test');
     assert.strictEqual(warnSpy.mock.calls.length, 1);
     assert.deepEqual(warnSpy.mock.calls[0]?.arguments, [
-      JSON.stringify({ message: 'test', correlation_id: '123456789' }),
+      JSON.stringify({ correlation_id: '123456789', message: 'test' }),
     ]);
 
     const infoSpy = testContext.mock.method(global.console, 'info', () => {});
@@ -66,7 +66,7 @@ describe('Logger', () => {
     logger.info('test');
     assert.strictEqual(infoSpy.mock.calls.length, 1);
     assert.deepEqual(infoSpy.mock.calls[0]?.arguments, [
-      JSON.stringify({ message: 'test', correlation_id: '123456789' }),
+      JSON.stringify({ correlation_id: '123456789', message: 'test' }),
     ]);
 
     const debugSpy = testContext.mock.method(global.console, 'debug', () => {});
@@ -74,7 +74,60 @@ describe('Logger', () => {
     logger.debug('test');
     assert.strictEqual(debugSpy.mock.calls.length, 1);
     assert.deepEqual(debugSpy.mock.calls[0]?.arguments, [
-      JSON.stringify({ message: 'test', correlation_id: '123456789' }),
+      JSON.stringify({ correlation_id: '123456789', message: 'test' }),
+    ]);
+  });
+
+  it('merges message payload with metadata', testContext => {
+    const metadata = { correlation_id: '123456789', http: { method: 'GET' } };
+    const logger = new Logger(metadata);
+
+    const logSpy = testContext.mock.method(global.console, 'log', () => {});
+    assert.strictEqual(logSpy.mock.calls.length, 0);
+    logger.log('test', { error: { code: '200', message: 'Page Not Found' } });
+    assert.strictEqual(logSpy.mock.calls.length, 1);
+    assert.deepEqual(logSpy.mock.calls[0]?.arguments, [
+      JSON.stringify({
+        correlation_id: '123456789',
+        http: { method: 'GET' },
+        error: { code: '200', message: 'Page Not Found' },
+        message: 'test',
+      }),
+    ]);
+  });
+
+  it('overwrites conflicting metadata keys (1st level) with message payload', testContext => {
+    const metadata = { correlation_id: '123456789', http: { method: 'GET' } };
+    const logger = new Logger(metadata);
+
+    const logSpy = testContext.mock.method(global.console, 'log', () => {});
+    assert.strictEqual(logSpy.mock.calls.length, 0);
+    logger.log('test', { http: { status_code: 200 } });
+    assert.strictEqual(logSpy.mock.calls.length, 1);
+    assert.deepEqual(logSpy.mock.calls[0]?.arguments, [
+      JSON.stringify({
+        correlation_id: '123456789',
+        http: { status_code: 200 },
+        message: 'test',
+      }),
+    ]);
+  });
+
+  it('snakify keys of Message and Metadata', testContext => {
+    const metadata = { correlationId: '123456789', http: { method: 'GET', statusCode: 200 } };
+    const logger = new Logger(metadata);
+
+    const logSpy = testContext.mock.method(global.console, 'log', () => {});
+    assert.strictEqual(logSpy.mock.calls.length, 0);
+    logger.log('test', { errorContext: { errorCode: 200, errorMessage: 'Page Not Found' } });
+    assert.strictEqual(logSpy.mock.calls.length, 1);
+    assert.deepEqual(logSpy.mock.calls[0]?.arguments, [
+      JSON.stringify({
+        correlation_id: '123456789',
+        http: { method: 'GET', status_code: 200 },
+        error_context: { error_code: 200, error_message: 'Page Not Found' },
+        message: 'test',
+      }),
     ]);
   });
 });