@tmlmobilidade/databases 20260506.1355.7 → 20260507.11.20

package/dist/clients/go-redis.d.ts

@@ -0,0 +1,30 @@
+import { type RedisClientType } from 'redis';
+export declare class GORedisClient {
+    private static _instance;
+    private client;
+    private tunnel;
+    /**
+     * Disallow direct instantiation of the service.
+     * Use getClient() instead to ensure singleton behavior.
+     */
+    private constructor();
+    /**
+     * Returns the singleton instance of the subclass.
+     */
+    static getClient(): Promise<RedisClientType>;
+    /**
+     * Connects to Redis, setting up the client instance.
+     * If SSH tunneling is required, it establishes the tunnel first.
+     * This method is called internally by the service and should not be used directly.
+     */
+    private connect;
+    /**
+     * Constructs the connection string based on environment variables
+     * and SSH tunneling configuration, and handles both direct connections and SSH-tunneled
+     * connections, validating the necessary environment variables for each case.
+     * This method is called internally by the service and should not be used directly.
+     * @throws Will throw an error if required environment variables are missing or if the SSH tunnel setup fails.
+     * @returns A promise that resolves to the Redis connection string.
+     */
+    private getConnectionString;
+}

package/dist/clients/go-redis.js

@@ -0,0 +1,114 @@
+/* * */
+import { Logger } from '@tmlmobilidade/logger';
+import { SshTunnelService } from '@tmlmobilidade/ssh';
+import { readFileSync } from 'node:fs';
+import { createClient } from 'redis';
+/* * */
+export class GORedisClient {
+    //
+    static _instance = null;
+    client;
+    tunnel = null;
+    /**
+     * Disallow direct instantiation of the service.
+     * Use getClient() instead to ensure singleton behavior.
+     */
+    constructor() { }
+    /**
+     * Returns the singleton instance of the subclass.
+     */
+    static async getClient() {
+        // If no instance exists, create one and store the promise.
+        // This ensures that if multiple calls to getClient() happen concurrently,
+        // they will all await the same initialization process.
+        if (!this._instance) {
+            this._instance = (async () => {
+                const instance = new GORedisClient();
+                // This behaves like the constructor,
+                // but allows for async initialization.
+                await instance.connect();
+                return instance;
+            })();
+        }
+        // Await the instance if it's still initializing,
+        // or return it immediately if ready.
+        const instance = await this._instance;
+        return instance.client;
+    }
+    /**
+     * Connects to Redis, setting up the client instance.
+     * If SSH tunneling is required, it establishes the tunnel first.
+     * This method is called internally by the service and should not be used directly.
+     */
+    async connect() {
+        Logger.info('[GORedisClient] Connecting to database...');
+        const connectionString = await this.getConnectionString();
+        this.client = createClient({ url: connectionString });
+        await this.client.connect();
+        Logger.info('[GORedisClient] Connected to database');
+    }
+    /**
+     * Constructs the connection string based on environment variables
+     * and SSH tunneling configuration, and handles both direct connections and SSH-tunneled
+     * connections, validating the necessary environment variables for each case.
+     * This method is called internally by the service and should not be used directly.
+     * @throws Will throw an error if required environment variables are missing or if the SSH tunnel setup fails.
+     * @returns A promise that resolves to the Redis connection string.
+     */
+    async getConnectionString() {
+        //
+        //
+        // Validate required environment variables
+        if (process.env.GO_REDIS_TUNNEL_ENABLED !== 'true' && process.env.GO_REDIS_TUNNEL_ENABLED !== 'false') {
+            throw new Error('Missing GO_REDIS_TUNNEL_ENABLED. Please indicate whether SSH tunneling is required by setting GO_REDIS_TUNNEL_ENABLED to "true" or "false".');
+        }
+        if (!process.env.GO_REDIS_HOST || !process.env.GO_REDIS_PORT) {
+            throw new Error('Missing GO_REDIS_HOST or GO_REDIS_PORT');
+        }
+        if (process.env.GO_REDIS_TUNNEL_ENABLED === 'false') {
+            return `redis://${process.env.GO_REDIS_HOST}:${process.env.GO_REDIS_PORT}`;
+        }
+        // SSH required
+        if (!process.env.GO_REDIS_TUNNEL_LOCAL_PORT) {
+            throw new Error('Missing GO_REDIS_TUNNEL_LOCAL_PORT');
+        }
+        if (!process.env.GO_REDIS_TUNNEL_SSH_HOST || !process.env.GO_REDIS_TUNNEL_SSH_USERNAME) {
+            throw new Error('Missing SSH config');
+        }
+        const sshConfig = {
+            forwardOptions: {
+                dstAddr: process.env.GO_REDIS_HOST,
+                dstPort: Number(process.env.GO_REDIS_PORT),
+                srcAddr: 'localhost',
+                srcPort: Number(process.env.GO_REDIS_TUNNEL_LOCAL_PORT),
+            },
+            serverOptions: {
+                port: Number(process.env.GO_REDIS_TUNNEL_LOCAL_PORT),
+            },
+            sshOptions: {
+                agent: process.env.GO_REDIS_TUNNEL_SSH_KEY_PATH ? undefined : process.env.SSH_AUTH_SOCK,
+                host: process.env.GO_REDIS_TUNNEL_SSH_HOST,
+                keepaliveCountMax: 20,
+                keepaliveInterval: 10_000,
+                port: 22,
+                privateKey: process.env.GO_REDIS_TUNNEL_SSH_KEY_PATH ? readFileSync(process.env.GO_REDIS_TUNNEL_SSH_KEY_PATH) : undefined,
+                username: process.env.GO_REDIS_TUNNEL_SSH_USERNAME,
+            },
+            tunnelOptions: {
+                autoClose: false,
+                reconnectOnError: true,
+            },
+        };
+        const sshOptions = {
+            maxRetries: 3,
+        };
+        this.tunnel = new SshTunnelService(sshConfig, sshOptions);
+        Logger.info('[GORedisClient] Setting up SSH Tunnel...');
+        const connection = await this.tunnel.connect();
+        const addr = connection.address();
+        if (!addr || typeof addr !== 'object') {
+            throw new Error('[GORedisClient] Failed to retrieve SSH tunnel address.');
+        }
+        return `redis://localhost:${addr.port}`;
+    }
+}

