Python으로 만든 학습용 Mini Redis 프로젝트입니다. 이 저장소는 단순한 key-value 저장소를 넘어서, CLI -> TCP -> RESP -> Command Routing -> Redis Engine -> Storage / TTL / Persistence / Invalidation / Mongo 흐름이 계층적으로 어떻게 분리되는지 보여주는 데 초점을 둡니다.
아래 순서로 읽으면 현재 프로젝트 구조가 가장 빠르게 이해됩니다.
- 사용자는
mini-redis-cli로 명령을 입력합니다. src/mini_redis/cli/client.py의CLIClient가 입력을 받고, 로컬 메타 명령인지 서버로 보낼 명령인지 구분합니다.src/mini_redis/cli/parser.py가 입력 문자열을{"name": "...", "args": [...]}형태의 공통 Command 객체로 바꿉니다.src/mini_redis/protocol/resp.py의RespCodec가 이 명령을 RESP 바이트로 인코딩합니다.src/mini_redis/network/tcp_client.py의TCPClient가 TCP 소켓으로 서버에 전송합니다.- 서버는
src/mini_redis/network/tcp_server.py에서 요청을 받고, 다시RespCodec으로 RESP를 Command 객체로 디코딩합니다. - 모든 서버 명령은
src/mini_redis/commands/manager.py의CommandManager.execute()로 들어갑니다. CommandManager는src/mini_redis/commands/queue.py의 FIFOCommandQueue를 통해 동시 요청 실행 순서를 직렬화합니다.- 그다음 명령 이름에 맞는 handler가 선택되고, 각 handler가 인자 검증과 명령별 로직 분기를 담당합니다.
- handler는 내부 오케스트레이터인
src/mini_redis/engine/redis.py의Redis객체를 호출합니다. Redis는 실제 데이터 저장과 부가 기능을 위해 Storage, TTL, Persistence, Invalidation, Mongo 매니저를 조합해 사용합니다.- 결과는 다시 RESP 응답으로 인코딩되어 TCP를 통해 CLI로 돌아옵니다.
이 프로젝트는 실행 시점에도 구조가 깔끔하게 나뉘어 있습니다.
src/mini_redis/server_main.py가 서버 시작점입니다.- 여기서
src/mini_redis/bootstrap.py의build_command_manager()를 호출합니다. build_command_manager()는StorageManager,TTLManager,InvalidationManager,PersistenceManager,MongoManager를 생성합니다.- 이 매니저들을 묶어
Redis엔진을 만듭니다. - 각 명령별 handler를 등록한 뒤
CommandManager를 생성합니다. - 마지막으로
TCPServer가CommandManager와RespCodec을 받아 요청 처리를 시작합니다.
src/mini_redis/cli_main.py가 클라이언트 시작점입니다.RespCodec,TCPClient,CLIClient를 조립합니다.CLIClient.run()이 인터랙티브 세션을 시작합니다.
miniRedis/
|-- img/
| `-- mini-redis-architecture.svg # README architecture image
|-- data/ # runtime persistence files
|-- docs/ # extra docs / legacy assets
|-- src/
| `-- mini_redis/
| |-- cli_main.py # CLI entrypoint
| |-- server_main.py # server entrypoint
| |-- bootstrap.py # dependency wiring
| |-- config.py # runtime settings
| |-- types.py # shared Command type
| |-- cli/
| | |-- client.py # terminal UX
| | `-- parser.py # CLI string -> Command
| |-- protocol/
| | `-- resp.py # RESP encode/decode
| |-- network/
| | |-- tcp_client.py # client transport
| | |-- tcp_server.py # server transport
| | `-- timing.py # timed request/response wrapper
| |-- commands/
| | |-- manager.py # single execution entrypoint
| | |-- queue.py # FIFO serialization
| | |-- catalog.py # HELP metadata
| | `-- handlers/ # one file per command family
| |-- engine/
| | `-- redis.py # internal orchestrator
| |-- storage/
| | |-- manager.py # in-memory hash table
| | |-- ttl.py # expiration tracking
| | |-- mongo_adapter.py # pymongo boundary
| | |-- mongo_manager.py # mongo policy / info
| | `-- benchmark.py # benchmark helpers
| |-- invalidation/
| | `-- manager.py # tag index
| `-- persistence/
| |-- manager.py # persistence coordinator
| |-- aof.py # append-only log
| |-- rdb.py # snapshot store
| `-- meta.py # metadata store
`-- tests/ # CLI / RESP / TCP / command / storage tests
- 책임: 입력, 출력, 프롬프트, 로컬 편의 명령 처리
- 핵심 파일:
src/mini_redis/cli/client.py,src/mini_redis/cli/parser.py - 하지 않는 일: 직접 Redis 엔진 호출, 직접 파일 저장
- 책임: RESP 인코딩/디코딩
- 핵심 파일:
src/mini_redis/protocol/resp.py - 하지 않는 일: 비즈니스 로직 처리
- 책임: TCP 연결 생성, 요청 수신/응답 전달
- 핵심 파일:
src/mini_redis/network/tcp_client.py,src/mini_redis/network/tcp_server.py - 하지 않는 일: 명령 해석, storage 접근
- 책임: 명령 진입점 통일, FIFO 실행, handler 라우팅
- 핵심 파일:
src/mini_redis/commands/manager.py,src/mini_redis/commands/queue.py,src/mini_redis/commands/handlers/ - 핵심 포인트: 서버 쪽 명령 실행은 항상
CommandManager를 통과합니다.
- 책임: 여러 내부 매니저를 묶어서 한 번의 명령을 완성
- 핵심 파일:
src/mini_redis/engine/redis.py - 핵심 포인트:
Redis는 저장, TTL, persistence, invalidation, mongo를 조합하는 오케스트레이터입니다.
StorageManager: 메모리 해시 테이블과 incremental rehashingTTLManager: 만료 시각 추적과 expired key 정리InvalidationManager: tag -> keys, key -> tags 인덱스 관리PersistenceManager: AOF, snapshot, recovery, background task 조정MongoManager: Mongo 연동 여부와 쓰기 시간 측정, adapter 호출
처음 읽을 때는 아래 순서를 추천합니다.
src/mini_redis/cli_main.pysrc/mini_redis/server_main.pysrc/mini_redis/bootstrap.pysrc/mini_redis/network/tcp_server.pysrc/mini_redis/commands/manager.pysrc/mini_redis/commands/queue.pysrc/mini_redis/engine/redis.pysrc/mini_redis/storage/manager.pysrc/mini_redis/storage/ttl.pysrc/mini_redis/invalidation/manager.pysrc/mini_redis/persistence/manager.pysrc/mini_redis/storage/mongo_manager.py
현재 코드 기준으로 눈여겨볼 기능은 아래와 같습니다.
- CLI client with local helper commands
- TCP client/server transport
- RESP codec
- FIFO command execution queue
- command-specific handlers
- in-memory hash table with incremental rehashing
- TTL / expiration
- tag-based invalidation
- AOF / snapshot persistence and recovery
- optional Mongo integration
- benchmark / inspect / probe diagnostics
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
mini-redis-server다른 터미널에서:
.venv\Scripts\Activate.ps1
mini-redis-cliMongoDB를 같이 쓰려면 서버를 시작하기 전에 아래 환경변수를 설정하면 됩니다.
$env:MINI_REDIS_MONGO_ENABLED = "1"
$env:MINI_REDIS_MONGO_URI = "mongodb://127.0.0.1:27017"
$env:MINI_REDIS_MONGO_DB = "mini_redis"
$env:MINI_REDIS_MONGO_COLLECTION = "kv_store"
$env:MINI_REDIS_MONGO_SERVER_SELECTION_TIMEOUT_MS = "2000"
mini-redis-server같은 세션에서 CLI를 열면 됩니다.
mini-redis-clipython3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
mini-redis-server다른 터미널에서:
source .venv/bin/activate
mini-redis-cliexport MINI_REDIS_MONGO_ENABLED=1
export MINI_REDIS_MONGO_URI="mongodb://127.0.0.1:27017"
export MINI_REDIS_MONGO_DB="mini_redis"
export MINI_REDIS_MONGO_COLLECTION="kv_store"
export MINI_REDIS_MONGO_SERVER_SELECTION_TIMEOUT_MS="2000"
mini-redis-server같은 셸에서 CLI를 실행하면 됩니다.
mini-redis-cliMINI_REDIS_MONGO_ENABLED: Mongo 연동 사용 여부.1,true,yes,on이면 활성화됩니다.MINI_REDIS_MONGO_URI: MongoDB 연결 URI입니다.MINI_REDIS_MONGO_DB: 사용할 데이터베이스 이름입니다.MINI_REDIS_MONGO_COLLECTION: 사용할 컬렉션 이름입니다.MINI_REDIS_MONGO_SERVER_SELECTION_TIMEOUT_MS: MongoDB 서버 선택 타임아웃(ms)입니다.
pytestdata/appendonly.aofdata/dump.rdb.jsondata/persistence.meta.json