Operations and outcomes

Every read, write and action on a Nodelet is an operation. Nodelets sends each operation to the device once, never resends it, and reports what it knows about the result without guessing.

Why once

A write or an action changes something in the world. If a command is resent after a timeout, and the first one had in fact reached the device, the device acts twice. For a setpoint that may be harmless. For an action such as dispensing, opening or resetting, it may not be. Nodelets leaves the decision to repeat with the caller, who knows what the command does.

What the outcomes say

A failed operation carries an outcome when Nodelets can say something about the device:

not-executed: the device did not act. The bridge could not reach it, it refused with an HTTP error, the cloud refused the call before sending it, or a read ran out of time. Trying again is safe.
unknown: the command may have reached the device, but nothing confirmed it. A connection dropped after the request went out, or no reply arrived before the deadline. The device may have acted, may act later, or may not act at all.

Success is only reported when something confirms it. For HTTP that is a 2xx status from the device. For MQTT it is a later message on the confirmation topic that carries the written value. A message retained by the broker, or one received before the command was published, never counts.

An unknown outcome is not a failure in disguise. Some systems queue a command for a device that is out of reach and run it when the device returns, so a command reported as unknown can take effect minutes later.

Reads are different

A read changes nothing, so a read that runs out of time is TIMEOUT and a dropped connection during a read is BRIDGE_UNAVAILABLE, not unknown. A read is always fresh: the value comes from the device for that request, and nothing is cached.

Where the guarantee holds

The bridge sends each command once. Above the bridge the picture is less complete:

A client that sends the same request again, after losing the reply, sends a new operation. Nodelets has no way to know the two were meant as one.
Some failures inside the cloud can return no outcome.
When a command’s deadline passes, the router reports unknown and asks the bridge to cancel the request. The device may already have acted.

The record keeps the same honesty

Each write and action sent through the cloud is entered on the device’s record with who sent it and what happened. A result there is a report, and the record says whose: “Done, as the bridge reported”. When no result reached the cloud, the entry reads unknown, never failed. See Permissions and records.