platform

package module
v0.2.0-preview.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 13 Imported by: 0

README

Spine RabbitMQ Platform

이 작업 소스의 대상 버전은 v0.2.0이며 Preview, RC, 정식 채널로 발행합니다. 릴리스 운영을 확인하세요. 기존 정식 v0.1.0은 변경하지 않습니다.

RabbitMQ를 Spine의 공개 이벤트 계약 spine.event-adapter/v1에 연결하는 Go 모듈입니다. adapter/event의 Factory, Reader, Delivery와 Publisher를 구현하며 도메인 이벤트, DI나 커널 내부 패키지를 import하지 않습니다.

App에는 spine.WithEventAdapter(name, factory)로 등록합니다. 브로커 연결은 이 플랫폼이, 소비 실행과 reader 재연결은 코어가 맡습니다. 아래는 HTTP 없는 워커 구성입니다. HTTP 앱은 spine.New에 Echo 플랫폼 옵션도 함께 넘깁니다. Spine v0.6.5의 공개 이벤트 계약과 App 연결 API를 사용합니다.

import (
    "github.com/NARUBROWN/spine"
    rabbitmqplatform "github.com/NARUBROWN/spine-rabbitmq-platform"
)

func buildWorker() (spine.App, error) {
    factory, err := rabbitmqplatform.NewFactory(rabbitmqplatform.Config{URL: "amqps://rabbitmq.example.com:5671/", Exchange: "events", Consume: true, Publish: true})
    if err != nil { return nil, err }
    return spine.New(spine.WithEventAdapter("rabbitmq", factory)), nil
}

기존 consumer 생성자와 app.Consumers().Register를 등록한 뒤 app.Run(boot.Options{})로 실행합니다. 공통 정책은 spine.WithEventConsumerRetry와 spine.WithEventSettlementTimeout으로 조정합니다. Prepare는 reader를 보관하고 Run이 같은 준비 경로에서 소비를 시작합니다. App 전환 안내를 참고하세요.

사용

import (
    "context"

    eventadapter "github.com/NARUBROWN/spine/contract/event"
    rabbitmqplatform "github.com/NARUBROWN/spine-rabbitmq-platform"
)

func consumeOne(ctx context.Context) error {
    factory, err := rabbitmqplatform.NewFactory(rabbitmqplatform.Config{
        URL: "amqp://guest:guest@localhost:5672/",
        Exchange: "events",
        Consume: true,
        FailurePolicy: rabbitmqplatform.FailureReject,
        AllowInsecureTransport: true, // 격리된 로컬 개발 브로커에서만 사용합니다.
    })
    if err != nil { return err }
    reader, err := factory.NewReader(ctx, eventadapter.Subscription{Topic: "order.created"})
    if err != nil { return err }
    defer reader.Close(context.Background())
    delivery, err := reader.Read(ctx)
    if err != nil { return err }
    // delivery.Message()의 본문을 처리한 뒤 성공하면 Ack, 실패하면 Nack을 호출합니다.
    return delivery.Ack(ctx)
}

발행은 Config.Publish: true와 factory.NewPublisher(ctx)를 사용합니다. Publish(ctx, eventadapter.Message{EventName: ..., Payload: ...})에는 이미 직렬화한 본문을 넘깁니다. 본문 형식을 가정하거나 다시 직렬화하지 않습니다.

설정

필드 동작
URL AMQP 연결 문자열. 기본적으로 amqps://가 필요합니다.
Exchange durable topic exchange 이름. 필수이며 기본 exchange는 지원하지 않습니다.
Consume, Publish 읽기, 발행 역할을 각각 활성화합니다. 하나 이상 필요합니다.
QueuePrefix 논리 구독 키 앞에 붙일 큐 이름 접두사. 기본은 빈 문자열입니다.
TopicPrefix 발행 이름과 구독 binding key 앞에 같은 접두사를 붙입니다.
PrefetchCount 기본 1. 양수로 지정할 수 있지만 Reader는 한 번에 하나의 전달만 커널에 넘깁니다.
FailurePolicy 기본 FailureReject. FailureRequeue는 실패 메시지를 재큐잉합니다.
DeadLetter 선택적 dead-letter exchange와 routing key. DLX, 대상 큐, binding은 호출자가 준비합니다.
TLS TLS 설정을 복사합니다. 기본값은 TLS 1.2 이상입니다.
AllowInsecureTransport 기본 false. 로컬 평문 연결을 명시적으로 허용하며 TLS 설정과 함께 사용할 수 없습니다.
StartupTimeout 연결, exchange, queue, binding 준비 제한 시간. 기본 10초입니다.
OperationTimeout 확인, 발행과 publisher confirm 대기 제한 시간. 기본 5초입니다.

factory 생성과 Capabilities 조회는 네트워크를 사용하지 않습니다. NewReader는 연결, durable exchange, queue 선언, binding, QoS와 consumer 구독을 완료합니다. NewPublisher는 exchange 선언과 confirm 설정을 완료합니다. 생성 context는 초기화만 제한하고 성공한 자원은 Close까지 유지됩니다.

