Skip to main content

Server

Struct Server 

Source
pub struct Server<'a, A, H> {
    pub node: Node<'a>,
    pub access: &'a A,
    pub handler: &'a H,
    pub limit: usize,
    pub versions: Option<&'a dyn DataVersionSource>,
    pub events: Option<&'a dyn EventSource>,
}
Expand description

A server that answers interactions against one node.

The node, the access control and the cluster handler are all long-lived — a device has one of each for its whole life — so they are held here rather than threaded through every call. What varies per interaction is the paths and the buffers.

Fields§

§node: Node<'a>

The data model being served.

§access: &'a A

Who is asking, and what they may have.

§handler: &'a H

The device’s clusters.

§limit: usize

The most reports one message may carry, on top of what fits in its buffer.

A second, coarser bound than the buffer: both end a chunk, whichever comes first, and neither loses anything, because Server::serve_chunk resumes from a ReadCursor. Bounding a message by bytes is what §10.2.3 actually asks for, so usize::MAX here is a reasonable choice — the buffer decides. A smaller value is for bounding the work a single response costs the peer that must parse it.

§versions: Option<&'a dyn DataVersionSource>

§7.10.3’s cluster data versions, for every cluster that does not track its own.

None means a report carries a DataVersion only where a cluster supplied one. That is legal — §10.6.4.1 makes the field omissible — and it is also how a node ends up uncommissionable: the CHIP SDK’s cluster-state cache is keyed by version and silently drops an attribute that arrives without one, so a commissioner receives every attribute it asked for and then reports each as missing. Give the server a table.

§events: Option<&'a dyn EventSource>

§7.14’s event log, for the EventRequests half of a read or subscription.

None is a node that reports no events, which is legal — §8.4.3.3 step 5 makes an empty EventRequests an empty answer — and is the wrong answer for any node whose clusters define events, because the client is told the log is empty rather than that nobody is serving it.

Implementations§

Source§

impl<'a, A: AccessControl, H: ClusterHandler> Server<'a, A, H>

Source

pub const fn new( node: Node<'a>, access: &'a A, handler: &'a H, limit: usize, ) -> Self

A server over a node.

Source

pub const fn with_data_versions( self, versions: &'a dyn DataVersionSource, ) -> Self

Supplies §7.10.3’s data versions for clusters that do not track their own.

A cluster’s own ClusterHandler::data_version still wins where it returns Some: a cluster that knows when its data changed knows better than a table that is only told about writes arriving over the wire.

Source

pub const fn with_events(self, events: &'a dyn EventSource) -> Self

Supplies §7.14’s event log, so a read or subscription can answer EventRequests.

Without it every event path is answered as though the node had recorded nothing, which a client cannot tell from a node that genuinely has.

Source

pub fn any_readable( &self, paths: impl IntoIterator<Item = Result<AttributePath>>, ) -> Result<bool>

Whether any path in paths survives §8.4.3.2’s steps 1 and 2 — exists, and the subject may read it.

§8.4.3 step 2: “If no error-free existent paths remain, then AttributeRequests are considered empty”, and step 7.a makes an empty Subscribe INVALID_ACTION. So a subscription to a cluster the subscriber cannot read is not an empty subscription that reports nothing — it is a malformed action, and answering it with a SubscribeResponse tells the subscriber it will hear about something it will never hear about.

Source

pub fn serve<'b>( &self, paths: impl IntoIterator<Item = Result<AttributePath>>, ctx: &InteractionContext<'_>, subscription_id: Option<u32>, scratch: &mut [u8], buf: &'b mut [u8], ) -> Result<(&'b [u8], ReadOutcome)>

Serves a whole ReadRequest into a single ReportData message.

For reads known to be small. A read that does not fit is ErrorCode::ReportWouldChunk rather than a truncated message: a single message cannot honour MoreChunkedMessages, and emitting one anyway would promise the client a continuation that never arrives. Serve such a read with Server::serve_chunk, which is the same processing across as many messages as it takes.

A whole-node wildcard on any real device does not fit, so a server answering arbitrary client reads wants serve_chunk and not this.

Source

pub fn serve_chunk<'b>( &self, paths: impl IntoIterator<Item = Result<AttributePath>>, ctx: &InteractionContext<'_>, subscription_id: Option<u32>, cursor: &mut ReadCursor, scratch: &mut [u8], buf: &'b mut [u8], ) -> Result<(&'b [u8], ReadOutcome)>

Serves one message of a ReadRequest, resuming at cursor (§10.2.3).

Packs as many information blocks into buf as fit, then stops on a block boundary and records where in cursor. When more remains the message carries MoreChunkedMessages and ReadOutcome::truncated is set; call again with the same cursor for the next message. The read is over when ReadCursor::is_done is true, which happens on the message that does not set the flag.

§10.2.3 requires the client’s StatusResponse between messages — “each data message requires a response before the next data message can be sent” — so the loop is driven by the exchange, not by this call.

Forward progress is guaranteed: a value too large for an empty message is either split per §10.6.4.3.1 when it is a list, or answered RESOURCE_EXHAUSTED when it cannot be split. So the loop always terminates, whatever a cluster returns.

Source

pub fn serve_chunk_with_events<'b>( &self, paths: impl IntoIterator<Item = Result<AttributePath>>, events: impl IntoIterator<Item = Result<EventPath>>, ctx: &InteractionContext<'_>, subscription_id: Option<u32>, cursor: &mut ReadCursor, scratch: &mut [u8], buf: &'b mut [u8], ) -> Result<(&'b [u8], ReadOutcome)>

