Skip to content

feat(notification-channel): let plugins provide notification destinations - #59

Open
Quick104 wants to merge 4 commits into
mainfrom
feat/notification-channel
Open

Quick104 wants to merge 4 commits into
mainfrom
feat/notification-channel

Conversation

@Quick104

@Quick104 Quick104 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Problem

A plugin that sends notifications to a service such as Pushover or ntfy subscribes to
notification.created and rebuilds what the host already does for webhooks: per-profile
preferences, a delivery queue, retries, deduplication, failure counts and auto-disable. Only the
host's built-in channels get that.

Approach

A new notification_channel.v1 capability. The plugin declares a kind of destination and its
settings form (NotificationChannelDescriptor, capability descriptor field 13), checks a
destination's settings (ValidateDestination), and sends one rendered message
(SendNotification). Its answer tells the host whether the message was delivered, should be
retried, failed, or whether the destination's settings stopped working. The host keeps
preferences, the queue, retries and auto-disable.

runtime.WithNotificationChannel registers the service, and ServeManifest refuses to start a
plugin that declares the capability without it. examples/hello-notification-channel posts to an
ntfy topic, and docs/notification-channel.md covers the contract and the host's retry window.

The settings form is a flat list of scalar fields: one object of string, integer, number or
boolean properties, with no $ref, combinators, conditionals, nested objects or arrays. People who
aren't administrators fill it in on every client, and loosening the rule later is additive, while
tightening it would break published plugins. manifest.ValidateDestinationSchema enforces it, and
hosts call the same function when they accept the capability.

The docs spell out three host behaviors a plugin depends on: retry_after_seconds sets a minimum
wait and never shortens the retry schedule; ValidateDestination has 10 seconds; and
DESTINATION_INVALID disables the destination on the first answer, so a plugin returns it only for
a definite refusal from the service, never for a proxy 401, a timeout or a 5xx.

Compatibility and release

Merge after #57: details is described as the events package's Notification type, which #57
adds.

Additive. A plugin that declares this capability needs a Silo server that includes
Silo-Server/silo-server#2502: an older server refuses to install it from a bare binary and won't
start it from an archive, because it doesn't know the descriptor field. A server without the host
side of this capability doesn't offer its destinations.

Related changes

Validation

  • go test ./..., go vet ./... and every example build: pass.
  • gofmt -l . lists only pkg/pluginsdk/runtime/scan_source_test.go, which is unformatted on main
    and not touched here.
  • Regenerating the protobuf code with the repo's buf leaves it unchanged. make proto itself stops
    at its protoc check on this machine, though generation doesn't use protoc.
  • The example plugin ran against silo-server on a test server and on shared dev, with a real ntfy
    server: settings refusal with the plugin's message, test message, a real notification delivered
    through the host's queue, a retry after the server was unreachable, and auto-disable when the
    service refused the token.

Evidence

Evidence: https://evidence.siloserver.org/r/silo-plugin-sdk/pr-59/

AI Disclosure

  • Harness: Claude Code, run from T3 Code
  • Tool(s): Claude Code (implementation); Codex CLI (independent review)
  • Model(s): claude-opus-5-5 (implementation); gpt-6.1-sol (review)
  • Involvement: Fully AI-generated, human verified
  • Adversarial review: the same Codex (gpt-6.1-sol) review, checking the send outcomes against the
    host's retry handling. It found the docs' retry window didn't match the host's schedule; fixed.

🤖 Generated with Claude Code

Note

Add notification_channel.v1 capability for plugin-provided notification destinations

  • Adds a new notification_channel.v1 capability type with a protobuf NotificationChannel service (ValidateDestination and SendNotification RPCs) in notification_channel.proto, plus a NotificationChannelDescriptor on CapabilityDescriptor (field 13)
  • Plugins register a server via the new WithNotificationChannel ServeManifest option in serve_manifest.go; manifestServeConfig errors when a manifest declares the capability without a non-nil server. runtime.Client.NotificationChannel exposes a client on the host side
  • Adds manifest validation in notification_channel.go: path-safe lowercase slug ID, non-blank display name, and a flat destination schema restricted to supported scalar fields and keywords
  • Includes a full ntfy example in hello-notification-channel that posts notifications with outcome mapping (delivered, destination-invalid, retry with Retry-After support, failed), and docs in notification-channel.md
  • Risk: manifest.Validate now rejects destination schemas with nested objects, arrays, references, or conditionals — existing manifests that previously passed with such schemas will fail validation

