TL;DR

  • Zizq는 임베디드 LSM 데이터베이스를 기반으로 Redis나 RDBMS 없이 실행되는 단일 네이티브 바이너리 작업 큐 서버임.
  • HTTP/1.1·HTTP/2 API와 JSON·MessagePack을 제공하며, Node.js·Ruby·Elixir·Rust 클라이언트로 서로 다른 언어 간 작업 등록과 실행을 지원함.
  • 명명된 큐, FIFO와 우선순위, 예약·크론 작업, 재시도·보존 정책, 중복 제거, 동시성 제어, 속도 제한 및 배치 작업을 지원함.
  • MacBook Pro M4에서 초당 10만 건 초과 처리량을 제공하며, 큐 관리 API와 실시간 모니터링용 zizq top을 포함함.
  • 서버 데이터 루트와 호스트·포트는 기본값 또는 명령행 플래그와 환경 변수로 설정하며, 기본 서버 포트는 7890, 관리 포트는 8901임.

Zizq 소개

  • Zizq(/zɪsk/)는 임베디드 LSM 데이터베이스를 기반으로 하는 빠르고 내구성 있는 작업 큐로, 단일 네이티브 바이너리에 담겨 있음. Redis나 RDBMS를 기반으로 하지 않음.
  • 서버는 HTTP/2 및 HTTP/1.1 API로 실행되며, 현재 Node.js·Ruby·Elixir·Rust 클라이언트가 구현되어 있고 다른 언어 클라이언트도 계획 중임.

기능

  • 별도 데이터 저장소가 필요 없는 독립형 실행 파일
  • 내구성과 원자성을 갖춘 작업 큐
  • JSON 또는 MessagePack을 지원하는 HTTP/1.1·HTTP/2 API
  • 언어 간 작업 등록과 실행
  • 제한 없는 명명 큐
  • FIFO 순서 및 세분화된 우선순위 작업
  • 예약 작업
  • 설정 가능한 백오프·재시도 정책
  • 설정 가능한 작업 보존 정책
  • 고유 작업 지원(중복 등록 제거)
  • 작업 동시성 제어(동시에 실행되는 작업 수 최대 N개)
  • 작업 속도 제한(시간에 따라 디스패치되는 작업 수 최대 N개)
  • 크론(반복 작업) 예약
  • 배치 작업 지원(등록 작업 접기·병합)
  • jq 표현식 필터를 포함한 큐 내용 관리 API
  • MacBook Pro M4에서 초당 10만 건 초과의 높은 작업 처리량
  • 큐 상태를 확인하는 zizq top 명령

리소스

  • 전체 문서
  • 시작 안내 문서
  • Zizq 명령어 레퍼런스
  • 공식 클라이언트 라이브러리

시작하기

서버 시작

  • Zizq는 하위 명령으로 구성된 단일 바이너리이며, serve 하위 명령이 서버를 시작함. 다른 하위 명령을 지정하지 않아도 기본적으로 서버가 시작됨.
  • 서버는 시작 시 모든 큐 데이터를 저장할 루트 디렉터리를 생성함. 기본값은 {PWD}/zizq-root/이며, --root-dir 플래그 또는 $ZIZQ_ROOT 환경 변수로 지정할 수 있음.
  • 기본 서버 주소는 127.0.0.1:7890이며, --host·--port 또는 $ZIZQ_HOST·$ZIZQ_PORT로 변경할 수 있음. 관리 주소는 127.0.0.1:8901임.
  • zizq serve --help에서 전체 옵션을 확인할 수 있으며, 서버가 공용 IP 주소에서 수신하도록 설정되지 않았다면 기본값도 프로덕션 사용에 적합함.

서버와 통신하기

  • 클라이언트 라이브러리를 일반적으로 사용하지만, Zizq API에 HTTP로 직접 요청을 보낼 수도 있음. 예시는 HTTPie를 사용해 example 큐에 hello_world 작업을 등록하며, 응답은 HTTP 201과 작업 ID·우선순위·상태 등의 정보를 반환함.
  • 작업을 가져오는 스트리밍 요청은 서버가 보내는 JSON 행을 읽으며, 빈 행은 하트비트이므로 건너뜀. 예시 스크립트는 jq로 작업 ID와 유형을 추출하고 작업 내용을 출력한 뒤 성공 처리 API를 호출함.
  • 해당 처리 루프는 중단 신호를 받을 때까지 종료되지 않음. 작업을 가져온 뒤에는 상태가 in_flight로 표시되고, 성공 확인 후 처리가 완료됨.

클라이언트 라이브러리

  • 공식 클라이언트 라이브러리는 MIT 라이선스이며, 일반적으로 사용되는 여러 언어를 대상으로 함. 현재 Node.js·Ruby·Elixir·Rust 클라이언트가 제공됨.
  • 각 클라이언트는 연결 풀링, 직렬화, 동시성 처리를 담당하며, 설정 가능한 동시성 수준으로 작업을 실행하는 워커를 제공함.
  • 한 언어에서 작업을 등록하고 다른 언어의 워커에서 처리할 수 있음.
  • Node.js 예시는 @zizq-labs/zizq의 Client를 생성해 send_email 유형의 작업을 emails 큐에 등록함.
  • Ruby 예시는 Zizq::Job을 포함하는 SendEmailJob을 정의하고, emails 큐에서 메일 전송을 수행하도록 한 뒤 작업을 등록함.
  • Elixir 예시는 Zizq.JobKind를 사용해 send_email 유형과 emails 큐를 정의하고, 작업 수행 시 메일러를 호출함.
  • Rust 예시는 JobKind 파생 매크로로 send_email 작업 유형과 emails 큐를 지정하고 작업을 등록함.
  • 현재 지원되지 않는 언어용 클라이언트는 기능 요청을 남기거나 직접 구현할 수 있음.

실시간 큐 활동 보기

  • Zizq에는 큐의 현재 처리 상황, 대기열 규모, 우선순위별 큐 깊이를 실시간으로 확인하는 터미널 기반 뷰어가 포함됨. 이 기능은 top 하위 명령으로 제공됨.
  • zizq top은 기본적으로 127.0.0.1:8901에 연결하며, 다른 호스트에는 --url을 지정해 연결함.
  • 목록을 위아래로 이동해 대기열을 확인할 수 있으며, 목록에서 현재 위치와 전체 큐 깊이가 실시간으로 표시됨. 실행 중인 작업, 준비된 작업, 나중에 실행되도록 예약된 작업을 확인할 수 있음.

지원 및 피드백

  • Zizq 사용에 도움이 필요하거나 피드백이 있는 경우 Zizq 저장소에 이슈를 만들 수 있음.