처리와 수명

  • 한 Reader에서 미확인 전달은 하나입니다. Ack는 한 건만 확인하고 Nack은 설정에 따라 reject 또는 requeue합니다. 같은 전달의 중복 확인은 native 작업을 반복하지 않습니다. 확인 오류 뒤에는 Reader를 닫고 다시 생성해야 합니다.
  • 커널은 Subscription.Topic에 연결된 핸들러를 실행해야 합니다. AMQP Type은 Message.EventName에 보존하지만 핸들러 선택에 사용하지 않습니다. 문자열 AMQP headers만 Metadata에 옮기며 그 밖의 native header 타입은 생략합니다.
  • 발행은 persistent 메시지, mandatory=true와 publisher confirm을 사용합니다. 수신 큐가 없으면 ErrUnroutable, negative confirm이나 확인 시간 초과는 오류입니다. 발행 호출은 동시에 받을 수 있으며 한 native 세션에서는 순서대로 처리합니다.
  • 전송, 확인 오류로 세션이 불확실해지면 해당 자원에서 새 작업을 막습니다. 새 Publisher를 생성한 뒤 재시도해야 합니다. 자동 재발행은 수행하지 않습니다. 오류나 취소 전에 브로커가 수신했을 수 있어 중복 방지는 애플리케이션 책임입니다.
  • native 송신 메서드는 context를 무시하므로 플랫폼이 취소, 시간 초과 시 소켓을 닫아 대기를 해제합니다. 이 경우 확인 결과가 불확실할 수 있습니다.
  • Close는 새 작업을 막고 진행 중인 전달 확인, 발행이 끝난 뒤 연결을 한 번 정리합니다. context는 완료 대기만 제한하고 후속 Close로 다시 기다릴 수 있습니다. 정상 정리의 native 연결 종료에는 최대 5초를 사용합니다.
  • reject된 메시지의 보존은 실제 DLX 토폴로지에 달려 있습니다. DLX가 없으면 버려질 수 있습니다. Requeue는 영구 실패 메시지를 반복 전달할 수 있습니다.

검증

go test -race ./... -count=1
bash scripts/check-module-boundary.sh
SPINE_TEST_RABBITMQ_URL=amqp://guest:guest@localhost:5672/ go test -race . -run '^TestLive' -count=1 -timeout=2m

브로커 환경변수가 없으면 live 테스트는 건너뜁니다. Live 테스트는 binary 본문, header 왕복, mandatory return, publisher confirm, requeue 재전달과 reject 후 dead-letter 보존을 검사합니다. CI는 단위, race 검사와 RabbitMQ 기반 live 검사를 분리해서 실행합니다. 운영 TLS, 인증, 클러스터 장애는 별도로 검증해야 합니다.

라이선스: MIT. 계약: Spine adapter/event.

v0.1.0 호환 버전

이 릴리스는 공개 계약을 포함한 Spine v0.6.5 이상을 요구합니다. 개인 경로의 replace 없이 정식 태그로 설치합니다.

go get github.com/NARUBROWN/spine-rabbitmq-platform@v0.1.0

릴리스와 공개 계약

이 플랫폼은 자체 버전과 채널로 발행합니다. go.mod의 Spine 버전은 사용하는 공개 계약의 최소 의존성이며 코어 릴리스 채널과 별도로 관리합니다. CI와 공개 설치 검증은 이 모듈의 의존성으로 플랫폼 자체를 검사합니다. 새로운 코어와 기존 플랫폼 태그의 조합 검증은 코어 릴리스에서 수행합니다.

Documentation

Overview

Package platform은 Spine 이벤트 계약의 RabbitMQ 구현입니다.

Index

Constants

This section is empty.

Variables

View Source
var ErrUnroutable = errors.New("RabbitMQ message was unroutable")

ErrUnroutable은 mandatory 발행을 수신할 큐가 없음을 나타냅니다.

Functions

func NewFactory

func NewFactory(config Config) (eventadapter.Factory, error)

NewFactory는 설정만 검사하고 복사하며 브로커에 연결하지 않습니다.

Types

type Config

type Config struct {
	URL                    string
	Exchange               string
	Consume                bool
	Publish                bool
	QueuePrefix            string
	TopicPrefix            string
	PrefetchCount          int
	FailurePolicy          FailurePolicy
	DeadLetter             *DeadLetter
	TLS                    *tls.Config
	AllowInsecureTransport bool
	StartupTimeout         time.Duration
	OperationTimeout       time.Duration
}

Config는 durable topic exchange의 송수신과 실패 정책을 설정합니다.

type DeadLetter

type DeadLetter struct {
	Exchange   string
	RoutingKey string
}

type FailurePolicy

type FailurePolicy string
const (
	FailureReject  FailurePolicy = "reject"
	FailureRequeue FailurePolicy = "requeue"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL