jetstream

package module
v0.0.0-...-cbee766 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 21 Imported by: 4

Documentation

Index

Constants

View Source
const (
	ACK HandlerDecision = iota + 1
	RETRY
	TERM

	HandlerDecisionACK   = ACK
	HandlerDecisionRETRY = RETRY
	HandlerDecisionTERM  = TERM
	HandlerDecisionRetry = RETRY
	HandlerDecisionTerm  = TERM
)

Variables

View Source
var (
	// ErrInvalidMessage means a message does not satisfy the MooX wire contract.
	ErrInvalidMessage = errors.New("invalid moox message")
	// ErrConnection means the client is not connected to NATS or a NATS operation failed.
	ErrConnection = errors.New("jetstream connection error")
	// ErrPublishTimeout means JetStream did not return a publication acknowledgement in time.
	ErrPublishTimeout = errors.New("jetstream publish timeout")
	// ErrDecode means a received NATS message is not a valid MooX message.
	ErrDecode = errors.New("decode moox message")
	// ErrInvalidConsumer means a pull consumer configuration is invalid.
	ErrInvalidConsumer        = errors.New("invalid pull consumer")
	ErrConsumerNotFound       = errors.New("pull consumer not found")
	ErrConsumerConfigConflict = errors.New("jetstream consumer config conflict")
	// ErrInvalidDelivery means a delivery is nil or no longer usable.
	ErrInvalidDelivery = errors.New("invalid delivery")
	// ErrClosed means the client or consumer has already been closed.
	ErrClosed = errors.New("jetstream client is closed")
)

Functions

func ApplyHandlerResult

func ApplyHandlerResult(ctx context.Context, delivery *Delivery, result HandlerResult) error

ApplyHandlerResult performs the transport action selected by a handler. Keeping this separate lets direct callers use the same ACK/NAK/TERM contract as Runner without duplicating the action switch.

func EncodeSubjectToken

func EncodeSubjectToken(value string) (string, error)

EncodeSubjectToken encodes a UTF-8 identifier as one lowercase NATS subject token.

func ExpandCredentialPath

func ExpandCredentialPath(path string) string

ExpandCredentialPath resolves environment variables and a leading ~/ so role credential files can be configured consistently across deployments.

Types

type ActionReporter

type ActionReporter interface {
	ReportAction(context.Context, *Delivery, HandlerResult, error)
}

ActionReporter observes the actual ACK/NAK/TERM attempt for a delivery. Reporting is best-effort and cannot change transport behavior. Reports may be concurrent when RunnerConfig.Concurrent is enabled.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client owns a NATS connection and its JetStream context.

func Connect

func Connect(ctx context.Context, cfg Config) (*Client, error)

Connect establishes a NATS connection and creates a JetStream context.

func (*Client) BindConsumer

func (c *Client) BindConsumer(ctx context.Context, cfg ConsumerConfig) (*Consumer, error)

BindConsumer binds an existing consumer. It never creates, updates, or scans streams.

func (*Client) Close

func (c *Client) Close() error

Close closes the client connection. Durable consumers are intentionally not deleted.

func (*Client) ConsumerState

func (c *Client) ConsumerState(ctx context.Context, stream, durable string) (ConsumerState, error)

ConsumerState returns the server-side delivery backlog for one durable.

func (*Client) DeleteConsumer

func (c *Client) DeleteConsumer(ctx context.Context, stream, durable string) error

func (*Client) EnsureConsumer

func (c *Client) EnsureConsumer(ctx context.Context, cfg ConsumerConfig) (*ConsumerInfo, error)

EnsureConsumer creates or reconciles a consumer without creating a subscription.

func (*Client) FlushWithContext

func (c *Client) FlushWithContext(ctx context.Context) error

func (*Client) Fork

func (c *Client) Fork(ctx context.Context, name string) (*Client, error)

Fork opens an independent NATS/JetStream connection using the same credentials and endpoint configuration. Long-lived consumers that must be failure-isolated should use a fork instead of sharing a connection whose reconnect can invalidate unrelated subscriptions.