package/dist/interfaces/api-cache/index.d.ts

@@ -0,0 +1,2 @@
+export * from './interface.js';
+export * from './keys.js';

package/dist/interfaces/api-cache/index.js

@@ -0,0 +1,2 @@
+export * from './interface.js';
+export * from './keys.js';

package/dist/interfaces/api-cache/interface.d.ts

@@ -0,0 +1,50 @@
+import { type ApiCacheKey } from './keys.js';
+import { type RedisClientType } from 'redis';
+declare class ApiCacheClass {
+    private static _instance;
+    private client;
+    /**
+     * Returns the singleton instance of the subclass.
+     */
+    static getInstance(): Promise<ApiCacheClass>;
+    /**
+     * Deletes all keys from the cache that are not defined in `ApiCacheKeyValues`.
+     * This method is useful for maintaining a clean state free of stale
+     * or irrelevant cache entries that consume storage and memory resources.
+     * @returns A promise that resolves when the cleaning process is complete.
+     * @throws Will throw an error if the cleaning process fails.
+     */
+    clean(): Promise<void>;
+    /**
+     * Deletes a cache entry by its key.
+     * @param key The key of the cache entry to delete.
+     * @returns A promise that resolves when the deletion process is complete.
+     * @throws Will throw an error if the deletion process fails.
+     */
+    delete(key: ApiCacheKey): Promise<void>;
+    /**
+     * Retrieves a cache entry by its key.
+     * @param key The key of the cache entry to retrieve.
+     * @returns A promise that resolves with the cache entry value,
+     * or `null` if not found.
+     * @throws Will throw an error if the retrieval process fails.
+     */
+    get(key: ApiCacheKey): Promise<null | string>;
+    /**
+     * Saves a cache entry with an optional time-to-live (TTL).
+     * @param key The key of the cache entry to save.
+     * @param value The value of the cache entry to save. Must be a string.
+     * @param ttl Optional time-to-live for the cache entry in seconds.
+     * If not provided, the entry will persist indefinitely.
+     */
+    set(key: ApiCacheKey, value: string, ttl?: number): Promise<void>;
+    protected connectToClient(): Promise<RedisClientType>;
+    /**
+     * Initializes the Redis client.
+     * @throws Will throw an error if the client initialization fails.
+     * @returns A promise that resolves when the initialization process is complete.
+     */
+    protected init(): Promise<void>;
+}
+export declare const apiCache: ApiCacheClass;
+export {};

package/dist/interfaces/api-cache/interface.js