One message of a read that asks for both attributes and events (§10.7.3).

A ReportData carries two arrays, and §8.4.3 processes AttributeRequests and EventRequests as two halves of one action. They chunk together: attributes first, then events, with the cursor remembering which half a series stopped in. A node that served only the first half would answer every EventRequests as though its log were empty — which a client cannot tell from a node that has genuinely recorded nothing.

Server::serve_chunk is this with no event paths.

Source§

impl<A: AccessControl, H: ClusterHandler> Server<'_, A, H>

Source

pub fn serve_write_path( &self, data: &AttributeData<'_>, ctx: &InteractionContext<'_>, action: &mut WriteAction, w: &mut TlvWriter<'_>, responses: &mut usize, ) -> Result<bool>

Serves one write path into an already-open WriteResponses array.

§8.7.3.2 mirrors §8.4.3.2 step for step — the same concrete/expanded asymmetry, the same two-stage access check — with three checks a read does not have:

  • step b.iv: an attribute with the T quality needs a Timed transaction (NEEDS_TIMED_INTERACTION);
  • step b.v: a fabric-scoped attribute needs an accessing fabric (UNSUPPORTED_ACCESS);
  • step b.vi: a DataVersion that disagrees with the cluster’s (DATA_VERSION_MISMATCH).

And one difference in what is reported: §8.7.3.3 step 2.b.ii generates a SUCCESS status for every path that was written, where a read reports success by returning data. So a write response is never empty unless everything was discarded.

Source

pub fn serve_write<'b>( &self, writes: impl IntoIterator<Item = Result<AttributeData<'b>>>, ctx: &InteractionContext<'_>, more_chunked: bool, buf: &'b mut [u8], ) -> Result<(&'b [u8], ReadOutcome)>

Serves a whole WriteRequest into a WriteResponse message.

Source§

impl<A: AccessControl, H: ClusterHandler> Server<'_, A, H>

Source

pub fn serve_invoke_command( &self, command: &CommandData<'_>, ctx: &InteractionContext<'_>, w: &mut TlvWriter<'_>, responses: &mut usize, scratch: &mut [u8], ) -> Result<bool>

Serves one command into an already-open InvokeResponses array.

§8.8.2.3 again mirrors the read, with one difference that matters: the first access check is at Operate, not View. §8.8.2.3 step b.i: “assuming the required_privilege for the element is Operate”. That is because there is no such thing as a read-only command — View is enough to look at a node, and never enough to make it do something.

Source

pub fn serve_invoke<'b>( &self, commands: impl IntoIterator<Item = Result<CommandData<'b>>>, ctx: &InteractionContext<'_>, suppress_response: bool, scratch: &mut [u8], buf: &'b mut [u8], ) -> Result<(&'b [u8], ReadOutcome)>

Serves a whole InvokeRequest into an InvokeResponse message.

commands is the request’s InvokeRequests array. §8.8.2.2 step 5 forbids a wildcard once there is more than one command, and the caller is expected to have refused such a request with INVALID_ACTION before reaching here — this serves what it is given.

Source§

impl<A: AccessControl, H: ClusterHandler> Server<'_, A, H>

Source

pub fn prime<'b>( &self, subscription_id: u32, paths: impl IntoIterator<Item = Result<AttributePath>>, ctx: &InteractionContext<'_>, scratch: &mut [u8], buf: &'b mut [u8], ) -> Result<(&'b [u8], ReadOutcome)>

Serves the priming report of a subscription — §8.5.1’s second action.

A Subscribe transaction is four actions: the request, a ReportData that primes the subscriber, a StatusResponse acknowledging it, and only then the SubscribeResponse that activates the subscription. This is the second, and it is an ordinary read — the specification routes both through the same processing, “as defined in Incoming Read Request and Subscribe Request Action Processing”.

The difference is the SubscriptionId, which §8.5.3.2 requires to be “the same as the one used in Report Data generated to prime this subscription”. So the id is allocated before the priming report and confirmed afterwards, not the other way round.

Source

pub fn report<'b, const P: usize>( &self, subscription: &mut Subscription<P>, reason: ReportReason, ctx: &InteractionContext<'_>, scratch: &mut [u8], buf: &'b mut [u8], ) -> Result<(&'b [u8], ReadOutcome)>

