Ranvier
EN 튜토리얼 시작

현황

서브모듈 상태를 한눈에 확인하세요.

각 모듈의 현재 가능 범위와 검증 방법을 한 곳에서 확인할 수 있습니다.

업데이트 일자: 2026-03-11

ranvier

처음 사용하는 개발자가 타입 안전한 의사결정 흐름을 만들고 기준 예제를 실행하며 HTTP 어댑터를 연결할 수 있는 핵심 Rust 모듈입니다.

단계: 안정화 중
커밋: 418efdf 최종 검증: 2026-03-07

버전

현재 0.30.0
라인 0.30.x
채널 안정
배포 상태 배포됨
버전 출처 ranvier/Cargo.toml [workspace.package.version]

배포 산출물

ranvier-core crates.io 0.30.0 배포됨
ranvier-macros crates.io 0.30.0 배포됨
ranvier-runtime crates.io 0.30.0 배포됨
ranvier-http crates.io 0.30.0 배포됨
ranvier-std crates.io 0.30.0 배포됨
ranvier-audit crates.io 0.30.0 배포됨
ranvier-compliance crates.io 0.30.0 배포됨
ranvier-inspector crates.io 0.30.0 배포됨
ranvier-openapi crates.io 0.30.0 배포됨
ranvier crates.io 0.30.0 배포됨

현재 가능한 작업

  • 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의 토큰/클레임 검증 매핑은 게이트웨이/배포 인프라 측 통합이 필요합니다. deployment-gateway

검증 명령

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

참고 문서

  • ranvier/README.md

cli

Ranvier 사용자가 명령 표면을 확인하고 예제 기반 schematic/projection 산출물을 생성할 수 있는 명령줄 도구입니다.

단계: 안정화 중
커밋: 9818f79 최종 검증: 2026-03-07

버전

현재 0.5.0
라인 0.5.x
채널 안정
배포 상태 배포됨
버전 출처 cli/Cargo.toml [package.version]

배포 산출물

ranvier-cli crates.io 0.5.0 배포됨

현재 가능한 작업

  • `ranvier --help`로 명령 표면과 사용법을 빠르게 확인할 수 있습니다.
  • 워크스페이스 예제에서 schematic 산출물을 생성할 수 있습니다.
  • `ranvier schematic diff`로 git ref 간 회로 구조 변화를 비교할 수 있습니다.
  • TOML 규칙 기반 구조 정책 검증을 실행하고 위반 시 비정상 종료코드를 반환할 수 있습니다.
  • 입력 산출물 처리 전에 schematic 스키마 버전 호환성을 검증할 수 있습니다.
  • schematic/timeline/example 입력에서 trace projection 산출물을 생성할 수 있습니다.
  • `ranvier new`로 매크로 중심 템플릿에서 새 프로젝트를 생성할 수 있습니다.
  • `ranvier migrate`로 dry-run/verbose/JSON 모드의 버전 마이그레이션 워크플로를 실행할 수 있습니다.
  • `ranvier catalog list/fetch/verify`로 원격 또는 로컬 카탈로그에서 예제 schematic을 조회하고 가져올 수 있습니다.
  • `ranvier test`로 API 테스트 컬렉션을 헤드리스 실행할 수 있습니다 — 순차 HTTP 실행, 어설션 평가(10개 연산자), 캡처 체이닝, 환경 변수 보간, glob 지원, text/JSON/JUnit XML 형식 출력으로 CI 통합 지원.
  • `ranvier new`로 dialoguer 기반 인터랙티브 프로젝트 생성(10개 템플릿), 의존성 선택기(DB/Auth/Observability), `.ranvier/collections/` 및 `.env.example` 자동 생성을 수행할 수 있습니다.
  • `ranvier status build` 및 `ranvier status from-schematic`으로 Schematic JSON에서 자립형 HTML 상태 페이지를 생성할 수 있습니다. v0.21 ranvier-status 크레이트 통합에서 복원됨.

해소 대상 제한

현재 해소 대상 제한 항목이 없습니다.

제품 경계

명시된 제품 경계 항목이 없습니다.

검증 명령

