Adopt core 0.5.0: declared verb scope + keepalive instance state - #9
Merged
Conversation
Bump the edgecommons pin to python-lib/v0.5.0 and migrate the command surface to the breaking scoped-command model (D-SC-1..6): - All nine verbs (sb/read, sb/write, sb/status, sb/signals, sb/browse, sb/pause, sb/resume, reconnect, repoll) register through register(verb, CommandScope.INSTANCE, handler) with handlers taking (request, addressed_instance). register_scoped is gone from the library. - routing.resolve_instance sheds the topic/body/conflict logic the library now owns and keeps only what needs configuration knowledge (D-SC-4): the optional-iff-one configured default and NO_SUCH_INSTANCE. No handler reads body["instance"] any more. Populate the state keepalive's instances[] with the instance state (D-SC-7), reversing D-M3's deviation: a new single state model (instance_state.device_state) decides ONLINE / PAUSED / BACKOFF / CONNECTING and feeds both surfaces - the keepalive element via with_state and sb/status's new state field - so a pushed keepalive and a pulled status cannot disagree, and a deliberately paused slave is distinguishable from a stale one. Docs and the decision register move with the code: the messaging-interface reference gains a scope column, the resolution-order addressing rules, the state token on the keepalive and sb/status; DESIGN.md gains D-M9 and marks D-M8 superseded; AGENTS.md replaces the instance-routing invariant with the declared-scope and single-state-model invariants.
Match the fleet-wide rule the OPC UA and EtherNet/IP adapters and the scaffold templates already follow: an instance whose link is down reports BACKOFF - CONNECTING before its first connect - whether or not sb/pause is latched, and PAUSED is reported only while the link is up. The pause itself stays visible on sb/status's paused field, so neither fact is hidden. device_state flips its precedence accordingly, with the rule stated in the module docs, the sb/status docstring, the messaging-interface reference, the D-M9 register entry, and the AGENTS invariant. A new test pins a break while paused as BACKOFF with paused still true.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adopts the breaking core 0.5.0 scoped-command model and the companion keepalive-instance-state item, one wave (D-SC-1..9).
Pin
edgecommonsmoves topython-lib/v0.5.0(release commita14a328) inrequirements.txtandpyproject.toml.Declared verb scope (D-SC-1..6)
sb/read,sb/write,sb/status,sb/signals,sb/browse,sb/pause,sb/resume,reconnect,repoll— register ascommands.register(verb, CommandScope.INSTANCE, handler); every handler ishandler(request, addressed_instance).register_scopedno longer exists.instanceextraction, the conflict-firstBAD_ARGS, andCOMPONENT-scope rejection, all before dispatch.routing.resolve_instancedrops its topic-authority logic and itsbodyparameter, keeping only the two policies that need configuration knowledge (D-SC-4): the optional-iff-one configured default andNO_SUCH_INSTANCE. No handler readsbody["instance"].describeadditionally advertises each verb'sscope.Keepalive instance state (D-SC-7)
modbus_adapter/instance_state.pyholds the single state model:device_state(paused, connected)→ONLINE/PAUSED/BACKOFF, plusCONNECTINGfor a configured instance whose device has not come up yet.statekeepalive'sinstances[](viaInstanceConnectivity.with_state) andsb/status's newstatefield — so a pushed keepalive and a pulled status cannot disagree.PAUSEDis reported only while the link is up, so a paused instance whose link is down readsBACKOFF(CONNECTINGbefore its first connect), with the pause still visible insb/status'spausedfield. Additive on the wire.Docs and register
docs/reference/messaging-interface.mdgains the verb Scope column, the resolution-order addressing rules,stateonsb/statusand on the keepalive element;explanation.md,how-to-guides.md, andsample-configurations.mdfollow.DESIGN.mdadds D-M9 and marks D-M8 superseded;AGENTS.mdreplaces the instance-routing invariant with the declared-scope and single-state-model invariants.Validation
python -m pytest(the repo's 90% gate ridesaddopts): 144 passed, coverage 95.80% — against a local checkout of core atpython-lib/v0.5.0. Baseline before the change: 141 passed, 95.74%.