Ticketing Rust 라이브러리 ​

리포지토리 ​

예제 ​

간단한 예제 ​

Tokio 기반 비동기 API입니다. 브로커는 앱 시작 시 한 번 만들어 공유하면 됩니다. wait=0은 queue 없는 즉시 시도이고 최대 255초, lease는 1~250초입니다. 네 번째 min_work_budget은 필수이며 0도 허용됩니다. 시간은 wire 초로 올림하고 범위 초과, lease 0, budget 250초 초과 또는 정규화한 lease 초과는 송신 전에 오류로 반환하며 값을 잘라 맞추지 않습니다.

use std::time::Duration;
use ticketing::TicketBroker;

let broker = TicketBroker::connect(["127.0.0.1:5225"]);
broker.wait_ready(Duration::from_secs(5)).await;

let ticket = broker.acquire(
    "key",
    Duration::from_secs(5),
    Duration::from_secs(30),
    Duration::from_secs(2), // 최소 작업 + pause + DB 종료 budget
).await?;
let token = ticket.token();
// 같은 DB transaction에서 token high-water 검사/갱신과 업무 write
ticket.release().await?;

ticket을 drop하면 bounded best-effort 반납 queue에 넣습니다. 성공을 보장하는 동작은 아니므로 결과가 필요하면 ticket.release().await를 사용합니다.

알아 두면 좋은 동작 ​

• writer가 frame을 시작하기 전 취소된 요청만 unsent로 처리할 수 있습니다. 한 바이트라도 송신할 가능성이 생긴 뒤 확정 응답을 잃으면 TicketError::Indeterminate 이며 같은 owner로 재전송하지 않습니다.
• acquire Future를 취소하면 unsent 요청은 제거하고, possible-send 요청은 session을 닫습니다. 그 사이 grant가 해석됐다면 Ticket을 공개하지 않고 서버가 돌려준 정확한 token으로 best-effort 반납합니다.
• M과 모든 E는 session-fatal입니다(auth_failed는 TicketError::Auth). malformed 응답도 session을 닫으며, 아직 확정되지 않은 possible-send acquire는 Indeterminate입니다.
• TicketError::Busy 는 server capacity가 이번 요청을 확정 미획득으로 거부했다는 뜻이며 즉시 반환됩니다. 내부 자동 재시도는 없으며 caller가 backoff 뒤 새 acquire 여부를 결정합니다.
• 명시적·보상 반납은 호출 또는 queue 등록 시점부터 계산한 절대 5초 deadline 안에서만 정확한 token으로 재시도합니다. R은 성공, N은 이미 없거나 현재 token이 아님이 확정된 결과이고, deadline까지 최종 응답이 없으면 성공으로 가장하지 않고 오류를 반환합니다.
• TicketError::InsufficientLease면 보수적인 남은 lease가 요구 budget보다 짧아 Ticket을 전달하지 않고 정확한 token으로 반납을 시도한 것입니다. ticket.conservative_valid_before()는 조기 중단 보조값이지 fencing 대체물이 아닙니다.
• ticket.token() 은 u64 펜싱 토큰입니다. persistent DB에서는 high-water와 업무 write를 같은 transaction에서 갱신하고 DB commit/rollback이 끝난 뒤 반납합니다.

보안 옵션 (토큰 · TLS) ​

옵션은 모두 선택입니다. token은 서버의 client_tokens와 맞추고, TLS는 끔 / 시스템 신뢰 저장소 / CA 지정 / 검증 생략(테스트 전용) 네 가지 모드입니다.

use ticketing::{TicketBroker, TlsMode};

let broker = TicketBroker::builder()
    .addrs(["10.0.0.1:5225", "10.0.0.2:5225", "10.0.0.3:5225"])
    .token("123")
    .tls(TlsMode::SystemRoots)
    // .tls(TlsMode::Ca("ca.crt".into()))
    // .tls(TlsMode::InsecureSkipVerify)
    .connect()?;

서버 쪽 토큰·TLS·클러스터 구성은 Ticketing 서버 배포에서 만들 수 있습니다.