CLI 명령 표면 확인 통과
cargo run -- --help
Schematic export 명령 확인 통과
cargo run -- schematic basic-schematic --output schematic.json
Schematic diff 명령 표면 확인 통과
cargo run -- schematic diff --help
Schematic policy check 명령 표면 확인 통과
cargo run -- schematic policy check --help
Catalog list 명령 확인 통과
cargo run -- catalog list --local --json
Catalog fetch + verify E2E 확인 통과
cargo run -- catalog fetch basic-schematic --local --output /tmp/basic.json && cargo run -- catalog verify /tmp/basic.json

참고 문서

  • cli/README.md

studio

Ranvier schematic을 불러와 오버레이를 확인하고 필터링된 이력 데이터를 내보낼 수 있는 사용자용 시각화 Inspector 앱입니다.

단계: 활성 개발
커밋: 0c4028e 최종 검증: 2026-02-07

버전

현재 0.0.1
라인 0.0.x
채널 프리뷰
배포 상태 내부 배포
버전 출처 studio/package.json [version]

배포 산출물

ranvier-studio npm 0.0.1 내부용

현재 가능한 작업

  • Studio 뷰어에서 schematic 노드/엣지 그래프를 로드하고 렌더링할 수 있습니다.
  • 원격 inspector endpoint에 attach해 `/schematic`과 trace 오버레이를 불러올 수 있습니다.
  • 원격 attach 요청에 선택적 Bearer 인증과 role/tenant 헤더를 함께 보낼 수 있습니다.
  • failure 이력을 필터/그룹으로 정리해 incident triage 속도를 높일 수 있습니다.
  • 필터링된 failure 보고서를 redact/profile preset과 함께 JSON으로 export할 수 있습니다.
  • 내보낸 보고서에 checksum/signature 메타데이터를 포함해 무결성 검증에 활용할 수 있습니다.

해소 대상 제한

현재 해소 대상 제한 항목이 없습니다.

제품 경계

  • Studio는 inline source navigation의 1차 IDE 도구가 아니며 이 범위는 VSCode 확장에 있습니다. studio
  • role/tenant 정책의 최종 강제는 여전히 서버/게이트웨이 정책에 의존합니다. deployment-gateway

검증 명령

원격 schematic 로드 확인 통과
Studio UI > Attach endpoint > Load /schematic
trace 오버레이 갱신 확인 통과
Studio UI > Load /trace/public and /events overlays
필터링 이력 export 확인 통과
Studio UI > Failure panel > Export JSON (redact/profile optional)

참고 문서

  • studio/README.md

vscode

Ranvier를 VSCode에서 처음 사용할 때 필요한 회로 시각화, source jump, diagnostics 오버레이, 이슈 이동 흐름을 제공하는 확장입니다.

단계: 활성 개발
커밋: 7f096b5 최종 검증: 2026-03-09

버전

현재 0.2.8
라인 0.2.x
채널 프리뷰
배포 상태 published
버전 출처 vscode/package.json [version]

배포 산출물

ranvier-vscode vscode-marketplace 0.2.8 배포됨

