class

Matter::FailsafeContext

Inherits Reference < Object

FailsafeContext manages commissioning state and coordinates rollback on failure

The failsafe context is created when ArmFailSafe is invoked and tracks all commissioning state changes (fabric operations, network config, etc.) so that they can be rolled back if the failsafe timer expires.

Matter Core Spec §11.10.7 - General Commissioning Cluster Matter Core Spec §5.5 - Commissioning Flows

Constants

Log = ::Log.for("matter.failsafe_context")

Constructors

new(associated_fabric_index : UInt8 | Nil, breadcrumb : UInt64, expiry_callback : Proc(Nil))

Create a new failsafe context

@param fabric_index Fabric index for CASE sessions (nil for PASE) @param breadcrumb Progress tracking value @param expiry_callback Callback invoked when failsafe expires (performs rollback)

Source

Instance methods

added_fabric_index

Whether a new fabric was added during this context

Source
added_fabric_index=(added_fabric_index : UInt8 | Nil)

Whether a new fabric was added during this context

Source
arm(expiry_length : UInt16, max_cumulative : UInt16) : Nil

Arm the failsafe timer with specified durations

@param expiry_length Primary timer duration in seconds (0 = disarm) @param max_cumulative Maximum cumulative duration in seconds

Source
armed?

Check if the failsafe timer is currently armed

Source
associated_fabric_index

Fabric index associated with this context (nil for PASE/initial commissioning)

Source
associated_fabric_index=(associated_fabric_index : UInt8 | Nil)

Fabric index associated with this context (nil for PASE/initial commissioning)

Source
breadcrumb=(breadcrumb : UInt64)

Breadcrumb value for progress tracking

Source
close

Close and cleanup the failsafe context

Should be called when context is destroyed.

Source
csr_nonce

CSR nonce for pairing (tracks session ID)

Source
csr_nonce=(csr_nonce : Bytes | Nil)

CSR nonce for pairing (tracks session ID)

Source
cumulative_time_remaining

Get time remaining on cumulative timer

Source
disarm

Disarm the failsafe timer (mark as completed without triggering rollback)

Source
for_update_noc=(for_update_noc : Bool)

Whether this is for updating an existing NOC (vs adding new)

Source
for_update_noc?

Whether this is for updating an existing NOC (vs adding new)

Source
mark_for_update_noc

Mark this context as being for UpdateNOC (vs AddNOC)

Source
matches_fabric?(fabric_index : UInt8 | Nil) : Bool

Validate that fabric index matches this context

@param fabric_index Fabric index to validate @return true if matches, false otherwise

Special case: If the context was created during PASE (nil fabric), and a CASE session is now calling with a fabric_index that matches the fabric added during commissioning, this is the normal PASE→CASE commissioning flow.

Source
max_cumulative_seconds

Maximum cumulative failsafe timeout (hard limit)

Source
max_cumulative_seconds=(max_cumulative_seconds : UInt16)

Maximum cumulative failsafe timeout (hard limit)

Source
network_state_snapshot

Network commissioning state snapshot (for rollback)

Source
network_state_snapshot=(network_state_snapshot : Hash(String, String) | Nil)

Network commissioning state snapshot (for rollback)

Source
noc_update_snapshot

NOC update snapshot (for UpdateNOC rollback) Stores: (fabric_index, operational_cert, operational_key)

Source
noc_update_snapshot=(noc_update_snapshot : Tuple(UInt8, Bytes, Bytes) | Nil)

NOC update snapshot (for UpdateNOC rollback) Stores: (fabric_index, operational_cert, operational_key)

Source
primary_time_remaining

Get time remaining on primary timer

Source
record_added_fabric(fabric_index : UInt8) : Nil

Record that a new fabric was added during commissioning

This will be rolled back if failsafe expires.

Source
record_csr_nonce(nonce : Bytes) : Nil

Record CSR nonce for session tracking

@param nonce CSR nonce bytes

Source
record_network_state(state : Hash(String, String)) : Nil

Record network commissioning state for rollback

@param state Snapshot of network configuration

Source
record_noc_update(fabric_index : UInt8, operational_cert : Bytes, operational_key : Bytes) : Nil

Record NOC state before UpdateNOC for rollback

@param fabric_index Fabric index being updated @param operational_cert Current operational certificate @param operational_key Current operational private key

Source
record_regulatory_config(location_type : UInt8, country_code : String) : Nil

Record regulatory config state for rollback

@param location_type Current regulatory location type (as UInt8) @param country_code Current country code (2-character string)

Source
record_root_cert(cert : Bytes) : Nil

Record root certificate for validation

@param cert Root certificate bytes

Source
regulatory_config_snapshot

Regulatory config snapshot (for rollback)

Source
regulatory_config_snapshot=(regulatory_config_snapshot : Tuple(UInt8, String) | Nil)

Regulatory config snapshot (for rollback)

Source
rollback(fabric_manager : FabricManager | Nil = nil, session_manager : SessionManager | Nil = nil, network_commissioning : Cluster::NetworkCommissioningCluster | Nil = nil, commissioning_window : CommissioningWindow | Nil = nil, general_commissioning : Cluster::GeneralCommissioningCluster | Nil = nil) : Nil

Perform complete rollback of all commissioning state

This implements the 9-step rollback sequence from Matter spec:

  1. Revoke added fabric (if AddNOC was used)
  2. Revert UpdateNOC changes
  3. Restore network commissioning state
  4. Clear PASE sessions
  5. Reset breadcrumb to 0
  6. Close commissioning windows
  7. Clear CSR session
  8. Reset regulatory config
  9. Clean up temporary state

@param fabric_manager FabricManager for fabric operations @param session_manager SessionManager for PASE cleanup @param network_commissioning NetworkCommissioning cluster for network state restoration @param commissioning_window For closing windows @param general_commissioning GeneralCommissioning cluster for regulatory config reset

Source
root_cert

Root certificate bytes (for validation)

Source
root_cert=(root_cert : Bytes | Nil)

Root certificate bytes (for validation)

Source