Documentation
¶
Overview ¶
Package expect evaluates captured observations of RBD fixtures against the conditions a test states, and explains each mismatch. Its evaluations read the image client observations of package rbd and the rbd-mirror link observations of package rbd/mirror.
It is optional: observing an image or running, observing and watching a link needs only package rbd or mirror, and neither imports it. A test that wants a precise verdict on one observation, such as "the new owner holds the exclusive lock and the former owner no longer watches", "the survivor leads while the stopped member stays in the cohort" or "the same image pair replays through a new receiving instance", states it as an expectation and evaluates the observation it already has:
status, err := link.ImageStatus(ctx, "volume")
if err != nil {
t.Fatal(err) // a failed query is never a mismatch
}
result, err := expect.MirrorImage{Select: baseline, Replaying: true, NewInstance: true}.Evaluate(status)
if err != nil {
t.Fatal(err) // an invalid expectation or a malformed observation
}
if !result.Matched {
t.Fatal(result) // names each identity or replay field that differs
}
Every Evaluate is pure: it reads only its arguments, performs no query, 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 a write or a checkpoint arrived.
Index ¶
- type ExclusiveLock
- type ImageClients
- type ImageClientsEvaluation
- type ImageClientsMismatch
- type ImageClientsMismatchReason
- type MirrorImage
- type MirrorImageEvaluation
- type MirrorImageMismatch
- type MirrorImageMismatchReason
- type ReceiverDaemon
- type ReceiverMismatch
- type ReceiverMismatchReason
- type Receivers
- type ReceiversEvaluation
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ExclusiveLock ¶
type ExclusiveLock string
ExclusiveLock names the state of an image's managed exclusive lock that an ImageClients expectation requires.
const ( // ExclusiveLockHeld requires a managed exclusive lock. ExclusiveLockHeld ExclusiveLock = "held" // ExclusiveLockFree requires no managed exclusive lock. Advisory locks // added through rbd lock add are not read. ExclusiveLockFree ExclusiveLock = "free" )
The lock states an ImageClients expectation can require. The zero value does not compare the lock.
type ImageClients ¶
type ImageClients struct {
Lock ExclusiveLock
Owner string
OwnerWatches bool
Departed []string
Unwatched bool
}
ImageClients states what a test expects of one rbd.ImageClientStatus observation of an image.
Lock, when set, requires the managed exclusive lock to be held or free. Owner, when set, names the entity (client.4235) that must hold it, and OwnerWatches requires the holder's address among the watchers; both need ExclusiveLockHeld. Departed lists addresses, such as a former owner's, that must not watch the image. Unwatched requires no watcher at all. Watchers and locks that the expectation does not name are not compared, so selecting one client leaves unrelated clients alone.
The watcher and lock lists come from separate native reads. During a lock handoff an observation can report the new owner without its watch, so an owner-watch mismatch is a possible observed state, not proof of a fault; the test decides whether and when to read again. A match does not prove that the owner can write.
func (ImageClients) Evaluate ¶
func (e ImageClients) Evaluate(observed rbd.ImageClientStatus) (ImageClientsEvaluation, error)
Evaluate checks one rbd.ImageClientStatus observation (from rbd.ImageClients) 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 that states nothing, an unknown Lock, an Owner or OwnerWatches without ExclusiveLockHeld, an Owner that is not a client entity name, an empty or repeated Departed address, and Unwatched together with OwnerWatches or Departed are ceph.ErrInvalidRequest. An observation with a watcher lacking its address or client ID, a lock lacking its ID, locker or address, a Managed flag that disagrees with the lock ID, or more than one managed lock is a malformed observation, never a mismatch. The result shares no slice with its arguments.
Example ¶
After a lock handoff the new owner must hold the exclusive lock and watch the image, and the former owner's watch must be gone. The two native reads behind the observation can disagree during the handoff, so the test decides whether to read again.
package main
import (
"fmt"
"github.com/JSYoo5B/ceph-testcontainers-go/rbd"
"github.com/JSYoo5B/ceph-testcontainers-go/rbd/expect"
)
func main() {
observed := rbd.ImageClientStatus{
Watchers: []rbd.ImageWatcher{{Address: "10.0.0.1:0/1001", ClientID: 4101, Cookie: 91}},
Locks: []rbd.ImageLock{{ID: "auto 92", Locker: "client.4102", Address: "10.0.0.2:0/2001", Managed: true}},
}
result, err := expect.ImageClients{
Lock: expect.ExclusiveLockHeld, Owner: "client.4102", OwnerWatches: true, Departed: []string{"10.0.0.1:0/1001"},
}.Evaluate(observed)
if err != nil {
panic(err)
}
fmt.Println(result)
}
Output: image clients want lock=held owner=client.4102 owner-watches departed=[10.0.0.1:0/1001]: owner-watch: want 10.0.0.2:0/2001 among watchers [10.0.0.1:0/1001]; departed: 10.0.0.1:0/1001 still watches
type ImageClientsEvaluation ¶
type ImageClientsEvaluation struct {
Expectation ImageClients
Observed rbd.ImageClientStatus
Mismatches []ImageClientsMismatch
Matched bool
}
ImageClientsEvaluation is the result of evaluating one observation. Expectation and Observed are copies of what was evaluated, so the diagnostics describe that observation even when the caller later reuses its slices. Mismatches are in the order of the reason constants, departed addresses in the order of the expectation; Matched means there are none.
func (ImageClientsEvaluation) String ¶
func (e ImageClientsEvaluation) String() string
String summarizes the expectation and at most eight mismatches.
type ImageClientsMismatch ¶
type ImageClientsMismatch struct {
Reason ImageClientsMismatchReason
Want, Observed string
}
ImageClientsMismatch is one reason an observation does not satisfy an expectation. Want and Observed are the compared values as text: "held" or "free" for ImageClientsMismatchLock, with the holder's entity name after an observed "held by"; entity names for ImageClientsMismatchOwner; the holder's address (Want) and the watcher addresses (Observed) for ImageClientsMismatchOwnerWatch; the address that still watches (Observed) for ImageClientsMismatchDeparted; and the watcher addresses (Observed) for ImageClientsMismatchWatched. Watcher addresses are in observation order, separated by spaces.
func (ImageClientsMismatch) String ¶
func (m ImageClientsMismatch) String() string
String names the reason and the evaluated values.
type ImageClientsMismatchReason ¶
type ImageClientsMismatchReason string
ImageClientsMismatchReason names why an observation does not satisfy an ImageClients expectation.
const ( // ImageClientsMismatchLock: the managed exclusive lock is held although // the expectation wants it free, or the reverse. A held expectation then // compares neither the owner nor its watch. ImageClientsMismatchLock ImageClientsMismatchReason = "lock" // ImageClientsMismatchOwner: another entity holds the managed lock. Its // watch is then not compared. ImageClientsMismatchOwner ImageClientsMismatchReason = "owner" // ImageClientsMismatchOwnerWatch: the holder's address is not among the // watchers, which a handoff between the two native reads can also show. ImageClientsMismatchOwnerWatch ImageClientsMismatchReason = "owner-watch" // ImageClientsMismatchDeparted: an address that must not watch the image // still does. ImageClientsMismatchDeparted ImageClientsMismatchReason = "departed" // ImageClientsMismatchWatched: an Unwatched expectation found watchers. ImageClientsMismatchWatched ImageClientsMismatchReason = "watched" )
The reasons an ImageClientsEvaluation reports.
type MirrorImage ¶
type MirrorImage struct {
Select mirror.ImageStatus
Replaying bool
Daemon string
NewInstance bool
}
MirrorImage states what a test expects of one mirrored image in one mirror.ImageStatus observation.
Select names the image and pins its identities, usually from an earlier observation of the same image. Name is required, and SourceNamespace and DestinationNamespace are always compared ("" is the default namespace). Pool and Mode are compared when set. A non-empty GlobalID, SourceImageID or DestinationImageID pins that native identity, so a re-created image of the same name does not match. Select.InstanceID is read only with NewInstance; the other Select fields are not read.
Replaying true requires an owned receiver to replay the source-primary/destination-secondary pair: ReplayReady, the native state up+replaying, both sides' mirroring enabled, a primary source and a non-primary destination. Replaying false requires only that ReplayReady is false; a stale native up+replaying report is then allowed. Daemon, when set, names the owned receiver that must report the replay. NewInstance requires a receiving instance other than Select.InstanceID, as after a receiver restart or replacement.
A match proves neither the arrival of a particular write nor the completion of a mirror snapshot: verify the destination data or the application's checkpoint separately.
func (MirrorImage) Evaluate ¶
func (e MirrorImage) Evaluate(observed mirror.ImageStatus) (MirrorImageEvaluation, error)
Evaluate checks one mirror.ImageStatus observation (from ImageStatus, WaitReplayReady or an image 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. A Select without a plain image name or with an unknown Mode, a Daemon or NewInstance without Replaying, and NewInstance without a Select.InstanceID are ceph.ErrInvalidRequest. An observation without an image name, or one that claims ReplayReady without the image identities and the receiving daemon and instance, is a malformed observation, never a mismatch.
Example ¶
A receiver restart must leave the image pair in place and replay it through a new receiving instance.
package main
import (
"fmt"
"github.com/JSYoo5B/ceph-testcontainers-go/rbd/expect"
"github.com/JSYoo5B/ceph-testcontainers-go/rbd/mirror"
)
func main() {
baseline := mirror.ImageStatus{
Pool: "volumes", Name: "volume", Mode: mirror.ModeJournal,
GlobalID: "6c1b8f9e-0000-4000-8000-000000000001", SourceImageID: "1a2b", DestinationImageID: "3c4d",
SourcePrimary: true, SourceMirrorState: "enabled", DestinationMirrorState: "enabled",
State: "up+replaying", DaemonName: "a", InstanceID: "4101", ReplayReady: true,
}
restarted := baseline
restarted.State, restarted.ReplayReady = "up+starting_replay", false
result, err := expect.MirrorImage{Select: baseline, Replaying: true, NewInstance: true}.Evaluate(restarted)
if err != nil {
panic(err)
}
fmt.Println(result)
}
Output: image volumes/:/volume want replaying=true new instance: replay: want true, observed false; state: want up+replaying, observed up+starting_replay; instance: want other than 4101, observed 4101
type MirrorImageEvaluation ¶
type MirrorImageEvaluation struct {
Expectation MirrorImage
Observed mirror.ImageStatus
Mismatches []MirrorImageMismatch
Matched bool
}
MirrorImageEvaluation is the result of evaluating one observation. Expectation and Observed are copies of what was evaluated. Mismatches are in the order of the reason constants; Matched means there are none. A scope mismatch is the only one reported, and a mode or pinned-identity mismatch suppresses the replay comparisons, since the observation describes another image.
func (MirrorImageEvaluation) String ¶
func (e MirrorImageEvaluation) String() string
String summarizes the expectation and at most eight mismatches.
type MirrorImageMismatch ¶
type MirrorImageMismatch struct {
Reason MirrorImageMismatchReason
Want, Observed string
}
MirrorImageMismatch is one reason an image does not satisfy an expectation. Want and Observed are the compared values as text: the scope as pool/source:destination/name for MirrorImageMismatchScope, the mirroring states as source/destination for MirrorImageMismatchMirrorState and the primary flags as source/destination for MirrorImageMismatchPrimary; for MirrorImageMismatchInstance, Want is the instance the observation must differ from.
func (MirrorImageMismatch) String ¶
func (m MirrorImageMismatch) String() string
String names the reason and the evaluated values.
type MirrorImageMismatchReason ¶
type MirrorImageMismatchReason string
MirrorImageMismatchReason names why an image does not satisfy a MirrorImage expectation.
const ( // MirrorImageMismatchScope: the observation describes another pool, namespace // mapping or image name. No other field is compared. MirrorImageMismatchScope MirrorImageMismatchReason = "scope" // MirrorImageMismatchMode: the mirroring mode differs. MirrorImageMismatchMode MirrorImageMismatchReason = "mode" // MirrorImageMismatchGlobalID: the native global mirror image ID differs // from the pinned one: the pair was re-created. MirrorImageMismatchGlobalID MirrorImageMismatchReason = "global-id" // MirrorImageMismatchSourceImage: the source image ID differs from the pinned // one: the source was re-created. MirrorImageMismatchSourceImage MirrorImageMismatchReason = "source-image" // MirrorImageMismatchDestinationImage: the destination image ID differs // from the pinned one, or no destination image is reported yet. MirrorImageMismatchDestinationImage MirrorImageMismatchReason = "destination-image" // MirrorImageMismatchReplay: ReplayReady differs from Replaying. MirrorImageMismatchReplay MirrorImageMismatchReason = "replay" // MirrorImageMismatchState: a Replaying expectation found a native state other // than up+replaying. MirrorImageMismatchState MirrorImageMismatchReason = "state" // MirrorImageMismatchMirrorState: a Replaying expectation found the // source's or the destination's mirroring not enabled. MirrorImageMismatchMirrorState MirrorImageMismatchReason = "mirror-state" // MirrorImageMismatchPrimary: a Replaying expectation found the source not // primary or the destination primary. MirrorImageMismatchPrimary MirrorImageMismatchReason = "primary" // MirrorImageMismatchDaemon: another owned receiver, or none, reports the // replay. MirrorImageMismatchDaemon MirrorImageMismatchReason = "daemon" // MirrorImageMismatchInstance: a NewInstance expectation found the pinned // receiving instance, or none. MirrorImageMismatchInstance MirrorImageMismatchReason = "instance" )
The reasons a MirrorImageEvaluation reports.
type ReceiverDaemon ¶
type ReceiverDaemon struct {
Name string
Baseline mirror.ReceiverDaemonStatus
Running bool
NewInstance bool
}
ReceiverDaemon selects one owned receiver daemon of a Receivers expectation by its daemon name.
Baseline is the daemon's status from an earlier mirror.ReceiverStatus observation, or the zero value. A non-empty Baseline.ContainerID pins the container, so a same-name replacement does not match. Baseline.InstanceID is read only with NewInstance; the other Baseline fields are not read.
Running true requires a running receiving process that reports the selected pool as running, has discovered the namespace mapping and has a native instance ID; false requires a process that is not running. NewInstance also requires a native instance ID other than Baseline.InstanceID, as after a restart of the same container. None of these prove image replay.
type ReceiverMismatch ¶
type ReceiverMismatch struct {
Reason ReceiverMismatchReason
Daemon string
Want, Observed string
}
ReceiverMismatch is one reason a cohort does not satisfy an expectation. Daemon is the daemon it concerns, empty for ReceiverMismatchLeader, ReceiverMismatchForeign and ReceiverMismatchReady. Want and Observed are the compared values as text: container IDs for ReceiverMismatchReplaced, "running" or "stopped" for ReceiverMismatchRunning, the pool state and namespace discovery for ReceiverMismatchDiscovered, instance IDs for ReceiverMismatchInstance and ReceiverMismatchForeign (Observed only), the problem code for ReceiverMismatchProblem (Observed only) and daemon names for ReceiverMismatchLeader. When the named leader matches but its election view conflicts with a selected receiver, Observed includes the conflicting views.
func (ReceiverMismatch) String ¶
func (m ReceiverMismatch) String() string
String names the daemon, the reason and the evaluated values.
type ReceiverMismatchReason ¶
type ReceiverMismatchReason string
ReceiverMismatchReason names why a cohort does not satisfy a Receivers expectation.
const ( // ReceiverMismatchAbsent: a selected daemon is not in the observed cohort. ReceiverMismatchAbsent ReceiverMismatchReason = "absent" // ReceiverMismatchReplaced: the daemon runs in another container than the // baseline pinned. Its other fields are not compared. ReceiverMismatchReplaced ReceiverMismatchReason = "replaced" // ReceiverMismatchRunning: the process runs although the expectation wants // it stopped, or the reverse. ReceiverMismatchRunning ReceiverMismatchReason = "running" // ReceiverMismatchDiscovered: a running process has not discovered the // selected pool and namespace mapping, or reports no instance. ReceiverMismatchDiscovered ReceiverMismatchReason = "discovered" // ReceiverMismatchInstance: a NewInstance selection still reports the // baseline's native instance. ReceiverMismatchInstance ReceiverMismatchReason = "instance" // ReceiverMismatchProblem: a Ready expectation found a daemon problem // code in the observation. ReceiverMismatchProblem ReceiverMismatchReason = "problem" // ReceiverMismatchUnselected: an Exact expectation found a daemon in the // observed cohort that the selection does not name. ReceiverMismatchUnselected ReceiverMismatchReason = "unselected" // ReceiverMismatchLeader: the agreed owned leader is not the expected one. ReceiverMismatchLeader ReceiverMismatchReason = "leader" // ReceiverMismatchForeign: a Ready or Exact expectation found a native // instance that the fixture does not own. ReceiverMismatchForeign ReceiverMismatchReason = "foreign" // ReceiverMismatchReady: a Ready expectation found the observation not // ready for no reason that another mismatch names. ReceiverMismatchReady ReceiverMismatchReason = "ready" )
The reasons a ReceiversEvaluation reports.
type Receivers ¶
type Receivers struct {
Select []ReceiverDaemon
Leader string
Ready bool
Exact bool
}
Receivers states what a test expects of the owned receiver cohort in one mirror.ReceiverStatus observation. Select names the daemons it checks. Leader, when set, names the selected running daemon that must be the agreed owned leader: it must claim its own instance, and every selected running receiver must report that instance as leader. Ready requires the observation's own Ready verdict, and lists each daemon problem and foreign instance that prevents it; Ready false places no requirement on the verdict. Exact requires the observed cohort to be exactly the selected daemons with no foreign native instance.
A match is a statement about the discovery and leader election that the observation reported: it does not prove that an image replays, nor that a write or a checkpoint arrived.
func (Receivers) Evaluate ¶
func (e Receivers) Evaluate(observed mirror.ReceiverStatus) (ReceiversEvaluation, error)
Evaluate checks one mirror.ReceiverStatus observation (from ReceiverStatus, WaitReceiverReady or a receiver 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 empty or duplicate selection, an empty daemon name, a Leader that is not a running selection, a NewInstance selection that is not running or has no baseline instance, and a Ready expectation with a stopped selection are ceph.ErrInvalidRequest. An observation with an empty or repeated cohort name, a daemon, problem or leader outside its cohort, or a Ready verdict that its own leader, foreign instances or problems contradict is a malformed observation, never a mismatch. The result shares no slice or map with its arguments.
Example ¶
After the leader stops, the survivor must lead while the stopped member stays in the cohort. The evaluation names what the observation lacks.
package main
import (
"fmt"
"github.com/JSYoo5B/ceph-testcontainers-go/rbd/expect"
"github.com/JSYoo5B/ceph-testcontainers-go/rbd/mirror"
)
func main() {
observed := mirror.ReceiverStatus{
Pool: "volumes", ExpectedDaemons: []string{"a", "b"},
Daemons: map[string]mirror.ReceiverDaemonStatus{
"a": {ContainerID: "cid-a", InstanceID: "4101", PoolState: "running", Running: true, NamespaceDiscovered: true, Leader: true},
"b": {ContainerID: "cid-b"},
},
LeaderDaemonName: "a", LeaderInstanceID: "4101", Instances: []string{"4101", "4102"},
DaemonProblems: map[string]string{"a": "receiver-membership-converging", "b": "receiver-not-running"},
}
result, err := expect.Receivers{Select: []expect.ReceiverDaemon{{Name: "a"}, {Name: "b", Running: true}}, Leader: "b"}.Evaluate(observed)
if err != nil {
panic(err) // invalid expectation or malformed observation: no verdict
}
fmt.Println(result.Matched)
fmt.Println(result)
}
Output: false receivers [a(stopped) b] leader=b in cohort [a b]: a running: want stopped, observed running; b running: want running, observed stopped; cohort leader: want b, observed a
type ReceiversEvaluation ¶
type ReceiversEvaluation struct {
Expectation Receivers
Observed mirror.ReceiverStatus
Mismatches []ReceiverMismatch
Matched bool
}
ReceiversEvaluation is the result of evaluating one observation. Expectation and Observed are copies of what was evaluated, so the diagnostics describe that observation even when the caller later reuses its slices and maps. Mismatches are ordered by selected or unselected daemon name, then in the order of the reason constants, followed by the leader, foreign instance (by ID) and ready mismatches; Matched means there are none.
func (ReceiversEvaluation) String ¶
func (e ReceiversEvaluation) String() string
String summarizes the expectation and at most eight mismatches.