@@ -0,0 +1,102 @@
+/* * */
+import { GORedisClient } from '../../clients/go-redis.js';
+import { ApiCacheKeyValues } from './keys.js';
+import { asyncSingletonProxy } from '@tmlmobilidade/utils';
+/* * */
+class ApiCacheClass {
+    //
+    static _instance = null;
+    client;
+    /**
+     * Returns the singleton instance of the subclass.
+     */
+    static async getInstance() {
+        // If no instance exists, create one and store the promise.
+        // This ensures that if multiple calls to getInstance() happen concurrently,
+        // they will all await the same initialization process.
+        if (!this._instance) {
+            this._instance = (async () => {
+                const instance = new ApiCacheClass();
+                // This behaves like the constructor,
+                // but allows for async initialization.
+                await instance.init();
+                return instance;
+            })();
+        }
+        // Await the instance if it's still initializing,
+        // or return it immediately if ready.
+        return await this._instance;
+    }
+    /**
+     * Deletes all keys from the cache that are not defined in `ApiCacheKeyValues`.
+     * This method is useful for maintaining a clean state free of stale
+     * or irrelevant cache entries that consume storage and memory resources.
+     * @returns A promise that resolves when the cleaning process is complete.
+     * @throws Will throw an error if the cleaning process fails.
+     */
+    async clean() {
+        const allKeys = await this.client.keys('*');
+        const keysToDelete = allKeys.filter(key => !ApiCacheKeyValues.includes(key));
+        if (keysToDelete.length)
+            await this.client.del(keysToDelete);
+    }
+    /**
+     * Deletes a cache entry by its key.
+     * @param key The key of the cache entry to delete.
+     * @returns A promise that resolves when the deletion process is complete.
+     * @throws Will throw an error if the deletion process fails.
+     */
+    async delete(key) {
+        await this.client.del(key);
+    }
+    /**
+     * Retrieves a cache entry by its key.
+     * @param key The key of the cache entry to retrieve.
+     * @returns A promise that resolves with the cache entry value,
+     * or `null` if not found.
+     * @throws Will throw an error if the retrieval process fails.
+     */
+    async get(key) {
+        const result = await this.client.get(key);
+        if (typeof result !== 'string')
+            return null;
+        return result;
+    }
+    /**
+     * Saves a cache entry with an optional time-to-live (TTL).
+     * @param key The key of the cache entry to save.
+     * @param value The value of the cache entry to save. Must be a string.
+     * @param ttl Optional time-to-live for the cache entry in seconds.
+     * If not provided, the entry will persist indefinitely.
+     */
+    async set(key, value, ttl) {
+        // Validate value type before setting cache
+        if (typeof value !== 'string')
+            throw new Error(`[ApiCache] Value must be a string. Got "${typeof value}" for key "${key}".`);
+        // Check if key is valid before setting cache
+        if (!ApiCacheKeyValues.includes(key))
+            throw new Error(`[ApiCache] Invalid cache key "${key}". Allowed keys are: ${ApiCacheKeyValues.join(', ')}.`);
+        // Set cache with optional TTL
+        if (ttl)
+            await this.client.set(key, value, { expiration: { type: 'EX', value: ttl } });
+        else
+            await this.client.set(key, value);
+    }
+    connectToClient() {
+        return GORedisClient.getClient();
+    }
+    /**
+     * Initializes the Redis client.
+     * @throws Will throw an error if the client initialization fails.
+     * @returns A promise that resolves when the initialization process is complete.
+     */
+    async init() {
+        // Skip if already initialized
+        if (this.client)
+            return;
+        // Connect to the Redis client
+        this.client = await this.connectToClient();
+    }
+}
+/* * */
+export const apiCache = asyncSingletonProxy(ApiCacheClass);

package/dist/interfaces/api-cache/keys.d.ts

@@ -0,0 +1,2 @@
+export declare const ApiCacheKeyValues: readonly ["alerts:all"];
+export type ApiCacheKey = typeof ApiCacheKeyValues[number];

package/dist/interfaces/api-cache/keys.js

@@ -0,0 +1,4 @@
+/* * */
+export const ApiCacheKeyValues = [
+    'alerts:all',
+];

package/dist/interfaces/index.d.ts

@@ -1,3 +1,4 @@
 export * from './apex/index.js';
+export * from './api-cache/index.js';
 export * from './simplified-apex/index.js';
 export * from './vehicle-events/index.js';

package/dist/interfaces/index.js

@@ -1,3 +1,4 @@
 export * from './apex/index.js';
+export * from './api-cache/index.js';
 export * from './simplified-apex/index.js';
 export * from './vehicle-events/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/databases",
-	"version": "20260506.1355.7",
+	"version": "20260507.11.20",
 	"author": {
 		"email": "iso@tmlmobilidade.pt",
 		"name": "TML-ISO"
@@ -42,6 +42,7 @@
 		"@tmlmobilidade/types": "*",
 		"@tmlmobilidade/utils": "*",
 		"mongodb": "7.2.0",
+		"redis": "5.12.1",
 		"zod": "3.25.76"
 	},
 	"devDependencies": {