notification

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 14 Imported by: 0

README

RGW notification queues

Import github.com/JSYoo5B/ceph-testcontainers-go/rgw/notification when a test of an application that consumes S3 bucket notifications must tell a notification still pending inside RGW apart from one that the consumer lost or failed to process. notification.Queue reads the persistent queue of one topic on an existing gateway: the topic's native identity and delivery limits, the queue statistics and, on request, a bounded sample of the pending entries. Topics, notification configurations and receivers belong to the SUT and the test, which create them with their own S3/SNS client; the package starts no container and adds no client or receiver. See API purpose and purpose tags.

Order of use

  1. Start a gateway with rgw.Run, rgw.Start or rgw.WithGateways, and hand the SUT its endpoint and a user (see rgw).
  2. Let the SUT or the test create the persistent topic (persistent=true) and the bucket notification configuration, and run the endpoint the topic pushes to.
  3. Observe with notification.Queue(ctx, gateway, topic, sample): notification.Topic{Tenant, Name} selects the topic, and notification.Sample{MaxEntries, MaxBytes} asks for the first MaxEntries pending entries in queue order; the zero Sample reads only the statistics.
  4. Correlate the snapshot with what the consumer received, by the object keys and event names the test wrote. Poll: delivery is asynchronous.
  5. Clean up: the topic stays the SUT's. Delete it with the client that created it, or terminate the cluster; this package removes nothing.
topic := notification.Topic{Name: "orders"}
pending := func(s notification.QueueSnapshot) bool {
	return s.Stats.Entries > 0 && slices.ContainsFunc(s.Pending, func(e notification.PendingEntry) bool {
		return e.Key == "orders/42" && e.EventName == "ObjectCreated:Put"
	})
}
// The consumer is down: after the SUT's write the event becomes pending in
// RGW, but not necessarily before the first read.
waitCtx, cancel := context.WithTimeout(ctx, 2*time.Minute)
defer cancel()
for {
	snapshot, err := notification.Queue(waitCtx, gateway, topic, notification.Sample{MaxEntries: 10})
	if err == nil && pending(snapshot) {
		break
	}
	select {
	case <-waitCtx.Done():
		t.Fatalf("event is not pending in RGW: %+v, last error %v", snapshot, err)
	case <-time.After(time.Second):
	}
}
// Start the consumer, wait until it reports orders/42, then poll Queue the
// same way until the entry has left the queue.

Concepts and limits

  • A snapshot is point-in-time RGW evidence, not a delivery verdict. An empty queue does not prove that the consumer received or processed anything, and a shrinking queue can mean that entries expired or ran out of retries (Metadata.TimeToLive, MaxRetries); the consumer's own record of what it received decides exactly-once or end-to-end delivery.
  • Stats.Entries counts committed entries, Stats.Reservations slots of notifications not committed yet, and Stats.SizeBytes is the native queue size. Statistics and sample are separate native reads, not one atomic view. The queue is the one of the gateway's zone.
  • Identity: the selection is a tenant and a name, and the topic's ARN must name both. Queue reads the topic before and after the queue and refuses a change of owner, ARN or queue name. Native topic metadata has no generation, so a topic deleted and recreated with the same name, owner and queue between two calls, or between the reads of one call, is not detected. Account-owned topics are not selected by a tenant; use Gateway.Admin for them.
  • Invalid selection or sample arguments match ceph.ErrInvalidRequest before any command runs. If the topic read shows that the topic has no persistent queue, the error matches both notification.ErrNotPersistent and ceph.ErrInvalidRequest via errors.Is.
  • A missing topic matches fs.ErrNotExist and a refused read matches fs.ErrPermission. A cluster before Ceph 19 matches ceph.ErrUnsupported. An unexpected native reply produces an unclassified error. Check the error before interpreting zero entries as an empty queue.
  • Bounds: at most MaxSampleEntries entries. topic dump writes the whole queue (its --max-entries only sizes its pages), so Queue keeps the first MaxBytes bytes of the reply (default DefaultSampleBytes), discards the rest as it arrives and decodes the sample from that prefix. A sample whose entries do not fit is refused, not shortened. The command still reads the whole queue; the call is bounded by its context and the cluster's startup timeout.
  • Redaction: PendingEntry keeps the event ID, name and time, the configuration ID, bucket, key, version, sequencer and entry creation time. Push endpoints and their arguments, user and request identities, source addresses, object metadata, tags and opaque data are never returned, and no error contains native output.
  • Queue only reads (topic get, topic stats, topic dump): it never changes, purges or removes a topic, its policy or its queue, and the result is plain data, so observing a SUT-created topic adopts nothing.

Reference

Documentation

Overview

Package notification observes the persistent queue of one RGW bucket notification topic through an existing gateway: the topic's native identity and delivery limits, its queue statistics and an optional bounded sample of the pending entries.

Topics, notification configurations and receivers belong to the SUT and the test, which create them through their own S3/SNS client. Queue only reads: it never creates, changes, purges or removes a topic, and observing a topic does not adopt it. It acts on a gateway that rgw.Run, rgw.Start or rgw.WithGateways started; it starts no container.