Macroscope summarized 36624d4.

@coderabbitai

coderabbitai Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

  • Ask an admin to enable usage-based reviews

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available. Your 82 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 3dded209-e414-4623-8c79-08ac0aa657f7
Commits

Reviewing files that changed from the base of the PR and between 5717267 and 36624d4.

Files ignored due to path filters: 3

  • pkg/pluginproto/silo/plugin/v1/common.pb.go is excluded by !**/*.pb.go
  • pkg/pluginproto/silo/plugin/v1/notification_channel.pb.go is excluded by !**/*.pb.go
  • pkg/pluginproto/silo/plugin/v1/notification_channel_grpc.pb.go is excluded by !**/*.pb.go
Files selected for processing: 18

  • CONTRIBUTING.md
  • README.md
  • docs/notification-channel.md
  • examples/hello-notification-channel/README.md
  • examples/hello-notification-channel/main.go
  • examples/hello-notification-channel/manifest.json
  • pkg/pluginsdk/capability/capability.go
  • pkg/pluginsdk/convert/convert.go
  • pkg/pluginsdk/convert/notification_channel_test.go
  • pkg/pluginsdk/manifest/destination_schema.go
  • pkg/pluginsdk/manifest/manifest.go
  • pkg/pluginsdk/manifest/notification_channel.go
  • pkg/pluginsdk/manifest/notification_channel_test.go
  • pkg/pluginsdk/runtime/notification_channel_test.go
  • pkg/pluginsdk/runtime/runtime.go
  • pkg/pluginsdk/runtime/serve_manifest.go
  • proto/silo/plugin/v1/common.proto
  • proto/silo/plugin/v1/notification_channel.proto
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@silo-triage silo-triage Bot added the size/XXL 1000–2999 added + deleted lines (all files); change volume, not priority. label Nov 5, 2026
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-18T15:59:32.854089Z 36624d4 New commits
🔒 Security Review ✅ Completed 2026-11-18T16:02:11.447766Z 36624d4 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@silo-kody

silo-kody Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

Comment thread pkg/pluginsdk/convert/convert.go Resolved
Comment thread pkg/pluginsdk/runtime/runtime.go Resolved
}

// NotificationChannel returns the client for notification_channel.v1
// destinations. Plugins that don't serve it answer Unimplemented.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Kody Rules low

NotificationChannel API comment omits its first SDK release

Without a release version, users cannot tell when NotificationChannel became available. Add its first SDK release to the API comment after verifying it against the published tags.

Kody rule violation: Identify the actual first SDK release containing new Go APIs

Prompt for LLM
File pkg/pluginsdk/runtime/runtime.go, line 193:

NotificationChannel API comment omits its first SDK release

Name the first SDK release that contains NotificationChannel in this API comment. Verify the release against the published tags rather than assuming the version of an earlier service.

Kody rule violation: [Identify the actual first SDK release containing new Go APIs](https://kodus.siloserver.org/settings/code-review/1247142454/kody-rules/3b921753-4a22-4967-8ee8-ac53eb6569d4?teamId=ba9922fc-c0ea-4cf8-87bb-9d4f42ffc73e)

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

@silo-kody

silo-kody Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

1 similar comment
@silo-kody

silo-kody Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

Comment on lines +65 to +70
if raw, ok := root["additionalProperties"]; ok {
var allowed bool
if err := json.Unmarshal(raw, &allowed); err != nil {
return fmt.Errorf("destination_schema additionalProperties must be a boolean")
}
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Bug medium

Additional properties bypass the flat scalar destination restriction

Undeclared properties can contain nested objects or arrays, violating the flat scalar contract. Require additionalProperties: false or enforce the same restriction when validating destination values.

Prompt for LLM
File pkg/pluginsdk/manifest/destination_schema.go, lines 65-70:

Additional properties bypass the flat scalar destination restriction

Schemas with `additionalProperties: true` or no `additionalProperties` allow undeclared values of any type, including nested objects and arrays, so accepted destination configurations do not obey the promised flat scalar contract. Require `additionalProperties: false` or enforce the equivalent restriction when validating destination values.

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

destinationFieldTypes = []string{"string", "integer", "number", "boolean"}
)

// ValidateDestinationSchema checks a notification_channel destination_schema:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Kody Rules low

ValidateDestinationSchema does not identify its first SDK release

Consumers may not know which SDK version includes ValidateDestinationSchema. Add its first release to the API comment, verified against the published tags.

Kody rule violation: Identify the actual first SDK release containing new Go APIs

Prompt for LLM
File pkg/pluginsdk/manifest/destination_schema.go, line 21:

ValidateDestinationSchema does not identify its first SDK release

Add the first SDK release containing `ValidateDestinationSchema` to its API comment. Verify the release against the published tags so consumers are not directed to a version that lacks this function.

Kody rule violation: [Identify the actual first SDK release containing new Go APIs](https://kodus.siloserver.org/settings/code-review/1247142454/kody-rules/3b921753-4a22-4967-8ee8-ac53eb6569d4?teamId=ba9922fc-c0ea-4cf8-87bb-9d4f42ffc73e)

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

Quick104 and others added 4 commits November 18, 2026 15:55
…ions

Add the notification_channel.v1 capability. A plugin declares a kind of
destination and its settings form, checks a destination's settings
(ValidateDestination), and sends one rendered message (SendNotification).
The host keeps preferences, the delivery queue, retries, failure counts
and auto-disable, so a Pushover or ntfy plugin no longer rebuilds them on
top of notification.created.

Register the service with runtime.WithNotificationChannel; ServeManifest
refuses to start a plugin that declares the capability without it. The
descriptor round-trips through capability records, and
examples/hello-notification-channel posts to an ntfy topic.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…eep ntfy's retry wait

ValidateDestination accepted a relative server URL such as /ntfy, which
the HTTP client can't post to. It now requires an absolute http or https
URL with a host.

A Retry-After above one hour was cut to an hour, so the host could retry
before ntfy asked. The example now passes the wait through and leaves
the cap to the host.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… fields

manifest.ValidateDestinationSchema accepts one object of string, integer,
number and boolean fields and refuses $ref, combinators, conditionals,
nested objects and arrays. Destination forms are filled in by people who
aren't administrators on every client, and loosening the rule later is
additive while tightening it would break plugins. Hosts call the same
function when they accept the capability.

The docs now say retry_after_seconds is a minimum wait, give the
10-second ValidateDestination timeout, and limit DESTINATION_INVALID to a
definite refusal from the service.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Quick104
Quick104 force-pushed the feat/notification-channel branch from 68d0a07 to 36624d4 Compare November 18, 2026 15:57

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 36624d4648

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +124 to +125
case resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden:
return outcome(pluginv1.NotificationSendOutcome_NOTIFICATION_SEND_OUTCOME_DESTINATION_INVALID, "ntfy refused the access token for this topic."), nil

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Verify ntfy rejected credentials before disabling the destination

When an administrator's ntfy server sits behind a proxy or CDN that returns a 401 or 403, this branch reports DESTINATION_INVALID without checking whether ntfy actually rejected the destination's credentials. That outcome immediately disables the destination and drops the message, so a proxy-side failure can disable otherwise valid destinations instead of being retried. This contradicts the explicit proxy-401 guidance in docs/notification-channel.md. Inspect the service's error response before classifying credentials as invalid, and return RETRY for unverified intermediary refusals rather than discarding the response body first.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request go Pull requests that update go code size/XXL 1000–2999 added + deleted lines (all files); change volume, not priority. triaged High-confidence review completed; does not mean fixed, validated, or accepted for release.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant