Skip to main content

InteractionContext

Struct InteractionContext 

Source
pub struct InteractionContext<'a> {
Show 14 fields pub timed: bool, pub fabric_index: Option<FabricIndex>, pub large_messages: bool, pub fabric_filtered: bool, pub now: Instant, pub vendor_id_verified: bool, pub session: Option<SessionId>, pub atomic: Option<ClaimRef<'a>>, pub peer_node_id: Option<NodeId>, pub attestation_challenge: Option<&'a SymmetricKey>, pub privilege: Option<Privilege>, pub group: Option<GroupId>, pub event_filters: Option<&'a [u8]>, pub data_version_filters: Option<&'a [u8]>,
}
Expand description

What a handler needs to know about the interaction it is running inside.

Everything here is a fact about the session and action, not about the node: a cluster cannot read any of it for itself, and several of §11.18’s commands are wrong without it.

Fields§

§timed: bool

Whether this action is part of a Timed transaction (§8.7.4).

The server has already refused anything that requires one and did not get it, so a handler needs this only if it wants to impose its own rule.

§fabric_index: Option<FabricIndex>

The fabric this interaction is scoped to, if any.

None on a PASE session during commissioning, which is why §8.8.2.3 step b.v makes a fabric-scoped command UNSUPPORTED_ACCESS when there is no accessing fabric.

§large_messages: bool

Whether the transport can carry Large Messages (§7.7.5) — that is, whether it is TCP.

§fabric_filtered: bool

Whether the request asked for fabric filtering (§7.19.1.8.2).

A fabric-scoped list read with filtering on reports only the accessing fabric’s entries; with it off, the full list, each entry carrying its FabricIndex global field. ReadRequest and SubscribeRequest both carry the flag, and a cluster that ignored it would either leak every administrator’s entries to one of them or hide from a verifier the entries §6.4.10 requires it to read.

Defaults to false — the unfiltered, full-list reading, which is what AttributePathIB’s own default means.

§now: Instant

Monotonic time, as of the moment the action started.

Handed to the handler rather than read by it, because a cluster is not the thing that owns a clock — and because a single action must see a single instant: §11.10.7.2’s fail-safe decides whether it is armed, re-arms it, and records progress, all of which must agree about when.

Defaults to Instant::ZERO, which is correct for a node whose clusters have no deadlines — nothing consults it.

§vendor_id_verified: bool

Whether §6.4.10’s Vendor ID Verification has been run against this peer.

Only §11.25.6.1 consults it, and the default of false is the cautious one: a node that assumed verification had happened would cross-sign an intermediate CA for an ecosystem whose vendor nobody had checked.

§session: Option<SessionId>

Which secure session this action arrived on.

§11.18.6.7 scopes the CSR state to a session — “If no context or memory exists of a prior CSRRequest command having been invoked in the same secure session as that which is receiving this AddNOC or UpdateNOC invocation, then the Node SHALL … respond with a StatusCode of MissingCsr”. Without this, one administrator’s CSRRequest could be consumed by another’s AddNOC.

§atomic: Option<ClaimRef<'a>>

The atomic write this action is part of, if any (§7.15.3).

An attribute with the Atomic quality is writable only inside a claim covering it — §7.15.3: “If a server receives a Write Request for an attribute that is not associated with an Atomic Write State that is also associated with the client making the request, the server SHALL return the error code INVALID_IN_STATE.” Derived by the caller from AtomicWrites::find, the same way timed is derived from the window table, and asserted here.

§peer_node_id: Option<NodeId>

The peer’s operational Node ID, when the session authenticated one (§6.6.6.3).

None on a PASE session, which has no node id — only a passcode. §6.6.6.1.3’s Incoming Subject Descriptor is “deterministic based on both incoming message fields and session metadata fields”, and this is the session’s half: it is what CASE proved, never what a message claimed, which is the difference between an access decision and a suggestion from the sender.

§attestation_challenge: Option<&'a SymmetricKey>

The session’s AttestationChallenge — the third key it derived (§4.14.2.6.2).

§11.18.4.7, §11.18.4.9 and §11.18.6.16 all sign over it, and it “SHALL NOT be included in any of the payloads conveyed”: a signature made over it proves the signer is on this session, which is precisely what stops a recorded attestation being replayed.

Borrowed rather than copied, because it is key material with a ZeroizeOnDrop owner and there is no reason for a second copy to exist.

§privilege: Option<Privilege>

The strongest privilege the ISD holds over this path (§6.6.6.2), when the caller computed one.

The access check that admitted an action only proves the subject cleared the required bar. A few clusters need to know how far above it the subject actually is, because the specification gives administrators and managers different rules for the same command: §9.16.7.1’s RegisterClient demands a verification key from a manager and ignores one from an administrator, so a server that could not tell them apart would either lock administrators out or let a manager overwrite any registration it liked.

Derived by the caller from the same access decision that admitted the action — with Granted::highest where the ACL engine is in use — the way timed and atomic are derived. None means the caller did not compute one, and a cluster that needs it must then take the cautious branch.

§group: Option<GroupId>

The group this action was addressed to, when it arrived as a groupcast (§4.16.1).

None is a unicast. Several clusters branch on this rather than on anything in the payload: §1.3.7.1.2 says the Groups cluster “SHALL NOT generate an AddGroupResponse command” for a groupcast, and the reason is arithmetic — one multicast reaching twenty lights would otherwise draw twenty unicast responses at once, on a network chosen for low power rather than burst capacity.

§8.8.2.2 also forbids a groupcast Invoke from carrying a concrete endpoint or expecting any response at all, so a cluster that answered anyway would be answering a request the client is not listening for.

§event_filters: Option<&'a [u8]>

§8.4.3.3 step 6.a.i’s EventFilters, still encoded, as the request carried them.

A client that already holds events up to some number sends this so the node does not resend them — the event log’s equivalent of DataVersionFilters, and the only way a client resuming after a gap avoids re-reading the whole ring.

§data_version_filters: Option<&'a [u8]>

§8.4.3.2 step 3.a’s DataVersionFilters, still encoded, as the request carried them.

Kept as TLV rather than a decoded list because this type is Copy and the crate does not allocate: the filters are walked once per reported attribute, which is cheap for the handful a client sends and costs nothing when there are none.

A client sends these to say “do not send me a cluster I already have”, which is the only mechanism in the interaction model that makes a wildcard read cheap on a device that mostly has not changed. A server that decodes them and ignores them is correct about every value it sends and wrong about the bandwidth, on exactly the reads that matter most.

Implementations§

Source§

impl<'a> InteractionContext<'a>

Source

pub const fn new() -> Self

The context of an action on an unauthenticated, untimed session.

A starting point for the with_* builders. This is const, and the builders are too, because a device’s fixed set of contexts is const data — and a const struct literal has to name every field, so every field added here would otherwise be a breaking change for anyone who wrote one.

Source

pub const fn with_event_filters(self, filters: &'a [u8]) -> Self

Carries §8.4.3.3 step 6.a.i’s EventFilters, as the request encoded them.

Source

pub const fn with_data_version_filters(self, filters: &'a [u8]) -> Self

Carries §8.4.3.2 step 3.a’s DataVersionFilters, as the request encoded them.

Source

pub const fn with_group(self, group: GroupId) -> Self

Marks the action as a groupcast addressed to group (§4.16.1).

Source

pub const fn with_privilege(self, privilege: Privilege) -> Self

Records the strongest privilege the ISD holds over this path.

Source

pub const fn with_vendor_id_verified(self) -> Self

Records that §6.4.10’s Fabric Table Vendor ID Verification Procedure was run against the peer that sent this action.

§11.25.6.1 is the one place that asks: ICACCSRRequest refuses with JfVidNotVerified until the peer has proved which vendor owns the fabric it is administering from. The procedure itself is a challenge and a signature over an exchange this layer does not see, so the answer comes in with the action rather than being derived here.

Source

pub const fn timed(self) -> Self

Marks the action as part of a Timed transaction (§8.7.4).

Source

pub const fn with_fabric(self, fabric_index: FabricIndex) -> Self

Sets the accessing fabric.

Source

pub const fn with_large_messages(self) -> Self

Marks the transport as able to carry Large Messages (§7.7.5) — that is, TCP.

Source

pub const fn fabric_filtered(self) -> Self

Asks for §7.19.1.8.2’s fabric filtering on a fabric-scoped list read.

Source

pub const fn at(self, now: Instant) -> Self

Sets the instant the action started.

Source

pub const fn on_session(self, session: SessionId) -> Self

Sets the secure session this action arrived on.

Source

pub const fn under_claim(self, claim: ClaimRef<'a>) -> Self

Marks this action as writing under an open atomic claim (§7.15.3).

Source

pub const fn from_peer(self, peer_node_id: NodeId) -> Self

Sets the peer’s operational Node ID, as CASE proved it (§6.6.6.3).

Source

pub const fn with_attestation_challenge( self, challenge: &'a SymmetricKey, ) -> Self

Attaches the session’s AttestationChallenge (§4.14.2.6.2).

Trait Implementations§

Source§

impl<'a> Clone for InteractionContext<'a>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<'a> Copy for InteractionContext<'a>

Source§

impl<'a> Debug for InteractionContext<'a>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for InteractionContext<'_>

Source§

fn default() -> Self

The same as InteractionContext::new, so the two cannot drift apart.

Auto Trait Implementations§

§

impl<'a> Forget for InteractionContext<'a>

§

impl<'a> Freeze for InteractionContext<'a>

§

impl<'a> Move for InteractionContext<'a>

§

impl<'a> RefUnwindSafe for InteractionContext<'a>

§

impl<'a> Send for InteractionContext<'a>

§

impl<'a> Sync for InteractionContext<'a>

§

impl<'a> Unpin for InteractionContext<'a>

§

impl<'a> UnsafeUnpin for InteractionContext<'a>

§

impl<'a> UnwindSafe for InteractionContext<'a>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.