OBSERVE registration failures are invisible to the caller

[mbillow]

A consumer that subscribes to many hrefs on one session needs to tell "this registration never took" from "this resource just hasn't changed yet". Right now it can't: subscribe() returns as soon as the register CON is written, and the only per-href signal that ever reaches the caller is on_notification. Both of the wire-level signals that would answer the question are dropped inside _dispatch_coap.

1. A non-2.05 on an observe token is logged and swallowed

dtls_session.py:697

if code != 0x45:
    logger.warning("observe %s: non-2.05 %s", href, fmt_code(code))
    return

That's a definitive "this registration failed", and it's the strongest
evidence available anywhere in the stack — but it goes to the log and
never to the caller, so acting on it means scraping log lines.

2. The Observe option is never read from a response

Option 6 is only ever written — register at dtls_session.py:1100,
deregister at :465. Nothing inspects it on the way back in; the
notification path reads only BLOCK2 out of ropts.

Two consequences:

• A declined registration is indistinguishable from a successful one.
  RFC 7641 §4.1: a server that does not add the client to its observer
  list still answers the GET, just without the Observe option. Since any
  2.05 on that token is treated as a notification, the caller records the
  href as push-covered and stops polling something that will never push
  again. This is the dangerous direction — it fails toward stale data.
• The initial registration response can't be told from a state change.
  The option's value is a sequence number (§3.4). Without it, "this href
  notified" means "it said something once", not "it pushes changes" —
  and every healthy href says something once, at registration. A caller
  wanting the stronger property has no way to compute it.

Why silence isn't a workable substitute

Inferring from "never notified" conflates at least three causes:

• registration refused or errored (cases 1 and 2 above),
• the register CON was lost — subscribe() is fire-and-forget and has no
  retransmit (unlike _blockwise_get's _BLOCK_MAX_ATTEMPTS), so a
  dropped datagram means no response ever arrives,
• a large resource whose initial representation is legitimately deferred:
  _dispatch_coap withholds any notification with Block2 M=1 or NUM>0 and
  hands it to the refetch worker, which is serialized, paced at 5 req/s
  and bounded by _REFETCH_TIMEOUT_S = 15.0.

Only the third recovers on its own, and the caller can't tell which it is.

Suggested shape

Matching the existing self.on_notification = on_notification # fn(href, payload_bytes)
attribute at :251:

• on_observe_error = None # fn(href, code) — invoked where the bare
  warning is today.
• Something that surfaces registration acceptance and the sequence number.
  Either an extra argument on the notification callback or a separate
  on_observe_registered(href, accepted: bool); the useful part is
  distinguishing "2.05 with no Observe option" and exposing the seq, so
  the exact shape is yours to pick.

Both default to None, so current behavior is unchanged for existing
callers.

Happy to send a PR if the direction looks right.

[QuiteYellow]

Every line reference here is accurate against main at 0722c55, including the part that is easy to get wrong: on the notification branch the only thing that touches ropts is the Block2 check, so option 6 really is write-only in this codebase. Thanks for tracing it properly rather than filing the symptom.

Direction is yes. Send the PR.

One thing to add, because it strengthens your case in a way you would have no reason to know about. Your point 2 is the fix for #41, which I filed on 15 August. Push Active in the demo bridge reports that an appliance is pushing when it has no route to Samsung's cloud and is emitting nothing at all. The cause is the one you describe: the registration response arrives on the observe token, gets dispatched as a notification, and sets the same "something pushed recently" timestamp a real notification would. At session start the cache is empty, so every registration response counts as a change. Reading option 6 is the discriminator that closes it. So this is not only an API gap on your side, it retires a bug on mine.

Shape

For the shape, I’m thinking:

self.on_observe_error = None       # fn(href, code)
self.on_observe_registered = None  # fn(href, accepted, seq)

Both default None, both alongside on_notification at :251. accepted is whether option 6 was present on the response, per RFC 7641 §4.1. seq is its value or None, per §3.4.

Two callbacks rather than an extra argument on on_notification, because widening that callback's signature breaks every existing handler. mqtt_demo's is _on_notification(self, href, payload_bytes) at bridge.py:199 and LocalThings' is on_notification(self, href, payload) at observe.py:203. Both take two parameters, so a third one turns every notification into a TypeError at the call site. I would rather not spend a breaking change on this.

One call I would like you to keep: the registration 2.05 should still reach on_notification. Withholding it is the tidier design and I considered asking for it, but cache seeding depends on that first payload on both sides, so suppressing it breaks working consumers for a correctness gain they can get anyway. Fire the new callback alongside it and let the caller decide what to do. On my side #41 becomes "ignore the ones where on_observe_registered already fired".

Sequencing

Your #54 and Jason's #51 are ahead of this and both touch the send path. I would rather land those and cut a release before this goes in, partly so LocalThings gets the pacing fix it is waiting on, partly so you are not rebasing this across two merges.

One thing that removes an overlap you might otherwise hit: #51 already closes #53. Jason put pace() and a liveness recheck at the top of subscribe(), with a test that walks an eleven-href registration burst and asserts ten waits at the rate-limit interval. So by the time you branch, subscribe() will already be paced and the register CON will no longer go straight to _send_dgram. Rebase onto it before you start, since your callbacks land next to that code.

Your third bullet is right and I would keep it out of this PR. subscribe() being fire-and-forget with no retransmit, where _blockwise_get has _BLOCK_MAX_ATTEMPTS, is #54's shape applied to the register CON. It should be its own change, once #54 has settled and its retransmit path has a default.