@alacard-project/config-sdk 1.0.0

package/.idea/workspace.xml

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ChangeListManager">
+    <list default="true" id="d6ddd62d-b258-48c7-8ac2-ae28e47081ad" name="Changes" comment="" />
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="MarkdownSettingsMigration">
+    <option name="stateVersion" value="1" />
+  </component>
+  <component name="ProjectId" id="38cLw1hfbaQQ7IG2qhtRfg4zBzC" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "WebServerToolWindowFactoryState": "false",
+    "node.js.detected.package.eslint": "true",
+    "node.js.detected.package.tslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "node.js.selected.package.tslint": "(autodetect)",
+    "nodejs_package_manager_path": "npm",
+    "vue.rearranger.settings.migration": "true"
+  }
+}]]></component>
+  <component name="SpellCheckerSettings" RuntimeDictionaries="0" Folders="0" CustomDictionaries="0" DefaultDictionary="application-level" UseSingleDictionary="true" transferred="true" />
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="d6ddd62d-b258-48c7-8ac2-ae28e47081ad" name="Changes" comment="" />
+      <created>1769094147893</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1769094147893</updated>
+      <workItem from="1769094150802" duration="320000" />
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>

package/README.md

@@ -0,0 +1,107 @@
+# @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**: Поддержка нескольких экземпляров клиента в одном процессе (подготовлено для сложной архитектуры 2026 года).
+
+## Установка
+
+Так как пакет является приватным, убедитесь, что ваш `.npmrc` настроен для доступа к соответствующему реестру.
+
+```bash
+npm install @alacard/config-sdk
+```
+
+## Быстрый старт
+
+### Инициализация
+
+Инициализируйте клиент при запуске вашего приложения (например, в `main.ts` или `bootstrap.ts`):
+
+```typescript
+import { ConfigClient } from '@alacard/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 || 'localhost:50055',
+    internalKey: process.env.INTERNAL_CONFIG_KEY, // Ключ для ConfigGrpcGuard
+    
+    // Опционально: Интеграция с Vault (KV + PKI)
+    vault: {
+      address: 'https://vault.prod.alacard.local:8200',
+      roleId: process.env.VAULT_ROLE_ID!,
+      secretId: process.env.VAULT_SECRET_ID!,
+      pkiPath: 'pki/issue/config-service', // Путь для динамических сертификатов
+    },
+
+    // Опционально: Ручная настройка mTLS (если не используется Vault PKI)
+    /*
+    tls: {
+      rootCert: fs.readFileSync('./certs/ca.crt'),
+      clientCert: fs.readFileSync('./certs/client.crt'),
+      clientKey: fs.readFileSync('./certs/client.key'),
+    },
+    */
+
+    kafkaBrokers: ['localhost:9092'],
+    useDotenvFallback: true,
+  });
+
+  const dbUrl = config.get('DATABASE_URL');
+}
+```
+
+## Как это работает (Порядок загрузки)
+
+1. **.env Fallback**: SDK пробует прочитать локальный `.env.<env>` файл (если `useDotenvFallback: true`).
+2. **Vault KV**: Если настроен `vault`, SDK логинится через AppRole и забирает секреты из `secret/data/config-service/<serviceName>`.
+3. **Vault PKI (mTLS)**: Если в `vault` указан `pkiPath`, SDK получает динамические сертификаты для защиты gRPC соединения.
+4. **gRPC Config Service**: SDK запрашивает финальный конфиг через зашифрованное соединение с микросервиса конфигураций.
+5. **Kafka Watch**: Запускается подписка на изменения для обновления параметров "на лету".
+
+  // Получение настроек
+  const port = config.getInt('PORT', 3000);
+  const dbUrl = config.get('DATABASE_URL');
+
+  console.log(`Сервис запущен на порту ${port}`);
+}
+```
+
+### Использование в других частях кода
+
+После инициализации вы можете получить доступ к инстансу в любом месте приложения:
+
+```typescript
+import { ConfigClient } from '@alacard/config-sdk';
+
+const config = ConfigClient.getInstance();
+const apiKey = config.get('EXTERNAL_API_KEY');
+```
+
+## Доступные методы
+
+- `get(key: string, defaultValue?: string): string` — получить строковое значение.
+- `getInt(key: string, defaultValue?: number): number` — получить целое число.
+- `getAll(): Record<string, string>` — получить все загруженные настройки.
+
+## Команды для разработки
+
+Если вы вносите правки в сам SDK:
+
+- `npm run gen:proto` — перегенерировать TypeScript-код из `.proto` файлов.
+- `npm run build` — скомпилировать TypeScript в JavaScript для публикации.
+
+## Структура конфигурации (gRPC)
+
+SDK использует `config.proto` для связи. Запросы отправляются методом `GetConfig`, включая `serviceName`, `environment` и `version`.
+
+---
+© 2026 Alacard Team

package/dist/config-client.d.ts

@@ -0,0 +1,33 @@
+import { VaultOptions } from './vault-client';
+export { VaultOptions };
+export interface ConfigOptions {
+    serviceName: string;
+    environment: string;
+    grpcUrl: string;
+    version?: string;
+    kafkaBrokers?: string[];
+    useDotenvFallback?: boolean;
+    internalKey?: string;
+    tls?: {
+        rootCert: Buffer;
+        clientCert: Buffer;
+        clientKey: Buffer;
+    };
+    vault?: VaultOptions;
+}
+export declare class ConfigClient {
+    private configMap;
+    private consumer;
+    private options;
+    private vaultClient;
+    private static instance;
+    constructor(options: ConfigOptions);
+    static initialize(options: ConfigOptions): Promise<ConfigClient>;
+    static getInstance(): ConfigClient;
+    private init;
+    private fetchRemoteConfig;
+    private startWatching;
+    get(key: string, defaultValue?: string): string;
+    getInt(key: string, defaultValue?: number): number;
+    getAll(): Record<string, string>;
+}

package/dist/config-client.js

@@ -0,0 +1,172 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+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 config_1 = require("./proto/config");
+const vault_client_1 = require("./vault-client");
+class ConfigClient {
+    configMap = {};
+    consumer = null;
+    options;
+    vaultClient = null;
+    static instance = null;
+    constructor(options) {
+        this.options = options;
+    }
+    static async initialize(options) {
+        const client = new ConfigClient(options);
+        await client.init();
+        this.instance = client;
+        return client;
+    }
+    static getInstance() {
+        if (!this.instance) {
+            throw new Error('[ConfigSDK] ConfigClient not initialized. Call initialize() first.');
+        }
+        return this.instance;
+    }
+    async init() {
+        const { serviceName, environment, grpcUrl, version = 'v1', useDotenvFallback = true } = this.options;
+        try {
+            // 1. Fallback to .env
+            if (useDotenvFallback) {
+                const envFile = `.env.${environment}`;
+                dotenv.config({ path: path.resolve(process.cwd(), envFile) });
+                const ALLOWED_ENV_PREFIXES = ['APP_', 'KAFKA_', 'DB_', 'REDIS_', 'GRPC_', 'PORT', 'NODE_ENV'];
+                for (const [key, value] of Object.entries(process.env)) {
+                    if (value && ALLOWED_ENV_PREFIXES.some(prefix => key.startsWith(prefix))) {
+                        this.configMap[key] = value;
+                    }
+                }
+            }
+            // 2. Load from Vault (KV)
+            if (this.options.vault) {
+                this.vaultClient = new vault_client_1.VaultClient(this.options.vault);
+                const vaultSecrets = await this.vaultClient.getKVSecrets(`config-service/${serviceName}`);
+                Object.assign(this.configMap, vaultSecrets);
+                console.log(`[ConfigSDK] Loaded secrets from Vault KV for ${serviceName}`);
+                // 3. Issue mTLS Certificates from Vault PKI if enabled
+                if (this.options.vault.pkiPath && !this.options.tls) {
+                    const certs = await this.vaultClient.issueCertificate(serviceName);
+                    this.options.tls = {
+                        rootCert: Buffer.from(certs.ca),
+                        clientCert: Buffer.from(certs.certificate),
+                        clientKey: Buffer.from(certs.privateKey),
+                    };
+                    console.log(`[ConfigSDK] Dynamic mTLS certificate issued from Vault PKI`);
+                }
+            }
+            // 4. Fetch additional config via gRPC
+            await this.fetchRemoteConfig(serviceName, environment, grpcUrl, version);
+            // 5. Start watching for changes via Kafka
+            if (this.options.kafkaBrokers && this.options.kafkaBrokers.length > 0) {
+                await this.startWatching();
+            }
+        }
+        catch (error) {
+            console.error(`[ConfigSDK] Initialization failed: ${error.message}`);
+        }
+    }
+    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);
+            }
+            client.getConfig(request, metadata, (error, response) => {
+                if (error) {
+                    console.warn(`[ConfigSDK] Failed to fetch remote config from gRPC: ${error.message}. Using local/Vault fallback.`);
+                    return resolve();
+                }
+                if (response && response.values) {
+                    Object.assign(this.configMap, response.values);
+                    console.log(`[ConfigSDK] Remote config loaded for ${serviceName} (${environment}, ${version})`);
+                }
+                resolve();
+            });
+        });
+    }
+    async startWatching() {
+        if (this.consumer)
+            return;
+        try {
+            const kafka = new kafkajs_1.Kafka({
+                clientId: `config-sdk-${this.options.serviceName}`,
+                brokers: this.options.kafkaBrokers,
+            });
+            const groupId = `config-watch-${this.options.serviceName}-${this.options.environment}`;
+            this.consumer = kafka.consumer({ groupId });
+            await this.consumer.connect();
+            await this.consumer.subscribe({ topic: 'config.updated', fromBeginning: false });
+            await this.consumer.run({
+                eachMessage: async ({ message }) => {
+                    if (!message.value)
+                        return;
+                    const event = JSON.parse(message.value.toString());
+                    if (event.service === 'global' || event.service === this.options.serviceName) {
+                        if (event.environment === this.options.environment && event.version === (this.options.version || 'v1')) {
+                            console.log(`[ConfigSDK] Hot-reload: ${event.key} updated`);
+                            this.configMap[event.key] = event.value;
+                        }
+                    }
+                },
+            });
+        }
+        catch (error) {
+            console.error(`[ConfigSDK] Watch mode failed: ${error.message}`);
+        }
+    }
+    get(key, defaultValue = '') {
+        return this.configMap[key] || defaultValue;
+    }
+    getInt(key, defaultValue = 0) {
+        const val = this.get(key);
+        return val ? parseInt(val, 10) : defaultValue;
+    }
+    getAll() {
+        return { ...this.configMap };
+    }
+}
+exports.ConfigClient = ConfigClient;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './config-client';

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./config-client"), exports);

package/dist/proto/config.d.ts

@@ -0,0 +1,116 @@
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+import { type CallOptions, type ChannelCredentials, Client, type ClientOptions, type ClientUnaryCall, type handleUnaryCall, type Metadata, type ServiceError, type UntypedServiceImplementation } from "@grpc/grpc-js";
+export interface GetConfigRequest {
+    serviceName: string;
+    environment: string;
+    version: string;
+}
+export interface ConfigResponse {
+    values: {
+        [key: string]: string;
+    };
+}
+export interface ConfigResponse_ValuesEntry {
+    key: string;
+    value: string;
+}
+export interface SetConfigRequest {
+    serviceName: string;
+    environment: string;
+    key: string;
+    value: string;
+}
+export interface ListConfigsRequest {
+    environment: string;
+}
+export interface ServiceConfig {
+    serviceName: string;
+    values: {
+        [key: string]: string;
+    };
+}
+export interface ServiceConfig_ValuesEntry {
+    key: string;
+    value: string;
+}
+export interface ListConfigsResponse {
+    configs: ServiceConfig[];
+}
+export declare const GetConfigRequest: MessageFns<GetConfigRequest>;
+export declare const ConfigResponse: MessageFns<ConfigResponse>;
+export declare const ConfigResponse_ValuesEntry: MessageFns<ConfigResponse_ValuesEntry>;
+export declare const SetConfigRequest: MessageFns<SetConfigRequest>;
+export declare const ListConfigsRequest: MessageFns<ListConfigsRequest>;
+export declare const ServiceConfig: MessageFns<ServiceConfig>;
+export declare const ServiceConfig_ValuesEntry: MessageFns<ServiceConfig_ValuesEntry>;
+export declare const ListConfigsResponse: MessageFns<ListConfigsResponse>;
+export type ConfigServiceService = typeof ConfigServiceService;
+export declare const ConfigServiceService: {
+    readonly getConfig: {
+        readonly path: "/config.ConfigService/GetConfig";
+        readonly requestStream: false;
+        readonly responseStream: false;
+        readonly requestSerialize: (value: GetConfigRequest) => Buffer;
+        readonly requestDeserialize: (value: Buffer) => GetConfigRequest;
+        readonly responseSerialize: (value: ConfigResponse) => Buffer;
+        readonly responseDeserialize: (value: Buffer) => ConfigResponse;
+    };
+    readonly setConfig: {
+        readonly path: "/config.ConfigService/SetConfig";
+        readonly requestStream: false;
+        readonly responseStream: false;
+        readonly requestSerialize: (value: SetConfigRequest) => Buffer;
+        readonly requestDeserialize: (value: Buffer) => SetConfigRequest;
+        readonly responseSerialize: (value: ConfigResponse) => Buffer;
+        readonly responseDeserialize: (value: Buffer) => ConfigResponse;
+    };
+    readonly listConfigs: {
+        readonly path: "/config.ConfigService/ListConfigs";
+        readonly requestStream: false;
+        readonly responseStream: false;
+        readonly requestSerialize: (value: ListConfigsRequest) => Buffer;
+        readonly requestDeserialize: (value: Buffer) => ListConfigsRequest;
+        readonly responseSerialize: (value: ListConfigsResponse) => Buffer;
+        readonly responseDeserialize: (value: Buffer) => ListConfigsResponse;
+    };
+};
+export interface ConfigServiceServer extends UntypedServiceImplementation {
+    getConfig: handleUnaryCall<GetConfigRequest, ConfigResponse>;
+    setConfig: handleUnaryCall<SetConfigRequest, ConfigResponse>;
+    listConfigs: handleUnaryCall<ListConfigsRequest, ListConfigsResponse>;
+}
+export interface ConfigServiceClient extends Client {
+    getConfig(request: GetConfigRequest, callback: (error: ServiceError | null, response: ConfigResponse) => void): ClientUnaryCall;
+    getConfig(request: GetConfigRequest, metadata: Metadata, callback: (error: ServiceError | null, response: ConfigResponse) => void): ClientUnaryCall;
+    getConfig(request: GetConfigRequest, metadata: Metadata, options: Partial<CallOptions>, callback: (error: ServiceError | null, response: ConfigResponse) => void): ClientUnaryCall;
+    setConfig(request: SetConfigRequest, callback: (error: ServiceError | null, response: ConfigResponse) => void): ClientUnaryCall;
+    setConfig(request: SetConfigRequest, metadata: Metadata, callback: (error: ServiceError | null, response: ConfigResponse) => void): ClientUnaryCall;
+    setConfig(request: SetConfigRequest, metadata: Metadata, options: Partial<CallOptions>, callback: (error: ServiceError | null, response: ConfigResponse) => void): ClientUnaryCall;
+    listConfigs(request: ListConfigsRequest, callback: (error: ServiceError | null, response: ListConfigsResponse) => void): ClientUnaryCall;
+    listConfigs(request: ListConfigsRequest, metadata: Metadata, callback: (error: ServiceError | null, response: ListConfigsResponse) => void): ClientUnaryCall;
+    listConfigs(request: ListConfigsRequest, metadata: Metadata, options: Partial<CallOptions>, callback: (error: ServiceError | null, response: ListConfigsResponse) => void): ClientUnaryCall;
+}
+export declare const ConfigServiceClient: {
+    new (address: string, credentials: ChannelCredentials, options?: Partial<ClientOptions>): ConfigServiceClient;
+    service: typeof ConfigServiceService;
+    serviceName: string;
+};
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+type Exact<P, I extends P> = P extends Builtin ? P : P & {
+    [K in keyof P]: Exact<P[K], I[K]>;
+} & {
+    [K in Exclude<keyof I, KeysOfUnion<P>>]: never;
+};
+interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create<I extends Exact<DeepPartial<T>, I>>(base?: I): T;
+    fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
+}
+export {};