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 AWho is asking, and what they may have.
handler: &'a HThe device’s clusters.
limit: usizeThe 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>
impl<'a, A: AccessControl, H: ClusterHandler> Server<'a, A, H>
Sourcepub const fn new(
node: Node<'a>,
access: &'a A,
handler: &'a H,
limit: usize,
) -> Self
pub const fn new( node: Node<'a>, access: &'a A, handler: &'a H, limit: usize, ) -> Self
A server over a node.
Sourcepub const fn with_data_versions(
self,
versions: &'a dyn DataVersionSource,
) -> Self
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.
Sourcepub const fn with_events(self, events: &'a dyn EventSource) -> Self
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.
Sourcepub fn any_readable(
&self,
paths: impl IntoIterator<Item = Result<AttributePath>>,
) -> Result<bool>
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.
Sourcepub 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)>
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.
Sourcepub 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)>
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.
Sourcepub 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)>
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>
impl<A: AccessControl, H: ClusterHandler> Server<'_, A, H>
Sourcepub fn serve_write_path(
&self,
data: &AttributeData<'_>,
ctx: &InteractionContext<'_>,
action: &mut WriteAction,
w: &mut TlvWriter<'_>,
responses: &mut usize,
) -> Result<bool>
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
Tquality needs a Timed transaction (NEEDS_TIMED_INTERACTION); - step b.v: a fabric-scoped attribute needs an accessing fabric
(
UNSUPPORTED_ACCESS); - step b.vi: a
DataVersionthat 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.
Sourcepub 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)>
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>
impl<A: AccessControl, H: ClusterHandler> Server<'_, A, H>
Sourcepub fn serve_invoke_command(
&self,
command: &CommandData<'_>,
ctx: &InteractionContext<'_>,
w: &mut TlvWriter<'_>,
responses: &mut usize,
scratch: &mut [u8],
) -> Result<bool>
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.
Sourcepub 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)>
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>
impl<A: AccessControl, H: ClusterHandler> Server<'_, A, H>
Sourcepub 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)>
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.
Sourcepub 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)>
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.
Sourcepub 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)>
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.