현재 가능한 작업

  • `schematic.json` 기반 회로 그래프를 렌더링하고 `Ranvier Circuit Nodes` 패널과 동기화할 수 있습니다.
  • 매핑 정보가 있을 때 선택한 회로 노드에서 소스 위치로 점프할 수 있습니다.
  • 현재 편집 파일/라인 문맥에서 매핑된 회로 노드를 하이라이트할 수 있습니다.
  • `diagnostics.json` 결과를 웹뷰/사이드바/VSCode Problems에 투영할 수 있습니다.
  • 명령 팔레트에서 현재 줄 기준 매핑된 회로 노드를 바로 찾을 수 있습니다.
  • 명령과 기본 단축키로 다음/이전 노드 이슈를 이동할 수 있습니다.
  • 팀 도입을 위해 EN/KO 로캘 UX와 단축키 오버라이드 템플릿을 제공합니다.
  • Inspector 서버에 자동 연결하고 실시간 히트맵(트래픽/레이턴시/에러/없음)으로 노드 메트릭을 시각화할 수 있습니다.
  • 이벤트 스트림 패널에서 노드/타입/텍스트 필터로 Inspector 생애주기 이벤트를 실시간 모니터링할 수 있습니다.
  • 임계값을 초과한 정체 노드를 pulsing glow 애니메이션으로 시각적 경고 표시할 수 있습니다.
  • 6종 Rust 코드 스니펫(rvtransition, rvroute, rvaxon, rvbus, rvtest)을 삽입하여 빠른 Ranvier 개발을 지원합니다.
  • catalog.json의 예제를 통합 터미널에서 탐색 및 실행할 수 있습니다 (`ranvier.runExample` 명령어).
  • Circuit-Aware API Explorer 사이드바에서 API 엔드포인트를 테스트할 수 있습니다 — Inspector에서 라우트 자동 발견, 헤더/파라미터/본문/인증 탭으로 요청 구성, 상태/시간/회로 트레이스와 함께 응답 표시, 캐시된 스키마로 오프라인 사용 가능.
  • `.ranvier/collections/`에서 요청 컬렉션을 관리할 수 있습니다 — 저장, 복제, 이름변경, 삭제, 필터, 정렬, 그룹 기능. 실행 이력 자동 저장 및 보관 정책 설정 가능.
  • JSON Schema 기반 빈 본문 템플릿 및 faker 자동 채움 데이터를 생성할 수 있습니다 (Inspector 서버 우선, 클라이언트 측 폴백). 요청별 프리셋 저장, `.ranvier/environments/` 파일의 `{{변수}}` 보간 지원.
  • 컬렉션을 `.ranvier-bundle.json` 또는 단일 요청을 `.ranvier-request.json`으로 내보낼 수 있습니다 — 민감 패턴 자동 감지 비밀 수정 포함. 충돌 감지 및 해결 다이얼로그와 함께 가져오기 지원.
  • 일괄 요청 실행(순차 진행 추적), 어설션 평가(10개 연산자, JSON 경로 대상), JSON Schema 기반 본문 검증, JUnit 호환 결과 요약을 제공합니다. 키보드 코드 단축키(Ctrl+R 접두사)로 전송, 템플릿, faker 작업 지원.
  • WebSocket 엔드포인트를 양방향 메시지 로그, 연결/해제 라이프사이클, 자동 재연결, 서브프로토콜 헤더, 메시지 필터링(text/JSON, 키워드 검색)으로 테스트할 수 있습니다.
  • SSE 엔드포인트를 이벤트 스트림 로그(type, data, id, retry), 이벤트 타입 필터, Last-Event-ID 재연결, 세션 히스토리로 테스트할 수 있습니다.
  • Svelte 5 기반의 통합된 탭 방식 사이드바로 확장 내 각종 보조 도구(Circuit, Toolbox, Features, API)를 단일 뷰에서 쉽고 빠르게 전환 사용할 수 있습니다.
  • API Explorer, Toolbox, Feature Hub 패널 등에서 Vite/Svelte 5 렌더링 초기화 시 발생할 수 있는 잠재적 런타임/CSP 충돌을 방지하고 안정적인 렌더링을 보장합니다.

해소 대상 제한

현재 해소 대상 제한 항목이 없습니다.

제품 경계

명시된 제품 경계 항목이 없습니다.

검증 명령

회로 뷰 열기 확인 통과
Command Palette > Ranvier: Open Circuit View
진단 오버레이 반영 확인 통과
Command Palette > Ranvier: Refresh Diagnostics
노드 이슈 이동 확인 통과
Command Palette > Ranvier: Go To Next Node Issue / Ranvier: Go To Previous Node Issue
서버 연결 + 히트맵 모드 전환 확인 통과
Connect to Inspector server > Toggle heatmap modes in Circuit View
이벤트 스트림 패널 필터링 확인 통과
Circuit View > Events panel > Filter by node/type/text
정체 노드 시각적 경고 확인 통과
Stall threshold exceeded > Node shows pulsing glow

참고 문서

  • vscode/README.md
  • vscode/README.ko.md
검증 명령이 실패하면 모듈 설정과 필요한 입력 파일을 확인한 뒤 같은 명령을 다시 실행하세요.