pubsub

package
v0.0.0-...-9aaa355 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source
const (
	SubscriptionStageEncoding = "encoding"
	SubscriptionStageDecode   = "decode"
	SubscriptionStageHandler  = "handler"

	SubscriptionOutcomeAck  = "ack"
	SubscriptionOutcomeNack = "nack"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AvroMessage

type AvroMessage struct {
	Data            map[string]interface{}
	Attributes      map[string]string
	ID              string
	PublishTime     time.Time
	DeliveryAttempt int
}

AvroMessage preserves the Pub/Sub envelope alongside the Avro payload. New consumers should use SubscribeWithAvroSchemaMessage when routing depends on subscription attributes (for example origin, region or schema version).

Data and Attributes belong to the callback and must not be retained or mutated after it returns.

type Client

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

func NewClient

func NewClient(ctx context.Context, di ClientDI) (*Client, error)

func (*Client) PublishAvroMessage

func (client *Client) PublishAvroMessage(ctx context.Context, topicName, schema string, data interface{}, opts ...PublishOption) (string, error)

PublishAvroMessage publishes an Avro-encoded message to a Pub/Sub topic. Options can be used to add attributes for subscription filtering (e.g., WithAttributes).

func (*Client) ServiceName

func (client *Client) ServiceName() string

func (*Client) Shutdown

func (client *Client) Shutdown(ctx context.Context) error

func (*Client) SubscribeWithAvroSchema

func (client *Client) SubscribeWithAvroSchema(
	ctx context.Context,
	subID string,
	schema string,
	handler func(context.Context, map[string]interface{}) error,
	opts ...SubscribeOption,
) error

func (*Client) SubscribeWithAvroSchemaMessage

func (client *Client) SubscribeWithAvroSchemaMessage(
	ctx context.Context,
	subID string,
	schema string,
	handler func(context.Context, AvroMessage) error,
	opts ...SubscribeOption,
) error

SubscribeWithAvroSchemaMessage receives Avro messages until ctx is cancelled or Pub/Sub returns a non-retryable receive error. Receive blocks while callbacks are active and returns only after they have drained, so its return value is suitable for service supervisors and graceful shutdown.

type ClientDI

type ClientDI struct {
	Telemetry *telemetry.Runtime
	ProjectID string
	Emulator  string
}

type Consumer

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

Consumer is a lifecycle pre-shutdown service: drain it before closing Client.

func StartConsumer

func StartConsumer(ctx context.Context, client *Client, subscription, schema string, handler func(context.Context, map[string]interface{}) error, opts ...SubscribeOption) (*Consumer, error)

StartConsumer starts a subscription with a separately cancellable context for admitted handlers. Cancellation of ctx stops intake. Always call Shutdown with a deadline to bound draining, including when ctx was already canceled.

func (*Consumer) Done

func (c *Consumer) Done() <-chan struct{}

func (*Consumer) Err

func (c *Consumer) Err() error

Err is available after Done closes; the channel synchronizes the receive result.

func (*Consumer) ServiceName

func (c *Consumer) ServiceName() string

func (*Consumer) Shutdown

func (c *Consumer) Shutdown(ctx context.Context) error

type ErrorMetadataFunc

type ErrorMetadataFunc func(message map[string]interface{}) reporter.Metadata

type PublishOption

type PublishOption func(*publishOptions)

PublishOption represents an option for publishing messages with attributes.

func WithAttributes

func WithAttributes(attrs map[string]string) PublishOption

WithAttributes adds attributes to the message for subscription filtering. Multiple calls to WithAttributes will merge the attributes.

type SubscribeOption

type SubscribeOption func(*subscribeOptions)

func WithErrorMetadata

func WithErrorMetadata(fn ErrorMetadataFunc) SubscribeOption

func WithErrorReporter

func WithErrorReporter(errorReporter reporter.Reporter) SubscribeOption

func WithMaxOutstandingBytes

func WithMaxOutstandingBytes(limit int) SubscribeOption

WithMaxOutstandingBytes bounds the aggregate bytes held by outstanding messages. Zero preserves the Pub/Sub client default; negative values are rejected by SubscribeWithAvroSchemaMessage.

func WithMaxOutstandingMessages

func WithMaxOutstandingMessages(limit int) SubscribeOption

WithMaxOutstandingMessages bounds the number of callbacks Pub/Sub may run concurrently for this subscription. The default is one, preserving the historical serial handler contract. Values lower than one are rejected by SubscribeWithAvroSchemaMessage. When limit is greater than one, the handler, observer and reporter supplied by the caller must be concurrency-safe.

func WithSubscriptionMessageObserver

func WithSubscriptionMessageObserver(observer SubscriptionMessageObserver) SubscribeOption

type SubscriptionMessageObservation

type SubscriptionMessageObservation struct {
	Subscription    string
	Encoding        string
	Stage           string
	Outcome         string
	Duration        time.Duration
	DeliveryAttempt int
}

SubscriptionMessageObservation is emitted exactly once for every delivered message, after the ACK/NACK decision has been made. Stage identifies where a NACK originated; ACK observations always use the handler stage.

type SubscriptionMessageObserver

type SubscriptionMessageObserver interface {
	ObserveSubscriptionMessage(context.Context, SubscriptionMessageObservation)
}

Jump to

Keyboard shortcuts

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