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)

llm/openaipreset.Client.GenerateLayeredResponsesJSON은 Responses API 스트리밍을 사용합니다. 중간 delta 대신 정상 종료된 response.completed의 전체 output_text를 반환하므로 호출자는 기존 출력 검증과 JSON 디코딩을 그대로 적용할 수 있습니다. 미완료·실패·취소·종료 후 오류에서는 부분 출력을 반환하지 않습니다. 이 변경은 v2.6.1에 포함되며, 소비자는 해당 버전으로 의존성을 갱신해야 합니다.

go get github.com/park285/shared-go/v2@latest

제공 패키지 목록 (Package Catalog)

패키지 경로	기능 및 역할
pkg/backoff	시도 횟수 및 상태를 기반으로 한 지수 백오프(Exponential Backoff) 계산 유틸리티 (대기 및 재시도 루프 제어는 호출부에서 직접 처리)
pkg/db/pgxdb	jackc/pgx/v5 pgxpool 기반 PostgreSQL 연결 풀 생성 도구 (sslmode 명시 강제, sslrootcert는 Config.SSLRootCert로만 지정하고 env를 읽지 않음, 재시도는 호출자 소유)
pkg/dbmigrate	embed.FS의 manifest.txt 순서대로 SQL 마이그레이션 파일을 실행하는 공통 처리 모듈 (database/sql 또는 pgx 실행 함수 주입 방식)
pkg/envutil	환경 변수 로드 및 *_FILE 형태의 파일 경로로 보안 토큰/시크릿 값을 주입하는 도구 (숫자·bool·duration은 잘못된 값을 오류로 돌려주는 IntE·Int64E·FloatE·BoolE·BoolExplicit·DurationE만 제공)
pkg/ginjson	Go 1.27 encoding/json/v2 JSON을 HTML-safe로 인코딩하는 Gin renderer와 response helper
pkg/h3	HTTP/3 전송 프로토콜 설정 도구 (자체 CA 번들 등록, TLS 상세 사양 정의)
pkg/health	version·uptime·component 상태 스냅샷과 /health·/ready 응답 본문 계약을 보관하는 server 측 health 모듈
pkg/healthprobe	서비스 헬스체크 및 프로브(Readiness / Liveness Probe) 도구
pkg/httputil	HTTP 클라이언트 커넥션 풀링 및 프로파일 구성 도구, 관리 API key 인증(X-API-Key 헤더만 수용, Authorization: Bearer는 거부)
pkg/irisdurable	Iris webhook durability 계약(admission·nonce·reply outbox 어휘, Iris admission 보존·replay 지평 typed 상수, bounded reissue ladder)
pkg/irisdurable/contracttest	irisdurable 계약을 봇별 저장소 구현에 적용하는 재사용 테스트 스위트(admission 멱등성, nonce set-once, outcome_unknown 보존, bounded reissue, 보존·지평)
pkg/irisdurable/pgstore	irisdurable 계약의 PostgreSQL 구현(ordering key FIFO inbox, nonce set-once TTL, reply outbox claim fence·redrive·retire·prune). 테이블 DDL은 소비 저장소 migration이 소유하고 testdata/schema.sql이 참조 스키마다
pkg/jsonutil	텍스트 혹은 HTTP 응답 문자열로부터 유효한 JSON을 정규화하여 추출하는 헬퍼 유틸리티
pkg/kakaoformat	Markdown 표현을 카카오 일반 채팅용 평문과 링크로 변환하는 formatter
pkg/llm	LLM provider 클라이언트 추상화 (JSONGenerator, OpenAI 호환 JSON 생성·가드, 진단 redaction). 지시는 InvariantPrompt/DeveloperPrompt 계층으로만 전달
pkg/llm/openaipreset	pkg/llm의 OpenAI 호환 JSON 생성 경로를 functional options로 구성하는 재사용 preset (지시는 PromptLayers로만 전달)
pkg/lockutil	FNV-1a hash로 key를 고정 256개 shard에 배정하는 bounded keyed mutex
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/panicguard	callback panic을 복구해 구조화된 진단을 남기는 실행 경계
pkg/promptguard	source-aware 프롬프트 인젝션 가드 (embedded v3 한/영 baseline, optional rules-only overlay, bounded decoding, policy digest, TTL cache)
pkg/reflectutil	interface에 담긴 nilable 값을 안전하게 판별하는 reflection helper
pkg/retry	pkg/backoff의 지연 값 계산을 사용해 context 취소를 존중하며 sleep·재시도·중단을 수행하는 재시도 루프(WithRetry) 구현체
pkg/runtime/automaxprocs	container CPU quota에 맞게 GOMAXPROCS를 설정하는 process bootstrap helper
pkg/runtime/bootstrap	프로세스 시작 입력을 검증하고 runtime 구성을 적용하는 bootstrap helper
pkg/runtime/httpserver	HTTP server 생성(수신 한계·OTel 계측)·본문 읽기 예산·시작·실행·graceful shutdown 소유권을 단일화하는 lifecycle helper
pkg/runtime/lifecycle	기동·주기 실행·종료 정리와 다중 close를 조정하는 runtime lifecycle helper
pkg/sqlutil	embed FS의 SQL asset을 읽고 공백을 제거하며 누락·빈 query에서 panic하는 loader
pkg/stringutil	범용 문자열 처리 유틸리티
pkg/telemetry	OpenTelemetry 기반의 분산 트레이싱(Tracing) 정보 설정 및 컨텍스트 전파 유틸리티
pkg/workercontract	strict worker profile 로드(env 경로·identity), service-owned settings decode·shape 검증, diagnostics registry, 공통 Prometheus exposition 모듈
pkg/workerpool	큐(Queue) 기반의 동시성 제어 워커 풀 구현체

