Documentation
¶
Overview ¶
Package faulthook gives fault operations outside package ceph the parts of a ceph.Container that are not public API: the cluster's fault registry, its mutex and the private helpers that fault operations use. Package ceph registers them in internal/hookreg when it is initialized.
The registry is the only way to make a fault known to Terminate. Each kind has a phase that package ceph fixes: network delays are undone first and block I/O tables second, both with the cluster mutex released, then interruptions under it (a failure keeps the network), then pauses and CPU limits last under it. Callers cannot add a phase, change the order or register another cleanup.
Lock rules: Reserve, Settle, Release, Closed, Owns, OwnedOSD, PoolPolicyReady and PoolState need the cluster mutex, held through WithTopology or WithTopologyNoContext. A function passed to them must not lock a handle's mutex that is itself held while the cluster mutex is taken (a network delay lease), must not call a public ceph.Container method that takes the cluster mutex, and returns before the hook unlocks.
Index ¶
- Constants
- func AddBlockDeviceOSD(ctx context.Context, c *ceph.Container, device BlockDevice, lease string) (*ceph.OSDContainer, error)
- func BlueStore(c *ceph.Container) bool
- func CLI(ctx context.Context, c *ceph.Container, args ...string) ([]byte, error)
- func CheckPoolID(ctx context.Context, c *ceph.Container, expected ceph.PoolState) error
- func ClassifyDocker(ctx context.Context, err error) error
- func Closed(c *ceph.Container) bool
- func Control(ctx context.Context, c *ceph.Container) (testcontainers.Container, error)
- func JudgeDeviceChain(ctx context.Context, c *ceph.Container, device BlockDevice, lease string, ...) (outcome, detail string)
- func NativeFailure(program string, code int, stdout, stderr []byte) error
- func OnlyMissingHostResource(err error) bool
- func OwnedLabel(c *ceph.Container) testcontainers.CustomizeRequestOption
- func OwnedOSD(c *ceph.Container, id int) bool
- func Owns(c *ceph.Container, id string) bool
- func PoolPolicyReady(c *ceph.Container) error
- func PoolState(ctx context.Context, c *ceph.Container, name string) (ceph.PoolState, error)
- func Release(c *ceph.Container, token Token) bool
- func Settle(c *ceph.Container, token Token, held Held) (bool, error)
- func StartupTimeout(c *ceph.Container) time.Duration
- func Terminated() (native, cluster error)
- func WithTopology(ctx context.Context, c *ceph.Container, fn func() error) error
- func WithTopologyNoContext(c *ceph.Container, fn func())
- func ZoneRouter(ctx context.Context, c *ceph.Container, zone string, plane ceph.NetworkPlane) (testcontainers.Container, string, error)
- type BlockDevice
- type ChainEvidence
- type Fact
- type Held
- type Kind
- type Token
Constants ¶
const ChainClear = "clear"
ChainClear is the one outcome of JudgeDeviceChain that raises no objection. Every other outcome retains the chain: retain-unknown, retain-claim, retain-identity or retain-busy.
Variables ¶
This section is empty.
Functions ¶
func AddBlockDeviceOSD ¶
func AddBlockDeviceOSD(ctx context.Context, c *ceph.Container, device BlockDevice, lease string) (*ceph.OSDContainer, error)
AddBlockDeviceOSD adds one OSD whose BlueStore main device is device, in the cluster's default placement, and waits for it to be up and in. The cluster must use the default OSD storage. The caller owns the file, loop and device-mapper chain behind device and keeps it until JudgeDeviceChain reports ChainClear; an error here never releases it. It is internal: no public option adds a device-backed OSD.
func CheckPoolID ¶
CheckPoolID refuses a pool that was replaced since expected was read.
func ClassifyDocker ¶
ClassifyDocker classifies a failed Docker call.
func JudgeDeviceChain ¶
func JudgeDeviceChain(ctx context.Context, c *ceph.Container, device BlockDevice, lease string, evidence func(context.Context) (ChainEvidence, error)) (outcome, detail string)
JudgeDeviceChain joins the cluster's claim table with the owner's evidence for device and lease. It is not authority to release anything; it only reports that neither receipt objects. It works after Terminate.
func NativeFailure ¶
NativeFailure describes a native command that exited nonzero.
func OnlyMissingHostResource ¶
OnlyMissingHostResource reports an error that only says a container or network is already gone.
func OwnedLabel ¶
func OwnedLabel(c *ceph.Container) testcontainers.CustomizeRequestOption
OwnedLabel labels a helper container as owned by the cluster.
func OwnedOSD ¶
OwnedOSD reports an OSD that the cluster owns and has not purged. The caller holds the mutex.
func PoolPolicyReady ¶
PoolPolicyReady refuses a terminated cluster or one without a control container. The caller holds the mutex.
func Release ¶
Release forgets the fault of token while its key still maps to it. The caller holds the mutex.
func Settle ¶
Settle records held for a reservation, or ends the reservation when held.Handle is nil. It reports whether Terminate has started meanwhile, in which case Terminate did not see the handle and the caller undoes it. The caller holds the mutex.
func StartupTimeout ¶
StartupTimeout bounds one fixture operation.
func Terminated ¶
func Terminated() (native, cluster error)
Terminated returns the error of a fault that Terminate overtook and the error of an operation on a terminated cluster.
func WithTopology ¶
WithTopology runs fn with the cluster mutex held, unless ctx ends first.
func WithTopologyNoContext ¶
WithTopologyNoContext runs fn with the cluster mutex held, waiting for it without a context. It is for finalization only: recording or freeing a reservation that must not be dropped when the caller's context ended.
func ZoneRouter ¶ added in v0.5.0
func ZoneRouter(ctx context.Context, c *ceph.Container, zone string, plane ceph.NetworkPlane) (testcontainers.Container, string, error)
ZoneRouter returns the router that forwards what leaves zone and the bridge of plane, after checking that the bridges of all configured planes contain only enrolled zone members and routers. It takes neither the cluster mutex nor a handle's mutex; the boundary's own lock is a leaf.
Types ¶
type BlockDevice ¶
BlockDevice is the identity a lease owner verified for one device-mapper node: its /dev/mapper path on the engine host, its number and its size.
type ChainEvidence ¶
type ChainEvidence struct {
Lease string
Device BlockDevice
DaemonStopped, BorrowsClosed, ScanComplete Fact
Openers int
}
ChainEvidence is what the lease owner observed about its chain: the lease and device it saw, whether the OSD daemon ended, whether every observer borrow of the device was closed, whether its opener scan was complete, and how many openers that scan found.
type Fact ¶
type Fact uint8
Fact is a tri-state observation of the lease owner. The zero value is unknown and never counts as evidence.
type Held ¶
type Held struct {
// Network is the network that an interruption needs back.
Network string
// Handle is the public handle that an overlap refusal may return.
Handle any
// Undo is what Terminate calls in the kind's phase.
Undo func(context.Context) error
// Complete reports a fault that no longer needs Undo. A kind that has it
// returns the previous handle with an overlap refusal and replaces a
// complete one; without it the key is held until Release.
Complete func(context.Context) (bool, error)
}
Held is what Settle records for a reservation.
type Kind ¶
type Kind string
Kind names one family of faults that a cluster tracks.
const ( // BlockIO restores an owned main-device table before daemon shutdown, // without the topology mutex. Its helper has a separate backend lifetime. BlockIO Kind = "BlockIO" // NetworkDelay holds a netem lease per network and container until its // Restore releases it; Terminate restores it first, unlocked. NetworkDelay Kind = "NetworkDelay" // NetworkInterruption holds a disconnected endpoint per network and // container; Terminate restores it under the mutex, and a failure keeps // its network. NetworkInterruption Kind = "NetworkInterruption" // ContainerPause holds a frozen container per ID; Terminate resumes it // under the mutex before native commands stop. ContainerPause Kind = "ContainerPause" // CPULimit holds a CPU bandwidth limit per container ID; Terminate // restores it under the mutex after pauses are resumed. CPULimit Kind = "CPULimit" )
type Token ¶
type Token struct {
// contains filtered or unexported fields
}
Token identifies one reservation. Only the token that a key still maps to settles or releases, so a stale handle cannot release its successor.