Serves a subscription’s periodic report (§8.6).

reason decides the shape. A ReportReason::Data report carries what changed and asks for a StatusResponse; a ReportReason::KeepAlive one is §8.6.2’s “Report Transaction Empty” — “report with no data or events with SuppressResponse set to TRUE”, because its only job is to prove the publisher is still there and there is nothing for a subscriber to acknowledge.

A subscription whose dirty set overflowed reports everything it covers: §8.5’s own recovery, “Including all subscription data to re-prime the subscription”.

One message only, and ErrorCode::ReportWouldChunk when that is not enough — the re-primed case above makes that likely, so a publisher serving wildcard subscriptions wants Server::report_chunk.

Source

pub fn report_chunk<'b, const P: usize>( &self, subscription: &mut Subscription<P>, reason: ReportReason, ctx: &InteractionContext<'_>, scratch: &mut [u8], buf: &'b mut [u8], ) -> Result<(&'b [u8], ReadOutcome)>

One message of a subscription’s report, resuming at cursor (§10.2.3).

A report over a wildcard subscription, and any re-primed one, is as large as the read that primed it, so it chunks the same way. Server::report is this for reports expected to fit.

The subscription carries its own cursor, so a series resumes and a finished one starts over without the caller tracking either: call this until ReadOutcome::truncated is false, answering each StatusResponse with the next chunk (§10.2.3). Two subscriptions reporting at once therefore cannot resume into each other’s report, which is the failure a single shared cursor produces and nothing on the wire reveals.

Trait Implementations§

Source§

impl<'a, A: Clone, H: Clone> Clone for Server<'a, A, H>

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, A: Copy, H: Copy> Copy for Server<'a, A, H>

Source§

impl<'a, A: Debug, H: Debug> Debug for Server<'a, A, H>

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'a, A, H> !RefUnwindSafe for Server<'a, A, H>

§

impl<'a, A, H> !Send for Server<'a, A, H>

§

impl<'a, A, H> !Sync for Server<'a, A, H>

§

impl<'a, A, H> !UnwindSafe for Server<'a, A, H>

§

impl<'a, A, H> Forget for Server<'a, A, H>

§

impl<'a, A, H> Freeze for Server<'a, A, H>

§

impl<'a, A, H> Move for Server<'a, A, H>

§

impl<'a, A, H> Unpin for Server<'a, A, H>

§

impl<'a, A, H> UnsafeUnpin for Server<'a, A, H>

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.