Documentation
¶
Overview ¶
Package expect evaluates captured observations of RGW fixtures against the conditions a test states, and explains each mismatch. Its evaluations read the observation types of package rgw and of its multisite extension, package rgw/multisite.
It is optional: running and observing gateways needs only package rgw or rgw/multisite, and neither imports it. A test that wants a precise verdict on one observation, such as "two root users of one account report the same account aggregate" or "zone b's data sync from zone a is behind", states it as an expectation and evaluates the observation it already has:
usage, err := root.Usage(ctx)
if err != nil {
t.Fatal(err) // a failed query is never a mismatch
}
want := expect.UserUsage{UserID: root.ID(), Scope: expect.UsageScopeAccount, OwnerID: account.ID(), Objects: 1, SizeBytes: 47}
result, err := want.Evaluate(usage)
if err != nil {
t.Fatal(err) // an invalid expectation or a malformed observation
}
if !result.Matched {
t.Fatal(result) // names each identity or counter that differs
}
Every Evaluate is pure: it reads only its arguments, performs no query, stats synchronization, wait or retry, and returns a result that shares no slice or map with them. A mismatch is a result; an error means there is no verdict. Polling, retries and assertion failures stay with the test and its own tools. A match never proves that an object's content is intact.
Index ¶
Examples ¶
Constants ¶
const ( // UsageScopeUser: the counters aggregate the selected ordinary user, who // is its own owner. UsageScopeUser = "user" // UsageScopeAccount: the counters aggregate the account the selected user // belongs to, which owns the buckets of all its users and roles. UsageScopeAccount = "account" )
The scopes of an rgw.UserUsage observation.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type MultisiteDataSync ¶
type MultisiteDataSync struct {
Zone, Source string
State MultisiteDataSyncState
}
MultisiteDataSync states what a test expects of one directional data sync stream in one multisite.SyncStatus observation: the data that Zone, the receiving zone the observation was read in, syncs from Source. Zone and Source are zone names and are required and distinct, and State is required. Each zone's status is its own observation, so a test that expects a lag in one direction and none in the other evaluates two expectations against the two zones' observations.
A match proves only what that one status read reported. Two observations read at different times are not one atomic state of both zones, and neither a caught-up stream nor a behind one proves that a particular object arrived or is missing: compare the S3 payloads separately. Metadata sync is not compared; assert multisite.SyncStatus.Metadata on its own.
func (MultisiteDataSync) Evaluate ¶
func (e MultisiteDataSync) Evaluate(observed multisite.SyncStatus) (MultisiteDataSyncEvaluation, error)
Evaluate checks one multisite.SyncStatus observation (from Fixture.SyncStatus, Fixture.WaitSyncReady or a sync watch event) against the expectation. It reads only its arguments: no query, wait or retry, so a test composes it with its own polling or assertion helpers. A mismatch is a result; an error means no verdict. An expectation without a Zone or a Source, with Source equal to Zone, or with an unknown State is ceph.ErrInvalidRequest. An observation without its zone's name and ID, or with a data sync stream whose source is unidentified, is the observed zone itself, is listed twice, has negative shard counts or claims to be caught up against its own counts, is a malformed observation, never a mismatch.
Example ¶
While zone b cannot read from zone a, b's stream from a must be behind and a's stream from b caught up. Each direction is evaluated against the observation of its receiving zone; here a has not caught up with b either.
package main
import (
"fmt"
"github.com/JSYoo5B/ceph-testcontainers-go/rgw/expect"
"github.com/JSYoo5B/ceph-testcontainers-go/rgw/multisite"
)
func main() {
b := multisite.SyncStatus{Zone: "b", ZoneID: "zone-b", DataSources: []multisite.DataSyncStatus{
{SourceZone: "a", SourceZoneID: "zone-a", Syncing: true, Shards: 128, IncrementalShards: 128, BehindShards: 3},
}}
a := multisite.SyncStatus{Zone: "a", ZoneID: "zone-a", DataSources: []multisite.DataSyncStatus{
{SourceZone: "b", SourceZoneID: "zone-b", Syncing: true, Shards: 128, IncrementalShards: 128, BehindShards: 1},
}}
for _, check := range []struct {
want expect.MultisiteDataSync
observed multisite.SyncStatus
}{
{expect.MultisiteDataSync{Zone: "b", Source: "a", State: expect.MultisiteDataSyncBehind}, b},
{expect.MultisiteDataSync{Zone: "a", Source: "b", State: expect.MultisiteDataSyncCaughtUp}, a},
} {
result, err := check.want.Evaluate(check.observed)
if err != nil {
panic(err)
}
fmt.Println(result)
}
}
Output: data sync of zone b from a want behind (observed 128 shards: 128 incremental, 0 full, 3 behind, 0 recovering): match data sync of zone a from b want caught-up (observed 128 shards: 128 incremental, 0 full, 1 behind, 0 recovering): caught-up: want true, observed false; behind-shards: want 0, observed 1
type MultisiteDataSyncEvaluation ¶
type MultisiteDataSyncEvaluation struct {
Expectation MultisiteDataSync
Observed multisite.SyncStatus
Stream multisite.DataSyncStatus
Mismatches []MultisiteDataSyncMismatch
Matched bool
}
MultisiteDataSyncEvaluation is the result of evaluating one observation. Expectation and Observed are copies of what was evaluated, and Stream is the observed stream from the expected source, zero when the observation was read in another zone or lists none. Mismatches are in the order of the reason constants; Matched means there are none. A zone or source mismatch is the only one reported.
func (MultisiteDataSyncEvaluation) String ¶
func (e MultisiteDataSyncEvaluation) String() string
String summarizes the expectation, the evaluated stream's shard counts and at most eight mismatches.
type MultisiteDataSyncMismatch ¶
type MultisiteDataSyncMismatch struct {
Reason MultisiteDataSyncMismatchReason
Want, Observed string
}
MultisiteDataSyncMismatch is one reason an observation does not satisfy a MultisiteDataSync expectation. Want and Observed are the compared values as text; a Want of ">0" requires a positive shard count.
func (MultisiteDataSyncMismatch) String ¶
func (m MultisiteDataSyncMismatch) String() string
String names the reason and the evaluated values.
type MultisiteDataSyncMismatchReason ¶
type MultisiteDataSyncMismatchReason string
MultisiteDataSyncMismatchReason names why an observation does not satisfy a MultisiteDataSync expectation.
const ( // MultisiteDataSyncMismatchZone: the observation was read in another // zone, as when the direction is swapped. No other field is compared. MultisiteDataSyncMismatchZone MultisiteDataSyncMismatchReason = "zone" // MultisiteDataSyncMismatchSource: the observation lists no data sync // stream from Source. No other field is compared. MultisiteDataSyncMismatchSource MultisiteDataSyncMismatchReason = "source" // MultisiteDataSyncMismatchCaughtUp: the stream's caught-up verdict // differs from the expected state's. MultisiteDataSyncMismatchCaughtUp MultisiteDataSyncMismatchReason = "caught-up" // MultisiteDataSyncMismatchSyncing: a caught-up expectation found the // stream not syncing. MultisiteDataSyncMismatchSyncing MultisiteDataSyncMismatchReason = "syncing" // MultisiteDataSyncMismatchFull: a caught-up expectation found shards // still in full sync. MultisiteDataSyncMismatchFull MultisiteDataSyncMismatchReason = "full-shards" // MultisiteDataSyncMismatchBehind: a caught-up expectation found shards // behind, or a behind expectation found none. MultisiteDataSyncMismatchBehind MultisiteDataSyncMismatchReason = "behind-shards" // MultisiteDataSyncMismatchRecovering: a caught-up expectation found // shards recovering. MultisiteDataSyncMismatchRecovering MultisiteDataSyncMismatchReason = "recovering-shards" )
The reasons a MultisiteDataSyncEvaluation reports.
type MultisiteDataSyncState ¶
type MultisiteDataSyncState string
MultisiteDataSyncState is the condition a MultisiteDataSync expectation states for one data sync stream.
const ( // MultisiteDataSyncCaughtUp: the stream reports caught up with its // source (multisite.DataSyncStatus.CaughtUp): syncing, every shard // incremental, none behind and none recovering. MultisiteDataSyncCaughtUp MultisiteDataSyncState = "caught-up" // MultisiteDataSyncBehind: the stream is not caught up and the native // comparison with the source's log finds a positive number of shards // behind. A stream that is only not caught up, such as one in full sync // or one without a shard count, is not behind. MultisiteDataSyncBehind MultisiteDataSyncState = "behind" )
The conditions of a data sync stream.
type UserUsage ¶
UserUsage states what a test expects of one rgw.UserUsage observation, read by rgw.User.Usage after the test's own stats synchronization.
UserID is the selected user and is required. Tenant, when set, is the user's tenant. Scope is UsageScopeUser or UsageScopeAccount. OwnerID is the effective owner the counters aggregate: for UsageScopeUser it is the user itself and may be left empty; for UsageScopeAccount it is the account ID, which is required and differs from UserID. Distinct users of one account therefore state the same OwnerID with their own UserID.
Objects and SizeBytes are always compared, so zero objects and zero bytes are expectations of their own. SizeBytes is the native logical size, the sum of object sizes; the rounded accounting size (SizeActualBytes) is not compared.
A match proves only what that one native stats read reported. Native accounting is asynchronous: synchronize the stats or poll before evaluating, and verify quota enforcement and object content separately.
func (UserUsage) Evaluate ¶
func (e UserUsage) Evaluate(observed rgw.UserUsage) (UserUsageEvaluation, error)
Evaluate checks one rgw.UserUsage observation against the expectation. It reads only its arguments: no query, stats synchronization, wait or retry, so a test composes it with its own polling or assertion helpers. A mismatch is a result; an error means no verdict. An expectation without a UserID, with an unknown Scope, with an OwnerID other than UserID in the user scope, or without an OwnerID distinct from UserID in the account scope is ceph.ErrInvalidRequest. An observation without a user or owner, with an unknown scope, or whose owner contradicts its scope is a malformed observation, never a mismatch.
Example ¶
A second root user of an account must report the account's aggregate, not its own: the evaluation names the scope and owner even though the counters match.
package main
import (
"fmt"
"github.com/JSYoo5B/ceph-testcontainers-go/rgw"
"github.com/JSYoo5B/ceph-testcontainers-go/rgw/expect"
)
func main() {
observed := rgw.UserUsage{
UserID: "account_tenant$tc-account-root-1", Tenant: "account_tenant", Scope: "user", OwnerID: "account_tenant$tc-account-root-1",
NumObjects: 1, SizeBytes: 47, SizeActualBytes: 4096,
}
want := expect.UserUsage{
UserID: "account_tenant$tc-account-root-1", Scope: expect.UsageScopeAccount, OwnerID: "RGW11111111111111111",
Objects: 1, SizeBytes: 47,
}
result, err := want.Evaluate(observed)
if err != nil {
panic(err) // invalid expectation or malformed observation: no verdict
}
fmt.Println(result.Matched)
fmt.Println(result)
}
Output: false usage of user account_tenant$tc-account-root-1 want scope=account owner=RGW11111111111111111 objects=1 size=47: scope: want account, observed user; owner: want RGW11111111111111111, observed account_tenant$tc-account-root-1
type UserUsageEvaluation ¶
type UserUsageEvaluation struct {
Expectation UserUsage
Observed rgw.UserUsage
Mismatches []UserUsageMismatch
Matched bool
}
UserUsageEvaluation is the result of evaluating one observation. Expectation and Observed are copies of what was evaluated; Expectation carries the resolved OwnerID. Mismatches are in the order of the reason constants, and every field is compared, so a wrong owner or scope is reported even when the counters match. Matched means there are none.
func (UserUsageEvaluation) String ¶
func (e UserUsageEvaluation) String() string
String summarizes the expectation and at most eight mismatches.
type UserUsageMismatch ¶
type UserUsageMismatch struct {
Reason UserUsageMismatchReason
Want, Observed string
}
UserUsageMismatch is one reason an observation does not satisfy a UserUsage expectation. Want and Observed are the compared values as text.
func (UserUsageMismatch) String ¶
func (m UserUsageMismatch) String() string
String names the reason and the evaluated values.
type UserUsageMismatchReason ¶
type UserUsageMismatchReason string
UserUsageMismatchReason names why an observation does not satisfy a UserUsage expectation.
const ( // UserUsageMismatchUser: the observation is of another user. UserUsageMismatchUser UserUsageMismatchReason = "user" // UserUsageMismatchTenant: the user's tenant differs. UserUsageMismatchTenant UserUsageMismatchReason = "tenant" // UserUsageMismatchScope: the counters aggregate the user where an // account is expected, or the reverse. UserUsageMismatchScope UserUsageMismatchReason = "scope" // UserUsageMismatchOwner: the counters aggregate another owner. UserUsageMismatchOwner UserUsageMismatchReason = "owner" // UserUsageMismatchObjects: the object count differs. UserUsageMismatchObjects UserUsageMismatchReason = "objects" // UserUsageMismatchSize: the logical size in bytes differs. UserUsageMismatchSize UserUsageMismatchReason = "size" )
The reasons a UserUsageEvaluation reports.