@alacard-project/config-sdk 1.0.9 → 1.1.0

package/README.md

@@ -1,14 +1,6 @@
-# @alacard-project/config-sdk
+# Alacard Config SDK
 
-**Alacard Config SDK** — это клиентская библиотека для взаимодействия с централизованным микросервисом конфигураций (CCS) через gRPC. SDK обеспечивает строго типизированный доступ к настройкам, поддерживает горячую перезагрузку через Kafka и имеет встроенный fallback на `.env` файлы.
-
-## Основные возможности
-
-- 🚀 **gRPC-First**: Высокая производительность и низкая задержка при получении конфигураций.
-- 🛡️ **Строгая типизация**: Автоматическая генерация TypeScript-интерфейсов из Protocol Buffers (`ts-proto`).
-- ⚡ **Hot-Reloading**: Мгновенное обновление параметров в памяти приложения при изменении в базе (через Kafka).
-- 📂 **.env Fallback**: Поддержка локальных `.env.<environment>` файлов для разработки и как резервный вариант.
-- 🏗️ **Instance-based**: Поддержка нескольких экземпляров клиента в одном процессе.
+SDK для централизованного управления конфигурацией в микросервисах Alacard. Поддерживает интеграцию с HashiCorp Vault и встроенным Config Service.
 
 ## Установка
 
@@ -16,38 +8,29 @@
 npm install @alacard-project/config-sdk
 ```
 
-## Быстрый старт
-
-### Инициализация
-
-Инициализируйте клиент при запуске вашего приложения (например, в `main.ts` или `bootstrap.ts`):
+## Использование
 
 ```typescript