새로운 공통 기능이 필요할 경우, pkg/ 하위에 신규 패키지 형식으로 추가해 주십시오.

stdout 사본과 유실 계측

파일 로깅의 Options.AsyncStdout은 stdout 사본에만 bounded queue를 적용합니다. 정상 JSON은 그대로 전달하고, 64 KiB를 넘는 사본은 유효한 JSON으로 축약합니다. time/level/msg/event/trace_id/span_id/request_id 문자열을 각각 최대 1024 UTF-8 bytes로 보존하며 stdout_truncated·stdout_original_bytes를 추가합니다. 나머지 필드의 전체 sanitized 원본은 동기 파일 lane에 남습니다.

logging.SnapshotStdout()과 obsmetrics.WriteLoggingMetrics(w)는 프로세스 수명 동안의 iris_stack_logging_stdout_dropped_total·iris_stack_logging_stdout_truncated_total을 제공합니다. 큐 포화·종료 후 쓰기·sink 오류·short write는 dropped, 성공적으로 전달한 축약 사본은 truncated입니다. 두 counter는 파일 쓰기·console-only logger·종료 진단 자체를 집계하지 않습니다. async 유실 요약은 파일에도 기록되며, 포화 큐에서는 복사 전에 거절해 추가 할당을 하지 않습니다.

파일 lane 쓰기 실패는 logging.SnapshotFile().WriteFailed로 세고, 같은 WriteLoggingMetrics가 iris_stack_logging_file_write_failed_total로 노출합니다. 오류나 short write로 끝난 동기 파일 기록 (MaxSizeMB를 넘는 record, 디스크 부족, rotate·open 실패, 종료 시 유실 요약 기록 포함)이 대상이며 실패한 record는 일부만 기록됐을 수 있습니다. console-only logger에는 파일 lane이 없습니다. 0은 알려진 실패가 없다는 뜻일 뿐 내구 저장을 증명하지 않습니다.

Close의 2초 제한은 대기 상한이지 I/O 취소가 아닙니다. timeout 이후에도 pending write가 완료될 수 있으므로 종료 요약은 기록 시점에 알려진 결과만 나타냅니다. 새 API를 사용하는 소비자는 같은 shared-go 소스로 workspace 검증한 뒤 실제 게시 버전으로 의존성을 함께 갱신해야 합니다. 소스 구현은 운영 배포를 뜻하지 않습니다.

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를 소유합니다.

