상세 매뉴얼

지속성 및 크래시 복구

프로덕션급 워크플로 내구성과 사가(Saga) 스타일 보상 패턴을 다룹니다.

운영 런북 매뉴얼 허브 지속성 데모

핵심 개념

복구 흐름

Append: 런타임이 모든 성공적인 단계마다 체크포인트를 저장합니다.

Crash: 외부 효과는 이미 커밋된 상태로 유지되며 프로세스 상태만 소멸합니다.

Resume: 재시작된 프로세스가 추적 데이터를 로드하고 마지막 커서부터 재개합니다.

내구성 어댑터

PostgreSQL: ACID를 보장하는 다중 프로세스용 내구성 저장소.

Redis: 고처리량, 밀리초 미만 지연 시간의 휘발성 체크포인트.

InMemory: 의존성 없는 로컬 개발 및 테스트용 어댑터.

사가 패턴

Compensation: 복구 불가능한 부작용에 대한 롤백 훅을 정의합니다.

Idempotency: 동일 추적 ID에 대해 보상 훅이 단 한 번만 실행되도록 보장합니다.

Auto-Trigger: 런타임이 Fault 발생 시 보상 훅을 자동으로 트리거합니다.

역량 스냅샷

가능

Axon/Transition/Outcome 계약, 명시적 Bus 주입, 무결 파이프라인용 `Never` 에러 타입으로 타입 안전한 의사결정 흐름을 구성할 수 있습니다. 10개 크레이트 전체를 다루는 61개 유지보수 예제 포함.

프로토콜-애그노스틱 코어 회로를 HTTP 인그레스 어댑터에 연결하고 동적 라우팅, 요청 추출, 라이프사이클 제어, 미들웨어 조합, 경로 단위 정책 override를 구성할 수 있습니다.

`ranvier-std` Guard 노드(CorsGuard, RateLimit, SecurityHeaders, IpFilter)로 HTTP 보안/정책을 Schematic 내에서 적용할 수 있습니다.

`ranvier-openapi`로 요청/응답 계약 기반 OpenAPI 문서와 Swagger UI를 생성할 수 있습니다.

정적 디렉터리 서빙과 SPA fallback, cache/compression 옵션으로 풀스택형 제공 경로를 구성할 수 있습니다.

WebSocket/SSE 실시간 흐름을 처리하고 연결/세션 컨텍스트를 Bus에 주입할 수 있습니다.

LLM-as-Transition 패턴으로 AI 분류/모더레이션 파이프라인을 구축하고 콘텐츠 정책을 적용할 수 있습니다.

`TestApp/TestRequest/TestResponse`로 인-프로세스 HTTP 통합 테스트를 작성하고 `AxonTestKit`/`Timeline`으로 실행 경로를 단언할 수 있습니다.

`ranvier-inspector`로 TraceStore 영속 저장, BearerAuth 인증, AlertHook 알림, OTLP 연동을 구성할 수 있습니다.

session/job/persistence 패턴을 실행하고 PersistenceStore와 compensation hook으로 장애 워크플로를 체크포인트에서 재개할 수 있습니다.

cargo-semver-checks와 schematic diff/policy CLI 명령으로 API 호환성과 구조 드리프트를 검증할 수 있습니다.

내장 Inspector REST + WebSocket 서버로 노드별 메트릭(처리량, 레이턴시 백분위, 에러율) 수집, 페이로드 검사, DLQ 관리, 조건부 중단점, 정체 감지를 제공할 수 있습니다.

`.with_input_schema::<T>()` 빌더 API 또는 `#[transition(schema)]` 매크로 속성으로 회로 노드에 JSON Schema를 등록할 수 있습니다. Inspector가 스키마 포함 라우트 메타데이터 제공(`GET /api/v1/routes`), 실행 중인 회로에 HTTP 요청 릴레이(`POST /api/v1/relay`), 스키마 기반 빈 템플릿/랜덤 샘플 생성(`POST /api/v1/routes/schema`, `POST /api/v1/routes/sample`)을 제공합니다.

`RanvierConfig`(`ranvier.toml` + 환경변수 오버라이드 + 프로필 시스템)로 프로덕션 인프라를 구성하고 `init_logging()`(JSON/pretty/compact)으로 구조화 로깅을 초기화하며 `rustls` TLS를 선택적으로 활성화할 수 있습니다.

RFC 7807 `ProblemDetail`/`IntoProblemDetail`로 표준 에러 응답을 반환하고 `RetryPolicy`(고정/지수 백오프)와 `Axon::then_with_retry()`로 실패한 트랜지션을 재시도할 수 있습니다.

criterion 마이크로벤치마크(Axon 레이턴시, Bus 연산, Transition 체인)와 Axum/Actix-web 비교 서버로 정량 성능 기준을 제공합니다.

세 개의 참조 애플리케이션으로 실제 패턴을 보여줍니다: Todo API(CRUD + JWT 인증), Chat Server(다중 방 WebSocket), E-commerce Order Pipeline(4단계 Saga 보상 + 감사 추적 + 다중 테넌시).