-import { ConfigClient } from '@alacard-project/config-sdk';
-
-async function bootstrap() {
-  const config = await ConfigClient.initialize({
-    serviceName: 'auth-service',
-    environment: process.env.NODE_ENV || 'development',
-    grpcUrl: process.env.GRPC_CONFIG_URL || 'config-microservice:50055',
-    kafkaBrokers: ['kafka:9092'],
-    useDotenvFallback: true, // Использовать .env если gRPC недоступен
-  });
-
-  const dbUrl = config.get('DATABASE_URL');
-  console.log('Config loaded!');
-}
+import { ConfigModule } from '@alacard-project/config-sdk';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      vaultUrl: process.env.VAULT_URL,
+      vaultToken: process.env.VAULT_TOKEN,
+      serviceName: 'my-service'
+    })
+  ]
+})
+export class AppModule {}
 ```
 
-### Использование в NestJS
-
-Рекомендуется создать `ConfigService` обертку или использовать `ConfigModule` (если он реализован в вашем проекте), который внутри вызывает `ConfigClient.initialize`.
+## Возможности
 
-## Как это работает (Порядок загрузки)
+- Загрузка секретов из Vault.
+- Резервное копирование и кэширование конфигурации.
+- **Отказоустойчивость**: Если Vault недоступен, SDK может использовать локальные переменные окружения или кэш.
 
-1. **.env Fallback**: SDK пробует прочитать локальный `.env.<env>` файл (если `useDotenvFallback: true`).
-2. **gRPC Config Service**: SDK запрашивает финальный конфиг через gRPC.
-3. **Kafka Watch**: Запускается подписка на изменения для обновления параметров "на лету".
+## Лицензия
 
----
-© 2026 Alacard Team
+MIT

package/dist/clients/config.client.d.ts

@@ -5,6 +5,7 @@ export declare class ConfigClient {
     private consumer;
     private options;
     private vaultClient;
+    private breaker;
     private static instance;
     private constructor();
     static initialize(options: ConfigOptions): Promise<ConfigClient>;
@@ -13,9 +14,11 @@ export declare class ConfigClient {
     private loadProcessEnv;
     private loadDotEnv;
     private loadVaultSecrets;
+    private initCircuitBreaker;
     private fetchRemoteConfig;
     private startWatching;
-    get(key: string, defaultValue?: string): string;
+    get<T = string>(key: string, defaultValue?: T): T;
     getInt(key: string, defaultValue?: number): number;
+    getBool(key: string, defaultValue?: boolean): boolean;
     getAll(): Record<string, string>;
 }

package/dist/clients/config.client.js

@@ -32,12 +32,16 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConfigClient = void 0;
 const grpc = __importStar(require("@grpc/grpc-js"));
 const kafkajs_1 = require("kafkajs");
 const path = __importStar(require("path"));
 const dotenv = __importStar(require("dotenv"));
+const opossum_1 = __importDefault(require("opossum"));
 const common_1 = require("@nestjs/common");
 const config_1 = require("../generated/config");
 const vault_client_1 = require("./vault.client");
@@ -47,11 +51,15 @@ class ConfigClient {
     consumer = null;
     options;
     vaultClient = null;
+    breaker = null;
     static instance = null;
     constructor(options) {
         this.options = options;
     }
     static async initialize(options) {
+        if (this.instance) {
+            return this.instance;
+        }
         const client = new ConfigClient(options);
         await client.init();
         this.instance = client;
@@ -66,26 +74,31 @@ class ConfigClient {
     async init() {
         const { serviceName, environment, grpcUrl, version = 'v1', useDotenvFallback = true } = this.options;
         try {
+            // 1. Load from Process Env (Highest Priority for overrides)
             this.loadProcessEnv();
+            // 2. Load from DotEnv (if enabled)
             if (useDotenvFallback) {
                 this.loadDotEnv(environment);
             }
+            // 3. Load from Vault (if configured)
             if (this.options.vault) {
                 await this.loadVaultSecrets(serviceName);
             }
+            // 4. Fetch Remote Config via gRPC (with Circuit Breaker)
             await this.fetchRemoteConfig(serviceName, environment, grpcUrl, version);
+            // 5. Start Kafka Watcher (if configured)
             if (this.options.kafkaBrokers && this.options.kafkaBrokers.length > 0) {
                 await this.startWatching();
             }
             this.logger.log(`Configuration initialized with ${Object.keys(this.configMap).length} keys`);
         }
         catch (error) {
-            this.logger.error(`Critical initialization failure: ${error.message}`);
-            throw error;
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            this.logger.error(`Critical initialization failure: ${errorMsg}. Service starting with loaded config.`);
         }
     }
     loadProcessEnv() {
-        const ALLOWED_ENV_PREFIXES = ['APP_', 'KAFKA_', 'DB_', 'REDIS_', 'GRPC_', 'PORT', 'NODE_ENV', 'DATABASE_URL', 'RABBITMQ_URL'];
+        const ALLOWED_ENV_PREFIXES = ['APP_', 'KAFKA_', 'DB_', 'REDIS_', 'GRPC_', 'PORT', 'NODE_ENV', 'DATABASE_URL'];
         for (const [key, value] of Object.entries(process.env)) {
             if (value && ALLOWED_ENV_PREFIXES.some(prefix => key.startsWith(prefix))) {
                 this.configMap[key] = value;
@@ -93,57 +106,92 @@ class ConfigClient {
         }
     }
     loadDotEnv(environment) {
-        const envFiles = [`.env.${environment}`, '.env.local', '.env'];
+        // Only support standard .env and environment-specific .env
+        const envFiles = [`.env.${environment}`, '.env'];
         for (const file of envFiles) {
             const filePath = path.resolve(process.cwd(), file);
             const result = dotenv.config({ path: filePath });
             if (result.parsed) {
-                Object.assign(this.configMap, result.parsed);
+                // Do not overwrite existing keys (process.env wins)
+                for (const [key, value] of Object.entries(result.parsed)) {
+                    if (!this.configMap[key]) {
+                        this.configMap[key] = value;
+                    }
+                }
                 this.logger.log(`Loaded variables from ${file}`);
             }
         }
     }
     async loadVaultSecrets(serviceName) {
+        if (!this.options.vault)
+            return;
         this.vaultClient = new vault_client_1.VaultClient(this.options.vault);
         try {
             const vaultSecrets = await this.vaultClient.getKVSecrets(`config-service/${serviceName}`);
-            Object.assign(this.configMap, vaultSecrets);
+            // Vault secrets should overwrite env vars if needed, or fill gaps. 
+            // Usually Vault > Env, but here we treat Env > Vault for local overrides. 
+            // Let's adopt a safe merge: Existing keys (from Env) take precedence.
+            for (const [key, value] of Object.entries(vaultSecrets)) {
+                if (!this.configMap[key]) {
+                    this.configMap[key] = value;
+                }
+            }
             this.logger.log(`Loaded secrets from Vault for ${serviceName}`);
         }
         catch (error) {
-            this.logger.warn(`Vault secrets unavailable: ${error.message}. Continuing with local config.`);
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`Vault secrets unavailable: ${errorMsg}. Continuing with local config.`);
         }
     }
+    initCircuitBreaker(client) {
+        const fetchFunction = (request, metadata) => {
+            return new Promise((resolve, reject) => {
+                client.getConfig(request, metadata, (error, response) => {
+                    if (error)
+                        return reject(error);
+                    resolve(response.values || {});
+                });
+            });
+        };
+        this.breaker = new opossum_1.default(fetchFunction, {
+            timeout: 5000, // 5s timeout
+            errorThresholdPercentage: 50, // 50% errors opens the breaker
+            resetTimeout: 10000, // wait 10s before trying again
+        });
+        this.breaker.on('open', () => this.logger.warn('Circuit Breaker (Config gRPC) is OPEN'));
+        this.breaker.on('halfOpen', () => this.logger.log('Circuit Breaker (Config gRPC) is HALF_OPEN'));
+        this.breaker.on('close', () => this.logger.log('Circuit Breaker (Config gRPC) is CLOSED'));
+    }
     async fetchRemoteConfig(serviceName, environment, grpcUrl, version) {
         let credentials = grpc.credentials.createInsecure();
         if (this.options.tls) {
             credentials = grpc.credentials.createSsl(this.options.tls.rootCert, this.options.tls.clientKey, this.options.tls.clientCert);
         }
         const client = new config_1.ConfigServiceClient(grpcUrl, credentials);
-        return new Promise((resolve) => {
-            const request = { serviceName, environment, version };
-            const metadata = new grpc.Metadata();
-            if (this.options.internalKey) {
-                metadata.set('x-internal-key', this.options.internalKey);
-            }
-            const timeout = 3000;
-            const timer = setTimeout(() => {
-                this.logger.warn(`Remote config (gRPC) timeout after ${timeout}ms. Using local/vault fallback.`);
-                resolve();
-            }, timeout);
-            client.getConfig(request, metadata, (error, response) => {
-                clearTimeout(timer);
-                if (error) {
-                    this.logger.warn(`Remote config (gRPC) unavailable: ${error.message}. Using local/vault fallback.`);
-                    return resolve();
-                }
-                if (response && response.values) {
-                    Object.assign(this.configMap, response.values);
-                    this.logger.log(`Remote config loaded from config-service`);
+        if (!this.breaker) {
+            this.initCircuitBreaker(client);
+        }
+        const request = { serviceName, environment, version };
+        const metadata = new grpc.Metadata();
+        if (this.options.internalKey) {
+            metadata.set('x-internal-key', this.options.internalKey);
+        }
+        try {
+            const values = await this.breaker.fire(request, metadata);
+            if (values) {
+                // Remote config fills in the gaps
+                for (const [key, value] of Object.entries(values)) {
+                    if (!this.configMap[key]) {
+                        this.configMap[key] = value;
+                    }
                 }
-                resolve();
-            });
-        });
+                this.logger.log(`Remote config loaded from config-service`);
+            }
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`Remote config (gRPC) failure: ${errorMsg}. Using local/vault fallback.`);
+        }
     }
     async startWatching() {
         if (this.consumer)
@@ -152,6 +200,10 @@ class ConfigClient {
             const kafka = new kafkajs_1.Kafka({
                 clientId: `config-sdk-${this.options.serviceName}`,
                 brokers: this.options.kafkaBrokers,
+                retry: {
+                    retries: 5, // Retry up to 5 times
+                    maxRetryTime: 30000 // Max time spent retrying
+                }
             });
             const groupId = `config-watch-${this.options.serviceName}-${this.options.environment}`;
             this.consumer = kafka.consumer({ groupId });
@@ -171,21 +223,41 @@ class ConfigClient {
                         }
                     }
                     catch (err) {
-                        this.logger.error(`Failed to parse config update: ${err.message}`);
+                        const errorMsg = err instanceof Error ? err.message : String(err);
+                        this.logger.error(`Failed to parse config update: ${errorMsg}`);
                     }
                 },
             });
         }
         catch (error) {
-            this.logger.warn(`Config watch mode (Kafka) failed: ${error.message}`);
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`Config watch mode (Kafka) failed: ${errorMsg}`);
         }
     }
-    get(key, defaultValue = '') {
-        return this.configMap[key] || defaultValue;
+    get(key, defaultValue) {
+        const val = this.configMap[key];
+        if (val === undefined || val === null) {
+            if (defaultValue !== undefined) {
+                return defaultValue;
+            }
+            // Strict mode: warn if key is missing and no default value
+            this.logger.warn(`Configuration key '${key}' not found and no default value provided.`);
+            return undefined;
+        }
+        return val;
     }
     getInt(key, defaultValue = 0) {
         const val = this.get(key);
-        return val ? parseInt(val, 10) : defaultValue;
+        if (!val)
+            return defaultValue;
+        const parsed = parseInt(val, 10);
+        return isNaN(parsed) ? defaultValue : parsed;
+    }
+    getBool(key, defaultValue = false) {
+        const val = this.get(key);
+        if (!val)
+            return defaultValue;
+        return val.toLowerCase() === 'true' || val === '1';
     }
     getAll() {
         return { ...this.configMap };

package/dist/clients/vault.client.js

@@ -34,7 +34,7 @@ class VaultClient {
             this.logger.log('Successfully authenticated with Vault AppRole');
         }
         catch (error) {
-            const errorMsg = error.response?.data?.errors?.[0] || error.message;
+            const errorMsg = error instanceof Error ? error.response?.data?.errors?.[0] || error.message : String(error);
             this.logger.error(`Vault login failed: ${errorMsg}`);
             throw new Error(`Vault login failed: ${errorMsg}`);
         }
@@ -46,12 +46,16 @@ class VaultClient {
             return response.data.data.data;
         }
         catch (error) {
-            if (error.response?.status === 404) {
-                this.logger.warn(`Secret not found at path: ${path}`);
-                return {};
+            if (error && typeof error === 'object' && 'response' in error) {
+                const axiosError = error;
+                if (axiosError.response?.status === 404) {
+                    this.logger.warn(`Secret not found at path: ${path}`);
+                    return {};
+                }
             }
-            this.logger.error(`Failed to fetch secrets from path ${path}: ${error.message}`);
-            throw new Error(`Failed to fetch secrets: ${error.message}`);
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            this.logger.error(`Failed to fetch secrets from path ${path}: ${errorMsg}`);
+            throw new Error(`Failed to fetch secrets: ${errorMsg}`);
         }
     }
     async issueCertificate(commonName) {
@@ -69,8 +73,9 @@ class VaultClient {
             };
         }
         catch (error) {
-            this.logger.error(`Failed to issue certificate for ${commonName}: ${error.message}`);
-            throw new Error(`Failed to issue certificate: ${error.message}`);
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            this.logger.error(`Failed to issue certificate for ${commonName}: ${errorMsg}`);
+            throw new Error(`Failed to issue certificate: ${errorMsg}`);
         }
     }
 }

package/dist/generated/config.js

@@ -1,12 +1,6 @@
 "use strict";
-// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
-// versions:
-//   protoc-gen-ts_proto  v2.11.0
-//   protoc               v5.29.3
-// source: config.proto
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConfigServiceClient = exports.ConfigServiceService = exports.ListConfigsResponse = exports.ServiceConfig_ValuesEntry = exports.ServiceConfig = exports.ListConfigsRequest = exports.SetConfigRequest = exports.ConfigResponse_ValuesEntry = exports.ConfigResponse = exports.GetConfigRequest = void 0;
-/* eslint-disable */
 const wire_1 = require("@bufbuild/protobuf/wire");
 const grpc_js_1 = require("@grpc/grpc-js");
 function createBaseGetConfigRequest() {

package/dist/utils/nest-helpers.d.ts

@@ -1,9 +1,6 @@
 import { Environment } from '../enums/env.enum';
 export declare abstract class BaseConfigService {
-    protected readonly configService: any;
-    private remoteConfig;
-    constructor(configService: any);
-    setRemoteConfig(config: Record<string, string>): void;
+    constructor();
     protected get<T = string>(key: string, defaultValue?: T): T;
     getRequiredString(key: string): string;
     getRequiredNumber(key: string): number;

package/dist/utils/nest-helpers.js

@@ -2,20 +2,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseConfigService = void 0;
 const env_enum_1 = require("../enums/env.enum");
+const config_client_1 = require("../clients/config.client");
 class BaseConfigService {
-    configService;
-    remoteConfig = {};
-    constructor(configService) {
-        this.configService = configService;
-    }
-    setRemoteConfig(config) {
-        this.remoteConfig = { ...this.remoteConfig, ...config };
-    }
+    constructor() { }
     get(key, defaultValue) {
-        if (this.remoteConfig[key] !== undefined) {
-            return this.remoteConfig[key];
+        // 1. Try Config Client (if initialized)
+        try {
+            const client = config_client_1.ConfigClient.getInstance();
+            const val = client.get(key);
+            if (val !== undefined && val !== '') {
+                return val;
+            }
+        }
+        catch (_e) {
+            // Client not initialized yet, fall through to process.env
+        }
+        // 2. Try process.env
+        const envVal = process.env[key];
+        if (envVal !== undefined) {
+            return envVal;
         }
-        return this.configService.get(key, defaultValue);
+        return defaultValue;
     }
     getRequiredString(key) {
         const value = this.get(key);

package/eslint.config.mjs

@@ -1,27 +1,29 @@
-// @ts-check
-import eslint from '@eslint/js';
-import tseslint from 'typescript-eslint';
-import globals from 'globals';
+import js from "@eslint/js";
+import globals from "globals";
+import tsParser from "@typescript-eslint/parser";
+import tsPlugin from "@typescript-eslint/eslint-plugin";
 
-export default tseslint.config(
+export default [
+    js.configs.recommended,
     {
-        ignores: ['dist/**'],
+        ignores: ["src/generated/**/*"],
     },
-    eslint.configs.recommended,
-    ...tseslint.configs.recommended,
     {
+        files: ["src/**/*.ts"],
         languageOptions: {
+            parser: tsParser,
             globals: {
                 ...globals.node,
                 ...globals.jest,
             },
         },
+        plugins: {
+            "@typescript-eslint": tsPlugin,
+        },
         rules: {
-            '@typescript-eslint/interface-name-prefix': 'off',
-            '@typescript-eslint/explicit-function-return-type': 'off',
-            '@typescript-eslint/explicit-module-boundary-types': 'off',
-            '@typescript-eslint/no-explicit-any': 'off',
-            '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+            "no-console": "error",
+            "@typescript-eslint/no-unused-vars": ["warn", { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }],
+            "@typescript-eslint/no-explicit-any": "warn",
         },
     },
-);
+];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@alacard-project/config-sdk",
-    "version": "1.0.9",
+    "version": "1.1.0",
     "engines": {
         "node": ">=24.0.0"
     },
@@ -13,9 +13,9 @@
     },
     "scripts": {
         "build": "tsc",
-        "gen:proto": "protoc --plugin=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=src/generated --proto_path=proto proto/config.proto --ts_proto_opt=outputServices=grpc-js,env=node,useOptionals=messages,exportCommonSymbols=false,esModuleInterop=true",
         "lint": "eslint \"src/**/*.ts\" --fix",
         "test": "jest",
+        "test:watch": "jest --watch",
         "test:cov": "jest --coverage",
         "prepublishOnly": "npm run build"
     },
@@ -25,20 +25,22 @@
         "@grpc/proto-loader": "^0.7.13",
         "axios": "^1.7.9",
         "dotenv": "^16.4.7",
-        "kafkajs": "^2.2.4"
+        "kafkajs": "^2.2.4",
+        "opossum": "^9.0.0"
     },
     "devDependencies": {
-        "@eslint/js": "^9.18.0",
+        "@eslint/js": "^9.39.2",
         "@nestjs/common": "^11.1.12",
         "@types/jest": "^29.5.14",
         "@types/node": "^22.10.7",
-        "eslint": "^9.18.0",
-        "globals": "^15.14.0",
+        "@types/opossum": "^8.1.9",
+        "eslint": "^9.39.2",
+        "globals": "^15.15.0",
         "jest": "^29.7.0",
         "ts-jest": "^29.2.5",
         "ts-proto": "^2.6.1",
         "typescript": "^5.7.3",
-        "typescript-eslint": "^8.20.0"
+        "typescript-eslint": "^8.54.0"
     },
     "jest": {
         "moduleFileExtensions": [
@@ -46,15 +48,15 @@
             "json",
             "ts"
         ],
-        "rootDir": "src",
+        "rootDir": ".",
         "testRegex": ".*\\.spec\\.ts$",
         "transform": {
             "^.+\\.(t|j)s$": "ts-jest"
         },
         "collectCoverageFrom": [
-            "**/*.(t|j)s"
+            "src/**/*.(t|j)s"
         ],
-        "coverageDirectory": "../coverage",
+        "coverageDirectory": "./coverage",
         "testEnvironment": "node"
     }
-}
+}