상세 매뉴얼

표준 라이브러리 (ranvier-std)

로직 제어, 흐름 관리 및 데이터 조작을 위한 내장 노드 집합.

표준 라이브러리 예제 매뉴얼 허브

핵심 개념

로직 노드

FilterNode: 조건부 검증 및 거부(Reject) 흐름 제어.

RandomBranch: 확률 기반 트래픽 분사 (A/B 테스팅).

SwitchNode: 요청에 대한 다중 패턴 매칭 분기.

흐름 제어

DelayNode: 지정된 시간 동안 실행 일시 중단 (비동기 네이티브).

IdentityNode: 구조적 명시성을 위한 플레이스홀더 노드.

HaltNode: 워크플로 브랜치의 명시적 종료.

데이터 유틸리티

MathNode: 숫자 상태에 대한 표준 산술 연산.

StringNode: 문자열 변환, 대소문자 변경 및 결합 작업.

LogNode: 트레이스 통합 구조화된 로깅.

역량 스냅샷

가능

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

빠른 시작

use ranvier_std::prelude::*;

Axon::new("LogicLoop")
  .then(FilterNode::new(|x| x > 100))
  .then(LogNode::info("Validated input!"))
  .then(MathNode::add(10));

주요 워크플로

`Cargo.toml`에 `ranvier-std`를 추가합니다.

`SwitchNode`를 사용하여 복잡한 의사 결정 트리를 구성합니다.

노드 단위의 전이 디버깅을 위해 `LogNode`를 적용합니다.

카나리 배포나 실험을 위해 `RandomBranch`를 활용합니다.

검증 명령

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

하위 crate 구성

`ranvier-core`

Ecosystem: crates.io

Version: 0.30.0

Status: released

`ranvier-macros`

Ecosystem: crates.io

Version: 0.30.0

Status: released

`ranvier-runtime`

Ecosystem: crates.io

Version: 0.30.0

Status: released

`ranvier-http`

Ecosystem: crates.io

Version: 0.30.0

Status: released

`ranvier-std`

Ecosystem: crates.io

Version: 0.30.0

Status: released

재사용 가능한 고수준 Transition들을 제공하는 코어 라이브러리.

`ranvier-audit`

Ecosystem: crates.io

Version: 0.30.0

Status: released

`ranvier-compliance`

Ecosystem: crates.io

Version: 0.30.0

Status: released

`ranvier-inspector`

Ecosystem: crates.io

Version: 0.30.0

Status: released

`ranvier-openapi`

Ecosystem: crates.io

Version: 0.30.0

Status: released

`ranvier`

Ecosystem: crates.io

Version: 0.30.0

Status: released

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