Ranvier 매뉴얼

코어 런타임과 경계 가이드

Axon, Outcome, Ingress/Egress 경계를 기준으로 구현·검증 규칙을 확인합니다.

소개 튜토리얼 매뉴얼 허브 샘플

핵심 개념

레이어 모델

Core: 프로토콜 독립 계약(Transition, Outcome, Bus, Schematic).

Runtime: Axon이 타입 기반 의사결정 흐름을 실행.

Adapter: ingress/egress 경계에서 프로토콜을 상태와 응답으로 매핑.

코어 타입

Transition: 비동기 상태 변환 계약.

Outcome: Next, Branch, Jump, Emit, Fault.

Bus: 필요한 순간에만 읽는 타입 기반 리소스 컨테이너.

구조적 보장

Ingress는 요청을 타입 입력 상태로 변환합니다.

Schematic은 정적·비실행 아티팩트입니다.

런타임 전에 diff/검증/시각화에 사용합니다.

LLM 제안은 반영 전에 명시적 리뷰를 거칩니다.

하위 crate 구성

`ranvier-core`

Ecosystem: crates.io

Version: 0.30.0

Status: released

Transition, Outcome, Bus, Schematic 같은 프로토콜 독립 코어 계약을 정의합니다.

사용 시점: HTTP 어댑터와 분리된 의사결정 흐름을 모델링할 때 사용합니다.

관련 예제

typed-state-tree basic-schematic

상세 보기

`ranvier-macros`

Ecosystem: crates.io

Version: 0.30.0

Status: released

회로/라우트 연결 보일러플레이트를 줄이는 매크로를 제공합니다.

사용 시점: 선언형 매크로 기반 연결로 가독성과 일관성을 높이고 싶을 때 사용합니다.

상세 보기

`ranvier-runtime`

Ecosystem: crates.io

Version: 0.30.0

Status: released

Axon 실행 엔진과 상태 전이/흐름 제어 오케스트레이션을 제공합니다.

사용 시점: 재시도/실패 경로를 포함해 회로를 실제 실행할 때 사용합니다.

관련 예제

order-processing-demo retry-dlq-demo

상세 보기

`ranvier-http`

Ecosystem: crates.io

Version: 0.30.0

Status: released

HTTP ingress/egress 경계, 라우팅, 타입 추출기, 전송 매핑을 제공합니다.

사용 시점: Axon 회로를 HTTP API로 노출할 때 사용합니다.

관련 예제

routing-demo multipart-upload-demo

상세 보기

`ranvier-std`

Ecosystem: crates.io

Version: 0.30.0

Status: released

flow/math/logic/string/debug 등 표준 노드 프리미티브를 제공합니다.

사용 시점: 커스텀 노드 구현 없이 공통 로직을 빠르게 조합할 때 사용합니다.

관련 예제

std-lib-demo

상세 보기

`ranvier-audit`

Ecosystem: crates.io

Version: 0.30.0

Status: released

추적 가능한 운영 기록을 위한 감사 이벤트 싱크와 헬퍼 타입을 제공합니다.

사용 시점: 위변조 감지형 또는 정책 기반 감사 추적이 필요할 때 사용합니다.

관련 예제

audit-demo

상세 보기

`ranvier-compliance`

Ecosystem: crates.io

Version: 0.30.0

Status: released

서비스 흐름의 정책/규제 정합성을 위한 컴플라이언스 헬퍼 표면입니다.

사용 시점: 워크플로에 명시적 컴플라이언스 체크포인트가 필요할 때 사용합니다.

관련 예제

compliance-demo

상세 보기

`ranvier-inspector`

Ecosystem: crates.io

Version: 0.30.0

Status: released

노드별 메트릭, 페이로드 캡처, 조건부 중단점, 정체 감지를 제공하는 Inspector REST + WebSocket 서버입니다.

사용 시점: 런타임 관측에 사용합니다: 처리량/레이턴시 백분위 모니터링, 페이로드 검사, 조건부 중단점, 정체 노드 감지.

관련 예제

studio-demo inspector-demo

상세 보기

`ranvier-openapi`

Ecosystem: crates.io

Version: 0.30.0

Status: released

Ranvier HTTP 서비스용 OpenAPI 명세 생성/노출 기능을 제공합니다.

사용 시점: 클라이언트가 기계 판독 가능한 API 계약을 필요로 할 때 사용합니다.

관련 예제

openapi-demo

상세 보기

`ranvier`

Ecosystem: crates.io

Version: 0.30.0

Status: released

주요 Ranvier API 표면(core, runtime, HTTP)을 재노출하는 파사드 crate입니다.

사용 시점: 온보딩/초기 프로토타입에서 단일 의존성으로 시작하고 싶을 때 사용합니다.

관련 예제

hello-world

상세 보기

역량 스냅샷

가능

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 check --workspace
cargo run -p typed-state-tree
cargo run -p basic-schematic

주요 워크플로

Axon/Outcome 계약으로 의사결정 흐름을 명시적으로 구성합니다.

코어는 프로토콜 독립으로 유지하고, HTTP는 어댑터에서 연결합니다.

Schematic 추출 후 배포 전에 구조 diff/검증을 수행합니다.

검증 명령

워크스페이스 예제 빌드 확인 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

Guard nodes demo compile (CorsGuard, RateLimit, SecurityHeaders, IpFilter) cargo check -p guard-demo

Auth JWT role-based demo compile (IamVerifier, IamPolicy, with_iam) cargo check -p auth-jwt-role-demo

샘플 재현 페이지

재현 절차는 /ko/manual/samples/ranvier에서 확인하세요.

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