`ranvier migrate --from 0.20 --to 0.25`로 버전 간 import 경로 교체, 크레이트 의존성 전환을 자동화할 수 있습니다. TOML 기반 마이그레이션 규칙(text_replace, rename_import, warn)과 --dry-run 모드를 제공합니다.

Inspector `/metrics` Prometheus 포맷 메트릭 내보내기, TelemetryConfig으로 OTLP TracerProvider 자동 초기화, AccessLogGuard 경로 마스킹 HTTP 요청 로깅, PostgresAuditSink 해시 체인 감사 이벤트 영속 저장, OpenAPI SecurityScheme(bearerAuth) + ProblemDetail(RFC 7807) 에러 응답 자동 등록을 수행할 수 있습니다.

PHILOSOPHY.md('Opinionated Core, Flexible Edges' 원칙)를 통해 프레임워크 설계 철학을 이해하고 DESIGN_PRINCIPLES.md(Paradigm Test, Tower 분리, Opinionated Core 적용을 다루는 ADR 형식)로 아키텍처 결정 근거를 파악할 수 있습니다.

두 가지 인증 접근법을 구현할 수 있습니다: Transition 기반(examples/auth-transition — Bus 컨텍스트 전파, Schematic 시각화, 쉬운 테스트) 또는 Tower 통합(examples/auth-tower-integration — 생태계 호환성을 위한 AsyncAuthorizeRequest 트레잇).

docs/guides/auth-comparison.md로 인증 전략을 비교할 수 있습니다: 7개 항목 비교 표, 성능 벤치마크(둘 다 ~1-2μs 오버헤드), 사용 시기 결정 트리, Transition과 Tower 접근법 간 마이그레이션 경로 제공.

제한

role/tenant header의 토큰/클레임 검증 매핑은 게이트웨이/배포 인프라 측 통합이 필요합니다.

빠른 시작

// Cargo.toml: feature persistence-postgres
let store = PostgresPersistenceStore::new(pool);
store.ensure_schema().await?;
bus.insert(PersistenceHandle::from_store(store));

주요 워크플로

Ingress 경계에서 PersistenceHandle을 Bus에 주입합니다.

부작용이 있는 Transition에 대해 CompensationHook을 정의합니다.

규제/감사 요건에 따라 데이터 보존 정책(TTL/Purge)을 구성합니다.

프로덕션에서 checkpoint_failures_total 메트릭을 모니터링합니다.

검증 명령

워크스페이스 예제 빌드 확인 cargo check --workspace

타입 흐름 예제 실행 확인 cargo run -p typed-state-tree

Guard 노드 (CorsGuard/RateLimit/SecurityHeaders/IpFilter) 테스트 확인 cargo run -p routing-params-demo

OpenAPI 생성기 회귀 테스트 확인 cargo test -p ranvier-http

OpenAPI 데모 컴파일 확인 cargo test -p ranvier-http --test test_app_health

정적 서빙/SPA fallback 회귀 테스트 확인 cargo test -p ranvier-http --features validation

정적 SPA 데모 컴파일 확인 cargo run -p ranvier-http --example validation_struct_level --features validation

WebSocket ingress 업그레이드/이벤트 브리지 테스트 확인 cargo test -p ranvier-std guard

WebSocket ingress 데모 컴파일 확인 cargo test -p ranvier-openapi

Inspector TraceStore + BearerAuth 테스트 확인 cargo check -p openapi-demo

워크스페이스 전체 테스트 스윕 확인 cargo test -p ranvier-http

예제 회귀 스모크(M119) 확인 cargo check -p static-spa-demo

Inspector quick-view 스모크 확인 cargo test -p ranvier-http

Schematic diff/policy 스모크 확인 cargo check -p websocket-ingress-demo

Fullstack embedded static 스모크 확인 cargo test -p ranvier-inspector

M132 ecosystem reference 조합 스모크 확인 cargo test --workspace

Session 패턴 예제 컴파일 확인 ./scripts/m119_examples_smoke.ps1

Inspector 메트릭 수집 + stall 감지 테스트 확인 ./scripts/m131_inspector_quickview_smoke.ps1

Inspector 조건부 중단점 + 페이로드 캡처 테스트 확인 ./scripts/m131_schematic_diff_policy_smoke.ps1

Fullstack embedded static smoke ./scripts/m131_fullstack_embedded_smoke.ps1

Runtime timeline integration assertion cargo test -p ranvier-runtime timeline_assertion_works_in_integration_test

M132 SeaORM ecosystem reference run cargo run -p ecosystem-seaorm-demo

M132 Diesel ecosystem reference run cargo run -p ecosystem-diesel-demo

M132 Redis ecosystem reference run cargo run -p ecosystem-redis-demo

M132 NATS ecosystem reference run cargo run -p ecosystem-nats-demo

M132 Meilisearch ecosystem reference run cargo run -p ecosystem-meilisearch-demo

Session pattern example compile cargo check -p session-pattern

Inspector metrics + stall detection tests cargo test -p ranvier-inspector metrics stall

Inspector conditional breakpoint + payload capture tests cargo test -p ranvier-inspector breakpoint payload

Ecosystem: crates.io

Version: 0.30.0

Status: released

최신 capability 상태와 버전 산출물은 /ko/status에서 확인하세요.