feat(data): add optional notify block to the campaign schema - #1841
Open
martien-wdy wants to merge 1 commit into
Open
feat(data): add optional notify block to the campaign schema#1841martien-wdy wants to merge 1 commit into
martien-wdy wants to merge 1 commit into
Conversation
Campaign version 1 gains an optional notify block:
notify:
on: episode_committed
The block is device-inert. It is validated at deploy time (episode_committed
is the only supported event, rejected with ErrUnsupportedNotifyOn otherwise),
stored with the plan, hashed into the campaign revision, and copied verbatim
onto the episode trigger so it rides in the committed manifest JSON at
trigger.notify. The cloud ingest service, which receives that JSON as
attributes_json, decides whether to notify; the device never opens a network
connection because of the block.
Unknown keys inside notify warn at deployment instead of failing it, unlike
the rest of the document: the cloud side may understand keys an older agent
does not, and a newer plan must not brick deployment to an older device.
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
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.
Problem
Fleet operators want to be notified when a campaign episode is committed, but the campaign schema has no way for a plan author to declare that intent. Any notification mechanism must not add device-side network behavior: devices already upload the committed manifest, and the cloud is the right place to act.
Context
The device manifest does not carry the campaign plan wholesale; it carries only
trigger.campaign_nameandtrigger.campaign_revisionthroughEpisodeTrigger. The uploader (buildEpisodeManifestingo/internal/agent/services/data_transfer_worker.go) marshals the full device manifest into the cloudEpisodeManifest.attributes_json, so anything on the manifest reaches the cloud verbatim, but a new plan block does not ride along on its own. It needs one field of plumbing from the plan onto the trigger.Solution
Campaign version 1 gains an optional
notify:block:go/internal/agent/data/campaign.go):CampaignNotifyfollows the same declaration pattern as the existingupload:andexport:blocks.episode_committedis the only supported value foron:; anything else is rejected at deploy-time validation with the named sentinel errorErrUnsupportedNotifyOn, identifiable witherrors.Is.notify:warn at deployment instead of failing it. The rest of the document rejects unknown fields via the YAML decoder's known-fields check, but this block is read by the cloud rather than the device, so a newer cloud-side key must not brick deployment to an older device. A customUnmarshalYAMLcollects the unknown keys andDeployCampaignappends a warning naming each one.go/internal/agent/data/model.go,go/internal/agent/services/data_service.go): the block is copied verbatim from the plan ontoEpisodeTrigger.Notifywhen a campaign triggers, and the trigger flows unchanged into the committed manifest. The cloud reads it atattributes_json->trigger->notify->{"on": "episode_committed"}.omitemptyon a nil pointer).docs/clients/wendy-cli/commands/data.mddocuments the block, and the annotatedExamples/WendyDataCampaign/campaign.yamlshows it with a comment.Tests
New unit tests in
go/internal/agent/data/campaign_notify_test.gocover: the block round-tripping into the manifest JSON attrigger.notify.on(and staying absent when the plan has no notify block), rejection of unsupportedon:values viaerrors.Is(err, ErrUnsupportedNotifyOn), the deploy-time warning naming unknown keys, durable storage with the plan, and the revision hash changing when notify is added.Verified with
CC=/usr/bin/clang go build ./go/...,go test ./go/internal/agent/data/... ./go/internal/agent/services/...(all passing),gofmtandgo vetclean on the changed packages.