feat(subscribe): add sourcePolicy and excludeSources to subscribe message#679
Open
dirkwa wants to merge 1 commit into
Open
feat(subscribe): add sourcePolicy and excludeSources to subscribe message#679dirkwa wants to merge 1 commit into
dirkwa wants to merge 1 commit into
Conversation
…sage
The subscribe schema was silent on how a client controls source
selection when a path has multiple producers, leaving the
implementations that do support it without spec coverage.
Adds two top-level fields to SubscribeMessage:
- sourcePolicy ("preferred" | "all", default "preferred") — selects
whether the subscription receives a single priority-resolved value
per path or every source unranked.
- excludeSources (array of $source refs) — drops the listed sources
from the priority cascade's candidate set, so a derived-data plugin
that publishes on the same path it consumes can apply the user's
source ranking across the upstream sources without seeing its own
output.
Updates the Subscription Protocol doc with a Source selection section
covering both fields and the canonical excludeSources use case, and
notes the matching ?sourcePolicy=... query parameter in the Streaming
API doc.
Plugin-API implementations MAY offer a plugin-only shorthand for
self-exclusion (the Node server exposes excludeSelf:true). The
shorthand is plugin-API only; WebSocket and TCP clients use the
explicit excludeSources form, so it is described in prose without a
schema field.
Follows up signalk-server#2688.
Closes SignalK#678.
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.
Motivation
Closes #678 — follow-up to SignalK/signalk-server#2688.
The subscribe schema is silent on how a client controls source selection when a path has multiple producers. Server implementations (and the Node server specifically, as of #2688) support it; the spec needs to catch up so other clients and servers can interop on a documented contract.
The concrete gap: a derived-data plugin that publishes on the same path it consumes cannot benefit from source priority today. Under
sourcePolicy: 'preferred'it would see its own output and feed back on itself; under'all'it loses the user's priority cascade across the upstream sources.What this PR adds
Two top-level fields on
SubscribeMessage:sourcePolicy("preferred"|"all", default"preferred") — selects whether each subscribed path delivers a single priority-resolved value or every source unranked. Applies to every row in the message and to the bootstrap snapshot the server replays on subscribe.excludeSources(array of$sourcerefs) — drops the listed sources from the priority cascade's candidate set. The subscription still delivers a single priority-resolved value per path; the cascade just runs without the excluded sources, with the configured fallback timeouts honoured. Effective only undersourcePolicy: 'preferred'; ignored under'all'.The canonical use case for
excludeSourcesis the derived-data plugin: with user rankingmyPlugin > sourceB > sourceA, a subscription withexcludeSources: ["myPlugin"]receivessourceBwhile it publishes, falls back tosourceApastsourceB's timeout, returns tosourceBwhen it resumes, and never seesmyPlugineven though it ranks highest.What this PR does not add
excludeSelfis a plugin-API shorthand only — the server resolves it to the plugin's id, which has no analogue on a WebSocket/TCP wire. The Node server exposes it on its in-process subscribe API; documentation calls it out as plugin-API-only and points wire clients atexcludeSources. It is not added to the schema (would be misleading on the wire) and not added as a query parameter (same reason).Changes
schemas/messages/subscribe.json—sourcePolicy(string + enum) andexcludeSources(array of strings) added as top-level optional properties.mdbook/src/subscription_protocol.md— new "Source selection" section with both fields, the cascade-fallback example and the plugin-shorthand note.mdbook/src/streaming_api.md— short note that servers MAY accept?sourcePolicy=...as a connection default.samples/subscribe/docs-subscription_protocol-excludeSources.json— the example referenced from the new prose, validated by the subscribe sample tests.test/data/subscribe-valid/— three new valid samples (preferred, all, excludeSources).test/data/subscribe-invalid/— one new invalid sample (sourcePolicy: "bogus") to lock in the enum.Tested
npm test— 212 passing (was 207). The five new samples are picked up by the existing valid/invalid harnesses; the negative case confirms tv4 enforces thesourcePolicyenum.node -e 'JSON.parse(...)'smoke check onsubscribe.json.