상세 매뉴얼

HTTP Ingress 및 라우팅

Router DSL(M151)을 활용한 타입 안정적이고 명시적인 HTTP 경계 구축.

라우팅 예제 매뉴얼 허브 Inspector 가이드

핵심 개념

Router DSL (M151)

그룹화: 관련된 라우트를 공통 접두사(예: /api/v1) 아래에 묶습니다.

매크로: `ranvier_router!`를 사용하여 복잡한 라우팅 테이블을 선언적으로 정의합니다.

계층 모델: 그룹 내에 서브 그룹을 중첩하여 API 구조를 표현합니다.

타입 안정 라우팅

경로 파라미터: URL 내 변수(예: /user/:id)를 원하는 타입으로 직접 추출합니다.

메서드 보호: GET, POST, PUT, DELETE 등 특정 HTTP 메서드만 허용하도록 제한합니다.

명시적 제어: 숨겨진 '미들웨어 마법' 없이 모든 변환이 표준 Axon 단계로 처리됩니다.

Body 처리

JsonBody<T>: 타입 검증이 포함된 JSON 요청/응답을 네이티브로 지원합니다.

스트리밍: 메모리를 과도하게 사용하지 않고 대용량 페이로드를 처리합니다.

Server-Sent Events (SSE): EventSource 스트림 브리지로 text/event-stream을 지원합니다 (M158).

멀티파트: Multipart 추출기로 multipart/form-data 파일 업로드를 크기 제한과 함께 파싱합니다 (M159).

제한(Limits): 라우트별 또는 전역 본문 크기 제한을 설정합니다.

역량 스냅샷

가능

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

빠른 시작

Ranvier::http()
  .bind("0.0.0.0:3000")
  .route("/", hello_axon)
  .route_group("/api/v1", |v1| {
      v1.route("/users", user_axon)
  })
  .run().await?;

주요 워크플로

API 로직을 위한 Schematic을 정의합니다.

Axon을 URI 및 HTTP 메서드에 바인딩합니다.

특정 그룹에 미들웨어 레이어(CORS, Auth)를 추가합니다.

Path<T> 익스트랙터를 사용하여 경로 파라미터를 추출합니다.

검증 명령

워크스페이스 예제 빌드 확인 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에서 확인하세요.