func (*Client) MaxPayload

func (c *Client) MaxPayload() int64

func (*Client) NewConsumer

func (c *Client) NewConsumer(ctx context.Context, cfg ConsumerConfig) (*Consumer, error)

NewConsumer keeps the established ensure-then-bind behavior.

func (*Client) ProbePublishPermission

func (c *Client) ProbePublishPermission(ctx context.Context, subject, probeID string) error

ProbePublishPermission is reserved for deployment tooling that verifies a credential cannot publish to an exact NATS API subject.

func (*Client) PublishRaw

func (c *Client) PublishRaw(ctx context.Context, subject, messageID string, payload []byte, contentType string) (*PublishAck, error)

PublishRaw publishes a caller-owned protobuf envelope without making the transport package depend on a business event schema. packages/events uses this boundary for EventMessage; business modules must not call it directly.

func (*Client) Ready

func (c *Client) Ready() bool

func (*Client) Reconnect

func (c *Client) Reconnect(ctx context.Context) error

Reconnect replaces the underlying NATS connection with a fresh connection. It is intended for JetStream subscriptions that remain invalid after the server has restarted. The durable consumer is preserved on the server and callers can bind a new subscription after this method returns.

func (*Client) RequestWithContext

func (c *Client) RequestWithContext(ctx context.Context, subject string, payload []byte) (*nats.Msg, error)

RequestWithContext uses the existing authenticated connection for a non-persistent request. Callers must reconcile or retry lost responses.

func (*Client) Subscribe

func (c *Client) Subscribe(subject string, handler nats.MsgHandler) (*nats.Subscription, error)

Subscribe registers a Core NATS service on this connection. The subscription survives automatic NATS reconnects, but not an explicit Client.Reconnect; services should use a dedicated Client and own their subscription lifecycle.

type Config

type Config struct {
	URLs           []string
	Name           string
	Username       string
	Password       string
	Credentials    string
	TLSCAFile      string
	TLSCAPEMBase64 string
	TLSCertFile    string
	TLSKeyFile     string
	ConnectTimeout time.Duration
	ReconnectWait  time.Duration
	// ReconnectBufferBytes controls messages held by nats.go while reconnecting.
	// Zero disables the buffer, which is required for best-effort Host Agent publishing.
	ReconnectBufferBytes int
	// MaxReconnects defaults to -1 (unlimited) when zero, so a central broker restart is recoverable.
	MaxReconnects int
	MaxPayload    int
	// AsyncErrorHandler receives connection-level errors such as permission denials.
	AsyncErrorHandler func(error)
}

Config controls the connection to a central NATS JetStream service.

func ConfigFromEnv

func ConfigFromEnv(urls []string, name string) Config

ConfigFromEnv applies the deployment-wide EventBus connection contract to a module-owned URL/name pair. YAML still supplies the endpoint by default; credentials and TLS material stay out of checked-in module configs.

func (*Config) ApplyCredentialFile

func (c *Config) ApplyCredentialFile(path string) error

func (Config) MaxPayloadBytes

func (cfg Config) MaxPayloadBytes() int

type Consumer

type Consumer struct {
	// contains filtered or unexported fields
}

func (*Consumer) Close

func (p *Consumer) Close() error

func (*Consumer) Fetch

func (p *Consumer) Fetch(ctx context.Context, batch int) ([]*Delivery, error)

func (*Consumer) MaxDeliver

func (p *Consumer) MaxDeliver() int

type ConsumerAPI

type ConsumerAPI interface {
	Fetch(context.Context, int) ([]*Delivery, error)
	Close() error
}

ConsumerAPI 是 Runner 所需的最小消费接口。

type ConsumerConfig

type ConsumerConfig struct {
	Stream        string
	Durable       string
	FilterSubject string
	// FilterSubjects is mutually exclusive with FilterSubject.
	FilterSubjects []string
	AckWait        time.Duration
	MaxDeliver     int
	MaxAckPending  int
	FetchMaxWait   time.Duration
	DeliverPolicy  nats.DeliverPolicy
	// DeliverDecodeErrors 控制是否把解码失败的消息交给业务层分类处理。
	DeliverDecodeErrors bool
}

