faulthook

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: 5 Imported by: 0

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

View Source
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 BlueStore

func BlueStore(c *ceph.Container) bool

BlueStore reports a cluster with BlueStore OSDs.

func CLI

func CLI(ctx context.Context, c *ceph.Container, args ...string) ([]byte, error)

CLI runs a Ceph CLI command with the admin identity.

func CheckPoolID

func CheckPoolID(ctx context.Context, c *ceph.Container, expected ceph.PoolState) error

CheckPoolID refuses a pool that was replaced since expected was read.

func ClassifyDocker

func ClassifyDocker(ctx context.Context, err error) error

ClassifyDocker classifies a failed Docker call.

func Closed

func Closed(c *ceph.Container) bool

Closed reports a terminated cluster. The caller holds the mutex.

func Control

Control returns the container that runs the control CLI.

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

func NativeFailure(program string, code int, stdout, stderr []byte) error

NativeFailure describes a native command that exited nonzero.

func OnlyMissingHostResource

func OnlyMissingHostResource(err error) bool

OnlyMissingHostResource reports an error that only says a container or network is already gone.

func OwnedLabel

OwnedLabel labels a helper container as owned by the cluster.

func OwnedOSD

func OwnedOSD(c *ceph.Container, id int) bool

OwnedOSD reports an OSD that the cluster owns and has not purged. The caller holds the mutex.

func Owns

func Owns(c *ceph.Container, id string) bool

Owns reports a container of the cluster's own daemons. The caller holds the mutex.

func PoolPolicyReady

func PoolPolicyReady(c *ceph.Container) error

PoolPolicyReady refuses a terminated cluster or one without a control container. The caller holds the mutex.

func PoolState

func PoolState(ctx context.Context, c *ceph.Container, name string) (ceph.PoolState, error)

PoolState reads one pool. The caller holds the mutex.

func Release

func Release(c *ceph.Container, token Token) bool

Release forgets the fault of token while its key still maps to it. The caller holds the mutex.

func Settle

func Settle(c *ceph.Container, token Token, held Held) (bool, error)

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

func StartupTimeout(c *ceph.Container) time.Duration

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

func WithTopology(ctx context.Context, c *ceph.Container, fn func() error) error

WithTopology runs fn with the cluster mutex held, unless ctx ends first.

func WithTopologyNoContext

func WithTopologyNoContext(c *ceph.Container, fn func())

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

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

type BlockDevice struct {
	HostPath     string
	Major, Minor uint32
	SizeBytes    int64
}

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.

const (
	FactUnknown Fact = iota
	FactNo
	FactYes
)

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.

func Reserve

func Reserve(ctx context.Context, c *ceph.Container, kind Kind, key string) (Token, any, error)

Reserve reserves key for a fault of kind. The caller holds the mutex and has refused a closed cluster with its own error. A refusal of NetworkInterruption, ContainerPause or CPULimit may return the previous handle, which still needs its undo.

Jump to

Keyboard shortcuts

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