메시지 큐

분산 큐에서 메시지를 발행하고 소비합니다. RabbitMQ 및 기타 AMQP 호환 브로커를 포함한 여러 백엔드를 지원합니다.

큐 설정은 큐를 참조하세요.

로딩

local queue = require("queue")

메시지 발행

ID로 큐에 메시지 보내기:

local ok, err = queue.publish("app:tasks", {
    action = "send_email",
    user_id = 456,
    template = "welcome"
})
if err then
    return nil, err
end
파라미터 타입 설명
queue_id string 큐 식별자 (형식: "namespace:name")
data any 메시지 데이터 (테이블, 문자열, 숫자, 불리언)
headers table 선택적 메시지 헤더

반환: boolean, error

메시지 헤더

헤더는 라우팅, 우선순위, 추적을 가능하게 합니다:

queue.publish("app:notifications", {
    type = "order_shipped",
    order_id = order.id
}, {
    priority = "high",
    correlation_id = request_id
})

전달 컨텍스트 접근

큐 컨슈머 내에서 현재 메시지에 접근:

local msg, err = queue.message()
if err then
    return nil, err
end

local msg_id = msg:id()
local priority = msg:header("priority")
local all_headers = msg:headers()

반환: Message, error

컨슈머 컨텍스트에서 큐 메시지를 처리할 때만 사용 가능합니다.

메시지 메서드

메서드 반환 설명
id() string, error 고유 메시지 식별자
header(key) string, error 단일 헤더 값을 문자열로 반환 (없으면 nil)
headers() table, error 모든 메시지 헤더
ack() boolean, error 처리 확인 (single-shot)
nack() boolean, error 재전송 또는 dead-letter를 위한 실패 신호 (single-shot)

런타임은 핸들러 성공 시 자동으로 ack하고 핸들러 오류 시 자동으로 nack합니다. 조기에 확정할 때만 ack/nack를 호출하세요.

큐 정보

local stats, err = queue.info("app:tasks")
-- stats에 포함될 수 있는 필드: message_count, consumer_count, ready (드라이버 의존)

반환: table, error

컨슈머 패턴

queue.consumer 엔트리는 큐를 핸들러 함수(func로 참조)에 바인딩합니다. 핸들러는 메시지 페이로드를 직접 받습니다:

entries:
  - kind: queue.consumer
    name: email_worker
    queue: app:emails
    func: app:email_handler

-- app:email_handler
function handle_email(payload)
    local msg = queue.message()

    logger:info("Processing", {
        message_id = msg:id(),
        to = payload.to
    })

    local ok, err = email.send(payload.to, payload.template, payload.data)
    if err then
        return nil, err  -- 메시지가 재큐잉되거나 데드레터링됨
    end
end

권한

큐 작업은 보안 정책 평가 대상입니다.

액션 리소스 설명
queue.publish - 메시지 발행 일반 권한
queue.publish.queue 큐 ID 특정 큐에 발행

두 권한 모두 확인됩니다: 먼저 일반 권한, 그 다음 큐별 권한.

에러

조건 종류 재시도 가능
큐 ID 비어있음 errors.INVALID 아니오
메시지 데이터 비어있음 errors.INVALID 아니오
전달 컨텍스트 없음 errors.INVALID 아니오
발행 허용되지 않음 errors.INVALID 아니오
발행 실패 errors.INTERNAL 아니오

에러 처리는 에러 처리를 참조하세요.

참고