Index

Constants

View Source
const (
	// MaxSampleEntries is the largest Sample.MaxEntries.
	MaxSampleEntries = 100
	// DefaultSampleBytes is the reply prefix kept for a sample whose MaxBytes
	// is zero.
	DefaultSampleBytes = 64 << 10
	// MaxSampleBytes is the largest Sample.MaxBytes.
	MaxSampleBytes = 1 << 20
)

Sample bounds.

Variables

View Source
var ErrNotPersistent = errors.New("RGW notification topic is not persistent")

ErrNotPersistent reports a topic that exists but has no persistent queue: its notifications are pushed synchronously and nothing is pending inside RGW. It is a ceph.ErrInvalidRequest, never an empty queue.

Functions

This section is empty.

Types

type Metadata

type Metadata struct {
	Tenant, Name string
	// Owner is the native owner, such as tenant$user; empty when Ceph does
	// not report it.
	Owner string
	ARN   string
	// Queue is the native persistent queue name; empty when Ceph does not
	// report it.
	Queue string
	// TimeToLive, MaxRetries and RetrySleepDuration are the native texts,
	// such as None for the global default. A backlog can shrink because
	// entries expire or exhaust their retries, not only by delivery.
	TimeToLive, MaxRetries, RetrySleepDuration string
}

Metadata is the native identity and delivery policy of a persistent topic. The push endpoint, its arguments, the opaque data and the topic policy are left out: they can carry credentials and no queue assertion needs them.

Native topic metadata has no generation: a topic deleted and recreated with the same tenant, name, owner and queue is indistinguishable from the original. Queue compares this identity before and after its reads and refuses a change it sees, nothing more.

type PendingEntry

type PendingEntry struct {
	EventID, EventName, EventTime, ConfigurationID string
	Bucket, Key, VersionID, Sequencer              string
	CreationTime                                   string
}

PendingEntry is the identity of one pending notification: the event's native ID, name and time, the notification configuration ID, the bucket, the object key, version and sequencer, and the queue entry's creation time, all as native text. The push endpoint and its arguments, user and request identities, source address, object metadata and tags are left out.

type QueueSnapshot

type QueueSnapshot struct {
	Topic   Metadata
	Stats   Stats
	Pending []PendingEntry
	Sampled bool
}

QueueSnapshot is one bracketed observation. Sampled reports that a sample was requested and read; Pending then holds up to Sample.MaxEntries entries in native order, and is empty, not nil, for an empty queue.

func Queue

func Queue(ctx context.Context, g *rgw.Gateway, topic Topic, sample Sample) (QueueSnapshot, error)

Queue reads the persistent queue of the selected topic through gateway g: radosgw-admin topic get, topic stats, optionally topic dump bounded by sample, and topic get again, in the gateway's scope. It refuses the result when the topic's tenant, name, owner, ARN or queue name differs between the two reads or from the selection. The statistics and the sample are separate native reads, not one atomic view; the queue is the one of the gateway's zone.

The snapshot is point-in-time RGW evidence. An empty queue does not prove that the SUT received or processed a notification, and a shrinking queue can reflect expiry or exhausted retries; it is not an exactly-once or end-to-end delivery verdict. Correlate it with what the consumer received.

The outcomes stay distinct: an invalid selection or sample is ceph.ErrInvalidRequest before any command; a missing topic matches fs.ErrNotExist and a refused read fs.ErrPermission (ceph.ErrNativeFailure either way); a topic without a persistent queue is ErrNotPersistent; a cluster before Ceph 19 is ceph.ErrUnsupported; an unexpected native reply is an unclassified error. Errors never contain native output. Queue never creates, changes, purges or removes a topic, its policy or its queue, and the result is plain data, not a handle: observing a SUT-created topic does not adopt its lifetime. The call is bounded by ctx and the cluster's startup timeout; no radosgw-admin outlives it.

type Sample

type Sample struct {
	MaxEntries, MaxBytes int
}

Sample asks Queue for a bounded sample of the pending entries: the first MaxEntries entries in queue order. MaxEntries zero takes no sample; otherwise it is 1 to MaxSampleEntries. radosgw-admin topic dump writes the whole queue whatever its --max-entries, which only sizes its pages, so Queue keeps the first MaxBytes bytes of the reply and discards the rest as it arrives; zero selects DefaultSampleBytes, and MaxBytes is at most MaxSampleBytes. The command still runs to the end of the queue, within the call's context. A sample whose entries do not fit in MaxBytes is refused, never shortened.

type Stats

type Stats struct {
	Reservations, Entries, SizeBytes uint64
}

Stats are the native statistics of the persistent queue: reserved slots of notifications not committed yet, committed entries and their native size in bytes.

type Topic

type Topic struct {
	Tenant, Name string
}

Topic selects one topic by its native tenant and name. Empty Tenant selects the legacy namespace. Name is 1 to 256 letters, digits, hyphens and underscores. Topics owned by an account are not selected by a tenant; read them with rgw.Gateway.Admin.

Jump to

Keyboard shortcuts

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