README
¶
shared-go
Iris Stack의 Go 프로젝트들(hololive-bot, chat-bot-go-kakao, twentyq-bot 등)이 공통으로 사용하는 유틸리티 라이브러리 전용 Go 모듈입니다.
본 라이브러리는 cmd/ 실행 진입점이 없는 순수 라이브러리(Library-only) 모듈로 설계되었으며, 이를 호출하는 서비스들을 위해 일관되고 안정적인 API 사양을 유지합니다.
호환성 정책: 이 모듈의 호환성 보장 대상은 iris-stack 내부 소비자(
hololive-bot,chat-bot-go-kakao,twentyq-bot)로 한정됩니다. 외부 사용을 막지는 않지만 외부 importer 호환성은 보장하지 않으며, 스택 내 소비자가 0인 exported API는 major 승격 없이 minor 릴리스에서 제거될 수 있습니다.
설치 (Installation)
go get github.com/park285/shared-go@latest
제공 패키지 목록 (Package Catalog)
| 패키지 경로 | 기능 및 역할 |
|---|---|
pkg/backoff |
시도 횟수 및 상태를 기반으로 한 지수 백오프(Exponential Backoff) 계산 유틸리티 (대기 및 재시도 루프 제어는 호출부에서 직접 처리) |
pkg/db/pgxdb |
jackc/pgx/v5 pgxpool 기반 PostgreSQL 연결 풀 생성 도구 (sslmode 명시 강제, 인증 실패·context 취소 시 즉시 중단하는 OpenPoolWithRetry, compose 서비스명 postgres 한정 localhost DNS 폴백) |
pkg/db/sqldb |
pgx 무의존 표준 database/sql *sql.DB 커넥션 풀 파라미터 적용 도구 |
pkg/dbmigrate |
embed.FS의 manifest.txt 순서대로 SQL 마이그레이션 파일을 실행하는 공통 처리 모듈 (database/sql 또는 pgx 실행 함수 주입 방식) |
pkg/envutil |
환경 변수 로드 및 *_FILE 형태의 파일 경로로 보안 토큰/시크릿 값을 주입하는 도구 |
pkg/ginjson |
Gin 웹 프레임워크용 Sonic 라이브러리 기반 고성능 JSON 렌더링 및 바인딩 모듈 |
pkg/h3 |
HTTP/3 전송 프로토콜 설정 도구 (자체 CA 번들 등록, TLS 상세 사양 정의) |
pkg/healthprobe |
서비스 헬스체크 및 프로브(Readiness / Liveness Probe) 도구 |
pkg/httputil |
HTTP 클라이언트 커넥션 풀링 및 프로파일 구성 도구 |
pkg/json |
Sonic 엔진을 내장한 고성능 JSON 인코딩/디코딩 추상화 계층 |
pkg/jsonutil |
텍스트 혹은 HTTP 응답 문자열로부터 유효한 JSON을 정규화하여 추출하는 헬퍼 유틸리티 |
pkg/llm |
LLM provider 클라이언트 추상화 (JSONGenerator 인터페이스, OpenAI Responses 호환 JSON 생성, Codex CLI 실행/로그인, 응답 redaction) |
pkg/logging |
Slog 기반의 구조화된 로깅 모듈 (비동기 처리, 민감한 키 정보 마스킹 및 실시간 로그 로테이션 지원) |
pkg/netguard |
외부 HTTP 대상 URL 및 dial 주소를 fail-closed로 검증하는 네트워크 가드 (private/loopback/link-local/ULA 대역 차단, Policy.AllowedHosts allowlist 지원) |
pkg/obsmetrics |
client_golang 의존성 없이 Prometheus 평문 텍스트 exposition을 생성하는 메트릭 키트 (webhook/런타임 메트릭, prefix 네임스페이스 분리) |
pkg/outputguard |
LLM 생성 출력 가드 (구조화된 차단 사유, 출력·보호 텍스트 크기 제한, 역할/시크릿/보호 지침 중첩 탐지, bounded TTL index cache) |
pkg/promptguard |
source-aware 프롬프트 인젝션 가드 (embedded v3 한/영 baseline, optional rules-only overlay, bounded decoding, policy digest, TTL cache) |
pkg/retry |
pkg/backoff의 지연 값 계산을 사용해 context 취소를 존중하며 sleep·재시도·중단을 수행하는 재시도 루프(WithRetry) 구현체 |
pkg/runtime |
Go 런타임 최적화를 포함한 프로세스 부트스트랩 도구 (automaxprocs, 애플리케이션 라이프사이클 관리, HTTPServer) |
pkg/stringutil |
범용 문자열 처리 유틸리티 |
pkg/telemetry |
OpenTelemetry 기반의 분산 트레이싱(Tracing) 정보 설정 및 컨텍스트 전파 유틸리티 |
pkg/workerconfig |
개별 백그라운드 워커들의 동작 프로파일 설정 로드 모듈 |
pkg/workerpool |
큐(Queue) 기반의 동시성 제어 워커 풀 구현체 |
새로운 공통 기능이 필요할 경우, pkg/ 하위에 신규 패키지 형식으로 추가해 주십시오.
Prompt guard 계약
Check 호출은 Source와 Enforcement를 모두 명시해야 합니다. EnforcementUnspecified와 알 수 없는 값은 탐지나 cache 조회 전에 ErrInvalidCheckRequest로 거부됩니다.
Enforcement |
Allow |
Review |
Block |
|---|---|---|---|
EnforcementObserve |
허용 | 허용 | 허용 |
EnforcementInteractive |
허용 | 허용 | 거부 |
EnforcementPersistent |
허용 | 거부 | 거부 |
지원 source는 user_prompt, prompt_bundle, retrieved_memory, memory_candidate, session_patch, simulation_state, law_context, session_context, chat_log, web_search_result, image_prompt로 고정됩니다. 저장·요약·재사용되는 데이터에는 EnforcementPersistent를 사용해야 합니다.
UseEmbeddedDefaults=true는 pkg/promptguard/rulepacks의 v3 baseline을 먼저 로드합니다. RulepacksDir 또는 RulepackFS를 함께 지정하면 v3 kind: rules overlay 하나만 추가할 수 있으며, policy 변경과 baseline rule ID 중복은 시작 단계에서 거부됩니다. PolicyDigest()는 engine version과 최종 유효 policy/rules의 결정론적 digest이며 사용자 입력을 포함하지 않습니다. Runtime override 없이 v3 policy 문서만 threshold를 소유합니다.
make guard-perf-gate는 검토된 GUARD_PERF_BASELINE이 없으면 실패하며 자동으로 baseline을 만들지 않습니다. 신규 baseline 생성은 --require-baseline 없이 scripts/perf/check-bench-regression.sh를 명시적으로 실행하는 별도 개발 작업입니다.
Prompt guard는 v3 rulepack과 source/enforcement를 명시하는 Check만 지원합니다.
로컬 검증 (Verification)
개발 시 로컬에서 아래 명령어로 검증할 수 있습니다.
make lint
go test ./...
go build ./...
CI 정책: 본 리포지토리는 원격 깃허브 액션(GitHub Actions)이 실제 검증 주체입니다. ci.yml은 PR 및 main push마다 workflow secret 경계 검사, SQL ownership 검사, gofmt, go vet, golangci-lint, 경합 조건 검사를 포함한 테스트 슈트(go test -race -count=1 ./...), perf gate(벤치마크 회귀 검사)를 수행하며, security.yml은 main push·주간 스케줄·수동 dispatch 시 govulncheck 취약점 분석을 수행합니다.
Directories
¶
| Path | Synopsis |
|---|---|
|
pkg
|
|
|
backoff
Package backoff는 공용 exponential backoff helper를 제공합니다.
|
Package backoff는 공용 exponential backoff helper를 제공합니다. |
|
db/pgxdb
Package pgxdb는 jackc/pgx/v5 pgxpool 기반 PostgreSQL 연결 풀 생성 도구를 제공합니다.
|
Package pgxdb는 jackc/pgx/v5 pgxpool 기반 PostgreSQL 연결 풀 생성 도구를 제공합니다. |
|
db/sqldb
Package sqldb는 표준 database/sql *sql.DB 커넥션 풀 파라미터 적용 도구를 제공합니다.
|
Package sqldb는 표준 database/sql *sql.DB 커넥션 풀 파라미터 적용 도구를 제공합니다. |
|
dbmigrate
Package dbmigrate는 embed.FS의 manifest.txt 순서대로 SQL 파일을 실행합니다.
|
Package dbmigrate는 embed.FS의 manifest.txt 순서대로 SQL 파일을 실행합니다. |
|
httputil
Package httputil은 공용 HTTP client, JSON request, response 검증 helper를 제공합니다.
|
Package httputil은 공용 HTTP client, JSON request, response 검증 helper를 제공합니다. |
|
httputil/ginauth
Package ginauth는 gin 기반 관리 API key 인증 middleware를 제공합니다.
|
Package ginauth는 gin 기반 관리 API key 인증 middleware를 제공합니다. |
|
jsonutil
Package jsonutil은 model과 HTTP response 텍스트에서 JSON을 추출하는 helper를 제공합니다.
|
Package jsonutil은 model과 HTTP response 텍스트에서 JSON을 추출하는 helper를 제공합니다. |
|
llm/openaipreset
Package openaipreset는 pkg/llm의 OpenAI 호환 JSON 생성 경로를 functional-options 클라이언트로 감싼 재사용 프리셋이다.
|
Package openaipreset는 pkg/llm의 OpenAI 호환 JSON 생성 경로를 functional-options 클라이언트로 감싼 재사용 프리셋이다. |
|
logging
Package logging은 runtime 서비스용 공용 구조화 로깅 helper를 제공합니다.
|
Package logging은 runtime 서비스용 공용 구조화 로깅 helper를 제공합니다. |
|
netguard
Package netguard는 외부 HTTP 대상과 dial 주소를 fail-closed로 검증합니다.
|
Package netguard는 외부 HTTP 대상과 dial 주소를 fail-closed로 검증합니다. |
|
obsmetrics
Package obsmetrics는 client_golang 의존성 없이 Prometheus 평문 텍스트 exposition을 직접 생성하는 메트릭 키트입니다.
|
Package obsmetrics는 client_golang 의존성 없이 Prometheus 평문 텍스트 exposition을 직접 생성하는 메트릭 키트입니다. |
|
retry
Package retry는 pkg/backoff의 지연 값 계산을 사용해 context 취소를 존중하며 sleep·재시도·중단을 수행하는 재시도 루프(WithRetry)를 제공합니다.
|
Package retry는 pkg/backoff의 지연 값 계산을 사용해 context 취소를 존중하며 sleep·재시도·중단을 수행하는 재시도 루프(WithRetry)를 제공합니다. |
|
runtime/httpserver
Package httpserver는 HTTP server를 위한 작은 lifecycle helper를 제공합니다.
|
Package httpserver는 HTTP server를 위한 작은 lifecycle helper를 제공합니다. |
|
runtime/lifecycle
Package lifecycle는 runtime 서비스의 기동·주기 실행·종료 정리를 위한 작은 helper 모음입니다.
|
Package lifecycle는 runtime 서비스의 기동·주기 실행·종료 정리를 위한 작은 helper 모음입니다. |
|
telemetry
Package telemetry는 OpenTelemetry tracing 설정과 context 전파 helper를 제공합니다.
|
Package telemetry는 OpenTelemetry tracing 설정과 context 전파 helper를 제공합니다. |