Documentation
¶
Index ¶
- Constants
- Variables
- func ApplyHandlerResult(ctx context.Context, delivery *Delivery, result HandlerResult) error
- func EncodeSubjectToken(value string) (string, error)
- func ExpandCredentialPath(path string) string
- type ActionReporter
- type Client
- func (c *Client) BindConsumer(ctx context.Context, cfg ConsumerConfig) (*Consumer, error)
- func (c *Client) Close() error
- func (c *Client) ConsumerState(ctx context.Context, stream, durable string) (ConsumerState, error)
- func (c *Client) DeleteConsumer(ctx context.Context, stream, durable string) error
- func (c *Client) EnsureConsumer(ctx context.Context, cfg ConsumerConfig) (*ConsumerInfo, error)
- func (c *Client) FlushWithContext(ctx context.Context) error
- func (c *Client) Fork(ctx context.Context, name string) (*Client, error)
- func (c *Client) MaxPayload() int64
- func (c *Client) NewConsumer(ctx context.Context, cfg ConsumerConfig) (*Consumer, error)
- func (c *Client) ProbePublishPermission(ctx context.Context, subject, probeID string) error
- func (c *Client) PublishRaw(ctx context.Context, subject, messageID string, payload []byte, ...) (*PublishAck, error)
- func (c *Client) Ready() bool
- func (c *Client) Reconnect(ctx context.Context) error
- func (c *Client) RequestWithContext(ctx context.Context, subject string, payload []byte) (*nats.Msg, error)
- func (c *Client) Subscribe(subject string, handler nats.MsgHandler) (*nats.Subscription, error)
- type Config
- type Consumer
- type ConsumerAPI
- type ConsumerConfig
- type ConsumerInfo
- type ConsumerState
- type CredentialFile
- type Delivery
- type DeliveryHandler
- type DeliveryHandlerFunc
- type ErrorReporter
- type ErrorReporterFunc
- type HandlerDecision
- type HandlerResult
- type PublishAck
- type Runner
- type RunnerConfig
Constants ¶
const ( ACK HandlerDecision = iota + 1 RETRY TERM HandlerDecisionACK = ACK HandlerDecisionRETRY = RETRY HandlerDecisionTERM = TERM HandlerDecisionRetry = RETRY HandlerDecisionTerm = TERM )
Variables ¶
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 ¶
EncodeSubjectToken encodes a UTF-8 identifier as one lowercase NATS subject token.
func ExpandCredentialPath ¶
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 (*Client) BindConsumer ¶
BindConsumer binds an existing consumer. It never creates, updates, or scans streams.
func (*Client) Close ¶
Close closes the client connection. Durable consumers are intentionally not deleted.
func (*Client) ConsumerState ¶
ConsumerState returns the server-side delivery backlog for one durable.
func (*Client) DeleteConsumer ¶
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) Fork ¶
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 (*Client) NewConsumer ¶
NewConsumer keeps the established ensure-then-bind behavior.
func (*Client) ProbePublishPermission ¶
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) Reconnect ¶
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 ¶
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 (Config) MaxPayloadBytes ¶
type Consumer ¶
type Consumer struct {
// contains filtered or unexported fields
}
func (*Consumer) MaxDeliver ¶
type ConsumerAPI ¶
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 ¶
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
}
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 Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
func NewRunner ¶
func NewRunner(consumer ConsumerAPI, handler DeliveryHandler, cfg RunnerConfig) *Runner
type RunnerConfig ¶
type RunnerConfig struct {
BatchSize int
InProgressInterval time.Duration
ErrorReporter ErrorReporter
ActionReporter ActionReporter
// Concurrent 让每条投递在独立 goroutine 中处理,最多 BatchSize 条在途;一条完成就立刻腾出名额继续拉取,
// 不等同批其他投递。只用于彼此独立的投递(顺序由处理器自己保证)。
Concurrent bool
}