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 ¶
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 ¶
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 ¶
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.