type ConsumerInfo

type ConsumerInfo struct {
	MaxDeliver int
}

type ConsumerState

type ConsumerState struct {
	NumPending    uint64
	NumAckPending int
}

ConsumerState is a point-in-time server view of one durable's backlog.

type CredentialFile

type CredentialFile struct {
	URLs                 []string `yaml:"urls"`
	Version              int      `yaml:"version"`
	Username             string   `yaml:"username"`
	Password             string   `yaml:"password"`
	Token                string   `yaml:"token"`
	EventBusToken        string   `yaml:"eventbus_token"`
	MonitorEventBusToken string   `yaml:"monitor_eventbus_token"`
	CAFile               string   `yaml:"ca_file"`
}

func LoadCredentialFile

func LoadCredentialFile(path string) (CredentialFile, error)

type Delivery

type Delivery struct {
	Subject       string
	Stream        string
	Consumer      string
	StreamSeq     uint64
	ConsumerSeq   uint64
	DeliveryCount uint64
	// StoredAt 是消息写入流的时间(服务端时间戳),用来度量从发布到被消费者拿到之间的排队。
	StoredAt time.Time
	// DecodeError and RawData are populated when a consumer opts into transport
	// validation errors. Business EventMessage decoding happens in packages/events.
	DecodeError  error
	RawData      []byte
	RawMessageID string
	ContentType  string
	// contains filtered or unexported fields
}

func (*Delivery) Ack

func (d *Delivery) Ack(ctx context.Context) error

func (*Delivery) InProgress

func (d *Delivery) InProgress(ctx context.Context) error

func (*Delivery) Nak

func (d *Delivery) Nak(ctx context.Context, delay time.Duration) error

func (*Delivery) Term

func (d *Delivery) Term(ctx context.Context) error

type DeliveryHandler

type DeliveryHandler interface {
	Handle(context.Context, *Delivery) HandlerResult
}

DeliveryHandler decides what should happen to one delivery. It must not call Ack, Nak, InProgress, or Term itself.

type DeliveryHandlerFunc

type DeliveryHandlerFunc func(context.Context, *Delivery) HandlerResult

func (DeliveryHandlerFunc) Handle

func (f DeliveryHandlerFunc) Handle(ctx context.Context, delivery *Delivery) HandlerResult

type ErrorReporter

type ErrorReporter interface {
	Report(error)
}

ErrorReporter observes fetch and in-progress transport failures. Handler business errors belong to the handler, while delivery actions are observed through ActionReporter.

type ErrorReporterFunc

type ErrorReporterFunc func(error)

func (ErrorReporterFunc) Report

func (f ErrorReporterFunc) Report(err error)

type HandlerDecision

type HandlerDecision uint8

HandlerDecision is the transport outcome selected by a delivery handler.

type HandlerResult

type HandlerResult struct {
	Decision HandlerDecision
	Delay    time.Duration
	Err      error
}

HandlerResult keeps domain processing separate from JetStream actions.

type PublishAck

type PublishAck struct {
	Stream    string
	Sequence  uint64
	Duplicate bool
}

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

func NewRunner

func NewRunner(consumer ConsumerAPI, handler DeliveryHandler, cfg RunnerConfig) *Runner

func (*Runner) Run

func (r *Runner) Run(ctx context.Context) error

type RunnerConfig

type RunnerConfig struct {
	BatchSize          int
	InProgressInterval time.Duration
	ErrorReporter      ErrorReporter
	ActionReporter     ActionReporter
	// Concurrent 让每条投递在独立 goroutine 中处理,最多 BatchSize 条在途;一条完成就立刻腾出名额继续拉取,
	// 不等同批其他投递。只用于彼此独立的投递(顺序由处理器自己保证)。
	Concurrent bool
}

Directories

Path Synopsis
Package testkit provides embedded JetStream infrastructure for tests.
Package testkit provides embedded JetStream infrastructure for tests.

Jump to

Keyboard shortcuts

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