feat(api): add shared infrastructure

This commit is contained in:
dahyeon committed 2026-04-06 23:48:00 +09:00
1 parent f24674b12c
commit 2e311d9cbf
10 files changed
+1088

No files matched your search

@@ -0,0 +1 @@
export const GARNET_CLIENT = Symbol('GARNET_CLIENT');
@@ -0,0 +1,57 @@
import { Logger, Module } from '@nestjs/common';
import { createClient } from 'redis';
import { SecretModule } from '../secret/secret.module';
import { SecretService } from '../secret/secret.service';
import { GARNET_CLIENT } from './garnet.constants';
import { GarnetService, type GarnetRedisClient } from './garnet.service';
function normalizeGarnetUrl(endpoint: string): string {
const trimmed = endpoint.trim();
if (!trimmed) {
throw new Error('GARNET_ENDPOINT cannot be empty');
}
if (/^redis(s)?:\/\//iu.test(trimmed)) {
return trimmed;
}
return `redis://${trimmed}`;
}
@Module({
imports: [SecretModule],
providers: [
{
provide: GARNET_CLIENT,
inject: [SecretService],
useFactory: async (
secretService: SecretService,
): Promise<GarnetRedisClient> => {
await secretService.ready();
const [endpoint, username, password] = await Promise.all([
secretService.get<string>('GARNET_ENDPOINT'),
secretService.get<string>('GARNET_USERID'),
secretService.get<string>('GARNET_PASSWORD'),
]);
const logger = new Logger('GarnetClient');
const client = createClient({
url: normalizeGarnetUrl(endpoint),
username,
password,
});
client.on('error', (error) => {
logger.error(`Garnet client error: ${error?.message ?? error}`);
});
await client.connect();
logger.log('Garnet connected');
return client;
},
},
GarnetService,
],
exports: [GarnetService, GARNET_CLIENT],
})
export class GarnetModule {}
@@ -0,0 +1,213 @@
import {
Inject,
Injectable,
Logger,
OnModuleDestroy,
} from '@nestjs/common';
import type { createClient } from 'redis';
import { GARNET_CLIENT } from './garnet.constants';
export type GarnetRedisClient = ReturnType<typeof createClient>;
export interface StreamEntry {
deliveriesCounter?: number;
id: string;
message: Record<string, string>;
millisElapsedFromDelivery?: number;
}
export interface StreamReadResult {
messages: StreamEntry[];
name: string;
}
interface RawStreamMessage {
deliveriesCounter?: number;
id: string;
message: unknown;
millisElapsedFromDelivery?: number;
}
interface RawStreamReadResult {
messages: RawStreamMessage[];
name: string;
}
function normalizeStreamFields(fields: unknown): Record<string, string> {
if (fields instanceof Map) {
return Object.fromEntries(
[...fields.entries()].map(([key, value]) => [String(key), String(value)]),
);
}
if (typeof fields === 'object' && fields !== null) {
return Object.fromEntries(
Object.entries(fields as Record<string, unknown>).map(([key, value]) => [
key,
String(value),
]),
);
}
return {};
}
@Injectable()
export class GarnetService implements OnModuleDestroy {
private readonly logger = new Logger(GarnetService.name);
constructor(
@Inject(GARNET_CLIENT) private readonly client: GarnetRedisClient,
) {}
async onModuleDestroy() {
try {
await this.client.quit();
} catch {
this.client.destroy();
}
}
public raw(): GarnetRedisClient {
return this.client;
}
public async getJson<T>(key: string): Promise<T | null> {
const raw = await this.client.get(key);
if (!raw) return null;
try {
return JSON.parse(raw) as T;
} catch (err) {
this.logger.warn(
`Failed to JSON.parse cached value for key="${key}": ${
(err as Error)?.message ?? err
}`,
);
return null;
}
}
public async setJson(
key: string,
value: unknown,
ttlSeconds?: number,
): Promise<void> {
const serialized = JSON.stringify(value);
if (ttlSeconds && ttlSeconds > 0) {
await this.client.set(key, serialized, { EX: ttlSeconds });
return;
}
await this.client.set(key, serialized);
}
public async getString(key: string): Promise<string | null> {
return this.client.get(key);
}
public async setString(
key: string,
value: string,
ttlSeconds?: number,
): Promise<void> {
if (ttlSeconds && ttlSeconds > 0) {
await this.client.set(key, value, { EX: ttlSeconds });
return;
}
await this.client.set(key, value);
}
public async setStringIfAbsent(
key: string,
value: string,
ttlSeconds?: number,
): Promise<boolean> {
const options: { EX?: number; NX: true } = { NX: true };
if (ttlSeconds && ttlSeconds > 0) options.EX = ttlSeconds;
const result = await this.client.set(key, value, options);
return result === 'OK';
}
public async delete(key: string): Promise<number> {
return this.client.del(key);
}
public async appendStream(
key: string,
fields: Record<string, string>,
options?: { maxLen?: number },
): Promise<string> {
const trimOptions =
options?.maxLen && options.maxLen > 0
? {
TRIM: {
strategy: 'MAXLEN' as const,
strategyModifier: '~' as const,
threshold: options.maxLen,
},
}
: undefined;
return this.client.xAdd(key, '*', fields, trimOptions);
}
public async createConsumerGroup(
key: string,
group: string,
startId = '$',
): Promise<void> {
await this.client.xGroupCreate(key, group, startId, { MKSTREAM: true });
}
public async readGroup(
key: string,
group: string,
consumer: string,
startId: string,
options?: { blockMs?: number; count?: number },
): Promise<StreamReadResult[] | null> {
const readOptions: { BLOCK?: number; COUNT?: number } = {};
if (options?.blockMs !== undefined) readOptions.BLOCK = options.blockMs;
if (options?.count !== undefined) readOptions.COUNT = options.count;
const reply = await this.client.xReadGroup(
group,
consumer,
{ key, id: startId },
readOptions,
);
if (!reply) return null;
return (reply as RawStreamReadResult[]).map((stream) => ({
name: String(stream.name),
messages: stream.messages.map((message) => ({
deliveriesCounter:
typeof message.deliveriesCounter === 'number'
? message.deliveriesCounter
: undefined,
id: String(message.id),
message: normalizeStreamFields(message.message),
millisElapsedFromDelivery:
typeof message.millisElapsedFromDelivery === 'number'
? message.millisElapsedFromDelivery
: undefined,
})),
}));
}
public async acknowledgeStream(
key: string,
group: string,
ids: string | string[],
): Promise<number> {
return this.client.xAck(key, group, ids);
}
public async streamLength(key: string): Promise<number> {
return this.client.xLen(key);
}
public async publish(channel: string, message: string): Promise<number> {
return this.client.publish(channel, message);
}
}
@@ -0,0 +1,13 @@
import { Module, Global } from '@nestjs/common';
import { SecretModule } from './secret/secret.module';
import { NatsModule } from './nats/nats.module';
import { DatabaseModule } from './database/database.module';
import { GarnetModule } from './garnet/garnet.module';
@Global()
@Module({
imports: [SecretModule, NatsModule, DatabaseModule, GarnetModule],
providers: [],
exports: [SecretModule, NatsModule, DatabaseModule, GarnetModule],
})
export class GlobalModule {}
@@ -0,0 +1 @@
export const NATS_CLIENT = Symbol('NATS_CLIENT');
@@ -0,0 +1,45 @@
import { Module } from '@nestjs/common';
import fs from 'fs/promises';
import { connect } from 'nats';
import type { NatsConnection } from 'nats';
import { SecretModule } from '../secret/secret.module';
import { SecretService } from '../secret/secret.service';
import { NATS_CLIENT } from './nats.constants';
import { NatsService } from './nats.service';
@Module({
imports: [SecretModule],
providers: [
{
provide: NATS_CLIENT,
inject: [SecretService],
useFactory: async (
secretService: SecretService,
): Promise<NatsConnection> => {
await secretService.ready();
const [endpoint, user, password, serviceName] = await Promise.all([
secretService.get<string>('NATS_ENDPOINT'),
secretService.get<string>('NATS_USER'),
secretService.get<string>('NATS_PASS'),
secretService.get<string>('SERVICE_NAME'),
]);
return connect({
name: serviceName,
servers: [endpoint],
maxReconnectAttempts: -1,
reconnectTimeWait: 500,
reconnect: true,
pingInterval: 20000,
timeout: 5000,
user,
pass: password,
});
},
},
NatsService,
],
exports: [NatsService, NATS_CLIENT],
})
export class NatsModule {}
@@ -0,0 +1,117 @@
import {
Inject,
Injectable,
Logger,
OnModuleDestroy,
} from '@nestjs/common';
import { StringCodec } from 'nats';
import type { Msg, NatsConnection, Subscription } from 'nats';
import { NATS_CLIENT } from './nats.constants';
export type NatsMessageHandler<T = unknown> = (
data: T,
msg: Msg,
) => Promise<void> | void;
@Injectable()
export class NatsService implements OnModuleDestroy {
private readonly logger = new Logger(NatsService.name);
private readonly stringCodec = StringCodec();
private readonly subscriptions = new Set<Subscription>();
constructor(
@Inject(NATS_CLIENT) private readonly natsClient: NatsConnection,
) {}
async onModuleDestroy() {
for (const sub of this.subscriptions) {
try {
sub.unsubscribe();
} catch {
// ignore
}
}
this.subscriptions.clear();
try {
const closed = this.natsClient.closed();
await this.natsClient.drain();
const err = await closed;
if (err) this.logger.error(`NATS closed with error: ${err}`);
} catch {
try {
await this.natsClient.close();
} catch {
// ignore
}
}
}
public async publish<T = unknown>(subject: string, data: T): Promise<void> {
this.natsClient.publish(
subject,
this.stringCodec.encode(JSON.stringify(data)),
);
await this.natsClient.flush();
}
public subscribe<T = unknown>(
subject: string,
handler: NatsMessageHandler<T>,
options?: { queue?: string },
): Subscription {
const sub = this.natsClient.subscribe(subject, {
queue: options?.queue,
});
this.subscriptions.add(sub);
void this.consumeSubscription(sub, handler);
return sub;
}
private async consumeSubscription<T>(
sub: Subscription,
handler: NatsMessageHandler<T>,
): Promise<void> {
try {
for await (const msg of sub) {
await this.dispatch(msg, handler);
}
} catch (err) {
this.logger.error(
`NATS subscription on subject="${sub.getSubject()}" terminated: ${
(err as Error)?.message ?? err
}`,
);
} finally {
this.subscriptions.delete(sub);
}
}
private async dispatch<T>(
msg: Msg,
handler: NatsMessageHandler<T>,
): Promise<void> {
let data: T;
try {
const decoded = this.stringCodec.decode(msg.data);
data = JSON.parse(decoded) as T;
} catch (err) {
this.logger.warn(
`Failed to decode NATS message on subject="${msg.subject}": ${
(err as Error)?.message ?? err
}`,
);
return;
}
try {
await handler(data, msg);
} catch (err) {
this.logger.error(
`Handler error on subject="${msg.subject}": ${
(err as Error)?.stack ?? err
}`,
);
}
}
}
@@ -0,0 +1,9 @@
import { Module } from '@nestjs/common';
import { SecretService } from './secret.service';
@Module({
imports: [],
providers: [SecretService],
exports: [SecretService],
})
export class SecretModule {}
@@ -0,0 +1,243 @@
import { Injectable, Logger } from '@nestjs/common';
import { InfisicalSDK } from '@infisical/sdk';
import { ConfigService } from '@nestjs/config';
type SecretMap = Record<string, string | undefined>;
const DEFAULT_INFISICAL_SITE_URL = 'https://secret-manager.dahyeon.us/';
const IMDS_TOKEN_TTL_SECONDS = 60;
const IMDS_REQUEST_TIMEOUT_MS = 1500;
const FALLBACK_IMDS_BASE_URLS = [
'http://169.254.169.254',
'http://host.docker.internal:8675',
];
interface InfisicalBootstrapConfig {
siteUrl: string;
clientId: string;
clientSecret: string;
projectId: string;
}
@Injectable()
export class SecretService {
private logger = new Logger(SecretService.name);
private secrets: SecretMap | null = null; // null = 아직 로드 전
private loading?: Promise<void>; // 진행 중인 로드(중복 호출 방지)
constructor(private readonly config: ConfigService) {}
/** 한 번만 로그인/페치. 동시에 여러 번 호출돼도 같은 Promise를 공유 */
private async fetchSecrets(): Promise<void> {
if (this.secrets) return; // 이미 로드됨
if (this.loading) return this.loading; // 로드 중이면 그거 기다리기
this.loading = (async () => {
const bootstrapConfig = await this.resolveInfisicalBootstrapConfig();
const infisicalClient = new InfisicalSDK({
siteUrl: bootstrapConfig.siteUrl,
});
await infisicalClient.auth().universalAuth.login({
clientId: bootstrapConfig.clientId,
clientSecret: bootstrapConfig.clientSecret,
});
const res = await infisicalClient.secrets().listSecrets({
environment:
process.env.NODE_ENV === 'prod'
? 'prod'
: process.env.NODE_ENV === 'test'
? 'staging'
: 'dev',
projectId: bootstrapConfig.projectId,
});
// 임시 객체에 채운 뒤 한 번에 교체(일관성 보장)
const map: SecretMap = {};
for (const s of res.secrets) {
map[s.secretKey] = s.secretValue;
}
// 앱 생명주기에서 필요한 env는 모두 SecretService가 process.env에 반영한다.
for (const [k, v] of Object.entries(map)) {
if (typeof v === 'string' && v.length > 0) {
process.env[k] = v;
}
}
this.secrets = map;
this.logger.log(
`Fetched ${Object.keys(map).length} secrets from Infisical`,
);
})();
try {
await this.loading;
} finally {
this.loading = undefined; // 실패/성공 모두 끝나면 해제(실패 시 재시도 가능)
}
}
private async resolveInfisicalBootstrapConfig(): Promise<InfisicalBootstrapConfig> {
const [clientId, clientSecret, projectId] = await Promise.all([
this.resolveBootstrapValue('INFISICAL_CLIENT_ID'),
this.resolveBootstrapValue('INFISICAL_CLIENT_SECRET'),
this.resolveBootstrapValue('INFISICAL_PROJECT_ID'),
]);
const siteUrl =
(await this.resolveBootstrapValue('INFISICAL_SITE_URL', false)) ??
DEFAULT_INFISICAL_SITE_URL;
const missing = [
!siteUrl && 'INFISICAL_SITE_URL',
!clientId && 'INFISICAL_CLIENT_ID',
!clientSecret && 'INFISICAL_CLIENT_SECRET',
!projectId && 'INFISICAL_PROJECT_ID',
].filter(Boolean);
if (missing.length > 0) {
throw new Error(
`Missing required Infisical bootstrap configuration: ${missing.join(', ')}`,
);
}
if (!clientId || !clientSecret || !projectId) {
throw new Error('Missing required Infisical bootstrap configuration.');
}
return {
siteUrl,
clientId,
clientSecret,
projectId,
};
}
private async resolveBootstrapValue(
key: string,
required = true,
): Promise<string | undefined> {
const configured = this.config.get<string>(key)?.trim();
if (configured) return configured;
const fromImds = await this.getImdsSecret(key);
if (fromImds) {
process.env[key] = fromImds;
return fromImds;
}
if (required) {
throw new Error(`Missing required bootstrap secret: ${key}`);
}
return undefined;
}
private async getImdsSecret(key: string): Promise<string | undefined> {
let lastError: Error | undefined;
for (const baseUrl of this.resolveImdsBaseUrls()) {
try {
const token = await this.issueImdsToken(baseUrl);
const secret = await this.fetchImdsText(
`${baseUrl.replace(/\/$/u, '')}/latest/meta-data/secrets/${encodeURIComponent(key)}`,
{
'X-aws-ec2-metadata-token': token,
},
);
return secret.trim() || undefined;
} catch (error) {
lastError = error instanceof Error ? error : new Error(String(error));
}
}
if (lastError) {
this.logger.debug(
`IMDS secret lookup failed for ${key}: ${lastError.message}`,
);
}
return undefined;
}
private resolveImdsBaseUrls(): string[] {
return [
this.config.get<string>('IMDS_BASE_URL'),
this.config.get<string>('MACHINE_METADATA_BASE_URL'),
...FALLBACK_IMDS_BASE_URLS,
]
.map((value) => value?.trim())
.filter((value): value is string => Boolean(value));
}
private async issueImdsToken(baseUrl: string): Promise<string> {
return this.fetchImdsText(
`${baseUrl.replace(/\/$/u, '')}/latest/api/token`,
{
'X-aws-ec2-metadata-token-ttl-seconds': String(IMDS_TOKEN_TTL_SECONDS),
},
'PUT',
);
}
private async fetchImdsText(
url: string,
headers: Record<string, string>,
method = 'GET',
): Promise<string> {
const controller = new AbortController();
const timeout = setTimeout(
() => controller.abort(),
IMDS_REQUEST_TIMEOUT_MS,
);
try {
const response = await fetch(url, {
method,
headers,
signal: controller.signal,
});
if (!response.ok) {
throw new Error(`IMDS ${method} ${url} failed with ${response.status}`);
}
return response.text();
} finally {
clearTimeout(timeout);
}
}
/** lazy get: 필요할 때 처음 한번만 로드 */
public async get<T = string>(key: string, fallback?: T): Promise<T> {
if (!this.secrets) {
await this.fetchSecrets();
}
// console.log('Secrets loaded:', this.secrets);
const val = this.secrets![key];
if (val === undefined) {
const cfg = this.config.get<T>(key);
if (cfg !== undefined) return cfg;
if (fallback !== undefined) return fallback;
throw new Error(`Secret not found for key="${key}"`);
}
return val as T;
}
/** 필요 시: 동기 접근(초기화 안됐으면 에러). constructor 등에서 강제 사용 금지 */
public getSync<T = string>(key: string, fallback?: T): T {
if (!this.secrets) {
const cfg = this.config.get<T>(key);
if (cfg !== undefined) return cfg;
if (fallback !== undefined) return fallback;
throw new Error(`SecretService not initialized yet (key="${key}")`);
}
const val = this.secrets[key];
if (val === undefined) {
const cfg = this.config.get<T>(key);
if (cfg !== undefined) return cfg;
if (fallback !== undefined) return fallback;
throw new Error(`Secret not found for key="${key}"`);
}
return val as T;
}
/** 선택: 사전에 강제로 로드하고 싶을 때 호출 */
public async ready(): Promise<void> {
await this.fetchSecrets();
}
}