Benchmark와 결정적 guard 검증

Go benchmark 함수는 명시적인 성능 조사와 프로파일링을 위해 유지합니다. 필요할 때 표준 Go 명령으로 직접 실행합니다.

go test -run '^$' -bench . ./pkg/promptguard ./pkg/outputguard

Blocking CI는 머신별 baseline이나 상대 wall-clock 비교를 사용하지 않습니다. Prompt/output guard의 의미론·적대적 입력·fail-closed 계약은 일반 테스트가 소유하며, 운영상 명시적으로 보호하던 prompt guard allocation 상한은 testing.AllocsPerRun 기반 결정적 테스트로 검증합니다. ns/op와 B/op는 수동 조사 지표이며 CI 합격 판정으로 사용하지 않습니다.

Prompt guard는 v3 rulepack과 source/enforcement를 명시하는 Check만 지원합니다.

Inbox 업무 복구 transaction

pgstore.InboxRecoveryDecision과 Store.ApplyInboxRecovery는 소비자가 잠근 inbox·업무 행을 판정한 뒤 공용 inbox 상태 변경만 한 bulk SQL로 적용합니다. Store는 기존 transaction에 묶어야 하며 pool에서 자동 transaction을 열지 않습니다. 소비자는 선택·업무 행을 잠그고 미청구·만료 inbox 또는 자신이 소유한 처리 claim만 판정합니다. 살아 있는 업무 lease의 제외와 업무 정산·환불·metadata 변경도 같은 transaction에서 소유합니다.

판정은 pending·completed·manual_review만 허용합니다. scope·ID·message ID·attempts와 processing token·정확한 lease snapshot을 대조하며, 빈 token은 token·lease가 NULL인 pending만 바꿉니다. pending 사유는 비어야 하고 manual_review는 사유가 필요합니다. 모든 입력을 SQL 전에 검증하고, 영향 행 수가 판정 수와 다르면 ErrClaimLost를 반환합니다. 일부 행은 이미 바뀌었을 수 있으므로 오류가 나면 호출자가 전체 transaction을 rollback해야 합니다. 완료 payload는 지우고 수동 검토 payload는 DiscardInboxManualReviewPayload 정책을 따릅니다.

로컬 검증 (Verification)

개발 시 로컬에서 아래 명령어로 검증할 수 있습니다.

make lint
go test ./...
go build ./...

CI 정책: 본 리포지토리는 원격 깃허브 액션(GitHub Actions)이 실제 검증 주체입니다. ci.yml은 PR 및 main push마다 module tidy drift, 고정 Unicode 생성 테이블, SQL ownership 검사, golangci-lint(gofumpt·gci·goimports formatter와 govet 포함), 경합 조건 검사를 포함한 테스트 슈트(go test -race -count=1 ./...)를 수행하며, security.yml은 main push·주간 스케줄·수동 dispatch 시 govulncheck 취약점 분석을 수행합니다.

파일 줄 수(800)와 함수 길이 상한은 .golangci.yml의 revive file-length-limit과 funlen이 검사합니다. 별도 구조 예산은 두지 않습니다. Workflow 보안 정책(action 전체 SHA 고정, id-token·attestations 권한은 release.yml만, PR의 secret 사용 금지)은 iris-stack의 tools/checks/check-workflow-policy.py가 검증합니다. 로컬 릴리스 게이트도 make test-allocations로 race 빌드에서 빠지는 할당 상한을 검증합니다.

릴리스 검증(bash scripts/ci/release-gate.sh)은 Docker가 준비된 환경에서 별도 일회용 PostgreSQL 컨테이너를 소유합니다. pkg/irisdurable/...의 race 테스트를 실제 DB로 실행하고 필수 pgstore 사례의 pass와 전체 skip=0을 확인합니다. 컨테이너를 준비할 수 없으면 릴리스 검증은 실패합니다.