pyjwt-rs

jwt_rs는 PyJWT 호환을 목표로 하는 Rust 기반 Python 확장 모듈입니다.

핵심 목표는 두 가지입니다.

• 같은 코드에 import jwt_rs as jwt만 바꿔서 동작할 것
• Rust 코어로 주요 공개키 JWT workload에서 PyJWT보다 더 빠를 것

Current Status

현재 공개 표면은 PyJWT 스타일을 유지합니다.

• encode(payload, key, algorithm="HS256", headers=None)
• decode(token, key, algorithms=None, options=None, audience=None, issuer=None, leeway=0)
• decode_complete(...)
• get_unverified_header(token)
• PyJWS, PyJWK, algorithm registry

현재 지원 알고리즘:

• HMAC: HS256, HS384, HS512
• RSA: RS256, RS384, RS512, PS256, PS384, PS512
• EC: ES256, ES384, ES512, ES256K
• EdDSA

테스트 상태:

• 324 passed

품질 정책:

• 테스트는 hidden warning 없이 통과해야 합니다. CI는 -W error 기반 게이트를 사용합니다.
• 의도된 skip은 .quality/pytest-allowlist.json에 명시되어야 합니다.
• 릴리스/호환성 작업은 공개 GitHub issue와 milestone으로 추적합니다.
• 자세한 운영 정책은 CONTRIBUTING.md, 호환성 갭은 COMPATIBILITY_CHECKLIST.md 에서 관리합니다.

Usage

import jwt_rs as jwt

token = jwt.encode({"sub": "alice"}, "secret", algorithm="HS256")
claims = jwt.decode(token, "secret", algorithms=["HS256"])
header = jwt.get_unverified_header(token)

Performance

성능 목표는 모든 경로 일괄 2배가 아니라, 먼저 실사용 공개키 경로에서 PyJWT를 확실히 추월하는 것입니다.

아래 블록은 benchmark 스크립트로 자동 생성됩니다. 수동으로 적지 않습니다.

Auto-generated from scripts/benchmark_same_api.py on 2026-04-21T07:14:04+00:00 using --iterations 150 --warmup 20.

현재 same-API benchmark 기준:

Case	encode	decode	decode_complete
hs256	1.43x	2.10x	2.04x
rs256	59.10x	2.15x	2.13x
es256	3.12x	1.76x	1.81x
eddsa	1.59x	1.06x	1.06x

좋은 구간:

• rs256.encode: jwt_rs가 PyJWT 대비 59.10x
• es256.encode: jwt_rs가 PyJWT 대비 3.12x
• es256.decode: jwt_rs가 PyJWT 대비 1.76x
• eddsa.encode: jwt_rs가 PyJWT 대비 1.59x

아직 미달인 구간:

• 현재 주요 추적 경로는 모두 PyJWT 이상입니다.

해석:

• 1.00x 초과면 jwt_rs가 빠릅니다.
• 2.00x 이상이면 README 목표인 PyJWT 대비 2배를 넘긴 것입니다.
• 현재 목표는 특히 공개키 경로에서 이 값을 끌어올리는 것입니다.

벤치 재현 명령:

uv run --with pyjwt python scripts/benchmark_same_api.py --iterations 150 --warmup 20

README 자동 갱신 명령:

uv run python scripts/update_readme_bench.py

Development

source "$HOME/.cargo/env"
cd pyjwt-rs
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
uv run --with maturin maturin develop
uv run pytest -q

Notes

• Python은 호환 인터페이스를 담당하고, 코어 sign/verify hot path는 Rust가 담당합니다.
• 현재 공개키 알고리즘 경로는 Rust 내부 OpenSSL backend를 사용합니다.
• options={"verify_signature": False} 경로는 별도 insecure decode 흐름을 사용합니다.
• 완전한 PyJWT parity를 목표로 하지만, 성능 최적화를 위해 내부 구현은 PyJWT와 다릅니다.
• 배포 버전과 PyJWT 호환 버전 구분은 VERSIONING.md 에 정리했습니다.